> ## Documentation Index > Fetch the complete documentation index at: https://docs.kairos.trade/llms.txt > Use this file to discover all available pages before exploring further. # Discover perpetual instruments > Returns strict canonical instrument metadata, optionally for one venue. Financial values are exact decimal strings or null; consumers must not invent a contract multiplier, tick, or leverage value when one is absent. Results are cached independently per venue for 60 seconds. This endpoint owns discovery and instrument rules only. Fetch live market state from the Market Data API's REST snapshot endpoint and real-time transport from `websocket_cpp`. This preview exists only in Kairos staging and returns 404 when disabled. ## OpenAPI ````yaml /openapi/data-api.yaml get /perpetuals/instruments openapi: 3.1.0 info: title: Kairos Data API version: 1.0.0 summary: >- The full Kairos data plane — markets, candles, trades, search, discover, sports, trader analytics, and PnL. description: | The Kairos Data API at `data.kairos.trade` is the platform's primary data plane: market metadata and prices, OHLCV candles, live venue trade proxies, normalized trade history, full-text search, discovery feeds, the sports catalog, public trader analytics, and account PnL. ## Authentication Most endpoints accept a Kairos **API key** (`X-Client-Id` + `X-Api-Key` + `X-Api-Secret`, all three) or a first-party session JWT. Endpoints tagged `public` (trader analytics, provider configs, several sports feeds) need no credentials at all. Some endpoints additionally require an API-key **scope** (`trade:read`, `position:read`) — stated per operation. For high-volume market-data consumption (candles/trades/metadata at scale), prefer the dedicated **Market Data API** at `md.kairos.trade` — it has higher budgets, ETag caching, and a binary candle format. ## Rate limits Rate limits use a sliding window keyed on the authenticated user (JWT `sub`) or, for anonymous callers, the trusted client IP. Routes belong to a named **bucket** (`x-kairos-bucket`) whose per-minute budget is shared by every route in it; routes with no bucket run under the service default of 100/minute. `x-kairos-rate-limit` states the bucket's compile-time default — operators can raise or lower a bucket at runtime, so treat the documented number as the baseline, not a contract. 429 responses carry `Retry-After` and `X-RateLimit-*`. ## Conventions - Prices are on the **0–100 cents scale** unless a field says otherwise (trader-analytics position/trade prices use the 0–1 scale; each field's description states its scale). - Errors: `{"detail": ""}` for handler errors; FastAPI's standard validation envelope for 422s. Errors surfaced from a venue adapter instead use `{"error", "provider", "operation", "message"}` — see `DataProviderError`. Unhandled failures always return the generic 500 body; internal details are logged, never returned. - Every request body is capped at 8 MiB service-wide (413). contact: name: Kairos url: https://app.kairos.trade/docs/api-reference termsOfService: https://kairos.trade/terms servers: - url: https://data.kairos.trade description: Production - url: https://staging-data.kairos.trade description: Staging security: - apiKeyClientId: [] apiKeyKey: [] apiKeySecret: [] paths: /perpetuals/instruments: get: tags: - Perpetuals summary: Discover perpetual instruments description: > Returns strict canonical instrument metadata, optionally for one venue. Financial values are exact decimal strings or null; consumers must not invent a contract multiplier, tick, or leverage value when one is absent. Results are cached independently per venue for 60 seconds. This endpoint owns discovery and instrument rules only. Fetch live market state from the Market Data API's REST snapshot endpoint and real-time transport from `websocket_cpp`. This preview exists only in Kairos staging and returns 404 when disabled. operationId: listPerpetualInstruments parameters: - name: venue in: query required: false description: Restrict discovery to one canonical venue. schema: $ref: '#/components/schemas/PerpetualVenue' responses: '200': description: Canonical perpetual instrument records. content: application/json: schema: type: array items: $ref: '#/components/schemas/PerpetualInstrument' '404': description: The staging preview is disabled. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: Perpetual metadata is disabled '422': $ref: '#/components/responses/DataValidationError' '429': $ref: '#/components/responses/DataRateLimited' '502': description: Venue metadata was unavailable or failed strict validation. content: application/json: schema: $ref: '#/components/schemas/DataError' example: detail: Perpetual venue metadata is unavailable or invalid security: [] servers: - url: https://staging-data.kairos.trade description: Staging preview only components: schemas: PerpetualVenue: type: string description: Canonical perpetual venue identifier. enum: - hyperliquid - polymarket_perps - kalshi_margin PerpetualInstrument: type: object additionalProperties: false required: - instrument_id - venue - integration_id - environment - venue_instrument_id - display_symbol - base_asset_id - quote_asset_id - collateral_asset_id - settlement_asset_id - native_quantity_unit - contract_multiplier - status - isolated_only - max_leverage - price_increment - size_increment - metadata properties: instrument_id: type: string description: | Stable Kairos instrument identity. Hyperliquid standard assets use `hl-mainnet-{base}-usdt`; HYPE and PURR use the USDC exception. examples: - hl-mainnet-btc-usdt - hl-mainnet-hype-usdc - hl-mainnet-purr-usdc venue: $ref: '#/components/schemas/PerpetualVenue' integration_id: type: string description: Product-specific routing and credential boundary. environment: type: string venue_instrument_id: type: string description: >- Exact identifier accepted by the venue and Market Data API snapshot endpoint. display_symbol: type: string examples: - BTC-USDT - HYPE-USDC - PURR-USDC base_asset_id: type: string quote_asset_id: type: string description: Hyperliquid uses USDT except for HYPE and PURR, which use USDC. examples: - USDT - USDC collateral_asset_id: type: string settlement_asset_id: type: - string - 'null' native_quantity_unit: type: string enum: - base_asset - contracts contract_multiplier: type: - string - 'null' description: >- Exact decimal string, or null when no authoritative conversion exists. status: type: string enum: - active - inactive - closed - delisted - unknown isolated_only: type: - boolean - 'null' description: Null when the venue does not publish an authoritative mode. max_leverage: type: - string - 'null' description: Exact decimal string when published by the venue. price_increment: type: - string - 'null' description: Exact venue price increment; null when not established. size_increment: type: - string - 'null' description: Exact venue quantity increment; null when not established. metadata: $ref: '#/components/schemas/PublicInstrumentMetadata' DataError: type: object description: Handler error envelope (FastAPI HTTPException). required: - detail properties: detail: type: string description: Human-readable error message. example: Invalid provider PublicInstrumentMetadata: oneOf: - $ref: '#/components/schemas/HyperliquidPublicMetadata' - $ref: '#/components/schemas/PolymarketPublicMetadata' - $ref: '#/components/schemas/KalshiPublicMetadata' discriminator: propertyName: kind mapping: hyperliquid: '#/components/schemas/HyperliquidPublicMetadata' polymarket_perps: '#/components/schemas/PolymarketPublicMetadata' kalshi_margin: '#/components/schemas/KalshiPublicMetadata' HyperliquidPublicMetadata: type: object additionalProperties: false required: - kind - listing_namespace - margin_table_id - venue_margin_mode properties: kind: type: string const: hyperliquid listing_namespace: type: string const: validator_main_dex margin_table_id: type: integer venue_margin_mode: type: - string - 'null' PolymarketPublicMetadata: type: object additionalProperties: false required: - kind - category - funding_interval - price_decimals - risk_tiers properties: kind: type: string const: polymarket_perps category: type: string funding_interval: type: string price_decimals: type: integer risk_tiers: type: array items: $ref: '#/components/schemas/PolymarketRiskTier' KalshiPublicMetadata: type: object additionalProperties: false required: - kind - title - fractional_trading_enabled - sampled_leverage - sampled_leverage_curve - schedule properties: kind: type: string const: kalshi_margin title: type: string fractional_trading_enabled: type: boolean sampled_leverage: oneOf: - $ref: '#/components/schemas/KalshiSampledLeverage' - type: 'null' sampled_leverage_curve: type: array items: $ref: '#/components/schemas/KalshiSampledLeverage' schedule: oneOf: - $ref: '#/components/schemas/KalshiMarketSchedule' - type: 'null' PolymarketRiskTier: type: object additionalProperties: false required: - lower_bound - max_leverage properties: lower_bound: type: string description: Exact decimal-string lower bound for the tier. max_leverage: type: integer KalshiSampledLeverage: type: object additionalProperties: false required: - semantics - leverage - sample_notional_usd properties: semantics: type: string const: sampled_estimate leverage: type: string description: Exact decimal-string leverage estimate. sample_notional_usd: type: - string - 'null' description: Exact decimal-string sample notional, or null. KalshiMarketSchedule: type: object additionalProperties: false required: - is_open - next_close_ts - next_open_ts properties: is_open: type: boolean next_close_ts: type: - integer - 'null' description: Venue Unix timestamp, or null when no next close is published. next_open_ts: type: - integer - 'null' description: Venue Unix timestamp, or null when no next open is published. responses: DataValidationError: description: Request failed FastAPI parameter validation. content: application/json: schema: type: object required: - detail properties: detail: type: array description: >- One entry per failed field, with location, message, and error type. items: type: object additionalProperties: true DataRateLimited: description: > Rate limit exceeded for this route's sliding window, keyed on the session `sub` when authenticated and on the trusted client IP otherwise. Honor `Retry-After`. A per-API-key data ceiling (set per credential) rejects with `{"detail": "API key data rate limit exceeded"}` instead of the `error` envelope below. headers: Retry-After: schema: type: integer X-RateLimit-Limit: schema: type: integer X-RateLimit-Remaining: schema: type: integer X-RateLimit-Reset: schema: type: integer content: application/json: schema: type: object properties: error: type: string example: 'Rate limit exceeded: 100 per 1 minute' securitySchemes: apiKeyClientId: type: apiKey in: header name: X-Client-Id description: >- Credential client id (`kairos_ck_...`). Must be sent together with X-Api-Key and X-Api-Secret. apiKeyKey: type: apiKey in: header name: X-Api-Key description: 64-char hex API key. apiKeySecret: type: apiKey in: header name: X-Api-Secret description: 64-char hex API secret. ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.