$ cat ./how-it-works

Polymarket's crypto bucket markets price UP/DOWN tokens based on whether an asset will be above or below a strike price at expiry. The bot connects to Binance's aggTrade WebSocket stream for BTC, ETH, SOL, and XRP, computing price deltas in real time. When a move occurs on Binance, there's a window — typically in the hundreds of milliseconds — before Polymarket's CLOB fully reprices.

This isn't because Polymarket's market makers are amateurs — the CLOB has sophisticated participants including designated market makers doing significant volume at low latency. The edge exists because even professional MMs have some requote latency on a prediction market CLOB versus a CEX spot feed. Backtester sweeps show the edge is meaningful at ~200ms of latency and marginal by ~550ms.

The bot uses configurable lookback windows (lookback_secs) and delta thresholds (entry_min_delta) to filter noise from signal. The price_delta(N) function computes the percentage move over N seconds, and the bot only fires when the absolute delta meets the threshold. Deployed configs typically use short lookback windows (2-3 seconds) with tight thresholds.

Worth noting: the edge exists in theory but is hard to capture profitably in practice. Fees and adverse selection eat into the raw signal. The backtester and dry_run mode exist precisely for this — to validate that parameter combinations produce positive expected value after costs before risking real capital.

Every Polymarket bucket market has two tokens: UP and DOWN. At expiry, exactly one pays out $1.00 and the other pays $0.00. This means UP + DOWN must always equal $1.00 at resolution.

The arb strategy checks whether the combined bid prices of UP + DOWN fall below $1.00. When they do — say UP bid at $0.48 and DOWN bid at $0.49 — buying both sides at $0.97 total guarantees a $1.00 payout at resolution, a $0.03 risk-free profit per contract regardless of direction. The bot places both orders together as GTC limits at the bid via batch buy, acting as maker on both sides.

Each bot instance runs one symbol on one time window — it checks whether the combined price is below $1.00 and the spread meets the spread_threshold every tick. To cover multiple assets and windows, you run multiple instances.

The key risk is an adverse fill — only one side executing, leaving you with a directional position. If only one leg fills, the bot cancels remaining unfilled orders after the trade_cooldown_ms elapses and moves on. It doesn't actively unwind the position — instead, a price_bias mechanism biases future bids toward the underweight side, naturally rebalancing the imbalance over subsequent cycles.

Backtesting a trading strategy is only useful if the simulated fills are realistic. The bot includes three fill models, each with different assumptions about how orders get filled:

Deterministic — assumes every order fills instantly at the quoted price. Fast to run and useful for initial strategy screening, but overly optimistic. Real markets have slippage, partial fills, and queue priority. Use this to quickly eliminate bad parameter combinations before running slower models.

Probabilistic — assigns a fill probability based on historical fill rates at each price level. A limit order at the best bid might fill 80% of the time; one tick behind the best bid might fill 40%. This model uses the 6.8 GB historical dataset to calibrate these probabilities per asset and time window.

Latency — the most realistic model. Simulates network round-trip time, order queue position, and the delay between signal detection and order placement. A momentum signal detected at T+0ms might result in an order arriving at T+50ms, by which point the price has already moved. This model produces the most conservative (and accurate) PnL estimates.

You select one fill model per run. The backtester parallelizes across thousands of markets within each run — to compare all three models, run it three times. Strategies that look profitable under the latency model are the ones worth deploying with real capital.

Polymarket's CLOB charges different fees for makers (limit orders that add liquidity) and takers (market orders that remove liquidity). The bot has four execution modes, each optimizing for different market conditions:

single_taker — sends a Fill-Or-Kill order at the ask. Either fills immediately or cancels entirely. The default mode — prioritizes execution speed over fee optimization. Used when capturing a fast momentum signal where certainty of fill matters more than cost.

gtc_at_ask — posts a GTC limit order at the current ask price. If there's resting liquidity at the ask, this crosses the spread and fills as a taker. If not, it sits on the book as a maker until the next evaluation cycle cancels it. The key difference from FOK: if it doesn't fill instantly, it stays rather than cancelling — useful when you want the order to have a chance to fill passively.

single_maker — posts a GTC limit at the bid price (capped at ask - $0.01). Sits on the book as a resting order, only filling when someone crosses into it. Lowest fees but risks never filling, or filling after the price has moved against you (adverse selection).

dual_hybrid — fires both sides simultaneously: a FOK taker on the signal side and a GTC maker on the contra side (opposite direction). This hedges the position at entry rather than escalating from passive to aggressive. Both legs execute concurrently via async join, so latency on one doesn't delay the other.

The bot uses fixed share sizes, not dollar-denominated allocation. Each config specifies momentum_size (shares per directional order, e.g. 10) and max_buy_order_size (max shares per buy, e.g. 20). The bot fires on every qualifying signal within a window — there's no concurrency limit or portfolio-level capital tracking.

This means your wallet balance determines how many orders can fill. With $300-500 in USDC, the pre-tuned share sizes work comfortably across all asset/window combinations. If your wallet runs low, orders will fail on-chain rather than being skipped proactively — the bot has a hardcoded 5-share minimum floor below which it won't submit orders, but it doesn't track remaining capital.

The pre-tuned configs ship with share sizes hand-tuned from backtester parameter sweeps across historical data. You can adjust momentum_size and max_buy_order_size to match your capital — larger sizes for bigger wallets, smaller for conservative starts.

Use dry_run: true to observe order frequency and sizing without risking real capital. This lets you estimate how much USDC the bot would consume per hour before going live.

No strategy works in all market conditions. Transparency about when the bot underperforms is as important as understanding when it excels.

Low volatility — momentum trading needs price moves to generate signals. If the price delta over the lookback window stays below the configured entry_min_delta threshold, the bot skips. During flat markets (common on weekends or between macro events), it may go hours without firing a trade. This isn't a bug — it's the bot correctly waiting for conditions that match its edge.

Tight spreads (arb mode) — the arb strategy profits when UP + DOWN tokens are priced below $1.00 combined. When markets are efficient with tight spreads and active market makers, these dislocations disappear. Note that arb is a separate strategy mode you configure per instance — the bot doesn't dynamically switch between momentum and arb.

Binance feed staleness — if the Binance WebSocket disconnects, the signal goes stale after ~5 seconds. The momentum loop continues running but won't fire new entries since there's no fresh signal — any resting GTC orders stay in place. Binance reconnects automatically via its built-in reconnect loop. SIGTERM sets a shutdown flag and the bot exits cleanly after the current market window.

Regime changes — Polymarket occasionally changes fee structures, adds new assets, or modifies market mechanics. The bot's parameters may need re-tuning when this happens. Re-run the backtester against recent data to find new optimal parameters before deploying updated configs.