Prediction Market Orderbook Data for Developers: Integration Guide

For production systems that need cross-venue orderbook depth, use a unified, normalized Data API. It eliminates per-venue parsing logic, delivers a consistent schema across Polymarket, Kalshi, and Limitless, and cuts integration time from weeks to hours.

Two paths exist:

• Unified aggregator (recommended for most teams): Single endpoint, normalized L2 schema, snapshot+delta streams, consistent auth. Lower operational cost; no per-venue state machines. Use this unless you need venue-specific order routing or features unavailable through the aggregator.

• Direct venue connections (justified for venue-specific trading): Higher control, access to L3 order records, and venue-native order placement. Engineering cost is proportionally higher: you maintain separate WebSocket consumers, handle on-chain reorgs for CLOB venues, and normalize schemas yourself.

Typical latency differences: centralized venues push updates in under 100ms via WebSocket; on-chain CLOBs add block-confirmation delays that can reach several seconds. Auth models also diverge: centralized APIs use bearer tokens or API keys in request headers, while on-chain venues require wallet signatures or RPC node access.

Immediate next step: Request an API key at Data or open a venue WebSocket directly. The sections below cover schema, endpoints, and production patterns for both paths.

Key Takeaways

A unified, normalized Data API is the lowest-risk, lowest-overhead path to production-grade cross-venue prediction-market orderbook depth.

Table of Contents

• What prediction market orderbooks are and how L2 vs L3 data differs

• How venue architectures differ and what that means for your integration

• REST endpoints, request parameters, and the normalized orderbook schema

• How to build a resilient real-time orderbook consumer

• Pre-trade liquidity checks every bot should run

• Error handling and data integrity under real conditions

• Assymetrix Data API: unified orderbook depth across all major venues

• Developer checklist for any prediction-market orderbook API

• What production integrations actually teach you

• Assymetrix gives developers one integration instead of three

• Sources

• FAQ

What prediction market orderbooks are and how L2 vs L3 data differs

A prediction market orderbook is not a single book. Binary markets, the dominant format on Polymarket, Kalshi, and Limitless, maintain a separate orderbook for each outcome. A “Will Candidate X win?” market has a YES book and a NO book, each with its own bids and asks. That structure changes your data model immediately: where an FX or crypto consumer tracks one book per instrument, a prediction-market consumer tracks two per market, and must join them to compute the full probability surface.

L2 vs L3 semantics determine how much detail you receive per price level.

L2 (aggregated) gives you price levels with cumulative size. Each entry in the bids or asks array represents all resting orders at that price, collapsed into a single quantity. This is sufficient for pre-trade liquidity screening, slippage estimation, and most algorithmic strategies.

L3 (order-level) exposes individual order records: each order has its own ID, size, and nanosecond timestamp. L3 endpoints require authenticated access and typically higher permission scopes. You need L3 when you are reconstructing queue position, detecting iceberg orders, or building a full matching-engine simulation.

Core fields to expect from a prediction-market L2 feed:

The liquidity.within1pct and within5pct fields are pre-computed quoted-liquidity bands. They save you from recalculating depth at runtime and are the primary inputs to pre-trade gating logic.

How venue architectures differ and what that means for your integration

The three major prediction market venues split into two architectural categories, with a third option sitting above both.

On-chain CLOB venues (Polymarket): Orders live on a blockchain. Change detection requires tracking block events or subscribing to sub-streams from a node or indexer. Block confirmation adds latency, and chain reorganizations can invalidate state you already applied. Schema is determined by the smart contract ABI, not a REST spec. Maintaining direct connections to on-chain CLOBs is engineering-intensive because you need event/block tracking alongside normal WebSocket consumers, and reorg handling adds a non-trivial state machine.

Centralized orderbook venues (Kalshi, Limitless): Standard REST + WebSocket APIs, bearer-token auth, and push-based delta streams. Latency is sub-100ms in normal conditions. Schema is documented and versioned. These are far simpler to integrate directly, but each venue has its own field names, price formats, and WebSocket topic structures.

