<!-- source: https://secondlayer.tools/docs/api-reference#list-canonical-blocks -->

## Canonical block-hash map

`GET /v1/index/canonical`

One row per height on the canonical chain, oldest first. Orphaned blocks never appear, so you can check your own chain against it. Lean by design; `/v1/index/blocks` is the full block. Not metered.

### Range and paging

| Name | Type | Description |
| --- | --- | --- |
| `limit` | integer · 1 to 1000 | Page size; capped at 1000. |
| `cursor` | string | `<block_height>:<event_index>` from a previous page's `next_cursor`. Resumes after it. |
| `from_cursor` | string | Same as `cursor`. Mutually exclusive with it and with `from_height`. |
| `from_height` | integer | First block height to read. Mutually exclusive with a cursor. With neither, the read starts one day behind the tip. |
| `to_height` | integer | Last block height to read, inclusive. |

### Returns

A cursor envelope; `canonical` holds `CanonicalBlock` objects.

### Responses

- `200` Cursor-paginated envelope
- `400` A parameter, filter, cursor or body field was refused; `code` says which
- `401` This bind requires the instance token, and it was missing or wrong
- `429` Rate limited; retry after `Retry-After` seconds

### Example

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

```json
{
  "canonical": [
    {
      "cursor": "9048503:0",
      "block_height": 9048503,
      "block_hash": "0x5560590afefe994adbe2188586a44ba3668e8964a7e64bb137c0df216531da0c",
      "parent_hash": "0x2a20974330e301b65086d3cde9b0006c9b7471479ba9a3fc2ca72621479655cc",
      "burn_block_height": 968276,
      "burn_block_hash": "0x000000000000000000019d25cd76d06a9eea796a906ac88300cd70fd70ccdb57"
    }
  ],
  "next_cursor": "7960000:42",
  "tip": {
    "block_height": 9048690,
    "finalized_height": 9048457,
    "lag_seconds": 4,
    "source_block_height": 9048692
  }
}
```