fetchTotalUstxStacked

Calls the pox-5 get-total-ustx-stacked read-only and returns the micro-STX delegated in a reward cycle, from protocol bonds and STX-only staking combined.

---

Usage

import { fetchPoxInfo, fetchTotalUstxStacked } from '@stacks/bitcoin-staking';

const { rewardCycleId } = await fetchPoxInfo({ network: 'mainnet' });

const totalUstx = await fetchTotalUstxStacked({ rewardCycle: rewardCycleId, network: 'mainnet' }); // micro-STX, as a bigint

Notes

• get-total-ustx-stacked returns get-ustx-delegated-for-cycle, which reads the ustx-delegated-per-cycle map. Returns 0n when there is no entry. fetchUstxDelegatedForCycle reads the same value.

• The total includes every staker added to a signer-manager for the cycle, whether or not that signer-manager reached the signer set minimum (L1769-L1772). For the micro-STX that STX-only staking rewards are divided by, use fetchTotalSharesStakedForCycle.

• Throws an Error if the node returns a non-2xx status (the message starts with Error calling read-only function.) or answers okay: false (the message is the node's cause).

Reference Link

---

Signature

function fetchTotalUstxStacked(
  opts: { rewardCycle: number } & NetworkClientParam
): Promise<bigint>;

opts is a NetworkClientParam plus rewardCycle.

---

Returns

Promise<bigint>

Total micro-STX delegated for the cycle.

---

Parameters

opts.rewardCycle (required)

• Type: number

Reward cycle to read.

opts.network (optional)

• Type: StacksNetworkName | StacksNetwork

The network to query: a name such as 'mainnet' or 'testnet', or a StacksNetwork object. Defaults to 'mainnet'.

opts.client (optional)

• Type: { baseUrl?: string; fetch?: FetchFn }

Overrides the API base URL or the fetch function, for example to query your own node. Fields you set replace the network's defaults.