Aggregator/normalized APIs (Assymetrix): Sit above both categories. A single endpoint delivers a consistent schema regardless of the underlying venue type. You pay no per-venue engineering cost and get cross-venue data in one response shape.

The table below maps the dimensions that matter most for integration decisions:

When direct connections are justified: You need to place trades on that specific venue using venue-native order types, or you need L3 order-level data that the aggregator does not expose. Direct connections also make sense for teams that already operate infrastructure for one venue and are not expanding to others.

When an aggregator is preferable: Any system that reads from more than one venue, runs cross-venue arbitrage signals, or needs a consistent schema for downstream analytics. The operational cost of maintaining two or three separate venue consumers, each with its own reconnect logic and schema parser, compounds quickly. See the Kalshi vs Polymarket architecture comparison for a deeper breakdown of the trade-offs.

REST endpoints, request parameters, and the normalized orderbook schema

Snapshot endpoints return a point-in-time L2 book and are designed for live polling or initial state seeding, not for historical range queries. They have no date-range parameter.

Common request parameters:

• depth — number of price levels to return per side (e.g., depth=10 returns the top 10 bids and top 10 asks)

• side — yes or no to request a specific outcome book; omit to receive both

• platform — filter to a specific venue when the endpoint aggregates multiple

Standard request headers:

GET /sdk/markets/{marketId}/orderbook?side=yes&depth=20
Authorization: Bearer YOUR_API_KEY
X-Rate-Limit-Remaining: 95
X-Rate-Limit-Reset: 1720000060

GET /sdk/markets/{marketId}/orderbook?side=yes&depth=20
Authorization: Bearer YOUR_API_KEY
X-Rate-Limit-Remaining: 95
X-Rate-Limit-Reset: 1720000060

A 404 response means the market is not present on that venue or has not been indexed yet. Treat it as a missing-market signal, not a transient error.

Normalized L2 snapshot response (JSON):

{
  "marketId": "will-fed-cut-rates-july-2026",
  "platform": "kalshi",
  "side": "yes",
  "timestamp": "2026-03-15T14:22:01.342Z",
  "hash": "a3f9c12e",
  "bids": [
    { "price": 0.62, "size": 450 },
    { "price": 0.61, "size": 1200 }
  ],
  "asks": [
    { "price": 0.64, "size": 300 },
    { "price": 0.65, "size": 800 }
  ],
  "spread": 0.02,
  "midPrice": 0.63,
  "liquidity": {
    "within1pct": 750,
    "within5pct": 2750
  }
}

{
  "marketId": "will-fed-cut-rates-july-2026",
  "platform": "kalshi",
  "side": "yes",
  "timestamp": "2026-03-15T14:22:01.342Z",
  "hash": "a3f9c12e",
  "bids": [
    { "price": 0.62, "size": 450 },
    { "price": 0.61, "size": 1200 }
  ],
  "asks": [
    { "price": 0.64, "size": 300 },
    { "price": 0.65, "size": 800 }
  ],
  "spread": 0.02,
  "midPrice": 0.63,
  "liquidity": {
    "within1pct": 750,
    "within5pct": 2750
  }
}

Schema normalization is not cosmetic. Some venues return price as an integer in cents (62 for $0.62); others return a decimal string ("0.6200"). Size fields vary between integer contracts and fractional quantities. Mixing these without normalization produces silent precision bugs in P&L and liquidity math. Internally, represent price as a Decimal or BigDecimal type, size as a float, and timestamps as UTC ISO-8601 strings. Never use native floating-point arithmetic for price comparisons.

The Assymetrix snapshot endpoint delivers this normalized shape consistently across venues, including the pre-computed liquidity.within1pct and within5pct bands and the hash field for change detection.

How to build a resilient real-time orderbook consumer

Reliable consumers combine snapshot seeding with delta streams, using sequence IDs or content hashes to verify integrity. The pattern has four stages:

1. Seed from a trusted snapshot. On startup or reconnect, fetch a full L2 snapshot via REST. Store the hash and the highest sequenceId received.

