Settlement and Event Streams

The event WebSocket is the fastest path from a detected Polymarket fill to your application. A settlements subscription emits:

settlement when PolyNode detects a matching transaction, with status set to pending or confirmed
status_update when a previously pending transaction is confirmed on-chain

The SDK waits for the server’s subscription acknowledgement before returning the subscription. It then routes typed events to handlers or an async iterator.

TypeScript
Python
Rust

import { PolyNode } from 'polynode-sdk';

const apiKey = process.env.POLYNODE_API_KEY;
if (!apiKey) throw new Error('Set POLYNODE_API_KEY');
const pn = new PolyNode({ apiKey });

const sub = await pn.ws
  .subscribe('settlements')
  .status('all')
  .snapshotCount(25)
  .send();

sub.on('settlement', (event) => {
  console.log(event.status, event.tx_hash, event.taker_side, event.taker_size);
});
sub.on('status_update', (event) => {
  console.log('confirmed', event.tx_hash, event.block_number);
});

process.once('SIGINT', () => {
  sub.unsubscribe();
  pn.ws.disconnect();
});

import asyncio
import os
from polynode import AsyncPolyNode

async def main() -> None:
    async with AsyncPolyNode(api_key=os.environ["POLYNODE_API_KEY"]) as pn:
        sub = await (
            pn.ws.subscribe("settlements")
            .status("all")
            .snapshot_count(25)
            .send()
        )
        try:
            async for event in sub:
                if event.event_type == "settlement":
                    print(event.status, event.tx_hash, event.taker_size)
                elif event.event_type == "status_update":
                    print("confirmed", event.tx_hash, event.block_number)
        finally:
            sub.unsubscribe()
            pn.ws.disconnect()

asyncio.run(main())

use polynode::{PolyNodeClient, PolyNodeEvent, WsMessage};
use polynode::ws::{StreamOptions, Subscription, SubscriptionType};

#[tokio::main]
async fn main() -> polynode::Result<()> {
    let client = PolyNodeClient::new(
        std::env::var("POLYNODE_API_KEY").expect("Set POLYNODE_API_KEY")
    )?;
    let mut stream = client.stream(StreamOptions::default()).await?;
    let ack = stream.subscribe_with_ack(
        Subscription::new(SubscriptionType::Settlements)
            .status("all")
            .snapshot_count(25),
    ).await?;
    println!("subscription {}", ack.subscription_id);

    while let Some(message) = stream.next().await {
        match message? {
            WsMessage::Event(PolyNodeEvent::Settlement(event)) => {
                println!("{:?} {} {}", event.status, event.tx_hash, event.taker_size);
            }
            WsMessage::Event(PolyNodeEvent::StatusUpdate(event)) => {
                println!("confirmed {} in {}", event.tx_hash, event.block_number);
            }
            WsMessage::Replay(notice) => eprintln!("{}", notice.warning),
            _ => {}
        }
    }
    stream.close().await?;
    Ok(())
}

snapshotCount / snapshot_count returns recent matching events before live delivery. Set it only when your application benefits from a warm start.

Filter at the server

Filters reduce bandwidth and work before events reach your process.

Filter	TypeScript	Python	Rust	Use
Wallets	`.wallets([...])`	`.wallets([...])`	`.wallets(vec![...])`	maker or taker addresses
Tokens	`.tokens([...])`	`.tokens([...])`	`.tokens(vec![...])`	outcome token IDs
Market slugs	`.slugs([...])`	`.slugs([...])`	`.slugs(vec![...])`	exact market slugs
Conditions	`.conditionIds([...])`	`.condition_ids([...])`	`.condition_ids(vec![...])`	condition IDs
Minimum / maximum size	`.minSize(n)` / `.maxSize(n)`	`.min_size(n)` / `.max_size(n)`	`.min_size(n)` / `.max_size(n)`	USD-size bounds
Status	`.status('all')`	`.status('all')`	`.status("all")`	pending, confirmed, or both
Replay cursor	`.since(ms)`	`.since(ms)`	`.since(ms)`	events newer than Unix milliseconds

Example wallet filter:

TypeScript
Python
Rust

const sub = await pn.ws.subscribe('settlements')
  .wallets(['0xabc...', '0xdef...'])
  .minSize(1000)
  .status('all')
  .send();

sub = await (
    pn.ws.subscribe("settlements")
    .wallets(["0xabc...", "0xdef..."])
    .min_size(1000)
    .status("all")
    .send()
)

let ack = stream.subscribe_with_ack(
    Subscription::new(SubscriptionType::Settlements)
        .wallets(vec!["0xabc...".into(), "0xdef...".into()])
        .min_size(1000.0)
        .status("all"),
).await?;

See Subscribing for preset-specific filter behavior.

Presets

The SDKs use the same subscription names:

