> 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-blocks.md).

# Bitcoin Blocks

## Get Bitcoin blocks

> Retrieves canonical Bitcoin blocks, newest first. Each block carries its header time once the API has learned it from a Stacks block anchored to it, an interpolated time for a past block no Stacks block anchored to, and a projected time for the newest blocks no Stacks block has anchored to yet.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.10.0"},"tags":[],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/bitcoin-blocks":{"get":{"operationId":"get_bitcoin_blocks","summary":"Get Bitcoin blocks","tags":["Bitcoin Blocks"],"description":"Retrieves canonical Bitcoin blocks, newest first. Each block carries its header time once the API has learned it from a Stacks block anchored to it, an interpolated time for a past block no Stacks block anchored to, and a projected time for the newest blocks no Stacks block has anchored to yet.","parameters":[{"schema":{"minimum":1,"default":20,"maximum":30,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0-9]{1,10}$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating Bitcoin blocks (sorted by height, descending). Format: height"}],"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":30,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Bitcoin blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Bitcoin blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Bitcoin blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"BitcoinBlock","type":"object","required":["height","hash","time","time_iso","projected_time","projected_time_iso","stacks_block_count","tx_count"],"properties":{"height":{"description":"Height of the Bitcoin block","type":"integer"},"hash":{"description":"Hash of the Bitcoin block; `null` for a future block that has not been mined.","anyOf":[{"type":"string"},{"type":"null"}]},"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 the 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). Set for a future block, and for the newest mined blocks whose time the API has not learned yet (no Stacks block has anchored to them); `null` whenever `time` is set, 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"}]},"stacks_block_count":{"description":"Number of canonical Stacks blocks anchored to this Bitcoin block. `0` for a block no Stacks block anchored to (e.g. a missed sortition), one too new to have any yet, and a future block.","type":"integer"},"tx_count":{"description":"Number of transactions in the canonical Stacks blocks anchored to this Bitcoin block","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"}}}}}}}}}}}
```

## Get Bitcoin block

> Retrieves a single canonical Bitcoin block, by height, hash, or \`latest\`, with its time (see the Bitcoin blocks list). A height above the Bitcoin tip returns the future block with no hash and its projected time.

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.10.0"},"tags":[],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/bitcoin-blocks/{height_or_hash}":{"get":{"operationId":"get_bitcoin_block","summary":"Get Bitcoin block","tags":["Bitcoin Blocks"],"description":"Retrieves a single canonical Bitcoin block, by height, hash, or `latest`, with its time (see the Bitcoin blocks list). A height above the Bitcoin tip returns the future block with no hash and its projected time.","parameters":[{"schema":{"anyOf":[{"type":"string","enum":["latest"]},{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},{"title":"Block height","description":"Block height","minimum":0,"maximum":2147483647,"type":"integer"}]},"in":"path","name":"height_or_hash","required":true}],"responses":{"200":{"description":"Default Response","content":{"application/json":{"schema":{"title":"BitcoinBlock","type":"object","required":["height","hash","time","time_iso","projected_time","projected_time_iso","stacks_block_count","tx_count"],"properties":{"height":{"description":"Height of the Bitcoin block","type":"integer"},"hash":{"description":"Hash of the Bitcoin block; `null` for a future block that has not been mined.","anyOf":[{"type":"string"},{"type":"null"}]},"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 the 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). Set for a future block, and for the newest mined blocks whose time the API has not learned yet (no Stacks block has anchored to them); `null` whenever `time` is set, 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"}]},"stacks_block_count":{"description":"Number of canonical Stacks blocks anchored to this Bitcoin block. `0` for a block no Stacks block anchored to (e.g. a missed sortition), one too new to have any yet, and a future block.","type":"integer"},"tx_count":{"description":"Number of transactions in the canonical Stacks blocks anchored to this Bitcoin block","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"}}}}}}}}}}}
```

## Get Bitcoin block Stacks blocks

> Retrieves the summaries of the canonical Stacks blocks confirmed by a single canonical Bitcoin block, newest first

```json
{"openapi":"3.0.3","info":{"title":"Stacks Blockchain API","version":"9.10.0"},"tags":[],"servers":[{"url":"https://api.hiro.so/","description":"mainnet"}],"paths":{"/extended/v3/bitcoin-blocks/{height_or_hash}/blocks":{"get":{"operationId":"get_bitcoin_block_stacks_blocks","summary":"Get Bitcoin block Stacks blocks","tags":["Bitcoin Blocks"],"description":"Retrieves the summaries of the canonical Stacks blocks confirmed by a single canonical Bitcoin block, newest first","parameters":[{"schema":{"minimum":1,"default":20,"maximum":30,"type":"integer"},"in":"query","name":"limit","required":false,"description":"Number of results per page"},{"schema":{"pattern":"^[0-9]{1,10}$","type":"string"},"in":"query","name":"cursor","required":false,"description":"Cursor for paginating Stacks blocks (sorted by height, descending). Format: height"},{"schema":{"anyOf":[{"type":"string","enum":["latest"]},{"pattern":"^(0x)?[a-fA-F0-9]{64}$","title":"Block hash","description":"Block hash","type":"string"},{"title":"Block height","description":"Block height","minimum":0,"maximum":2147483647,"type":"integer"}]},"in":"path","name":"height_or_hash","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":30,"description":"Number of results per page","type":"integer"},"cursor":{"type":"object","required":["next","previous","current"],"properties":{"next":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Stacks blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]},"previous":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Stacks blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]},"current":{"anyOf":[{"pattern":"^[0-9]{1,10}$","description":"Cursor for paginating Stacks blocks (sorted by height, descending). Format: height","type":"string"},{"type":"null"}]}}},"results":{"type":"array","items":{"title":"BlockSummary","type":"object","required":["height","hash","index_hash","time","time_iso","tenure_height","tx_count","bitcoin_block"],"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"},"tenure_height":{"description":"The tenure height (AKA coinbase height) of this block. Before Nakamoto every block was its own tenure, so this is the block height. `null` for a Nakamoto block indexed before tenure heights were recorded.","anyOf":[{"type":"integer"},{"type":"null"}]},"tx_count":{"description":"Number of transactions included in the block","type":"integer"},"bitcoin_block":{"type":"object","required":["height","hash"],"properties":{"height":{"description":"Height of the Bitcoin block this block is anchored to","type":"integer"},"hash":{"description":"Hash of the Bitcoin block this block is anchored to","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"}}}}}}}}}}}
```


---

# 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/bitcoin-blocks.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.