2. Subscribe to the delta stream. Open a WebSocket connection and subscribe to the relevant market topics. Apply each delta in sequence-ID order to your in-memory book.

3. Verify with the content fingerprint. After applying a batch of deltas, recompute the book hash and compare it to the hash field in the next snapshot or the delta’s embedded fingerprint. A mismatch means your state has drifted.

4. Re-seed periodically. Even without detected drift, re-seed from a fresh snapshot every few minutes. This bounds accumulated error from any missed or out-of-order delta.

Sequencing rules:

• Apply deltas strictly in ascending sequence-ID order.

• On a gap (sequence IDs are non-contiguous), discard buffered deltas and request a new snapshot immediately.

• Discard any delta whose sequence ID is less than or equal to the last applied ID.

Connection management:

• Run parallel subscribers: one for top-of-book alerts (low-latency, minimal state), one for full-book reconstruction (higher memory, used for depth screening).

• Reconnect with exponential backoff: start at 250ms, cap at 30 seconds, add random jitter to avoid thundering-herd reconnects.

• On failover to a backup feed, re-seed before resuming delta application. Never assume the backup feed’s sequence IDs continue from the primary’s.

Pro Tip: Batch incoming delta messages into 50ms windows before applying them to the book. This reduces lock contention in multi-threaded consumers and lets you compact redundant updates at the same price level before they hit your state machine. A level updated five times in one batch only needs one write.

For Python-specific implementation patterns, the Assymetrix Python developer guide covers SDK setup and delta reconciliation with working code.

Pre-trade liquidity checks every bot should run

Prediction-market liquidity is thin and event-dependent. The most common reason automated executions fail is not a bad signal: it is sending a marketable order into a book that cannot absorb it at an acceptable price. Depth gating is a higher-yield defense than aggressive order timing.

Depth screening formula:

The liquidity.within1pct field gives you this directly if your provider pre-computes it.

Slippage estimation:

Walk the asks (for a buy) from best ask upward, accumulating size until you reach your target order quantity. The weighted-average fill price minus midPrice, divided by midPrice, is your estimated slippage as a fraction.

slippage = (weighted_avg_fill - midPrice) / midPrice

slippage = (weighted_avg_fill - midPrice) / midPrice

For a sell, walk bids downward from best bid.

Pre-trade gating checklist for bots and algorithmic traders:

• liquidity.within1pct must exceed your minimum threshold (set this per market category; thin event markets may warrant 200 contracts minimum).

• spread must be below your maximum acceptable spread (e.g., reject if spread exceeds 5% of midPrice).

• timestamp age must be under your freshness threshold (reject books older than 10 seconds for fast-moving events).

• Estimated slippage for your order size must be below your cost budget.

• Reject books with asymmetric depth: if the bid side holds less than 20% of the ask side’s within1pct liquidity, the book is one-sided and likely stale or manipulated.

• Reject books where the top-of-book size is more than 80% of total within1pct liquidity. That concentration pattern often indicates a single passive order, not genuine market depth.

Pro Tip: Log every rejected pre-trade check with the reason code and the book state at rejection time. After a week of production data, the rejection distribution tells you which markets are structurally untradeable for your order sizes, and you can exclude them from your signal universe entirely.

Cross-venue arbitrage signal generation depends on these same depth checks running on both legs simultaneously before any order is sent.

Error handling and data integrity under real conditions

Production orderbook consumers fail in predictable ways. Build recovery logic for each of these before you go live.

Common failure modes and recovery patterns:

Missing deltas and sequence gaps trigger an immediate re-seed. Do not attempt to interpolate missing state. Request a fresh snapshot, reset your sequence counter, and resume from there.

Hash mismatches after delta application indicate either a missed delta or a server-side correction. The response is the same: discard current state and re-seed.

Rate-limit 429 responses require exponential backoff with jitter. Read the X-Rate-Limit-Reset header and wait until that epoch before retrying. Never hammer a 429 endpoint with immediate retries.

5xx server errors warrant a circuit breaker. After three consecutive 5xx responses within 60 seconds, stop sending requests to that endpoint for 30 seconds, then retry with a single probe request before resuming normal polling.

