Polymarket order books and recent trades

When you review a trading idea, you need to know which prices and sizes were available at the time. This actor saves every bid and ask returned by Polymarket's public order-book API, together with recent public trades for the selected tokens. You can capture one snapshot or repeat the collection at a fixed interval to keep a record of how liquidity changes.

Choose a market to include both outcome tokens, or supply token IDs when you want particular books. The actor reads public data without a Polymarket login, wallet key or API key, and it never places orders. A snapshot shows what the API returned, which doesn't tell you whether an order would have filled. Past performance is not a recommendation to trade.

Run the actor

The markets input accepts market slugs and 66-character condition IDs beginning with 0x. Event slugs and URLs won't work, and tokenIds takes decimal strings so JavaScript doesn't round large IDs. The example below selects the October 2026 Fed-rate market for repeated snapshots. If that market has closed, choose an active market because a closed market may have no live book and return unavailable.

{
  "markets": ["will-there-be-no-change-in-fed-interest-rates-after-the-october-2026-meeting-20260617190324031"],
  "tokenIds": [],
  "intervalSeconds": 10,
  "durationMinutes": 1,
  "maxSnapshots": 6,
  "recentTradesLimit": 100
}

For a local run, install the repository dependencies with npm ci at the root and use the commands below. The default dataset holds one row per token for each snapshot round. The actor writes the run summary to storage/key_value_stores/default/OUTPUT.json, and examples/sample-output.json contains a recorded two-token capture.

cd actors/polymarket-orderbook-snapshot
npx apify run --input-file examples/input.json

Read a snapshot

Every row keeps the full CLOB book response, including all returned price levels, the original numeric strings, the book timestamp and its hash. It also calculates bestBid, bestAsk and spread across those levels, then attaches recent market trades filtered to that token without dropping their original fields. The row identifies the token and any known market, records the cycle with UTC request and capture times, and includes errors so an unavailable book can't be mistaken for a valid empty book.

The excerpt below shows the shape of a result with a bid at $0.45 and an ask at $0.55. Those numbers are made up, and the checked-in sample has real values with every returned level. Read each row's status and errors before using its prices or trades.

{
  "cycle": 0,
  "status": "ok",
  "bestBid": 0.45,
  "bestAsk": 0.55,
  "spread": 0.10000000000000003,
  "book": {
    "bids": [{ "price": "0.45", "size": "10" }],
    "asks": [{ "price": "0.55", "size": "8" }]
  },
  "errors": []
}

Timing and coverage

Set durationMinutes to zero for a single round, or use a positive duration to schedule rounds start-to-start every intervalSeconds. Intervals can be between 5 and 60 seconds, with a maximum duration of 60 minutes and up to 1,000 rounds per run. Inputs must resolve to no more than 100 tokens, each of which can produce a row in every round. Slow requests can delay the schedule, and a round already underway may finish after the duration ends. The actor reads tokens one after another, so a round isn't a single instant view of the market.

The recentTradesLimit input requests between 0 and 500 market rows per round. The actor fetches those trades once per condition, then filters them by token, so a token can have fewer trades than the requested limit. Repeated snapshots can overlap, and takerOnly=false means the public response may include both participants in a trade. Treat it as a sample of recent trades rather than a complete or deduplicated history. It doesn't page back through the wallet feed, so that feed's 10,000-offset cap doesn't come into it.

For a token ID supplied alone, the actor learns its condition ID from the book. If that book is unavailable, it can't discover the token's trades and records the reason, while a known market can still return trades without an available book. HTTP requests use a browser User-Agent and make up to three attempts when an error is retryable, without retaining Cloudflare cookies. Public books and trades can change between any two requests.

Charges and verification

You pay one orderbook-snapshot event for each token row that has a valid book. If the recent-trade request fails, the row is marked partial and still charged, while a row without a book costs nothing. A run stops when the SDK reports that you've hit the event-charge limit. The repository's PUBLISH.md documents pricing and Console setup.

Run npm test from the repository root to check token lookup, full-book preservation and both-outcome collection against controlled API responses. The tests also exercise failed or unrelated responses, repeated snapshot timing and billing limits. Collection uses Gamma's market lookup, the CLOB market and book endpoints, and the public Data API trades endpoint. It doesn't infer fills or simulate market-making returns.