{"uid":"cap_ZZkUMpw-mTV7mVrFQpEel","slug":"laevitas-perpetuals-instrument-history-discovery-2885c4f2","name":"Laevitas Perpetuals Instrument History Discovery","description":"Professional market data API for crypto derivatives, spot markets, prediction markets, Hyperliquid HyperCore data, proprietary volatility surfaces, and analytics.\n\n## Authentication\n\nUse an API key for authenticated REST requests:\n\n```http\nX-API-Key: your-api-key-here\n```\n\nData and history endpoints also accept x402 without an API key: 1, 5 or 10 credits ($0.001 each) for data up to 1 year, 1–3 years or older.\n\n**Subscriptions with USDC:** Premium and Enterprise can be purchased on Base or Solana for a month, a quarter, six months or a year. Access is prepaid, with no automatic renewal. [Buy a subscription](https://v3.laevitas.ch/profile/subscription/wallet) or read the [USDC subscription guide](/x402#subscriptions).\n\nThe subscription belongs to your signed-in Laevitas account; wallet sign-in does not require an email. Enterprise users generate an API key in V3 after activation. Plan and billing-period limits still apply. Subscription purchases are separate from API credit bundles.\n\nFor Claude MCP, add `https://apiv2.laevitas.ch/api/v1/mcp`, select **Sign in now → Register automatically**\nwith no custom headers, and authorize with your API key on the Laevitas page.\nDo not enter a client ID or secret manually. All OAuth clients require PKCE S256.\nConnection guide: [MCP setup](/mcp). CIMD / published client identity is not supported.\n\n| Resource | Path |\n| --- | --- |\n| OpenAPI JSON | `GET /openapi.json` |\n| x402 discovery | `GET /.well-known/x402` |\n| Changelog | `GET /api/v1/changelog` |\n| WebSocket docs | `GET /websocket` |\n\n## REST Surfaces\n\n| Surface | Examples |\n| --- | --- |\n| Instruments | Cross-market contract reference data |\n| Futures | OHLCVT, trades, tickers, orderbook, liquidations, carry |\n| Perpetuals | OHLCVT, trades, funding, open interest, orderbook, liquidations |\n| Options | OHLCVT, trades, Greeks, volatility, flow, dealer GEX |\n| Options Backtests | Strategy templates, asynchronous submission, status, combined results, cancellation |\n| Vol Surface | Proprietary surface snapshots, slices, strikes, term structure, risk |\n| Spot | OHLCVT, ticker, trades, volume, L2 orderbook, snapshots |\n| Predictions | Polymarket instruments, categories, trades, ticker history |\n| Hyperliquid - HyperCore | Node-derived fills, liquidations, positions, funding, TWAPs, resting orders, L2 books |\n| Analytics | Realized volatility and derived metrics |\n\n## Pagination\n\nBacktests are asynchronous jobs, not paginated market-data queries. Start with\n`GET /api/v1/options/backtests/strategies`, submit with `POST /api/v1/options/backtests`,\nthen poll `/{id}` and retrieve `/{id}/result`. These responses have no data/meta wrapper.\n\nPaginated endpoints return the cursor at `meta.next_cursor`. Pass that value back as the `cursor` query parameter to fetch the next page.\n\n## WebSocket Streaming\n\nReal-time streams are documented at `/websocket`.\n\n| Data | Channel pattern |\n| --- | --- |\n| Trades | `trades.{market}.{exchange}.{instrument}` |\n| OHLC ticker | `ohlc.ticker.{market}.{exchange}.{instrument}.{timeframe}` |\n| OHLCVT | `ohlc.vt.{market}.{exchange}.{instrument}.{timeframe}` |\n\nVariables: `market` is one of `perpetuals`, `futures`, `options`, or `spot`; `timeframe` is one of `1m`, `5m`, `15m`, `1h`, `4h`, or `1d`.\n\n## Quick Start\n\n```bash\ncurl \"https://apiv2.laevitas.ch/api/v1/futures/ohlcvt?exchange=deribit&instrument_name=BTC-PERPETUAL\" \\\n  -H \"X-API-Key: your-api-key-here\"\n```","url":"https://apiv2.laevitas.ch/api/v1/perpetuals/instrument-history/discovery?utm_source=zero.xyz","method":"POST","headers":{},"bodySchema":{"type":"object","required":["mode","currency","exchange"],"properties":{"date":{"type":"string","description":"Required only for instruments: YYYY-MM-DD UTC day to search, not an expiry or a trading-status date."},"mode":{"enum":["instruments","coverage"],"type":"string","description":"instruments finds contract names observed on a UTC day. coverage reports retained observation bounds for one exact currency and contract."},"limit":{"type":"integer","description":"instruments page size, default 100, maximum 500. Not accepted for coverage."},"cursor":{"type":"string","description":"instruments continuation from meta.next_cursor; keep the same product, exchange, currency, date and limit."},"currency":{"type":"string","description":"Required in both modes. Exact historical currency label, for example BTC. Currency aliases are not expanded. Contracts with different quote currencies or multipliers may share this label; their names stay separate."},"exchange":{"enum":["binance","bitmex","deribit","okx","dydx","huobi","kraken","bybit","bitget","aevo","blitz","coinbase","bitfinex","hyperliquid","paradex","vertex"],"type":"string","description":"Venue supported by the corresponding instrument-history route. Acceptance does not establish that matching history exists."},"instrument_name":{"type":"string","description":"Required only for coverage. Exact, case-sensitive contract name copied from instruments; letter-case variants stay separate."}}},"responseSchema":{"type":"object","required":["data","meta"],"properties":{"data":{"type":"array","items":{"type":"object","required":["instrument_name","first_observed_at","last_observed_at","retrieval"],"properties":{"retrieval":{"type":"object","required":["path","parameters"],"properties":{"path":{"enum":["/api/v1/perpetuals/instrument-history","/api/v1/futures/instrument-history"],"type":"string"},"parameters":{"type":"object","required":["exchange","instrument_name","start","end","resolution","projection","page","limit"],"properties":{"end":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"page":{"enum":[1],"type":"number"},"limit":{"enum":[100],"type":"number"},"start":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"},"exchange":{"enum":["binance","bitmex","deribit","okx","dydx","huobi","kraken","bybit","bitget","aevo","blitz","coinbase","bitfinex","hyperliquid","paradex","vertex"],"type":"string"},"projection":{"enum":["full"],"type":"string"},"resolution":{"enum":["native"],"type":"string"},"instrument_name":{"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"instrument_name":{"type":"string"},"last_observed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"Last observed timestamp for the declared currency and bounds_scope; not expiry or delisting time."},"first_observed_at":{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$","description":"First observed timestamp for the declared currency and bounds_scope; not listing or publication time."}},"additionalProperties":false}},"meta":{"type":"object","required":["dataset_id","definition_id","instrument_type","mode","exchange","currency","date","bounds_scope","next_cursor","completeness","sampling"],"properties":{"date":{"type":"string","nullable":true},"mode":{"enum":["instruments","coverage"],"type":"string"},"currency":{"type":"string"},"exchange":{"enum":["binance","bitmex","deribit","okx","dydx","huobi","kraken","bybit","bitget","aevo","blitz","coinbase","bitfinex","hyperliquid","paradex","vertex"],"type":"string"},"sampling":{"type":"object","required":["kind","native_interval_seconds","supported_resolutions","meaning"],"properties":{"kind":{"enum":["point_in_time_observations"],"type":"string"},"meaning":{"type":"string"},"supported_resolutions":{"type":"array","items":{"enum":["native","1m","5m","15m","30m","1h","2h","4h","6h","12h","1d"],"type":"string"}},"native_interval_seconds":{"enum":[null],"type":"string","nullable":true,"description":"No single native interval is certified over these bounds."}},"additionalProperties":false},"dataset_id":{"enum":["perpetuals.instrument_observations","futures.instrument_observations"],"type":"string","description":"Matches dataset_id in the corresponding history response."},"next_cursor":{"type":"string","nullable":true},"bounds_scope":{"enum":["requested_utc_day","currency_instrument"],"type":"string","description":"Both scopes require the exact historical currency label. currency_instrument covers all retained dates under that label only; other currency labels are not included."},"completeness":{"enum":["not_certified"],"type":"string"},"definition_id":{"enum":["perpetuals.instrument_history","futures.instrument_history"],"type":"string"},"instrument_type":{"enum":["perpetual","future"],"type":"string"}},"additionalProperties":false}},"additionalProperties":false},"example":null,"exampleRequest":null,"tags":["x402"],"displayCostAmount":"0.1","displayCostAsset":"USDC","priceDynamic":false,"priceHint":null,"priceStatus":"priced","priceSource":"probe","requiresHandshake":false,"reviewCount":0,"rating":{"score":"0.00","successRate":"0.00","reviews":0,"stars":null,"state":"unrated"},"availabilityStatus":"unknown","priceObserved":null,"sessionDeposit":null,"pricing":{"kind":"static","summary":"$0.1/call","primary":{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"},"accepted":[{"kind":"static","protocol":"x402","network":"base","amountUsd":"0.1","per":"call","confidence":"exact"}]},"paymentMethods":[{"uid":"pm_KZGt05SjMKReU5kucXtrN","protocol":"x402","methodType":"crypto","chain":"base","mode":"charge","costAmount":"0.1","costPer":"request","priority":0,"asset":"0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913","unit":"request","depositMicros":null,"planRef":null}],"brandName":null,"brandSlug":null,"brandBaseUrl":null,"brandDocsUrl":null,"whatItDoes":"Discovers historical perpetual contract names observed on a given exchange/currency/date, or retrieves observation bounds for a specific contract.","exampleAgentPrompt":"Using Laevitas, find all BTC perpetual contract names that were observed on Binance on 2024-01-15, using instruments mode with a page size of 100.","exampleUseCases":[{"title":"Audit available BTC perps on a date","prompt":"Show me all the BTC perpetual contract names that were active on Bybit on March 1st 2024 — I want to know every instrument that was observed that day."},{"title":"Check coverage bounds for a specific perp","prompt":"I need to know when Laevitas first and last recorded data for the BTC-PERP instrument on Deribit — can you look up the coverage for that exact contract?"},{"title":"Enumerate ETH perps across exchange for research","prompt":"Can you list all ETH perpetual instruments Laevitas has on record for OKX from January 10th 2024, paginating through up to 500 results?"}],"resultDescription":"Returns an array of perpetual instrument records, each containing the exact contract name, the first and last timestamps it was observed, and a retrieval object with the path and parameters needed to fetch its full historical data. Also includes pagination metadata with a next_cursor for continuing large result sets.","failureModes":["Missing required fields (mode, currency, exchange) returns validation error","Invalid exchange value not in enum returns 400","instrument_name required for coverage mode but not provided returns error","date required for instruments mode but missing returns error","No matching history for the given exchange/currency/date returns empty data array","Invalid cursor or mismatched pagination parameters returns error","Expired or missing API key / insufficient x402 credits returns 401/402"],"whenToPreferThis":"Use this endpoint when you need to discover which perpetual contract names existed on a specific exchange at a point in time, or when you want to know the exact observation date range for a named perpetual instrument before fetching its full history. It is the right starting point when you don't yet know the exact instrument name or when you need to enumerate all available perps for a currency/exchange/date combination before calling the instrument-history endpoint.","instructions":null,"reviewSummary":null,"reviewSummaryHighlights":null,"reviewSummaryConcerns":null,"reviewSummaryGeneratedAt":null,"activationCount":0,"lastUsedAt":null,"lastSuccessfullyRanAt":null,"lastHealthCheckAt":"2026-10-31T18:41:40.481Z","isFirstParty":false,"canonicalSlug":"laevitas-perpetuals-instrument-history-discovery-2885c4f2"}