> 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/bitcoin-staking.md).

# Bitcoin Staking

Endpoints for retrieving STX-staking positions, bonds, and registered staking signers.

## Get a staking summary for a principal.

> One-call summary for a principal: STX-staking position plus bond aggregate.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/principals/{principal}/staking":{"get":{"summary":"Get a staking summary for a principal.","tags":["Staking"],"operationId":"getPrincipalStaking","description":"One-call summary for a principal: STX-staking position plus bond aggregate.","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (standard or contract principal).","schema":{"type":"string"}}],"responses":{"200":{"description":"Staking summary for the principal","content":{"application/json":{"schema":{"type":"object","required":["stx","bonds"],"properties":{"stx":{"type":"object","description":"STX-staking position: the STX staked alongside the BTC, as reported by the pox-5 contract (distinct from classic PoX stacking).","properties":{"locked":{"type":"string","description":"Staked STX (microSTX)."},"rewards":{"type":"object","properties":{"btc":{"type":"object","properties":{"accrued":{"type":"string"},"claimed":{"type":"string"},"claimable":{"type":"string"}}}}}}},"bonds":{"type":"object","properties":{"count":{"type":"integer"},"locked":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}},"rewards":{"type":"object","properties":{"btc":{"type":"object","properties":{"accrued":{"type":"string"},"claimed":{"type":"string"},"claimable":{"type":"string"}}}}}}}}}}}}}}}}}
```

## Get the bond positions for a principal.

> The principal's bond positions, cursor-paginated.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/principals/{principal}/staking/bonds":{"get":{"summary":"Get the bond positions for a principal.","tags":["Staking"],"operationId":"getPrincipalStakingBonds","description":"The principal's bond positions, cursor-paginated.","parameters":[{"name":"principal","in":"path","required":true,"description":"Stacks address (standard or contract principal).","schema":{"type":"string"}},{"name":"cursor","in":"query","required":false,"description":"Opaque cursor for the next page of results.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return.","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Cursor-paginated list of the principal's bond positions","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"cursor":{"type":"object","properties":{"next":{"type":["string","null"]},"previous":{"type":["string","null"]},"current":{"type":["string","null"]}}},"results":{"type":"array","items":{"type":"object","properties":{"bond_index":{"type":"integer"},"status":{"type":"string"},"active":{"type":"boolean"},"enrollment":{"type":"object","properties":{"tx_id":{"type":"string"},"btc_lockup":{"type":"object","properties":{"amount":{"type":"string","description":"sats"}}}}},"locked":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}},"rewards":{"type":"object","properties":{"btc":{"type":"object","properties":{"accrued":{"type":"string"},"claimed":{"type":"string"},"claimable":{"type":"string"}}}}}}}}}}}}}}}}}}
```

## List bonds.

