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

Document odds liquidity and limit fields with verified emitters, and keep the new liquidity concept page aligned with current docs main.\n\nFixes #232\nType: docs

Author: paperclip-resolver[bot]

content/en/api-reference/odds.mdx

@@ -330,11 +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 and SBObet. See [Liquidity and limits](/en/concepts/liquidity/). |
-| `volume` | number\|undefined | Matched-volume on this selection. Exchange books only (Betfair, Kalshi, Novig, ProphetX, Polymarket, SX Bet). Units follow the originating book (e.g. matched stake for Betfair, share volume for prediction markets). See [Liquidity and limits](/en/concepts/liquidity/). |
-| `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. |
-| `exchange_token_id` | string\|undefined | Exchange-native token or market identifier for order-routing use cases. Emitted where the upstream exchange exposes a stable token ID, such as Polymarket CLOB token IDs and SX Bet market hashes. |
+| `max_bet` | number\|undefined | Maximum wager amount (USD) for this market type. Emitted by Pinnacle and SBObet. See [Liquidity and limits](/en/concepts/liquidity/). |
+| `volume` | number\|undefined | Cumulative traded volume on the selection, in the exchange's native units. Exchanges only — currently Kalshi. See [Liquidity and limits](/en/concepts/liquidity/). |
+| `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-native token or market identifier for order-routing use cases. Emitted where the upstream exchange exposes a stable token ID, currently Polymarket (`token_id`) and SX Bet (`marketHash`). |
 | `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/liquidity.mdx

@@ -1,26 +1,41 @@
 ---
 title: "Liquidity and Limits"
-description: "What liquidity, open-interest, and max-bet signals SharpAPI surfaces on odds rows, and what upstream sportsbooks do not expose."
+description: "What liquidity and limit signals SharpAPI surfaces on odds rows, and what upstream sportsbooks do not expose."
 ---
 
+import { Callout } from 'nextra/components'
+
 # Liquidity and Limits
 
-SharpAPI exposes liquidity-adjacent fields when the upstream book or exchange publishes them. These fields are optional because traditional sportsbooks and exchange-style books expose different data.
+SharpAPI surfaces every liquidity and limit signal we receive from upstream books. These fields are optional on `/api/v1/odds` rows because traditional sportsbooks and exchange-style books expose different data.
 
 ## Fields on odds rows
 
-| Field | Meaning | Typical sources |
-|---|---|---|
-| `volume` | Matched volume on the selection. Units follow the upstream venue. | Exchange-style books such as Betfair, Novig, ProphetX, Polymarket, SX Bet |
-| `volume_24h` | Trailing 24-hour matched volume. | Prediction markets and exchanges such as Kalshi and Polymarket |
-| `open_interest` | Outstanding open interest or currently held contracts/shares. | Kalshi, Polymarket, and other exchanges that publish it |
-| `max_bet` | Maximum accepted stake for the current line, when exposed by the book. | Pinnacle, SBObet |
-| `exchange_token_id` | Exchange-native token or market identifier for routing orders outside SharpAPI. | Polymarket CLOB token IDs, SX Bet market hashes |
+| Field | Type | Meaning | Emitting books |
+|---|---|---|---|
+| `max_bet` | number | Maximum wager the book will accept on this market or selection at the current line. | Pinnacle, SBObet |
+| `volume` | number | Cumulative traded volume on the selection, in the exchange's native units. | 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-native token or market hash for downstream order routing. | Polymarket (`token_id`), SX Bet (`marketHash`) |
+
+These values are returned only when present in the source feed. Absence means the upstream book did not expose that signal for the row; it does not imply zero liquidity or a zero limit.
 
-These values are returned on [`/api/v1/odds`](/en/api-reference/odds/) rows only when present in the source feed. Absence means the upstream book did not expose that signal for the row; it does not imply zero liquidity or a zero limit.
+<Callout type="info">
+The exchange-side fields (`volume`, `volume_24h`, `open_interest`, and `exchange_token_id`) are liquidity proxies, not a full depth-of-book feed. Their units are not directly comparable across books.
+</Callout>
 
 ## What we do not surface
 
-SharpAPI does not expose a full bid/ask order book, pre-bet limit check, or sportsbook-side suspension reason on odds rows. Most traditional sportsbooks do not publish those fields in public feeds. When a market disappears, the streaming APIs can emit an `odds:removed` delta, but the upstream feed usually does not include the reason.
+- **Bid / ask order-book depth.** Traditional sportsbooks do not operate a visible order book. Exchange-style books may operate one internally, but the public feeds we consume generally publish aggregate volume or open interest rather than depth.
+- **Pre-bet limit checks.** No upstream book exposes a public "will this wager be accepted at this size" probe. `max_bet` is the book's posted ceiling on the market; the actual accept-or-reject decision is made at slip-submission time.
+- **Real-time suspension reasons.** When a book pulls a line, `/api/v1/odds/delta` can emit a removal and the row disappears from `/api/v1/odds`, but upstream feeds usually do not include a structured reason.
+
+## Detecting coverage gaps
+
+If a customer-side coverage check relies on liquidity:
 
-For exchange-style books, use `volume`, `volume_24h`, and `open_interest` as practical liquidity proxies. For traditional sharp books, use `max_bet` where available; otherwise, treat limit information as unavailable rather than inferred.
+1. Filter `/api/v1/odds` by the books you care about.
+2. For exchange-style books, 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.
+4. For everything else, fall back to row presence: an odds row is a positive signal that the book is currently quoting that market.