fetchProtocolBondMemberships

Reads a staker's entry in the pox-5 protocol-bond-memberships map directly, including an entry whose bond has ended.

---

Usage

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

const entry = await fetchProtocolBondMemberships({
  address: 'SP2J6ZY48GV1EZ5V2V5RB9MP66SW86PYKKNRV9EJ7',
  network: 'mainnet',
});

if (entry) {
  entry.bondIndex;
  entry.amountSats; // sats, as a bigint
}

Notes

• Reads the protocol-bond-memberships map through the node's /v2/map_entry endpoint, with no expiry filter. This is the same read unstake-sbtc makes (L1267-L1269).
• fetchBondMembership goes through get-bond-membership instead, which returns none once the bond's 12 reward cycles have passed.
• The entry stays after the bond ends. A later register-for-bond overwrites it, and a stake that rolls the bond into STX-only staking deletes it (L1071).
• A non-2xx response, or a response without data, throws an Error whose message starts with Error fetching map entry for map "protocol-bond-memberships".

Reference Link

---

Signature

function fetchProtocolBondMemberships(
  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 map has no entry for the address.

---

Parameters

opts.address (required)

• Type: string

Stacks address of the staker, the map key. 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.