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

# Accounts

Read-only endpoints to obtain Stacks account details

## Get principal mining summary

> A one-call overview of a principal's mining: its lifetime matured miner rewards (coinbase and fees, in µSTX), counting only rewards on the canonical chain. The individual rewards are paginated at \`/principals/:principal/mining/rewards\`.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/mining":{"get":{"operationId":"get_principal_mining_summary","summary":"Get principal mining summary","tags":["Accounts"],"description":"A one-call overview of a principal's mining: its lifetime matured miner rewards (coinbase and fees, in µSTX), counting only rewards on the canonical chain. The individual rewards are paginated at `/principals/:principal/mining/rewards`.","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":"PrincipalMiningSummary","type":"object","required":["rewards"],"properties":{"rewards":{"type":"object","required":["count","coinbase","fees","total"],"properties":{"count":{"description":"Number of non-zero matured miner rewards received","type":"integer"},"coinbase":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"fees":{"pattern":"^[0-9]+$","title":"Amount","description":"Transaction fees included in the reward, in µSTX","type":"string"},"total":{"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 principal mining rewards

> Returns the matured miner rewards credited to a principal, most recent first. Miner rewards are credited to the recipient's STX balance when they mature, without a transaction or STX event, so they don't appear in the principal's transactions or transfers. Each reward reports the \`block\` it matured (and was credited) in and the \`source\_block\` whose reward matured; a parent-miner share of fees reports the same \`source\_block\` as the miner reward it was paid alongside. Only rewards on the canonical chain are listed; zero-value rewards are left out.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/mining/rewards":{"get":{"operationId":"get_principal_mining_rewards","summary":"Get principal mining rewards","tags":["Accounts"],"description":"Returns the matured miner rewards credited to a principal, most recent first. Miner rewards are credited to the recipient's STX balance when they mature, without a transaction or STX event, so they don't appear in the principal's transactions or transfers. Each reward reports the `block` it matured (and was credited) in and the `source_block` whose reward matured; a parent-miner share of fees reports the same `source_block` as the miner reward it was paid alongside. Only rewards on the canonical chain are listed; zero-value rewards are left out.","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]+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating matured miner rewards. Format: mature_block_height:reward_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":"^[0-9]+:[0-9]+$","description":"Cursor for paginating matured miner rewards. Format: mature_block_height:reward_index","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^[0-9]+:[0-9]+$","description":"Cursor for paginating matured miner rewards. Format: mature_block_height:reward_index","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^[0-9]+:[0-9]+$","description":"Cursor for paginating matured miner rewards. Format: mature_block_height:reward_index","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"PrincipalMinerReward","type":"object","required":["id","recipient","miner","block","source_block","coinbase","fees","total"],"properties":{"id":{"pattern":"^0x[0-9a-fA-F]{64}:[0-9]+$","description":"Stable reward identifier: the index block hash of the block the reward matured in, followed by the reward position within that block. A block can mature more than one reward for the same recipient (its own miner reward plus its parent-miner share of fees).","type":"string"},"recipient":{"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"}]},"miner":{"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"}]},"block":{"title":"BlockSummary","type":"object","required":["height","hash","index_hash","time","time_iso"],"properties":{"height":{"title":"Block height","description":"Block height","type":"integer"},"hash":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},"index_hash":{"description":"Index block hash of the block","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"}}},"source_block":{"title":"BlockSummary","type":"object","required":["height","hash","index_hash","time","time_iso"],"properties":{"height":{"title":"Block height","description":"Block height","type":"integer"},"hash":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},"index_hash":{"description":"Index block hash of the block","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"}}},"coinbase":{"pattern":"^[0-9]+$","title":"Amount","description":"Amount","type":"string"},"fees":{"pattern":"^[0-9]+$","title":"Amount","description":"Transaction fees included in the reward, in µSTX","type":"string"},"total":{"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 principal STX balance

> Get a principal's STX balance: its total and spendable (available) balance, any locked STX, and the projected balance from pending mempool transactions.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/balances/stx":{"get":{"operationId":"get_principal_balances_stx","summary":"Get principal STX balance","tags":["Accounts"],"description":"Get a principal's STX balance: its total and spendable (available) balance, any locked STX, and the projected balance from pending mempool transactions.","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":"PrincipalStxBalance","type":"object","required":["balance","available","locked","mempool"],"properties":{"balance":{"description":"Total micro-STX balance (available plus locked)","type":"string"},"available":{"description":"Spendable micro-STX balance (balance minus locked)","type":"string"},"locked":{"anyOf":[{"title":"StxLock","type":"object","required":["amount","pox_version","lock_tx_id","stacks_lock_height","burn_lock_height","burn_unlock_height"],"properties":{"amount":{"description":"The amount of locked micro-STX","type":"string"},"pox_version":{"description":"The PoX contract version that created the lock (e.g. 4, 5)","type":"integer"},"lock_tx_id":{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Transaction ID","description":"Transaction ID","type":"string"},"stacks_lock_height":{"description":"The Stacks block height at which the lock was created","type":"integer"},"burn_lock_height":{"description":"The burnchain block height at which the lock was created","type":"integer"},"burn_unlock_height":{"description":"The burnchain block height at which the locked STX unlocks","type":"integer"}}},{"type":"null"}]},"mempool":{"anyOf":[{"title":"StxMempoolBalance","type":"object","required":["estimated_balance","inbound","outbound"],"properties":{"estimated_balance":{"description":"Estimated spendable micro-STX balance once pending mempool txs confirm","type":"string"},"inbound":{"description":"Pending inbound micro-STX from the mempool","type":"string"},"outbound":{"description":"Pending outbound micro-STX from the mempool (transfers plus fees)","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 principal FT balances

> Get a principal's fungible-token balances, sorted by balance descending.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/balances/ft":{"get":{"operationId":"get_principal_balances_ft","summary":"Get principal FT balances","tags":["Accounts"],"description":"Get a principal's fungible-token balances, sorted by balance descending.","parameters":[{"schema":{"minimum":1,"default":100,"maximum":200,"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 FT balances (sorted by balance, descending). Format: balance:asset_identifier"},{"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":"^\\d+:.+$","description":"Cursor for paginating FT balances (sorted by balance, descending). Format: balance:asset_identifier","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^\\d+:.+$","description":"Cursor for paginating FT balances (sorted by balance, descending). Format: balance:asset_identifier","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^\\d+:.+$","description":"Cursor for paginating FT balances (sorted by balance, descending). Format: balance:asset_identifier","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"PrincipalFtPosition","type":"object","required":["asset_identifier","balance"],"properties":{"asset_identifier":{"description":"Fungible token asset identifier","type":"string"},"balance":{"description":"The principal's balance of this token, as a string-quoted integer in base units","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 FT balance

> Get a principal's balance of a single fungible token. Returns a zero balance if the principal does not currently hold the token.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/balances/ft/{asset_identifier}":{"get":{"operationId":"get_principal_balance_ft","summary":"Get principal FT balance","tags":["Accounts"],"description":"Get a principal's balance of a single fungible token. Returns a zero balance if the principal does not currently hold the token.","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},{"schema":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}::[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*]){0,127}$","title":"Asset Identifier","type":"string"},"in":"path","name":"asset_identifier","required":true,"description":"Asset Identifier"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"PrincipalFtPosition","type":"object","required":["asset_identifier","balance"],"properties":{"asset_identifier":{"description":"Fungible token asset identifier","type":"string"},"balance":{"description":"The principal's balance of this token, as a string-quoted integer in base units","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 NFT balances

> Get the non-fungible token instances currently owned by a principal, ordered by asset identifier and value. Optionally filtered to a single asset class via \`asset\_identifier\`.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/balances/nft":{"get":{"operationId":"get_principal_balances_nft","summary":"Get principal NFT balances","tags":["Accounts"],"description":"Get the non-fungible token instances currently owned by a principal, ordered by asset identifier and value. Optionally filtered to a single asset class via `asset_identifier`.","parameters":[{"schema":{"minimum":1,"default":100,"maximum":200,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^0x[0-9a-fA-F]*:.+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating NFT balances (sorted by asset identifier then value). Format: value:asset_identifier"},{"schema":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}\\.[a-zA-Z]([a-zA-Z0-9]|[-_]){0,39}::[a-zA-Z]([a-zA-Z0-9]|[-_!?+<>=/*]){0,127}$","title":"Asset Identifier","type":"string"},"in":"query","name":"asset_identifier","required":false,"description":"Return only the instances of this non-fungible token asset class. For example, BNS names are held as `SP000000000000000000002Q6VF78.bns::names` on mainnet."},{"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":"^0x[0-9a-fA-F]*:.+$","description":"Cursor for paginating NFT balances (sorted by asset identifier then value). Format: value:asset_identifier","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^0x[0-9a-fA-F]*:.+$","description":"Cursor for paginating NFT balances (sorted by asset identifier then value). Format: value:asset_identifier","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^0x[0-9a-fA-F]*:.+$","description":"Cursor for paginating NFT balances (sorted by asset identifier then value). Format: value:asset_identifier","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"PrincipalNftPosition","type":"object","required":["asset_identifier","value"],"properties":{"asset_identifier":{"description":"Non-fungible token asset identifier","type":"string"},"value":{"description":"The NFT instance identifier, as a Clarity value","type":"object","required":["hex","repr"],"properties":{"hex":{"type":"string"},"repr":{"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 nonces

> Get a Stacks account's latest nonce state by inspecting its confirmed transactions and the mempool, including the nonce to use for its next transaction. Only standard principals have nonces; contract principals are not valid.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Accounts","description":"Read-only endpoints to obtain Stacks account details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/principals/{principal}/nonces":{"get":{"operationId":"get_principal_nonces","summary":"Get principal nonces","tags":["Accounts"],"description":"Get a Stacks account's latest nonce state by inspecting its confirmed transactions and the mempool, including the nonce to use for its next transaction. Only standard principals have nonces; contract principals are not valid.","parameters":[{"schema":{"pattern":"^[0123456789ABCDEFGHJKMNPQRSTVWXYZ]{28,41}$","title":"Stacks Address","type":"string"},"in":"path","name":"principal","required":true,"description":"Stacks Address"}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"PrincipalNonces","type":"object","required":["next_nonce","last_confirmed_nonce","mempool"],"properties":{"next_nonce":{"description":"The nonce to use for this principal's next transaction, derived from the latest confirmed and mempool nonces. May be inaccurate if the API is not fully synchronized.","type":"integer"},"last_confirmed_nonce":{"anyOf":[{"description":"Highest nonce among the principal's confirmed transactions, or null if none.","type":"integer"},{"type":"null"}]},"mempool":{"title":"PrincipalMempoolNonces","type":"object","required":["last_nonce","pending_nonces","missing_nonces"],"properties":{"last_nonce":{"anyOf":[{"description":"Highest nonce among the principal's pending mempool transactions, or null if none.","type":"integer"},{"type":"null"}]},"pending_nonces":{"description":"Intermediate nonces found in the mempool between the last confirmed nonce and the highest mempool nonce.","type":"array","items":{"type":"integer"}},"missing_nonces":{"description":"Expected intermediate nonces between the last confirmed nonce and the highest mempool nonce that are absent from the mempool — likely stalling transactions.","type":"array","items":{"type":"integer"}}}}}}}}},"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/accounts.md?ask=<question>&goal=<user_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.