DEV Community: BlueWhale-Quant-Lab

Polymarket CLOB WebSocket in Python — Real-Time Order Book Without Polling

BlueWhale-Quant-Lab — Wed, 17 Jun 2026 04:52:41 +0000

If your Polymarket bot polls GET /book in a loop, your view of the market is as stale as your interval — and you'll lose to anyone using the WebSocket feed. This tutorial builds a real-time local order book in Python from the CLOB WebSocket stream.

Why WebSocket beats polling

Polling: you ask every N ms → your data is up to N ms old, and you burn REST rate-limit budget.
WebSocket: the server pushes changes → your information latency drops to roughly your network round-trip.

For a reactive strategy, this is the difference between trading the market that is and the market that was.

Connect and subscribe

import asyncio, json, websockets

WS_URL = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

async def subscribe(token_ids):
    async with websockets.connect(WS_URL, ping_interval=20, ping_timeout=20) as ws:
        await ws.send(json.dumps({"assets_ids": token_ids, "type": "market"}))
        async for raw in ws:
            yield json.loads(raw)

(Confirm the exact URL, subscription payload, and message shapes against current Polymarket docs — they change.)

Maintain a local book from snapshot + deltas

The feed typically sends an initial book snapshot then incremental price-change messages. Apply them to a local structure:

class LocalBook:
    def __init__(self):
        self.bids = {}   # price -> size
        self.asks = {}

    def apply_snapshot(self, msg):
        self.bids = {float(l["price"]): float(l["size"]) for l in msg.get("bids", [])}
        self.asks = {float(l["price"]): float(l["size"]) for l in msg.get("asks", [])}

    def apply_delta(self, msg):
        for ch in msg.get("changes", []):
            side = self.bids if ch["side"] == "BUY" else self.asks
            price, size = float(ch["price"]), float(ch["size"])
            if size == 0:
                side.pop(price, None)
            else:
                side[price] = size

    def best_bid(self): return max(self.bids) if self.bids else None
    def best_ask(self): return min(self.asks) if self.asks else None
    def mid(self):
        b, a = self.best_bid(), self.best_ask()
        return (b + a) / 2 if b and a else None

Wire it together

async def run(token_id):
    book = LocalBook()
    async for msg in subscribe([token_id]):
        t = msg.get("event_type") or msg.get("type")
        if t in ("book", "snapshot"):
            book.apply_snapshot(msg)
        elif t in ("price_change", "delta"):
            book.apply_delta(msg)
        # react immediately on fresh state
        m = book.mid()
        if m is not None:
            on_mid(m, book)

asyncio.run(run(TOKEN_ID))

Measure your information lag

Always know how fresh your book is:

import time
lag_ms = (time.time() - float(msg["timestamp"])) * 1000
if lag_ms > 50:
    print(f"⚠ stale: {lag_ms:.0f}ms behind server")

The ceiling you can't code around

Here's the catch: your information latency can never beat your network round-trip to the server. The CLOB WebSocket terminates in Amsterdam — I measured ~1.2 ms from an AMS box vs ~88 ms from US-East. From the US, even a perfect WebSocket implementation is ~90 ms behind reality, because that's how long the packets take to arrive.

So the prerequisite for a fast feed is a server near the feed. I run mine on an Amsterdam-metro VPS: my Amsterdam VPS
Disclosure: affiliate link, I earn a referral. It's the box behind the 1.2 ms.

Robustness checklist

Reconnect with backoff — WebSockets drop; resubscribe and re-snapshot on reconnect.
Detect gaps — if deltas reference prices you don't have, request a fresh snapshot.
Heartbeat — use ping_interval so dead connections are detected fast.
One process, many assets — subscribe to multiple assets_ids on one socket.

Recap

WebSocket + a maintained local book gives you near-real-time perception. But the floor on "real-time" is your distance to Amsterdam. Get the server location right, then this code makes you genuinely fast.

Code is illustrative — verify against current docs. Latency from my own 2026 tests. Not financial advice.

How to Benchmark API Latency to Any Endpoint (Polymarket Case Study)

BlueWhale-Quant-Lab — Wed, 17 Jun 2026 04:51:36 +0000

"Just ping it" is bad latency advice. ICMP gets deprioritized behind CDNs and tells you almost nothing about real request latency. This is how to benchmark API latency properly, with a real case study: finding where Polymarket's order book lives.

Why `ping` lies

ping measures ICMP echo round-trip. But:

CDNs and load balancers often rate-limit or deprioritize ICMP, so the number is noisy or misleadingly high/low.
It ignores TLS handshake cost, which dominates short HTTPS requests.
It tells you nothing about server processing time (TTFB).

For an API, measure what the API actually does: TCP connect, TLS, and time-to-first-byte.

A proper latency harness (Python)

import socket, ssl, time, statistics, http.client

def percentiles(xs):
    xs = sorted(xs); n = len(xs)
    return {
        "min": round(xs[0], 2),
        "p50": round(statistics.median(xs), 2),
        "p95": round(xs[int(n*0.95)-1], 2),
        "p99": round(xs[int(n*0.99)-1], 2),
        "max": round(xs[-1], 2),
    }

def tcp_connect_ms(host, port=443):
    t = time.perf_counter()
    s = socket.create_connection((host, port), timeout=5); s.close()
    return (time.perf_counter() - t) * 1000

def ttfb_ms(host, path="/"):
    t = time.perf_counter()
    c = http.client.HTTPSConnection(host, 443, timeout=5,
                                    context=ssl.create_default_context())
    c.request("GET", path); r = c.getresponse(); r.read(1); c.close()
    return (time.perf_counter() - t) * 1000

def bench(host, n=200):
    return {
        "tcp_connect": percentiles([tcp_connect_ms(host) for _ in range(n)]),
        "ttfb":        percentiles([ttfb_ms(host) for _ in range(n)]),
    }

import json
print(json.dumps(bench("clob.polymarket.com"), indent=2))

Read p99 and jitter, not just the average

The average is marketing. What kills a trading bot is the p99 — your latency during the volatile windows you actually trade in. Always report min / p50 / p95 / p99 / max. A box with p50=1.2 ms but p99=12 ms is worse than a steady p50=3 ms box.

Check jitter over time, too:

ping -i 0.5 -c 600 clob.polymarket.com | tail -3   # watch min/avg/max/mdev spread

