How arbitrage bots work on Polymarket, end to end.

ws Market channel

In plain termsA live feed of who wants to buy and sell each side, and at what price, updating moment to moment.

It streams the order book over a WebSocket (a persistent connection that pushes updates instantly, with no repeated polling). The best ask is the lowest price someone will sell at, the bid is the highest someone will buy at, and the mid sits halfway between.

ws User channel

In plain termsWhat you actually own, based on trades that truly executed rather than what you hoped would happen.

A fill is an order that actually traded, in full or in part. Your position and average cost are rebuilt from real fills, never from assumptions, so the bot always knows its true exposure.

rest Gamma API

In plain termsA lookup service that hands you the basic facts about a market before you trade it.

It returns the token ids to subscribe to (each outcome is its own token), the tick (the smallest price step a market allows, for example one cent), and the neg_risk flag that selects the correct on-chain Merge path.

rest Order lifecycle

In plain termsThe calls that place, cancel, and batch your orders, plus one easy-to-forget setup step.

CLOB V2 (the exchange's order-matching system) needs a /balance-allowance/update call to sync on boot, and again after funding, before any order is accepted. Skipping it is the top cause of silent V2 failures.

chain CTF contract

In plain termsThe on-chain tool that turns your matched shares back into spendable cash so you can keep trading.

On Polygon, you Merge a pair of opposite shares back into $1 to recycle capital early, and you Redeem after the market resolves to collect the winning side.

opt Edge enhancers

In plain termsExtra information a bot can bolt on to trade smarter, though none of it is required for a first working build.

Examples include a live score or game-clock feed, or a reference book from another venue like Pinnacle or Binance to compare prices against.

① Gate

In plain termsIt refuses any buy that would make a completed pair cost more than your target, so a finished pair always profits.

If price > C − avg(other) the buy is rejected, where avg(other) is what you have already paid per share on the opposite side.

② Eligibility

In plain termsEvery buy needs a real reason: either to even out a lopsided position, or to genuinely lower your average cost.

A buy must build toward balance (move the two sides closer to equal) or be a true average-down, priced below your current average by at least the edge you require. No reason means no buy.

③ Imbalance cap

In plain termsIt stops the bot from piling onto one side and quietly turning into a directional bet.

A buy that does not move toward balance is refused once |qA − qB| ≥ imb, where qA and qB are your share counts on each side and imb is the cap on how far apart they may drift.

Buy the dip freshTrough

The price just set a new low for this side, the cheapest it has been since the last buy here. That signals a real dip rather than ordinary jitter, so the bot steps in while the discount is genuinely on the table, before the price ticks back up.

Grab a bargain deep

The price has fallen so far below the ceiling that the profit this buy locks in, its edge, is unusually large: at least six cents per pair. A discount that big is worth taking right away, so this trigger overrides the usual patience and buys immediately.

Rebalance on patience patient

No dramatic dip, but two things are true at once: enough time has passed since the last buy (the patience window), and the bot holds fewer shares of this side than the other. It tops up the lagging side to complete more pairs, rather than sitting idle waiting for a dip that may never come.

How much to buy

Once a buy fires, its size scales with the opportunity. The base order (the clip) grows up to five times larger as the discount deepens, so the best prices get the most capital. It can also jump to close a gap when one side has fallen behind. Then, as the capital already deployed in a market approaches its budget, every order tapers down, so the bot eases off the gas rather than going all in.

The one hard stop

Everything above is soft pacing: gentle nudges up or down. There is exactly one absolute refusal. Once the capital deployed in a single market reaches three times its budget, no new buys are allowed, period. It is the backstop that caps how much can ever be at risk in one market.

Merge · before resolution

One A share plus one B share is a complete set, and a complete set is always worth exactly $1: whichever side wins pays $1, the other pays $0. The on-chain Merge operation (mergePositions) burns a complete set and returns $1 in collateral (pUSD) right away, with no need to wait for the market to resolve. The neg_risk flag only decides whether that Merge routes through the standard contract or the NegRiskAdapter.

How many pairs can you Merge? Exactly min(qA, qB), the smaller of your two share counts, where qA is the shares of A you hold and qB the shares of B. A pair needs one of each, so the number of complete pairs you own is simply whichever side you hold less of. Merging those pairs locks in their profit and frees the cash to redeploy, leaving only the surplus on the heavier side as open inventory. Bots batch their Merges so the Polygon gas cost stays small next to the capital freed.

Redeem · after resolution

Whatever inventory is left when the market settles, the unmatched surplus on one side, is cashed out with the Redeem operation (redeemPositions). Once the oracle reports the result, Redeem pays $1 for each winning share and $0 for each losing share.

Capital stays locked inside a position until you Merge it or Redeem it: those are the only two ways to turn shares back into cash. Merge is the early exit for pairs you have already hedged, and Redeem is the final settlement for everything still open at the end.

Imbalance cap

In plain termsIf you keep buying one side more than the other, you are quietly making a directional bet. This cap limits how lopsided your two stacks of shares can get, so you stay hedged instead of gambling on an outcome.

Stop adding to the heavy side once the gap hits the limit: |qA−qB| ≥ imb bounds directional exposure (the part of your position that wins or loses with the market).

Per-market capital

In plain termsA ceiling on how much you put into any single market, so one trade cannot sink you. The bot slows down as it nears the planned amount, and flatly refuses to go far past it.

Soft taper as you approach budget; hard refuse at 3 × budget.

Trend kill

In plain termsArbitrage assumes prices wobble around a fair value and come back. If the price just keeps marching one way, that assumption is broken and the bot should stop opening positions.

If signed flow (net buying pressure, with direction) stays beyond 2σ (two standard deviations, an unusually large move) with no reversion, stop initiating and Merge what exists.

Daily loss limit

In plain termsA hard stop for the day. Once total losses reach a set ceiling, the bot shuts off new trades so a bad day cannot become a disaster.

Global circuit breaker. Halt all new intents past the limit.

Fee-adjusted gate

In plain termsA trade that looks profitable before fees can be a loser after them, so the bot checks the after-fee number before committing.

Run C_effective (your ceiling after fees), never raw C, in taker mode (Step 6).

Heartbeat & resolution

In plain termsIf the bot loses its live connection it may be trading on stale prices, so it resyncs first. And once a market is closing out, it stops trading it.

Resync on a heartbeat lapse (a missed "still alive" ping); stop trading once a market enters settlement (the final payout phase).

Fees tighten C, but only for takers

In plain termsFees only hit you when you take an order already resting on the book, not when you post your own. So a patient, maker-style bot can pay nothing.

Fees are taker-only. Resting limit (maker) orders fill free, so a maker bot keeps C_effective = C. Takers pay fee = shares · feeRate · p(1−p), largest near 50¢ and smaller toward the wings. Worst case per pair runs ≈0.015 (sports) to ≈0.035 (crypto), so a taker C=0.99 drops to ~0.95 effective on crypto. Run C_effective = C − fee/pair in taker mode.

Latency

In plain termsBy the time your order reaches the exchange, the cheap price you saw may already be taken. Quote from the live book and cap the price you will accept, so you never chase a fill.

Use the WS book and marketable limits (an order that fills now, but with a price ceiling) with a small buffer. Sports has a multi-second taker delay. Patience, not speed.

Fills & partials

In plain termsYou rarely get your whole order at once. Often only part fills (a partial), so base every decision on what you actually got, not what you asked for.

Model fills against real book depth and re-evaluate on the actual filled quantity. The imbalance cap is enforced on realized shares.

Archetype 1 · temporal pair-cost accumulation

The approach this guide focuses on, run by bots like gabagool, Bonereaper, and the RN1 sports bot. As a taker (someone who takes an existing order off the book, paying for speed), cross the spread the instant the pair-cost math permits, accumulating each side on its own dips. The profit driver is the spread captured across time, hence temporal. One documented gabagool BTC cycle: ~1,267 YES at avg $0.517 and ~1,295 NO at avg $0.449, a pair cost near $0.966, about $58 profit on ~$1,237 deployed in 15 minutes.

Archetype 2 · passive market making

What the open-source poly-maker does. Post resting limit orders just inside the book on both sides and earn the spread plus maker rebates (small payments for adding orders to the book) and liquidity rewards (extra payouts for keeping orders posted near the mid). The profit driver is rebate and reward income, not the spread. Fills are slower and probabilistic, but makers pay zero fees, so the economics are gentler. It is the natural next step beyond the taker approach.

① Game selection

Filter for oscillation, meaning prices that swing back and forth rather than drifting one way: competitive matchups, liquid books, an active reward pool. Avoid blowout-prone games, where one side runs away early and the price never comes back. This is the biggest determinant of survival, and the step most homegrown bots skip.

② Pre-game accumulation

As a maker, rest bids just below the mid on both sides and build a hedged base near 50/50 at close to cost, paid for by rewards and rebates.

③ Tip-off

All resting sports orders auto-cancel at game start. The base inventory carries over, and the bot flips into reactive, in-game, taker-leaning mode.

④ In-game

Apply the gate on every book update. The latency window, the brief lag before everyone sees the same news, is the opening: official feeds update seconds after an event while livestreams lag far longer, leaving stale orders to pick off.

⑤ Recycle

Merge the matched pairs, min(qA, qB) of them, back to pUSD any time before resolution and redeploy. The same dollars round-trip many times, which is why these bots show huge volume relative to their balance.

⑥ Endgame

Prices go extreme, the back-and-forth dies, and any remaining imbalance is a naked directional bet (an unhedged wager on one outcome). Accept small, cheap, capped one-sided inventory. Never force the second leg.