Partial market presence is normal in cross-venue systems. A market available on Kalshi may not exist on Polymarket. Handle 404 responses as a missing-market signal and exclude that venue from cross-venue aggregation for that market, rather than treating it as a fatal error.

Data integrity checks to run continuously:

• Verify timestamps are monotonically increasing within a stream. A timestamp regression signals a feed replay or clock skew issue.

• Verify sequence IDs are strictly increasing. Any non-monotonic sequence ID is a gap event.

• Cross-venue reconciliation: if the same market trades on two venues, the midPrice values should be within a reasonable arbitrage band. A divergence beyond that band is either a genuine arbitrage opportunity or a data integrity failure. Log both cases.

Operational metrics to emit: book reconstruction latency, delta application lag, re-seed frequency, rate-limit throttle count per hour, and hash-mismatch rate. A rising re-seed frequency without a corresponding rise in hash mismatches usually means your delta stream is dropping messages upstream.

For sandbox testing, use simulated feeds that replay historical snapshots and inject artificial sequence gaps to verify your recovery logic. The Assymetrix backtesting guide covers replay patterns against the historical dataset.

Assymetrix Data API: unified orderbook depth across all major venues

The Assymetrix Data API at Data delivers a single normalized L2 orderbook feed across Polymarket, Kalshi, and Limitless through one endpoint: /sdk/markets/:id/orderbook.

A minimal GET request looks like this:

GET https://data.assymetrix.com/sdk/markets/will-fed-cut-rates-july-2026/orderbook?side=yes&depth=20
Authorization: Bearer YOUR_API_KEY

GET https://data.assymetrix.com/sdk/markets/will-fed-cut-rates-july-2026/orderbook?side=yes&depth=20
Authorization: Bearer YOUR_API_KEY

The response matches the normalized schema described above: marketId, platform, side, timestamp, hash, bids[], asks[], spread, midPrice, liquidity.within1pct, and liquidity.within5pct. Price is always a decimal, size is always a float, and timestamps are always UTC ISO-8601. No per-venue parsing branches required.

What the API provides beyond raw snapshots:

• Cross-venue normalization: one schema regardless of whether the underlying venue is an on-chain CLOB or a centralized orderbook

• Pre-computed quoted-liquidity bands at ±1% and ±5% of midPrice

• Content fingerprint (hash) on every snapshot for change detection and drift verification

• Snapshot+delta WebSocket streams with sequence IDs

• Historical backfill built on approximately 1.5 terabytes of data spanning nearly one billion rows of trading activity

Cross-venue aggregation changes what you can see. A single-venue dashboard shows you the book on one platform. A normalized feed across Polymarket, Kalshi, and Limitless shows you where order concentration is building across the full market. That cross-venue view is how Smart Money activity becomes detectable before it moves price on any individual venue. Assymetrix surfaces that signal layer alongside the raw orderbook data.

For teams building AI agents that consume prediction market data, the consistent schema eliminates the parsing complexity that otherwise forces agent prompts to handle venue-specific field names.

Developer checklist for any prediction-market orderbook API

Use this list during integration and code review to confirm your consumer handles required behaviors correctly.

Request headers and rate-limit semantics:

• Send API key in the Authorization: Bearer header or the venue-specific header name documented in the API reference.

• Read X-Rate-Limit-Remaining on every response. When it reaches zero, wait until X-Rate-Limit-Reset (Unix epoch) before the next request.

• Never retry a 429 immediately. Always respect the reset timestamp.

Schema expectations:

• Price fields: confirm whether the API returns decimal strings or integer cents. Normalize to Decimal internally before any arithmetic.

• Size fields: confirm integer contracts vs fractional. Store as float internally.

• Timestamps: confirm ISO-8601 UTC. Reject any timestamp more than your freshness threshold behind wall clock.

• side enum: confirm accepted values (yes/no, buy/sell, or venue-specific strings) and map to your canonical enum at ingestion.

• hash/ETag: confirm whether it is present, nullable, or absent. Build hash-check logic as optional but always log when it is missing.

