Polymarket Fill Risk
polymarket_fill_riskRealizable-vs-theoretical edge check against live CLOB order-book depth — AND Polymarket's own taker fee, which is never zero and is folded in rather than left for you to add (fleet #3446: r/PredictionsMarkets flagged a "clean" fill that quietly omitted it as optimistic in the direction that loses money). REQUIRES one of market (single-market mode) or event (basket/partition mode). SINGLE-MARKET: pass a market slug/URL + side (buy_yes|sell_yes|buy_no|sell_no, default buy_yes) + size_usd (default 1000 — max spend on buys, target proceeds on sells); walks the ladder and returns top_of_book, vwap_fill_price, slippage_pp, shares_filled, max_fillable_usd, verdict (clean|degraded|cannot_fill), fee_schedule ({category, taker_rate, exponent, maker_rebate_rate, fees_enabled, basis} — read off THIS market, never assumed free), fee_usd/fee_pp at the actual VWAP fill, breakeven_win_rate_taker (the win probability your side needs just to cover price + fee — ~51.8% on a 50c crypto taker fill, not 50%), breakeven_win_rate_maker (no fee charged to makers — any rebate is in fee_schedule.maker_rebate_rate), and all_in_cost_pp = slippage_pp + fee_pp. BASKET: pass an event slug/URL + side (sell_yes = capture overround by selling every leg, buy_yes = capture underround; default auto from partition sum) + size_usd interpreted as settlement notional S (shares per leg; each share pays $1); returns theoretical_sum vs realizable_sum (top-of-book vs VWAP across all legs), capture_ratio and profit_usd — both NET of every leg's own Polymarket taker fee (capture_ratio_gross/profit_usd_gross keep the pre-fee figures; per_leg[].fee_usd itemizes each leg, summed as fees_usd_total), per-leg fill detail, thin_legs[], max_clean_notional_usd, and forced_directional_risk naming the legs most likely to strand you unhedged. USE THIS before acting on any polymarket_arbitrage SELL/BUY-EVERY-LEG signal or any polymarket_edges trade above ~$500 — theoretical overround on thin books is not capturable, and partial basket fills convert an arb into an unhedged directional position (the dominant loss mode in real arb-bot P&L). Adverse selection while working resting orders is still not modeled.
Example tool call
This call uses example arguments supplied in the tool’s input schema.
{
"id": 1,
"jsonrpc": "2.0",
"method": "tools/call",
"params": {
"arguments": {
"side": "buy_yes",
"market": "will-the-fed-increase-interest-rates-by-25-bps-after-the-december-2026-meeting-20260729232808636",
"size_usd": 1000
},
"name": "polymarket_fill_risk"
}
}Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| side | No | Single-market: buy_yes | sell_yes | buy_no | sell_no (default buy_yes). Basket: sell_yes | buy_yes (default auto — sell if partition sum > 1, buy if < 1). | |
| event | No | Basket mode: event slug or full polymarket.com URL — checks every leg of the partition. | |
| market | No | Single-market mode: market slug or full polymarket.com URL. | |
| size_usd | No | Single-market: USD to spend (buys) or target proceeds (sells). Basket: settlement notional — shares per leg, each paying $1 at resolution. Default 1000, clamp 10–1,000,000. |
Output Schema
| Name | Required | Description | Default |
|---|---|---|---|
| mode | No | Which mode answered — set by which of market/event was passed. | |
| side | No | Single-market mode: the side actually priced (buy_yes|sell_yes|buy_no|sell_no). | |
| _hint | No | Usage note — what is gross vs net of fees, and what is still unmodeled. | |
| error | No | Error code (orderbook_unavailable, event_books_unavailable, empty_book, bad_side, missing_input) — present only on failure. | |
| event | No | Basket mode: resolved event slug. | |
| title | No | Basket mode: event title. | |
| fee_pp | No | Single-market mode: the taker fee as a percentage point of a $1 share — size-invariant, so it's the same number at any trade size. | |
| market | No | Single-market mode: resolved market slug. | |
| fee_usd | No | Single-market mode: Polymarket taker fee in USD on the shares actually filled. | |
| message | No | Human-readable error detail — present only on failure. | |
| per_leg | No | Basket mode: per-leg fill detail. | |
| verdict | No | Single-market mode: fill-quality verdict based on depth/slippage (independent of the fee). | |
| question | No | Single-market mode: the market question. | |
| strategy | No | Basket mode: which side was priced across every leg. | |
| dead_legs | No | Basket mode: leg slugs with zero visible depth on the priced side. | |
| leg_count | No | Basket mode: number of legs priced. | |
| reasoning | No | Plain-English explanation of the verdict, naming the all-in cost and breakeven. | |
| thin_legs | No | Basket mode: leg slugs that cannot cleanly absorb the requested size. | |
| usd_filled | No | Single-market mode: dollars actually fillable from visible depth. | |
| slippage_pp | No | Single-market mode: |vwap - top_of_book| in percentage points. | |
| theoretical | No | Basket mode: top-of-book sum across all legs, before depth. | |
| top_of_book | No | Single-market mode: best price on the side priced. | |
| fee_schedule | No | Polymarket's published taker-fee parameters for this market, read off the market payload (fleet #3446) — never assumed fee-free. | |
| capture_ratio | No | Basket mode: fraction of the theoretical edge that survives depth AND fees (fleet #3446 — was gross of fees before). | |
| shares_filled | No | Single-market mode: shares actually fillable from visible depth. | |
| all_in_cost_pp | No | Single-market mode: slippage_pp + fee_pp — the full round-trip cost of this fill. | |
| truncated_legs | No | Basket mode: legs dropped by the 80-leg cap, if any. | |
| vwap_fill_price | No | Single-market mode: volume-weighted fill price across the requested size; null if nothing filled. | |
| max_fillable_usd | No | Single-market mode: total USD value of the entire visible side of the book. | |
| partition_complete | No | Basket mode: false means truncated_legs > 0 — edge figures are directional only. | |
| side_auto_selected | No | Basket mode: true if side was inferred from the partition sum rather than passed explicitly. | |
| size_usd_requested | No | Single-market mode: the size_usd argument, clamped. | |
| book_levels_visible | No | Single-market mode: count of price levels on the side priced. | |
| capture_ratio_gross | No | Basket mode: the pre-fee figure capture_ratio used to report. | |
| forced_directional_risk | No | Basket mode: plain-English risk note naming dead/thin legs. | |
| breakeven_win_rate_maker | No | Single-market mode: win-rate a maker (no taker fee charged) would need — equals top_of_book. | |
| breakeven_win_rate_taker | No | Single-market mode: win-rate (0-1) the filled side needs to break even as a taker, INCLUDING the fee — always worse than the raw fill price. | |
| realizable_at_executed_size | No | Basket mode: VWAP sum across all legs at the executed size, net of each leg's own Polymarket taker fee (fleet #3446 — profit_usd was gross before). | |
| scaled_down_by_thinnest_leg | No | Basket mode: true if executed size was capped below the requested size. | |
| settlement_notional_executed_usd | No | Basket mode: shares-per-leg actually executable, scaled down by the thinnest leg. | |
| settlement_notional_requested_usd | No | Basket mode: requested shares-per-leg (the size_usd argument). |