Skip to content
For the complete documentation index, see llms.txt. This page is also available as Markdown.

Bitcoin Blocks

Get Bitcoin blocks

get

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.

Query parameters
limitinteger · min: 1 · max: 30Optional

Number of results per page

Default: 20
cursorstringOptional

Cursor for paginating Bitcoin blocks (sorted by height, descending). Format: height

Pattern: ^[0-9]{1,10}$
Responses
200

Default Response

application/json
totalintegerRequiredExample: 1
limitinteger · min: 1 · max: 30Required

Number of results per page

Default: 20
get/extended/v3/bitcoin-blocks
GET /extended/v3/bitcoin-blocks HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "height": 1,
      "hash": "text",
      "time": 1,
      "time_iso": "2026-10-08T19:18:41.000Z",
      "projected_time": 1,
      "projected_time_iso": "2027-03-01T08:30:00.000Z",
      "stacks_block_count": 1,
      "tx_count": 1
    }
  ]
}

Get Bitcoin block

get

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.

Path parameters
height_or_hashany ofRequired
string · enumOptionalPossible values:
or
stringOptional

Block hash

Example: 0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c62075133Pattern: ^(0x)?[a-fA-F0-9]{64}$
or
integer · max: 2147483647Optional

Block height

Example: 777678
Responses
200

Default Response

application/json
heightintegerRequired

Height of the Bitcoin block

hashstring · nullableRequired

Hash of the Bitcoin block; null for a future block that has not been mined.

timeinteger · nullableRequired

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.

time_isostring · nullableRequired

The time as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; null with it.

Example: 2026-10-08T19:18:41.000Z
projected_timeinteger · nullableRequired

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.

projected_time_isostring · nullableRequired

The projected_time as an ISO 8601 (YYYY-MM-DDTHH:mm:ss.sssZ) UTC timestamp; null with it.

Example: 2027-03-01T08:30:00.000Z
stacks_block_countintegerRequired

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.

tx_countintegerRequired

Number of transactions in the canonical Stacks blocks anchored to this Bitcoin block

get/extended/v3/bitcoin-blocks/{height_or_hash}
GET /extended/v3/bitcoin-blocks/{height_or_hash} HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
  "height": 1,
  "hash": "text",
  "time": 1,
  "time_iso": "2026-10-08T19:18:41.000Z",
  "projected_time": 1,
  "projected_time_iso": "2027-03-01T08:30:00.000Z",
  "stacks_block_count": 1,
  "tx_count": 1
}

Get Bitcoin block Stacks blocks

get

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

Path parameters
height_or_hashany ofRequired
string · enumOptionalPossible values:
or
stringOptional

Block hash

Example: 0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c62075133Pattern: ^(0x)?[a-fA-F0-9]{64}$
or
integer · max: 2147483647Optional

Block height

Example: 777678
Query parameters
limitinteger · min: 1 · max: 30Optional

Number of results per page

Default: 20
cursorstringOptional

Cursor for paginating Stacks blocks (sorted by height, descending). Format: height

Pattern: ^[0-9]{1,10}$
Responses
200

Default Response

application/json
totalintegerRequiredExample: 1
limitinteger · min: 1 · max: 30Required

Number of results per page

Default: 20
get/extended/v3/bitcoin-blocks/{height_or_hash}/blocks
GET /extended/v3/bitcoin-blocks/{height_or_hash}/blocks HTTP/1.1
Host: api.hiro.so/
Accept: */*
{
  "total": 1,
  "limit": 20,
  "cursor": {
    "next": "text",
    "previous": "text",
    "current": "text"
  },
  "results": [
    {
      "height": 777678,
      "hash": "0xdaf79950c5e8bb0c620751333967cdd62297137cdaf79950c5e8bb0c62075133",
      "index_hash": "text",
      "time": 1,
      "time_iso": "2026-10-08T19:18:41.000Z",
      "tenure_height": 1,
      "tx_count": 1,
      "bitcoin_block": {
        "height": 1,
        "hash": "text"
      }
    }
  ]
}

Last updated

Was this helpful?