> ## Documentation Index
> Fetch the complete documentation index at: https://docs.routeur.app/llms.txt
> Use this file to discover all available pages before exploring further.

> ## Agent Instructions
> Prices are US dollars per contract that pays $1: 0.46 means 46 cents. Spread is the Yes ask plus the No ask minus $1. Liquidity grades are deep, tradeable and thin; lists hide thin markets unless include_thin=true. Relations are proven from contract terms, never inferred from wording; a lead marked informational is never executable. Every figure carries a graph_run; read /agents/reading-order first, then /concepts/relations and /concepts/liquidity.

# Slippage at size

> Walk the recorded order book to price a $1,000 order on Yes and on No, and compare it with what the top of book promised.

## What you'll get

The cost of buying $1,000 of Yes and $1,000 of No in one market, filled level by level from the recorded order book: contracts bought, average and worst price, and how far that sits from the best ask. Run on a deep market and a thin one, it shows why a top-of-book price on a thin market says almost nothing. On 2026-09-17 a deep Bitcoin market filled \$1,000 of No at 0.24¢ over the top; a thin college-football spread filled it 4.96¢ over.

## Prerequisites

* An API key in `ROUTEUR_API_KEY`
* Python 3 with `requests`
* A market whose book is recorded. Markets graded `tradeable` or `deep`, markets in a current lead, and markets of followed events are recorded at full depth; every other listed market is polled five levels per side.