> List of bonds, cursor-paginated.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds":{"get":{"summary":"List bonds.","tags":["Staking"],"operationId":"getStakingBonds","description":"List of bonds, cursor-paginated.","parameters":[{"name":"cursor","in":"query","required":false,"description":"Opaque cursor for the next page of results.","schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"description":"Maximum number of results to return.","schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Cursor-paginated list of bonds","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"cursor":{"type":"object","properties":{"next":{"type":["string","null"]},"previous":{"type":["string","null"]},"current":{"type":["string","null"]}}},"results":{"type":"array","items":{"type":"object","properties":{"index":{"type":"integer"},"pox_version":{"type":"string"},"status":{"type":"string","enum":["upcoming","active","unlocked"]},"parameters":{"type":"object","properties":{"target_rate_bps":{"type":"integer"},"stx_value_ratio":{"type":"integer"},"minimum_stx_ratio":{"type":"integer"},"btc_capacity":{"type":"string","description":"sats"}}},"registrations":{"type":"object","properties":{"allowed_count":{"type":"integer"},"registered_count":{"type":"integer"}}},"schedule":{"type":"object","properties":{"activation":{"type":"object","properties":{"bitcoin_height":{"type":"integer"},"pox_cycle":{"type":"integer"}}},"unlock":{"type":"object","properties":{"bitcoin_height":{"type":"integer"},"pox_cycle":{"type":"integer"}}}}},"balances":{"type":"object","properties":{"locked":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}},"paid_out":{"type":"object","properties":{"btc":{"type":"string","description":"sats"}}}}}}}}}}}}}}}}}}
```

## Get bond detail.

> Bond detail for a given bond index, including the registering transaction and Bitcoin block position.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds/{bond_index}":{"get":{"summary":"Get bond detail.","tags":["Staking"],"operationId":"getStakingBond","description":"Bond detail for a given bond index, including the registering transaction and Bitcoin block position.","parameters":[{"name":"bond_index","in":"path","required":true,"description":"Bond index.","schema":{"type":"integer"}}],"responses":{"200":{"description":"Bond detail","content":{"application/json":{"schema":{"type":"object","properties":{"index":{"type":"integer"},"pox_version":{"type":"string"},"status":{"type":"string","enum":["upcoming","active","unlocked"]},"parameters":{"type":"object","properties":{"target_rate_bps":{"type":"integer"},"stx_value_ratio":{"type":"integer"},"minimum_stx_ratio":{"type":"integer"},"btc_capacity":{"type":"string","description":"sats"}}},"registrations":{"type":"object","properties":{"allowed_count":{"type":"integer"},"registered_count":{"type":"integer"}}},"schedule":{"type":"object","properties":{"activation":{"type":"object","properties":{"bitcoin_height":{"type":"integer"},"pox_cycle":{"type":"integer"}}},"unlock":{"type":"object","properties":{"bitcoin_height":{"type":"integer"},"pox_cycle":{"type":"integer"}}}}},"balances":{"type":"object","properties":{"locked":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}},"paid_out":{"type":"object","properties":{"btc":{"type":"string","description":"sats"}}}}},"transaction":{"type":"object","properties":{"tx_id":{"type":"string"},"block":{"type":"object","properties":{"height":{"type":"integer"},"hash":{"type":"string"},"index_hash":{"type":"string"},"time":{"type":"integer"},"tx_index":{"type":"integer"}}},"bitcoin_block":{"type":"object","properties":{"height":{"type":"integer"},"time":{"type":"integer"}}}}}}}}}},"404":{"description":"Bond not found"}}}}}}
```

## List allowlist entries for a bond.

> Allowlist entries for a given bond, cursor-paginated.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/allowlist":{"get":{"summary":"List allowlist entries for a bond.","tags":["Staking"],"operationId":"getStakingBondAllowlist","description":"Allowlist entries for a given bond, cursor-paginated.","parameters":[{"name":"bond_index","in":"path","required":true,"description":"Bond index.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Cursor-paginated list of allowlist entries","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"cursor":{"type":"object","properties":{"next":{"type":["string","null"]},"previous":{"type":["string","null"]},"current":{"type":["string","null"]}}},"results":{"type":"array","items":{"type":"object","properties":{"staker":{"type":"string"},"max_sats":{"type":"string","description":"Maximum BTC the staker may lock (sats)."}}}}}}}}}}}}}}
```

## Get a single allowlist entry.

> Single allowlist entry for a principal on a given bond.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/allowlist/{principal}":{"get":{"summary":"Get a single allowlist entry.","tags":["Staking"],"operationId":"getStakingBondAllowlistEntry","description":"Single allowlist entry for a principal on a given bond.","parameters":[{"name":"bond_index","in":"path","required":true,"description":"Bond index.","schema":{"type":"integer"}},{"name":"principal","in":"path","required":true,"description":"Stacks address (standard or contract principal).","schema":{"type":"string"}}],"responses":{"200":{"description":"Allowlist entry","content":{"application/json":{"schema":{"type":"object","properties":{"staker":{"type":"string"},"max_sats":{"type":"string","description":"Maximum BTC the staker may lock (sats)."}}}}}},"404":{"description":"Allowlist entry not found"}}}}}}
```

## List registrations for a bond.

