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

# Subscriptions & markets

> Reference a market with MarketStream, then subscribe, unsubscribe, and list

A subscription is one `(market, channel)` pair on a connection. You create them
with `subscribe`, name the market with a `MarketStream`, and the server hands
back a `subscriptionId` that keys every frame that follows.

## `MarketStream`

How you reference a market on the wire. It's a discriminated union on `venue` —
you build it from venue-native identifiers you already have, or that you get
from the [Markets API](/api-reference/markets/search-markets).

<CodeGroup>
  ```json Polymarket theme={null}
  {
    "venue": "polymarket",
    "outcomeId": "71045620195867637"
  }
  ```

  ```json Limitless CLOB theme={null}
  {
    "venue": "limitless",
    "kind": "clob",
    "marketId": "btc-100k-weekly",
    "outcomeId": "84329471234058196"
  }
  ```
</CodeGroup>

| Field       | Venue      | Meaning                                                                                                                                                                                                     |
| ----------- | ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `outcomeId` | polymarket | ERC-1155 token id of the outcome side (already outcome-specific).                                                                                                                                           |
| `kind`      | limitless  | `"clob"` for orderbook markets. (`"amm"` is reserved; not yet streamable.)                                                                                                                                  |
| `marketId`  | limitless  | Market slug.                                                                                                                                                                                                |
| `outcomeId` | limitless  | Outcome token id of the side you want — the same value the Markets API returns as the outcome's `outcomeId`. Must be one of the slug's two outcome tokens; anything else is rejected with `UNKNOWN_MARKET`. |

<Note>
  Limitless YES and NO are two views of one shared orderbook — the NO book is the
  exact complement of the YES book. One slug covers both sides; you subscribe to
  YES and NO as two separate `MarketStream` entries, one per token. You can
  subscribe to either or both; both stream accurately.
</Note>

## Channels

| Channel | Status                | Delivers                                                                                                                                                                                                                                                      |
| ------- | --------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `book`  | **Live**              | [`snapshot`](/streaming/orderbook#snapshot-and-delta) then [`delta`](/streaming/orderbook#snapshot-and-delta) frames — the orderbook. This is the default when `channels` is omitted.                                                                         |
| `trade` | **Live** (Polymarket) | [`trade`](/streaming/trades) frames — the market's public trade tape, one frame per fill, from the moment you subscribe. Limitless does not publish a public trade feed, so a `trade` subscribe on a Limitless market is rejected with `UNSUPPORTED_CHANNEL`. |

A subscription is one `(market, channel)` pair. Subscribing to one market on
both channels counts as two subscriptions against the
[per-connection cap](/streaming/connection#connection-limits).

## `subscribe`

```json theme={null}
{
  "type": "subscribe",
  "markets": [ { "venue": "polymarket", "outcomeId": "71045620195867637" } ],
  "channels": ["book"],
  "requestId": "01HZX0RJQ4Z6K7Y9V2N0WP3M8C"
}
```

| Field       | Required | Notes                                                                     |
| ----------- | -------- | ------------------------------------------------------------------------- |
| `markets`   | yes      | Array of `MarketStream`. One `subscribed` **or** `error` reply per entry. |
| `channels`  | no       | Defaults to `["book"]`.                                                   |
| `requestId` | no       | Echoed on connection-level error replies for this call.                   |

For each market in the batch you get back **either** a `subscribed` ack **or**
an `error` (for example, `UNKNOWN_MARKET`) — one reply per market, so a single
bad entry never sinks the rest of the batch.

```json theme={null}
{
  "type": "subscribed",
  "v": 1,
  "serverTimestamp": 1748020034200,
  "market": { "venue": "polymarket", "outcomeId": "71045620195867637" },
  "channel": "book",
  "subscriptionId": "f47ac10b-58cc-4372-a567-0e02b2c3d479",
  "snapshotPending": true
}
```

Cache the mapping from `subscriptionId` to whatever local state you keep for
that market — every subsequent frame for this subscription is keyed by that id,
and it's also the handle you pass to [`unsubscribe`](#unsubscribe).
`snapshotPending: true` tells you a `snapshot` is on its way (it is always
`false` on the trade channel — the tape has no snapshot).

Subscribing is idempotent per `(connection, market, channel)`: a repeat returns
the existing `subscriptionId` rather than creating a second one.

## `unsubscribe`

```json theme={null}
{ "type": "unsubscribe", "subscriptionIds": ["f47ac10b-58cc-4372-a567-0e02b2c3d479"], "requestId": "…" }
```

Unsubscribe by the `subscriptionId`(s) from prior `subscribed` acks. One
`unsubscribed` reply per id, carrying `subscriptionId`, `market`, and `channel`.

## `list`

```json theme={null}
{ "type": "list", "requestId": "…" }
```

Returns a `subscriptions` frame: one atomic snapshot of every active
subscription on this connection.