Sharp-API · Mlaz-code · May 25, 2026 · May 25, 2026 · May 25, 2026
diff --git a/content/en/api-reference/conventions.mdx b/content/en/api-reference/conventions.mdx
@@ -191,7 +191,7 @@ ETag: "9dc023776c4b382"
 
 ## Machine-readable source of truth
 
-- REST surface: [`openapi.json`](https://docs.sharpapi.io/openapi.json) (OpenAPI 3.1)
+- REST surface: `openapi.json` from the docs domain root (OpenAPI 3.1)
 - WebSocket surface: [`asyncapi.yaml`](https://docs.sharpapi.io/asyncapi.yaml) (AsyncAPI 3.0)
 
 Both files are published as static assets and can be diffed in CI. If this page drifts from the spec, the spec wins — the spec is generated from the deployed server.
diff --git a/content/en/api-reference/odds.mdx b/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). |
+| `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. |
 | `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}`. |

diff --git a/content/en/concepts/_meta.js b/content/en/concepts/_meta.js
@@ -5,6 +5,7 @@ export default {
   "event-matching": "Event Matching",
   "entity-reference-ids": "Entity Reference IDs",
   "live-vs-prematch": "Live vs. Pre-Match",
+  liquidity: "Liquidity and Limits",
   "pinnacle-odds-changed-at": "Pinnacle `odds_changed_at`",
   "polymarket-resolution": "Polymarket Resolution",
 }
diff --git a/content/en/concepts/liquidity.mdx b/content/en/concepts/liquidity.mdx
@@ -0,0 +1,26 @@
+---
+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."
+---
+
+# 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.
+
+## 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 |
+
+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.
+
+## 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.
+
+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.