Order Book (CLOB) Data Storage Format

Polymarket order book data are stored in text files.

The storage format is TSV (tab-separated values): one line = one event.

---

Each line in a file consists of two parts separated by a tab character:

<capture_timestamp_ms>    <json_payload>

• capture_timestamp_ms — time when the event was written to the file, in Unix epoch milliseconds (UTC).

• json_payload — a JSON object or JSON array containing the event data.

Important:

• capture_timestamp_ms is the file write time.

• The timestamp field inside the JSON is the event time from the data source.

Event Types (event_type)

Each message contains the field:

• event_type — string identifier of the event type.

Supported event types:

• book

• price_change

• last_trade_price

• best_bid_ask

• new_market

• market_resolved

• tick_size_change

Data Representation

• All identifiers (market, asset_id, id) are stored as strings.

• All numeric price and volume values (price, size, best_bid, best_ask, spread) are stored as strings in decimal representation.

• Timestamps inside JSON are Unix epoch milliseconds (UTC).

• Each line in the file is self-contained and can be processed independently.

1. book — Full Order Book Snapshot

The message contains the complete order book state for a single asset_id.

• event_type — "book".

• market — market identifier (hex string starting with 0x).

• asset_id — outcome token identifier (string).

• timestamp — snapshot generation time in Unix epoch milliseconds.

• hash — snapshot version identifier.

• bids — array of bid levels.

• asks — array of ask levels.

• last_trade_price — last traded price for this asset_id.

Structure of bids / asks Elements

Each level is an object with:

• price — level price (decimal string).

• size — total size at the level (decimal string).

bids — buy orders (from best to worst).

asks — sell orders (from best to worst).

---

2. price_change — Order Book Level Updates

The message contains a set of updates for a single market.

• event_type — "price_change".

• market — market identifier.

• timestamp — event time in Unix epoch milliseconds.

• price_changes — array of changes.

Structure of price_changes Elements

• asset_id — outcome token to which the change applies.

• price — level price (string).

• size — size change at this level (string).

• side — side of the book:

  • "BUY" — bid side,

  • "SELL" — ask side.

• hash — change identifier.

• best_bid — current best bid after the update.

• best_ask — current best ask after the update.

---

3. last_trade_price — Last Trade Price

Message updating the last traded price.

• event_type — "last_trade_price".

• market — market identifier.

• asset_id — outcome token.

• price — last trade price (string).

• timestamp — event time in Unix epoch milliseconds.

---

4. best_bid_ask — Best Prices and Spread

Message containing the current best prices.

• event_type — "best_bid_ask".

• market — market identifier.

• asset_id — outcome token.

• best_bid — best bid price (string).

• best_ask — best ask price (string).

• spread — difference between best_ask and best_bid.

• timestamp — event time in Unix epoch milliseconds.

---

5. new_market — New Market

Message announcing the creation of a new market.

• event_type — "new_market".

• id — internal market identifier.

• question — market title/question.

• market — market identifier (0x...).

• slug — string market identifier.

• description — market rules/description.

• asset_ids — array of outcome tokens (strings).

• outcomes — array of outcome names.

• timestamp — event time in Unix epoch milliseconds.

• tags — array of tags (may be empty).

• event_message — nested object with extended market information.

---

6. market_resolved — Market Resolved

Message indicating market completion and the winning outcome.

• event_type — "market_resolved".

• id — market identifier.

• question — market title.

• market — market identifier (0x...).

• slug — market slug.

• winning_outcome — name of the winning outcome.

• winning_asset_id — asset_id of the winning outcome token.

• timestamp — event time in Unix epoch milliseconds.

---

7. tick_size_change — Tick Size Update

Message indicating a change in the minimum price tick size for an asset_id.

• event_type — "tick_size_change".

• market — market identifier.

• asset_id — outcome token.

• old_tick_size — previous tick size.

• new_tick_size — new tick size.

• timestamp — event time in Unix epoch milliseconds.