fetchBondMembership

Calls the pox-5 get-bond-membership read-only and returns the staker's protocol bond membership, or undefined if the staker has no membership or its bond has ended.

---

Usage

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

const membership = await fetchBondMembership({
  address: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
  network: 'mainnet',
});

if (membership) {
  membership.bondIndex;
  membership.amountSats; // sats, as a bigint
  membership.isL1Lock; // true for a Bitcoin L1 lockup, false for sBTC
}

Notes

• Reads the protocol-bond-memberships map through get-bond-membership. The contract returns none when no entry exists, and also once the current reward cycle reaches the bond's first reward cycle plus 12 (BOND_LENGTH_CYCLES). Both cases resolve to undefined.

• A membership for a bond that has not started yet is returned.

• To read the entry after the bond ends, use fetchProtocolBondMemberships, which reads the map directly. unstake-sbtc also reads the map directly (L1267-L1269), without this expiry filter.

• After announce-l1-early-exit, the entry is still returned with amountSats set to 0n (L1235-L1237).

• 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 fetchBondMembership(
  opts: { address: string } & NetworkClientParam
): Promise<BondMembership | undefined>;

opts is a NetworkClientParam plus address.

---

Returns

Promise<BondMembership | undefined>

Resolves to a BondMembership, or undefined when the contract returns none.

---

Parameters

opts.address (required)

• Type: string

Stacks address of the staker. A contract principal (<address>.<contract-name>) is also accepted.

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.