> ## Documentation Index
> Fetch the complete documentation index at: https://docs.struct.to/llms.txt
> Use this file to discover all available pages before exploring further.

# Liquidity

> Stream real-time USD order-book liquidity for positions, markets, and events.

<Note>
  **Room IDs:** `polymarket_position_liquidity`, `polymarket_market_liquidity`, `polymarket_event_liquidity` \
  **Endpoint:** `wss://api.struct.to/ws` \
  **Rate:** 0.001 credits per message
</Note>

Stream real-time USD order-book liquidity at three granularities. Each room pushes an update whenever the relevant liquidity changes.

| Room ID                         | Granularity                                              | Filter (optional) |
| ------------------------------- | -------------------------------------------------------- | ----------------- |
| `polymarket_position_liquidity` | Per outcome token (position)                             | `position_ids`    |
| `polymarket_market_liquidity`   | Per market (condition), summed across its outcome tokens | `condition_ids`   |
| `polymarket_event_liquidity`    | Per event, summed across its markets                     | `event_slugs`     |

All three rooms share the same subscribe flow, acknowledgement shape, and event fields. Liquidity is reported in USD as `liquidity_usd`, and `liquidity_updated_at` is a Unix-millisecond timestamp.

## Subscribe

Filters are optional. Omit the identifier array (or send an empty one) to receive every update for that granularity (a firehose). When provided, each room accepts up to 500 identifiers. Update a subscription at any time by sending another `subscribe` message, and stop it with `action: "unsubscribe_all"`.

### Filters

| Room                            | Filter          | Type       | Description                                                                        |
| ------------------------------- | --------------- | ---------- | ---------------------------------------------------------------------------------- |
| `polymarket_position_liquidity` | `position_ids`  | `string[]` | ERC-1155 outcome token IDs (decimal or hex). Empty or omitted means all positions. |
| `polymarket_market_liquidity`   | `condition_ids` | `string[]` | 64-char hex market IDs. Empty or omitted means all markets.                        |
| `polymarket_event_liquidity`    | `event_slugs`   | `string[]` | Event slugs. Empty or omitted means all events.                                    |

### Example

```json theme={null}
{
  "type": "join_room",
  "payload": {
    "room_id": "polymarket_market_liquidity"
  }
}
```

```json theme={null}
{
  "type": "room_message",
  "payload": {
    "room_id": "polymarket_market_liquidity",
    "message": {
      "action": "subscribe",
      "condition_ids": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"]
    }
  }
}
```

### Response

All three rooms acknowledge with the same `liquidity_stream_subscribe_response` envelope. `data.ids` echoes the accepted filter values (empty for a firehose subscription), and `data.rejected` lists any identifiers that failed validation.

```json theme={null}
{
  "type": "liquidity_stream_subscribe_response",
  "room_id": "polymarket_market_liquidity",
  "data": {
    "ids": ["0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef"],
    "rejected": []
  }
}
```

## Events

Each room emits a single update object (not a batch) whenever liquidity changes. Every event carries `liquidity_usd` (current USD order-book liquidity) and `liquidity_updated_at` (Unix milliseconds).

### `position_liquidity_update`

Latest USD liquidity for one outcome token, from `polymarket_position_liquidity`.

```json theme={null}
{
  "type": "position_liquidity_update",
  "room_id": "polymarket_position_liquidity",
  "data": {
    "position_id": "12345678901234567",
    "liquidity_usd": 42250.75,
    "liquidity_updated_at": 1743500000000
  }
}
```

| Field                  | Type     | Description                                |
| ---------------------- | -------- | ------------------------------------------ |
| `position_id`          | `string` | ERC-1155 outcome token ID (decimal string) |
| `liquidity_usd`        | `number` | Order-book liquidity in USD                |
| `liquidity_updated_at` | `int`    | Update timestamp (Unix milliseconds)       |

### `market_liquidity_update`

Total USD liquidity for one market, summed across its outcome tokens, from `polymarket_market_liquidity`.

```json theme={null}
{
  "type": "market_liquidity_update",
  "room_id": "polymarket_market_liquidity",
  "data": {
    "condition_id": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
    "liquidity_usd": 128400.0,
    "liquidity_updated_at": 1743500000000
  }
}
```

| Field                  | Type     | Description                          |
| ---------------------- | -------- | ------------------------------------ |
| `condition_id`         | `string` | 64-char hex condition ID             |
| `liquidity_usd`        | `number` | Total order-book liquidity in USD    |
| `liquidity_updated_at` | `int`    | Update timestamp (Unix milliseconds) |

### `event_liquidity_update`

Total USD liquidity for one event, summed across its markets, from `polymarket_event_liquidity`.

```json theme={null}
{
  "type": "event_liquidity_update",
  "room_id": "polymarket_event_liquidity",
  "data": {
    "event_slug": "bitcoin-price-markets",
    "liquidity_usd": 512900.0,
    "liquidity_updated_at": 1743500000000
  }
}
```

| Field                  | Type     | Description                          |
| ---------------------- | -------- | ------------------------------------ |
| `event_slug`           | `string` | Event slug                           |
| `liquidity_usd`        | `number` | Total order-book liquidity in USD    |
| `liquidity_updated_at` | `int`    | Update timestamp (Unix milliseconds) |