Orderbook Streaming and PN1

The orderbook WebSocket is separate from the settlement stream. It emits full snapshots, absolute depth updates, price changes, and last-trade metadata for selected outcome token IDs. Use one of three levels:

Level	Best for
Raw orderbook stream	applications that already manage book state
`LocalOrderbook`	applying messages to an in-memory book yourself
`OrderbookEngine`	managed connection, local state, filtered views, reconnect recovery, and optional PN1 integrity

For most applications, start with OrderbookEngine.

Managed local book

Set TOKEN_ID to a Polymarket outcome token ID. You can obtain token IDs from V3 market data or the clobTokenIds / clob_token_ids field on a short-form rotation.

TypeScript
Python
Rust

import {
  OrderbookEngine,
  type BookSnapshot,
  type BookUpdate,
} from 'polynode-sdk';

const apiKey = process.env.POLYNODE_API_KEY;
const tokenId = process.env.TOKEN_ID;
if (!apiKey || !tokenId) throw new Error('Set POLYNODE_API_KEY and TOKEN_ID');

const engine = new OrderbookEngine({ apiKey });
engine.on('ready', () => {
  console.log('best bid', engine.bestBid(tokenId));
  console.log('best ask', engine.bestAsk(tokenId));
  console.log('midpoint', engine.midpoint(tokenId));
});
engine.on('update', (update: BookSnapshot | BookUpdate) => {
  console.log(update.type, update.asset_id);
});

await engine.subscribe([tokenId]);
process.once('SIGINT', () => engine.close());

import asyncio
import os
from polynode import OrderbookEngine

async def main() -> None:
    token_id = os.environ["TOKEN_ID"]
    engine = OrderbookEngine(api_key=os.environ["POLYNODE_API_KEY"])
    engine.on(
        "ready",
        lambda: print(
            "touch",
            engine.best_bid(token_id),
            engine.best_ask(token_id),
            engine.midpoint(token_id),
        ),
    )
    engine.on("update", lambda update: print(update.type, update.asset_id))
    try:
        await engine.subscribe([token_id])
        await asyncio.Event().wait()
    finally:
        engine.close()

asyncio.run(main())

use polynode::{EngineOptions, OrderbookEngine};

#[tokio::main]
async fn main() -> polynode::Result<()> {
    let api_key = std::env::var("POLYNODE_API_KEY")
        .expect("Set POLYNODE_API_KEY");
    let token_id = std::env::var("TOKEN_ID").expect("Set TOKEN_ID");
    let engine = OrderbookEngine::connect(&api_key, EngineOptions::default()).await?;
    engine.subscribe(vec![token_id.clone()]).await?;

    loop {
        if let Some(book) = engine.book(&token_id).await {
            println!("{} bids, {} asks", book.0.len(), book.1.len());
            println!("midpoint {:?}", engine.midpoint(&token_id).await);
            break;
        }
        tokio::task::yield_now().await;
    }

    engine.close().await?;
    Ok(())
}

subscribe() resolves after the server acknowledges the requested identifiers. The local book becomes readable after its initial snapshot arrives. TypeScript and Python emit ready when every acknowledged token has a valid baseline.

Book update rules

Apply raw messages with these rules:

Message	Effect on depth
`book_snapshot`	replace the complete book for that token
`book_update`	upsert each absolute price level; size `"0"` removes it
`price_change`	upsert the absolute level on `BUY` bids or `SELL` asks; size `"0"` removes it
`last_trade_price`	update trade metadata only; never mutate depth

Prices and sizes are decimal strings. Keep them as strings or use a decimal library for exact calculations. Converting them to binary floating point can change level identity and is incompatible with PN1 checksum verification.

Enable PN1 integrity

PN1 lets the SDK detect a missing or out-of-order depth message instead of continuing with a book that merely looks plausible. It validates:

a trusted anchor snapshot for each token
sequence continuity across depth changes
the checksum after every verified mutation

TypeScript
Python
Rust

