> ## Documentation Index
> Fetch the complete documentation index at: https://docs.polymarket.com/llms.txt
> Use this file to discover all available pages before exploring further.
# Book
> Perps WebSocket order book updates.
The book channel pushes a full snapshot every 100 ms for each subscribed
instrument. Subscribe to `book::{iid}` for the top 20 bid and ask levels, or
opt in to `book::{iid}::50` for the top 50 levels per side. The 50-level form
provides deeper order book visibility than the default snapshot.
Each push replaces the prior state; it is not a delta. Levels in `data.b` are
sorted from highest to lowest price, and levels in `data.a` are sorted from
lowest to highest price. If a side has fewer levels than the selected depth,
the snapshot includes all available levels on that side.
Allowed depths are exactly 20 and 50. `book::{iid}::20` is an alias of
`book::{iid}`; updates for either subscription use the canonical
`ch: "book::{iid}"`. Updates for `book::{iid}::50` use
`ch: "book::{iid}::50"`. Other suffixes are rejected like any unknown channel
with `{"status":"err","error":"invalid channel"}` in the response `data`
array. You can subscribe to both depths on one connection, and each counts as
one subscription toward the per-connection limit.
## AsyncAPI
````yaml asyncapi-perps.json book
id: book
title: Book
description: >-
Order book snapshot updates (top 20 or, with the ::50 suffix, top 50 levels
per side). Pushed every 100ms.
servers:
- id: production
protocol: wss
host: ws.perpetuals.polymarket.com
bindings: []
variables: []
address: /v1/ws
parameters: []
bindings: []
operations:
- &ref_1
id: BookSubscribe
title: Book subscribe
description: Subscribe to book
type: receive
messages:
- &ref_6
id: SubscribeRequest
contentType: application/json
payload:
- name: Subscribe
description: Subscribe to order book updates for an instrument
type: object
properties:
- name: id
type: integer
description: Client-supplied identifier used to correlate the response.
required: false
- name: req
type: string
description: Request type
enumValues:
- post
- sub
- unsub
required: true
- name: chs
type: array
description: >-
Book subscription in format "book::{iid}" or
"book::{iid}::{depth}". Omitted depth and "20" select the top
20 levels per side; "50" selects the top 50. Allowed depths
are exactly 20 and 50.
required: true
properties:
- name: item
type: string
required: false
headers: []
jsonPayloadSchema:
type: object
title: Base Request
properties:
id:
description: Client-supplied identifier used to correlate the response.
type: integer
x-parser-schema-id:
req:
type: string
description: Request type
enum:
- post
- sub
- unsub
x-parser-schema-id:
chs:
type: array
description: >-
Book subscription in format "book::{iid}" or
"book::{iid}::{depth}". Omitted depth and "20" select the top 20
levels per side; "50" selects the top 50. Allowed depths are
exactly 20 and 50.
items:
type: string
pattern: ^book::\d+(::(20|50))?$
x-parser-schema-id:
example:
- book::1
- book::1::50
x-parser-schema-id:
required:
- req
- chs
description: >
Each inbound request consumes a weighted WebSocket message token.
Before
authentication the budget is per client IP; after authentication all
of
the account's sockets share its tier budget across IPs. The first
valid
signed write also binds an unauthenticated socket to its recovered
account;
later signed writes must resolve that same account. A breach returns
`message_rate_limited` and leaves the socket open.
On gateways configured for concurrent post dispatch, signed write
posts
carrying an `id` may execute and respond out of request order,
matching
the semantics of concurrent HTTP requests. For strict ordering,
await
each response before sending the next request or omit `id` to keep
posts
serial. Use a unique `id` for every in-flight request on a
connection;
uniqueness is not enforced and duplicate in-flight IDs are
ambiguous.
x-parser-schema-id:
title: Subscribe
description: Subscribe to order book updates for an instrument
example: |-
{
"req": "sub",
"chs": [
"book::1",
"book::1::50"
]
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: SubscribeRequest
bindings: []
extensions: &ref_0
- id: x-parser-unique-object-id
value: book
- &ref_3
id: BookSubscribeResponse
title: Book subscribe response
description: Book subscribe response
type: send
messages:
- &ref_8
id: SubscribeResponse
contentType: application/json
payload:
- name: Subscribe Response
description: Response to book subscribe request
type: object
properties:
- name: id
type: integer
description: Correlation ID for request-response matching
required: false
- name: data
type: array
title: Subscribe Response
required: true
properties:
- name: item
type: object
required: false
properties:
- name: status
type: string
enumValues:
- ok
required: true
- name: status
type: string
enumValues:
- err
required: true
- name: error
type: string
description: >-
Error identifier. For domain rejections and transport
errors (`401`/`404`/`429`/`500`) this is a stable,
machine-readable snake_case identifier that is part of
the API contract and safe to branch on, e.g.
`insufficient_margin`, `insufficient_balance`,
`order_not_found`, `reduce_only_invalid`,
`price_outside_bounds`, `position_not_found`,
`position_exists`, `open_orders_exist`,
`invalid_margin_mode`, `invalid_margin_amount`,
`margin_below_required_initial`,
`account_liquidating`, `unauthorized`, `not_found`.
For `400` it is a human-readable validation detail
whose wording may change. See the Error handling guide
for the domain identifiers. (Post-only / Fill-or-Kill
outcomes are order statuses such as
`post_only_rejected`, not rejections.)
required: true
- name: arts
type: integer
description: >-
Gateway arrival timestamp captured at handler entry,
in Unix milliseconds.
required: false
- name: ts
type: integer
description: >-
decision time in Unix milliseconds: terminal event
time for event-backed outcomes, gateway decision time
otherwise
required: false
- name: ref
type: string
description: >-
Unique server-generated rejection reference. Include
this value when asking support to locate the
corresponding structured rejection trace.
required: false
headers: []
jsonPayloadSchema:
type: object
title: Base Response
properties:
id:
type: integer
description: Correlation ID for request-response matching
x-parser-schema-id:
data:
title: Subscribe Response
type: array
items:
oneOf:
- type: object
required:
- status
properties:
status:
type: string
enum:
- ok
x-parser-schema-id:
x-parser-schema-id:
- type: object
required:
- status
- error
properties:
status:
type: string
enum:
- err
x-parser-schema-id:
error:
type: string
description: >-
Error identifier. For domain rejections and transport
errors (`401`/`404`/`429`/`500`) this is a stable,
machine-readable snake_case identifier that is part of
the API contract and safe to branch on, e.g.
`insufficient_margin`, `insufficient_balance`,
`order_not_found`, `reduce_only_invalid`,
`price_outside_bounds`, `position_not_found`,
`position_exists`, `open_orders_exist`,
`invalid_margin_mode`, `invalid_margin_amount`,
`margin_below_required_initial`,
`account_liquidating`, `unauthorized`, `not_found`.
For `400` it is a human-readable validation detail
whose wording may change. See the Error handling guide
for the domain identifiers. (Post-only / Fill-or-Kill
outcomes are order statuses such as
`post_only_rejected`, not rejections.)
example: insufficient_margin
x-parser-schema-id:
arts:
type: integer
description: >-
Gateway arrival timestamp captured at handler entry,
in Unix milliseconds.
example: 1767225600000
x-parser-schema-id:
ts:
type: integer
description: >-
decision time in Unix milliseconds: terminal event
time for event-backed outcomes, gateway decision time
otherwise
example: 1767225600000
x-parser-schema-id:
ref:
type: string
description: >-
Unique server-generated rejection reference. Include
this value when asking support to locate the
corresponding structured rejection trace.
example: g-0011223344556
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
required:
- data
x-parser-schema-id:
title: Subscribe Response
description: Response to book subscribe request
example: |-
{
"data": []
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: SubscribeResponse
bindings: []
extensions: *ref_0
- &ref_2
id: BookUnsubscribe
title: Book unsubscribe
description: Unsubscribe from book
type: receive
messages:
- &ref_7
id: UnsubscribeRequest
contentType: application/json
payload:
- name: Unsubscribe
description: Unsubscribe from order book updates
type: object
properties:
- name: id
type: integer
description: Client-supplied identifier used to correlate the response.
required: false
- name: req
type: string
description: Request type
enumValues:
- post
- sub
- unsub
required: true
- name: chs
type: array
description: >-
Book subscription in format "book::{iid}" or
"book::{iid}::{depth}". Omitted depth and "20" select the top
20 levels per side; "50" selects the top 50. Allowed depths
are exactly 20 and 50.
required: true
properties:
- name: item
type: string
required: false
headers: []
jsonPayloadSchema:
type: object
title: Base Request
properties:
id:
description: Client-supplied identifier used to correlate the response.
type: integer
x-parser-schema-id:
req:
type: string
description: Request type
enum:
- post
- sub
- unsub
x-parser-schema-id:
chs:
type: array
description: >-
Book subscription in format "book::{iid}" or
"book::{iid}::{depth}". Omitted depth and "20" select the top 20
levels per side; "50" selects the top 50. Allowed depths are
exactly 20 and 50.
items:
type: string
pattern: ^book::\d+(::(20|50))?$
x-parser-schema-id:
example:
- book::1
- book::1::50
x-parser-schema-id:
required:
- req
- chs
description: >
Each inbound request consumes a weighted WebSocket message token.
Before
authentication the budget is per client IP; after authentication all
of
the account's sockets share its tier budget across IPs. The first
valid
signed write also binds an unauthenticated socket to its recovered
account;
later signed writes must resolve that same account. A breach returns
`message_rate_limited` and leaves the socket open.
On gateways configured for concurrent post dispatch, signed write
posts
carrying an `id` may execute and respond out of request order,
matching
the semantics of concurrent HTTP requests. For strict ordering,
await
each response before sending the next request or omit `id` to keep
posts
serial. Use a unique `id` for every in-flight request on a
connection;
uniqueness is not enforced and duplicate in-flight IDs are
ambiguous.
x-parser-schema-id:
title: Unsubscribe
description: Unsubscribe from order book updates
example: |-
{
"req": "unsub",
"chs": [
"book::1",
"book::1::50"
]
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: UnsubscribeRequest
bindings: []
extensions: *ref_0
- &ref_4
id: BookUnsubscribeResponse
title: Book unsubscribe response
description: Book unsubscribe response
type: send
messages:
- &ref_9
id: UnsubscribeResponse
contentType: application/json
payload:
- name: Unsubscribe Response
description: Response to book unsubscribe request
type: object
properties:
- name: id
type: integer
description: Correlation ID for request-response matching
required: false
- name: data
type: array
title: Subscribe Response
required: true
properties:
- name: item
type: object
required: false
properties:
- name: status
type: string
enumValues:
- ok
required: true
- name: status
type: string
enumValues:
- err
required: true
- name: error
type: string
description: >-
Error identifier. For domain rejections and transport
errors (`401`/`404`/`429`/`500`) this is a stable,
machine-readable snake_case identifier that is part of
the API contract and safe to branch on, e.g.
`insufficient_margin`, `insufficient_balance`,
`order_not_found`, `reduce_only_invalid`,
`price_outside_bounds`, `position_not_found`,
`position_exists`, `open_orders_exist`,
`invalid_margin_mode`, `invalid_margin_amount`,
`margin_below_required_initial`,
`account_liquidating`, `unauthorized`, `not_found`.
For `400` it is a human-readable validation detail
whose wording may change. See the Error handling guide
for the domain identifiers. (Post-only / Fill-or-Kill
outcomes are order statuses such as
`post_only_rejected`, not rejections.)
required: true
- name: arts
type: integer
description: >-
Gateway arrival timestamp captured at handler entry,
in Unix milliseconds.
required: false
- name: ts
type: integer
description: >-
decision time in Unix milliseconds: terminal event
time for event-backed outcomes, gateway decision time
otherwise
required: false
- name: ref
type: string
description: >-
Unique server-generated rejection reference. Include
this value when asking support to locate the
corresponding structured rejection trace.
required: false
headers: []
jsonPayloadSchema:
type: object
title: Base Response
properties:
id:
type: integer
description: Correlation ID for request-response matching
x-parser-schema-id:
data:
title: Subscribe Response
type: array
items:
oneOf:
- type: object
required:
- status
properties:
status:
type: string
enum:
- ok
x-parser-schema-id:
x-parser-schema-id:
- type: object
required:
- status
- error
properties:
status:
type: string
enum:
- err
x-parser-schema-id:
error:
type: string
description: >-
Error identifier. For domain rejections and transport
errors (`401`/`404`/`429`/`500`) this is a stable,
machine-readable snake_case identifier that is part of
the API contract and safe to branch on, e.g.
`insufficient_margin`, `insufficient_balance`,
`order_not_found`, `reduce_only_invalid`,
`price_outside_bounds`, `position_not_found`,
`position_exists`, `open_orders_exist`,
`invalid_margin_mode`, `invalid_margin_amount`,
`margin_below_required_initial`,
`account_liquidating`, `unauthorized`, `not_found`.
For `400` it is a human-readable validation detail
whose wording may change. See the Error handling guide
for the domain identifiers. (Post-only / Fill-or-Kill
outcomes are order statuses such as
`post_only_rejected`, not rejections.)
example: insufficient_margin
x-parser-schema-id:
arts:
type: integer
description: >-
Gateway arrival timestamp captured at handler entry,
in Unix milliseconds.
example: 1767225600000
x-parser-schema-id:
ts:
type: integer
description: >-
decision time in Unix milliseconds: terminal event
time for event-backed outcomes, gateway decision time
otherwise
example: 1767225600000
x-parser-schema-id:
ref:
type: string
description: >-
Unique server-generated rejection reference. Include
this value when asking support to locate the
corresponding structured rejection trace.
example: g-0011223344556
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
x-parser-schema-id:
required:
- data
x-parser-schema-id:
title: Unsubscribe Response
description: Response to book unsubscribe request
example: |-
{
"data": []
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: UnsubscribeResponse
bindings: []
extensions: *ref_0
- &ref_5
id: BookUpdate
title: Book update
description: Receive book updates
type: send
messages:
- &ref_10
id: Update
contentType: application/json
payload:
- name: Update
description: Real-time order book updates for subscribed instruments
type: object
properties:
- name: ch
type: string
description: >-
Channel name for push data. Parameterized channels include the
instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
"tickers::all"). Private channels use plain names (e.g.
"fills", "orders").
required: true
- name: ts
type: integer
description: Server send time, Unix milliseconds
required: true
- name: ets
type: integer
description: >-
Event timestamp — the newest event this update reflects, in
Unix milliseconds. Distinct from `ts`, which is the server
send time; `ts - ets` is time spent inside the exchange after
the event. `ets=0` means no event horizon is attested, and
consumers must treat the horizon as unknown.
required: true
- name: sq
type: integer
description: Sequence number
required: true
- name: data
type: object
required: true
properties:
- name: b
type: array
description: Bid levels
required: true
properties:
- name: item
type: array
description: |
- `"100.00"` - Price
- `"10.00"` - Quantity
required: false
properties:
- name: item
type: string
required: false
- name: a
type: array
description: Ask levels
required: true
properties:
- name: item
type: array
description: |
- `"100.00"` - Price
- `"10.00"` - Quantity
required: false
properties:
- name: item
type: string
required: false
headers: []
jsonPayloadSchema:
title: Book Update
type: object
properties:
ch:
type: string
description: >-
Channel name for push data. Parameterized channels include the
instrument ID (e.g. "trades::1", "book::1", "klines::1::1m",
"tickers::all"). Private channels use plain names (e.g. "fills",
"orders").
example: trades::1
x-parser-schema-id:
ts:
description: Server send time, Unix milliseconds
type: integer
example: 1767225600000
x-parser-schema-id:
ets:
type: integer
description: >-
Event timestamp — the newest event this update reflects, in Unix
milliseconds. Distinct from `ts`, which is the server send time;
`ts - ets` is time spent inside the exchange after the event.
`ets=0` means no event horizon is attested, and consumers must
treat the horizon as unknown.
example: 1767225600000
x-parser-schema-id:
sq:
type: integer
description: Sequence number
example: 1234567890
x-parser-schema-id:
data:
type: object
required:
- b
- a
properties:
b:
type: array
items:
type: array
items:
type: string
x-parser-schema-id:
maxItems: 2
description: |
- `"100.00"` - Price
- `"10.00"` - Quantity
example:
- '100.00'
- '10.00'
x-parser-schema-id:
description: Bid levels
x-parser-schema-id:
a:
type: array
items:
type: array
items:
type: string
x-parser-schema-id:
maxItems: 2
description: |
- `"100.00"` - Price
- `"10.00"` - Quantity
example:
- '100.00'
- '10.00'
x-parser-schema-id:
description: Ask levels
x-parser-schema-id:
x-parser-schema-id:
required:
- ch
- ts
- ets
- sq
- data
x-parser-schema-id:
title: Update
description: Real-time order book updates for subscribed instruments
example: |-
{
"ch": "book::1",
"ts": 1767225600000,
"ets": 1767225600000,
"sq": 1234567890,
"data": {
"b": [
[
"100.00",
"10.00"
]
],
"a": [
[
"100.00",
"10.00"
]
]
}
}
bindings: []
extensions:
- id: x-parser-unique-object-id
value: Update
bindings: []
extensions: *ref_0
sendOperations:
- *ref_1
- *ref_2
receiveOperations:
- *ref_3
- *ref_4
- *ref_5
sendMessages:
- *ref_6
- *ref_7
receiveMessages:
- *ref_8
- *ref_9
- *ref_10
extensions:
- id: x-parser-unique-object-id
value: book
securitySchemes: []
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.