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

# Tokens

Read-only endpoints to obtain STX, fungible token, and non-fungible token details

## Get total STX supply

> Retrieves the total liquid STX supply in micro-STX (µSTX) at the current chain tip: all STX minted (including vesting schedule unlocks) plus matured miner coinbase rewards, minus burned STX.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Tokens","description":"Read-only endpoints to obtain STX, fungible token, and non-fungible token details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/tokens/stx/supply":{"get":{"operationId":"get_stx_total_supply","summary":"Get total STX supply","tags":["Tokens"],"description":"Retrieves the total liquid STX supply in micro-STX (µSTX) at the current chain tip: all STX minted (including vesting schedule unlocks) plus matured miner coinbase rewards, minus burned STX.","responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"StxSupply","type":"object","required":["total","projected_total_2050"],"properties":{"total":{"pattern":"^[0-9]+$","title":"Amount","description":"Total liquid STX supply as a string-quoted integer of micro-STX (µSTX): all STX minted (including vesting schedule unlocks) plus matured miner coinbase rewards, minus burned STX","type":"string"},"projected_total_2050":{"pattern":"^[0-9]+$","title":"Amount","description":"Projected total STX supply in the year 2050, as a string-quoted integer of micro-STX (µSTX).","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 STX holders

> Retrieves the principals holding STX, sorted by balance descending. Balances are the total µSTX held, including any STX locked for stacking — they are not the spendable balance reported as \`available\` by a principal's STX balance.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Tokens","description":"Read-only endpoints to obtain STX, fungible token, and non-fungible token details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/tokens/stx/holders":{"get":{"operationId":"get_stx_holders","summary":"Get STX holders","tags":["Tokens"],"description":"Retrieves the principals holding STX, sorted by balance descending. Balances are the total µSTX held, including any STX locked for stacking — they are not the spendable balance reported as `available` by a principal's STX balance.","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+:\\S+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance: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":200,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^\\d+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^\\d+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^\\d+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"FtHolder","type":"object","required":["principal","balance"],"properties":{"principal":{"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"}]},"balance":{"pattern":"^[0-9]+$","title":"Amount","description":"The holder's balance, as a string-quoted integer in the token's own 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 fungible token holders

> Retrieves the principals holding a given fungible token, sorted by balance descending. Balances are in the token's own base units.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Tokens","description":"Read-only endpoints to obtain STX, fungible token, and non-fungible token details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/tokens/ft/{asset_identifier}/holders":{"get":{"operationId":"get_fungible_token_holders","summary":"Get fungible token holders","tags":["Tokens"],"description":"Retrieves the principals holding a given fungible token, sorted by balance descending. Balances are in the token's own base units.","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+:\\S+$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal"},{"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":{"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+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^\\d+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^\\d+:\\S+$","description":"Cursor for paginating fungible token holders (sorted by balance descending, then holder principal). Format: balance:principal","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"FtHolder","type":"object","required":["principal","balance"],"properties":{"principal":{"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"}]},"balance":{"pattern":"^[0-9]+$","title":"Amount","description":"The holder's balance, as a string-quoted integer in the token's own 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 total fungible token supply

> Retrieves the total supply of a fungible token: the sum of every holder balance, equivalent to the token's mints minus its burns. Returns a zero supply for a token with no recorded balances.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Tokens","description":"Read-only endpoints to obtain STX, fungible token, and non-fungible token details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/tokens/ft/{asset_identifier}/supply":{"get":{"operationId":"get_ft_total_supply","summary":"Get total fungible token supply","tags":["Tokens"],"description":"Retrieves the total supply of a fungible token: the sum of every holder balance, equivalent to the token's mints minus its burns. Returns a zero supply for a token with no recorded balances.","parameters":[{"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":"FtSupply","type":"object","required":["asset_identifier","total"],"properties":{"asset_identifier":{"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","description":"Asset Identifier","type":"string"},"total":{"pattern":"^[0-9]+$","title":"Amount","description":"Total supply of the token, as a string-quoted integer in the token's own 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 non-fungible token history

> Retrieves the event history of a single non-fungible token instance, newest first. Useful for determining an asset's ownership history. Mints have a null \`sender\` and burns a null \`recipient\`. The instance is addressed by a SIP-009 token id, or by its serialized Clarity value when the collection is not keyed by a \`uint\`.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.6.0"},"tags":[{"name":"Tokens","description":"Read-only endpoints to obtain STX, fungible token, and non-fungible token details"}],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/tokens/nft/{asset_identifier}/{value}/history":{"get":{"operationId":"get_nft_instance_history","summary":"Get non-fungible token history","tags":["Tokens"],"description":"Retrieves the event history of a single non-fungible token instance, newest first. Useful for determining an asset's ownership history. Mints have a null `sender` and burns a null `recipient`. The instance is addressed by a SIP-009 token id, or by its serialized Clarity value when the collection is not keyed by a `uint`.","parameters":[{"schema":{"minimum":1,"default":50,"maximum":200,"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":{"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"},{"schema":{"pattern":"^(\\d+|0x[a-fA-F0-9]+)$","title":"NFT instance identifier","type":"string"},"in":"path","name":"value","required":true,"description":"The token instance's identifier, either as a plain integer (a SIP-009 token id, which is serialized as a Clarity `uint`) or as a `0x`-prefixed serialized Clarity value."}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"type":"object","required":["total","limit","cursor","results"],"properties":{"total":{"type":"integer"},"limit":{"minimum":1,"default":50,"maximum":200,"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":"NftHistoryEvent","type":"object","required":["sender","recipient","transaction","block"],"properties":{"sender":{"anyOf":[{"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"}]},{"type":"null"}]},"recipient":{"anyOf":[{"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"}]},{"type":"null"}]},"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"}}}}}}}}}}},"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/tokens.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.