ZEIT FINANCE · Building a Polymarket Bot

Part 3 — The Local Mirror

---

Introduction

In Part 2, we architected the Scanner to curate a high-quality tradable universe. Now, we move to the core of the execution engine.

WebSockets often look deceptively simple in a demo: you connect, subscribe, and watch the JSON events roll in. But the first time you wire this data stream into an automated trading system, you encounter an uncomfortable truth:

Messy reality is a dropped packet during a volatility spike. It is an update arriving before its baseline snapshot. It is a single token silently freezing while the rest of the connection looks healthy.

If your bot trades on this corrupted state, you aren't just missing fills—you are manufacturing fake edges and trading against ghosts.

This article details the engineering required to build the Local Mirror: a resilient, self-healing, in-memory representation of the order book that your strategies can actually trust.

---

1. Why Polling Fails (The Physics of Latency)

A common instinct when building a bot is to rely on simple polling: just hit the REST API every second to get the latest prices. While this works for a user interface, it is fatal for an algorithmic trader.

If you poll every second, you are routinely making decisions based on state that is 500ms old—an eternity in high-frequency environments. In arbitrage setups, that stale data is often indistinguishable from a profitable opportunity, baiting your bot into executing orders that will inevitably fail or fill at bad prices.

The Sampling Bias Trap

Markets are continuous streams, not discrete snapshots. A massive liquidity injection or a spread collapse might exist for only 200ms. A polling architecture will miss these transient events entirely, while a WebSocket-based system captures every tick.

---

2. The Mental Model: The Pipeline

Forget "WebSocket Client" as the product. The product is a continuously trustworthy in-memory order book.

To be considered trustworthy, your internal book must be:

This requires viewing your data ingestion not as a simple listener, but as a state management pipeline:

The pipeline starts by fetching a REST Snapshot to establish baseline truth. Once primed, it applies WS Deltas to keep that state current. But critically, it doesn't assume this state remains perfect. Continuous Health Checks monitor for divergence, and if any drift is detected, a Resync is triggered to wipe the slate clean and restore absolute truth.

---

3. The Four Horsemen of Arbitrage Failure

🏇 Horseman #1: The "Delta Before Snapshot" Race Condition

When you first connect, you might receive price_change events before the initial full book snapshot arrives. Applying a "change" to an empty book effectively invents liquidity that doesn't exist.

---

🏇 Horseman #2: The "Ghost Bid" (Silent Death)

A WebSocket connection can appear perfectly healthy—pings are flowing, and most markets are updating—while one specific token silently freezes.

If your system tracks health only at the connection level, it will miss this token-level failure. Your bot will continue trading on a "Best Bid" that disappeared five minutes ago.

---

🏇 Horseman #3: The Reconnect Trap

Brief disconnects are dangerous not because the connection drops, but because of what happens when it returns.

If you reconnect and simply resume processing, you have missed every update that occurred during the outage. Your book is now permanently drifted.

---

🏇 Horseman #4: Backpressure (Process Lag)

Sometimes the socket is fine, but your bot is the bottleneck. If your downstream logic (logging, database writes, complex math) is slower than the incoming data rate, a queue builds up.

You might be processing messages that are technically "valid" but are 500ms old.

---

4. The Defense: Detect, Classify, Heal

To keep strategies from executing on garbage data, we treat the book's health as a formal state machine.

We enforce this via a layered defense system:

---

Layer 1: Continuous Invariants

Every single update triggers a sanity check:

✓	Are bids lower than asks?
✓	Are all sizes positive?
✓	Are the levels ordered correctly?

If any mathematical invariant is violated, we don't try to patch it. We immediately mark the book SUSPECT and trigger a full resync.

---

Layer 2: The Truth Probe

Internal consistency doesn't prove external reality. To catch silent drift, the system should frequently perform a lightweight "Truth Probe":

1. Fetch the top-of-book price from REST
2. Compare it to the in-memory state
3. If they mismatch for more than a few checks → the book is considered drifted

---

Layer 3: Preventive Maintenance

Even if no errors are detected, a production system should periodically resync anyway.

---

5. Observability: KPIs That Matter

If you want observability that actually prevents losses, you need metrics that measure state quality, not just connection status.

---

Summary: Speed is State

By building a resilient Local Mirror that handles snapshots, deltas, and drift, you create the foundation for high-frequency decision making.

---

What's Next

---

Keep Building

---

Continue the Series

---

This article is Part 3 of the ZEIT Finance series on building Polymarket trading bots. ZEIT Finance turns prediction markets into perpetual assets.