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

## State writes

`GET /v1/index/state-writes`

The exact MARF writes each canonical block committed, in the node's write order: every changed leaf of the block's state trie, named. Oldest first; the cursor is `<block_height>:<ordinal>`. `block_height` reads one block. Present only from the height this instance's node subscribed to the `state_writes` observer key, with no earlier history. The window follows the ingest tip. `reorgs` overlaps by height.

### Filters

| Name | Type | Description |
| --- | --- | --- |
| `block_height` | integer | Read one block: the same as `from_height` and `to_height` both set to it, which it excludes. A cursor with it must sit at that height. |
| `contract_id` | string | One contract, `<address>.<contract-name>`: only keys under `vm::<contract_id>::` (its data maps, data vars and token balances). Exact, no wildcards. |
| `tx_context` | boolean | `true` adds the writing transaction's `tx_id`, `tx_sender`, `tx_type`, `tx_status`, `tx_contract_id` and `tx_function_name` to each row; null for block-level writes. |

### Range and paging

| Name | Type | Description |
| --- | --- | --- |
| `limit` | integer · 1 to 1000 | Page size; capped at 1000. |
| `cursor` | string | `<block_height>:<ordinal>` 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; `state_writes` holds `StateWrite` 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/state-writes \
  -H "Authorization: Bearer $SECONDLAYER_API_KEY"
```

```json
{
  "state_writes": [
    {
      "cursor": "100:1",
      "block_height": 100,
      "ordinal": 1,
      "tx_index": 0,
      "key": "vm::ST3FEXKRAY93SR2MERXNSAXWGV9XSDNM1MVEFY5TH.store::0::map::0d0000000568656c6c6f",
      "value_hex": "30313030303030303030303030303030303030303030303030303030303030303031"
    }
  ],
  "next_cursor": "7960000:42",
  "tip": {
    "block_height": 9048690,
    "finalized_height": 9048457,
    "lag_seconds": 4,
    "source_block_height": 9048692
  },
  "reorgs": [
    {
      "id": "3f16c2c5-9551-4ae9-adb0-923668e5c65e",
      "detected_at": "2026-09-15T15:39:38.129Z",
      "fork_point_height": 8996511,
      "old_index_block_hash": "0x45ba0195071488eda13afa66d8ce8612558a739f781be5a032d96332797c4174",
      "new_index_block_hash": "0xa686ff58e7c5ccb26c850a7eaffa7e7274fcbc081c706344eb6f1e1446023df0",
      "orphaned_range": {
        "from": "8996511:0",
        "to": "8996512:2701"
      },
      "new_canonical_tip": "8996511:0"
    }
  ]
}
```