The case study: where is Polymarket's CLOB?

I ran the harness from VPS boxes in five regions:

Region	TCP connect p50	TTFB p50
Amsterdam	~1.4 ms	~6 ms
Frankfurt	~9 ms	~16 ms
US-East	~90 ms	~110 ms
Singapore	~168 ms	~195 ms

A ~1.4 ms TCP connect is only possible within ~100 km (fiber does ~200 km/ms RTT). So the endpoint is in Amsterdam — proven by physics, not vibes. (Whether the matching engine is co-located vs behind an edge is a fair inference from the low TTFB, but the hosting decision is the same either way.)

Turning the benchmark into a decision

The whole point of benchmarking is to act on it. For Polymarket, the data says: host in Amsterdam. I moved my bot to an AMS-metro VPS and the connect time went from ~90 ms to ~1.2 ms. The box I use: the Amsterdam box I use
Disclosure: affiliate link — I earn a referral. The numbers above are from this box.

Reusable checklist

✅ Measure TCP connect + TTFB, not just ICMP.
✅ Report percentiles, especially p99.
✅ Test jitter over minutes, at different times of day.
✅ Compare multiple regions with hourly VPS boxes.
✅ Convert sub-2 ms numbers into "same metro" conclusions via the fiber speed limit.

This harness works for any endpoint — exchanges, RPCs, your own APIs. Polymarket just happens to have a satisfying answer: Amsterdam.

Numbers from my own 2026 tests. Not financial advice.

Polymarket's Price-to-Beat Has No API — Why a Co-located Server Gets It in Real Time, Not 15 Seconds

BlueWhale-Quant-Lab — Wed, 17 Jun 2026 04:51:26 +0000

If you automate Polymarket's crypto Up/Down markets, you hit this wall fast: there is no API that returns the "price to beat" (PTB) — the strike/reference price that decides whether Up or Down wins. You have to reconstruct it. And the speed + accuracy of that reconstruction turns out to be a server-location problem. Let me connect the two, because almost nobody does.

What the price-to-beat actually is

Each Up/Down cycle settles against one number — the PTB — captured at the cycle open (t_start). It's not stored in a Polymarket endpoint; it's taken from an upstream source at that instant:

Cycle	Where the PTB comes from
5m / 15m / 4h	the Chainlink price pushed at `t_start`
1h	the Binance 1h candle OPEN at `t_start`
1d	the Binance 1m candle CLOSE at noon-ET `t_start`

