### Path Parameter Examples Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example values for path parameters used in the API request. ```yaml Coin: btc Type: 15m Ticker: KXBTC15M-26APR221830-T105000 ``` -------------------------------- ### Authentication Error Examples Source: https://docs.kalshibacktest.com/api-reference/v1/list-markets JSON examples for missing or invalid API key authentication errors. ```json error: code: AUTH_MISSING message: >- Missing API key. Pass X-API-Key or Authorization: Bearer . meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` ```json error: code: AUTH_INVALID message: API key is invalid meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### Cursor Pagination Example Source: https://docs.kalshibacktest.com/api-reference/v1/overview Demonstrates how to paginate through results by passing the next_cursor from the previous response. ```bash # Page 1 curl 'https://api.kalshibacktest.com/v1/btc/15m/markets?limit=50' \ -H "X-API-Key: $KBT_KEY" # Page 2 - pass the cursor from page 1 curl 'https://api.kalshibacktest.com/v1/btc/15m/markets?limit=50&cursor=eyJjdCI...' \ -H "X-API-Key: $KBT_KEY" ``` -------------------------------- ### Snapshot Data Example Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example of a snapshot object containing market ticker, pricing, and orderbook data. ```json description: Wall-clock time of the snapshot. example: '2026-04-22T18:15:03.214Z' market_ticker: type: string example: KXBTC15M-26APR221830-T105000 yes_best_bid: type: - number - 'null' description: Top-of-book YES bid (0.00 - 1.00). example: 0.42 no_best_bid: type: - number - 'null' description: Top-of-book NO bid (0.00 - 1.00). example: 0.57 coin_price: type: - number - 'null' description: Underlying coin price at `time`. example: 104872.45 seq: type: - integer - 'null' description: Kalshi `orderbook_delta` sequence number for reconstructing diffs. example: 8871 orderbook_yes: $ref: '#/components/schemas/OrderbookSide' orderbook_no: $ref: '#/components/schemas/OrderbookSide' gap_ms: type: - integer - 'null' description: >- Only present on `snapshots/at`. Milliseconds between the requested timestamp and the returned snapshot's `time`. example: 186 ``` -------------------------------- ### Error Response Examples Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Examples of error responses returned when a market is not found or no snapshot exists within the specified tolerance. ```yaml MarketNotFound: summary: Unknown market ticker value: error: code: MARKET_NOT_FOUND message: Market not found details: market_ticker: KXBTC15M-00XXX00000-T000000 meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' SnapshotNotFound: summary: No snapshot within tolerance value: error: code: SNAPSHOT_NOT_FOUND message: No snapshot within 2000 ms of requested timestamp details: market_ticker: KXBTC15M-26APR221830-T105000 timestamp: '2026-04-22T18:20:00Z' nearest_gap_ms: 4821 tolerance_ms: 2000 meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### OrderbookSide Schema Example Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example of the orderbook side structure containing price and quantity pairs. ```json bids: type: array description: >- Top-15 `[price, qty]` pairs. Price is 0-100 cents (integer) per Kalshi's native format; qty is number of contracts. items: type: array items: type: number minItems: 2 maxItems: 2 example: - - 42 - 150 - - 41 - 320 - - 40 - 500 ``` -------------------------------- ### Rate Limit Error Examples Source: https://docs.kalshibacktest.com/api-reference/v1/list-markets JSON examples for burst and sustained rate limit exceedance errors. ```json error: code: RATE_LIMIT_BURST message: 'RATE_LIMIT_BURST: limit 1 per second' details: retry_after: 1 limit: 1 window: second meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` ```json error: code: RATE_LIMIT_SUSTAINED message: 'RATE_LIMIT_SUSTAINED: limit 60 per minute' details: retry_after: 47 limit: 60 window: minute meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### RateLimitError Burst Example Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example JSON response when the per-second burst limit is exceeded. ```json { "error": { "code": "RATE_LIMIT_BURST", "message": "RATE_LIMIT_BURST: limit 1 per second", "details": { "retry_after": 1, "limit": 1, "window": "second" } }, "meta": { "request_id": "req_a1b2c3d4e5f6", "timestamp": "2026-04-24T18:00:00Z" } } ``` -------------------------------- ### OpenAPI Specification for Get Market by Ticker Source: https://docs.kalshibacktest.com/api-reference/v1/get-market The OpenAPI definition for the GET /v1/{coin}/{type}/markets/{ticker} endpoint, including the response schema and an example market object. ```yaml openapi: 3.1.0 info: title: KalshiBackTest API version: 1.0.0 summary: Markets and full-depth snapshots for every Kalshi up/down crypto market. description: >- The **KalshiBackTest API** exposes the data that powers [kalshibacktest.com](https://kalshibacktest.com): Kalshi up/down crypto market metadata plus ~100 ms orderbook snapshots from open through settlement. Every response uses the v1 envelope - `{ data, pagination?, meta }` on success, `{ error, meta }` on error. All endpoints are rate-limited per API key; limits are exposed via `X-RateLimit-*` response headers. **Supported deployments today (`coin:type`):** `btc:15m`, `eth:15m`, `sol:15m`, `doge:15m`, `xrp:15m`. See [Error Codes](/api-reference/v1/error-codes) for the full machine-readable error catalogue. contact: name: KalshiBackTest Support url: https://kalshibacktest.com email: support@kalshibacktest.com license: name: Proprietary url: https://kalshibacktest.com/terms servers: - url: https://api.kalshibacktest.com description: Production security: - ApiKeyAuth: [] - BearerAuth: [] tags: - name: Kalshi Markets description: Metadata and orderbook snapshots for Kalshi up/down crypto markets. - name: Utility description: Health checks and other non-authenticated utility endpoints. paths: /v1/{coin}/{type}/markets/{ticker}: get: tags: - Kalshi Markets summary: Get Market by Ticker description: >- Fetch a single market by `market_ticker` **or** `event_ticker` (the one in Kalshi URLs). Exact `market_ticker` matches take precedence; for event tickers that map to multiple markets, the newest by `close_time` is returned. Unknown tickers return `404` with `error.code = MARKET_NOT_FOUND`. Free keys can fetch only the newest 50 markets for the requested `(coin, type)` pair; older known tickers return `403` with `error.code = PLAN_UPGRADE_REQUIRED`. operationId: getMarket parameters: - $ref: '#/components/parameters/Coin' - $ref: '#/components/parameters/Type' - $ref: '#/components/parameters/Ticker' responses: '200': description: The requested market. content: application/json: schema: $ref: '#/components/schemas/MarketResponse' example: data: market_ticker: KXBTC15M-26APR221830-T105000 event_ticker: KXBTC15M-26APR221830 series_ticker: KXBTC15M title: Bitcoin above $105,000 at 18:30? subtitle: 15-minute market rules_primary: >- If the final BTC price is strictly greater than $105,000 at 18:30 ET, this market resolves YES. strike_type: greater floor_strike: 105000 open_time: '2026-04-22T18:15:00Z' close_time: '2026-04-22T18:30:00Z' expiration_time: '2026-04-22T18:30:00Z' coin_price_start: 104872.12 coin_price_end: 105224.45 expiration_value: 105224.45 result: 'yes' settlement_ts: '2026-04-22T18:30:12Z' status: finalized created_at: '2026-04-22T18:14:58Z' updated_at: '2026-04-22T18:30:12Z' meta: request_id: req_a1b2c3d4e5f6 ``` -------------------------------- ### Snapshots Page Response Example Source: https://docs.kalshibacktest.com/api-reference/v1/list-snapshots Represents a successful 200 OK response containing market metadata and a paginated list of snapshots. ```json data: market_ticker: KXBTC15M-26APR221830-T105000 event_ticker: KXBTC15M-26APR221830 series_ticker: KXBTC15M title: Bitcoin above $105,000 at 18:30? subtitle: 15-minute market rules_primary: >- If the final BTC price is strictly greater than $105,000 at 18:30 ET, this market resolves YES. strike_type: greater floor_strike: 105000 open_time: '2026-04-22T18:15:00Z' close_time: '2026-04-22T18:30:00Z' expiration_time: '2026-04-22T18:30:00Z' coin_price_start: 104872.12 coin_price_end: 105224.45 expiration_value: 105224.45 result: 'yes' settlement_ts: '2026-04-22T18:30:12Z' status: finalized created_at: '2026-04-22T18:14:58Z' updated_at: '2026-04-22T18:30:12Z' snapshots: - id: 1298374 time: '2026-04-22T18:15:03.214Z' market_ticker: KXBTC15M-26APR221830-T105000 yes_best_bid: 0.42 no_best_bid: 0.57 coin_price: 104872.45 seq: 8871 - id: 1298375 time: '2026-04-22T18:15:03.317Z' market_ticker: KXBTC15M-26APR221830-T105000 yes_best_bid: 0.43 no_best_bid: 0.56 coin_price: 104875.1 seq: 8872 pagination: next_cursor: >- eyJ0cyI6IjIwMjYtMDQtMjJUMTg6MTU6MDMuMzE3WiIsImlkIjoxMjk4Mzc1fQ has_more: true limit: 100 count: 100 total_count: null meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### Authentication Error Responses Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Examples of error responses returned when authentication fails. ```json Missing: summary: No API key sent value: error: code: AUTH_MISSING message: >- Missing API key. Pass X-API-Key or Authorization: Bearer . meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` ```json Invalid: summary: Key is revoked, unknown, or malformed value: error: code: AUTH_INVALID message: API key is invalid meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### Snapshot Response Data Structure Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example of the successful response body containing market details and the closest snapshot. ```yaml open_time: '2026-04-22T18:15:00Z' close_time: '2026-04-22T18:30:00Z' expiration_time: '2026-04-22T18:30:00Z' coin_price_start: 104872.12 coin_price_end: 105224.45 expiration_value: 105224.45 result: 'yes' settlement_ts: '2026-04-22T18:30:12Z' status: finalized created_at: '2026-04-22T18:14:58Z' updated_at: '2026-04-22T18:30:12Z' snapshot: id: 1298412 time: '2026-04-22T18:20:00.186Z' market_ticker: KXBTC15M-26APR221830-T105000 yes_best_bid: 0.48 no_best_bid: 0.51 coin_price: 104998.21 seq: 12440 gap_ms: 186 meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### RateLimitError Sustained Example Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example JSON response when the per-minute sustained limit is exceeded. ```json { "error": { "code": "RATE_LIMIT_SUSTAINED", "message": "RATE_LIMIT_SUSTAINED: limit 60 per minute", "details": { "retry_after": 47, "limit": 60, "window": "minute" } }, "meta": { "request_id": "req_a1b2c3d4e5f6", "timestamp": "2026-04-24T18:00:00Z" } } ``` -------------------------------- ### Validation Error Examples Source: https://docs.kalshibacktest.com/api-reference/v1/list-markets JSON examples for common request validation failures including invalid timestamps, cursors, and type pairs. ```json error: code: INVALID_TIMESTAMP message: 'Invalid start_time: expected millisecond epoch or ISO-8601' details: value: last-tuesday field: start_time meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` ```json error: code: INVALID_CURSOR message: Cursor is malformed or unreadable meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` ```json error: code: INVALID_TYPE message: No data deployment for BTC at type 1h details: coin: btc type: 1h available: - btc:15m - doge:15m - eth:15m - sol:15m - xrp:15m meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### GET /v1/{coin}/15m/markets/{ticker} Source: https://docs.kalshibacktest.com/quickstart Retrieves details for a specific market by its Kalshi ticker. ```APIDOC ## GET /v1/{coin}/15m/markets/{ticker} ### Description Retrieves details for a single market identified by its Kalshi ticker. ### Method GET ### Endpoint /v1/{coin}/15m/markets/{ticker} ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier - **ticker** (string) - Required - The Kalshi market ticker ``` -------------------------------- ### GET /api-reference/v1/list-snapshots Source: https://docs.kalshibacktest.com/api-reference/v1/list-snapshots Fetches market metadata and a sequence of snapshots for a market, allowing for forward replay of market activity. ```APIDOC ## GET /list-snapshots ### Description Returns the market's metadata together with a cursor-paginated forward replay of ~100 ms snapshots (oldest-first). Embedding the market metadata allows for scoring against snapshots in a single round-trip. ### Method GET ### Endpoint /list-snapshots ### Parameters #### Query Parameters - **include_orderbook** (boolean) - Optional - Pass true to receive full top-15 YES/NO ladders as {"bids": [[price, qty], ...]} on each snapshot. ### Response #### Success Response (200) - **data** (object) - Contains market metadata and the snapshots array. - **pagination** (object) - Contains cursor information (next_cursor, has_more, limit, count). - **meta** (object) - Contains request_id and timestamp. #### Response Example { "data": { "market_ticker": "KXBTC15M-26APR221830-T105000", "snapshots": [ { "id": 1298374, "time": "2026-04-22T18:15:03.214Z", "yes_best_bid": 0.42, "no_best_bid": 0.57, "coin_price": 104872.45, "seq": 8871 } ] }, "pagination": { "next_cursor": "eyJ0cy...", "has_more": true, "limit": 100, "count": 100 }, "meta": { "request_id": "req_...", "timestamp": "..." } } ``` -------------------------------- ### Plan Upgrade Error Response Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Example of an error response when the user's plan lacks access to the requested data. ```json error: code: PLAN_UPGRADE_REQUIRED message: >- Your plan can only access the newest 50 BTC 15m markets. Upgrade to Pro for full history. details: plan: free coin: btc ``` -------------------------------- ### GET /v1/btc/15m/markets/{market_ticker}/snapshots Source: https://docs.kalshibacktest.com/fetching-data Retrieves snapshots for a specific market using cursor-based pagination. ```APIDOC ## GET /v1/btc/15m/markets/{market_ticker}/snapshots ### Description Retrieves a paginated list of snapshots for a given market ticker. Use the `next_cursor` from the response to fetch subsequent pages. ### Method GET ### Endpoint https://api.kalshibacktest.com/v1/btc/15m/markets/{market_ticker}/snapshots ### Parameters #### Path Parameters - **market_ticker** (string) - Required - The unique identifier for the market. #### Query Parameters - **limit** (integer) - Optional - The number of records to return (default 100). - **cursor** (string) - Optional - The opaque cursor string used for pagination. ``` -------------------------------- ### Market Not Found Error Example Source: https://docs.kalshibacktest.com/api-reference/v1/list-snapshots Represents a 404 error response when the requested market ticker does not exist. ```json error: code: MARKET_NOT_FOUND message: Market not found details: market_ticker: KXBTC15M-00XXX00000-T000000 meta: request_id: req_a1b2c3d4e5f6 timestamp: '2026-04-24T18:00:00Z' ``` -------------------------------- ### GET /v1/{coin}/{type}/markets/{ticker}/snapshots Source: https://docs.kalshibacktest.com/api-reference/v1/list-snapshots Returns the market's metadata together with a cursor-paginated forward replay of ~100 ms snapshots (oldest-first). ```APIDOC ## GET /v1/{coin}/{type}/markets/{ticker}/snapshots ### Description Returns the market's metadata together with a cursor-paginated forward replay of ~100 ms snapshots (oldest-first) inside `data.snapshots[]`. Embedding the market means a single round-trip is enough to start scoring against snapshots. ### Method GET ### Endpoint /v1/{coin}/{type}/markets/{ticker}/snapshots ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier (e.g., btc, eth). - **type** (string) - Required - The market type (e.g., 15m). - **ticker** (string) - Required - The market ticker. #### Query Parameters - **start_time** (string) - Optional - Lower bound on snapshot `time`. Millisecond epoch or ISO-8601. - **end_time** (string) - Optional - Upper bound on snapshot `time`. - **include_orderbook** (boolean) - Optional - Include `orderbook_yes` and `orderbook_no` top-15 ladders on each row. Default: false. - **limit** (integer) - Optional - Page size. 1-1000. Default: 100. - **cursor** (string) - Optional - Opaque keyset cursor from a prior `pagination.next_cursor`. - **include_count** (boolean) - Optional - When `true`, run a `COUNT(*)` and populate `pagination.total_count`. ``` -------------------------------- ### GET /markets/{ticker} Source: https://docs.kalshibacktest.com/api-reference/v1/get-market Retrieves the full details of a specific market by its ticker. ```APIDOC ## GET /markets/{ticker} ### Description Retrieves static and resolved information about a single Kalshi up/down market. ### Method GET ### Endpoint /markets/{ticker} ### Parameters #### Path Parameters - **ticker** (string) - Required - The Kalshi market_ticker (e.g., KXBTC15M-26APR221830-T105000). ### Response #### Success Response (200) - **data** (object) - The market object containing details like market_ticker, event_ticker, title, rules_primary, and settlement status. - **meta** (object) - Response metadata. #### Error Response (404) - **error** (object) - Contains error code MARKET_NOT_FOUND and details about the missing ticker. ``` -------------------------------- ### GET /v1/{coin}/15m/markets/{ticker}/snapshots Source: https://docs.kalshibacktest.com/quickstart Retrieves snapshots for a specific market. ```APIDOC ## GET /v1/{coin}/15m/markets/{ticker}/snapshots ### Description Streams snapshots for a given market, optionally including orderbook depth. ### Method GET ### Endpoint /v1/{coin}/15m/markets/{ticker}/snapshots ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier - **ticker** (string) - Required - The Kalshi market ticker #### Query Parameters - **include_orderbook** (boolean) - Optional - Whether to include full orderbook depth - **limit** (integer) - Optional - Number of snapshots to return - **cursor** (string) - Optional - Cursor for pagination ``` -------------------------------- ### GET /v1/{coin}/15m/markets/{ticker}/snapshots/at/{timestamp} Source: https://docs.kalshibacktest.com/quickstart Retrieves the snapshot closest to a specific wall-clock time. ```APIDOC ## GET /v1/{coin}/15m/markets/{ticker}/snapshots/at/{timestamp} ### Description Fetches the market snapshot closest to the provided ISO 8601 timestamp. ### Method GET ### Endpoint /v1/{coin}/15m/markets/{ticker}/snapshots/at/{timestamp} ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier - **ticker** (string) - Required - The Kalshi market ticker - **timestamp** (string) - Required - The wall-clock time in ISO 8601 format ``` -------------------------------- ### GET /v1/{coin}/15m/markets Source: https://docs.kalshibacktest.com/quickstart Retrieves a list of markets for a specific coin and timeframe. ```APIDOC ## GET /v1/{coin}/15m/markets ### Description Fetches a list of markets for the specified coin and 15m timeframe. ### Method GET ### Endpoint /v1/{coin}/15m/markets ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier (btc, eth, sol, doge, xrp) #### Query Parameters - **limit** (integer) - Optional - Number of markets to return - **cursor** (string) - Optional - Cursor for pagination ``` -------------------------------- ### GET /markets/{coin}/{type}/{ticker}/snapshots Source: https://docs.kalshibacktest.com/api-reference/v1/list-snapshots Fetches a paginated list of snapshots for a specified market, ordered by time in ascending order. ```APIDOC ## GET /markets/{coin}/{type}/{ticker}/snapshots ### Description Retrieves a paginated list of snapshots for a specific market. The snapshots are returned in ascending order by time. ### Method GET ### Endpoint /markets/{coin}/{type}/{ticker}/snapshots ### Parameters #### Path Parameters - **coin** (string) - Required - Coin segment. One of `btc`, `eth`, `sol`, `doge`, `xrp`. - **type** (string) - Required - Market type. Currently only `15m` is supported. - **ticker** (string) - Required - The Kalshi `market_ticker` (e.g., `KXBTC15M-26APR221830-T105000`). ### Response #### Success Response (200) - **data** (object) - Market metadata and the list of snapshots. - **pagination** (object) - Pagination details including `next_cursor`, `has_more`, `limit`, and `count`. - **meta** (object) - Response metadata including `request_id` and `timestamp`. #### Response Example { "data": { "market_ticker": "KXBTC15M-26APR221830-T105000", "snapshots": [ { "id": 1298374, "time": "2026-04-22T18:15:03.214Z", "market_ticker": "KXBTC15M-26APR221830-T105000", "yes_best_bid": 0.42, "no_best_bid": 0.57, "coin_price": 104872.45, "seq": 8871 } ] }, "pagination": { "next_cursor": "eyJ0cyI6IjIwMjYtMDQtMjJUMTg6MTU6MDMuMzE3WiIsImlkIjoxMjk4Mzc1fQ", "has_more": true, "limit": 100, "count": 100 }, "meta": { "request_id": "req_a1b2c3d4e5f6", "timestamp": "2026-04-24T18:00:00Z" } } ``` -------------------------------- ### GET /snapshot-at Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Fetches the market's metadata and the single snapshot whose time is closest to the requested timestamp. ```APIDOC ## GET /snapshot-at ### Description Returns the market's metadata together with the single snapshot whose time is closest to the provided timestamp. The snapshot includes a gap_ms field to indicate how stale the match is. ### Method GET ### Endpoint /snapshot-at ### Query Parameters - **timestamp** (string/number) - Required - The time to query, provided as a millisecond epoch or an ISO-8601 string. - **tolerance_ms** (number) - Optional - The maximum allowed time difference for a snapshot to be considered valid. ### Response #### Success Response (200) - **data** (object) - Contains market metadata and the snapshot object. - **data.snapshot** (object) - The closest snapshot found, including gap_ms. - **meta** (object) - Request metadata including request_id and timestamp. #### Error Response (404) - **error.code** (string) - Returns SNAPSHOT_NOT_FOUND if no snapshot falls within the tolerance_ms. - **details.nearest_gap_ms** (number) - Provided for diagnosis. #### Error Response (403) - **error.code** (string) - Returns PLAN_UPGRADE_REQUIRED for free keys querying older markets. ``` -------------------------------- ### GET /v1/btc/15m/markets Source: https://docs.kalshibacktest.com/fetching-data Retrieves a list of markets with optional total count inclusion. ```APIDOC ## GET /v1/btc/15m/markets ### Description Retrieves a list of markets. By default, total counts are omitted for performance; use the include_count parameter to retrieve them. ### Method GET ### Endpoint https://api.kalshibacktest.com/v1/btc/15m/markets ### Parameters #### Query Parameters - **include_count** (boolean) - Optional - Set to true to include the total_count in the pagination object. - **limit** (integer) - Optional - The number of records to return. ``` -------------------------------- ### GET /v1/{coin}/{type}/markets/{ticker} Source: https://docs.kalshibacktest.com/api-reference/v1/get-market Fetch a single market by market_ticker or event_ticker. Exact market_ticker matches take precedence; for event tickers that map to multiple markets, the newest by close_time is returned. ```APIDOC ## GET /v1/{coin}/{type}/markets/{ticker} ### Description Fetch a single market by `market_ticker` or `event_ticker`. Exact `market_ticker` matches take precedence; for event tickers that map to multiple markets, the newest by `close_time` is returned. Unknown tickers return `404` with `error.code = MARKET_NOT_FOUND`. Free keys can fetch only the newest 50 markets for the requested `(coin, type)` pair; older known tickers return `403` with `error.code = PLAN_UPGRADE_REQUIRED`. ### Method GET ### Endpoint /v1/{coin}/{type}/markets/{ticker} ### Parameters #### Path Parameters - **coin** (string) - Required - The coin identifier (e.g., btc, eth, sol, doge, xrp). - **type** (string) - Required - The market type (e.g., 15m). - **ticker** (string) - Required - The market_ticker or event_ticker to fetch. ### Response #### Success Response (200) - **data** (object) - The requested market details. - **meta** (object) - Metadata including request_id. #### Response Example { "data": { "market_ticker": "KXBTC15M-26APR221830-T105000", "event_ticker": "KXBTC15M-26APR221830", "series_ticker": "KXBTC15M", "title": "Bitcoin above $105,000 at 18:30?", "subtitle": "15-minute market", "rules_primary": "If the final BTC price is strictly greater than $105,000 at 18:30 ET, this market resolves YES.", "strike_type": "greater", "floor_strike": 105000, "open_time": "2026-04-22T18:15:00Z", "close_time": "2026-04-22T18:30:00Z", "expiration_time": "2026-04-22T18:30:00Z", "coin_price_start": 104872.12, "coin_price_end": 105224.45, "expiration_value": 105224.45, "result": "yes", "settlement_ts": "2026-04-22T18:30:12Z", "status": "finalized", "created_at": "2026-04-22T18:14:58Z", "updated_at": "2026-04-22T18:30:12Z" }, "meta": { "request_id": "req_a1b2c3d4e5f6" } } ``` -------------------------------- ### GET /markets/{coin}/{type} Source: https://docs.kalshibacktest.com/api-reference/v1/list-markets Retrieves a paginated list of markets for a specific coin and market type. ```APIDOC ## GET /markets/{coin}/{type} ### Description Retrieves a paginated list of markets for a specific coin and market type. ### Method GET ### Endpoint /markets/{coin}/{type} ### Parameters #### Path Parameters - **coin** (string) - Required - Coin segment. One of `btc`, `eth`, `sol`, `doge`, `xrp`. - **type** (string) - Required - Market type. Today only `15m` is deployed. #### Query Parameters - **start_time** (string) - Optional - Lower bound on `close_time`. Accepts millisecond epoch or ISO-8601. - **end_time** (string) - Optional - Upper bound on `close_time`. Same format as `start_time`. - **limit** (integer) - Optional - Page size. 1-200. Default: 50. - **cursor** (string) - Optional - Opaque keyset cursor from a prior `pagination.next_cursor`. - **include_count** (boolean) - Optional - When `true`, run a `COUNT(*)` matching your filter and populate `pagination.total_count`. ### Response #### Success Response (200) - **data** (array) - List of markets. - **pagination** (object) - Pagination metadata. - **meta** (object) - Response metadata. #### Response Example { "data": [ { "market_ticker": "KXBTC15M-26APR221830-T105000", "event_ticker": "KXBTC15M-26APR221830", "series_ticker": "KXBTC15M", "title": "Bitcoin above $105,000 at 18:30?", "subtitle": "15-minute market", "rules_primary": "If the final BTC price is strictly greater than $105,000 at 18:30 ET, this market resolves YES.", "strike_type": "greater", "floor_strike": 105000, "open_time": "2026-04-22T18:15:00Z", "close_time": "2026-04-22T18:30:00Z", "expiration_time": "2026-04-22T18:30:00Z", "coin_price_start": 104872.12, "coin_price_end": 105224.45, "expiration_value": 105224.45, "result": "yes", "settlement_ts": "2026-04-22T18:30:12Z", "status": "finalized", "created_at": "2026-04-22T18:14:58Z", "updated_at": "2026-04-22T18:30:12Z" } ], "pagination": { "next_cursor": "eyJjdCI6IjIwMjYtMDQtMjJUMTg6MzA6MDBaIiwidGsiOiJLWEJUQzE1TS0yNkFQUjIyMTgzMC1UMTA1MDAwIn0", "has_more": true, "limit": 50, "count": 50, "total_count": null }, "meta": { "request_id": "req_a1b2c3d4e5f6", "timestamp": "2026-04-24T18:00:00Z" } } ``` -------------------------------- ### GET /v1/{coin}/{type}/markets/{market_ticker}/snapshots/at/{timestamp} Source: https://docs.kalshibacktest.com/ Retrieve the exact snapshot for a market at a specific moment in time. ```APIDOC ## GET /v1/{coin}/{type}/markets/{market_ticker}/snapshots/at/{timestamp} ### Description Retrieves the exact snapshot for a market at a specific ISO 8601 timestamp. ### Method GET ### Endpoint /v1/{coin}/{type}/markets/{market_ticker}/snapshots/at/{timestamp} ### Parameters #### Path Parameters - **coin** (string) - Required - The cryptocurrency ticker. - **type** (string) - Required - The market type. - **market_ticker** (string) - Required - The specific market identifier. - **timestamp** (string) - Required - The ISO 8601 formatted timestamp. ``` -------------------------------- ### GET /v1/{coin}/{type}/markets Source: https://docs.kalshibacktest.com/ List the most recent markets for a specific coin and market type. ```APIDOC ## GET /v1/{coin}/{type}/markets ### Description Retrieves a list of the most recent markets for the specified coin and market type. ### Method GET ### Endpoint /v1/{coin}/{type}/markets ### Parameters #### Path Parameters - **coin** (string) - Required - The cryptocurrency ticker (e.g., btc, eth). - **type** (string) - Required - The market type (e.g., 15m). #### Query Parameters - **limit** (integer) - Optional - The number of markets to return. ``` -------------------------------- ### GET /v1/{coin}/{type}/markets Source: https://docs.kalshibacktest.com/available-data Retrieves market information for a specific coin and cadence type. ```APIDOC ## GET /v1/{coin}/{type}/markets ### Description Retrieves market metadata for a specified coin and cadence type. ### Method GET ### Endpoint /v1/{coin}/{type}/markets ### Parameters #### Path Parameters - **coin** (string) - Required - The coin segment (e.g., btc, eth, sol, doge, xrp) - **type** (string) - Required - The cadence type (e.g., 15m) ``` -------------------------------- ### GET /v1/{coin}/{type}/markets/.../snapshots Source: https://docs.kalshibacktest.com/available-data Retrieves orderbook snapshots for a specific market. ```APIDOC ## GET /v1/{coin}/{type}/markets/.../snapshots ### Description Retrieves orderbook snapshots for a specific market. Snapshots include timestamps, best bid prices, coin prices, and sequence numbers. ### Method GET ### Endpoint /v1/{coin}/{type}/markets/.../snapshots ### Parameters #### Query Parameters - **include_orderbook** (boolean) - Optional - If set to true, includes full top-15 ladders for yes and no orderbooks. ``` -------------------------------- ### GET /markets/{ticker}/snapshot-at Source: https://docs.kalshibacktest.com/api-reference/v1/snapshot-at Retrieves the market metadata and the snapshot closest to the requested timestamp for a specific market ticker. ```APIDOC ## GET /markets/{ticker}/snapshot-at ### Description Retrieves the market metadata and the snapshot closest to the requested timestamp for a specific market ticker. ### Method GET ### Endpoint /markets/{ticker}/snapshot-at ### Parameters #### Path Parameters - **ticker** (string) - Required - The Kalshi market_ticker (e.g. KXBTC15M-26APR221830-T105000). #### Query Parameters - **timestamp** (string) - Required - The target timestamp to find the closest snapshot for. - **tolerance_ms** (integer) - Optional - The maximum allowed time difference in milliseconds between the requested timestamp and the actual snapshot time. ### Response #### Success Response (200) - **data** (object) - Market metadata wrapping the single snapshot closest to the requested timestamp. - **meta** (object) - Tracing / diagnostics block attached to the response. #### Error Response (404) - **error** (object) - Contains error code (MARKET_NOT_FOUND or SNAPSHOT_NOT_FOUND) and message. ``` -------------------------------- ### Health Check Response Example Source: https://docs.kalshibacktest.com/api-reference/v1/health The response body returned by the /v1/health endpoint, indicating the status of database pools and active market deployments. ```json { "data": { "status": "ok", "pools": { "btc:15m": true, "eth:15m": true, "sol:15m": true, "doge:15m": true, "xrp:15m": true, "auth": true }, "markets": [ { "coin": "btc", "type": "15m" }, { "coin": "eth", "type": "15m" }, { "coin": "sol", "type": "15m" }, { "coin": "doge", "type": "15m" }, { "coin": "xrp", "type": "15m" } ] }, "meta": { "request_id": "req_a1b2c3d4e5f6", "timestamp": "2026-04-24T18:00:00Z" } } ``` -------------------------------- ### Authentication Methods Source: https://docs.kalshibacktest.com/api-reference/v1/overview Shows the two supported methods for providing API keys in request headers. ```bash curl 'https://api.kalshibacktest.com/v1/btc/15m/markets' \ -H "X-API-Key: $KBT_KEY" # or curl 'https://api.kalshibacktest.com/v1/btc/15m/markets' \ -H "Authorization: Bearer $KBT_KEY" ``` -------------------------------- ### Integrate API with Python Source: https://docs.kalshibacktest.com/quickstart Use the httpx library to fetch markets and iterate through snapshots programmatically. ```python import httpx, os BASE = "https://api.kalshibacktest.com" KEY = os.environ["KBT_API_KEY"] with httpx.Client(base_url=BASE, headers={"X-API-Key": KEY}, timeout=30) as c: markets = c.get("/v1/btc/15m/markets", params={"limit": 10}).json() for m in markets["data"]: snapshots = c.get( f"/v1/btc/15m/markets/{m['market_ticker']}/snapshots", params={"limit": 1000, "include_orderbook": True}, ).json() # ... replay, score, write results ... ``` -------------------------------- ### Fetch Markets and Snapshots Source: https://docs.kalshibacktest.com/quickstart Retrieve market lists, specific market details, and historical snapshots using cURL. ```bash # Latest 5 BTC 15m markets curl "https://api.kalshibacktest.com/v1/btc/15m/markets?limit=5" \ -H "X-API-Key: kbt_your_api_key_here" # One market by its Kalshi ticker curl "https://api.kalshibacktest.com/v1/btc/15m/markets/KXBTC15M-26APR221830-T105000" \ -H "X-API-Key: kbt_your_api_key_here" # Stream snapshots ASC with full orderbook depth curl "https://api.kalshibacktest.com/v1/btc/15m/markets/KXBTC15M-26APR221830-T105000/snapshots?include_orderbook=true&limit=500" \ -H "X-API-Key: kbt_your_api_key_here" # Snapshot closest to a specific wall-clock moment curl "https://api.kalshibacktest.com/v1/btc/15m/markets/KXBTC15M-26APR221830-T105000/snapshots/at/2026-04-22T18:20:00Z" \ -H "X-API-Key: kbt_your_api_key_here" ``` -------------------------------- ### GET /health Source: https://docs.kalshibacktest.com/api-reference/v1/health Checks the health status of the service and its database connections. ```APIDOC ## GET /health ### Description Returns the current health status of the service. It verifies that all configured database pools, including the authentication database, are reachable. ### Method GET ### Endpoint /health ### Response #### Success Response (200) - **status** (string) - Returns 'ok' if all pools are reachable, or 'degraded' otherwise. ``` -------------------------------- ### Authenticate with API Key Header Source: https://docs.kalshibacktest.com/api-reference/authorization Use the x-api-key header to provide your API key directly. ```http x-api-key: kbt_... ```