fetchStakerCustodiedSbtc

Reads the sBTC, in sats, that pox-5 holds for a staker's protocol bond. Wraps the pox-5 read-only get-staker-custodied-sbtc, which reads the protocol-bond-memberships map.

---

Usage

import { fetchStakerCustodiedSbtc } from '@stacks/bitcoin-staking';

async function custodied(staker: string) {
  return fetchStakerCustodiedSbtc({ staker, network: 'mainnet' }); // sats of sBTC, as a bigint
}

Notes

• Returns the bond membership's amount-sats, or 0n when the bond is an L1 lock or the staker has no membership (get-staker-custodied-sbtc).

• It reads the map entry without the expiry check that get-bond-membership applies (get-bond-membership), so it still reports the sBTC after the bond's term ends. fetchProtocolBondMemberships reads the same entry.

• unstake-sbtc reverts with ERR_INVALID_UNSTAKE_SBTC_AMOUNT (u37) when asked for more than this amount (unstake-sbtc). Read it before buildUnstakeSbtc.

• A non-2xx response throws an Error whose message starts with Error calling read-only function. and includes the status code and URL. If the node reports that the call failed, the Error message is the node's cause.

Reference Link

---

Signature

function fetchStakerCustodiedSbtc(
  opts: { staker: string } & NetworkClientParam
): Promise<bigint>;

opts is a NetworkClientParam plus staker.

---

Returns

Promise<bigint>

Resolves to an amount of sBTC in sats.

---

Parameters

opts.staker (required)

• Type: string

Stacks address of the staker.

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.