> For the complete documentation index, see [llms.txt](https://docs.hydromancer.xyz/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.hydromancer.xyz/readme/rest-api/market-data/l2book.md).

# l2Book

### Overview

The `l2Book` endpoint returns L2 orderbook snapshots — aggregated price levels with total size and order count at each level. Supports optional price aggregation via significant figures and mantissa parameters.

**Key details:**

* Depth-20 snapshots (top 20 bids and asks)
* Refreshed once per second
* Supports price aggregation (`nSigFigs`, `mantissa`)
* Returns zstd-compressed msgpack

### Request

**Endpoint:** `POST /info`

**Single coin:**

```json
{
    "type": "l2Book",
    "coin": "ETH"
}
```

**Multiple coins:**

```json
{
    "type": "l2Book",
    "coins": ["ETH", "BTC", "SOL"]
}
```

**With aggregation:**

```json
{
    "type": "l2Book",
    "coin": "BTC",
    "nSigFigs": 5,
    "mantissa": 2
}
```

**Parameters:**

| Parameter  | Type      | Required | Description                                                          |
| ---------- | --------- | -------- | -------------------------------------------------------------------- |
| `coin`     | string    | No\*     | Single coin to fetch. Outcome markets (`"#2870"` etc.) are accepted. |
| `coins`    | string\[] | No\*     | Multiple coins to fetch. Outcome markets are accepted.               |
| `nSigFigs` | number    | No       | Aggregate price levels to N significant figures (2-5).               |
| `mantissa` | number    | No       | Snap to mantissa step (2 or 5). Only valid when `nSigFigs=5`.        |

\* Either `coin` or `coins` must be provided. This endpoint has no all-markets / firehose mode — use [`l2BookDiffSnapshot`](/readme/rest-api/market-data/l2bookdiffsnapshot.md) for that.

### Response

**Headers:**

* `Content-Type: application/octet-stream`
* `Content-Encoding: zstd`

**Format:** Zstd-compressed msgpack `L2BookSnapshot`:

```json
{
    "coin": "ETH",
    "time": 1704067200000,
    "levels": [
        [
            {"px": "3245.5", "sz": "12.4", "n": 3},
            {"px": "3244.0", "sz": "8.7", "n": 5}
        ],
        [
            {"px": "3246.0", "sz": "6.2", "n": 2},
            {"px": "3247.5", "sz": "15.3", "n": 4}
        ]
    ],
    "height": 782007304
}
```

For multiple coins, each snapshot is returned as a separate zstd-compressed msgpack blob.

### Field reference

| Field           | Type   | Description                                               |
| --------------- | ------ | --------------------------------------------------------- |
| `coin`          | string | Market symbol                                             |
| `time`          | number | Block timestamp (milliseconds since epoch)                |
| `levels`        | array  | Tuple of `[bids, asks]`. Bids descending, asks ascending. |
| `levels[][].px` | string | Price as decimal string                                   |
| `levels[][].sz` | string | Total size at this price level                            |
| `levels[][].n`  | number | Number of orders at this level                            |
| `height`        | number | Block height of this snapshot                             |

### Common errors

* **400**: Missing or invalid `coin`/`coins` parameter
* **400**: Invalid `nSigFigs` (must be 2-5) or `mantissa` (must be 2 or 5 with `nSigFigs=5`)
* **403**: Permission denied - check API key
* **404**: No snapshot available yet
* **429**: Rate limit exceeded