docs(odds): document exchange liquidity fields + correct max_bet coverage

Adds documentation for the four exchange liquidity signals already emitted
on /api/v1/odds (volume, volume_24h, open_interest, exchange_token_id) and
corrects the max_bet field to mention SBObet alongside Pinnacle. Introduces
a new concepts/liquidity.mdx page that enumerates what we surface, what we
don't, and why — so future customer questions land on a docs page instead
of generating Crisp follow-ups.

Field emission verified against sharp-api-go/main.go (REST struct) and
api-adapters: max_bet from Pinnacle + SBObet; volume + open_interest from
Kalshi; volume_24h from Polymarket + Kalshi; exchange_token_id from
Polymarket + SX Bet.

Fixes #232

Author: paperclip-resolver[bot]

content/en/api-reference/odds.mdx

@@ -330,10 +330,11 @@ X-Request-Id: req_abc123def456
 | `home_pitcher` | string\|undefined | MLB only. Home-team starting pitcher when published by the book. |
 | `away_pitcher` | string\|undefined | MLB only. Away-team starting pitcher when published by the book. |
 | `public_bet_pct` | number\|undefined | Public betting ticket percentage (0.0-1.0). Currently BetMGM only. |
-| `max_bet` | number\|undefined | Maximum wager amount (USD) for this market type. Currently Pinnacle only. |
-| `volume` | number\|undefined | Matched-volume on this selection. Exchange books only (Betfair, Novig, ProphetX, Polymarket). Units follow the originating book (e.g. matched stake for Betfair, share volume for prediction markets). |
-| `volume_24h` | number\|undefined | Trailing 24-hour matched volume on this selection. Exchange books only. |
-| `open_interest` | number\|undefined | Outstanding open interest (matched stake / shares currently held) on this selection. Exchange books only. |
+| `max_bet` | number\|undefined | Maximum wager amount (USD) for this market type. Emitted by Pinnacle and SBObet. |
+| `volume` | number\|undefined | Cumulative traded volume on the selection, in the exchange's native units (USD for Kalshi). Exchanges only — currently Kalshi. |
+| `volume_24h` | number\|undefined | Rolling 24-hour traded volume, in the exchange's native units. Exchanges only — currently Polymarket and Kalshi. |
+| `open_interest` | number\|undefined | Outstanding open contracts on the selection. Exchanges only — currently Kalshi. |
+| `exchange_token_id` | string\|undefined | Exchange's native token / market hash for the selection — useful for downstream order routing. Exchanges only — currently Polymarket (`token_id`) and SX Bet (`marketHash`). See [Liquidity & limits](/en/concepts/liquidity/). |
 | `polymarket_resolution` | string\|undefined | Polymarket only. UMA optimistic-oracle resolution status when the market has terminated — one of `settled_normal`, `voided`, `disputed`, `proposed`, `unknown`. Absent for live (unresolved) Polymarket markets and for every non-Polymarket book. |
 | `home` | object\|undefined | **New (May 2026).** Nested home-team reference: `{id, numerical_id, name, abbreviation, logo, city, mascot, conference, division}`. See [Entity reference IDs](/en/concepts/entity-reference-ids/). |
 | `away` | object\|undefined | **New (May 2026).** Nested away-team reference: `{id, numerical_id, name, abbreviation, logo, city, mascot, conference, division}`. |

content/en/concepts/_meta.js

@@ -4,6 +4,7 @@ export default {
   arbitrage: "Arbitrage",
   "event-matching": "Event Matching",
   "entity-reference-ids": "Entity Reference IDs",
+  liquidity: "Liquidity & Limits",
   "live-vs-prematch": "Live vs. Pre-Match",
   "pinnacle-odds-changed-at": "Pinnacle `odds_changed_at`",
   "polymarket-resolution": "Polymarket Resolution",

content/en/concepts/liquidity.mdx

@@ -0,0 +1,64 @@
+---
+description: "What liquidity and limit signals SharpAPI surfaces (max_bet, volume, volume_24h, open_interest, exchange_token_id) and what upstream books don't expose."
+---
+
+import { Callout } from 'nextra/components'
+
+# Liquidity & Limits
+
+SharpAPI surfaces every liquidity and limit signal we receive from upstream
+books. This page enumerates exactly what's available, which books emit each
+field, and what isn't surfaced (with a note on why).
+
+## What we surface
+
+Each field below is an optional column on the `/api/v1/odds` response. The
+field is only present on rows where the upstream book actually publishes it —
+treat all five as `undefined`-tolerant.
+
+| Field | Type | Meaning | Emitting books |
+|-------|------|---------|----------------|
+| `max_bet` | number (USD) | Maximum wager the book will accept on this market / selection at the current line. | Pinnacle, SBObet |
+| `volume` | number | Cumulative traded volume on the selection, in the exchange's native units (USD for Kalshi). | Kalshi |
+| `volume_24h` | number | Rolling 24-hour traded volume in the exchange's native units. | Polymarket, Kalshi |
+| `open_interest` | number | Outstanding open contracts on the selection. | Kalshi |
+| `exchange_token_id` | string | Exchange's native token / market hash — used for downstream order routing on the exchange. | Polymarket (`token_id`), SX Bet (`marketHash`) |
+
+<Callout type="info">
+The exchange-side fields (`volume`, `volume_24h`, `open_interest`,
+`exchange_token_id`) are the closest thing to a depth-of-book proxy that any
+public sportsbook API exposes. Use them as a coverage / liquidity signal when
+ranking selections within an exchange book; they are not directly comparable
+across books with different units.
+</Callout>
+
+## What we don't surface (and why)
+
+These are commonly asked about but are not surfaced today, because upstream
+books don't expose them in the public APIs we consume:
+
+- **Bid / ask order-book depth.** Traditional sportsbooks don't operate a
+  visible order book. Exchanges (Polymarket, Kalshi, Novig, SX Bet) operate an
+  internal book but only publish aggregate volume / open-interest, not depth.
+- **Pre-bet limit checks.** No upstream book exposes a "will this wager be
+  accepted at this size" probe via public API. The `max_bet` field above is
+  the book's posted ceiling on the market — the actual accept-or-reject
+  decision is made at slip-submission time.
+- **Real-time book-side suspension reasons.** When a book pulls a line we
+  emit a `removed` delta on `/api/v1/odds/delta` and the row disappears from
+  `/api/v1/odds`, but we do not publish a structured reason code (suspended /
+  void / cashout-only / etc.) — upstream books don't expose one.
+
+## Detecting coverage gaps
+
+If a customer-side coverage check relies on liquidity, the recommended
+pattern is:
+
+1. Filter `/api/v1/odds` by your books of interest.
+2. For exchange books, additionally filter rows where `volume_24h` or
+   `open_interest` exceeds your minimum threshold.
+3. For traditional books, use `max_bet` (when emitted) as a coarse limit
+   signal — Pinnacle and SBObet only.
+4. For everything else, fall back to row presence: an odds row in
+   `/api/v1/odds` is a positive signal that the book is currently quoting
+   that market.