--- title: "Get a live perpetual market-data snapshot" method: GET path: "/v1/perpetuals/{venue}/{instrument}/snapshot" tags: ["Perpetuals"] --- # Get a live perpetual market-data snapshot `GET /v1/perpetuals/{venue}/{instrument}/snapshot` ## Request - Base URL: `https://md.kairos.trade` - URL: `https://md.kairos.trade/v1/perpetuals/{venue}/{instrument}/snapshot` - Auth: one of: - none - API key in header `X-Client-Id` and API key in header `X-Api-Key` and API key in header `X-Api-Secret` Production beta, sourced directly from the selected venue by the Market Data API. Returns a canonical ordered book, recent trades, one-minute candles, funding observations, and typed market state. Financial values are exact decimal strings. Prices are direct venue prices, never 0–100 prediction probabilities. Quantities and volumes retain the declared `base_asset` or `contracts` unit. Do not derive notional for contract quantities without authoritative instrument metadata, and never apply the prediction-market `/ 100` formula. Each request costs 6 units in the HEAVY rate-limit bucket because it fans out to multiple venue resources. Responses are never cacheable by clients; the Market Data API uses a bounded one-second replica-local cache to coalesce bursts. ## Path parameters - `venue` 'hyperliquid' | 'polymarket_perps' | 'kalshi_margin', required - `instrument` string, required ## Query parameters - `depth` integer ## Response `200` Live canonical venue snapshot. - PerpetualSnapshot: Live perpetual snapshot, in beta. Prices are direct venue prices. Quantities retain native units. This object intentionally carries no synthesized notional: consumers must inspect `instrument_context` and must not convert contract quantities when `contract_multiplier` is null. - `venue` 'hyperliquid' | 'polymarket_perps' | 'kalshi_margin', required - `environment` string, required: Venue environment for this source identity. - `integration_id` string, required: Kairos integration and routing identity. - `canonical_instrument_id` string, required: Stable Kairos perpetual instrument identity. - `venue_instrument_id` string, required: Exact venue-native instrument identifier. - `instrument_context` PerpetualInstrumentContext, required - `base_asset_id` string, required - `quote_asset_id` string, required: Asset in which direct prices are expressed. Hyperliquid standard main-dex perpetuals use USDT. - `collateral_asset_id` string, required: Asset securing margin. This is independent of the quote asset; Hyperliquid standard main-dex perpetuals use USDC collateral. - `settlement_asset_id` string, required: Asset in which settlement or realized PnL is denominated. Hyperliquid uses USDC, Polymarket Perps uses pUSD, and Kalshi Margin uses USD. - `price_unit` string, required: Explicit unit relationship for every direct price in the snapshot. A perpetual price is never a 0–100 prediction probability. - `quantity_unit` 'base_asset' | 'contracts', required: Native quantity unit used by books and trades. Candle volume declares its own `native_volume_unit` and may differ; for example, a venue can quote book/trade quantities as contracts but kline volume as base asset. - `contract_multiplier` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `notional_formula` string, required: Machine-readable formula identity describing any supported notional conversion. It is not the prediction-market `size * price / 100` formula. - `book` PerpetualOrderBookSnapshot, required - `bids` PerpetualBookLevel[], required: Price levels ordered strictly highest to lowest. - `price` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `quantity` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `order_count` integer, nullable, required: Venue-reported order count at this level, or null when unavailable. - `asks` PerpetualBookLevel[], required: Price levels ordered strictly lowest to highest. - `price` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `quantity` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `order_count` integer, nullable, required: Venue-reported order count at this level, or null when unavailable. - `event_time_ns` integer, nullable, required: Venue event time in Unix nanoseconds, or null when unavailable. - `received_time_ns` integer, required: Kairos receive time in Unix nanoseconds. - `source_sequence` integer, nullable, required: Venue-native source sequence, or null for an unsequenced source. - `sequence_domain` string, required: Scope in which `source_sequence` has meaning. - `feed_mode` 'snapshot_only', required: The preview exposes complete REST snapshots, not deltas. - `depth` integer, required: Number of levels returned on the deeper populated side. - `requested_depth` integer, required: Depth requested by the caller. - `source_depth_limit` integer, nullable, required: Authoritative maximum depth imposed by the source endpoint, or null when the source does not declare a fixed limit. - `depth_limited` boolean, required: True when the returned depth is below `requested_depth` because of an identified source limit. False does not imply both sides contain the requested number of populated levels. - `native_volume_unit` 'base_asset' | 'contracts', required: Native quantity unit for every level in this book. - `market_state` PerpetualMarketState, required - `event_time_ns` integer, required: Market-state event time in Unix nanoseconds. - `status` 'active' | 'inactive' | 'delisted' | 'unknown', required - `prices` PerpetualPriceObservation[], required - `price_type` string, required: Venue-backed price identity, such as mark, index, oracle, or mid. - `value` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `observed_time_ns` integer, nullable, required: Observation time in Unix nanoseconds, or null when unavailable. - `measures` PerpetualMeasureObservation[], required - `measure_type` string, required: Measure identity, such as open_interest or open_interest_notional. - `value` string, required: Normalized, exact base-10 decimal greater than or equal to zero. - `unit` string, required: Explicit venue-native or derived unit, such as base_asset, contracts, or usd. - `next_funding_time_ns` integer, nullable, required: Next funding time in Unix nanoseconds, or null when unavailable. - `trades` PerpetualPublicTrade[], required: Recent public trades in venue-native quantity units. - `trade_id` string, required: Venue-native public trade identifier. - `price` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `quantity` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `quantity_unit` 'base_asset' | 'contracts', required - `side` 'buy' | 'sell', required - `event_time_ns` integer, required: Venue trade time in Unix nanoseconds. - `candles` PerpetualTradeCandle[], required: One-minute trade candles in venue-native volume units. - `interval` string, required: Venue candle interval. The preview currently requests one minute. - `interval_start_ns` integer, required: Inclusive start of the candle's half-open interval, in Unix nanoseconds. - `interval_end_ns` integer, required: Exclusive end of the candle's half-open interval, in Unix nanoseconds. - `open` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `high` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `low` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `close` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `native_volume` string, required: Normalized, exact base-10 decimal greater than or equal to zero. - `native_volume_unit` 'base_asset' | 'contracts', required: Native unit reported by the candle source. It may differ from the book and trade quantity unit for the same instrument. - `trade_count` integer, nullable, required: Venue-reported trade count, or null when unavailable. - `finality` 'open' | 'closed_unconfirmed', required: `open` means the interval has not closed. `closed_unconfirmed` means its half-open interval has ended, but the preview does not claim an immutable or venue-confirmed final candle. - `funding` PerpetualFundingRate[], required: Final or estimated funding observations using positive_longs_pay sign convention. - `rate` string, required: Normalized, exact base-10 decimal. No exponent notation, leading zeros, trailing fractional zeros, NaN, or infinity. May be negative. - `phase` 'estimate' | 'final', required - `effective_time_ns` integer, required - `calculated_time_ns` integer, nullable, required: Calculation time in Unix nanoseconds, or null when unavailable. - `rate_period_seconds` integer, nullable, required: Period represented by `rate`, or null when the venue does not provide it. - `payment_interval_seconds` integer, nullable, required: Funding payment interval, or null when unavailable. - `sign_convention` 'positive_longs_pay', required - `funding_price` string, required: Normalized, exact base-10 decimal strictly greater than zero. - `funding_price_type` string, nullable, required: Identity of `funding_price`, such as mark, or null with no price. - `source` 'venue_public_api', required - `fetched_at_ns` integer, required: Kairos fetch completion time in Unix nanoseconds. ## Other responses - `400`: `unsupported perpetual venue` (a `venue` outside the enum), `depth must be an integer`, `depth must be between 1 and 500`, or `invalid perpetual instrument` — the instrument is empty, longer than 128 bytes, or does not match the venue's identifier grammar (`^[A-Za-z0-9][A-Za-z0-9._-]*$` for Hyperliquid, which is what rejects HIP-3 `dex:coin`; a positive integer for `polymarket_perps`; `^KX[A-Z0-9]+PERP$` for `kalshi_margin`). - `401`: No valid credential presented. Every path returns `code: unauthorized`; the triggers differ: - An `Authorization` header on a deployment where bearer auth is not enabled (`bearer authentication is not enabled`). - A bearer token that fails verification (`invalid or expired session`), or whose token/session has been revoked (`session has been revoked`). - An incomplete or wrong API-key header set. Sending *any* of `X-Client-Id`, `X-Api-Key`, `X-Api-Secret` commits the request to the API-key path, so a partial set is rejected rather than silently degrading to anonymous limits (`valid X-Client-Id, X-Api-Key, and X-Api-Secret headers are required`). - No credential material at all while the anonymous free tier is unavailable — switched off for the deployment, forced off through the runtime kill switch, or not yet resolvable on a replica that has never read the flag (it fails closed). - `403`: API key presented from a source IP not in that credential's whitelist. - `429`: Two different gates return this status, both with `code: rate_limited`: - **Per-credential (or per-IP, when anonymous) weighted budget exhausted.** The message is `rate limit exceeded`, or, for anonymous callers, `anonymous rate limit exceeded — request an API key for higher limits (…)`. `Retry-After` is the whole number of seconds until the current one-minute window rolls over, floored at 1. All four `X-RateLimit-*` headers are present. - **Per-IP admission gate.** An in-process, pre-authentication guard that keeps a flood off the shared credential cache and database. The message is `too many requests from this address` and `Retry-After` is a flat `60`. Because this fires *before* authentication, the response carries **no** `X-RateLimit-*` headers at all. - `500`: `internal` / `authentication backend unavailable` — the API-key path could not reach the credential store. - `502`: `upstream` / `perpetual venue data is unavailable or invalid`. Covers every non-validation failure: the venue returned a non-2xx status or an undecodable body, the 12s composite fetch deadline expired, or the assembled snapshot failed canonical validation (crossed or unsorted book, non-exact decimal, unknown market status, bad candle interval, unknown funding sign convention). - `503`: The rate limiter is unreachable. Fails CLOSED — the request is rejected rather than let through unmetered. --- [API](https://skmtc.dev/kairos/apis/kairos-market-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-market-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-market-data-api/revisions/01e987f59a04?raw)