> Registrations for a given bond, cursor-paginated.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/registrations":{"get":{"summary":"List registrations for a bond.","tags":["Staking"],"operationId":"getStakingBondRegistrations","description":"Registrations for a given bond, cursor-paginated.","parameters":[{"name":"bond_index","in":"path","required":true,"description":"Bond index.","schema":{"type":"integer"}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":20}}],"responses":{"200":{"description":"Cursor-paginated list of registrations","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"cursor":{"type":"object","properties":{"next":{"type":["string","null"]},"previous":{"type":["string","null"]},"current":{"type":["string","null"]}}},"results":{"type":"array","items":{"type":"object","properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"type":"string","description":"Registration type, e.g. l1."},"balances":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}}}}}}}}}}}}}}}
```

## Get a single registration.

> Single registration for a principal on a given bond, including L1 lockup transactions.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/bonds/{bond_index}/registrations/{principal}":{"get":{"summary":"Get a single registration.","tags":["Staking"],"operationId":"getStakingBondRegistration","description":"Single registration for a principal on a given bond, including L1 lockup transactions.","parameters":[{"name":"bond_index","in":"path","required":true,"description":"Bond index.","schema":{"type":"integer"}},{"name":"principal","in":"path","required":true,"description":"Stacks address (standard or contract principal).","schema":{"type":"string"}}],"responses":{"200":{"description":"Registration","content":{"application/json":{"schema":{"type":"object","properties":{"staker":{"type":"string"},"signer":{"type":"string"},"type":{"type":"string"},"balances":{"type":"object","properties":{"btc":{"type":"string","description":"sats"},"stx":{"type":"string","description":"microSTX"}}},"l1_lockup":{"type":"object","properties":{"transactions":{"type":"array","items":{"type":"object","properties":{"tx_id":{"type":"string"},"output_index":{"type":"integer"}}}}}}}}}}},"404":{"description":"Registration not found"}}}}}}
```

## List registered staking signers.

> Registered signers, cursor-paginated.

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/signers":{"get":{"summary":"List registered staking signers.","tags":["Staking"],"operationId":"getStakingSigners","description":"Registered signers, cursor-paginated.","parameters":[{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","default":100}}],"responses":{"200":{"description":"Cursor-paginated list of registered signers","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"type":"integer"},"cursor":{"type":"object","properties":{"next":{"type":["string","null"]},"previous":{"type":["string","null"]},"current":{"type":["string","null"]}}},"results":{"type":"array","items":{"type":"object","properties":{"signer":{"type":"string"},"signer_key":{"type":"string","description":"Hex-encoded compressed Secp256k1 public key (33 bytes)."}}}}}}}}}}}}}}
```

## Get a registered staking signer.

> Signer plus registration transaction block position (Stacks block and Bitcoin block).

```json
{"openapi":"3.1.0","info":{"title":"Stacks Blockchain API","version":"1.0.0"},"tags":[{"name":"Staking","description":"Endpoints for retrieving STX-staking positions, bonds, and registered staking signers."}],"servers":[{"url":"https://api.private-1.hiro.so","description":"Bitcoin staking testnet"},{"url":"https://api.hiro.so","description":"Hiro Mainnet API"}],"paths":{"/extended/v3/staking/signers/{principal}":{"get":{"summary":"Get a registered staking signer.","tags":["Staking"],"operationId":"getStakingSigner","description":"Signer plus registration transaction block position (Stacks block and Bitcoin block).","parameters":[{"name":"principal","in":"path","required":true,"description":"Signer principal (standard or contract principal).","schema":{"type":"string"}}],"responses":{"200":{"description":"Signer with registration tx block position","content":{"application/json":{"schema":{"type":"object","properties":{"signer":{"type":"string"},"signer_key":{"type":"string","description":"Hex-encoded compressed Secp256k1 public key (33 bytes)."},"transaction":{"type":"object","properties":{"tx_id":{"type":"string"},"block":{"type":"object","properties":{"height":{"type":"integer"},"hash":{"type":"string"},"index_hash":{"type":"string"},"time":{"type":"integer"},"tx_index":{"type":"integer"}}},"bitcoin_block":{"type":"object","properties":{"height":{"type":"integer"},"time":{"type":"integer"}}}}}}}}}},"404":{"description":"Signer not found"}}}}}}
```


---

# 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 dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter, and the optional `goal` query parameter:

```
GET https://docs.stacks.co/reference/api/stacks-blockchain-api/bitcoin-staking.md?ask=<question>&goal=<endgoal>
```

`ask` is the immediate question: it should be specific, self-contained, and written in natural language.
`goal` is optional and describes the broader end goal you are ultimately trying to accomplish on behalf of the user. GitBook uses it to tailor the answer towards what is most useful for that goal.

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.