From 625c06e498cd54a0a013f84edc9e081a23f87164 Mon Sep 17 00:00:00 2001 From: "paperclip-resolver[bot]" <285242166+paperclip-resolver[bot]@users.noreply.github.com> Date: Sat, 23 May 2026 13:29:00 +0000 Subject: [PATCH] docs(odds): document exchange liquidity fields + correct max_bet coverage MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit 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 --- content/en/api-reference/odds.mdx | 6 ++- content/en/concepts/_meta.js | 1 + content/en/concepts/liquidity.mdx | 64 +++++++++++++++++++++++++++++++ 3 files changed, 70 insertions(+), 1 deletion(-) create mode 100644 content/en/concepts/liquidity.mdx diff --git a/content/en/api-reference/odds.mdx b/content/en/api-reference/odds.mdx index addf8aa..330cb22 100644 --- a/content/en/api-reference/odds.mdx +++ b/content/en/api-reference/odds.mdx @@ -320,7 +320,11 @@ X-Request-Id: req_abc123def456 | `player_name` | string\|undefined | Player name (player prop markets only) | | `stat_category` | string\|undefined | Stat category, e.g. `points`, `rebounds` (player prop markets only) | | `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. | +| `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/). | | `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}`. | | `sport_ref` | object\|undefined | **New (May 2026).** Nested sport reference: `{id, numerical_id, name}`. | diff --git a/content/en/concepts/_meta.js b/content/en/concepts/_meta.js index 64d594f..fd09dfb 100644 --- a/content/en/concepts/_meta.js +++ b/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", diff --git a/content/en/concepts/liquidity.mdx b/content/en/concepts/liquidity.mdx new file mode 100644 index 0000000..65170b0 --- /dev/null +++ b/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`) | + + +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. + + +## 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.