---
title: "Discover perpetual instruments"
method: GET
path: "/perpetuals/instruments"
tags: ["Perpetuals"]
---

# Discover perpetual instruments

`GET /perpetuals/instruments`

## Request

- Base URL: `https://staging-data.kairos.trade`
- URL: `https://staging-data.kairos.trade/perpetuals/instruments`
- Auth: none required

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.

## Query parameters

- `venue` 'hyperliquid' | 'polymarket_perps' | 'kalshi_margin': Canonical perpetual venue identifier.

## Response `200`

Canonical perpetual instrument records.

- PerpetualInstrument[]
  - `instrument_id` string, required: Stable Kairos instrument identity. Hyperliquid standard assets use `hl-mainnet-{base}-usdt`; HYPE and PURR use the USDC exception.
  - `venue` 'hyperliquid' | 'polymarket_perps' | 'kalshi_margin', required: Canonical perpetual venue identifier.
  - `integration_id` string, required: Product-specific routing and credential boundary.
  - `environment` string, required
  - `venue_instrument_id` string, required: Exact identifier accepted by the venue and Market Data API snapshot endpoint.
  - `display_symbol` string, required
  - `base_asset_id` string, required
  - `quote_asset_id` string, required: Hyperliquid uses USDT except for HYPE and PURR, which use USDC.
  - `collateral_asset_id` string, required
  - `settlement_asset_id` string, nullable, required
  - `native_quantity_unit` 'base_asset' | 'contracts', required
  - `contract_multiplier` string, nullable, required: Exact decimal string, or null when no authoritative conversion exists.
  - `status` 'active' | 'inactive' | 'closed' | 'delisted' | 'unknown', required
  - `isolated_only` boolean, nullable, required: Null when the venue does not publish an authoritative mode.
  - `max_leverage` string, nullable, required: Exact decimal string when published by the venue.
  - `price_increment` string, nullable, required: Exact venue price increment; null when not established.
  - `size_increment` string, nullable, required: Exact venue quantity increment; null when not established.
  - `metadata` union, required
    - HyperliquidPublicMetadata
      - `kind` 'hyperliquid', required
      - `listing_namespace` 'validator_main_dex', required
      - `margin_table_id` integer, required
      - `venue_margin_mode` string, nullable, required
    - PolymarketPublicMetadata
      - `kind` 'polymarket_perps', required
      - `category` string, required
      - `funding_interval` string, required
      - `price_decimals` integer, required
      - `risk_tiers` PolymarketRiskTier[], required
        - `lower_bound` string, required: Exact decimal-string lower bound for the tier.
        - `max_leverage` integer, required
    - KalshiPublicMetadata
      - `kind` 'kalshi_margin', required
      - `title` string, required
      - `fractional_trading_enabled` boolean, required
      - `sampled_leverage` KalshiSampledLeverage, required
        - `semantics` 'sampled_estimate', required
        - `leverage` string, required: Exact decimal-string leverage estimate.
        - `sample_notional_usd` string, nullable, required: Exact decimal-string sample notional, or null.
      - `sampled_leverage_curve` KalshiSampledLeverage[], required
        - `semantics` 'sampled_estimate', required
        - `leverage` string, required: Exact decimal-string leverage estimate.
        - `sample_notional_usd` string, nullable, required: Exact decimal-string sample notional, or null.
      - `schedule` KalshiMarketSchedule, required
        - `is_open` boolean, required
        - `next_close_ts` integer, nullable, required: Venue Unix timestamp, or null when no next close is published.
        - `next_open_ts` integer, nullable, required: Venue Unix timestamp, or null when no next open is published.

## Other responses

- `404`: The staging preview is disabled.
- `422`: Request failed FastAPI parameter validation.
- `429`: 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.
- `502`: Venue metadata was unavailable or failed strict validation.

---

[API](https://skmtc.dev/kairos/apis/kairos-data-api.md) - [All operations](https://skmtc.dev/kairos/apis/kairos-data-api/llms.txt) - [OpenAPI document](https://skmtc.dev/kairos/apis/kairos-data-api/revisions/cf6b76079e38?raw)