<Steps>
  <Step title="Read the book">
    Both outcomes' ladders, best first, with the top of book and the USD resting within 1, 2 and 5¢ of each side's best bid.

    ```bash theme={null}
    curl "https://api.routeur.app/v1/markets/kalshi/KXBTCD-26SEP1717-T76249.99/book?depth=5" -H "X-API-Key: $ROUTEUR_API_KEY"
    ```

    Trimmed to the top and the first three levels, observed 2026-09-17 12:40 UTC:

    ```json theme={null}
    {
      "data": {
        "venue": "kalshi", "market_id": "KXBTCD-26SEP1717-T76249.99",
        "source": "live", "tier": "full", "as_of": "2026-09-17T12:40:14.78221Z", "seq": 169697,
        "snapshot_at": "2026-09-17T12:39:42.497794Z", "events_applied": 491, "depth": 5,
        "yes": { "bids": [ { "price_usd": "0.76", "quantity": "1048", "notional_usd": "796.48" } ],
                 "asks": [ { "price_usd": "0.77", "quantity": "3031", "notional_usd": "2333.87" },
                           { "price_usd": "0.78", "quantity": "21976", "notional_usd": "17141.28" },
                           { "price_usd": "0.79", "quantity": "576", "notional_usd": "455.04" } ] },
        "no":  { "asks": [ { "price_usd": "0.24", "quantity": "1048", "notional_usd": "251.52" },
                           { "price_usd": "0.25", "quantity": "2737", "notional_usd": "684.25" },
                           { "price_usd": "0.26", "quantity": "9269", "notional_usd": "2409.94" } ] },
        "top": { "yes_bid_usd": "0.76", "yes_ask_usd": "0.77", "no_bid_usd": "0.23", "no_ask_usd": "0.24",
                 "mid_usd": "0.765", "microprice_usd": "0.762569", "spread_usd": "0.01",
                 "yes_depth_1c_usd": "2849.23", "yes_depth_2c_usd": "9708.29", "yes_depth_5c_usd": "26300.39",
                 "no_depth_1c_usd": "5531.85", "no_depth_2c_usd": "5652.81", "no_depth_5c_usd": "6911.31", "imbalance": "0.583802" },
        "feed": { "connected": true, "last_message_at": "2026-09-17T12:40:12.241523Z", "stale_seconds": 1 },
        "issues": [],
        "volume_24h_usd": "109134.43", "open_interest_usd": "56631.73", "trades_24h": 785, "liquidity": "deep"
      }
    }
    ```

    The No asks are the Yes bids seen from the other side: 1,048 contracts bid at 76¢ for Yes are 1,048 contracts offered at 24¢ for No.
  </Step>

  <Step title="Walk the levels">
    Spend the budget up each ladder until it runs out, and compare the average price paid with the best ask.

    ```python Python theme={null}
    import os
    import sys
    from decimal import Decimal

    import requests

    API = "https://api.routeur.app"
    venue, market_id = os.environ.get("VENUE", "kalshi"), os.environ["MARKET_ID"]
    BUDGET = Decimal(os.environ.get("BUDGET_USD", "1000"))

    res = requests.get(f"{API}/v1/markets/{venue}/{market_id}/book", params={"depth": 100},
                       headers={"X-API-Key": os.environ["ROUTEUR_API_KEY"]}, timeout=30)
    if res.status_code == 404:
        sys.exit("book_not_found: no order book is recorded for this market")
    res.raise_for_status()
    book = res.json()["data"]


    def walk(asks, budget):
        """Spend `budget` up the ladder. Returns (contracts bought, dollars spent, worst price paid, levels used)."""
        contracts, spent, worst, levels = Decimal(0), Decimal(0), None, 0
        for level in asks:
            price, size = Decimal(level["price_usd"]), Decimal(level["quantity"])
            if spent >= budget:
                break
            take = min(size, (budget - spent) / price)
            contracts += take
            spent += take * price
            worst = price
            levels += 1
        return contracts, spent, worst, levels


    print(f"{venue}:{market_id} · {book['liquidity']} · ${float(book['volume_24h_usd']):,.0f} traded in 24h · "
          f"book {book['source']}/{book['tier']} as of {book['as_of']} · issues {book['issues'] or 'none'}")
    top = book["top"]
    print(f"top of book: Yes {top.get('yes_bid_usd')} / {top.get('yes_ask_usd')}   No {top.get('no_bid_usd')} / {top.get('no_ask_usd')}"
          f"   spread {top.get('spread_usd')}   within 5¢: Yes ${float(top['yes_depth_5c_usd']):,.0f}, No ${float(top['no_depth_5c_usd']):,.0f}")

    for side in ("yes", "no"):
        asks = book[side]["asks"]
        if not asks:
            print(f"\n{side.upper()}: no asks recorded")
            continue
        best = Decimal(asks[0]["price_usd"])
        contracts, spent, worst, levels = walk(asks, BUDGET)
        avg = spent / contracts if contracts else Decimal(0)
        at_top = BUDGET / best                                   # what top-of-book alone would promise
        print(f"\nBuy ${BUDGET:,.0f} of {side.upper()}")
        print(f"  best ask {best * 100:.1f}¢ shows {Decimal(asks[0]['quantity']):,.2f} contracts (${Decimal(asks[0]['notional_usd']):,.2f})")
        if spent < BUDGET:
            print(f"  only ${spent:,.2f} can be filled from the {len(asks)} recorded levels: the rest of the budget has nothing to hit")
        print(f"  fills {contracts:,.0f} contracts across {levels} level(s), average {avg * 100:.2f}¢, worst {worst * 100:.1f}¢")
        print(f"  slippage vs top of book: {(avg - best) * 100:+.2f}¢ per contract, {at_top - contracts:,.0f} fewer contracts than the top price promised")
        print(f"  a $1 payout on every contract returns ${contracts - spent:,.2f} before fees")
    ```

    A deep market, observed 2026-09-17 12:48 UTC:

    ```text theme={null}
    $ MARKET_ID=KXBTCD-26SEP1717-T76249.99 python3 slippage.py
    kalshi:KXBTCD-26SEP1717-T76249.99 · deep · $109,134 traded in 24h · book live/full as of 2026-09-17T12:48:25.984895Z · issues none
    top of book: Yes 0.71 / 0.72   No 0.28 / 0.29   spread 0.01   within 5¢: Yes $25,974, No $8,559

    Buy $1,000 of YES
      best ask 72.0¢ shows 3,228.00 contracts ($2,324.16)
      fills 1,389 contracts across 1 level(s), average 72.00¢, worst 72.0¢
      slippage vs top of book: -0.00¢ per contract, 0 fewer contracts than the top price promised
      a $1 payout on every contract returns $388.89 before fees

    Buy $1,000 of NO
      best ask 29.0¢ shows 2,610.00 contracts ($756.90)
      fills 3,420 contracts across 2 level(s), average 29.24¢, worst 30.0¢
      slippage vs top of book: +0.24¢ per contract, 28 fewer contracts than the top price promised
      a $1 payout on every contract returns $2,420.33 before fees
    ```

    A thin one, observed 2026-09-17 12:52 UTC:

    ```text theme={null}
    $ MARKET_ID=KXNCAAFSPREAD-26SEP17SYRPITT-SYR10 python3 slippage.py
    kalshi:KXNCAAFSPREAD-26SEP17SYRPITT-SYR10 · thin · $171 traded in 24h · book live/full as of 2026-09-17T12:51:58.059971Z · issues none
    top of book: Yes 0.1 / 0.11   No 0.89 / 0.9   spread 0.01   within 5¢: Yes $32, No $17,083

    Buy $1,000 of YES
      best ask 11.0¢ shows 13,863.85 contracts ($1,525.02)
      fills 9,091 contracts across 1 level(s), average 11.00¢, worst 11.0¢
      slippage vs top of book: +0.00¢ per contract, 0 fewer contracts than the top price promised
      a $1 payout on every contract returns $8,090.91 before fees

    Buy $1,000 of NO
      best ask 90.0¢ shows 0.01 contracts ($0.01)
      fills 1,053 contracts across 7 level(s), average 94.96¢, worst 96.0¢
      slippage vs top of book: +4.96¢ per contract, 58 fewer contracts than the top price promised
      a $1 payout on every contract returns $53.12 before fees
    ```
  </Step>

  <Step title="Compare">
    |                         | Bitcoin above \$76,249.99 (deep) | Syracuse −9.5 (thin) |
    | ----------------------- | -------------------------------- | -------------------- |
    | Top-of-book spread      | 1¢                               | 1¢                   |
    | \$1,000 of Yes          | 1 level, no slippage             | 1 level, no slippage |
    | \$1,000 of No           | 2 levels, +0.24¢                 | 7 levels, +4.96¢     |
    | Size at the best No ask | 2,610 contracts                  | 0.01 contracts       |

    Both markets show a 1¢ spread. On the thin one, the best No ask is a hundredth of a contract: the quote is real and the market behind it is not. `spread_usd` alone would have graded them the same; `liquidity`, `volume_24h_usd` and the 5¢ depth did not.
  </Step>
