<!-- source: https://secondlayer.tools/docs/api-reference#get-streams-canonical-block -->

## Canonical block by height

`GET /v1/streams/canonical/{height}`

The canonical Stacks block at one height and the Bitcoin block it anchors to. Finalized heights are cached for good and answer `If-None-Match` with 304; the `ETag` is the block hash.

### Path parameters

| Name | Type | Description |
| --- | --- | --- |
| `height` | integer, required | Block height (Stacks by default, Bitcoin with chain=bitcoin). |

### Query parameters

| Name | Type | Description |
| --- | --- | --- |
| `chain` | enum | `stacks` (default) is the existing Stacks feed, byte-identical to before. `bitcoin` serves Runes events (rune_etch, rune_mint, rune_transfer, rune_burn — see the RuneStreamsEvent schema) on their own cursor space: a bitcoin cursor only resumes with chain=bitcoin. Stacks-only filters (contract_id, sender, recipient, asset_identifier, filters, clock) 400 on chain=bitcoin; rune and address are bitcoin-only. Values: `stacks`, `bitcoin`. |

### Returns

One `StreamsCanonicalBlock` object.

### Responses

- `200` The canonical block. chain=bitcoin returns a StreamsBitcoinCanonicalBlock (btc block hash, no burn-chain fields) instead.
- `304` Block unchanged since the `ETag` sent in `If-None-Match`
- `400` `height` is not a non-negative integer
- `401` This bind requires the instance token, and it was missing or wrong
- `404` No canonical block at that height yet
- `429` Rate limited on the hosted API (50/s per IP without a key, 10/s on a free key). Self-hosted instances do not throttle Streams. Retry after `Retry-After` seconds

### Example

```bash
curl https://api.secondlayer.tools/v1/streams/canonical/9048876 \
  -H "Authorization: Bearer $SECONDLAYER_API_KEY"
```

```json
{
  "block_height": 9048876,
  "block_hash": "0xba0676b375e8d5fc1495a02847cc3cc32b5f7c2113a5e73999d94ee8d75ebde4",
  "burn_block_height": 968284,
  "burn_block_hash": "0x00000000000000000001b1cadea50180db28922325872c9f16ca19edda3f8bae",
  "is_canonical": true
}
```