const engine = new OrderbookEngine({
  apiKey,
  integrity: true,
  allowStaleReads: false,
});

engine.on('integrity_error', (error) => {
  console.error(error.token, error.code, error.message);
});
await engine.subscribe([tokenId]);

engine = OrderbookEngine(
    api_key=os.environ["POLYNODE_API_KEY"],
    integrity=True,
    allow_stale_reads=False,
)
engine.on(
    "integrity_error",
    lambda error: print(error.token, error.code, error),
)
await engine.subscribe([token_id])

let engine = OrderbookEngine::connect(
    &api_key,
    EngineOptions {
        integrity: true,
        allow_stale_reads: false,
        ..Default::default()
    },
).await?;

let mut errors = engine.integrity_errors();
tokio::spawn(async move {
    while let Ok(error) = errors.recv().await {
        eprintln!("{} {:?}: {}", error.token, error.code, error.message);
    }
});
engine.subscribe(vec![token_id]).await?;

PN1 mode requires explicit market identifiers. A wildcard/firehose orderbook subscription is not available with integrity enabled.

Fail-closed lifecycle

With allowStaleReads / allow_stale_reads left at its default false, the local book moves through these states:

State	Readable?	Meaning
`initializing`	No	waiting for a valid anchor
`ready`	Yes	current sequence and checksum are valid
`stale`	No	connection was lost
`resyncing`	No	a replacement anchor was requested
`failed`	No	integrity could not be recovered on the current stream

On a sequence or checksum failure, the engine gates only the affected token and requests a fresh anchor. It does not serve the last book as verified state. Set stale reads to true only when your application deliberately prefers availability over verified depth. Surface that choice to downstream consumers; a stale book should not be mistaken for current market state.

Reconnects

Orderbook reconnect is automatic by default. The SDK replays the active token set and waits for fresh snapshots. Sequence state from the old connection is never reused as if it belonged to the replacement connection. Application handlers remain attached across reconnects. You do not need to register them again.

Filtered views

Views share the engine’s connection and state but receive updates only for their token set.

TypeScript
Python
Rust

const view = engine.view([tokenId]);
view.on('update', (update) => console.log(update.asset_id));
console.log(view.midpoint(tokenId));

view.setTokens([anotherTokenId]);
view.destroy();

view = engine.view([token_id])
view.on("update", lambda update: print(update.asset_id))
print(view.midpoint(token_id))

view.set_tokens([another_token_id])
view.destroy()

let mut view = engine.view(vec![token_id.clone()]);
if let Some(update) = view.next().await {
    println!("{update:?}");
}
view.set_tokens(vec![another_token_id]).await;

Use views when several application components need different slices of one shared book connection.

Raw stream

Choose the raw client when you need protocol messages or maintain state elsewhere:

TypeScript: pn.orderbook.subscribe(tokenIds) and pn.orderbook.on(...)
Python: await pn.orderbook.subscribe(token_ids) and pn.orderbook.on(...)
Rust: client.orderbook_stream(ObStreamOptions::default()).await?

In raw mode, your code is responsible for applying snapshots and deltas correctly. LocalOrderbook provides the same deterministic update logic without the higher-level engine.

Cleanup

TypeScript
Python
Rust

engine.close();

engine.close()

engine.close().await?;

See the orderbook protocol, message reference, and PN1 integrity reference for wire-level details.

Getting Started

Core Guides

Optional Helpers

TypeScript

Python

Rust

Charts (Browser)

Orderbook Streaming and PN1

Managed local book

Book update rules

Enable PN1 integrity

Fail-closed lifecycle

Reconnects

Filtered views

Raw stream

Cleanup

​Managed local book

​Book update rules

​Enable PN1 integrity

​Fail-closed lifecycle

​Reconnects

​Filtered views

​Raw stream

​Cleanup

Managed local book

Book update rules

Enable PN1 integrity

Fail-closed lifecycle

Reconnects

Filtered views

Raw stream

Cleanup