</Steps>

## Read the result

| Field                                              | Meaning                                                                                                                                                                                                                                |
| -------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `yes.asks[]`, `no.asks[]`                          | Resting offers on each outcome, best first. `price_usd` per contract that pays $1; `quantity` in contracts on Kalshi and outcome shares on Polymarket; `notional_usd` is price × quantity. A Yes ask is a No bid at $1 less the price. |
| `top`                                              | The book in Yes terms: best bid and ask, mid, `microprice_usd` (leans toward the thinner side), the spread, and USD within 1, 2 and 5¢ of each side's best bid. `imbalance` is (Yes − No) / (Yes + No) of the 5¢ depths.               |
| `source`, `tier`                                   | `live` is the latest recorded book; `rebuilt` is the book at the `at` you asked for. `full` means every level change is recorded from the venue feed; `rest` means polled, five levels per side.                                       |
| `as_of`, `feed.stale_seconds`                      | When the last change was received, and how long ago. A book that has not changed in minutes on a busy market means the feed dropped, not that nothing traded.                                                                          |
| `issues`                                           | `polled` (a `rest` book), `stale` (no change for a while), `truncated` (more levels exist than were returned).                                                                                                                         |
| `liquidity`, `volume_24h_usd`, `open_interest_usd` | The market's grade and the figures behind it.                                                                                                                                                                                          |

## Pitfalls

* **A `rest` book has five levels per side.** A $1,000 walk on one can run out of levels; the script says so ("only $X can be filled from the N recorded levels"). That is a limit of the recording, not the market.
* **Quantities can be fractional.** Polymarket shares are, and Kalshi showed a `0.01` on 2026-09-17. Use `Decimal`, not `int`.
* **Fees are not in these numbers.** Kalshi charges a taker fee per contract that depends on the price; Polymarket a rate on the notional. A lead's `depth.fees_usd` estimates both; see [Leads](/concepts/leads).
* **Books can be one-sided.** A Polymarket book on 2026-09-17 carried Yes asks and No bids but no Yes bids, so `top.yes_bid_usd` was absent and both `yes_depth_*` were `0`. Check for the field before subtracting.
* **The book is a recording.** `as_of` says how old. For an order, read the venue directly; use this to decide whether an order is worth placing.
* **`404 book_not_found`** means no book is recorded for that market at that time. Market data still exists; the book does not.

## Related

* [Proof trail](/cookbook/proof-trail): a lead's `depth` does this walk for both legs and subtracts fees.
* [Price chart](/cookbook/price-chart): the top of the book over time from `/book/history`.
* `GET /v1/markets/{venue}/{id}/book?at=2026-09-16T14:30:00Z`: the book as it stood at any moment in the last 90 days.
* `GET /v1/books/health`: whether each venue's feed is up, how many markets are recorded at full depth and how many are polled.
* [Stream consumer](/cookbook/stream-consumer): the `books` topic pushes the top of book as it changes, at most once a second per market.