Offline replay lesson
A connection is not a current book
Connect, load a fictional snapshot, then update it. Disconnect and reconnect to see why retained prices should stay marked stale until a new snapshot arrives. This is an original state-management lesson, not a live stream or a protocol implementation.
- Connection
- Disconnected
- Snapshot status
- Awaiting snapshot / stale
- Retained bid
- Unavailable
- Retained ask
- Unavailable
Disconnected. No verified snapshot.
On this page
A Polymarket WebSocket integration needs a data-state policy as well as a connection. Receiving a frame does not establish that your displayed book is complete, current or executable. This guide pairs a bounded read-only example with an original offline lesson about retaining and recovering state.
Reviewed October 13, 2026. The linked market stream belongs to the international product. Use our general API guide for the broader API map and our REST book guide and JSON inspector for one snapshot.
Connect to the public market stream
The official real-time reference documents wss://ws-subscriptions-clob.polymarket.com/ws/market, a subscription with type: "market" and assets_ids, and text PING every ten seconds with a PONG response.
Download the read-only Node.js example. It subscribes to one supplied outcome ID and stops after the first matching book or a twenty-second timeout. It accepts an object or array of frames. It does not open a wallet, provide credentials, subscribe to private account updates or submit orders.
node read-polymarket-market-stream.mjs YOUR_OUTCOME_IDThe example uses the built-in Node.js WebSocket; use Node.js 22.4 or newer. Save the request time and selected outcome beside the result. A time-limited reader is useful for inspecting a payload, but it is not a long-running reconnecting client.
Keep outcome IDs as strings
The same official reference distinguishes CTF token IDs from Protocol V2 position IDs. Unified SDK subscriptions use assetIds; the raw market frame examples use asset_id. Do not mix camel-case SDK payloads with raw snake-case frames in one parser without an explicit normalization boundary.
Our suggested integration record includes the market question, outcome label, identifier and product. This is a design convention, not a new venue rule. A precise identity prevents an attractive number from being attached to a different contract merely because titles look similar.
Classify frames before updating the display
The reference shows book, price_change, last_trade_price and tick_size_change events. Additional market events require the documented custom-feature option. An application-level heartbeat reply is text, not a JSON book.
| Input | Original application policy |
|---|---|
| Book snapshot | Check asset identity and shape before replacing book state |
| Price update | Apply only to a seeded state under a tested update contract |
| Last trade | Store separately from current bid and ask |
| Heartbeat | Record connection health without changing price |
| Unknown frame | Preserve a bounded diagnostic; do not invent a quote |
These policies are recommendations for an integration you control. The offline lesson intentionally avoids pretending to implement every live delta field. Before replaying a production order book, test the precise update semantics and ordering guarantees for your selected stream.
Practice snapshot recovery
In the lesson above, an update before a snapshot is ignored. Connect and load the fictional snapshot to seed bid 0.41 and ask 0.45. Update changes the invented values to 0.42 and 0.46. These are educational inputs, not venue observations.
Disconnect retains those values while marking them stale. Reconnect does not make the retained book current. Try updating again: the lesson requires a new snapshot first. That policy makes a recovery boundary visible instead of silently carrying an earlier session into a new one.
Make reconnection an explicit state
For a long-running application, distinguish disconnected, connecting, subscribed and seeded states. Put a cap on retry frequency and preserve cancellation so a closed screen does not leave an unwanted reader running. The downloadable example closes rather than retries; its bounded scope makes inspection easy to audit.
In an original failure scenario, a user’s laptop sleeps while a book changes. On waking, a socket may reconnect while the screen still holds old levels. Displaying “connected” alone hides the missing data interval. A separate snapshot-status label communicates what has actually been recovered.
Connection time is not quote time
A heartbeat says something about the connection. A source timestamp describes a particular payload. A local receipt time records when your process saw it. None of those observations guarantees an order will execute later for a particular size.
Keep a model forecast separate too. Alphascope’s market research pages display AI forecast context. Comparing that estimate with a venue snapshot requires the same outcome and cutoff, plus spread, depth, fees and dated evidence.
A compact integration review
Test non-JSON heartbeats, array frames, another asset’s book, malformed data, early disconnects and the twenty-second deadline. Then test snapshot replacement and recovery separately from transport. A successful connection test is weaker evidence than a confirmed matching frame with validated fields.
For price-level inspection, use the local book inspector. For hypothetical execution depth, use the slippage calculator. Those lessons do not validate account eligibility or send orders.