Behavior expectations:

• depth parameter: confirm it truncates the book server-side. Do not assume the full book is returned when depth is omitted.

• Per-outcome side selection: confirm you can request YES and NO books independently.

• 404 on missing market: confirm your consumer treats this as a missing-market signal, not a fatal error.

• Pagination or depth truncation: confirm whether the API paginates deep books or simply truncates at the requested depth.

Operational checks:

• Confirm sandbox vs production endpoint URLs are distinct and that test keys do not hit production rate limits.

• Confirm L3 access requires a separate permission scope and that your API key has that scope if you need order-level data.

• Verify sample or test keys are available for local development before requesting production credentials.

What production integrations actually teach you

The biggest operational surprises in prediction-market orderbook integrations are not the ones you plan for. Thin event liquidity is the first. A market that looks liquid at 9 AM can be nearly empty by the time a news event resolves, and your pre-trade checks need to handle that transition in real time, not just at startup.

Timestamp drift is the second. Centralized venues occasionally serve stale snapshots during high-load periods. A book with a timestamp 30 seconds behind wall clock is not a live book, and treating it as one will produce incorrect slippage estimates. Freshness checks are not optional.

Schema mismatches are the third, and the subtlest. Two venues may both call a field price, but one returns it as a decimal and the other as an integer in cents. That bug does not throw an exception. It silently produces prices 100x off, which corrupts every downstream calculation until someone notices P&L is wrong.

The two investments that pay back fastest: sequence-ID verification catches drift before it compounds, and simulated load testing with injected gaps finds your recovery logic failures before production does. Both are cheap to build early and expensive to retrofit after an outage.

Assymetrix gives developers one integration instead of three

Building separate orderbook consumers for Polymarket, Kalshi, and Limitless means three authentication flows, three WebSocket topic structures, three schema parsers, and three sets of reconnect logic. The Assymetrix Data API collapses that into one.

The unified /sdk/markets/:id/orderbook endpoint delivers normalized L2 depth, pre-computed liquidity bands, content fingerprints, and snapshot+delta streams across all three venues through a single API key. Historical backfill across nearly one billion rows of trading activity means you can test your consumer against real market conditions before going live.

Developer-friendly from day one: example keys for sandbox testing, Python and TypeScript SDK support, and full API reference at Data. Start with a free-tier key, run a local snapshot+delta replay, and confirm your pre-trade checks work against real historical depth before connecting to live feeds.

Sources

• One Data Layer for the Future of Event Markets

• The problem with prediction markets

• Get current market orderbook

• Market Orderbook (Nansen docs)

FAQ

What does prediction-market orderbook data reveal that price alone cannot?

Price tells you where the last trade cleared. The orderbook shows bid-ask spread, liquidity concentration at key probability levels, order imbalance between YES and NO sides, and where market makers are positioned, all of which are inputs price alone cannot supply.

Is the Polymarket API free to access?

Polymarket’s on-chain data is publicly accessible via RPC nodes and indexers, but building a reliable consumer requires infrastructure for block tracking and reorg handling. Third-party aggregators like Assymetrix provide normalized Polymarket orderbook data through a standard API key, with free-tier access available.

What are the main prediction market platforms for developers to integrate?

Polymarket (on-chain CLOB), Kalshi (centralized orderbook), and Limitless are the three primary venues with meaningful liquidity and developer-accessible data. Assymetrix aggregates all three into a single normalized feed.

How much does it cost to build a prediction market platform from scratch?

A full platform requires a trading engine, real-time pricing layer, wallet integration, liquidity mechanisms, and oracle/resolution integration. Engineering cost varies widely by team size and scope; most teams find that consuming a normalized data API for the intelligence layer reduces build time significantly compared to building venue connections from scratch.

Can you make money trading prediction markets algorithmically?

Algorithmic strategies can be profitable, but thin and event-dependent liquidity means execution quality is the primary constraint. Depth gating, slippage estimation, and cross-venue arbitrage detection are the core tools; strategies that ignore orderbook depth and rely on price signals alone tend to fail at execution.