Staking
Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards
A one-call overview of a principal's staking: its pox-5 STX-staking position (locked STX and its sBTC rewards) plus aggregate totals across all of its bond positions. The per-bond breakdown is paginated at /principals/:principal/staking/bonds.
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Default Response
Default Response
GET /extended/v3/principals/{principal}/staking HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"stx": {
"locked": "text",
"rewards": {
"btc": {
"accrued": "text",
"claimed": "text",
"claimable": "text"
}
}
},
"bonds": {
"count": 1,
"locked": {
"btc": "text",
"stx": "text"
},
"rewards": {
"btc": {
"accrued": "text",
"claimed": "text",
"claimable": "text"
}
}
}
}Get a principal's bond positions — its enrollment, lock, status, and sBTC rewards in each bond it participates in.
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Number of results per page
20Cursor for paginating bonds. Format: bond_index
^\d+$Default Response
1Number of results per page
20Default Response
GET /extended/v3/principals/{principal}/staking/bonds HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 20,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"bond_index": 1,
"status": "enrolled",
"active": true,
"enrollment": {
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
"btc_lockup": {
"amount": "text"
}
},
"locked": {
"btc": "text",
"stx": "text"
},
"rewards": {
"btc": {
"accrued": "text",
"claimed": "text",
"claimable": "text"
}
}
}
]
}Get bonds
Number of results per page
20Cursor for paginating bonds. Format: bond_index
^\d+$Default Response
1Number of results per page
20Default Response
GET /extended/v3/staking/bonds HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 20,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"index": 1,
"pox_version": "pox5",
"status": "upcoming",
"parameters": {
"target_rate_bps": 1,
"stx_value_ratio": 1,
"minimum_stx_ratio": 1,
"btc_capacity": "text"
},
"registrations": {
"allowed_count": 1,
"registered_count": 1
},
"schedule": {
"enrollment_cutoff": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"activation": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"unlock": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
}
},
"balances": {
"locked": {
"btc": "text",
"stx": "text"
},
"rewards": {
"btc": {
"distributed": "text",
"accrued": "text",
"claimed": "text"
}
},
"paid_out": {}
}
}
]
}Get a bond. A bond that has not been set up yet but still can be (its activation height is ahead of the chain tip) is returned with a projected status and only the schedule pox-5 will assign it, which follows from its index.
The index of the bond in the PoX-5 bond list
Default Response
Default Response
GET /extended/v3/staking/bonds/{bond_index} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"index": 1,
"pox_version": "pox5",
"status": "upcoming",
"parameters": {
"target_rate_bps": 1,
"stx_value_ratio": 1,
"minimum_stx_ratio": 1,
"btc_capacity": "text"
},
"registrations": {
"allowed_count": 1,
"registered_count": 1
},
"schedule": {
"enrollment_cutoff": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"activation": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"unlock": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
}
},
"balances": {
"locked": {
"btc": "text",
"stx": "text"
},
"rewards": {
"btc": {
"distributed": "text",
"accrued": "text",
"claimed": "text"
}
},
"paid_out": {}
},
"transaction": {
"tx_id": "text",
"block": {
"height": 1,
"hash": "text",
"index_hash": "text",
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"tx_index": 1
},
"bitcoin_block": {
"height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z"
}
}
}A bond's pox-5 event log, newest first: setup, allowlist additions, registrations and registration updates, early exits (announce-l1-early-exit, and unstake-sbtc with a new_amount_sats of 0), partial sBTC unstakes, reward distributions, and staker reward claims.
The index of the bond in the PoX-5 bond list
Number of results per page
20Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index
^[0-9]+:[0-9]+:[0-9]+:[0-9]+$Default Response
1Number of results per page
20Default Response
GET /extended/v3/staking/bonds/{bond_index}/events HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 20,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"name": "setup-bond",
"bond_index": 1,
"transaction": {
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
"event_index": 1
},
"block": {
"height": 1,
"hash": "text",
"index_hash": "text",
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"tx_index": 1
},
"bitcoin_block": {
"height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z"
},
"data": {
"parameters": {
"target_rate_bps": 1,
"stx_value_ratio": 1,
"minimum_stx_ratio": 1
},
"early_unlock_bytes": "text",
"schedule": {
"enrollment_cutoff": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"activation": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"unlock": {
"bitcoin_height": 1,
"pox_cycle": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
}
}
}
}
]
}Get bond allowlist entries
The index of the bond in the PoX-5 bond list
Number of results per page
20Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index
^[0-9]+:[0-9]+:[0-9]+$Default Response
1Number of results per page
20Default Response
GET /extended/v3/staking/bonds/{bond_index}/allowlist HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 20,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"staker": "text",
"max_sats": "text"
}
]
}Get bond allowlist entry
The index of the bond in the PoX-5 bond list
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Default Response
Default Response
GET /extended/v3/staking/bonds/{bond_index}/allowlist/{principal} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"staker": "text",
"max_sats": "text"
}Get bond registrations
The index of the bond in the PoX-5 bond list
Number of results per page
20Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index
^[0-9]+:[0-9]+:[0-9]+$Default Response
1Number of results per page
20Default Response
GET /extended/v3/staking/bonds/{bond_index}/registrations HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 20,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"staker": "text",
"signer": "text",
"type": "l1",
"balances": {
"btc": "1000000",
"stx": "1000000"
}
}
]
}Get bond registration
The index of the bond in the PoX-5 bond list
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Default Response
Default Response
GET /extended/v3/staking/bonds/{bond_index}/registrations/{principal} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"staker": "text",
"signer": "text",
"type": "l1",
"balances": {
"btc": "1000000",
"stx": "1000000"
},
"l1_lockup": {
"transactions": [
{
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
"output_index": 1
}
]
}
}A summary of staking for one PoX reward cycle.
A PoX cycle number (up to nine digits), or one of current (the cycle containing the current Bitcoin tip), previous, or next. The prepare phase at the end of a cycle belongs to that cycle.
{"value":"143"}Pattern: ^([0-9]{1,9}|current|previous|next)$Default Response
The PoX reward cycle number
143Where the cycle stands relative to the current Bitcoin tip.
Default Response
GET /extended/v3/staking/cycles/{cycle_number} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"number": 143,
"status": "upcoming",
"schedule": {
"start": {
"bitcoin_height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"prepare_phase_start": {
"bitcoin_height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
},
"end": {
"bitcoin_height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"projected_time": 1,
"projected_time_iso": "2027-03-01T08:30:00.000Z"
}
},
"locked": {
"stx": {
"stx_only": "1000000",
"bonds": "1000000",
"total": "1000000"
},
"btc": {
"total": "1000000",
"native": "1000000",
"sbtc": "1000000"
}
},
"participants": {
"stakers": {
"stx_only": 1,
"bonds": 1
},
"signers": 1
},
"bonds": {
"total": 1,
"indexes": [
1
]
},
"rewards": {
"btc": {
"total": "1000000",
"waterfall": {
"bonds": "1000000",
"stx_only": "1000000",
"reserve_deposit": "1000000"
},
"claimed": "1000000"
}
}
}Get the signer set of a PoX cycle, including each signer's weight, staked amount, and the signer manager contracts whose registered signing key was this key when the cycle's reward set was calculated.
A PoX cycle number (up to nine digits), or one of current (the cycle containing the current Bitcoin tip), previous, or next. The prepare phase at the end of a cycle belongs to that cycle.
{"value":"143"}Pattern: ^([0-9]{1,9}|current|previous|next)$Number of results per page
100Cursor for paginating a cycle's signers (sorted by weight descending, then signing key). Format: signing key
^(0x)?[0-9a-fA-F]{66}$Default Response
1Number of results per page
100Default Response
GET /extended/v3/staking/cycles/{cycle_number}/signers HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 100,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"signing_key": "0x038e3c4529395611be9abf6fa3b6987e81d402385e3d605a073f42f407565a4a3d",
"weight": {
"amount": 1,
"percent": 1
},
"staked_stx": {
"amount": "text",
"percent": 1
},
"signer_managers": [
{
"signer_manager": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
"registered_at": {
"block_height": 1,
"bitcoin_block_height": 1,
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6"
},
"granted_keys": [
{
"signer_key": "text",
"auth_id": "text",
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6"
}
],
"grant_active": true,
"pending_key_update": {
"signer_key": "text",
"effective_cycle": 1,
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6"
}
}
]
}
]
}Get the total Bitcoin generated by staking on the Stacks network across all history, along with the total BTC burned by block commits. Values are in satoshis and always reflect the latest ingested chain state.
Default Response
Default Response
GET /extended/v3/staking/rewards HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"btc": {
"reward_amount": "9232234450122",
"burn_amount": "184023450122",
"total_amount": "9416257900244"
}
}Get the all-time registry of pox-5 staking signers: every signer principal that has ever registered a signer key, with its most recently registered key. Registrants are never removed from this registry, even if they are no longer part of the current cycle's signer set.
Number of results per page
100Cursor for paginating staking signers (sorted by signer). Format: signer principal
^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$Default Response
1Number of results per page
100Default Response
GET /extended/v3/staking/signers HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 100,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"signer": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
"signer_key": "0x03a0f9e1..."
}
]
}Get a registered pox-5 staking signer along with the details of the transaction that registered its current key.
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Default Response
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$The registered compressed secp256k1 public key, as a 0x-prefixed hex string
0x03a0f9e1...Default Response
GET /extended/v3/staking/signers/{principal} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"signer": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
"signer_key": "0x03a0f9e1...",
"transaction": {
"tx_id": "0xf6bd5f4a7b26184a3466340b2e99fd003b4962c0e382a7e4b6a13df3dd7a91c6",
"block": {
"height": 1,
"hash": "text",
"index_hash": "text",
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z",
"tx_index": 1
},
"bitcoin_block": {
"height": 1,
"time": 1,
"time_iso": "2026-10-08T19:18:41.000Z"
}
}
}List the stakers that belong to a pox-5 signer, across both direct STX staking and BTC/sBTC bond staking. Each entry indicates which staking type(s) the staker participates in under this signer.
Stacks Address
SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWPPattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$Smart Contract ID
SP000000000000000000002Q6VF78.pox-3Pattern: ^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$Number of results per page
100Cursor for paginating a signer's stakers (sorted by staker). Format: staker principal
^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$Default Response
1Number of results per page
100Default Response
GET /extended/v3/staking/signers/{principal}/stakers HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
"total": 1,
"limit": 100,
"cursor": {
"next": "text",
"previous": "text",
"current": "text"
},
"results": [
{
"staker": "SP318Q55DEKHRXJK696033DQN5C54D9K2EE6DHRWP",
"types": [
"stx"
]
}
]
}Last updated
Was this helpful?