> For the complete documentation index, see [llms.txt](https://docs.stacks.co/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stacks.co/reference/api/stacks-blockchain-api/staking.md). # Staking Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards ## Get principal staking summary > 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\`. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/staking":{"get":{"operationId":"get_principal_staking_summary","summary":"Get principal staking summary","tags":["Staking"],"description":"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`.","parameters":[{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["stx","bonds"],"properties":{"stx":{"type":"object","required":["locked","rewards"],"properties":{"locked":{"description":"The amount of uSTX currently locked in pox-5 STX staking","type":"string"},"rewards":{"type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["accrued","claimed","claimable"],"properties":{"accrued":{"description":"The lifetime sBTC reward sats accrued to this position","type":"string"},"claimed":{"description":"The lifetime sBTC reward sats already claimed against this position","type":"string"},"claimable":{"description":"The sBTC reward sats currently claimable (accrued minus claimed)","type":"string"}}}}}}},"bonds":{"type":"object","required":["count","locked","rewards"],"properties":{"count":{"description":"Number of bonds this principal has a position in","type":"integer"},"locked":{"type":"object","required":["btc","stx"],"properties":{"btc":{"description":"Total BTC locked across all bond positions","type":"string"},"stx":{"description":"Total STX locked across all bond positions","type":"string"}}},"rewards":{"type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["accrued","claimed","claimable"],"properties":{"accrued":{"description":"The lifetime sBTC reward sats accrued to this position","type":"string"},"claimed":{"description":"The lifetime sBTC reward sats already claimed against this position","type":"string"},"claimable":{"description":"The sBTC reward sats currently claimable (accrued minus claimed)","type":"string"}}}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get principal bond positions > Get a principal's bond positions — its enrollment, lock, status, and sBTC rewards in each bond it participates in. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/staking/bonds":{"get":{"operationId":"get_principal_bond_positions","summary":"Get principal bond positions","tags":["Staking"],"description":"Get a principal's bond positions — its enrollment, lock, status, and sBTC rewards in each bond it participates in.","parameters":[{"schema":{"minimum":1,"default":20,"maximum":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^\\d+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating bonds. Format: bond_index"},{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":20,"maximum":50,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"type":"object","required":["bond_index","status","active","enrollment","locked","rewards"],"properties":{"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"status":{"anyOf":[{"type":"string","enum":["enrolled"]},{"type":"string","enum":["running"]},{"type":"string","enum":["early_exit"]},{"type":"string","enum":["unlocked"]},{"type":"string","enum":["rolled_over"]}]},"active":{"description":"Whether the position is active","type":"boolean"},"enrollment":{"type":"object","required":["tx_id","btc_lockup"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"btc_lockup":{"type":"object","required":["amount"],"properties":{"amount":{"description":"The amount of BTC that is locked up for this principal","type":"string"}}}}},"locked":{"type":"object","required":["btc","stx"],"properties":{"btc":{"description":"The amount of BTC locked in this bond position","type":"string"},"stx":{"description":"The amount of STX locked in this bond position","type":"string"}}},"rewards":{"type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["accrued","claimed","claimable"],"properties":{"accrued":{"description":"The lifetime sBTC reward sats accrued to this position","type":"string"},"claimed":{"description":"The lifetime sBTC reward sats already claimed against this position","type":"string"},"claimable":{"description":"The sBTC reward sats currently claimable (accrued minus claimed)","type":"string"}}}}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bonds > Get bonds ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds":{"get":{"operationId":"get_bonds","summary":"Get bonds","tags":["Staking"],"description":"Get bonds","parameters":[{"schema":{"minimum":1,"default":20,"maximum":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^\\d+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating bonds. Format: bond_index"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":20,"maximum":50,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^\\d+$","description":"Cursor for paginating bonds. Format: bond_index","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"type":"object","required":["index","pox_version","status","parameters","registrations","schedule","balances"],"properties":{"index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"pox_version":{"type":"string","enum":["pox5"]},"status":{"anyOf":[{"type":"string","enum":["upcoming"]},{"type":"string","enum":["active"]},{"type":"string","enum":["unlocked"]}]},"parameters":{"type":"object","required":["target_rate_bps","stx_value_ratio","minimum_stx_ratio","btc_capacity"],"properties":{"target_rate_bps":{"description":"The target yield rate (APY) in basis points","type":"integer"},"stx_value_ratio":{"description":"This is a representation of the STXBTC price. The value represents \"uSTX per 100 sats\"","type":"integer"},"minimum_stx_ratio":{"description":"The amount of STX that must be locked relative to BTC, in equal-valued terms (ie in USD terms). This value is represented in basis points.","type":"integer"},"btc_capacity":{"description":"The total capacity of BTC that can be locked up for this bond","type":"string"}}},"registrations":{"type":"object","required":["allowed_count","registered_count"],"properties":{"allowed_count":{"description":"The number of entries in the allowlist for this bond","type":"integer"},"registered_count":{"description":"The number of registrations for this bond","type":"integer"}}},"schedule":{"description":"The bond's lifecycle timeline. Each point is the first Bitcoin height of a new phase: `enrollment_cutoff` is the first height at which `register-for-bond` is rejected (the prepare phase before activation, so enrollment is open strictly before it), `activation` is the first height the bond is active, and `unlock` the first height it is unlocked.","type":"object","required":["enrollment_cutoff","activation","unlock"],"properties":{"enrollment_cutoff":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"activation":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"unlock":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}}}},"balances":{"type":"object","required":["locked","rewards","paid_out"],"properties":{"locked":{"type":"object","required":["btc","stx"],"properties":{"btc":{"description":"The total amount of BTC that is locked up for this bond","type":"string"},"stx":{"description":"The total amount of STX that is locked up for this bond","type":"string"}}},"rewards":{"type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["distributed","accrued","claimed"],"properties":{"distributed":{"description":"The lifetime sBTC reward sats the contract has distributed into this bond's reward pool","type":"string"},"accrued":{"description":"An estimate of the lifetime sBTC reward sats credited to this bond's participants. Never more than `distributed`, because each share is floored to whole sats and the rounding remainder stays in the pool. This is computed by flooring each distribution, while the contract floors each settlement interval, so it can under-report by a few sats and may read slightly below `claimed`. Use `distributed` and `claimed` where exactness matters","type":"string"},"claimed":{"description":"The lifetime sBTC reward sats this bond's participants have already claimed","type":"string"}}}}},"paid_out":{"type":"object","required":["btc"],"properties":{"btc":{"description":"The total amount of BTC that has been paid out for this bond. **Deprecated**: use `rewards.btc.distributed`, which this mirrors","deprecated":true,"type":"string"}}}}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}":{"get":{"operationId":"get_bond","summary":"Get bond","tags":["Staking"],"description":"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.","parameters":[{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["index","pox_version","status","parameters","registrations","schedule","balances","transaction"],"properties":{"index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"pox_version":{"type":"string","enum":["pox5"]},"status":{"anyOf":[{"type":"string","enum":["upcoming"]},{"type":"string","enum":["active"]},{"type":"string","enum":["unlocked"]}]},"parameters":{"type":"object","required":["target_rate_bps","stx_value_ratio","minimum_stx_ratio","btc_capacity"],"properties":{"target_rate_bps":{"description":"The target yield rate (APY) in basis points","type":"integer"},"stx_value_ratio":{"description":"This is a representation of the STXBTC price. The value represents \"uSTX per 100 sats\"","type":"integer"},"minimum_stx_ratio":{"description":"The amount of STX that must be locked relative to BTC, in equal-valued terms (ie in USD terms). This value is represented in basis points.","type":"integer"},"btc_capacity":{"description":"The total capacity of BTC that can be locked up for this bond","type":"string"}}},"registrations":{"type":"object","required":["allowed_count","registered_count"],"properties":{"allowed_count":{"description":"The number of entries in the allowlist for this bond","type":"integer"},"registered_count":{"description":"The number of registrations for this bond","type":"integer"}}},"schedule":{"description":"The bond's lifecycle timeline. Each point is the first Bitcoin height of a new phase: `enrollment_cutoff` is the first height at which `register-for-bond` is rejected (the prepare phase before activation, so enrollment is open strictly before it), `activation` is the first height the bond is active, and `unlock` the first height it is unlocked.","type":"object","required":["enrollment_cutoff","activation","unlock"],"properties":{"enrollment_cutoff":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"activation":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"unlock":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}}}},"balances":{"type":"object","required":["locked","rewards","paid_out"],"properties":{"locked":{"type":"object","required":["btc","stx"],"properties":{"btc":{"description":"The total amount of BTC that is locked up for this bond","type":"string"},"stx":{"description":"The total amount of STX that is locked up for this bond","type":"string"}}},"rewards":{"type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["distributed","accrued","claimed"],"properties":{"distributed":{"description":"The lifetime sBTC reward sats the contract has distributed into this bond's reward pool","type":"string"},"accrued":{"description":"An estimate of the lifetime sBTC reward sats credited to this bond's participants. Never more than `distributed`, because each share is floored to whole sats and the rounding remainder stays in the pool. This is computed by flooring each distribution, while the contract floors each settlement interval, so it can under-report by a few sats and may read slightly below `claimed`. Use `distributed` and `claimed` where exactness matters","type":"string"},"claimed":{"description":"The lifetime sBTC reward sats this bond's participants have already claimed","type":"string"}}}}},"paid_out":{"type":"object","required":["btc"],"properties":{"btc":{"description":"The total amount of BTC that has been paid out for this bond. **Deprecated**: use `rewards.btc.distributed`, which this mirrors","deprecated":true,"type":"string"}}}}},"transaction":{"type":"object","required":["tx_id","block","bitcoin_block"],"properties":{"tx_id":{"description":"The transaction ID that created the bond","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}}}}}},{"description":"A bond that has not been set up yet. Its schedule is projected from its index under the current PoX version's rules (pox-5 starts a new bond every 2 reward cycles), so it carries no `pox_version`: the bond may end up set up under a later version, or never. Its parameters and allowlist are not known until it's set up.","type":"object","required":["index","status","schedule"],"properties":{"index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"status":{"type":"string","enum":["projected"]},"schedule":{"description":"The bond's lifecycle timeline. Each point is the first Bitcoin height of a new phase: `enrollment_cutoff` is the first height at which `register-for-bond` is rejected (the prepare phase before activation, so enrollment is open strictly before it), `activation` is the first height the bond is active, and `unlock` the first height it is unlocked.","type":"object","required":["enrollment_cutoff","activation","unlock"],"properties":{"enrollment_cutoff":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"activation":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"unlock":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}}}}}}]}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond events > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/events":{"get":{"operationId":"get_bond_events","summary":"Get bond events","tags":["Staking"],"description":"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.","parameters":[{"schema":{"minimum":1,"default":20,"maximum":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0-9]+:[0-9]+:[0-9]+:[0-9]+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index"},{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":20,"maximum":50,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"description":"Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index","pattern":"^[0-9]+:[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"description":"Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index","pattern":"^[0-9]+:[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"description":"Cursor for paginating individual events by their position in the chain. Format: block_height:microblock_sequence:tx_index:event_index","pattern":"^[0-9]+:[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"BondEvent","anyOf":[{"title":"BondSetupEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["setup-bond"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["parameters","early_unlock_bytes","schedule"],"properties":{"parameters":{"type":"object","required":["target_rate_bps","stx_value_ratio","minimum_stx_ratio"],"properties":{"target_rate_bps":{"description":"The target yield rate (APY) in basis points","type":"integer"},"stx_value_ratio":{"description":"This is a representation of the STXBTC price. The value represents \"uSTX per 100 sats\"","type":"integer"},"minimum_stx_ratio":{"description":"The amount of STX that must be locked relative to BTC, in equal-valued terms (ie in USD terms). This value is represented in basis points.","type":"integer"}}},"early_unlock_bytes":{"description":"Hex string of the Bitcoin script subscript guarding the early-exit branch of the L1 lockup","type":"string"},"schedule":{"description":"The bond's lifecycle timeline. Each point is the first Bitcoin height of a new phase: `enrollment_cutoff` is the first height at which `register-for-bond` is rejected (the prepare phase before activation, so enrollment is open strictly before it), `activation` is the first height the bond is active, and `unlock` the first height it is unlocked.","type":"object","required":["enrollment_cutoff","activation","unlock"],"properties":{"enrollment_cutoff":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"activation":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"unlock":{"type":"object","required":["bitcoin_height","pox_cycle","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point in the bond lifecycle","type":"integer"},"pox_cycle":{"description":"The PoX cycle of this point in the bond lifecycle","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}}}}}}}},{"title":"BondAddToAllowlistEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["add-to-allowlist"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["staker","max_sats"],"properties":{"staker":{"type":"string"},"max_sats":{"type":"string"}}}}},{"title":"BondRegisterEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["register-for-bond"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["staker","signer","type","balances"],"properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["l1"]},{"type":"string","enum":["l2"]}]},"balances":{"type":"object","required":["btc","stx"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"stx":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}}}}}},{"title":"BondUpdateRegistrationEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["update-bond-registration"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["staker","signer","type","balances","old_signer"],"properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["l1"]},{"type":"string","enum":["l2"]}]},"balances":{"type":"object","required":["btc","stx"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"stx":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"old_signer":{"description":"The previous signer of the registration","type":"string"}}}}},{"title":"BondAnnounceL1EarlyExitEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["announce-l1-early-exit"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["staker","signer","released"],"properties":{"staker":{"description":"The staker exiting the bond early","type":"string"},"signer":{"description":"The signer the staker was staked under","type":"string"},"released":{"description":"The sats released by the early exit","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}}}}}},{"title":"BondUnstakeSbtcEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["unstake-sbtc"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["staker","signer","withdrawn","remaining"],"properties":{"staker":{"description":"The staker withdrawing sBTC from the bond","type":"string"},"signer":{"description":"The signer the staker was staked under","type":"string"},"withdrawn":{"description":"The sats withdrawn","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"remaining":{"description":"The sBTC shares remaining after the withdrawal; 0 indicates a full early exit","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}}}}}},{"title":"BondDistributionEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["bond-distribution"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["calculation","target_yield","rewards","staked","accrued_rewards_per_sat","cumulative_rewards_per_sat"],"properties":{"calculation":{"description":"The `calculate-rewards` call this distribution was emitted by, from the `calculate-rewards` event in the same transaction.","type":"object","required":["bitcoin_height","reward_cycle"],"properties":{"bitcoin_height":{"description":"The Bitcoin height the rewards were calculated for: the start of the distribution period, which can differ from the height of the block carrying this event.","type":"integer"},"reward_cycle":{"description":"The PoX reward cycle the calculation (and this distribution) books to","type":"integer"}}},"target_yield":{"pattern":"^[0-9]+$","description":"The bond's target reward for this calculation, in sats","type":"string"},"rewards":{"description":"The rewards earned by this bond this calculation","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"staked":{"description":"The sats staked in the bond at calculation time","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"accrued_rewards_per_sat":{"pattern":"^[0-9]+$","description":"The per-sat rewards accrued this calculation, as a 1e18 fixed-point integer","type":"string"},"cumulative_rewards_per_sat":{"pattern":"^[0-9]+$","description":"The running per-sat reward total for the bond after this calculation, as a 1e18 fixed-point integer","type":"string"}}}}},{"title":"BondClaimStakerRewardsEvent","type":"object","required":["name","bond_index","transaction","block","bitcoin_block","data"],"properties":{"name":{"type":"string","enum":["claim-staker-rewards-for-signer"]},"bond_index":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"},"transaction":{"type":"object","required":["tx_id","event_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"event_index":{"description":"Index of the event within the transaction","type":"integer"}}},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}},"data":{"type":"object","required":["signer_manager","staker","reward_cycle","claimed"],"properties":{"signer_manager":{"description":"The signer manager that claimed on behalf of the staker","type":"string"},"staker":{"description":"The staker the rewards were claimed for","type":"string"},"reward_cycle":{"description":"The PoX reward cycle claimed","type":"integer"},"claimed":{"description":"The sats claimed","type":"object","required":["btc"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}}}}}}]}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond allowlist entries > Get bond allowlist entries ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/allowlist":{"get":{"operationId":"get_bond_allowlist_entries","summary":"Get bond allowlist entries","tags":["Staking"],"description":"Get bond allowlist entries","parameters":[{"schema":{"minimum":1,"default":20,"maximum":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index"},{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":20,"maximum":50,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"type":"object","required":["staker","max_sats"],"properties":{"staker":{"type":"string"},"max_sats":{"type":"string"}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond allowlist entry > Get bond allowlist entry ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/allowlist/{principal}":{"get":{"operationId":"get_bond_allowlist_entry","summary":"Get bond allowlist entry","tags":["Staking"],"description":"Get bond allowlist entry","parameters":[{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"},{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["staker","max_sats"],"properties":{"staker":{"type":"string"},"max_sats":{"type":"string"}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond registrations > Get bond registrations ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/registrations":{"get":{"operationId":"get_bond_registrations","summary":"Get bond registrations","tags":["Staking"],"description":"Get bond registrations","parameters":[{"schema":{"minimum":1,"default":20,"maximum":50,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index"},{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":20,"maximum":50,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"description":"Cursor for paginating transactions. Format: block_height:microblock_sequence:tx_index","pattern":"^[0-9]+:[0-9]+:[0-9]+$","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"type":"object","required":["staker","signer","type","balances"],"properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["l1"]},{"type":"string","enum":["l2"]}]},"balances":{"type":"object","required":["btc","stx"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"stx":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get bond registration > Get bond registration ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/registrations/{principal}":{"get":{"operationId":"get_bond_registration","summary":"Get bond registration","tags":["Staking"],"description":"Get bond registration","parameters":[{"schema":{"type":"integer"},"in":"path","name":"bond_index","required":true,"description":"The index of the bond in the PoX-5 bond list"},{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"anyOf":[{"type":"object","required":["staker","signer","type","balances","l1_lockup"],"properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["l1"]},{"type":"string","enum":["l2"]}]},"balances":{"type":"object","required":["btc","stx"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"stx":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"l1_lockup":{"type":"object","required":["transactions"],"properties":{"transactions":{"description":"The proven L1 lockup transactions","type":"array","items":{"type":"object","required":["tx_id","output_index"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"output_index":{"description":"The output index of the proven L1 lockup","type":"integer"}}}}}}}},{"type":"object","required":["staker","signer","type","balances","l2_lockup"],"properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"anyOf":[{"type":"string","enum":["l1"]},{"type":"string","enum":["l2"]}]},"balances":{"type":"object","required":["btc","stx"],"properties":{"btc":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"stx":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"}}},"l2_lockup":{"type":"object","required":["tx_id"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"}}}}}]}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get staking cycle > A summary of staking for one PoX reward cycle. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/cycles/{cycle_number}":{"get":{"operationId":"get_staking_cycle","summary":"Get staking cycle","tags":["Staking"],"description":"A summary of staking for one PoX reward cycle.","parameters":[{"schema":{"pattern":"^([0-9]{1,9}|current|previous|next)$","type":"string"},"in":"path","name":"cycle_number","required":true,"description":"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."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"StakingCycle","type":"object","required":["number","status","schedule","locked","participants","bonds","rewards"],"properties":{"number":{"description":"The PoX reward cycle number","type":"integer"},"status":{"description":"Where the cycle stands relative to the current Bitcoin tip.","anyOf":[{"type":"string","enum":["upcoming"]},{"type":"string","enum":["reward_phase"]},{"type":"string","enum":["prepare_phase"]},{"type":"string","enum":["finished"]}]},"schedule":{"description":"The Bitcoin heights delimiting the cycle, inclusive: its first block, the first block of its prepare phase, and its last block.","type":"object","required":["start","prepare_phase_start","end"],"properties":{"start":{"type":"object","required":["bitcoin_height","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"prepare_phase_start":{"type":"object","required":["bitcoin_height","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}},"end":{"type":"object","required":["bitcoin_height","time","time_iso","projected_time","projected_time_iso"],"properties":{"bitcoin_height":{"description":"The Bitcoin height of this point","type":"integer"},"time":{"description":"Unix timestamp (in seconds) of when the Bitcoin block was mined, once it has been. The API learns Bitcoin block times only from the Stacks blocks anchored to them: for a block a Stacks block anchored to, this is the time recorded in its header; for a past block none anchored to (e.g. a missed sortition), it is an estimate, interpolated between the nearest anchored blocks before and after it. `null` for a block that has not been mined yet, and for a past block older than any Stacks block.","anyOf":[{"type":"integer"},{"type":"null"}]},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]},"projected_time":{"description":"Unix timestamp (in seconds) of when a future Bitcoin block is projected to be mined, extrapolated from the recent Bitcoin block pace (on mainnet, from the pace of the current difficulty period until its retarget, and the 10-minute target after it). Projections further out are less precise, by days for blocks months away. `null` once the block has been mined, and for a block projected past the end of year 9999.","anyOf":[{"type":"integer"},{"type":"null"}]},"projected_time_iso":{"description":"The `projected_time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; `null` with it.","anyOf":[{"type":"string"},{"type":"null"}]}}}}},"locked":{"description":"The assets locked by staking for this cycle","type":"object","required":["stx","btc"],"properties":{"stx":{"type":"object","required":["stx_only","bonds","total"],"properties":{"stx_only":{"pattern":"^[0-9]+$","title":"Amount","description":"STX locked in STX-only staking that counts for this cycle, in µSTX.","type":"string"},"bonds":{"pattern":"^[0-9]+$","title":"Amount","description":"STX locked across the bonds covering this cycle, in µSTX.","type":"string"},"total":{"pattern":"^[0-9]+$","title":"Amount","description":"Sum of `stx_only` and `bonds`, in µSTX.","type":"string"}}},"btc":{"type":"object","required":["total","native","sbtc"],"properties":{"total":{"pattern":"^[0-9]+$","title":"Amount","description":"BTC locked across the bonds covering this cycle, in satoshis (proven Bitcoin L1 lockups and sBTC lockups). For a finished cycle this is the BTC staked per bond at the cycle's latest reward distribution; otherwise the bonds' running locked totals.","type":"string"},"native":{"pattern":"^[0-9]+$","title":"Amount","description":"Of `total`, the satoshis locked through proven Bitcoin L1 lockups.","type":"string"},"sbtc":{"pattern":"^[0-9]+$","title":"Amount","description":"Of `total`, the satoshis locked through sBTC lockups.","type":"string"}}}}},"participants":{"description":"Who participates in the cycle","type":"object","required":["stakers","signers"],"properties":{"stakers":{"type":"object","required":["stx_only","bonds"],"properties":{"stx_only":{"description":"Principals whose STX-only stake counts for this cycle.","type":"integer"},"bonds":{"description":"Principals holding a position in a bond covering this cycle.","type":"integer"}}},"signers":{"anyOf":[{"description":"Signers in the cycle's reward set. `null` until the node has emitted the reward set, which happens during the previous cycle's prepare phase.","type":"integer"},{"type":"null"}]}}},"bonds":{"description":"The pox-5 bonds active during this cycle","type":"object","required":["total","indexes"],"properties":{"total":{"description":"Bonds whose term covers this cycle","type":"integer"},"indexes":{"description":"Their bond indexes, ascending","type":"array","items":{"description":"The index of the bond in the PoX-5 bond list","type":"integer"}}}},"rewards":{"description":"The rewards generated by this cycle","type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["total","waterfall","claimed"],"properties":{"total":{"pattern":"^[0-9]+$","title":"Amount","description":"sBTC rewards booked to this cycle by the pox-5 reward distributions run so far, in satoshis. Distributions run periodically within a cycle, so this grows while the cycle is active; it equals the sum of the `waterfall` entries.","type":"string"},"waterfall":{"description":"How the accrued rewards were split, in payout order","type":"object","required":["bonds","stx_only","reserve_deposit"],"properties":{"bonds":{"pattern":"^[0-9]+$","title":"Amount","description":"The share paid to bond participants, in satoshis.","type":"string"},"stx_only":{"pattern":"^[0-9]+$","title":"Amount","description":"The share paid to STX-only stakers, in satoshis.","type":"string"},"reserve_deposit":{"pattern":"^[0-9]+$","title":"Amount","description":"The share deposited into the protocol reserve, in satoshis.","type":"string"}}},"claimed":{"pattern":"^[0-9]+$","title":"Amount","description":"sBTC claimed from the pox-5 contract by signer managers for this cycle so far, in satoshis. Claims trail distributions and can keep growing after the cycle ends.","type":"string"}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get cycle signers > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/cycles/{cycle_number}/signers":{"get":{"operationId":"get_cycle_signers","summary":"Get cycle signers","tags":["Staking"],"description":"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.","parameters":[{"schema":{"minimum":1,"default":100,"maximum":250,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^(0x)?[0-9a-fA-F]{66}$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating a cycle's signers (sorted by weight descending, then signing key). Format: signing key"},{"schema":{"pattern":"^([0-9]{1,9}|current|previous|next)$","type":"string"},"in":"path","name":"cycle_number","required":true,"description":"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."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":100,"maximum":250,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^(0x)?[0-9a-fA-F]{66}$","description":"Cursor for paginating a cycle's signers (sorted by weight descending, then signing key). Format: signing key","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^(0x)?[0-9a-fA-F]{66}$","description":"Cursor for paginating a cycle's signers (sorted by weight descending, then signing key). Format: signing key","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^(0x)?[0-9a-fA-F]{66}$","description":"Cursor for paginating a cycle's signers (sorted by weight descending, then signing key). Format: signing key","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"CycleSigner","type":"object","required":["signing_key","weight","staked_stx","signer_managers"],"properties":{"signing_key":{"description":"The signing key in the cycle's reward set, as a `0x`-prefixed hex string","type":"string"},"weight":{"description":"The signer's voting weight in the cycle","type":"object","required":["amount","percent"],"properties":{"amount":{"type":"integer"},"percent":{"description":"Percentage of the cycle's total signer weight","type":"number"}}},"staked_stx":{"description":"The uSTX staked behind this signer in the cycle","type":"object","required":["amount","percent"],"properties":{"amount":{"type":"string"},"percent":{"description":"Percentage of the cycle's total staked STX","type":"number"}}},"signer_managers":{"description":"The signer manager contracts whose registered signing key (via `register-signer`) was this key when the cycle's reward set was calculated.","type":"array","items":{"title":"CycleSignerManager","type":"object","required":["signer_manager","registered_at","granted_keys","grant_active","pending_key_update"],"properties":{"signer_manager":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"registered_at":{"description":"The position of the `register-signer` event that bound this key to the manager.","type":"object","required":["block_height","bitcoin_block_height","tx_id"],"properties":{"block_height":{"description":"Stacks block height of the `register-signer` event","type":"integer"},"bitcoin_block_height":{"description":"Bitcoin block height of the `register-signer` event","type":"integer"},"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"}}},"granted_keys":{"description":"The manager's live `grant-signer-key` authorizations (granted and not revoked). A grant authorizes a future `register-signer` for that key but does not rotate the key by itself.","type":"array","items":{"title":"SignerKeyGrant","type":"object","required":["signer_key","auth_id","tx_id"],"properties":{"signer_key":{"description":"The granted signing key, as a `0x`-prefixed hex string","type":"string"},"auth_id":{"description":"The grant's auth id as a decimal string","type":"string"},"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"}}}},"grant_active":{"description":"Whether a live `grant-signer-key` authorization currently exists for the registered key.","type":"boolean"},"pending_key_update":{"anyOf":[{"description":"The manager's latest key registered after this cycle's reward set was calculated, when it differs from the cycle's signing key. Takes effect next cycle.","type":"object","required":["signer_key","effective_cycle","tx_id"],"properties":{"signer_key":{"description":"The newly registered signing key, as a `0x`-prefixed hex string","type":"string"},"effective_cycle":{"description":"The PoX cycle in which the new key takes effect","type":"integer"},"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"}}},{"type":"null"}]}}}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get network staking reward totals > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/rewards":{"get":{"operationId":"get_staking_rewards","summary":"Get network staking reward totals","tags":["Staking"],"description":"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.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"StakingRewards","type":"object","required":["btc"],"properties":{"btc":{"type":"object","required":["reward_amount","burn_amount","total_amount"],"properties":{"reward_amount":{"pattern":"^[0-9]+$","title":"Amount","description":"Total Bitcoin generated by staking on the Stacks network, in satoshis, counted as the BTC paid by block commits to reward recipients: stacker reward addresses directly through pox-4, and the sBTC peg custody address from pox-5 on (whose inflows fund the sBTC staking rewards distributed through the pox-5 contract).","type":"string"},"burn_amount":{"pattern":"^[0-9]+$","title":"Amount","description":"Total BTC burned by block commits, in satoshis, including pox-1 through pox-4 prepare-phase burns. Excludes the 2.0-era PoX sunset-ramp surcharge (bitcoin blocks ~766050-781551), which the node never reported. pox-5 commits do not burn.","type":"string"},"total_amount":{"pattern":"^[0-9]+$","title":"Amount","description":"Sum of `reward_amount` and `burn_amount`, in satoshis: the total BTC block commits have spent toward staking across all history, whether paid to recipients or burned.","type":"string"}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get staking signers > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/signers":{"get":{"operationId":"get_staking_signers","summary":"Get staking signers","tags":["Staking"],"description":"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.","parameters":[{"schema":{"minimum":1,"default":100,"maximum":250,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating staking signers (sorted by signer). Format: signer principal"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":100,"maximum":250,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating staking signers (sorted by signer). Format: signer principal","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating staking signers (sorted by signer). Format: signer principal","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating staking signers (sorted by signer). Format: signer principal","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"StakingSigner","type":"object","required":["signer","signer_key"],"properties":{"signer":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"signer_key":{"description":"The registered compressed secp256k1 public key, as a `0x`-prefixed hex string","type":"string"}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get staking signer > Get a registered pox-5 staking signer along with the details of the transaction that registered its current key. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/signers/{principal}":{"get":{"operationId":"get_staking_signer","summary":"Get staking signer","tags":["Staking"],"description":"Get a registered pox-5 staking signer along with the details of the transaction that registered its current key.","parameters":[{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"StakingSignerDetail","type":"object","required":["signer","signer_key","transaction"],"properties":{"signer":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"signer_key":{"description":"The registered compressed secp256k1 public key, as a `0x`-prefixed hex string","type":"string"},"transaction":{"type":"object","required":["tx_id","block","bitcoin_block"],"properties":{"tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"block":{"type":"object","required":["height","hash","index_hash","time","time_iso","tx_index"],"properties":{"height":{"description":"Height of the block this transactions was associated with","type":"integer"},"hash":{"description":"Hash of the blocked this transactions was associated with","type":"string"},"index_hash":{"description":"Hash of the index block this transactions was associated with","type":"string"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"},"tx_index":{"description":"Index of the transaction, indicating the order. Starts at `0` and increases with each transaction","type":"integer"}}},"bitcoin_block":{"type":"object","required":["height","time","time_iso"],"properties":{"height":{"description":"Height of the anchor burn block.","type":"integer"},"time":{"description":"Unix timestamp (in seconds) indicating when this block was mined.","type":"number"},"time_iso":{"description":"The `time` as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp.","type":"string"}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` ## Get staking signer stakers > 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. ```json {"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Staking","description":"Read-only endpoints to obtain PoX-5 Bitcoin Staking details: bonds, allowlists, registrations, cycles, signers and rewards"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/staking/signers/{principal}/stakers":{"get":{"operationId":"get_staking_signer_stakers","summary":"Get staking signer stakers","tags":["Staking"],"description":"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.","parameters":[{"schema":{"minimum":1,"default":100,"maximum":200,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating a signer's stakers (sorted by staker). Format: staker principal"},{"schema":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"in":"path","name":"principal","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":100,"maximum":200,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating a signer's stakers (sorted by staker). Format: staker principal","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating a signer's stakers (sorted by staker). Format: staker principal","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}(\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39})?$","description":"Cursor for paginating a signer's stakers (sorted by staker). Format: staker principal","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"SignerStaker","type":"object","required":["staker","types"],"properties":{"staker":{"anyOf":[{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","description":"Stacks Address","type":"string"},{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}$","title":"Smart Contract ID","description":"Smart Contract ID","type":"string"}]},"types":{"description":"The staking types this staker participates in under this signer: `stx` for direct pox-5 STX staking, `btc` for BTC/sBTC bond staking. A staker doing both has both entries.","type":"array","items":{"anyOf":[{"type":"string","enum":["stx"]},{"type":"string","enum":["btc"]}]}}}}}}}}}},"4XX":{"description":"Default Response","content":{"application/json":{"schema":{"title":"Error Response","additionalProperties":true,"type":"object","required":["error"],"properties":{"error":{"type":"string"},"message":{"type":"string"}}}}}}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.stacks.co/reference/api/stacks-blockchain-api/staking.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.