Preset	Typical events
`settlements`	settlement detection and confirmation updates
`trades`	settlements, confirmed trades, status updates
`dome` / `fills`	normalized per-fill events
`combos`	combo executions and status updates
`redemptions` / `redemption`	redemptions
`wallets`	settlement, trade, position, deposit, conversion, and redemption activity for selected wallets
`markets`	activity for selected markets
`large_trades`	settlement and trade events above a size threshold
`blocks`	block summaries
`oracle`	oracle lifecycle events
`chainlink`	spot or explicit TWAP price events
`global`	the default public event set; combo events require `combos`

Acknowledgements

Do not assume a subscription is active before the SDK’s subscribe call resolves. The acknowledgement includes the server-assigned subscription ID and may include warnings. For Chainlink subscriptions it also reports the selected price source and explicit TWAP windows:

TypeScript
Python
Rust

const prices = await pn.ws.subscribe('chainlink')
  .feeds(['BTC/USD'])
  .twapWindows([30])
  .send();

console.log(prices.id, prices.priceSource, prices.twapWindows, prices.warnings);

prices = await (
    pn.ws.subscribe("chainlink")
    .feeds(["BTC/USD"])
    .twap_windows([30])
    .send()
)
print(prices.id, prices.price_source, prices.twap_windows, prices.warnings)

let ack = stream.subscribe_with_ack(
    Subscription::new(SubscriptionType::Chainlink)
        .feeds(vec!["BTC/USD".into()])
        .twap_windows(vec![30]),
).await?;
println!("{:?} {:?} {:?}", ack.price_source, ack.twap_windows, ack.warnings);

One event-stream connection can carry several normal subscriptions. Chainlink feed and TWAP selection is connection-scoped, so combine all desired Chainlink feeds and windows in one Chainlink subscription on that connection. Use another connection for a different selection.

Reconnect behavior

Automatic reconnect is enabled by default. After a disconnect, the SDK:

opens a replacement socket
resubscribes each active subscription with its original filters
adds a best-effort since cursor based on the latest accepted event
overlaps the cursor slightly and removes duplicate delivery in the client
reports replay state to your application

This reduces avoidable gaps, but it is not an unlimited gapless guarantee. Server history is bounded, and a disconnect can outlast it. Treat every replay notice as an observable recovery interval.

TypeScript
Python
Rust

pn.ws.onReplay((notice) => {
  console.warn(notice.phase, notice.since, notice.guaranteed, notice.warning);
});
pn.ws.onReconnect((attempt) => console.warn('reconnected', attempt));
pn.ws.onError((error) => console.error(error.message));

pn.ws.on_replay(
    lambda notice: print(
        notice.phase, notice.since, notice.guaranteed, notice.warning
    )
)
pn.ws.on_reconnect(lambda attempt: print("reconnected", attempt))
pn.ws.on_error(lambda error: print(error))

match message? {
    WsMessage::Replay(notice) => {
        eprintln!("{} (guaranteed={})", notice.warning, notice.guaranteed);
    }
    WsMessage::Error { code, message } => eprintln!("{code:?}: {message}"),
    _ => {}
}

Managed short-form streams also reconnect at every market boundary. That deliberate rotation is required to replace the old market slugs and connection-scoped Chainlink selection. See Short-form and TWAP.

Slow consumers

TypeScript and Python async iterators use a bounded per-subscription queue. Register an overflow callback if processing may fall behind:

TypeScript
Python
Rust

sub.onOverflow((notice) => {
  console.error('dropped events', notice.droppedEvents, notice.queueCapacity);
});

sub.on_overflow(
    lambda notice: print("dropped events", notice.dropped_events)
)

Rust applies backpressure to the bounded stream instead of silently evicting settlement events. Keep the next() loop lightweight and hand expensive work to a bounded worker queue.

Handler callbacks are still invoked immediately. Queue overflow applies to the async-iterator buffer.

Forward-compatible events

New event types do not disappear merely because your SDK predates their typed model:

TypeScript emits an unknown event containing wire_event_type, raw, and an optional decode error.
Python yields UnknownEvent with the complete raw payload.
Rust emits WsMessage::UnknownEvent or WsMessage::UnknownMessage.

Log the event type and upgrade the SDK; avoid logging credentials or an entire payload when it may contain user data.

Cleanup

Stop subscriptions and close their owning socket during shutdown:

TypeScript
Python
Rust

sub.unsubscribe();
pn.ws.disconnect();

sub.unsubscribe()
pn.ws.disconnect()

stream.unsubscribe(Some(ack.subscription_id)).await?;
stream.close().await?;

Next: Short-form and Chainlink TWAP or the full event reference.

Getting Started

Core Guides

Optional Helpers

TypeScript

Python

Rust

Charts (Browser)

Settlement and Event Streams

Filter at the server

Presets

Acknowledgements

Reconnect behavior

Slow consumers

Forward-compatible events

Cleanup

​Subscribe to settlements

​Filter at the server

​Presets

​Acknowledgements

​Reconnect behavior

​Slow consumers

​Forward-compatible events

​Cleanup

Subscribe to settlements

Filter at the server

Presets

Acknowledgements

Reconnect behavior

Slow consumers

Forward-compatible events

Cleanup