(The per-cycle recipe and the noon-ET/DST boundary rules are deterministic — there's a clean open-source resolver for that part, linked at the end.)

The key word is instant. The PTB is a snapshot of an upstream feed at a precise moment. Whoever samples that feed closest to that moment reconstructs the most faithful copy of the number Polymarket itself locked.

The two ways to get it — and why one is 15 seconds too slow

Option A — scrape it off the market page. Load the Polymarket Up/Down page, wait for it to render, parse the displayed strike. In practice that's ~15 seconds end to end (page load, JS hydration, polling until the value appears). For most of the cycle, fine. For the moment that matters — the open — it's useless.

Option B — reconstruct it yourself at t_start. Sample the same upstream feed (Chainlink/Binance) at the cycle boundary and apply the recipe. You get the number as it's being set, not 15 seconds after.

Option B is only as good as your sampling delay — how long after t_start you actually capture the upstream value. And that delay is dominated by network latency. Which is where the server comes in.

Why co-location makes your PTB match Polymarket's

Here's the part I verified empirically. My order/data infra sits in Amsterdam, the same metro Polymarket's CLOB answers from (I measured ~1.2 ms to it — see my latency benchmark post). Because my box is effectively co-located with Polymarket's own slicing path, when I sample the upstream price at t_start, I capture essentially the same tick Polymarket captured.

In my testing, the PTB I reconstruct this way matches Polymarket's locked value ~99% of the time, and when it differs the error is under 0.2%. That's not luck — it's what happens when your sampling delay (the "lock-delay") shrinks toward zero. The upstream feed (especially a Chainlink push) can drift in the moments after t_start; a far-away server samples late, catches drift, and reconstructs a strike that's slightly — sometimes decisively — off. A co-located server samples at the same instant and matches.

The failure mode is brutal: a late-sampled PTB can flip which side is "Up" vs "Down" on a tight cycle. Getting the strike wrong doesn't throw an error — it silently puts you on the losing side.

So "low latency" here isn't about order speed at all. It's about reconstructing the correct reference number in the first place. Distance from the feed = drift = wrong strike.

Why this matters most at T0

The opportunities cluster in the T0 window — the pre-open / just-opened price-chaos period where the book is thin, quotes are stale, and the fair strike is still settling. That window is seconds long. A 15-second scrape never sees it. A far-away reconstruction sees a drifted strike. Only a co-located, real-time reconstruction lets you act inside T0 with a strike you trust.

That's the whole edge: right number, right now, while the window is open.

The setup

Reconstruct, don't scrape. The deterministic recipe (source/candle/field per cycle, noon-ET & DST boundaries, candle-close validation) is open source: BlueWhale's price-to-beat resolver (MIT, runs offline).
Co-locate in Amsterdam so your sampling delay → ~1 ms and your reconstructed PTB matches Polymarket's. This is the infra half of the problem; the resolver is the logic half. The box I run mine on: the Amsterdam VPS behind my ~1.2 ms / 0.2%-error setup Disclosure: affiliate link — I earn a referral. It's the same box producing the numbers above.
Validate the candle close for the daily (don't trust a 1-minute CLOSE before its close_time), and treat a Chainlink push that lands too long after t_start as untrusted — at that point the price has drifted and the side can flip.

Heads-up

The ~99% match / <0.2% error are my own measurements from an Amsterdam box in 2026 — re-measure on yours; results depend on the feed and your sampling discipline.
A correct PTB is a data primitive, not a trade. It tells you the strike and the likely side — it places no orders and promises no profit.
Co-location removes the latency excuse; your strategy, sizing, and risk still have to be right.

Bottom line

Polymarket's price-to-beat has no API — you reconstruct it at the cycle open, and a co-located Amsterdam server lets you reconstruct it in real time and accurate to within ~0.2%, instead of scraping a number that's 15 seconds stale. For T0 arbitrage, that's the difference between trading the open and reading about it afterward.

Latency/accuracy figures from my own 2026 tests. Not financial advice.

How to get the Polymarket Price To Beat at T0 - the open price the instant the window opens

BlueWhale-Quant-Lab — Thu, 04 Jun 2026 13:03:08 +0000

How to get the Polymarket Price To Beat at T0 — the open price the instant the window opens

Every Polymarket crypto Up/Down market resolves against one number: the Price To Beat (PTB) — the opening reference price. Final price > PTB → Up wins; below it → Down. If you're building anything on "BTC Up or Down", the PTB is the number your whole edge depends on.

And there is no API for it on crypto markets. Worse: by the time the PTB shows up anywhere you can read it, your 5-minute window is already closing. The fix isn't to scrape it harder — it's to resolve it at T0 (the instant the window opens) from the same upstream sources Polymarket itself uses.

"Read it off the page" comes too late

The frontend does render the PTB and outcome — but only ~20 seconds after the window closes. That's perfect for recording results or backfilling history. It's useless for entry, where you need the open price before the window runs. Different problem, different data path.

To act at the open, you have to go to the source.

Where the open price actually comes from (it depends on the cycle)

This is the reverse-engineered part. There is no single feed — each timeframe resolves against a different one:

Cycle	Reference price (the PTB)
5m / 15m / 4h	the Chainlink oracle stream Polymarket resolves against — first tick at/after the window boundary
1h	the Binance 1-hour candle OPEN at the window start
1d	the Binance 1-minute candle CLOSE at the official noon-ET open

Use one source for all of them — say, the live Chainlink price for the daily too — and you'll be off, sometimes by hundreds of dollars, and you won't get an error. You'll just get the wrong winning side.

The boundaries aren't all UTC

5m / 15m / 1h start on UTC grid lines.
4h starts on America/New_York hours (00/04/08/12/16/20). A fixed UTC formula is wrong half the year because EST and EDT differ by an hour.
1d starts at noon ET — not UTC midnight, not ET midnight. "Up or Down on March 5" runs Mar 4 noon ET → Mar 5 noon ET, and the PTB is taken at Mar 4 noon ET. A DST-transition day is 23 or 25 hours, so the end is "noon ET + one calendar day", never "start + 86400".

Don't read the daily candle early

The daily uses the close of the 1-minute candle at noon ET. Binance returns that candle the moment it opens, but until it closes, close is just the latest trade — not the final close:

open_time, _, _, _, close, _, close_time, *_ = candle[0]
if now_ms <= int(close_time):
    raise NotReady("1m candle hasn't closed; CLOSE is still live")
price_to_beat = float(close)

Also: Binance startTime is a filter, not an exact match — always check the returned candle's open_time equals the t_start you asked for.

One async call at T0

With the per-cycle source mapping and the Eastern-time boundaries handled, getting the open price becomes a single call:

ptb = await resolver.get_ptb(asset, tf, t_start)
# 5m/15m/4h -> first Chainlink tick at/after t_start
# 1h        -> Binance 1h candle OPEN
# 1d        -> Binance 1m candle CLOSE at noon ET (waited until final)

For 5m/15m/4h the resolver subscribes to the real-time Chainlink feed and takes the first tick at or after the boundary — the open price in real time, long before on-chain settlement.

Two complementary approaches

If all you need is the settled result after the fact, the free page-scraper reads the rendered Outcome (and PTB) ~20s after close:

https://github.com/BlueWhale-Quant-Lab/Polymarket-Crypto-UpDown-Outcome-Scraper

But for entry you need the PTB at the open, in real time, from the underlying sources — which is exactly what the T0 resolver does. I packaged the full per-cycle mapping (Chainlink stream for 5m/15m/4h, Binance open for 1h, noon-ET 1m close for 1d), the DST-aware boundaries, and the wait-for-close guard into a small async library + CLI:

Polymarket T0 Price-To-Beat Resolver — get the open price the instant the window opens

It covers BTC, ETH, SOL, XRP, DOGE across 5m / 15m / 1h / 4h / 1d, with one dependency (aiohttp).

Good to know

The source mapping mirrors Polymarket's own settlement logic and was checked against settled markets — in practice the resolved PTB matches the settled value to the precision the site displays. The free scraper covers the after-the-fact read completely; the T0 resolver is for when you need the number at the open.
You need network access to Binance and Polymarket — some regions block Binance, so use appropriate egress.
Chainlink ticks at its own cadence; the "first tick at/after the boundary" is the open the platform uses, not a continuous price.
If Polymarket ever changes a settlement source, the mapping would need updating.
It returns a price, not a profit — a data primitive, not a trading bot. No orders, no financial advice.

Takeaway

The PTB is reconstructable at T0 as long as you respect three things: the per-cycle source (Chainlink vs Binance open vs Binance close), the noon-ET / DST boundaries for 4h and 1d, and the wait-for-close rule on the daily. Get those right and you have the opening reference price in real time — the one number the API never gives you.

How to read a Polymarket Up/Down outcome (and the Price To Beat) before the oracle settles

BlueWhale-Quant-Lab — Thu, 04 Jun 2026 13:03:04 +0000

How to read a Polymarket Up/Down outcome (and the Price To Beat) before the oracle settles

Polymarket runs hugely popular short-window crypto markets — "Will BTC be Up or Down at the close?" — on BTC, ETH, SOL, XRP and DOGE, over 5m / 15m / 1h / 4h / 1d windows. If you automate them, two numbers decide everything:

Price To Beat (PTB) — the opening reference price. Final price > PTB → Up wins; otherwise Down.
Outcome — once the window closes, the market settles Up or Down.

Here's the part that surprises everyone: for crypto markets, neither number is in the public API in a way you can actually use to trade. This is where they live, and how to read the outcome about 20 seconds after close instead of waiting minutes for on-chain settlement.

The API gap is real (and specific)

Polymarket does expose an opening-price endpoint — but only for non-crypto:

GET https://polymarket.com/api/equity/price-to-beat/{slug}   # stocks, FX, gold, oil

For crypto Up-or-Down windows there is no public PTB endpoint. And the settled Outcome? Neither the Gamma API (gamma-api.polymarket.com) nor the CLOB API (clob.polymarket.com) returns it quickly — on-chain Chainlink settlement can take 5–10 minutes for a 5-minute market. By then your window is long gone.

The outcome isn't in the HTML, either

The obvious move — curl the event page and parse it — doesn't work:

Source	Can you read the outcome?
On-chain oracle (`closed` / `outcomePrices`)	Authoritative, but lags by minutes
Raw HTML (`curl` the page)	No — "Outcome: Up" isn't in the HTML, any XHR, or `__NEXT_DATA__`
Front-end render	Yes — React shows it within ~20s of close ✅

The frontend computes the result client-side from a live oracle pipe and paints it into the DOM. It's never in a response you can fetch directly. So the reliable approach is to become the front-end.

Become the front-end: headless Chromium

Load the page in headless Chromium (Playwright), let React render, then poll the DOM inside the browser until the outcome text appears:

import asyncio
from polymarket_ptb_scraper import PolymarketScraper

async def main():
    async with PolymarketScraper(asset="btc", window="5m") as s:
        t_start = s.previous_window_start()
        r = await s.fetch(t_start)
        if r.success:
            print(f"{t_start}: {r.outcome.upper()}  PTB=${r.ptb}  final=${r.final_price}")

asyncio.run(main())
# BTC 1778839200: DOWN  PTB=80478.47  final=80470.32

Three things make this fast and stable in production:

In-browser polling — page.wait_for_function() at 100ms looking for /Outcome:\s*(Up|Down)/, so it resolves the instant the text renders, not on a fixed Python-side timer.
SPA navigation — Polymarket is Next.js, so page.goto(next_slug) is a client-side route change (JS/CSS stay cached) — roughly 5× faster than page.reload().
Resource interception — block images/fonts/media and known analytics domains, but never block first-party JS/CSS or React won't render.

Add backoff-retry to a deadline and a periodic browser recycle (Chromium leaks a few MB per fetch) and it stays under ~300 MB RSS for hours.

The catch across timeframes: the slug

The scrape is the easy part. Building the URL is where most people get stuck, because the periods don't share a slug format:

Period	Slug	Derivable from a timestamp?
5m / 15m / 4h	`{asset}-updown-{w}-{t_start}` (`t_start % w == 0`)	✅ yes
1h	`bitcoin-up-or-down-may-29-2026-10pm-et`	❌ human-readable date slug
1d	`what-price-will-bitcoin-hit-on-may-29`	❌ different market shape

So a deterministic builder covers 5m/15m/4h, but 1h and 1d need a slug-discovery step (look the event up by date via the Gamma events API, then feed its slug to the scraper) — and the daily is a different price-target market type entirely.

The free build

The open-source version covers the 5m / 15m windows for BTC/ETH/SOL/XRP/DOGE — point it at a market, get back outcome, ptb, final_price:

https://github.com/BlueWhale-Quant-Lab/Polymarket-crypto-updown-PTB-Outcome-Scraper

It's a clean, dependency-light reference (Playwright only) and fully standalone — no API keys, no accounts.

When you need every coin and every timeframe

The free build stops at 5m/15m on purpose — that's the part you can derive from docs. When you hit the 1h / 4h / 1d markets you run into the slug-discovery problem above, plus the daily's noon-ET / different-market-shape edge cases. I packaged the complete version — all coins, all timeframes (5m / 15m / 1h / 4h / 1d) with the slug discovery and the period quirks handled — here:

Polymarket PTB & Outcome Scraper PRO — All Coins, All Timeframes

Good to know

The rendered label is an early indicator (~20s), not the final on-chain settlement. If correctness is critical, reconcile against the oracle once it lands — the free build covers the fast read completely; the on-chain reconcile is your call.
It reads public, already-rendered content. Keep request rates modest (12 fetches/hour per window has never been rate-limited in testing) and respect Polymarket's Terms of Service.
If Polymarket changes its markup, the outcome regex is the one place to update.
This is a data primitive — it reads PTB and outcome. It does not place trades or promise profit; what you build on top is yours.

Takeaway

For crypto Up/Down, the API won't hand you the PTB or a timely outcome — but the front-end already computes both, and you can read them ~20s after close by rendering the page yourself. The only real complexity is the slug across timeframes; solve that and you have a clean data feed for the whole BTC/ETH/SOL/XRP/DOGE board.

Building a Low-Latency Polymarket Trading Bot in Python (py-clob-client + WebSocket)

BlueWhale-Quant-Lab — Thu, 04 Jun 2026 06:13:16 +0000

This is a hands-on guide to a low-latency Polymarket trading bot in Python. We'll wire up py-clob-client for orders, the CLOB WebSocket feed for real-time book updates, and cover the infrastructure decision that beats every code optimization combined.

Architecture

WebSocket feed  ──►  strategy logic  ──►  REST place/cancel  ──►  Polygon settlement
 (perceive,            (your edge)         (act, warm conn)
  ~1.2 ms info)

Two channels: WebSocket to perceive (push, no polling lag) and REST to act (place/cancel orders). Keep both warm.

Step 0: host near the order book (the biggest lever)

Polymarket's CLOB API answers from Amsterdam. I benchmarked it: ~1.2 ms from an AMS box vs ~88 ms from US-East. Before any code, deploy your bot in an Amsterdam-metro datacenter — that single choice is worth ~90 ms, more than anything below.

Sanity check from your server:

curl -s -o /dev/null -w "connect=%{time_connect} ttfb=%{time_starttransfer}\n" \
  https://clob.polymarket.com/

I run mine on a modest AMS VPS (bots are network-bound, so a few cores + NVMe is plenty): the Amsterdam VPS I run the bot on
Disclosure: affiliate link, I earn a referral. It's the box producing the 1.2 ms.

Step 1: authenticate with py-clob-client

from py_clob_client.client import ClobClient

HOST = "https://clob.polymarket.com"
client = ClobClient(HOST, key=PRIVATE_KEY, chain_id=137)  # Polygon
creds = client.create_or_derive_api_creds()
client.set_api_creds(creds)

Reuse this client. Don't reconstruct it per order — you'd pay a fresh TCP + TLS handshake every time. One warm client = keep-alive = you pay TLS once.

Step 2: place and cancel orders

from py_clob_client.clob_types import OrderArgs
from py_clob_client.order_builder.constants import BUY, SELL

def place(token_id, price, size, side=BUY):
    order = client.create_order(OrderArgs(
        token_id=token_id, price=price, size=size, side=side))
    return client.post_order(order)

def cancel(order_id):
    return client.cancel(order_id)

Step 3: perceive via WebSocket (no polling)

Polling GET /book makes your view as stale as your loop interval. Subscribe instead:

import asyncio, json, websockets

WS = "wss://ws-subscriptions-clob.polymarket.com/ws/market"

async def stream(token_ids, on_update):
    async with websockets.connect(WS, ping_interval=20) as ws:
        await ws.send(json.dumps({"assets_ids": token_ids, "type": "market"}))
        async for raw in ws:
            on_update(json.loads(raw))   # 'book' snapshots + 'price_change' deltas

(Endpoints/params evolve — verify against current Polymarket docs.)

Step 4: the reactive loop

def on_update(msg):
    book = maintain_local_book(msg)      # apply snapshot/deltas
    signal = strategy(book)              # YOUR edge — keep it lean
    if signal:
        place(signal.token_id, signal.price, signal.size, signal.side)

asyncio.run(stream([TOKEN_ID], on_update))

Once the network is ~1.2 ms, you can become the bottleneck. Keep strategy() tight; push logging/analytics off the hot path; avoid per-tick allocations and JSON re-parsing.

Step 5: don't get throttled

The CLOB enforces rate limits (check current docs). Rules of thumb:

Get data over WebSocket, not REST — save your REST budget for orders.
Batch cancels when the market moves; pulling stale quotes is the priority.
Handle 429 with backoff.

Recap

Host in Amsterdam (~90 ms win).
Reuse a warm py-clob-client (keep-alive/TLS).
Perceive over WebSocket, act over REST.
Keep your decision path lean.
Respect rate limits.

Get step 0 right and the rest is incremental. Skip it and no amount of clever code makes you competitive.

Latency figures from my own 2026 tests; code is illustrative — verify against current docs. Not financial advice.

I Measured Polymarket's API Latency From 5 Regions — Here's the Script and the Results

BlueWhale-Quant-Lab — Thu, 04 Jun 2026 04:17:48 +0000

TL;DR — I benchmarked round-trip latency to Polymarket's CLOB order API (clob.polymarket.com) from five VPS regions. Amsterdam: ~1.2 ms. US-East: ~88 ms. The script is below — run it yourself.

If you build trading bots, you eventually ask: where is the order book I'm racing other bots to hit? For Polymarket, every Reddit answer is a guess and nobody posts numbers. So I measured it.

Why latency to the order book matters

Polymarket runs an off-chain Central Limit Order Book (CLOB) that matches orders, then settles on Polygon. When a market moves, bots race to the same fill — and your round-trip time to the CLOB is, mechanically, your place in line. Code optimization is rounding error next to physical distance to the endpoint.

The benchmark script

ICMP ping lies behind CDNs, so I measure the TCP connect and time-to-first-byte on a real HTTPS request — far more honest for a web service.

import socket, ssl, time, statistics, http.client

HOST = "clob.polymarket.com"
N = 100

def tcp_connect_ms():
    start = time.perf_counter()
    s = socket.create_connection((HOST, 443), timeout=5)
    dt = (time.perf_counter() - start) * 1000
    s.close()
    return dt

def ttfb_ms():
    ctx = ssl.create_default_context()
    start = time.perf_counter()
    conn = http.client.HTTPSConnection(HOST, 443, timeout=5, context=ctx)
    conn.request("GET", "/")
    resp = conn.getresponse()
    resp.read(1)                       # first byte
    dt = (time.perf_counter() - start) * 1000
    conn.close()
    return dt

def bench(fn, n=N):
    xs = sorted(fn() for _ in range(n))
    return {
        "p50": round(statistics.median(xs), 2),
        "p99": round(xs[int(n * 0.99) - 1], 2),
        "min": round(xs[0], 2),
    }

print("TCP connect:", bench(tcp_connect_ms))
print("TTFB       :", bench(ttfb_ms))

Run it on whatever box you've got, then on a box in another region, and compare. That delta is the whole story.

The results

VPS region	ICMP ping (p50)	TCP connect (p50)	TTFB (p50)
Amsterdam (AMS)	~1.2 ms	~1.4 ms	~6 ms
Frankfurt	~8 ms	~9 ms	~16 ms
London	~10 ms	~11 ms	~19 ms
US-East (Virginia)	~88 ms	~90 ms	~110 ms
Singapore	~165 ms	~168 ms	~195 ms

What the 1.2 ms means (and what it doesn't)

A 1.2 ms round trip is near-LAN. Light in fiber covers ~200 km per millisecond round-trip, so 1.2 ms means the endpoint is within ~100 km of my Amsterdam box. Across the Atlantic it's physically impossible — hence US-East's ~88 ms.

Being precise about the claim:

✅ Proven: the CLOB order API's point of presence is in Amsterdam.
🤔 Inferred: that the matching engine itself is co-located (the ~6 ms TTFB on order-book requests is consistent with local matching, but I can't see inside their stack).

Either way the actionable conclusion is identical: to minimize latency to Polymarket, host in Amsterdam. US-East — the most common guess — is ~90 ms slower, which no code change recovers.

What I run

My bot lives on a modest VPS in a real Amsterdam-metro datacenter — that's what produces the 1.2 ms. Specs barely matter (a Polymarket bot is network-bound, not CPU-bound); the city is the entire trick. A "Europe" box that actually sits in Frankfurt costs ~8 ms instead.

The provider/plan I use: HostKey — Amsterdam VPS/dedicated

Disclosure: that's an affiliate link — I earn a referral if you sign up. I pay for and use the same box; the 1.2 ms above is from it.

Try it

Spin up an hourly box in Amsterdam and one in US-East, run the script on both, and watch the ~90 ms gap. If a region labeled "EU" pings >5 ms, it isn't really in Amsterdam — that's your proof to look elsewhere.

Numbers are from my own 2026 tests and will drift as Polymarket scales. Re-measure before betting money on it. Not financial advice.

If this was useful, I'm writing more on building low-latency Polymarket bots in Python — follow along.

What it takes to run a Polymarket Up/Down arbitrage bot in production

BlueWhale-Quant-Lab — Wed, 03 Jun 2026 14:37:58 +0000

A "risk-free" arbitrage on Polymarket's crypto Up/Down markets is easy to describe and hard to actually run. The edge — the cross-cycle sandwich — is real, but the money is won or lost in execution. Here's the engineering that turns the idea into a bot that survives production, and the specific things that break if you skip them.

The edge in two sentences

Polymarket runs Up/Down markets on the same asset across cycles (5m/15m/1h/4h/1d). Two cycles that settle at the same time share one final price but have different strikes (the per-cycle "price to beat"). Buy UP on the lower strike and DOWN on the higher strike: at least one leg always wins, and if the settlement price lands between the two strikes, both win. If the legs cost under $1.00 combined, that's a structural edge — on paper.

total_cost = up_price_low_strike + down_price_high_strike
edge = total_cost < 1.00          # at least one leg pays $1 -> can't lose if both fill

The phrase that matters is "if both fill." Everything below is about that.

Problem 1 — direction is the whole game

Assign the sides from the strikes: UP on the lower PTB, DOWN on the higher. Get it backwards and the middle band — the region you most want — loses both legs (a "death sandwich"). So the bot's correctness hinges on a trustworthy price-to-beat per cycle, and the per-cycle rules are not uniform:

5m/15m/4h: the Chainlink price pushed at the cycle open.
1h: the Binance 1-hour candle Open.
1d: the Binance 1-minute candle Close at the noon-ET boundary (DST-aware).

A PTB that locks a second or two late can already have drifted enough to flip which strike is "lower." So you gate on lock delay and refuse to fire on a stale strike.

Problem 2 — fire both legs, fast, together

Two legs posted seconds apart is two chances for the market to move between them, leaving you one-sided. The fix is boring but essential: one keep-alive connection, TCP_NODELAY, and asyncio.gather so both orders hit the book within milliseconds.

results = await asyncio.gather(place(leg_up), place(leg_down))

Problem 3 — when only one leg fills

It will happen. Now you hold a naked leg and must top up the other side — and this is where bots quietly hemorrhage:

Overbuy loop. Size the top-up from the positions API and it lags (reads 0), so you resubmit, it fills, reads 0 again... A real run targeted 4.29 shares and bought 37.5. Size from an internal fill tally, never a lagging read.
Fee drift. Fees mean the two legs never match to the exact share — use a tolerance band instead of chasing crumbs.
The $1 floor. Orders under ~$1 notional are rejected; a 1-share crumb loops forever on invalid amount. Below the floor, let it settle.

Problem 4 — timeouts must not double-fill

On an HTTP timeout, the naive retry resubmits the order. If the first one actually landed, you've now got double exposure. Confirm against /data/trades before any resubmit; treat a timeout as "unknown," not "failed."

Problem 5 — the 2026-04 SDK migration

Late April 2026, Polymarket shipped a V2 SDK that broke older bots two ways. If yours started failing then, this is why:

# order_version_mismatch -> the wire body must be built by order_to_json_v2
from py_clob_client_v2.order_utils.model.order_data_v2 import order_to_json_v2
body = order_to_json_v2(signed, api_key, OrderType.GTC.value, False, False)

# 'not enough balance / allowance' (with funds!) -> sync the cache once at startup
client.update_balance_allowance(params=BalanceAllowanceParams(asset_type=AssetType.COLLATERAL))

The old hand-built {order, owner, orderType} body is dead, and the CLOB caches balance=0 after a deposit until you force a re-read.

The honest part

With cost < 1 and both legs filled, a pair can't lose. The risk is execution — one-sided fills, slippage, the gap between your two orders, rate limits while you scan and fire. A production engine is mostly machinery for shrinking that risk: direction lock, concurrent posting, a hedge/overbuy guard, timeout idempotency, and staying under the API limits. It is not a money printer; prediction-market trading can lose money, and you should paper-test before risking real funds.

The complete engine

Everything above — three execution routes (immediate / pre-place / downstream-lock), the dual engine (arbitrage + strangle), the hedge-leg hound for one-sided fills, live Oracle + market WebSockets, timeout idempotency, and both 2026-04 SDK fixes (order_to_json_v2 + startup update_balance_allowance) wired in — is the ready-to-run V25 build. Bilingual, configurable, fill your keys and run:

https://bluewhalequantlab.gumroad.com/l/polymarket-updown-sandwich-bot-v25

Respect that the strategy is the easy 20% and the execution is the other 80%.

Fix Polymarket order_version_mismatch and not-enough-balance (2026-04 SDK upgrade)

BlueWhale-Quant-Lab — Wed, 03 Jun 2026 01:16:23 +0000

If your Polymarket Up/Down bot started throwing order_version_mismatch or not enough balance / allowance (with funds in your wallet) in late April 2026, you hit the V2 SDK upgrade. Here are both fixes, plus a minimal PTB → signal → order quickstart.

Fix 1 — `order_version_mismatch`: serialize with `order_to_json_v2`

The order wire body changed. The old hand-built JSON ({"order": ..., "owner": ..., "orderType": ...}) is rejected. Serialize the signed order with order_to_json_v2 from py_clob_client_v2 — the V2 wire adds timestamp/metadata/builder, postOnly/deferExec, and an integer salt.

from py_clob_client_v2.order_utils.model.order_data_v2 import order_to_json_v2
signed = client.create_order(OrderArgs(price=p, size=s, side="BUY", token_id=tid))
body   = order_to_json_v2(signed, client.creds.api_key, OrderType.GTC.value, False, False)
# POST `body` to /order with create_level_2_headers(...)

Fix 2 — `not enough balance / allowance`: sync once at startup

After a deposit, the on-chain balance updates but the CLOB cache doesn't refresh — get_balance_allowance returns balance=0 and orders are rejected. Force a re-read once at startup:

from py_clob_client_v2 import BalanceAllowanceParams, AssetType
client.update_balance_allowance(params=BalanceAllowanceParams(asset_type=AssetType.COLLATERAL))

The strategy it powers — cross-cycle sandwich

Two Up/Down markets on the same asset settling at the same time but on different cycles (5m/15m/1h/4h/1d) have different strikes (PTB). Buy UP on the lower strike and DOWN on the higher strike: at least one leg always wins, and if settlement lands between the strikes, both win (~2×). Under $1.00 combined, it's a structural edge — the real risk is execution.

from polymarket_updown_quickstart import Leg, sandwich_signal
sandwich_signal(Leg("15m", ptb=70000, up_price=0.55, down_price=0.47),
                Leg("1h",  ptb=70120, up_price=0.50, down_price=0.44))
# -> buy UP on 15m + DOWN on 1h, total_cost 0.99, edge=True, sweet_band (70000,70120)

Repo (free, MIT, 8 tests, runnable demo):
https://github.com/BlueWhale-Quant-Lab/polymarket-updown-arbitrage-quickstart

From quickstart to a running bot

The quickstart is the minimal shape. A real deployment also needs live price/orderbook feeds, multiple execution routes, a hedge guard for one-sided fills, timeout idempotency, and rate-limit handling. If you want the complete, ready-to-run engine with both SDK fixes wired in, there's a full V25 build — but the quickstart above stands on its own for learning the flow.

Takeaway

Post-April-2026 Polymarket: build order bodies with order_to_json_v2, and call update_balance_allowance once at startup. Those two lines unbreak most Up/Down bots.

The Polymarket cross-cycle sandwich: a structural arbitrage in Up/Down markets

BlueWhale-Quant-Lab — Tue, 02 Jun 2026 17:45:48 +0000

Search "Polymarket arbitrage" and you mostly find cross-venue bots (Kalshi vs Polymarket) or the textbook buy-YES-and-NO trade. There's a different edge hiding inside Polymarket's own crypto Up/Down markets — the cross-cycle sandwich. Here's the strategy from first principles, with an open-source scanner.

The key observation

Polymarket runs Up/Down markets on the same asset across cycle lengths: 5m, 15m, 1h, 4h, 1d. Two cycles of different lengths can end at the same wall-clock time (t_end). They then settle against the same final price P — but because they opened at different times, each has its own price to beat (PTB / strike).

That difference in strikes, for the same asset settling on the same P, is the opportunity.

The trade

Two same-t_end contracts with PTB_low < PTB_high. Buy:

UP (Yes) on the low-PTB contract, and
DOWN (No) on the high-PTB contract.

Where `P` lands	UP wins (`P>PTB_low`)	DOWN wins (`P<PTB_high`)	legs paid
`P > PTB_high`	yes	no	1
`PTB_low < P < PTB_high`	yes	yes	2 (sweet)
`P < PTB_low`	no	yes	1

At least one leg always pays $1/share. So if the two legs cost total_cost < $1.00 per share, you collect ≥ $1 against a < $1 cost in every region — a structural arbitrage — and in the middle band you're paid on both (~2×).

The trap: the death sandwich

Reverse the direction (UP on the high strike, DOWN on the low) and the middle band — the region you most want — loses both legs. Direction is everything, which is why a reliable price-to-beat is non-negotiable.

The 5-minute pruning trick

Only 5m cycles opening at :10/:25/:40/:55 end on a 15-minute boundary and can share a t_end with the bigger cycles. The other ~67% can never pair — prune them before scanning.

The scanner

from polymarket_sandwich import find_pairs, settle_pair
pairs = find_pairs(contracts)          # cross-cycle, pruned, direction-correct, ranked
best  = pairs[0]
best.total_cost                        # e.g. 0.99 -> arbitrage
best.sweet_band                        # (PTB_low, PTB_high)
settle_pair(best, 70060, shares=10)    # {'sweet': True, 'winners': 2, 'pnl': 10.1}

Repo (free, MIT, 13 tests, worked example):
https://github.com/BlueWhale-Quant-Lab/polymarket-cross-cycle-sandwich-arbitrage

The honest part

With cost < 1 and both legs filled, the pair can't lose. The real risk is execution — getting one leg but not the other, the price moving between your two orders, slippage, rate limits. That's the engineering, not the payoff, and it's what the rest of the toolkit (price-to-beat, live feed, order book, execution, hedge guard, rate limiter) and the complete multi-route engine handle.

Takeaway

Same asset, same settlement time, two different strikes → UP on the low strike, DOWN on the high strike; under $1 total and you've got a structural edge, with the band between strikes as your double. Get the direction from a real PTB, and respect that the hard part is execution.

Polymarket rate limits are per 10 seconds, not per second (and 429 traps)

BlueWhale-Quant-Lab — Tue, 02 Jun 2026 17:08:33 +0000

If you've hit 429 Too Many Requests on the Polymarket APIs, the fix isn't just "slow down" — it's understanding how the limits are shaped and giving your client the right tooling. Here are the traps and a small open-source limiter.

Trap 1: the window is 10 seconds, not 1

Polymarket's published limits use a 10-second window (trading also has a 10-minute sustained cap):

Endpoint	Limit
`/book`, `/price`, `/midpoint`	1,500 / 10s
`/books`, `/prices`	500 / 10s
POST/DELETE `/order`	5,000 / 10s burst (120,000 / 10 min)
DELETE `/cancel-all`	250 / 10s

So /book is 150 req/s sustained with a burst of 1,500 — not "1500/s", and not "150/s with no burst". A token bucket models this exactly: refill max / window per second, capacity max.

rate, burst = 1500 / 10, 1500   # 150 tokens/sec, cap 1500

Trap 2: authenticated GETs throttle much earlier

The published numbers are for public market-data endpoints. Authenticated reads (e.g. polling a single order) get throttled far below that — around ~10/s once you're also placing and cancelling. Budget authed reads conservatively; don't assume the 1,500/10s ceiling applies.

Trap 3: a fresh connection per request

Every call that opens a new TCP+TLS connection is slow and leans harder on the limiter. Reuse one keep-alive connection (or a small pool). TCP_NODELAY and GC control are the rest of the latency story.

Trap 4: no Retry-After / backoff

The docs say over-limit requests are "throttled rather than rejected" — but in practice you do see 429. Honor Retry-After when present (it can be an integer or an HTTP date), and otherwise back off exponentially with jitter:

from polymarket_rate_limit import parse_retry_after, should_retry, backoff
if should_retry(resp.status):                       # 429 or 5xx
    time.sleep(backoff(attempt, retry_after=parse_retry_after(resp.headers)))

The limiter

I packaged the documented limits, a per-endpoint token bucket, the Retry-After parser, and correct backoff into a zero-dependency MIT module (injectable clock, fully tested):

from polymarket_rate_limit import RateLimiter
lim = RateLimiter()
wait = lim.acquire("/price")     # 0 if you may send now, else seconds to wait
if wait: time.sleep(wait)

Repo (free, MIT, 15 tests):
https://github.com/BlueWhale-Quant-Lab/polymarket-api-rate-limit-429-handler

The speed side — keep-alive pooling, TCP_NODELAY, GC control, TLS prewarm, and a p50/p99 latency benchmark — is a complete version, but the limiter above stands on its own.

Takeaway

Model the 10-second window as a token bucket, rate-limit authed GETs conservatively, reuse connections, and honor Retry-After.

How a Polymarket bot buys 37 shares when it wanted 4 (the overbuy loop)

BlueWhale-Quant-Lab — Tue, 02 Jun 2026 13:09:33 +0000

If you run a two-sided or arbitrage bot on Polymarket, you've probably hit this: one leg of a paired position fills, the other doesn't, and when you top up the missing leg your bot buys way more than you asked for. A real run targeted 4.29 shares and ended up holding 37.5 — an 8.7× overbuy. Here's how it happens and how to stop it.

The overbuy loop

You hold a naked leg and want to top up the hedge side, so you ask "how much do I already hold?" via the positions API and buy the difference.

The trap: the indexer lags. For a few seconds after a fill it still reports your old balance — often 0. So:

You place a GTC top-up for the full size. It fills instantly.
You re-check positions → still 0.
Thinking nothing filled, you place the full size again. Fills again.
Repeat until the indexer catches up — by which point you're multiples over.

The positions API is fine for reconciliation; it's the wrong thing to size a hot re-submit loop against.

The fix: an internal tally

Size every attempt from your own running total of fills, updated the instant an order response reports one:

internal_filled = 0.0
def on_fill(shares):           # call with takingAmount from each order/poll response
    global internal_filled
    internal_filled += shares

remaining = max(0.0, target_shares - internal_filled)   # never re-buy what you hold

Clamp at zero so an over-fill can never produce a negative "buy more".

Two more traps in the same path

Fee drift. Buy 8 shares; fees leave you ~7.9 received while the other leg sits at 8.4. They never reconcile to the exact share, so "keep topping up until equal" never terminates. Use a tolerance band — within ~2%, call it balanced.

The $1 floor. Polymarket rejects orders under ~$1 notional. A 1-share top-up at $0.53 loops on invalid amount. Below the floor, leave the crumb to settle.

Chasing it to a fill

Once you know the size, you still have to land it on a venue that moves. The production pattern separates two cadences: poll ~5s to absorb fills, reprice ~30s to nudge your bid toward a cost ceiling — chasing only the remaining shares each round, and refusing to launch a second chaser for a leg that already has one (a duplicate doubles your exposure).

The library

I packaged the sizing math (shortfall + tolerance, the $1 floor, overbuy-safe remaining_to_buy, a cost ceiling, and a one-call plan_hedge) into a zero-dependency MIT module:

from polymarket_hedge_leg import plan_hedge
plan_hedge(20.0, 6.75, hedge_price=0.46, primary_cost=0.49, max_total_cost=0.95)
# {'need_shares': 13.25, 'ok': True, 'skip_reason': None, 'est_cost': 6.095}

Repo (free, MIT, 19 tests):
https://github.com/BlueWhale-Quant-Lab/polymarket-hedge-leg-overbuy-guard

The async hound that chases the leg to a fill — with the overbuy-safe accounting and a dedup registry — is a complete version, but the sizing math above stands on its own.

Takeaway

Never size a re-submit from a lagging positions read. Keep an internal fill tally, add a tolerance band for fees, and respect the $1 floor.

DEV Community: BlueWhale-Quant-Lab

Polymarket CLOB WebSocket in Python — Real-Time Order Book Without Polling

Why WebSocket beats polling

Connect and subscribe

Maintain a local book from snapshot + deltas

Wire it together

Measure your information lag

The ceiling you can't code around

Robustness checklist

Recap

How to Benchmark API Latency to Any Endpoint (Polymarket Case Study)

Why ping lies

A proper latency harness (Python)

Read p99 and jitter, not just the average

The case study: where is Polymarket's CLOB?

Turning the benchmark into a decision

Reusable checklist

Polymarket's Price-to-Beat Has No API — Why a Co-located Server Gets It in Real Time, Not 15 Seconds

What the price-to-beat actually is

The two ways to get it — and why one is 15 seconds too slow

Why co-location makes your PTB match Polymarket's

Why this matters most at T0

The setup

Heads-up

Bottom line

How to get the Polymarket Price To Beat at T0 - the open price the instant the window opens

How to get the Polymarket Price To Beat at T0 — the open price the instant the window opens

"Read it off the page" comes too late

Where the open price actually comes from (it depends on the cycle)

The boundaries aren't all UTC

Don't read the daily candle early

One async call at T0

Two complementary approaches

Good to know

Takeaway

How to read a Polymarket Up/Down outcome (and the Price To Beat) before the oracle settles

How to read a Polymarket Up/Down outcome (and the Price To Beat) before the oracle settles

The API gap is real (and specific)

The outcome isn't in the HTML, either

Become the front-end: headless Chromium

The catch across timeframes: the slug

The free build

When you need every coin and every timeframe

Good to know

Takeaway

Building a Low-Latency Polymarket Trading Bot in Python (py-clob-client + WebSocket)

Architecture

Step 0: host near the order book (the biggest lever)

Step 1: authenticate with py-clob-client

Step 2: place and cancel orders

Step 3: perceive via WebSocket (no polling)

Step 4: the reactive loop

Step 5: don't get throttled

Recap

I Measured Polymarket's API Latency From 5 Regions — Here's the Script and the Results

Why latency to the order book matters

The benchmark script

The results

What the 1.2 ms means (and what it doesn't)

What I run

Try it

What it takes to run a Polymarket Up/Down arbitrage bot in production

The edge in two sentences

Problem 1 — direction is the whole game

Problem 2 — fire both legs, fast, together

Problem 3 — when only one leg fills

Problem 4 — timeouts must not double-fill

Problem 5 — the 2026-04 SDK migration

The honest part

The complete engine

Fix Polymarket order_version_mismatch and not-enough-balance (2026-04 SDK upgrade)

Fix 1 — order_version_mismatch: serialize with order_to_json_v2

Fix 2 — not enough balance / allowance: sync once at startup

The strategy it powers — cross-cycle sandwich

From quickstart to a running bot

Takeaway

The Polymarket cross-cycle sandwich: a structural arbitrage in Up/Down markets

The key observation

The trade

The trap: the death sandwich

Why `ping` lies

Fix 1 — `order_version_mismatch`: serialize with `order_to_json_v2`

Fix 2 — `not enough balance / allowance`: sync once at startup