{"openapi":"3.0.0","paths":{"/api/v1/x402/ws-pass/hour":{"post":{"description":"Purchase a 1-hour WebSocket streaming entitlement via x402 (USDC on Base mainnet). On success, the wallet is granted a pass slot in Redis and an `x-credit-token` JWT is returned that authenticates subsequent WebSocket connections at `/ws` and `/stream`. Buying a pass while one is already active extends the expiry additively.","operationId":"Buy WS Hour Pass","parameters":[],"responses":{"200":{"description":"Pass granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WsPassResponseDto"}}}},"402":{"description":"Payment required (sign and retry with PAYMENT-SIGNATURE)"}},"summary":"Buy a 1-hour WebSocket streaming pass","tags":["x402"]}},"/api/v1/x402/ws-pass/day":{"post":{"description":"Purchase a 24-hour WebSocket streaming entitlement via x402 (USDC on Base mainnet). See `/x402/ws-pass/hour` for the auth flow; the only difference is the duration and the price.","operationId":"Buy WS Day Pass","parameters":[],"responses":{"200":{"description":"Pass granted","content":{"application/json":{"schema":{"$ref":"#/components/schemas/WsPassResponseDto"}}}},"402":{"description":"Payment required (sign and retry with PAYMENT-SIGNATURE)"}},"summary":"Buy a 24-hour WebSocket streaming pass","tags":["x402"]}},"/api/v1/options/catalog":{"get":{"description":"Returns a list of available options instruments.","operationId":"Options Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity/expiry date (e.g., 14AUG26, 27JUN25)","schema":{"example":"14AUG26","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of instruments to return (1-1000)","schema":{"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response","schema":{"type":"string"}},{"name":"option_type","required":false,"in":"query","description":"Filter by option type: C (Call) or P (Put)","schema":{"example":"C","type":"string","enum":["C","P"]}},{"name":"strike_min","required":false,"in":"query","description":"Minimum strike price","schema":{"example":50000,"type":"number"}},{"name":"strike_max","required":false,"in":"query","description":"Maximum strike price","schema":{"example":100000,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"example":[{"instrument_name":"AVAX_USDC-22NOV25-12-C","exchange":"deribit"},{"instrument_name":"AVAX_USDC-22NOV25-12-P","exchange":"deribit"},{"instrument_name":"AVAX_USDC-22NOV25-12d4-C","exchange":"deribit"}]}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Catalog","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)"},"currency":{"example":"BTC","type":"string","description":"Filter by base currency (e.g., BTC, ETH, SOL)"},"maturity":{"example":"14AUG26","type":"string","description":"Filter by maturity/expiry date (e.g., 14AUG26, 27JUN25)"},"limit":{"default":100,"example":100,"type":"number","description":"Maximum number of instruments to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor from a previous response"},"option_type":{"example":"C","type":"string","enum":["C","P"],"description":"Filter by option type: C (Call) or P (Put)"},"strike_min":{"example":50000,"type":"number","description":"Minimum strike price"},"strike_max":{"example":100000,"type":"number","description":"Maximum strike price"}}}}}}}},"/api/v1/options/metadata":{"get":{"description":"Returns metadata for a specific options instrument including data availability, total record count, and pagination information.","operationId":"Options Metadata","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name","schema":{"example":"deribit","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records per page for pagination calculation","schema":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number"}},{"name":"instrument_name","required":true,"in":"query","description":"Instrument name","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"description":"Metadata successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponseEntity"}}}},"400":{"description":"Bad Request - Invalid parameters or no data found","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Metadata","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name"},"limit":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number","description":"Number of records per page for pagination calculation"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Instrument name"}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/options/ohlcvt":{"get":{"description":"Returns open, high, low, close, volume, and trade statistics for a specific option instrument aggregated by the requested resolution.","operationId":"Options Market Data","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"description":"OHLCVT data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsOhlcvtEntity"}}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","open":0.2157,"high":0.2157,"low":0.2157,"close":0.2157,"vwap":0.2157,"volume":0,"buy_volume":0,"sell_volume":0,"trades_count":0,"buy_trades_count":0,"sell_trades_count":0,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":0.2157,"index_price":103722.83,"days_to_expiry":324.9166666666667},{"date":"2025-11-04 11:01:00","open":0.2154,"high":0.2154,"low":0.2154,"close":0.2154,"vwap":0.2154,"volume":0,"buy_volume":0,"sell_volume":0,"trades_count":0,"buy_trades_count":0,"sell_trades_count":0,"liquidation_short_volume":120,"liquidation_long_volume":280,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":0.2154,"index_price":103639.67,"days_to_expiry":324.91597222222225},{"date":"2025-11-04 11:02:00","open":0.2156,"high":0.2156,"low":0.2156,"close":0.2156,"vwap":0.2156,"volume":0,"buy_volume":0,"sell_volume":0,"trades_count":0,"buy_trades_count":0,"sell_trades_count":0,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":5000,"block_trade_sell_volume":3500,"mark_price":0.2156,"index_price":103695.66,"days_to_expiry":324.91527777777776}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options OHLC Market Data","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/volume":{"get":{"description":"Returns rolling 24h volume metrics (base and USD) for options instruments filtered by currency with optional aggregation and interval bucketing.","operationId":"Options Volume Stats","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved options volume data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BaseVolumeDataEntity"}}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","volume_24h":1.2,"volume_usd_24h":29521.78},{"date":"2025-11-04 11:01:00","volume_24h":1.2,"volume_usd_24h":29521.78},{"date":"2025-11-04 11:02:00","volume_24h":1.2,"volume_usd_24h":29521.78}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Volume Stats","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/trades/summary":{"get":{"description":"Returns aggregated trade statistics for options grouped by a chosen axis. One compact call replaces scanning individual trades. Returns grouped stats: trade_count, volume, buy/sell_volume, premium_usd, buy/sell_premium_usd, notional, net_oi_change, net_delta/gamma/vega, block_trade_count. Group by: exchange, instrument_name, strike, maturity, option_type, direction, or strategy.","operationId":"Options Trades Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH)","schema":{"example":"BTC","type":"string"}},{"name":"group_by","required":true,"in":"query","description":"Axis to group results by","schema":{"type":"string","enum":["exchange","instrument_name","strike","maturity","option_type","direction","strategy"]}},{"name":"min_premium_usd","required":false,"in":"query","description":"Minimum premium in USD. Filters dust trades.","schema":{"type":"number"}},{"name":"min_notional","required":false,"in":"query","description":"Minimum notional value in USD.","schema":{"type":"number"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only include block trades.","schema":{"default":false,"type":"boolean"}},{"name":"opening_only","required":false,"in":"query","description":"If true, only include opening trades (strategy starts with Opened).","schema":{"default":false,"type":"boolean"}},{"name":"option_type","required":false,"in":"query","description":"Filter by option type: C (call) or P (put)","schema":{"type":"string","enum":["C","P"]}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity date (e.g. 14AUG26)","schema":{"type":"string"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values.","schema":{"type":"string","enum":["BEAR_CALL_SPREAD","BEAR_DIAGONAL_SPREAD (Calls)","BEAR_DIAGONAL_SPREAD (Puts)","BEAR_PUT_SPREAD","BOX_SPREAD","BULL_CALL_SPREAD","BULL_DIAGONAL_SPREAD (Calls)","BULL_DIAGONAL_SPREAD (Puts)","BULL_PUT_SPREAD","CALL_CALENDAR","CALL_ROLL_BACK/UP","CALL_ROLL_FORWARD/DOWN","CALL_ROLL_FORWARD/UP","COLLAR_WITH_FUTURE","COMBO_CALL_BUTTERFLY","COMBO_CALL_CALENDAR","COMBO_CALL_DIAGONAL","COMBO_CALL_RATIO_SPREAD_1X2","COMBO_CALL_RATIO_SPREAD_1X3","COMBO_CALL_SPREAD","COMBO_IRON_CONDOR","COMBO_PUT_CALENDAR","COMBO_PUT_DIAGONAL","COMBO_PUT_RATIO_SPREAD_1X3","COMBO_PUT_SPREAD","COMBO_REVERSAL","COMBO_RISK_REVERSAL","COMBO_STRADDLE","COMBO_STRADDLE_CALENDAR","COMBO_STRANGLE","COVERED_CALL_WITH_FUTURE","CUSTOM_STRATEGY","Close_CALL/Open_PUT","Close_PUT/Open_CALL","Closed BEAR_CALL_SPREAD","Closed BEAR_DIAGONAL_SPREAD (Calls)","Closed BULL_DIAGONAL_SPREAD (Calls)","Closed COMBO_PUT_SPREAD","Closed COMBO_STRADDLE","Closed LONG_CALL","Closed LONG_PUT","Closed LONG_RATIO_CALL_SPREAD","Closed LONG_STRANGLE","Closed SHORT_CALL","Closed SHORT_COVERED_CALL_WITH_FUTURE","Closed SHORT_PROTECTIVE_PUT_WITH_FUTURE","Closed SHORT_PUT","Closed SHORT_RATIO_CALL_SPREAD","Closed SHORT_STRADDLE","HEDGED_OPTIONS_STRATEGY","LONG_CALL","LONG_CALL_BUTTERFLY","LONG_CALL_CONDOR","LONG_IRON_CONDOR","LONG_PUT","LONG_RATIO_CALL_SPREAD","LONG_RATIO_PUT_SPREAD","LONG_RISK_REVERSAL","LONG_STRADDLE","LONG_STRANGLE","Opened BEAR_CALL_SPREAD","Opened BEAR_DIAGONAL_SPREAD (Calls)","Opened BEAR_DIAGONAL_SPREAD (Puts)","Opened BOX_SPREAD","Opened BULL_CALL_SPREAD","Opened BULL_DIAGONAL_SPREAD (Calls)","Opened BULL_DIAGONAL_SPREAD (Puts)","Opened CALL_CALENDAR","Opened COLLAR_WITH_FUTURE","Opened COMBO_CALL_CALENDAR","Opened COMBO_CALL_RATIO_SPREAD_1X2","Opened COMBO_CALL_SPREAD","Opened COMBO_PUT_CALENDAR","Opened COMBO_PUT_RATIO_SPREAD_1X3","Opened COMBO_PUT_SPREAD","Opened COMBO_RISK_REVERSAL","Opened COMBO_STRANGLE","Opened LONG_CALL","Opened LONG_IRON_CONDOR","Opened LONG_PUT","Opened LONG_RATIO_PUT_SPREAD","Opened LONG_RISK_REVERSAL","Opened LONG_STRADDLE","Opened LONG_STRANGLE","Opened PROTECTIVE_PUT_WITH_FUTURE","Opened PUT_CALENDAR","Opened SHORT_CALL","Opened SHORT_COLLAR_WITH_FUTURE","Opened SHORT_COVERED_CALL_WITH_FUTURE","Opened SHORT_PUT","Opened SHORT_RATIO_CALL_SPREAD","Opened SHORT_STRADDLE","Opened SHORT_STRANGLE","PROTECTIVE_PUT_WITH_FUTURE","PUT_CALENDAR","PUT_ROLL_BACK/DOWN","PUT_ROLL_BACK/UP","REVERSE_CALL_CALENDAR","REVERSE_PUT_CALENDAR","ROLL_DOWN","ROLL_FORWARD","ROLL_UP","SHORT_CALL","SHORT_CALL_BUTTERFLY","SHORT_COLLAR_WITH_FUTURE","SHORT_COVERED_CALL_WITH_FUTURE","SHORT_IRON_CONDOR","SHORT_PUT","SHORT_PUT_BUTTERFLY","SHORT_RATIO_CALL_SPREAD","SHORT_RATIO_PUT_SPREAD","SHORT_RISK_REVERSAL","SHORT_STRADDLE","SHORT_STRANGLE"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"group_key":"100000","trade_count":85,"volume":500.2,"buy_volume":300.1,"sell_volume":200.1,"premium_usd":1250000,"buy_premium_usd":750000,"sell_premium_usd":500000,"notional":47500000,"net_oi_change":120.5,"net_delta":45.2,"net_gamma":0.003,"net_vega":12500,"block_trade_count":3}],"metadata":{"group_by":"strike","total_trades":85,"total_volume":500.2}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Trades Summary","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH)"},"group_by":{"type":"string","enum":["exchange","instrument_name","strike","maturity","option_type","direction","strategy"],"description":"Axis to group results by"},"min_premium_usd":{"type":"number","description":"Minimum premium in USD. Filters dust trades."},"min_notional":{"type":"number","description":"Minimum notional value in USD."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction"},"block_only":{"default":false,"type":"boolean","description":"If true, only include block trades."},"opening_only":{"default":false,"type":"boolean","description":"If true, only include opening trades (strategy starts with Opened)."},"option_type":{"type":"string","enum":["C","P"],"description":"Filter by option type: C (call) or P (put)"},"maturity":{"type":"string","description":"Filter by maturity date (e.g. 14AUG26)"},"strategy":{"type":"string","description":"Filter by strategy label. Accepts comma-separated values."}},"required":["exchange","currency","group_by"]}}}}}},"/api/v1/options/trades":{"get":{"description":"Returns options trades with full trade details and Greeks. Supports two modes: (1) instrument mode — provide instrument_name for a single option, (2) currency mode — provide currency (e.g. BTC) for ALL options trades across all instruments. Additional filters: min_premium_usd, min_notional, direction, strategy, block_only, opening_only, option_type, maturity, sort, sort_dir.","operationId":"Options Trade History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to DESC for currency-level queries (newest/largest first), ASC for instrument-level queries.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C). Either instrument_name or currency is required.","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL instruments for this currency. Either currency or instrument_name is required.","schema":{"example":"BTC","type":"string"}},{"name":"min_premium_usd","required":false,"in":"query","description":"Minimum premium in USD. Filters out dust trades.","schema":{"example":1000,"type":"number"}},{"name":"min_notional","required":false,"in":"query","description":"Minimum notional value in USD.","schema":{"example":10000,"type":"number"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values (e.g. SHORT_CALL,LONG_PUT).","schema":{"type":"string","enum":["BEAR_CALL_SPREAD","BEAR_DIAGONAL_SPREAD (Calls)","BEAR_DIAGONAL_SPREAD (Puts)","BEAR_PUT_SPREAD","BOX_SPREAD","BULL_CALL_SPREAD","BULL_DIAGONAL_SPREAD (Calls)","BULL_DIAGONAL_SPREAD (Puts)","BULL_PUT_SPREAD","CALL_CALENDAR","CALL_ROLL_BACK/UP","CALL_ROLL_FORWARD/DOWN","CALL_ROLL_FORWARD/UP","COLLAR_WITH_FUTURE","COMBO_CALL_BUTTERFLY","COMBO_CALL_CALENDAR","COMBO_CALL_DIAGONAL","COMBO_CALL_RATIO_SPREAD_1X2","COMBO_CALL_RATIO_SPREAD_1X3","COMBO_CALL_SPREAD","COMBO_IRON_CONDOR","COMBO_PUT_CALENDAR","COMBO_PUT_DIAGONAL","COMBO_PUT_RATIO_SPREAD_1X3","COMBO_PUT_SPREAD","COMBO_REVERSAL","COMBO_RISK_REVERSAL","COMBO_STRADDLE","COMBO_STRADDLE_CALENDAR","COMBO_STRANGLE","COVERED_CALL_WITH_FUTURE","CUSTOM_STRATEGY","Close_CALL/Open_PUT","Close_PUT/Open_CALL","Closed BEAR_CALL_SPREAD","Closed BEAR_DIAGONAL_SPREAD (Calls)","Closed BULL_DIAGONAL_SPREAD (Calls)","Closed COMBO_PUT_SPREAD","Closed COMBO_STRADDLE","Closed LONG_CALL","Closed LONG_PUT","Closed LONG_RATIO_CALL_SPREAD","Closed LONG_STRANGLE","Closed SHORT_CALL","Closed SHORT_COVERED_CALL_WITH_FUTURE","Closed SHORT_PROTECTIVE_PUT_WITH_FUTURE","Closed SHORT_PUT","Closed SHORT_RATIO_CALL_SPREAD","Closed SHORT_STRADDLE","HEDGED_OPTIONS_STRATEGY","LONG_CALL","LONG_CALL_BUTTERFLY","LONG_CALL_CONDOR","LONG_IRON_CONDOR","LONG_PUT","LONG_RATIO_CALL_SPREAD","LONG_RATIO_PUT_SPREAD","LONG_RISK_REVERSAL","LONG_STRADDLE","LONG_STRANGLE","Opened BEAR_CALL_SPREAD","Opened BEAR_DIAGONAL_SPREAD (Calls)","Opened BEAR_DIAGONAL_SPREAD (Puts)","Opened BOX_SPREAD","Opened BULL_CALL_SPREAD","Opened BULL_DIAGONAL_SPREAD (Calls)","Opened BULL_DIAGONAL_SPREAD (Puts)","Opened CALL_CALENDAR","Opened COLLAR_WITH_FUTURE","Opened COMBO_CALL_CALENDAR","Opened COMBO_CALL_RATIO_SPREAD_1X2","Opened COMBO_CALL_SPREAD","Opened COMBO_PUT_CALENDAR","Opened COMBO_PUT_RATIO_SPREAD_1X3","Opened COMBO_PUT_SPREAD","Opened COMBO_RISK_REVERSAL","Opened COMBO_STRANGLE","Opened LONG_CALL","Opened LONG_IRON_CONDOR","Opened LONG_PUT","Opened LONG_RATIO_PUT_SPREAD","Opened LONG_RISK_REVERSAL","Opened LONG_STRADDLE","Opened LONG_STRANGLE","Opened PROTECTIVE_PUT_WITH_FUTURE","Opened PUT_CALENDAR","Opened SHORT_CALL","Opened SHORT_COLLAR_WITH_FUTURE","Opened SHORT_COVERED_CALL_WITH_FUTURE","Opened SHORT_PUT","Opened SHORT_RATIO_CALL_SPREAD","Opened SHORT_STRADDLE","Opened SHORT_STRANGLE","PROTECTIVE_PUT_WITH_FUTURE","PUT_CALENDAR","PUT_ROLL_BACK/DOWN","PUT_ROLL_BACK/UP","REVERSE_CALL_CALENDAR","REVERSE_PUT_CALENDAR","ROLL_DOWN","ROLL_FORWARD","ROLL_UP","SHORT_CALL","SHORT_CALL_BUTTERFLY","SHORT_COLLAR_WITH_FUTURE","SHORT_COVERED_CALL_WITH_FUTURE","SHORT_IRON_CONDOR","SHORT_PUT","SHORT_PUT_BUTTERFLY","SHORT_RATIO_CALL_SPREAD","SHORT_RATIO_PUT_SPREAD","SHORT_RISK_REVERSAL","SHORT_STRADDLE","SHORT_STRANGLE"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only return trades with a block_trade_id (block trades).","schema":{"default":false,"type":"boolean"}},{"name":"opening_only","required":false,"in":"query","description":"If true, only return trades where strategy starts with \"Opened\" (new positions).","schema":{"default":false,"type":"boolean"}},{"name":"option_type","required":false,"in":"query","description":"Filter by option type: C (call) or P (put)","schema":{"type":"string","enum":["C","P"]}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity date (e.g. 14AUG26)","schema":{"example":"14AUG26","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","premium_usd","notional","amount"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsTradeEntity"}}}}]},"example":{"data":[{"instrument_name":"BTC-25SEP26-100000-C","timestamp":1759220633312,"trade_id":"387076415","date":"2025-10-11 12:45:49","block_trade_id":"","combo_id":"","combo_trade_id":"","strategy":"Opened SHORT_CALL","direction":"sell","tick_direction":1,"amount":0.1,"price":0.267,"index_price":113610.41,"oi_change":0.1,"open_interest":0.1,"oi_before":null,"maturity":"25SEP26","days_to_expiry":359.9834,"iv":44.95,"mark_price":0.2669,"ask_price":0.269,"bid_price":0.267,"ask_size":2.8,"bid_size":9.7,"bid_iv_change":0,"ask_iv_change":0,"bid_price_change":-0.002,"ask_price_change":0,"bid_size_change":0,"ask_size_change":0,"premium":0.0267,"premium_usd":3033.4,"notional":11361.04,"delta":-0.0694643,"gamma":-6.9e-7,"vega":-39.54125,"theta":2.468719,"strike":100000,"option_type":"C"},{"instrument_name":"BTC-25SEP26-100000-C","timestamp":1760189549998,"date":"2025-10-11 12:45:49","trade_id":"390187993","block_trade_id":"","combo_id":"","combo_trade_id":"","strategy":"Opened SHORT_CALL","direction":"sell","tick_direction":2,"amount":0.1,"price":0.261,"index_price":112021.37,"oi_change":0.1,"open_interest":0.2,"oi_before":0.1,"maturity":"25SEP26","days_to_expiry":348.7691,"iv":46.9,"mark_price":0.2604,"ask_price":0.2675,"bid_price":0.261,"ask_size":27.1,"bid_size":18.1,"bid_iv_change":0,"ask_iv_change":0,"bid_price_change":-0.0035,"ask_price_change":0,"bid_size_change":0,"ask_size_change":0,"premium":0.0261,"premium_usd":2923.76,"notional":11202.14,"delta":-0.0683262,"gamma":-7e-7,"vega":-38.99059,"theta":2.621582,"strike":100000,"option_type":"C"},{"instrument_name":"BTC-25SEP26-100000-C","timestamp":1760461299893,"trade_id":"391006860","date":"2025-10-11 12:45:49","block_trade_id":"","combo_id":"","combo_trade_id":"","strategy":"Opened SHORT_CALL","direction":"sell","tick_direction":2,"amount":0.1,"price":0.2595,"index_price":111949.78,"oi_change":0.1,"open_interest":0.3,"oi_before":0.2,"maturity":"25SEP26","days_to_expiry":345.6238,"iv":47.14,"mark_price":0.2587,"ask_price":0.261,"bid_price":0.2595,"ask_size":2.2,"bid_size":2.2,"bid_iv_change":0,"ask_iv_change":0,"bid_price_change":-0.0035,"ask_price_change":0,"bid_size_change":0,"ask_size_change":0,"premium":0.026,"premium_usd":2905.1,"notional":11194.98,"delta":-0.0682762,"gamma":-7e-7,"vega":-38.81525,"theta":2.647056,"strike":100000,"option_type":"C"}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NjM0Mzk0NTc1NTksInRyYWRlX2lkIjoiMzk4OTU3NDk3In0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Trade History","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to DESC for currency-level queries (newest/largest first), ASC for instrument-level queries."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C). Either instrument_name or currency is required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL instruments for this currency. Either currency or instrument_name is required."},"min_premium_usd":{"example":1000,"type":"number","description":"Minimum premium in USD. Filters out dust trades."},"min_notional":{"example":10000,"type":"number","description":"Minimum notional value in USD."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"strategy":{"example":"","type":"string","description":"Filter by strategy label. Accepts comma-separated values (e.g. SHORT_CALL,LONG_PUT)."},"block_only":{"default":false,"type":"boolean","description":"If true, only return trades with a block_trade_id (block trades)."},"opening_only":{"default":false,"type":"boolean","description":"If true, only return trades where strategy starts with \"Opened\" (new positions)."},"option_type":{"type":"string","enum":["C","P"],"description":"Filter by option type: C (call) or P (put)"},"maturity":{"example":"14AUG26","type":"string","description":"Filter by maturity date (e.g. 14AUG26)"},"sort":{"default":"timestamp","type":"string","enum":["timestamp","premium_usd","notional","amount"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/options/flow":{"get":{"description":"Returns an aggregated flow summary for a currency including total trades, premium breakdowns (call/put, buy/sell), net Greeks (delta, gamma, vega), opening/closing counts, block trade stats, most active strikes, and notable trades. One call returns everything pre-computed.","operationId":"Options Flow Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH). Required.","schema":{"example":"BTC","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time bucket resolution for aggregation.","schema":{"default":"1h","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"min_premium_usd","required":false,"in":"query","description":"Minimum premium_usd per trade to include in aggregation. Filters dust before aggregating.","schema":{"example":1000,"type":"number"}},{"name":"top_n","required":false,"in":"query","description":"Number of notable trades to return (most_active_strikes always returns top 10). Default 10.","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Flow summary successfully retrieved","content":{"application/json":{"schema":{"properties":{"summary":{"$ref":"#/components/schemas/OptionsFlowSummaryEntity"},"buckets":{"type":"array","items":{"$ref":"#/components/schemas/OptionsFlowBucketEntity"}},"notable_trades":{"type":"array","items":{"$ref":"#/components/schemas/OptionsTradeEntity"}}}},"example":{"summary":{"start":"2026-03-11T10:00:00.000Z","end":"2026-03-18T10:00:00.000Z","resolution":"1h","total_trades":17473,"total_premium_usd":313090175.66,"total_notional_usd":10663319458.94,"call_premium_usd":178403755.18,"put_premium_usd":134686420.48,"buy_premium_usd":166205839.48,"sell_premium_usd":146884336.18,"net_delta":2409.04,"net_gamma":0.24,"net_vega":413362.73,"opening_trades":3144,"closing_trades":887,"net_oi_change":46885.23,"block_trade_count":1223,"block_trade_premium_usd":190954915.46,"most_active_strikes":[{"instrument_name":"BTC-25SEP26-70000-C","trade_count":78,"premium_usd":14778377.67,"net_oi_change":913.8},{"instrument_name":"BTC-25SEP26-70000-P","trade_count":27,"premium_usd":8580802.91,"net_oi_change":862.4},{"instrument_name":"BTC-26JUN26-95000-P","trade_count":3,"premium_usd":8027375.24,"net_oi_change":0}]},"buckets":[{"date":"2026-03-11T10:00:00.000Z","trade_count":142,"buy_count":78,"sell_count":64,"total_amount":1250.5,"buy_amount":680.2,"sell_amount":570.3,"total_premium_usd":2450312.45,"buy_premium_usd":1320150.22,"sell_premium_usd":1130162.23,"total_notional":85230100.5,"buy_notional":46120050.3,"sell_notional":39110050.2,"call_premium_usd":1420180.3,"put_premium_usd":1030132.15,"call_count":82,"put_count":60,"block_trade_count":8,"block_premium_usd":1520200.4,"net_oi_change":320.5,"avg_iv":52.34,"avg_abs_delta":0.45},{"date":"2026-03-11T11:00:00.000Z","trade_count":98,"buy_count":52,"sell_count":46,"total_amount":890.3,"buy_amount":470.1,"sell_amount":420.2,"total_premium_usd":1780245.12,"buy_premium_usd":950130.45,"sell_premium_usd":830114.67,"total_notional":62150080.3,"buy_notional":33080040.1,"sell_notional":29070040.2,"call_premium_usd":1020140.2,"put_premium_usd":760104.92,"call_count":55,"put_count":43,"block_trade_count":5,"block_premium_usd":980130.2,"net_oi_change":180.2,"avg_iv":51.87,"avg_abs_delta":0.43}],"notable_trades":[{"instrument_name":"BTC-26JUN26-95000-P","timestamp":1773269099057,"trade_id":"412345678","block_trade_id":"BLK-12345","combo_id":"","strategy":"Opened LONG_PUT","date":"2026-03-11 14:30:00","currency":"BTC","maturity":"26JUN26","days_to_expiry":107.4,"strike":95000,"option_type":"P","direction":"buy","amount":50,"price":0.0312,"iv":58.2,"index_price":84500.12,"mark_price":0.031,"premium_usd":8027375.24,"notional":4225006,"delta":-0.3512,"gamma":0.000008,"vega":142.35,"theta":-18.42,"oi_change":50,"open_interest":250}]}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Flow Summary","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Required."},"resolution":{"default":"1h","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time bucket resolution for aggregation."},"min_premium_usd":{"example":1000,"type":"number","description":"Minimum premium_usd per trade to include in aggregation. Filters dust before aggregating."},"top_n":{"default":10,"example":10,"type":"number","description":"Number of notable trades to return (most_active_strikes always returns top 10). Default 10."}},"required":["exchange","currency"]}}}}}},"/api/v1/options/open-interest":{"get":{"description":"Aggregates open interest across the selected instrument or currency using the requested resolution.","operationId":"Options Open Interest","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/BaseOpenInterestEntity"}}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","oi_open":2.6,"oi_high":2.6,"oi_low":2.6,"oi_close":2.6},{"date":"2025-11-04 11:01:00","oi_open":2.6,"oi_high":2.6,"oi_low":2.6,"oi_close":2.6},{"date":"2025-11-04 11:02:00","oi_open":2.6,"oi_high":2.6,"oi_low":2.6,"oi_close":2.6}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Open Interest","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/level1":{"get":{"description":"Returns level 1 order book data for options instruments.","operationId":"Options Level 1","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","bid_price_open":0.212,"bid_price_high":0.212,"bid_price_low":0.2115,"bid_price_close":0.2115,"ask_price_open":0.2195,"ask_price_high":0.22,"ask_price_low":0.2195,"ask_price_close":0.22,"bid_size_open":19.3,"bid_size_high":19.3,"bid_size_low":19.3,"bid_size_close":19.3,"ask_size_open":19.4,"ask_size_high":31.3,"ask_size_low":12,"ask_size_close":31.3,"bid_ask_spread_open":0.007500000000000007,"bid_ask_spread_high":0.008500000000000008,"bid_ask_spread_low":0.007500000000000007,"bid_ask_spread_close":0.008500000000000008,"total_liquidity_open":38.7,"total_liquidity_high":50.6,"total_liquidity_low":31.3,"total_liquidity_close":50.6,"total_liquidity_avg":43.16666666666667},{"date":"2025-11-04 11:01:00","bid_price_open":0.2115,"bid_price_high":0.2115,"bid_price_low":0.2115,"bid_price_close":0.2115,"ask_price_open":0.22,"ask_price_high":0.22,"ask_price_low":0.22,"ask_price_close":0.22,"bid_size_open":19.3,"bid_size_high":19.3,"bid_size_low":19.3,"bid_size_close":19.3,"ask_size_open":31.3,"ask_size_high":31.3,"ask_size_low":31.3,"ask_size_close":31.3,"bid_ask_spread_open":0.008500000000000008,"bid_ask_spread_high":0.008500000000000008,"bid_ask_spread_low":0.008500000000000008,"bid_ask_spread_close":0.008500000000000008,"total_liquidity_open":50.6,"total_liquidity_high":50.6,"total_liquidity_low":50.6,"total_liquidity_close":50.6,"total_liquidity_avg":50.600000000000016},{"date":"2025-11-04 11:02:00","bid_price_open":0.211,"bid_price_high":0.214,"bid_price_low":0.211,"bid_price_close":0.214,"ask_price_open":0.22,"ask_price_high":0.22,"ask_price_low":0.219,"ask_price_close":0.219,"bid_size_open":19.3,"bid_size_high":19.3,"bid_size_low":0.3,"bid_size_close":0.3,"ask_size_open":31.3,"ask_size_high":31.3,"ask_size_low":19.3,"ask_size_close":19.6,"bid_ask_spread_open":0.009000000000000008,"bid_ask_spread_high":0.009000000000000008,"bid_ask_spread_low":0.0050000000000000044,"bid_ask_spread_close":0.0050000000000000044,"total_liquidity_open":50.6,"total_liquidity_high":50.6,"total_liquidity_low":19.6,"total_liquidity_close":19.900000000000002,"total_liquidity_avg":26.576190476190483}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Level 1","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/volatility":{"get":{"description":"Returns implied volatility and Greeks data for options instruments.","operationId":"Options Volatility & Greeks","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","strike":100000,"maturity":"25SEP26","days_to_expiry":324.9166666666667,"underlying_price":109227.13,"mark_iv_open":47.62,"mark_iv_high":47.62,"mark_iv_low":47.62,"mark_iv_close":47.62,"bid_iv_open":46.42,"bid_iv_high":46.53,"bid_iv_low":46.36,"bid_iv_close":46.4,"ask_iv_open":48.6,"ask_iv_high":48.89,"ask_iv_low":48.57,"ask_iv_close":48.87,"iv_spread_open":2.1799999999999997,"iv_spread_high":2.47,"iv_spread_low":2.17,"iv_spread_close":2.469999999999999,"iv_spread_avg":2.3077777777777784,"delta":0.66315,"gamma":0.00001,"theta":-27.57357,"vega":376.24963,"rho":435.06539},{"date":"2025-11-04 11:01:00","strike":100000,"maturity":"25SEP26","days_to_expiry":324.91597222222225,"underlying_price":109138.04,"mark_iv_open":47.62,"mark_iv_high":47.62,"mark_iv_low":47.62,"mark_iv_close":47.62,"bid_iv_open":46.45,"bid_iv_high":46.51,"bid_iv_low":46.39,"bid_iv_close":46.51,"ask_iv_open":48.92,"ask_iv_high":48.98,"ask_iv_low":48.86,"ask_iv_close":48.98,"iv_spread_open":2.469999999999999,"iv_spread_high":2.47,"iv_spread_low":2.46,"iv_spread_close":2.469999999999999,"iv_spread_avg":2.4662499999999987,"delta":0.66249,"gamma":0.00001,"theta":-27.57106,"vega":376.22951,"rho":434.42588},{"date":"2025-11-04 11:02:00","strike":100000,"maturity":"25SEP26","days_to_expiry":324.91527777777776,"underlying_price":109194.74,"mark_iv_open":47.62,"mark_iv_high":47.62,"mark_iv_low":47.62,"mark_iv_close":47.62,"bid_iv_open":46.51,"bid_iv_high":47.17,"bid_iv_low":46.24,"bid_iv_close":47.17,"ask_iv_open":48.97,"ask_iv_high":48.97,"ask_iv_low":48.54,"ask_iv_close":48.62,"iv_spread_open":2.460000000000001,"iv_spread_high":2.47,"iv_spread_low":1.45,"iv_spread_close":1.4499999999999957,"iv_spread_avg":1.8576190476190468,"delta":0.66291,"gamma":0.00001,"theta":-27.57346,"vega":376.24168,"rho":434.82764}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjQwOjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Volatility & Greeks","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/ticker-history":{"get":{"description":"Returns historical ticker data for options instruments.","operationId":"Options Ticker History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price":0.2157,"index_price":103722.83,"bid_price":0.2115,"ask_price":0.22,"bid_ask_spread":0.008500000000000008,"bid_size":19.3,"ask_size":31.3,"oi":2.6,"volume_usd_24h":29521.78,"bid_iv":46.4,"ask_iv":48.87,"mark_iv":47.62,"iv_spread":2.469999999999999},{"date":"2025-11-04 11:01:00","mark_price":0.2154,"index_price":103639.67,"bid_price":0.2115,"ask_price":0.22,"bid_ask_spread":0.008500000000000008,"bid_size":19.3,"ask_size":31.3,"oi":2.6,"volume_usd_24h":29521.78,"bid_iv":46.51,"ask_iv":48.98,"mark_iv":47.62,"iv_spread":2.469999999999999},{"date":"2025-11-04 11:02:00","mark_price":0.2156,"index_price":103695.66,"bid_price":0.214,"ask_price":0.219,"bid_ask_spread":0.0050000000000000044,"bid_size":0.3,"ask_size":19.6,"oi":2.6,"volume_usd_24h":29521.78,"bid_iv":47.17,"ask_iv":48.62,"mark_iv":47.62,"iv_spread":1.4499999999999957}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Ticker History","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/reference-price":{"get":{"description":"Returns reference price data for options instruments.","operationId":"Options Reference Prices","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)","schema":{"example":"BTC-25SEP26-84000-C","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price_open":0.2162,"mark_price_high":0.2162,"mark_price_low":0.2156,"mark_price_close":0.2157,"underlying_price":109227.13,"days_to_expiry":324.9166666666667,"index_price":103722.83},{"date":"2025-11-04 11:01:00","mark_price_open":0.2156,"mark_price_high":0.2157,"mark_price_low":0.2154,"mark_price_close":0.2154,"underlying_price":109138.04,"days_to_expiry":324.91597222222225,"index_price":103639.67},{"date":"2025-11-04 11:02:00","mark_price_open":0.2153,"mark_price_high":0.2158,"mark_price_low":0.2153,"mark_price_close":0.2156,"underlying_price":109194.74,"days_to_expiry":324.91527777777776,"index_price":103695.66}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Reference Prices","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive)"},"instrument_name":{"example":"BTC-25SEP26-84000-C","type":"string","description":"Full options instrument identifier (e.g., BTC-25SEP26-84000-C, ETH-14AUG26-4000-P)"}}}}}}}},"/api/v1/options/snapshot":{"get":{"description":"Returns a snapshot of all options instruments for a given exchange and currency at a single minute. If no date is provided, returns the latest available snapshot. Currency is required due to the large dataset size.","operationId":"Options Snapshot","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"date","required":false,"in":"query","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g., BTC, ETH). Required for options due to large dataset size.","schema":{"example":"BTC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"BTC-25SEP26-84000-C","currency":"BTC","mark_price":0.2157,"index_price":103722.83,"bid_price":0.2115,"ask_price":0.22,"bid_ask_spread":0.0085,"bid_size":19.3,"ask_size":31.3,"oi":2.6,"volume_usd_24h":29521.78,"bid_iv":46.4,"ask_iv":48.87,"mark_iv":47.62,"iv_spread":2.47},{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"BTC-25SEP26-84000-C","currency":"BTC","mark_price":0.0542,"index_price":103722.83,"bid_price":0.053,"ask_price":0.0555,"bid_ask_spread":0.0025,"bid_size":10.1,"ask_size":15.4,"oi":5.2,"volume_usd_24h":12340.5,"bid_iv":52.1,"ask_iv":54.3,"mark_iv":53.15,"iv_spread":2.2}],"meta":{"minute":"2025-11-04 11:00:00"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Snapshot","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH). Required for options due to large dataset size."}},"required":["exchange","currency"]}}}}}},"/api/v1/options/gex/catalog":{"get":{"description":"Lists currencies and venues available in the durable dealer GEX ClickHouse tables, including history depth and latest aggregate state.","operationId":"Options GEX Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of currency/venue rows to return.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"description":"Dealer GEX catalog successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexCatalogEntity"}},"meta":{"$ref":"#/components/schemas/PaginationMetaEntity"}}}]},"example":{"data":[{"currency":"BTC","exchange":"deribit","market":0,"first_date":"2025-10-04T00:00:00.000Z","latest_date":"2026-06-15T10:06:00.000Z","row_count":318224,"spot":65651.87,"total_gex":-4542768.08,"net_long_gex":19984373.25,"net_short_gex":-24527141.33,"regime":"neutral"}],"meta":{"next_cursor":null}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Dealer GEX Catalog","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of currency/venue rows to return."}}}}}}}},"/api/v1/options/gex/latest":{"get":{"description":"Returns the latest aggregate dealer gamma exposure snapshot from ClickHouse gex_index. Snapshots are emitted every 60 seconds; freshness is reported in meta.snapshot_time, meta.snapshot_interval_ms, meta.staleness_ms, and meta.warnings.","operationId":"Options GEX Latest","parameters":[{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Return the latest snapshot at or before this UTC datetime. Defaults to the latest available snapshot.","schema":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of currency/venue rows to return.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"description":"Latest dealer GEX successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexIndexEntity"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true},"snapshot_time":{"type":"string","nullable":true,"example":"2026-06-15 10:06:00"},"snapshot_time_iso":{"type":"string","nullable":true,"example":"2026-06-15T10:06:00.000Z"},"snapshot_interval_ms":{"type":"number","example":60000},"freshness_basis":{"type":"string","enum":["snapshot"]},"staleness_ms":{"type":"number","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}]},"example":{"data":[{"date":"2026-06-15T10:06:00.000Z","currency":"BTC","exchange":"deribit","market":0,"spot":65651.87,"total_gex":-4542768.08,"net_long_gex":19984373.25,"net_short_gex":-24527141.33,"regime":"neutral"}],"meta":{"next_cursor":null,"snapshot_time":"2026-06-15 10:06:00","snapshot_time_iso":"2026-06-15T10:06:00.000Z","snapshot_interval_ms":60000,"freshness_basis":"snapshot","staleness_ms":42000}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Latest Options Dealer GEX","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"date":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string","description":"Return the latest snapshot at or before this UTC datetime. Defaults to the latest available snapshot."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of currency/venue rows to return."}}}}}}}},"/api/v1/options/gex/history":{"get":{"description":"Returns aggregate dealer GEX history from ClickHouse gex_index for one currency/venue. Supports 1m, 5m, 15m, 1h, 4h, and 1d bucketing with cursor pagination via meta.next_cursor.","operationId":"Options GEX History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}}],"responses":{"200":{"description":"Dealer GEX history successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexIndexEntity"}},"meta":{"$ref":"#/components/schemas/PaginationMetaEntity"}}}]},"example":{"data":[{"date":"2026-06-15T10:00:00.000Z","currency":"BTC","exchange":"deribit","market":0,"spot":65590.12,"total_gex":-4120000,"net_long_gex":20100000,"net_short_gex":-24220000,"regime":"neutral"}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTA2LTE1IDEwOjAwOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Historical Options Dealer GEX","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."}}}}}}}},"/api/v1/options/gex/regime-changes":{"get":{"description":"Returns aggregate dealer-regime transitions from gex_index for one currency/venue. Use this to detect flips between positive, negative, and neutral dealer-gamma regimes.","operationId":"Options GEX Regime Changes","parameters":[{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 7 days ago.","schema":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC). Defaults to now.","schema":{"format":"date-time","example":"2026-06-15T00:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of regime changes to return.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from meta.next_cursor.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by transition time.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"Dealer GEX regime changes successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexRegimeChangeEntity"}},"meta":{"$ref":"#/components/schemas/PaginationMetaEntity"}}}]},"example":{"data":[{"date":"2026-06-15T09:18:00.000Z","currency":"BTC","exchange":"deribit","market":0,"spot":65380.22,"total_gex":125000,"net_long_gex":21400000,"net_short_gex":-21275000,"previous_regime":"negative","regime":"neutral"}],"meta":{"next_cursor":null}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Dealer GEX Regime Changes","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"start":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 7 days ago."},"end":{"format":"date-time","example":"2026-06-15T00:00:00Z","type":"string","description":"End date in ISO 8601 format (UTC). Defaults to now."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of regime changes to return."},"cursor":{"type":"string","description":"Pagination cursor from meta.next_cursor."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by transition time."}}}}}}}},"/api/v1/options/gex/strikes":{"get":{"description":"Returns strike-level dealer GEX contributions from ClickHouse. Legacy contribution fields are raw/unweighted; weighted_contribution fields use the dealer-model weighting and reconcile with aggregate total_gex when summed across per-expiry rows. Latest mode returns the most recent persisted detail snapshot; history mode is enabled by start, end, or cursor. When expiry is omitted, aggregate all_expiries rows are returned by default; set include_expiries=true for per-expiry rows.","operationId":"Options GEX Strike Contributions","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string"}},{"name":"expiry","required":false,"in":"query","description":"Expiry code to filter, e.g. '27JUN26'. Use 'all_expiries' for the aggregate strike view.","schema":{"example":"all_expiries","type":"string"}},{"name":"include_expiries","required":false,"in":"query","description":"Include per-expiry rows when expiry is omitted. Defaults to false, which returns aggregate all_expiries rows only.","schema":{"default":false,"type":"boolean"}},{"name":"strike_min","required":false,"in":"query","description":"Minimum numeric strike to return.","schema":{"example":50000,"type":"number"}},{"name":"strike_max","required":false,"in":"query","description":"Maximum numeric strike to return.","schema":{"example":90000,"type":"number"}},{"name":"contribution_basis","required":false,"in":"query","description":"Contribution basis used by min_abs_contribution. weighted reconciles with aggregate total_gex; raw preserves unweighted decomposition.","schema":{"default":"weighted","example":"weighted","type":"string","enum":["weighted","raw"]}},{"name":"min_abs_contribution","required":false,"in":"query","description":"Minimum absolute GEX contribution on contribution_basis. Defaults to weighted contribution, which reconciles with aggregate total_gex.","schema":{"example":10000,"type":"number"}}],"responses":{"200":{"description":"Dealer GEX strike contributions successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexStrikeContributionEntity"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true},"snapshot_time":{"type":"string","nullable":true,"example":"2026-06-15 10:06:00"},"snapshot_time_iso":{"type":"string","nullable":true,"example":"2026-06-15T10:06:00.000Z"},"snapshot_interval_ms":{"type":"number","example":60000},"freshness_basis":{"type":"string","enum":["snapshot"]},"staleness_ms":{"type":"number","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}]},"example":{"data":[{"date":"2026-06-15T10:06:00.000Z","currency":"BTC","exchange":"deribit","market":0,"spot":65651.87,"total_gex":-4542768.08,"expiry":"all_expiries","is_aggregate":true,"strike_label":"65000","strike":65000,"contribution":-1500000,"pos_contribution":200000,"neg_contribution":-1700000,"raw_contribution":-1500000,"raw_pos_contribution":200000,"raw_neg_contribution":-1700000,"weighted_contribution":-1297350,"weighted_pos_contribution":172980,"weighted_neg_contribution":-1470330,"moneyness_weight":0.93,"expiry_weight":0}],"meta":{"next_cursor":null,"snapshot_time":"2026-06-15 10:06:00","snapshot_time_iso":"2026-06-15T10:06:00.000Z","snapshot_interval_ms":60000,"freshness_basis":"snapshot","staleness_ms":42000}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Dealer GEX Strike Contributions","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"date":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot."},"expiry":{"example":"all_expiries","type":"string","description":"Expiry code to filter, e.g. '27JUN26'. Use 'all_expiries' for the aggregate strike view."},"include_expiries":{"default":false,"type":"boolean","description":"Include per-expiry rows when expiry is omitted. Defaults to false, which returns aggregate all_expiries rows only."},"strike_min":{"example":50000,"type":"number","description":"Minimum numeric strike to return."},"strike_max":{"example":90000,"type":"number","description":"Maximum numeric strike to return."},"contribution_basis":{"default":"weighted","example":"weighted","type":"string","enum":["weighted","raw"],"description":"Contribution basis used by min_abs_contribution. weighted reconciles with aggregate total_gex; raw preserves unweighted decomposition."},"min_abs_contribution":{"example":10000,"type":"number","description":"Minimum absolute GEX contribution on contribution_basis. Defaults to weighted contribution, which reconciles with aggregate total_gex."}}}}}}}},"/api/v1/options/gex/term-structure":{"get":{"description":"Returns per-expiry dealer GEX term structure from ClickHouse. Legacy total_gex/net_long_gex/net_short_gex fields are raw/unweighted; weighted_total_gex fields reconcile with snapshot_total_gex. Latest mode returns one snapshot; history mode is enabled by start, end, or cursor.","operationId":"Options GEX Term Structure","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string"}},{"name":"expiry","required":false,"in":"query","description":"Expiry code to filter, e.g. '27JUN26'. Omit to return all expiries.","schema":{"example":"27JUN26","type":"string"}}],"responses":{"200":{"description":"Dealer GEX term structure successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexTermStructureEntity"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true},"snapshot_time":{"type":"string","nullable":true,"example":"2026-06-15 10:06:00"},"snapshot_time_iso":{"type":"string","nullable":true,"example":"2026-06-15T10:06:00.000Z"},"snapshot_interval_ms":{"type":"number","example":60000},"freshness_basis":{"type":"string","enum":["snapshot"]},"staleness_ms":{"type":"number","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}]},"example":{"data":[{"date":"2026-06-15T10:06:00.000Z","currency":"BTC","exchange":"deribit","market":0,"expiry":"27JUN26","total_gex":-2100000,"net_long_gex":5500000,"net_short_gex":-7600000,"raw_total_gex":-2100000,"raw_net_long_gex":5500000,"raw_net_short_gex":-7600000,"weighted_total_gex":-1816290,"weighted_net_long_gex":4755300,"weighted_net_short_gex":-6571590,"strike_count":43,"spot":65651.87,"snapshot_total_gex":-4542768.08}],"meta":{"next_cursor":null,"snapshot_time":"2026-06-15 10:06:00","snapshot_time_iso":"2026-06-15T10:06:00.000Z","snapshot_interval_ms":60000,"freshness_basis":"snapshot","staleness_ms":42000}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Dealer GEX Term Structure","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"date":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot."},"expiry":{"example":"27JUN26","type":"string","description":"Expiry code to filter, e.g. '27JUN26'. Omit to return all expiries."}}}}}}}},"/api/v1/options/gex/profile":{"get":{"description":"Returns interpolated dealer GEX profile points from ClickHouse. Legacy gex is the raw interpolated profile; weighted_gex is interpolated from dealer-model weighted contributions. Defaults to profile_group=all_expiries and supports per-expiry profile groups, strike filters, latest mode, and paginated history mode.","operationId":"Options GEX Profile","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Options venue. Dealer GEX is currently backed by Deribit options.","schema":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"]}},{"name":"currency","required":false,"in":"query","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string"}},{"name":"profile_group","required":false,"in":"query","description":"Profile group to return. Defaults to 'all_expiries'; pass an expiry code for a per-expiry profile.","schema":{"default":"all_expiries","example":"all_expiries","type":"string"}},{"name":"strike_min","required":false,"in":"query","description":"Minimum numeric strike to return.","schema":{"example":50000,"type":"number"}},{"name":"strike_max","required":false,"in":"query","description":"Maximum numeric strike to return.","schema":{"example":90000,"type":"number"}}],"responses":{"200":{"description":"Dealer GEX profile successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/OptionsGexProfileEntity"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true},"snapshot_time":{"type":"string","nullable":true,"example":"2026-06-15 10:06:00"},"snapshot_time_iso":{"type":"string","nullable":true,"example":"2026-06-15T10:06:00.000Z"},"snapshot_interval_ms":{"type":"number","example":60000},"freshness_basis":{"type":"string","enum":["snapshot"]},"staleness_ms":{"type":"number","nullable":true},"warnings":{"type":"array","items":{"type":"object","properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT"]},"message":{"type":"string"}},"required":["code","message"]}}}}}}]},"example":{"data":[{"date":"2026-06-15T10:06:00.000Z","currency":"BTC","exchange":"deribit","market":0,"spot":65651.87,"total_gex":-4542768.08,"profile_group":"all_expiries","strike_label":"65000","strike":65000,"gex":-1200000,"raw_gex":-1200000,"weighted_gex":-1037880,"min_strike":40000,"max_strike":90000,"interpolator":"pchip"}],"meta":{"next_cursor":null,"snapshot_time":"2026-06-15 10:06:00","snapshot_time_iso":"2026-06-15T10:06:00.000Z","snapshot_interval_ms":60000,"freshness_basis":"snapshot","staleness_ms":42000}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Options Dealer GEX Profile","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"default":"deribit","example":"deribit","type":"string","enum":["deribit"],"description":"Options venue. Dealer GEX is currently backed by Deribit options."},"currency":{"example":"BTC","type":"string","description":"Dealer-worker currency. Examples: BTC, ETH, SOL, XRP, BTC_USDC, ETH_USDC."},"date":{"format":"date-time","example":"2026-06-15T10:00:00Z","type":"string","description":"Return the latest detail snapshot at or before this UTC datetime. When omitted and no start/end/cursor is supplied, returns the latest available snapshot."},"profile_group":{"default":"all_expiries","example":"all_expiries","type":"string","description":"Profile group to return. Defaults to 'all_expiries'; pass an expiry code for a per-expiry profile."},"strike_min":{"example":50000,"type":"number","description":"Minimum numeric strike to return."},"strike_max":{"example":90000,"type":"number","description":"Maximum numeric strike to return."}}}}}}}},"/api/v1/perpetuals/catalog":{"get":{"description":"Returns a list of available perpetual instruments.","operationId":"Perpetuals Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity/expiry date (e.g., 28MAR25, 27JUN25)","schema":{"example":"28MAR25","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of instruments to return (1-1000)","schema":{"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response","schema":{"type":"string"}},{"name":"asset_class","required":false,"in":"query","description":"Filter by asset class. Defaults to all classes. Use \"equity\"/\"commodity\"/\"forex\"/\"index\" to scope to non-crypto perps (NVDA/TSLA equity perps, GOLD/OIL commodity perps, EURUSD FX perps, etc.). Discover available instruments via /api/v1/macro/catalog.","schema":{"example":"equity","type":"string","enum":["crypto","equity","commodity","forex","index"]}},{"name":"sub_exchange","required":false,"in":"query","description":"Filter by sub-venue. Used for Hyperliquid HIP-3 deployers: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges.","schema":{"example":"xyz","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":[{"instrument_name":"0G-USDT-SWAP","exchange":"okx"},{"instrument_name":"0GUSDT","exchange":"binance"},{"instrument_name":"1000000BOBUSDT","exchange":"binance"}]}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Catalog","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)"},"currency":{"example":"BTC","type":"string","description":"Filter by base currency (e.g., BTC, ETH, SOL)"},"maturity":{"example":"28MAR25","type":"string","description":"Filter by maturity/expiry date (e.g., 28MAR25, 27JUN25)"},"limit":{"default":100,"example":100,"type":"number","description":"Maximum number of instruments to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor from a previous response"},"asset_class":{"example":"equity","type":"string","enum":["crypto","equity","commodity","forex","index"],"description":"Filter by asset class. Defaults to all classes. Use \"equity\"/\"commodity\"/\"forex\"/\"index\" to scope to non-crypto perps (NVDA/TSLA equity perps, GOLD/OIL commodity perps, EURUSD FX perps, etc.). Discover available instruments via /api/v1/macro/catalog."},"sub_exchange":{"example":"xyz","type":"string","description":"Filter by sub-venue. Used for Hyperliquid HIP-3 deployers: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges."}}}}}}}},"/api/v1/perpetuals/metadata":{"get":{"description":"Returns metadata for a specific perpetual instrument including data availability, total record count, and pagination information.","operationId":"Perpetuals Metadata","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name","schema":{"example":"deribit","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records per page for pagination calculation","schema":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number"}},{"name":"instrument_name","required":true,"in":"query","description":"Instrument name","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"description":"Metadata successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponseEntity"}}}},"400":{"description":"Bad Request - Invalid parameters or no data found","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Metadata","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name"},"limit":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number","description":"Number of records per page for pagination calculation"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Instrument name"}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/perpetuals/ohlcvt":{"get":{"description":"Retrieves Open, High, Low, Close, Volume, and Trade statistics for perpetual contracts.\n\n**Key Features:**\n- Historical trade-based OHLC candlestick data\n- Buy/sell volume breakdown\n- Trade count statistics\n- Liquidation and block trade volume tracking\n- Mark and index price references\n- Support for multiple resolutions (1m, 5m, 1h)","operationId":"Perpetuals OHLCVT Market Data","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"description":"OHLCVT data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FuturesOhlcvtEntity"}}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","open":103796,"high":103820,"low":103658.5,"close":103673,"vwap":103699.66571160624,"volume":6184600,"buy_volume":1253540,"sell_volume":4931060,"trades_count":419,"buy_trades_count":54,"sell_trades_count":365,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":103690.42,"index_price":103715.64},{"date":"2025-11-04 11:01:00","open":103673,"high":103721,"low":103620.5,"close":103620.5,"vwap":103672.90218204964,"volume":2230930,"buy_volume":325270,"sell_volume":1905660,"trades_count":204,"buy_trades_count":35,"sell_trades_count":169,"liquidation_short_volume":15430,"liquidation_long_volume":28950,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":103619.18,"index_price":103641.58},{"date":"2025-11-04 11:02:00","open":103610,"high":103745,"low":103610,"close":103672.5,"vwap":103706.1497721229,"volume":3613790,"buy_volume":1379460,"sell_volume":2234330,"trades_count":231,"buy_trades_count":70,"sell_trades_count":161,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":250000,"block_trade_sell_volume":180000,"mark_price":103662.33,"index_price":103686.53}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals OHLCVT Market Data","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/level1":{"get":{"description":"Returns level 1 order book data for perpetual instruments.","operationId":"Perpetuals Level 1","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","bid_price_open":103795.5,"bid_price_high":103819.5,"bid_price_low":103658.5,"bid_price_close":103673,"ask_price_open":103796,"ask_price_high":103820,"ask_price_low":103666,"ask_price_close":103673.5,"bid_size_open":141100,"bid_size_high":315370,"bid_size_low":20,"bid_size_close":175500,"ask_size_open":160120,"ask_size_high":859690,"ask_size_low":20,"ask_size_close":199550,"bid_ask_spread_open":0.5,"bid_ask_spread_high":34.5,"bid_ask_spread_low":0.5,"bid_ask_spread_close":0.5,"total_liquidity_open":244470,"total_liquidity_high":870680,"total_liquidity_low":140,"total_liquidity_close":375050,"total_liquidity_avg":346298.3168859649},{"date":"2025-11-04 11:01:00","bid_price_open":103673,"bid_price_high":103726,"bid_price_low":103609.5,"bid_price_close":103609.5,"ask_price_open":103673.5,"ask_price_high":103726.5,"ask_price_low":103610,"ask_price_close":103610,"bid_size_open":173630,"bid_size_high":429090,"bid_size_low":140,"bid_size_close":208530,"ask_size_open":175750,"ask_size_high":824410,"ask_size_low":40,"ask_size_close":176980,"bid_ask_spread_open":0.5,"bid_ask_spread_high":39.5,"bid_ask_spread_low":0.5,"bid_ask_spread_close":0.5,"total_liquidity_open":260070,"total_liquidity_high":1014770,"total_liquidity_low":13470,"total_liquidity_close":385510,"total_liquidity_avg":441197.5935828877},{"date":"2025-11-04 11:02:00","bid_price_open":103609.5,"bid_price_high":103744.5,"bid_price_low":103609.5,"bid_price_close":103655,"ask_price_open":103610,"ask_price_high":103745,"ask_price_low":103610,"ask_price_close":103655.5,"bid_size_open":182250,"bid_size_high":581540,"bid_size_low":20,"bid_size_close":133120,"ask_size_open":196980,"ask_size_high":565090,"ask_size_low":20,"ask_size_close":320250,"bid_ask_spread_open":0.5,"bid_ask_spread_high":32,"bid_ask_spread_low":0.5,"bid_ask_spread_close":0.5,"total_liquidity_open":461780,"total_liquidity_high":768070,"total_liquidity_low":1820,"total_liquidity_close":453370,"total_liquidity_avg":317816.1932938856}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Level 1","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/orderbook":{"get":{"description":"Returns aggregated L2 orderbook depth metrics for perpetual instruments.\n\n**Key Features:**\n- Bid/ask liquidity at 4 depth levels (10, 20, 50, 100 levels)\n- Order book imbalance metrics (OHLC + average) per depth\n- Microprice (liquidity-weighted mid-price)\n- Snapshot count per time bucket\n- Support for multiple resolutions (1m, 5m, 15m, 1h, 4h, 1d)","operationId":"Perpetuals L2 Orderbook","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"description":"L2 orderbook data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-01-22 07:20:00","exchange":"bybit","instrument_name":"BTCUSDT","currency":"BTC","bid_liq_10_open":0.301,"bid_liq_10_high":0.55,"bid_liq_10_low":0.15,"bid_liq_10_close":0.42,"bid_liq_10_avg":0.35,"bid_liq_20_open":0.359,"bid_liq_20_high":0.8,"bid_liq_20_low":0.2,"bid_liq_20_close":0.5,"bid_liq_20_avg":0.45,"bid_liq_50_open":7.831,"bid_liq_50_high":10.5,"bid_liq_50_low":5.2,"bid_liq_50_close":8.1,"bid_liq_50_avg":7.5,"bid_liq_100_open":12.891,"bid_liq_100_high":18,"bid_liq_100_low":9,"bid_liq_100_close":14.5,"bid_liq_100_avg":13.2,"ask_liq_10_open":5.375,"ask_liq_10_high":6.2,"ask_liq_10_low":4.1,"ask_liq_10_close":5.1,"ask_liq_10_avg":5,"ask_liq_20_open":6.398,"ask_liq_20_high":8,"ask_liq_20_low":4.5,"ask_liq_20_close":6,"ask_liq_20_avg":5.8,"ask_liq_50_open":18.966,"ask_liq_50_high":22,"ask_liq_50_low":15,"ask_liq_50_close":19.5,"ask_liq_50_avg":18.2,"ask_liq_100_open":40.834,"ask_liq_100_high":50,"ask_liq_100_low":30,"ask_liq_100_close":42,"ask_liq_100_avg":39.5,"imbalance_10_open":-0.894,"imbalance_10_high":-0.5,"imbalance_10_low":-0.95,"imbalance_10_close":-0.82,"imbalance_10_avg":-0.78,"imbalance_20_open":-0.894,"imbalance_20_high":-0.5,"imbalance_20_low":-0.95,"imbalance_20_close":-0.82,"imbalance_20_avg":-0.78,"imbalance_50_open":-0.416,"imbalance_50_high":-0.1,"imbalance_50_low":-0.6,"imbalance_50_close":-0.35,"imbalance_50_avg":-0.38,"imbalance_100_open":-0.52,"imbalance_100_high":-0.2,"imbalance_100_low":-0.7,"imbalance_100_close":-0.45,"imbalance_100_avg":-0.48,"microprice_open":89967.9,"microprice_high":89975,"microprice_low":89960,"microprice_close":89970.5,"microprice_avg":89968.2,"snapshot_count":60}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAxLTIyIDA3OjIxOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals L2 Orderbook","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/orderbook-raw":{"get":{"description":"Returns raw L2 orderbook snapshots for perpetual instruments with full bid/ask arrays.\n\n**Key Features:**\n- Full bid/ask price levels (up to 100 levels each)\n- Pre-computed liquidity at 4 depth levels (10, 20, 50, 100)\n- Order book imbalance per depth\n- Microprice (liquidity-weighted mid-price)\n- Individual snapshots (not aggregated) — 30-day data retention","operationId":"Perpetuals L2 Orderbook Raw","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full perpetual instrument identifier (e.g., BTC-PERPETUAL). Either instrument_name or currency is required.","schema":{"example":"BTC-PERPETUAL","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL perpetuals for this currency. Either currency or instrument_name is required.","schema":{"example":"BTC","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only return trades with a block_trade_id (block trades).","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts). Filters out dust trades.","schema":{"example":1,"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread).","schema":{"type":"string","enum":["COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_MULTI_LEG_1","COMBO_PERP_VS_FUTURE","CUSTOM_STRATEGY","Closed COMBO_MULTI_LEG_1","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_PERP","Closed SHORT_PERP","LONG_PERP","Opened COMBO_MULTI_LEG_1","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened LONG_PERP","Opened SHORT_PERP","SHORT_PERP"]}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"Raw L2 orderbook snapshots successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1769066457868,"date":"2026-01-22T07:20:57.000Z","exchange":"bybit","instrument_name":"BTCUSDT","currency":"BTC","margin_type":"linear","multiplier":1,"depth":100,"bids":[{"price":89967.9,"size":0.169},{"price":89967.8,"size":0.002}],"asks":[{"price":89968,"size":3.085},{"price":89968.2,"size":0.002}],"bid_liquidity_10":0.301,"ask_liquidity_10":5.375,"bid_liquidity_20":0.359,"ask_liquidity_20":6.398,"bid_liquidity_50":7.831,"ask_liquidity_50":18.966,"bid_liquidity_100":12.891,"ask_liquidity_100":40.834,"imbalance_10":-0.894,"imbalance_20":-0.894,"imbalance_50":-0.416,"imbalance_100":-0.52,"microprice":89967.905}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NjkwNjY0NTc4Njh9"}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals L2 Orderbook Raw Snapshots","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full perpetual instrument identifier (e.g., BTC-PERPETUAL). Either instrument_name or currency is required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL perpetuals for this currency. Either currency or instrument_name is required."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"block_only":{"default":false,"type":"boolean","description":"If true, only return trades with a block_trade_id (block trades)."},"min_amount":{"example":1,"type":"number","description":"Minimum trade amount (in contracts). Filters out dust trades."},"strategy":{"example":"calendar_spread","type":"string","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread)."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/perpetuals/volume":{"get":{"description":"Returns rolling 24h volume metrics (base and USD) for perpetual instruments filtered by currency with optional aggregation and interval bucketing.","operationId":"Perpetuals Volume Stats","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved perpetuals volume data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","volume_24h":13306.97626536,"volume_usd_24h":1408049640},{"date":"2025-11-04 11:01:00","volume_24h":13325.84296037,"volume_usd_24h":1409996050},{"date":"2025-11-04 11:02:00","volume_24h":13359.76934158,"volume_usd_24h":1413511150}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Volume Stats","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/trades/summary":{"get":{"description":"Returns aggregated trade statistics for perpetual swaps grouped by a chosen axis. One compact call replaces scanning individual trades. Returns grouped stats: trade_count, volume, buy/sell_volume, net_oi_change, block stats, avg_price, vwap. Group by: exchange, instrument_name, direction, or strategy.","operationId":"Perpetuals Trades Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH)","schema":{"example":"BTC","type":"string"}},{"name":"group_by","required":true,"in":"query","description":"Axis to group results by","schema":{"type":"string","enum":["exchange","instrument_name","direction","strategy"]}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only include block trades.","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts).","schema":{"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values.","schema":{"type":"string","enum":["COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_MULTI_LEG_1","COMBO_PERP_VS_FUTURE","CUSTOM_STRATEGY","Closed COMBO_MULTI_LEG_1","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_PERP","Closed SHORT_PERP","LONG_PERP","Opened COMBO_MULTI_LEG_1","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened LONG_PERP","Opened SHORT_PERP","SHORT_PERP"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"group_key":"BTC-PERPETUAL","trade_count":5000,"volume":12345.6,"buy_volume":6500.3,"sell_volume":5845.3,"net_oi_change":450.2,"block_trade_count":12,"block_trade_volume":800,"avg_price":95000,"vwap":95050}],"metadata":{"group_by":"instrument_name","total_trades":5000,"total_volume":12345.6}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Trades Summary","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH)"},"group_by":{"type":"string","enum":["exchange","instrument_name","direction","strategy"],"description":"Axis to group results by"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction"},"block_only":{"default":false,"type":"boolean","description":"If true, only include block trades."},"min_amount":{"type":"number","description":"Minimum trade amount (in contracts)."},"strategy":{"type":"string","description":"Filter by strategy label. Accepts comma-separated values."}},"required":["exchange","currency","group_by"]}}}}}},"/api/v1/perpetuals/flow":{"get":{"description":"Returns an aggregated flow summary for perpetual swaps including total trades, buy/sell volume split, net OI change, block trade stats, liquidation pressure (long/short breakdown), most active instruments, notable trades, and notable liquidations. One call returns everything pre-computed.","operationId":"Perpetuals Flow Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH). Required.","schema":{"example":"BTC","type":"string"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum contract amount per trade to include. Filters dust before aggregating.","schema":{"example":1,"type":"number"}},{"name":"top_n","required":false,"in":"query","description":"Number of notable trades and most active instruments to return. Default 10.","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Flow summary successfully retrieved","content":{"application/json":{"example":{"summary":{"total_trades":5000,"total_volume":12345.6,"buy_volume":6500.3,"sell_volume":5845.3,"net_oi_change":450.2,"block_trade_count":12,"block_trade_volume":800,"avg_price":95000,"vwap":95050,"most_active_instruments":[{"instrument_name":"BTC-PERPETUAL","trade_count":3000,"volume":8000,"net_oi_change":200}],"liquidation_count":120,"long_liquidation_count":75,"short_liquidation_count":45,"total_liquidation_usd":8500000,"long_liquidation_usd":5500000,"short_liquidation_usd":3000000,"largest_liquidation_usd":500000},"notable_trades":[],"notable_liquidations":[]}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Flow Summary","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Required."},"min_amount":{"example":1,"type":"number","description":"Minimum contract amount per trade to include. Filters dust before aggregating."},"top_n":{"default":10,"example":10,"type":"number","description":"Number of notable trades and most active instruments to return. Default 10."}},"required":["exchange","currency"]}}}}}},"/api/v1/perpetuals/trades":{"get":{"description":"Returns perpetual trades with full trade details. Supports two modes: (1) instrument mode — provide instrument_name for a single perpetual, (2) currency mode — provide currency (e.g. BTC) for ALL perpetual trades across all instruments. Additional filters: direction, block_only, min_amount, strategy, sort, sort_dir. Use top_n for quick top-trades scanning.","operationId":"Perpetuals Trade History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full perpetual instrument identifier (e.g., BTC-PERPETUAL). Either instrument_name or currency is required.","schema":{"example":"BTC-PERPETUAL","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL perpetuals for this currency. Either currency or instrument_name is required.","schema":{"example":"BTC","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only return trades with a block_trade_id (block trades).","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts). Filters out dust trades.","schema":{"example":1,"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread).","schema":{"type":"string","enum":["COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_MULTI_LEG_1","COMBO_PERP_VS_FUTURE","CUSTOM_STRATEGY","Closed COMBO_MULTI_LEG_1","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_PERP","Closed SHORT_PERP","LONG_PERP","Opened COMBO_MULTI_LEG_1","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened LONG_PERP","Opened SHORT_PERP","SHORT_PERP"]}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"instrument_name":"BTC-PERPETUAL","timestamp":1748936294661,"date":"2025-11-04 11:00:00","trade_id":"369968310","block_trade_id":"","combo_id":"BTC-FS-6JUN25_PERP","combo_trade_id":"369968308","strategy":"COMBO_PERP_VS_FUTURE","direction":"buy","tick_direction":0,"amount":500,"price":105306.5,"index_price":105306.68,"oi_change":null,"open_interest":968197530,"oi_before":968197530,"maturity":"PERPETUAL","basis":-0.17999999999301508,"funding":0.00001299},{"instrument_name":"BTC-PERPETUAL","timestamp":1748936295702,"date":"2025-11-04 11:00:00","trade_id":"369968315","block_trade_id":"","combo_id":"BTC-FS-6JUN25_PERP","combo_trade_id":"369968313","strategy":"COMBO_PERP_VS_FUTURE","direction":"buy","tick_direction":0,"amount":150,"price":105308,"index_price":105308.34,"oi_change":null,"open_interest":968197530,"oi_before":968197530,"maturity":"PERPETUAL","basis":-0.33999999999650754,"funding":0.00001299},{"instrument_name":"BTC-PERPETUAL","timestamp":1748936320292,"date":"2025-11-04 11:00:00","trade_id":"369968340","block_trade_id":"","combo_id":"BTC-FS-6JUN25_PERP","combo_trade_id":"369968338","strategy":"COMBO_PERP_VS_FUTURE","direction":"buy","tick_direction":0,"amount":500,"price":105307.5,"index_price":105310.39,"oi_change":null,"open_interest":968194400,"oi_before":968194400,"maturity":"PERPETUAL","basis":-2.889999999999418,"funding":0.00001299}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOiIxNzQ4OTk0NTQ5NDUyIiwidHJhZGVfaWQiOiIzNzAwNDk3NTEifQ=="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Trade History","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full perpetual instrument identifier (e.g., BTC-PERPETUAL). Either instrument_name or currency is required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL perpetuals for this currency. Either currency or instrument_name is required."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"block_only":{"default":false,"type":"boolean","description":"If true, only return trades with a block_trade_id (block trades)."},"min_amount":{"example":1,"type":"number","description":"Minimum trade amount (in contracts). Filters out dust trades."},"strategy":{"example":"calendar_spread","type":"string","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread)."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/perpetuals/open-interest":{"get":{"description":"Aggregates open interest across the selected perpetual instrument or currency using the requested resolution.","operationId":"Perpetuals Open Interest","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","oi_open":14483.836684775828,"oi_high":14494.975017789338,"oi_low":14480.302050051028,"oi_close":14484.75799403648},{"date":"2025-11-04 11:01:00","oi_open":14484.75799403648,"oi_high":14495.570477778463,"oi_low":14484.624753264488,"oi_close":14495.303282654815},{"date":"2025-11-04 11:02:00","oi_open":14495.306080458478,"oi_high":14495.349446553402,"oi_low":14470.044024835908,"oi_close":14479.21911460026}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Open Interest","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/ticker-history":{"get":{"description":"Returns historical ticker data for perpetual instruments.","operationId":"Perpetuals Ticker History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price":103690.42,"index_price":103715.64,"bid_price":103673,"ask_price":103673.5,"bid_ask_spread":0.5,"bid_size":175500,"ask_size":199550,"oi":14484.75799403648,"volume_usd_24h":1408049640,"funding_rate":5,"next_funding_time":155},{"date":"2025-11-04 11:01:00","mark_price":103619.18,"index_price":103641.58,"bid_price":103609.5,"ask_price":103610,"bid_ask_spread":0.5,"bid_size":208530,"ask_size":176980,"oi":14495.303282654815,"volume_usd_24h":1409996050,"funding_rate":5,"next_funding_time":155},{"date":"2025-11-04 11:02:00","mark_price":103662.33,"index_price":103686.53,"bid_price":103655,"ask_price":103655.5,"bid_ask_spread":0.5,"bid_size":133120,"ask_size":320250,"oi":14479.21911460026,"volume_usd_24h":1413511150,"funding_rate":5,"next_funding_time":155}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Ticker History","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/carry":{"get":{"description":"Returns funding rate (1-period and 8h forms), basis (mark − index), and annualized carry (% APR) per OHLC bucket for any perpetual instrument. **This is the funding-rate endpoint** — there is no separate /funding route. Funding, basis, and carry move together for perp analysis (a high positive funding rate with a wide negative basis means perps are trading rich vs. spot and longs are paying to hold), so they share one route. Works identically for crypto perps and macro perps (equity / commodity / FX / index — discover via /api/v1/macro/catalog).","operationId":"Perpetuals Carry","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1762250400000,"minute":"2025-11-04 11:00:00","funding_rate_open":0,"funding_rate_high":0,"funding_rate_low":0,"funding_rate_close":0,"funding_8h_open":-0.00004634,"funding_8h_high":-0.00004628,"funding_8h_low":-0.00004634,"funding_8h_close":-0.00004628,"basis_open":-19.69999999999709,"basis_high":-18.820000000006985,"basis_low":-23.330000000001746,"basis_close":-25.220000000001164},{"timestamp":1762250460000,"minute":"2025-11-04 11:01:00","funding_rate_open":0,"funding_rate_high":0,"funding_rate_low":-0.00001633,"funding_rate_close":0,"funding_8h_open":-0.00004628,"funding_8h_high":-0.00004627,"funding_8h_low":-0.00004628,"funding_8h_close":-0.00004627,"basis_open":-25.220000000001164,"basis_high":-23.020000000004075,"basis_low":-22.39999999999418,"basis_close":-22.40000000000873},{"timestamp":1762250520000,"minute":"2025-11-04 11:02:00","funding_rate_open":0,"funding_rate_high":0,"funding_rate_low":0,"funding_rate_close":0,"funding_8h_open":-0.00004626,"funding_8h_high":-0.00004626,"funding_8h_low":-0.00004626,"funding_8h_close":-0.00004626,"basis_open":-22.70999999999185,"basis_high":-17.830000000001746,"basis_low":-22.729999999995925,"basis_close":-24.19999999999709}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Carry — funding rate, basis, annualized carry","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/reference-price":{"get":{"description":"Returns reference price data for perpetual instruments.","operationId":"Perpetuals Reference Prices","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price_open":103794.61,"mark_price_high":103815.84,"mark_price_low":103680.29,"mark_price_close":103690.42,"index_price_open":103814.31,"index_price_high":103834.66,"index_price_low":103703.62,"index_price_close":103715.64,"underlying_price":19321.37},{"date":"2025-11-04 11:01:00","mark_price_open":103690.42,"mark_price_high":103709.23,"mark_price_low":103617.27,"mark_price_close":103619.18,"index_price_open":103715.64,"index_price_high":103732.25,"index_price_low":103639.67,"index_price_close":103641.58,"underlying_price":19321.37},{"date":"2025-11-04 11:02:00","mark_price_open":103619.16,"mark_price_high":103737.92,"mark_price_low":103618.85,"mark_price_close":103662.33,"index_price_open":103641.87,"index_price_high":103755.75,"index_price_low":103641.58,"index_price_close":103686.53,"underlying_price":19321.37}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Reference Prices","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"}}}}}}}},"/api/v1/perpetuals/snapshot":{"get":{"description":"Returns a snapshot of all perpetual instruments for a given exchange at a single minute. If no date is provided, returns the latest available snapshot. Currency is optional.","operationId":"Perpetuals Snapshot","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"date","required":false,"in":"query","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"currency","required":false,"in":"query","description":"Base currency filter (e.g., BTC, ETH)","schema":{"example":"BTC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"BTC-PERPETUAL","currency":"BTC","mark_price":103690.42,"index_price":103715.64,"bid_price":103673,"ask_price":103673.5,"bid_ask_spread":0.5,"bid_size":175500,"ask_size":199550,"oi":14484.76,"volume_usd_24h":1408049640,"funding_rate":5,"next_funding_time":1733788800000},{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"ETH-PERPETUAL","currency":"ETH","mark_price":3180.25,"index_price":3182.1,"bid_price":3179.5,"ask_price":3180,"bid_ask_spread":0.5,"bid_size":50000,"ask_size":60000,"oi":48200.3,"volume_usd_24h":520400000,"funding_rate":3.2,"next_funding_time":1733788800000}],"meta":{"minute":"2025-11-04 11:00:00"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Snapshot","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"currency":{"example":"BTC","type":"string","description":"Base currency filter (e.g., BTC, ETH)"}},"required":["exchange"]}}}}}},"/api/v1/perpetuals/liquidations":{"get":{"description":"Returns individual forced liquidation events for perpetual swaps. Supports filtering by direction, position side, and minimum USD amount. Data available for binance, bybit, and okx exchanges.","operationId":"Perpetuals Liquidation History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to DESC (newest/largest first).","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by liquidation order direction (buy = short squeeze, sell = long liquidation)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"position_side","required":false,"in":"query","description":"Filter by position side being liquidated","schema":{"type":"string","enum":["long","short"]}},{"name":"min_amount_usd","required":false,"in":"query","description":"Minimum liquidation value in USD. Filters out small liquidations.","schema":{"example":1000,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount_usd","price"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"instrument_name":"BTCUSDT","timestamp":1772104946628,"date":"2026-02-26T18:22:26.628Z","exchange":"binance","currency":"BTC","direction":"sell","position_side":"long","category":"forced","price":68187.4,"amount":0.075,"amount_base":0.075,"amount_usd":5114.05,"mark_price":68187.5,"index_price":68222.5,"margin_type":"linear","maturity":null,"days_to_expiry":null,"trade_id":null,"order_id":null},{"instrument_name":"ENSOUSDT","timestamp":1772104947089,"date":"2026-02-26T18:22:27.089Z","exchange":"binance","currency":"ENSO","direction":"sell","position_side":"long","category":"forced","price":1.5442,"amount":21.7,"amount_base":21.7,"amount_usd":33.51,"mark_price":1.5444,"index_price":1.6229,"margin_type":"linear","maturity":null,"days_to_expiry":null,"trade_id":null,"order_id":null}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NzIxMDQ5NDYwMDB9"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Perpetuals Liquidation History","tags":["Perpetuals"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to DESC (newest/largest first)."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, nado)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier (e.g., BTC-PERPETUAL, BTC-29MAR24-70000-C)"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by liquidation order direction (buy = short squeeze, sell = long liquidation)"},"position_side":{"type":"string","enum":["long","short"],"description":"Filter by position side being liquidated"},"min_amount_usd":{"example":1000,"type":"number","description":"Minimum liquidation value in USD. Filters out small liquidations."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount_usd","price"],"description":"Sort field. Default: timestamp."}}}}}}}},"/api/v1/futures/catalog":{"get":{"description":"Returns a list of available futures instruments.","operationId":"Futures Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Filter by base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity/expiry date (e.g., 14AUG26, 27JUN25)","schema":{"example":"14AUG26","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of instruments to return (1-1000)","schema":{"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":[{"instrument_name":"BNBUSD_251226","exchange":"binance"},{"instrument_name":"BNBUSD_260327","exchange":"binance"},{"instrument_name":"BTC-14AUG26","exchange":"deribit"}]}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Catalog","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid)"},"currency":{"example":"BTC","type":"string","description":"Filter by base currency (e.g., BTC, ETH, SOL)"},"maturity":{"example":"14AUG26","type":"string","description":"Filter by maturity/expiry date (e.g., 14AUG26, 27JUN25)"},"limit":{"default":100,"example":100,"type":"number","description":"Maximum number of instruments to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor from a previous response"}}}}}}}},"/api/v1/futures/metadata":{"get":{"description":"Returns metadata for a specific futures instrument including data availability, total record count, and pagination information.","operationId":"Futures Metadata","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name","schema":{"example":"deribit","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Number of records per page for pagination calculation","schema":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number"}},{"name":"instrument_name","required":true,"in":"query","description":"Instrument name","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"description":"Metadata successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponseEntity"}}}},"400":{"description":"Bad Request - Invalid parameters or no data found","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Metadata","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name"},"limit":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number","description":"Number of records per page for pagination calculation"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Instrument name"}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/futures/ohlcvt":{"get":{"description":"Retrieves Open, High, Low, Close, Volume, and Trade statistics for futures and perpetual\ncontracts.\n\n**Key Features:**\n- Historical trade-based OHLC candlestick data\n- Buy/sell volume breakdown\n- Trade count statistics\n- Liquidation and block trade volume tracking\n- Mark and index price references\n- Support for multiple resolutions (1m, 5m, 1h)\n- Filter by instrument type (perpetual vs dated futures)","operationId":"Futures OHLCVT Market Data","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"description":"OHLCVT data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/FuturesOhlcvtEntity"}}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","open":109307.5,"high":109307.5,"low":109307.5,"close":109307.5,"vwap":109307.5,"volume":5830,"buy_volume":0,"sell_volume":5830,"trades_count":2,"buy_trades_count":0,"sell_trades_count":2,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":109224.93,"index_price":103721.05,"days_to_expiry":324.9166666666667},{"date":"2025-11-04 11:01:00","open":109139.43,"high":109139.43,"low":109139.43,"close":109139.43,"vwap":109139.43,"volume":0,"buy_volume":0,"sell_volume":0,"trades_count":0,"buy_trades_count":0,"sell_trades_count":0,"liquidation_short_volume":3200,"liquidation_long_volume":5800,"block_trade_buy_volume":null,"block_trade_sell_volume":null,"mark_price":109139.43,"index_price":103641.58,"days_to_expiry":324.91597222222225},{"date":"2025-11-04 11:02:00","open":109183.39,"high":109183.39,"low":109183.39,"close":109183.39,"vwap":109183.39,"volume":0,"buy_volume":0,"sell_volume":0,"trades_count":0,"buy_trades_count":0,"sell_trades_count":0,"liquidation_short_volume":null,"liquidation_long_volume":null,"block_trade_buy_volume":50000,"block_trade_sell_volume":35000,"mark_price":109183.39,"index_price":103686.12,"days_to_expiry":324.91527777777776}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures OHLCVT Market Data","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/level1":{"get":{"description":"Returns level 1 order book data for futures instruments.","operationId":"Futures Level 1","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","bid_price_open":109295,"bid_price_high":109347.5,"bid_price_low":109120,"bid_price_close":109182.5,"ask_price_open":109330,"ask_price_high":109367.5,"ask_price_low":109207.5,"ask_price_close":109225,"bid_size_open":5730,"bid_size_high":48510,"bid_size_low":320,"bid_size_close":40000,"ask_size_open":700,"ask_size_high":59890,"ask_size_low":490,"ask_size_close":40000,"bid_ask_spread_open":35,"bid_ask_spread_high":192.5,"bid_ask_spread_low":2.5,"bid_ask_spread_close":42.5,"total_liquidity_open":40700,"total_liquidity_high":99890,"total_liquidity_low":1110,"total_liquidity_close":80000,"total_liquidity_avg":23645.138121546963},{"date":"2025-11-04 11:01:00","bid_price_open":109187.5,"bid_price_high":109242.5,"bid_price_low":109110,"bid_price_close":109125,"ask_price_open":109215,"ask_price_high":109315,"ask_price_low":109135,"ask_price_close":109135,"bid_size_open":7460,"bid_size_high":45000,"bid_size_low":40,"bid_size_close":3520,"ask_size_open":6980,"ask_size_high":135000,"ask_size_low":700,"ask_size_close":700,"bid_ask_spread_open":27.5,"bid_ask_spread_high":112.5,"bid_ask_spread_low":5,"bid_ask_spread_close":10,"total_liquidity_open":7250,"total_liquidity_high":148430,"total_liquidity_low":740,"total_liquidity_close":4220,"total_liquidity_avg":21844.923547400613},{"date":"2025-11-04 11:02:00","bid_price_open":109125,"bid_price_high":109260,"bid_price_low":109110,"bid_price_close":109162.5,"ask_price_open":109135,"ask_price_high":109330,"ask_price_low":109135,"ask_price_close":109182.5,"bid_size_open":4370,"bid_size_high":45000,"bid_size_low":40,"bid_size_close":4550,"ask_size_open":700,"ask_size_high":90000,"ask_size_low":670,"ask_size_close":700,"bid_ask_spread_open":10,"bid_ask_spread_high":165,"bid_ask_spread_low":5,"bid_ask_spread_close":20,"total_liquidity_open":6200,"total_liquidity_high":103430,"total_liquidity_low":1220,"total_liquidity_close":5250,"total_liquidity_avg":21753.742038216562}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Level 1","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/orderbook":{"get":{"description":"Returns aggregated L2 orderbook depth metrics for futures instruments.\n\n**Key Features:**\n- Bid/ask liquidity at 4 depth levels (10, 20, 50, 100 levels)\n- Order book imbalance metrics (OHLC + average) per depth\n- Microprice (liquidity-weighted mid-price)\n- Snapshot count per time bucket\n- Support for multiple resolutions (1m, 5m, 15m, 1h, 4h, 1d)","operationId":"Futures L2 Orderbook","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"description":"L2 orderbook data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-01-22 07:20:00","exchange":"deribit","instrument_name":"BTC-14AUG26","currency":"BTC","instrument_type":"future","maturity":"14AUG26","days_to_expiry":64.7,"bid_liq_10_open":12.5,"bid_liq_10_high":18.2,"bid_liq_10_low":8.1,"bid_liq_10_close":14.3,"bid_liq_10_avg":13.1,"bid_liq_20_open":25.8,"bid_liq_20_high":35,"bid_liq_20_low":18.5,"bid_liq_20_close":28.1,"bid_liq_20_avg":26.4,"bid_liq_50_open":65.2,"bid_liq_50_high":82,"bid_liq_50_low":50.3,"bid_liq_50_close":70.5,"bid_liq_50_avg":66.8,"bid_liq_100_open":120.5,"bid_liq_100_high":155,"bid_liq_100_low":95.2,"bid_liq_100_close":130.8,"bid_liq_100_avg":124.3,"ask_liq_10_open":15.3,"ask_liq_10_high":22.1,"ask_liq_10_low":10.5,"ask_liq_10_close":17.8,"ask_liq_10_avg":16.2,"ask_liq_20_open":30.1,"ask_liq_20_high":42,"ask_liq_20_low":22.5,"ask_liq_20_close":33.5,"ask_liq_20_avg":31,"ask_liq_50_open":78.5,"ask_liq_50_high":95,"ask_liq_50_low":60.2,"ask_liq_50_close":82.1,"ask_liq_50_avg":77.5,"ask_liq_100_open":145.2,"ask_liq_100_high":180,"ask_liq_100_low":110.5,"ask_liq_100_close":152.3,"ask_liq_100_avg":142.1,"imbalance_10_open":-0.1,"imbalance_10_high":0.25,"imbalance_10_low":-0.35,"imbalance_10_close":-0.11,"imbalance_10_avg":-0.09,"imbalance_20_open":-0.08,"imbalance_20_high":0.2,"imbalance_20_low":-0.3,"imbalance_20_close":-0.09,"imbalance_20_avg":-0.07,"imbalance_50_open":-0.09,"imbalance_50_high":0.15,"imbalance_50_low":-0.25,"imbalance_50_close":-0.08,"imbalance_50_avg":-0.06,"imbalance_100_open":-0.09,"imbalance_100_high":0.12,"imbalance_100_low":-0.2,"imbalance_100_close":-0.08,"imbalance_100_avg":-0.06,"microprice_open":105250.5,"microprice_high":105320,"microprice_low":105180,"microprice_close":105290.2,"microprice_avg":105260.8,"snapshot_count":60}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAxLTIyIDA3OjIxOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures L2 Orderbook","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/orderbook-raw":{"get":{"description":"Returns raw L2 orderbook snapshots for futures instruments with full bid/ask arrays.\n\n**Key Features:**\n- Full bid/ask price levels (up to 100 levels each)\n- Pre-computed liquidity at 4 depth levels (10, 20, 50, 100)\n- Order book imbalance per depth\n- Microprice (liquidity-weighted mid-price)\n- Individual snapshots (not aggregated) — 30-day data retention","operationId":"Futures L2 Orderbook Raw","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26). Either instrument_name or currency is required.","schema":{"example":"BTC-14AUG26","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL dated futures for this currency. Either currency or instrument_name is required.","schema":{"example":"BTC","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only return trades with a block_trade_id (block trades).","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts). Filters out dust trades.","schema":{"example":1,"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread).","schema":{"type":"string","enum":["COMBO_CALENDAR_SPREAD","COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_PERP_VS_FUTURE","COMBO_ROLL_BACK","COMBO_ROLL_FORWARD","CUSTOM_STRATEGY","Closed COMBO_CALENDAR_SPREAD","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_FUTURE","Closed SHORT_FUTURE","LONG_FUTURE","Opened COMBO_CALENDAR_SPREAD","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened SHORT_FUTURE"]}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity date (e.g. 14AUG26). Only for dated futures.","schema":{"example":"14AUG26","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"description":"Raw L2 orderbook snapshots successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1769066457868,"date":"2026-01-22T07:20:57.000Z","exchange":"deribit","instrument_name":"BTC-14AUG26","currency":"BTC","instrument_type":"future","maturity":"14AUG26","days_to_expiry":64.7,"margin_type":"inverse","multiplier":1,"depth":100,"bids":[{"price":105250,"size":1.5},{"price":105249.5,"size":0.8}],"asks":[{"price":105250.5,"size":2.1},{"price":105251,"size":1.2}],"bid_liquidity_10":12.5,"ask_liquidity_10":15.3,"bid_liquidity_20":25.8,"ask_liquidity_20":30.1,"bid_liquidity_50":65.2,"ask_liquidity_50":78.5,"bid_liquidity_100":120.5,"ask_liquidity_100":145.2,"imbalance_10":-0.1,"imbalance_20":-0.08,"imbalance_50":-0.09,"imbalance_100":-0.09,"microprice":105250.3}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NjkwNjY0NTc4Njh9"}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures L2 Orderbook Raw Snapshots","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26). Either instrument_name or currency is required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL dated futures for this currency. Either currency or instrument_name is required."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"block_only":{"default":false,"type":"boolean","description":"If true, only return trades with a block_trade_id (block trades)."},"min_amount":{"example":1,"type":"number","description":"Minimum trade amount (in contracts). Filters out dust trades."},"strategy":{"example":"calendar_spread","type":"string","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread)."},"maturity":{"example":"14AUG26","type":"string","description":"Filter by maturity date (e.g. 14AUG26). Only for dated futures."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/futures/volume":{"get":{"description":"Returns rolling 24h volume metrics (base and USD) for futures instruments filtered by currency with optional aggregation and interval bucketing.","operationId":"Futures Volume Stats","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved futures volume data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","volume_24h":29.54344186,"volume_usd_24h":3297310},{"date":"2025-11-04 11:01:00","volume_24h":29.54264721,"volume_usd_24h":3297220},{"date":"2025-11-04 11:02:00","volume_24h":29.54264721,"volume_usd_24h":3297220}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Volume Stats","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/trades/summary":{"get":{"description":"Returns aggregated trade statistics for dated futures grouped by a chosen axis. One compact call replaces scanning individual trades. Returns grouped stats: trade_count, volume, buy/sell_volume, net_oi_change, block stats, avg_price, vwap. Group by: exchange, instrument_name, maturity, direction, or strategy.","operationId":"Futures Trades Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH)","schema":{"example":"BTC","type":"string"}},{"name":"group_by","required":true,"in":"query","description":"Axis to group results by","schema":{"type":"string","enum":["exchange","instrument_name","maturity","direction","strategy"]}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only include block trades.","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts).","schema":{"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values.","schema":{"type":"string","enum":["COMBO_CALENDAR_SPREAD","COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_PERP_VS_FUTURE","COMBO_ROLL_BACK","COMBO_ROLL_FORWARD","CUSTOM_STRATEGY","Closed COMBO_CALENDAR_SPREAD","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_FUTURE","Closed SHORT_FUTURE","LONG_FUTURE","Opened COMBO_CALENDAR_SPREAD","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened SHORT_FUTURE"]}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity date (e.g. 14AUG26).","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"group_key":"14AUG26","trade_count":150,"volume":1234.5,"buy_volume":700.2,"sell_volume":534.3,"net_oi_change":120.5,"block_trade_count":5,"block_trade_volume":200,"avg_price":95000,"vwap":95100}],"metadata":{"group_by":"maturity","total_trades":150,"total_volume":1234.5}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Trades Summary","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH)"},"group_by":{"type":"string","enum":["exchange","instrument_name","maturity","direction","strategy"],"description":"Axis to group results by"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction"},"block_only":{"default":false,"type":"boolean","description":"If true, only include block trades."},"min_amount":{"type":"number","description":"Minimum trade amount (in contracts)."},"strategy":{"type":"string","description":"Filter by strategy label. Accepts comma-separated values."},"maturity":{"type":"string","description":"Filter by maturity date (e.g. 14AUG26)."}},"required":["exchange","currency","group_by"]}}}}}},"/api/v1/futures/flow":{"get":{"description":"Returns an aggregated flow summary for dated futures including total trades, buy/sell volume split, net OI change, block trade stats, liquidation pressure (long/short breakdown), most active instruments, notable trades, and notable liquidations. One call returns everything pre-computed.","operationId":"Futures Flow Summary","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g. BTC, ETH). Required.","schema":{"example":"BTC","type":"string"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum contract amount per trade to include. Filters dust before aggregating.","schema":{"example":1,"type":"number"}},{"name":"top_n","required":false,"in":"query","description":"Number of notable trades and most active instruments to return. Default 10.","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Flow summary successfully retrieved","content":{"application/json":{"example":{"summary":{"total_trades":500,"total_volume":1234.5,"buy_volume":700.2,"sell_volume":534.3,"net_oi_change":120.5,"block_trade_count":8,"block_trade_volume":400,"avg_price":95000,"vwap":95100,"most_active_instruments":[{"instrument_name":"BTC-14AUG26","trade_count":150,"volume":500,"net_oi_change":80}],"liquidation_count":45,"long_liquidation_count":30,"short_liquidation_count":15,"total_liquidation_usd":2500000,"long_liquidation_usd":1800000,"short_liquidation_usd":700000,"largest_liquidation_usd":250000},"notable_trades":[],"notable_liquidations":[]}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Flow Summary","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Required."},"min_amount":{"example":1,"type":"number","description":"Minimum contract amount per trade to include. Filters dust before aggregating."},"top_n":{"default":10,"example":10,"type":"number","description":"Number of notable trades and most active instruments to return. Default 10."}},"required":["exchange","currency"]}}}}}},"/api/v1/futures/trades":{"get":{"description":"Returns futures trades with full trade details. Supports two modes: (1) instrument mode — provide instrument_name for a single dated future, (2) currency mode — provide currency (e.g. BTC) for ALL dated futures trades across all instruments. Additional filters: direction, block_only, min_amount, strategy, maturity, sort, sort_dir. Use top_n for quick top-trades scanning.","operationId":"Futures Trade History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26). Either instrument_name or currency is required.","schema":{"example":"BTC-14AUG26","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL dated futures for this currency. Either currency or instrument_name is required.","schema":{"example":"BTC","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"block_only","required":false,"in":"query","description":"If true, only return trades with a block_trade_id (block trades).","schema":{"default":false,"type":"boolean"}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in contracts). Filters out dust trades.","schema":{"example":1,"type":"number"}},{"name":"strategy","required":false,"in":"query","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread).","schema":{"type":"string","enum":["COMBO_CALENDAR_SPREAD","COMBO_HEDGE_ROLL_TO_FUTURE","COMBO_HEDGE_ROLL_TO_PERP","COMBO_PERP_VS_FUTURE","COMBO_ROLL_BACK","COMBO_ROLL_FORWARD","CUSTOM_STRATEGY","Closed COMBO_CALENDAR_SPREAD","Closed COMBO_PERP_VS_FUTURE_UNWIND","Closed LONG_FUTURE","Closed SHORT_FUTURE","LONG_FUTURE","Opened COMBO_CALENDAR_SPREAD","Opened COMBO_PERP_VS_FUTURE_SPREAD","Opened SHORT_FUTURE"]}},{"name":"maturity","required":false,"in":"query","description":"Filter by maturity date (e.g. 14AUG26). Only for dated futures.","schema":{"example":"14AUG26","type":"string"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"instrument_name":"BTC-14AUG26","date":"2025-11-04T11:01:55.040Z","timestamp":1758876115040,"trade_id":"386518052","block_trade_id":"","combo_id":"BTC-FS-25SEP26_26JUN26","combo_trade_id":"386518051","strategy":"COMBO_CALENDAR_SPREAD","direction":"sell","tick_direction":2,"amount":23750,"price":117287.5,"index_price":109621.72,"oi_change":null,"open_interest":1095380,"oi_before":1095380,"maturity":"25SEP26","days_to_expiry":363.9709,"basis":7665.779999999999},{"instrument_name":"BTC-14AUG26","date":"2025-11-04T11:01:55.040Z","timestamp":1758885173562,"trade_id":"386539875","block_trade_id":"","combo_id":"BTC-FS-25SEP26_26JUN26","combo_trade_id":"386539874","strategy":"COMBO_CALENDAR_SPREAD","direction":"buy","tick_direction":2,"amount":50000,"price":116762.5,"index_price":108916.75,"oi_change":50000,"open_interest":2985210,"oi_before":2935210,"maturity":"25SEP26","days_to_expiry":363.866,"basis":7845.75},{"instrument_name":"BTC-14AUG26","date":"2025-11-04T11:01:55.040Z","timestamp":1758885174875,"trade_id":"386539878","block_trade_id":"","combo_id":"BTC-FS-25SEP26_26JUN26","combo_trade_id":"386539877","strategy":"COMBO_CALENDAR_SPREAD","direction":"sell","tick_direction":0,"amount":50000,"price":116797,"index_price":108913.27,"oi_change":50000,"open_interest":3035210,"oi_before":2985210,"maturity":"25SEP26","days_to_expiry":363.866,"basis":7883.729999999996}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOiIxNzU4ODk5MjAxMDY0IiwidHJhZGVfaWQiOiIzODY2MjA5ODgifQ=="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Trade History","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26). Either instrument_name or currency is required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL dated futures for this currency. Either currency or instrument_name is required."},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"block_only":{"default":false,"type":"boolean","description":"If true, only return trades with a block_trade_id (block trades)."},"min_amount":{"example":1,"type":"number","description":"Minimum trade amount (in contracts). Filters out dust trades."},"strategy":{"example":"calendar_spread","type":"string","description":"Filter by strategy label. Accepts comma-separated values (e.g. calendar_spread)."},"maturity":{"example":"14AUG26","type":"string","description":"Filter by maturity date (e.g. 14AUG26). Only for dated futures."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount","price"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/futures/open-interest":{"get":{"description":"Aggregates open interest across the selected instrument or currency using the requested resolution.","operationId":"Futures Open Interest","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","oi_open":559.1289933303566,"oi_high":559.7229134379199,"oi_low":559.0182983385522,"oi_close":559.6348745657242},{"date":"2025-11-04 11:01:00","oi_open":559.666130831103,"oi_high":560.0817095526673,"oi_low":559.5719114785235,"oi_close":560.0732934009276},{"date":"2025-11-04 11:02:00","oi_open":560.0728315462629,"oi_high":560.0728315462629,"oi_low":559.4456693812764,"oi_close":559.8441531321868}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Open Interest","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/ticker-history":{"get":{"description":"Returns historical ticker data for futures instruments.","operationId":"Futures Ticker History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price":109224.93,"index_price":103721.05,"bid_price":109182.5,"ask_price":109225,"bid_ask_spread":42.5,"bid_size":40000,"ask_size":40000,"oi":559.6348745657242,"volume_usd_24h":3297310,"days_to_expiry":324.9166666666667},{"date":"2025-11-04 11:01:00","mark_price":109139.43,"index_price":103641.58,"bid_price":109125,"ask_price":109135,"bid_ask_spread":10,"bid_size":3520,"ask_size":700,"oi":560.0732934009276,"volume_usd_24h":3297220,"days_to_expiry":324.91597222222225},{"date":"2025-11-04 11:02:00","mark_price":109184.1,"index_price":103686.53,"bid_price":109162.5,"ask_price":109182.5,"bid_ask_spread":20,"bid_size":4550,"ask_size":700,"oi":559.8441531321868,"volume_usd_24h":3297220,"days_to_expiry":324.91527777777776}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Ticker History","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/carry":{"get":{"description":"Returns carry/basis data (mark price minus index price) for dated futures instruments.","operationId":"Futures Carry","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1733788800000,"minute":"2024-12-10T00:00:00.000Z","basis_open":5503.88,"basis_high":5519.17,"basis_low":5497.57,"basis_close":5503.88},{"timestamp":1733788860000,"minute":"2024-12-10T00:01:00.000Z","basis_open":5503.88,"basis_high":5534.09,"basis_low":5497.65,"basis_close":5497.57}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI0LTEyLTEwIDAwOjAxOjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Carry","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/reference-price":{"get":{"description":"Returns reference price data for futures instruments.","operationId":"Futures Reference Prices","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2025-11-04 11:00:00","mark_price_open":109334.18,"mark_price_high":109355.83,"mark_price_low":109207.75,"mark_price_close":109224.93,"index_price_open":103814.31,"index_price_high":103834.66,"index_price_low":103703.62,"index_price_close":103721.05,"underlying_price":19321.37},{"date":"2025-11-04 11:01:00","mark_price_open":109218.83,"mark_price_high":109237.22,"mark_price_low":109137.79,"mark_price_close":109139.43,"index_price_open":103715.64,"index_price_high":103732.25,"index_price_low":103639.67,"index_price_close":103641.58,"underlying_price":19321.37},{"date":"2025-11-04 11:02:00","mark_price_open":109139.52,"mark_price_high":109261.87,"mark_price_low":109139.52,"mark_price_close":109184.1,"index_price_open":103641.87,"index_price_high":103755.75,"index_price_low":103641.87,"index_price_close":103686.53,"underlying_price":19321.37}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDEyOjM5OjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Reference Prices","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"}}}}}}}},"/api/v1/futures/snapshot":{"get":{"description":"Returns a snapshot of all futures instruments for a given exchange at a single minute. If no date is provided, returns the latest available snapshot. Currency is optional.","operationId":"Futures Snapshot","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"date","required":false,"in":"query","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"currency","required":false,"in":"query","description":"Base currency filter (e.g., BTC, ETH)","schema":{"example":"BTC","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"BTC-14AUG26","currency":"BTC","mark_price":109224.93,"index_price":103721.05,"bid_price":109182.5,"ask_price":109225,"bid_ask_spread":42.5,"bid_size":40000,"ask_size":40000,"oi":559.63,"volume_usd_24h":3297310,"days_to_expiry":324.92},{"date":"2025-11-04 11:00:00","exchange":"deribit","instrument_name":"ETH-14AUG26","currency":"ETH","mark_price":3212.45,"index_price":3180.12,"bid_price":3210,"ask_price":3215,"bid_ask_spread":5,"bid_size":500,"ask_size":600,"oi":12450.5,"volume_usd_24h":8540000,"days_to_expiry":143.92}],"meta":{"minute":"2025-11-04 11:00:00"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Snapshot","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"currency":{"example":"BTC","type":"string","description":"Base currency filter (e.g., BTC, ETH)"}},"required":["exchange"]}}}}}},"/api/v1/futures/liquidations":{"get":{"description":"Returns individual forced liquidation events for dated futures. Supports filtering by direction, position side, and minimum USD amount. Data available for binance, bybit, and okx exchanges.","operationId":"Futures Liquidation History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to DESC (newest/largest first).","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)","schema":{"example":"BTC-14AUG26","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by liquidation order direction (buy = short squeeze, sell = long liquidation)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"position_side","required":false,"in":"query","description":"Filter by position side being liquidated","schema":{"type":"string","enum":["long","short"]}},{"name":"min_amount_usd","required":false,"in":"query","description":"Minimum liquidation value in USD. Filters out small liquidations.","schema":{"example":1000,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount_usd","price"]}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"instrument_name":"BTCUSD_250627","timestamp":1772104946628,"date":"2026-02-26T18:22:26.628Z","exchange":"binance","currency":"BTC","direction":"sell","position_side":"long","category":"forced","price":68187.4,"amount":0.075,"amount_base":0.075,"amount_usd":5114.05,"mark_price":68187.5,"index_price":68222.5,"margin_type":"linear","maturity":"250627","days_to_expiry":121.2,"trade_id":null,"order_id":null}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NzIxMDQ5NDYwMDB9"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Futures Liquidation History","tags":["Futures"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to DESC (newest/largest first)."},"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, kraken)"},"instrument_name":{"example":"BTC-14AUG26","type":"string","description":"Full futures instrument identifier (e.g., BTC-14AUG26, ETH-14AUG26)"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by liquidation order direction (buy = short squeeze, sell = long liquidation)"},"position_side":{"type":"string","enum":["long","short"],"description":"Filter by position side being liquidated"},"min_amount_usd":{"example":1000,"type":"number","description":"Minimum liquidation value in USD. Filters out small liquidations."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount_usd","price"],"description":"Sort field. Default: timestamp."}}}}}}}},"/api/v1/options/vol-surface/by-expiry":{"get":{"description":"Returns ATM IV, 25-delta skew, and 25-delta butterfly across all real expiries for a given exchange and currency. **Snapshot mode** (default): provide `date` or omit for latest. **Time-series mode**: provide `start` and/or `end` to get paginated snapshots over time with cursor-based pagination.","operationId":"Vol Surface By Expiry","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Exact date/time for a single snapshot in ISO 8601 format (UTC). If omitted and no start/end provided, returns the latest available snapshot. Mutually exclusive with start/end.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start date for time-series mode in ISO 8601 format (UTC). When provided, returns paginated snapshots over time instead of a single snapshot.","schema":{"format":"date-time","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date for time-series mode in ISO 8601 format (UTC)","schema":{"format":"date-time","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for aggregation. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"limit","required":false,"in":"query","description":"Maximum number of distinct time buckets to return (1-1000). Only used in time-series mode (when start/end provided).","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response. Only used in time-series mode.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket (time-series mode only). ASC = oldest first (default). DESC = newest first. Keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2025-11-04T11:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"29NOV25","days_to_expiry":25.5,"underlying_price":103722.83,"atm_iv":47.62,"call_25d_iv":43.8,"put_25d_iv":52.1,"skew_25d":8.3,"butterfly_25d":0.33,"call_10d_iv":40.1,"put_10d_iv":58.3,"skew_10d":18.2,"butterfly_10d":1.58},{"date":"2025-11-04T11:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"27DEC25","days_to_expiry":53.5,"underlying_price":103722.83,"atm_iv":52.1,"call_25d_iv":48.5,"put_25d_iv":56.8,"skew_25d":8.3,"butterfly_25d":0.55,"call_10d_iv":44.2,"put_10d_iv":63.5,"skew_10d":19.3,"butterfly_10d":1.75},{"date":"2025-11-04T11:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"28MAR26","days_to_expiry":144.5,"underlying_price":103722.83,"atm_iv":55.3,"call_25d_iv":51.2,"put_25d_iv":60.1,"skew_25d":8.9,"butterfly_25d":0.35,"call_10d_iv":47.5,"put_10d_iv":66.2,"skew_10d":18.7,"butterfly_10d":1.55}],"meta":{"date":"2025-11-04T11:00:00.000Z","next_date":"2025-11-04T11:01:00.000Z"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface By Expiry","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries."},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for a single snapshot in ISO 8601 format (UTC). If omitted and no start/end provided, returns the latest available snapshot. Mutually exclusive with start/end."},"start":{"format":"date-time","type":"string","description":"Start date for time-series mode in ISO 8601 format (UTC). When provided, returns paginated snapshots over time instead of a single snapshot."},"end":{"format":"date-time","type":"string","description":"End date for time-series mode in ISO 8601 format (UTC)"},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for aggregation. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of distinct time buckets to return (1-1000). Only used in time-series mode (when start/end provided)."},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response. Only used in time-series mode."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket (time-series mode only). ASC = oldest first (default). DESC = newest first. Keep sort_dir constant within a paginated scan."}},"required":["exchange","currency"]}}}}}},"/api/v1/options/vol-surface/by-tenor":{"get":{"description":"Returns ATM IV, 25-delta skew, and 25-delta butterfly interpolated to fixed constant-maturity tenors (1d, 7d, 14d, 30d, 60d, 90d, 180d, 365d). Uses linear interpolation in total variance space. **Snapshot mode** (default): provide `date` or omit for latest. **Time-series mode**: provide `start` and/or `end` to get paginated term structures over time.","operationId":"Vol Surface By Tenor","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries.","schema":{"example":"BTC","type":"string"}},{"name":"date","required":false,"in":"query","description":"Exact date/time for a single snapshot in ISO 8601 format (UTC). If omitted and no start/end provided, returns the latest available snapshot. Mutually exclusive with start/end.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start date for time-series mode in ISO 8601 format (UTC). When provided, returns paginated snapshots over time instead of a single snapshot.","schema":{"format":"date-time","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date for time-series mode in ISO 8601 format (UTC)","schema":{"format":"date-time","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for aggregation. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"limit","required":false,"in":"query","description":"Maximum number of distinct time buckets to return (1-1000). Only used in time-series mode (when start/end provided).","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response. Only used in time-series mode.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket (time-series mode only). ASC = oldest first (default). DESC = newest first. Keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"tenor":1,"atm_iv":43.74,"call_25d_iv":41.2,"put_25d_iv":46.8,"skew_25d":5.6,"butterfly_25d":0.26,"call_10d_iv":38.5,"put_10d_iv":52.1,"skew_10d":13.6,"butterfly_10d":1.54},{"tenor":7,"atm_iv":40.43,"call_25d_iv":38.1,"put_25d_iv":43.9,"skew_25d":5.8,"butterfly_25d":0.57,"call_10d_iv":35.2,"put_10d_iv":49.3,"skew_10d":14.1,"butterfly_10d":1.82},{"tenor":14,"atm_iv":38.66,"call_25d_iv":36.5,"put_25d_iv":41.8,"skew_25d":5.3,"butterfly_25d":0.49,"call_10d_iv":33.8,"put_10d_iv":47.2,"skew_10d":13.4,"butterfly_10d":1.84},{"tenor":30,"atm_iv":38.55,"call_25d_iv":36.2,"put_25d_iv":41.9,"skew_25d":5.7,"butterfly_25d":0.5,"call_10d_iv":33.1,"put_10d_iv":48.5,"skew_10d":15.4,"butterfly_10d":2.25},{"tenor":60,"atm_iv":39.92,"call_25d_iv":37.4,"put_25d_iv":43.1,"skew_25d":5.7,"butterfly_25d":0.33,"call_10d_iv":34.5,"put_10d_iv":49.8,"skew_10d":15.3,"butterfly_10d":2.23},{"tenor":90,"atm_iv":41.3,"call_25d_iv":38.8,"put_25d_iv":44.5,"skew_25d":5.7,"butterfly_25d":0.35,"call_10d_iv":36.1,"put_10d_iv":51.2,"skew_10d":15.1,"butterfly_10d":2.35},{"tenor":180,"atm_iv":44.78,"call_25d_iv":42.1,"put_25d_iv":48.2,"skew_25d":6.1,"butterfly_25d":0.37,"call_10d_iv":39.3,"put_10d_iv":54.5,"skew_10d":15.2,"butterfly_10d":2.12},{"tenor":365,"atm_iv":47.15,"call_25d_iv":44.3,"put_25d_iv":50.8,"skew_25d":6.5,"butterfly_25d":0.4,"call_10d_iv":41.8,"put_10d_iv":57.3,"skew_10d":15.5,"butterfly_10d":2.4}],"meta":{"date":"2025-11-04T11:00:00.000Z","next_date":"2025-11-04T11:01:00.000Z"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface By Tenor","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries."},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for a single snapshot in ISO 8601 format (UTC). If omitted and no start/end provided, returns the latest available snapshot. Mutually exclusive with start/end."},"start":{"format":"date-time","type":"string","description":"Start date for time-series mode in ISO 8601 format (UTC). When provided, returns paginated snapshots over time instead of a single snapshot."},"end":{"format":"date-time","type":"string","description":"End date for time-series mode in ISO 8601 format (UTC)"},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for aggregation. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of distinct time buckets to return (1-1000). Only used in time-series mode (when start/end provided)."},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response. Only used in time-series mode."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket (time-series mode only). ASC = oldest first (default). DESC = newest first. Keep sort_dir constant within a paginated scan."}},"required":["exchange","currency"]}}}}}},"/api/v1/options/vol-surface/by-time":{"get":{"description":"Returns a paginated time-series of ATM IV, 25-delta skew, and 25-delta butterfly for the specified exchange and currency. Filter by maturity to track one expiry across time. Uses cursor-based pagination.","operationId":"Vol Surface By Time","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries.","schema":{"example":"BTC","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC)","schema":{"format":"date-time","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","type":"string"}},{"name":"maturity","required":true,"in":"query","description":"Maturity to query (e.g., 14AUG26). Required for vol-surface history due to large dataset size.","schema":{"example":"14AUG26","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for aggregation. Default 1m.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default). DESC = newest first. Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2025-11-04T10:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"29NOV25","days_to_expiry":25.54,"underlying_price":103500,"atm_iv":47.2,"call_25d_iv":43.5,"put_25d_iv":51.8,"skew_25d":8.3,"butterfly_25d":0.45,"call_10d_iv":39.8,"put_10d_iv":58.1,"skew_10d":18.3,"butterfly_10d":1.7},{"date":"2025-11-04T10:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"27DEC25","days_to_expiry":53.54,"underlying_price":103500,"atm_iv":51.9,"call_25d_iv":48.2,"put_25d_iv":56.5,"skew_25d":8.3,"butterfly_25d":0.45,"call_10d_iv":44.5,"put_10d_iv":63.2,"skew_10d":18.7,"butterfly_10d":1.75},{"date":"2025-11-04T11:00:00.000Z","exchange":"deribit","currency":"BTC","maturity":"29NOV25","days_to_expiry":25.5,"underlying_price":103722.83,"atm_iv":47.62,"call_25d_iv":43.8,"put_25d_iv":52.1,"skew_25d":8.3,"butterfly_25d":0.33,"call_10d_iv":40.1,"put_10d_iv":58.3,"skew_10d":18.2,"butterfly_10d":1.58}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI1LTExLTA0IDExOjAwOjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface By Time","tags":["Options"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx, bybit, bullish, derive). Required."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH). Required for vol-surface queries."},"start":{"format":"date-time","type":"string","description":"Start date in ISO 8601 format (UTC)"},"end":{"format":"date-time","type":"string","description":"End date in ISO 8601 format (UTC)"},"maturity":{"example":"14AUG26","type":"string","description":"Maturity to query (e.g., 14AUG26). Required for vol-surface history due to large dataset size."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for aggregation. Default 1m."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default). DESC = newest first. Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."}},"required":["exchange","currency","maturity"]}}}}}},"/api/v1/spot/catalog":{"get":{"description":"Returns a list of available spot instruments.","operationId":"Spot Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency filter (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency filter (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":[{"instrument_name":"BTCUSDT","exchange":"binance","currency":"BTC","quote_currency":"USDT"},{"instrument_name":"ETHUSDT","exchange":"binance","currency":"ETH","quote_currency":"USDT"},{"instrument_name":"BTC-USD","exchange":"coinbase","currency":"BTC","quote_currency":"USD"}]}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Catalog","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"currency":{"example":"BTC","type":"string","description":"Base currency filter (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency filter (e.g., USDT, USDC, USD)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."}}}}}}}},"/api/v1/spot/metadata":{"get":{"description":"Returns metadata for a specific spot instrument including data availability, total record count, and pagination information.","operationId":"Spot Metadata","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD)","schema":{"example":"BTCUSDT","type":"string"}}],"responses":{"200":{"description":"Metadata successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponseEntity"}}}},"400":{"description":"Bad Request - Invalid parameters or no data found","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Metadata","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD)"}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/spot/ohlcvt":{"get":{"description":"Retrieves Open, High, Low, Close, Volume, and Trade statistics for spot instruments.\n\n**Key Features:**\n- Historical trade-based OHLC candlestick data\n- Buy/sell volume breakdown (base and quote currency)\n- Trade count statistics\n- VWAP (Volume Weighted Average Price)\n- Support for multiple resolutions (1m, 5m, 1h, 1d)","operationId":"Spot OHLCVT Market Data","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"description":"OHLCVT data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/SpotOhlcvtEntity"}}}}]},"example":{"data":[{"date":"2026-03-06 12:00:00","open":90125.5,"high":90340.75,"low":89980.25,"close":90210,"vwap":90150.3,"volume":45.82,"buy_volume":25.5,"sell_volume":20.32,"quote_volume":4130280,"buy_quote_volume":2298825,"sell_quote_volume":1831455,"trades_count":312,"buy_trades_count":175,"sell_trades_count":137,"first_trade_id":"3847291001","last_trade_id":"3847291312","data_source":"rest","quote_currency":"USDT"},{"date":"2026-03-06 12:01:00","open":90210,"high":90415,"low":90150,"close":90380.5,"vwap":90285.2,"volume":38.15,"buy_volume":22.1,"sell_volume":16.05,"quote_volume":3444382,"buy_quote_volume":1995303,"sell_quote_volume":1449079,"trades_count":248,"buy_trades_count":140,"sell_trades_count":108,"first_trade_id":"3847291313","last_trade_id":"3847291560","data_source":"rest","quote_currency":"USDT"},{"date":"2026-03-06 12:02:00","open":90380.5,"high":90425,"low":90200,"close":90275,"vwap":90310.8,"volume":29.63,"buy_volume":14.2,"sell_volume":15.43,"quote_volume":2675507,"buy_quote_volume":1282413,"sell_quote_volume":1393094,"trades_count":195,"buy_trades_count":92,"sell_trades_count":103,"first_trade_id":"3847291561","last_trade_id":"3847291755","data_source":"rest","quote_currency":"USDT"}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAzLTA2IDEyOjAzOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot OHLCVT Market Data","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/spot/ticker":{"get":{"description":"Returns historical ticker data for spot instruments including bid/ask prices, spreads, sizes, and 24h rolling statistics.","operationId":"Spot Ticker History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-03-06 12:00:00","last_price_open":90125.5,"last_price_high":90340.75,"last_price_low":89980.25,"last_price_close":90210,"bid_price_open":90124,"bid_price_high":90339,"bid_price_low":89979,"bid_price_close":90209,"ask_price_open":90126,"ask_price_high":90341,"ask_price_low":89981,"ask_price_close":90211,"bid_ask_spread_open":2,"bid_ask_spread_high":5,"bid_ask_spread_low":0.5,"bid_ask_spread_close":2,"bid_ask_spread_avg":1.8,"bid_size_open":0.5,"bid_size_high":2,"bid_size_low":0.1,"bid_size_close":0.8,"bid_size_avg":0.6,"ask_size_open":0.4,"ask_size_high":1.5,"ask_size_low":0.05,"ask_size_close":0.7,"ask_size_avg":0.5,"total_liquidity_open":0.9,"total_liquidity_high":3.5,"total_liquidity_low":0.15,"total_liquidity_close":1.5,"total_liquidity_avg":1.1,"volume_24h":15230.5,"quote_volume_24h":1373250000,"high_24h":91200,"low_24h":88500,"price_change_24h_pct":2.35,"ticker_updates_count":1200,"quote_updates_count":800,"spread_stability_ratio":0.95,"quote_currency":"USDT"},{"date":"2026-03-06 12:01:00","last_price_open":90210,"last_price_high":90415,"last_price_low":90150,"last_price_close":90380.5,"bid_price_open":90209,"bid_price_high":90414,"bid_price_low":90149,"bid_price_close":90379,"ask_price_open":90211,"ask_price_high":90416,"ask_price_low":90151,"ask_price_close":90381,"bid_ask_spread_open":2,"bid_ask_spread_high":4,"bid_ask_spread_low":1,"bid_ask_spread_close":2,"bid_ask_spread_avg":1.9,"bid_size_open":0.8,"bid_size_high":1.8,"bid_size_low":0.2,"bid_size_close":0.6,"bid_size_avg":0.7,"ask_size_open":0.7,"ask_size_high":1.2,"ask_size_low":0.1,"ask_size_close":0.5,"ask_size_avg":0.55,"total_liquidity_open":1.5,"total_liquidity_high":3,"total_liquidity_low":0.3,"total_liquidity_close":1.1,"total_liquidity_avg":1.25,"volume_24h":15245.2,"quote_volume_24h":1374580000,"high_24h":91200,"low_24h":88500,"price_change_24h_pct":2.38,"ticker_updates_count":1150,"quote_updates_count":780,"spread_stability_ratio":0.94,"quote_currency":"USDT"}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAzLTA2IDEyOjAyOjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Ticker History","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/spot/trades":{"get":{"description":"Returns spot trades with full trade details. Supports two modes: (1) instrument mode — provide instrument_name for a single spot pair, (2) currency mode — provide currency (e.g. BTC) for ALL spot trades across all pairs. Additional filters: direction, min_amount, min_quote_amount, sort, sort_dir. Use top_n for quick top-trades scanning.","operationId":"Spot Trade History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT). Either instrument_name or currency is recommended.","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL spot pairs for this currency. Either currency or instrument_name is recommended.","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}},{"name":"direction","required":false,"in":"query","description":"Filter by trade direction (aggressor side)","schema":{"type":"string","enum":["buy","sell"]}},{"name":"min_amount","required":false,"in":"query","description":"Minimum trade amount (in base currency). Filters out dust trades.","schema":{"example":0.01,"type":"number"}},{"name":"min_quote_amount","required":false,"in":"query","description":"Minimum trade value in quote currency. Filters out small trades.","schema":{"example":100,"type":"number"}},{"name":"sort","required":false,"in":"query","description":"Sort field. Default: timestamp.","schema":{"default":"timestamp","type":"string","enum":["timestamp","amount","price","quote_amount"]}},{"name":"top_n","required":false,"in":"query","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned.","schema":{"example":20,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1772885400123,"date":"2026-03-06T12:30:00.123Z","trade_id":"3847291001","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","direction":"buy","amount":0.125,"price":90250.5,"quote_amount":11281.31,"bid_price":90249,"ask_price":90251,"bid_size":0.5,"ask_size":0.4},{"timestamp":1772885401456,"date":"2026-03-06T12:30:01.456Z","trade_id":"3847291002","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","direction":"sell","amount":0.05,"price":90248,"quote_amount":4512.4,"bid_price":90247,"ask_price":90249,"bid_size":0.3,"ask_size":0.6},{"timestamp":1772885402789,"date":"2026-03-06T12:30:02.789Z","trade_id":"3847291003","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","direction":"buy","amount":1.5,"price":90255,"quote_amount":135382.5,"bid_price":90254,"ask_price":90256,"bid_size":0.8,"ask_size":0.3}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOiIxNzcyODg1NDAyNzg5IiwidHJhZGVfaWQiOiIzODQ3MjkxMDAzIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Trade History","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction. Defaults to ASC for instrument mode, DESC for currency mode."},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT). Either instrument_name or currency is recommended."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, ETH). Returns trades across ALL spot pairs for this currency. Either currency or instrument_name is recommended."},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"},"direction":{"type":"string","enum":["buy","sell"],"description":"Filter by trade direction (aggressor side)"},"min_amount":{"example":0.01,"type":"number","description":"Minimum trade amount (in base currency). Filters out dust trades."},"min_quote_amount":{"example":100,"type":"number","description":"Minimum trade value in quote currency. Filters out small trades."},"sort":{"default":"timestamp","type":"string","enum":["timestamp","amount","price","quote_amount"],"description":"Sort field. Default: timestamp."},"top_n":{"example":20,"type":"number","description":"Return top N trades by the sort field (DESC). Overrides limit and sort_dir. No pagination cursor returned."}}}}}}}},"/api/v1/spot/volume":{"get":{"description":"Returns volume metrics for spot instruments including 24h rolling volume, buy/sell breakdown in both base and quote currency, and trade counts.","operationId":"Spot Volume Stats","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"description":"Successfully retrieved spot volume data","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-03-06 12:00:00","volume_24h":15230.5,"quote_volume_24h":1373250000,"buy_volume":25.5,"sell_volume":20.32,"volume":45.82,"buy_quote_volume":2298825,"sell_quote_volume":1831455,"quote_volume":4130280,"buy_trades_count":175,"sell_trades_count":137,"trades_count":312,"quote_currency":"USDT"},{"date":"2026-03-06 12:01:00","volume_24h":15245.2,"quote_volume_24h":1374580000,"buy_volume":22.1,"sell_volume":16.05,"volume":38.15,"buy_quote_volume":1995303,"sell_quote_volume":1449079,"quote_volume":3444382,"buy_trades_count":140,"sell_trades_count":108,"trades_count":248,"quote_currency":"USDT"},{"date":"2026-03-06 12:02:00","volume_24h":15260.8,"quote_volume_24h":1375920000,"buy_volume":14.2,"sell_volume":15.43,"volume":29.63,"buy_quote_volume":1282413,"sell_quote_volume":1393094,"quote_volume":2675507,"buy_trades_count":92,"sell_trades_count":103,"trades_count":195,"quote_currency":"USDT"}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAzLTA2IDEyOjAzOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Volume Stats","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/spot/snapshot":{"get":{"description":"Returns a snapshot of all spot instruments for a given exchange at a single minute. If no date is provided, returns the latest available snapshot. Currency and quote currency are optional filters.","operationId":"Spot Snapshot","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency filter (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency filter (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}},{"name":"date","required":false,"in":"query","description":"Snapshot date (ISO 8601 format). Defaults to latest available.","schema":{"example":"2025-01-15","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for the snapshot data","schema":{"default":"1d","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2026-03-06 12:00:00","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","last_price":90210,"bid_price":90209,"ask_price":90211,"bid_ask_spread":2,"bid_size":0.8,"ask_size":0.7,"volume_24h":15230.5,"quote_volume_24h":1373250000,"high_24h":91200,"low_24h":88500,"price_change_24h_pct":2.35},{"date":"2026-03-06 12:00:00","exchange":"binance","instrument_name":"ETHUSDT","currency":"ETH","quote_currency":"USDT","last_price":3450.25,"bid_price":3450,"ask_price":3450.5,"bid_ask_spread":0.5,"bid_size":5.2,"ask_size":4.8,"volume_24h":185000.5,"quote_volume_24h":638252000,"high_24h":3520,"low_24h":3380,"price_change_24h_pct":1.82}],"meta":{"minute":"2026-03-06 12:00:00"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Snapshot","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"currency":{"example":"BTC","type":"string","description":"Base currency filter (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency filter (e.g., USDT, USDC, USD)"},"date":{"example":"2025-01-15","type":"string","description":"Snapshot date (ISO 8601 format). Defaults to latest available."},"resolution":{"default":"1d","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for the snapshot data"}},"required":["exchange"]}}}}}},"/api/v1/spot/level1":{"get":{"description":"Returns level 1 order book data for spot instruments including top-of-book bid/ask prices, sizes, spreads, and liquidity metrics.","operationId":"Spot Level 1","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-03-06 12:00:00","last_price_open":90125.5,"last_price_high":90340.75,"last_price_low":89980.25,"last_price_close":90210,"bid_price_open":90124,"bid_price_high":90339,"bid_price_low":89979,"bid_price_close":90209,"ask_price_open":90126,"ask_price_high":90341,"ask_price_low":89981,"ask_price_close":90211,"bid_ask_spread_open":2,"bid_ask_spread_high":5,"bid_ask_spread_low":0.5,"bid_ask_spread_close":2,"bid_ask_spread_avg":1.8,"bid_size_open":0.5,"bid_size_high":2,"bid_size_low":0.1,"bid_size_close":0.8,"bid_size_avg":0.6,"ask_size_open":0.4,"ask_size_high":1.5,"ask_size_low":0.05,"ask_size_close":0.7,"ask_size_avg":0.5,"total_liquidity_open":0.9,"total_liquidity_high":3.5,"total_liquidity_low":0.15,"total_liquidity_close":1.5,"total_liquidity_avg":1.1,"volume_24h":15230.5,"quote_volume_24h":1373250000,"high_24h":91200,"low_24h":88500,"price_change_24h_pct":2.35,"ticker_updates_count":1200,"quote_updates_count":800,"spread_stability_ratio":0.95,"quote_currency":"USDT"}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAzLTA2IDEyOjAxOjAwIn0="}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot Level 1","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/spot/l2-orderbook":{"get":{"description":"Returns aggregated L2 orderbook depth metrics for spot instruments.\n\n**Key Features:**\n- Bid/ask liquidity at 4 depth levels (10, 20, 50, 100 levels)\n- Order book imbalance metrics (OHLC + average) per depth\n- Microprice (liquidity-weighted mid-price)\n- Snapshot count per time bucket\n- Support for multiple resolutions (1m, 5m, 15m, 1h, 4h, 1d)","operationId":"Spot L2 Orderbook","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"description":"L2 orderbook data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"date":"2026-03-06 12:00:00","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","bid_liq_10_open":0.301,"bid_liq_10_high":0.55,"bid_liq_10_low":0.15,"bid_liq_10_close":0.42,"bid_liq_10_avg":0.35,"bid_liq_20_open":0.359,"bid_liq_20_high":0.8,"bid_liq_20_low":0.2,"bid_liq_20_close":0.5,"bid_liq_20_avg":0.45,"bid_liq_50_open":7.831,"bid_liq_50_high":10.5,"bid_liq_50_low":5.2,"bid_liq_50_close":8.1,"bid_liq_50_avg":7.5,"bid_liq_100_open":12.891,"bid_liq_100_high":18,"bid_liq_100_low":9,"bid_liq_100_close":14.5,"bid_liq_100_avg":13.2,"ask_liq_10_open":5.375,"ask_liq_10_high":6.2,"ask_liq_10_low":4.1,"ask_liq_10_close":5.1,"ask_liq_10_avg":5,"ask_liq_20_open":6.398,"ask_liq_20_high":8,"ask_liq_20_low":4.5,"ask_liq_20_close":6,"ask_liq_20_avg":5.8,"ask_liq_50_open":18.966,"ask_liq_50_high":22,"ask_liq_50_low":15,"ask_liq_50_close":19.5,"ask_liq_50_avg":18.2,"ask_liq_100_open":40.834,"ask_liq_100_high":50,"ask_liq_100_low":30,"ask_liq_100_close":42,"ask_liq_100_avg":39.5,"imbalance_10_open":-0.894,"imbalance_10_high":-0.5,"imbalance_10_low":-0.95,"imbalance_10_close":-0.82,"imbalance_10_avg":-0.78,"imbalance_20_open":-0.894,"imbalance_20_high":-0.5,"imbalance_20_low":-0.95,"imbalance_20_close":-0.82,"imbalance_20_avg":-0.78,"imbalance_50_open":-0.416,"imbalance_50_high":-0.1,"imbalance_50_low":-0.6,"imbalance_50_close":-0.35,"imbalance_50_avg":-0.38,"imbalance_100_open":-0.52,"imbalance_100_high":-0.2,"imbalance_100_low":-0.7,"imbalance_100_close":-0.45,"imbalance_100_avg":-0.48,"microprice_open":90125.9,"microprice_high":90340,"microprice_low":89980,"microprice_close":90210.5,"microprice_avg":90165.2,"snapshot_count":60}],"meta":{"next_cursor":"eyJtaW51dGUiOiIyMDI2LTAzLTA2IDEyOjAxOjAwIn0="}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot L2 Orderbook","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/spot/l2-orderbook-raw":{"get":{"description":"Returns raw L2 orderbook snapshots for spot instruments with full bid/ask arrays.\n\n**Key Features:**\n- Full bid/ask price levels (up to 100 levels each)\n- Pre-computed liquidity at 4 depth levels (10, 20, 50, 100)\n- Order book imbalance per depth\n- Microprice (liquidity-weighted mid-price)\n- Individual snapshots (not aggregated) — 30-day data retention","operationId":"Spot L2 Orderbook Raw","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (e.g., binance, coinbase, bybit, okx)","schema":{"example":"binance","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)","schema":{"example":"BTCUSDT","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Quote currency (e.g., USDT, USDC, USD)","schema":{"example":"USDT","type":"string"}}],"responses":{"200":{"description":"Raw L2 orderbook snapshots successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array"}}}]},"example":{"data":[{"timestamp":1772885400123,"date":"2026-03-06T12:30:00.123Z","exchange":"binance","instrument_name":"BTCUSDT","currency":"BTC","quote_currency":"USDT","depth":100,"bids":[{"price":90209,"size":0.169},{"price":90208.5,"size":0.002}],"asks":[{"price":90211,"size":3.085},{"price":90211.5,"size":0.002}],"bid_liquidity_10":0.301,"ask_liquidity_10":5.375,"bid_liquidity_20":0.359,"ask_liquidity_20":6.398,"bid_liquidity_50":7.831,"ask_liquidity_50":18.966,"bid_liquidity_100":12.891,"ask_liquidity_100":40.834,"imbalance_10":-0.894,"imbalance_20":-0.894,"imbalance_50":-0.416,"imbalance_100":-0.52,"microprice":90210.905}],"meta":{"next_cursor":"eyJ0aW1lc3RhbXAiOjE3NzI4ODU0MDAxMjN9"}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Spot L2 Orderbook Raw Snapshots","tags":["Spot"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"example":"binance","type":"string","description":"Exchange name (e.g., binance, coinbase, bybit, okx)"},"instrument_name":{"example":"BTCUSDT","type":"string","description":"Full spot instrument identifier (e.g., BTCUSDT, BTC-USD, BTC-USDT)"},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USDT","type":"string","description":"Quote currency (e.g., USDT, USDC, USD)"}},"required":["instrument_name"]}}}}}},"/api/v1/analytics/realized-volatility":{"get":{"description":"Returns annualised realised volatility metrics (rv_annualized expressed as a percentage, e.g. 38.76 = 38.76%) from precomputed cross-asset analytics. Snapshot mode is used when start/end are omitted; historical mode is used when start and/or end are provided. If frequency, window_days, and estimator are omitted, all available variants for the requested instrument are returned.","operationId":"getRealizedVolatility","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name. Required. Case-insensitive. Example data includes Deribit, Binance, and Hyperliquid instruments.","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full instrument identifier. Required. Case-insensitive.","schema":{"example":"BTC-PERPETUAL","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency filter. Case-insensitive.","schema":{"example":"BTC","type":"string"}},{"name":"frequency","required":false,"in":"query","description":"Sampling frequency used to compute realised volatility.","schema":{"example":"daily","type":"string","enum":["daily","hourly"]}},{"name":"window_days","required":false,"in":"query","description":"Realised volatility lookback window in days.","schema":{"minimum":1,"example":30,"type":"number","enum":[7,30,60,90,180,365]}},{"name":"estimator","required":false,"in":"query","description":"Realised volatility estimator filter.","schema":{"example":"close_to_close","type":"string","enum":["close_to_close","parkinson","garman_klass"]}},{"name":"date","required":false,"in":"query","description":"Snapshot point-in-time in ISO 8601 format (UTC). If omitted in snapshot mode, returns latest rows.","schema":{"format":"date-time","example":"2026-04-27T12:35:30Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Providing start or end enables historical mode.","schema":{"format":"date-time","example":"2026-04-27T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC). Providing start or end enables historical mode.","schema":{"format":"date-time","example":"2026-04-28T00:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of historical records to return (1-1000). Ignored in snapshot mode.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next historical page. Use meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by ts (historical mode only). ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}}],"responses":{"200":{"description":"Realised volatility data successfully retrieved","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/PaginatedResponse"},{"properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/RealizedVolatilityEntity"}}}}]},"example":{"data":[{"date":"2026-04-27T12:35:30.000Z","exchange":"deribit","currency":"BTC","instrument_name":"BTC-PERPETUAL","frequency":"daily","window_days":30,"estimator":"close_to_close","rv_annualized":35.73,"sample_count":30},{"date":"2026-04-27T12:35:30.000Z","exchange":"deribit","currency":"BTC","instrument_name":"BTC-PERPETUAL","frequency":"daily","window_days":30,"estimator":"parkinson","rv_annualized":39.11,"sample_count":30},{"date":"2026-04-27T12:35:30.000Z","exchange":"deribit","currency":"BTC","instrument_name":"BTC-PERPETUAL","frequency":"daily","window_days":30,"estimator":"garman_klass","rv_annualized":39.85,"sample_count":30}],"meta":{"next_cursor":null}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Realized Volatility","tags":["Analytics"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name. Required. Case-insensitive. Example data includes Deribit, Binance, and Hyperliquid instruments."},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument identifier. Required. Case-insensitive."},"currency":{"example":"BTC","type":"string","description":"Base currency filter. Case-insensitive."},"frequency":{"example":"daily","type":"string","enum":["daily","hourly"],"description":"Sampling frequency used to compute realised volatility."},"window_days":{"minimum":1,"example":30,"type":"number","enum":[7,30,60,90,180,365],"description":"Realised volatility lookback window in days."},"estimator":{"example":"close_to_close","type":"string","enum":["close_to_close","parkinson","garman_klass"],"description":"Realised volatility estimator filter."},"date":{"format":"date-time","example":"2026-04-27T12:35:30Z","type":"string","description":"Snapshot point-in-time in ISO 8601 format (UTC). If omitted in snapshot mode, returns latest rows."},"start":{"format":"date-time","example":"2026-04-27T00:00:00Z","type":"string","description":"Start date in ISO 8601 format (UTC). Providing start or end enables historical mode."},"end":{"format":"date-time","example":"2026-04-28T00:00:00Z","type":"string","description":"End date in ISO 8601 format (UTC). Providing start or end enables historical mode."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of historical records to return (1-1000). Ignored in snapshot mode."},"cursor":{"type":"string","description":"Pagination cursor for fetching the next historical page. Use meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by ts (historical mode only). ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/instruments":{"get":{"description":"Returns a paginated list of instrument contract specifications across all exchanges and market types. Filter by exchange, market_type, base_currency, quote_currency, status, margin_type, option_type, expiry range, or partial instrument name match. Returns contract reference data including tick size, lot size, leverage, expiry, etc.","operationId":"getInstruments","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, bullish, nado, coinbase)","schema":{"example":"deribit","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Filter by market type","schema":{"example":"perpetual","type":"string","enum":["spot","perpetual","future","option"]}},{"name":"base_currency","required":false,"in":"query","description":"Filter by base currency (e.g., BTC, ETH, SOL)","schema":{"example":"BTC","type":"string"}},{"name":"quote_currency","required":false,"in":"query","description":"Filter by quote currency (e.g., USD, USDT, USDC)","schema":{"example":"USD","type":"string"}},{"name":"status","required":false,"in":"query","description":"Filter by instrument status. Default 'active'. Pass 'all' to include all statuses.","schema":{"default":"active","example":"active","type":"string","enum":["active","expired","delisted","suspended","all"]}},{"name":"instrument_name","required":false,"in":"query","description":"Filter by instrument name (partial match, case-insensitive)","schema":{"example":"BTC","type":"string"}},{"name":"margin_type","required":false,"in":"query","description":"Filter by margin type: linear or inverse","schema":{"example":"linear","type":"string"}},{"name":"option_type","required":false,"in":"query","description":"Filter by option type: call or put","schema":{"example":"call","type":"string"}},{"name":"asset_class","required":false,"in":"query","description":"Filter by asset class. Defaults to all classes. Use \"equity\"/\"commodity\"/\"forex\"/\"index\" to scope to non-crypto perps (NVDA/TSLA equity perps, GOLD/OIL commodity perps, EURUSD FX perps, etc.).","schema":{"example":"equity","type":"string","enum":["crypto","equity","commodity","forex","index"]}},{"name":"sub_exchange","required":false,"in":"query","description":"Filter by sub-venue. Used for Hyperliquid HIP-3 deployers: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges (binance/bybit/okx/kraken/etc.).","schema":{"example":"xyz","type":"string"}},{"name":"expiry_from","required":false,"in":"query","description":"Filter instruments with expiry_date >= this value (ISO 8601 datetime)","schema":{"example":"2026-01-01T00:00:00Z","type":"string"}},{"name":"expiry_to","required":false,"in":"query","description":"Filter instruments with expiry_date <= this value (ISO 8601 datetime)","schema":{"example":"2026-12-31T23:59:59Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in next_cursor from the previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated list of instrument metadata","content":{"application/json":{"example":{"data":[{"exchange":"deribit","instrument_name":"BTC-PERPETUAL","market_type":"perpetual","base_currency":"BTC","quote_currency":"USD","settlement_currency":"BTC","margin_type":"inverse","contract_multiplier":1,"contract_value":10,"contract_value_currency":"USD","tick_size":0.5,"lot_size":1,"min_order_size":1,"option_type":"","exercise_style":"","strike":null,"expiry_date":null,"contract_cycle":"","funding_interval_hours":8,"delivery_date":null,"underlying_index":"btc_usd","max_leverage":50,"price_precision":1,"quantity_precision":0,"sub_exchange":"","asset_class":"crypto","max_position_notional":null,"status":"active","listing_date":"2020-01-01T00:00:00.000Z","updated_at":"2026-04-02T12:00:00.000Z","created_at":"2020-01-01T00:00:00.000Z"}],"meta":{"next_cursor":"eyJvZmZzZXQiOjEwMH0=","total":15000,"count":1}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"List Instruments","tags":["Instruments"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Filter by exchange (e.g., deribit, binance, okx, bybit, hyperliquid, kraken, bullish, nado, coinbase)"},"market_type":{"example":"perpetual","type":"string","enum":["spot","perpetual","future","option"],"description":"Filter by market type"},"base_currency":{"example":"BTC","type":"string","description":"Filter by base currency (e.g., BTC, ETH, SOL)"},"quote_currency":{"example":"USD","type":"string","description":"Filter by quote currency (e.g., USD, USDT, USDC)"},"status":{"default":"active","example":"active","type":"string","enum":["active","expired","delisted","suspended","all"],"description":"Filter by instrument status. Default 'active'. Pass 'all' to include all statuses."},"instrument_name":{"example":"BTC","type":"string","description":"Filter by instrument name (partial match, case-insensitive)"},"margin_type":{"example":"linear","type":"string","description":"Filter by margin type: linear or inverse"},"option_type":{"example":"call","type":"string","description":"Filter by option type: call or put"},"asset_class":{"example":"equity","type":"string","enum":["crypto","equity","commodity","forex","index"],"description":"Filter by asset class. Defaults to all classes. Use \"equity\"/\"commodity\"/\"forex\"/\"index\" to scope to non-crypto perps (NVDA/TSLA equity perps, GOLD/OIL commodity perps, EURUSD FX perps, etc.)."},"sub_exchange":{"example":"xyz","type":"string","description":"Filter by sub-venue. Used for Hyperliquid HIP-3 deployers: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges (binance/bybit/okx/kraken/etc.)."},"expiry_from":{"example":"2026-01-01T00:00:00Z","type":"string","description":"Filter instruments with expiry_date >= this value (ISO 8601 datetime)"},"expiry_to":{"example":"2026-12-31T23:59:59Z","type":"string","description":"Filter instruments with expiry_date <= this value (ISO 8601 datetime)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in next_cursor from the previous response."}}}}}}}},"/api/v1/instruments/detail":{"get":{"description":"Returns the full contract specification for a single instrument, including the raw exchange API data. Use this to get complete reference data for a specific instrument.","operationId":"getInstrumentDetail","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name (e.g., deribit, binance, okx)","schema":{"example":"deribit","type":"string"}},{"name":"instrument_name","required":true,"in":"query","description":"Full instrument name (e.g., BTC-PERPETUAL, BTCUSDT, BTC-25SEP26-84000-C)","schema":{"example":"BTC-PERPETUAL","type":"string"}}],"responses":{"200":{"description":"Full instrument metadata including raw exchange data","content":{"application/json":{"example":{"data":{"exchange":"deribit","instrument_name":"BTC-PERPETUAL","market_type":"perpetual","base_currency":"BTC","quote_currency":"USD","settlement_currency":"BTC","margin_type":"inverse","contract_multiplier":1,"contract_value":10,"contract_value_currency":"USD","tick_size":0.5,"lot_size":1,"min_order_size":1,"option_type":"","exercise_style":"","strike":null,"expiry_date":null,"contract_cycle":"","funding_interval_hours":8,"delivery_date":null,"underlying_index":"btc_usd","max_leverage":50,"price_precision":1,"quantity_precision":0,"sub_exchange":"","asset_class":"crypto","max_position_notional":null,"status":"active","listing_date":"2020-01-01T00:00:00.000Z","updated_at":"2026-04-02T12:00:00.000Z","created_at":"2020-01-01T00:00:00.000Z","raw_data":"{\"instrument_name\":\"BTC-PERPETUAL\",\"kind\":\"future\",...}"},"meta":{}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"404":{"description":"Not Found - Instrument not found","content":{"application/json":{"example":{"statusCode":404,"message":"No instrument found for NONEXISTENT on exchange deribit","error":"Not Found"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Instrument Detail","tags":["Instruments"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name (e.g., deribit, binance, okx)"},"instrument_name":{"example":"BTC-PERPETUAL","type":"string","description":"Full instrument name (e.g., BTC-PERPETUAL, BTCUSDT, BTC-25SEP26-84000-C)"}},"required":["exchange","instrument_name"]}}}}}},"/api/v1/macro/catalog":{"get":{"description":"Discovery endpoint for non-crypto perpetuals: equity perps (NVDA, TSLA, MSTR, AAPL, …), commodity perps (GOLD, SILVER, OIL/CL, NATGAS, …), FX perps (EURUSD, GBPUSD, JPYUSD, …) and the small index segment. Returns full contract specs (tick_size, lot_size, max_leverage, funding_interval_hours, …).\n\nOnce you have an instrument_name + exchange, pull time-series data from the existing /api/v1/perpetuals/* endpoints — the routes are identical for crypto and macro perps:\n\n| Data | Route |\n|---|---|\n| OHLCVT candles (open/high/low/close/volume/trades) | `GET /api/v1/perpetuals/ohlcvt` |\n| Ticker history (mark/index/bid/ask/OI/spread) | `GET /api/v1/perpetuals/ticker-history` |\n| **Funding rate, basis, annualized carry** | `GET /api/v1/perpetuals/carry` |\n| Open interest history | `GET /api/v1/perpetuals/open-interest` |\n| Volume aggregates | `GET /api/v1/perpetuals/volume` |\n| L1 book (best bid/ask) | `GET /api/v1/perpetuals/level1` |\n| L2 orderbook (depth) | `GET /api/v1/perpetuals/orderbook` |\n| Liquidations | `GET /api/v1/perpetuals/liquidations` |\n| Snapshot (latest tick across all instruments) | `GET /api/v1/perpetuals/snapshot` |\n| Reference price | `GET /api/v1/perpetuals/reference-price` |\n| Individual trades (sparse on most macro venues) | `GET /api/v1/perpetuals/trades` |\n\nNote: funding rate lives on `/perpetuals/carry` (alongside basis and annualized carry — these three move together for perp analysis), not on a standalone `/funding` route. The MCP equivalent tool is `get_perpetuals_funding`.","operationId":"getMacroCatalog","parameters":[{"name":"asset_class","required":false,"in":"query","description":"Restrict to a single asset class. Defaults to all non-crypto (equity, commodity, forex, index).","schema":{"example":"equity","type":"string","enum":["equity","commodity","forex","index","crypto"]}},{"name":"market_type","required":false,"in":"query","description":"Restrict to one market_type. Defaults to perpetual (the dominant macro segment).","schema":{"default":"perpetual","example":"perpetual","type":"string","enum":["perpetual","future","spot"]}},{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (binance, bybit, hyperliquid, kraken, okx, nado).","schema":{"example":"hyperliquid","type":"string"}},{"name":"sub_exchange","required":false,"in":"query","description":"Hyperliquid HIP-3 sub-venue: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges.","schema":{"example":"xyz","type":"string"}},{"name":"base_currency","required":false,"in":"query","description":"Filter by base currency / underlying ticker (NVDA, TSLA, GOLD, EUR, ...)","schema":{"example":"NVDA","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Partial, case-insensitive instrument-name match (e.g. \"NVDA\" finds xyz:NVDA-USD and PF_NVDAXUSD).","schema":{"example":"NVDA","type":"string"}},{"name":"status","required":false,"in":"query","description":"Instrument status. Default \"active\". Pass \"all\" to include expired/delisted/suspended.","schema":{"default":"active","type":"string","enum":["active","expired","delisted","suspended","all"]}},{"name":"limit","required":false,"in":"query","description":"Records per page (1-1000)","schema":{"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response.","schema":{"type":"string"}}],"responses":{"200":{"description":"Paginated catalog of macro instruments"},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Macro Catalog","tags":["Macro"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asset_class":{"example":"equity","type":"string","enum":["equity","commodity","forex","index","crypto"],"description":"Restrict to a single asset class. Defaults to all non-crypto (equity, commodity, forex, index)."},"market_type":{"default":"perpetual","example":"perpetual","type":"string","enum":["perpetual","future","spot"],"description":"Restrict to one market_type. Defaults to perpetual (the dominant macro segment)."},"exchange":{"example":"hyperliquid","type":"string","description":"Filter by exchange (binance, bybit, hyperliquid, kraken, okx, nado)."},"sub_exchange":{"example":"xyz","type":"string","description":"Hyperliquid HIP-3 sub-venue: xyz, flx, km, cash, vntl, hyna. Empty string matches single-venue exchanges."},"base_currency":{"example":"NVDA","type":"string","description":"Filter by base currency / underlying ticker (NVDA, TSLA, GOLD, EUR, ...)"},"instrument_name":{"example":"NVDA","type":"string","description":"Partial, case-insensitive instrument-name match (e.g. \"NVDA\" finds xyz:NVDA-USD and PF_NVDAXUSD)."},"status":{"default":"active","type":"string","enum":["active","expired","delisted","suspended","all"],"description":"Instrument status. Default \"active\". Pass \"all\" to include expired/delisted/suspended."},"limit":{"default":100,"example":100,"type":"number","description":"Records per page (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor from a previous response."}}}}}}}},"/api/v1/macro/asset-classes":{"get":{"description":"Returns the four supported non-crypto asset classes (equity, commodity, forex, index) with active-instrument counts per market type and a few example tickers. Cheap dashboard endpoint.","operationId":"getMacroAssetClasses","parameters":[],"responses":{"200":{"description":"Asset class summary"},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Macro Asset Classes","tags":["Macro"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/macro/venues":{"get":{"description":"Per-asset-class venue breakdown. Returns each (asset_class, exchange, sub_exchange, market_type) tuple with active instrument counts. Perpetuals and dated futures appear as separate rows so OKX/Bybit gold weeklies (market_type=future) don't get folded in with their perp counts. Filter by market_type to scope.","operationId":"getMacroVenues","parameters":[{"name":"asset_class","required":false,"in":"query","description":"Restrict to a single asset class. Defaults to all non-crypto.","schema":{"example":"equity","type":"string","enum":["equity","commodity","forex","index"]}},{"name":"market_type","required":false,"in":"query","description":"Restrict to a single market type. Omit to get a row per (exchange, sub_exchange, market_type) tuple.","schema":{"example":"perpetual","type":"string","enum":["perpetual","future","spot"]}}],"responses":{"200":{"description":"Venue breakdown"},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Macro Venues","tags":["Macro"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asset_class":{"example":"equity","type":"string","enum":["equity","commodity","forex","index"],"description":"Restrict to a single asset class. Defaults to all non-crypto."},"market_type":{"example":"perpetual","type":"string","enum":["perpetual","future","spot"],"description":"Restrict to a single market type. Omit to get a row per (exchange, sub_exchange, market_type) tuple."}}}}}}}},"/api/v1/macro/summary":{"get":{"description":"Top-N most-traded macro instruments per non-crypto asset class over the last 24h, ranked by USD volume. Returns last close, volume_24h_usd, and venue. Defaults to perpetual (the dominant macro segment). Pass market_type=future for dated commodity futures (OKX/Bybit gold weeklies, Bybit XAUT dateds). Use to surface \"what is hot in equity perps right now\" or \"biggest gold-future moves today\" without scanning the full catalog.","operationId":"getMacroSummary","parameters":[{"name":"asset_class","required":false,"in":"query","description":"Restrict to a single asset class. Defaults to all non-crypto.","schema":{"example":"equity","type":"string","enum":["equity","commodity","forex","index"]}},{"name":"market_type","required":false,"in":"query","description":"Market type to rank. Defaults to perpetual (the dominant macro segment). Use \"future\" for dated commodity futures (e.g. OKX gold weeklies, Bybit XAUT dateds).","schema":{"default":"perpetual","example":"perpetual","type":"string","enum":["perpetual","future"]}},{"name":"top","required":false,"in":"query","description":"Top-N per asset class (1-50).","schema":{"default":10,"example":10,"type":"number"}}],"responses":{"200":{"description":"Top-N per asset class"},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Macro 24h Summary","tags":["Macro"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"asset_class":{"example":"equity","type":"string","enum":["equity","commodity","forex","index"],"description":"Restrict to a single asset class. Defaults to all non-crypto."},"market_type":{"default":"perpetual","example":"perpetual","type":"string","enum":["perpetual","future"],"description":"Market type to rank. Defaults to perpetual (the dominant macro segment). Use \"future\" for dated commodity futures (e.g. OKX gold weeklies, Bybit XAUT dateds)."},"top":{"default":10,"example":10,"type":"number","description":"Top-N per asset class (1-50)."}}}}}}}},"/api/v1/vol-surface/catalog":{"get":{"description":"Lists available proprietary vol-surface tuples by exchange, currency, margin, and model with the latest calibration timestamp. Use this before querying slices, term structure, strikes, or risk.","operationId":"Vol Surface Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Optional exchange filter.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Optional base currency filter.","schema":{"example":"BTC","type":"string"}},{"name":"margin","required":false,"in":"query","description":"Optional margin filter.","schema":{"example":"inverse","type":"string","enum":["inverse","linear"]}},{"name":"model","required":false,"in":"query","description":"Optional model filter.","schema":{"example":"svi","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of surface tuples to return.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"exchange":"deribit","currency":"BTC","margin":"inverse","model":"svi","date":"2026-06-08T12:00:00.000Z","index_price":104000.25,"n_slices":10,"n_forward_knots":7}],"meta":{"next_cursor":null}}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Catalog","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Optional exchange filter."},"currency":{"example":"BTC","type":"string","description":"Optional base currency filter."},"margin":{"example":"inverse","type":"string","enum":["inverse","linear"],"description":"Optional margin filter."},"model":{"example":"svi","type":"string","description":"Optional model filter."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of surface tuples to return."}}}}}}}},"/api/v1/vol-surface/snapshots":{"get":{"description":"Returns surface-level calibration metadata from `vol_surface_snapshots`: index price, slice count, forward-curve JSON, and calendar-arbitrage diagnostics. Omit start/end for latest snapshot mode; pass start/end for paginated history.","operationId":"Vol Surface Snapshots","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"margin","required":false,"in":"query","description":"Margin book. Inverse and linear surfaces are distinct and must not be combined.","schema":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"]}},{"name":"date","required":false,"in":"query","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of rows to return in historical scan mode.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from meta.next_cursor.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction for historical scan mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"model","required":false,"in":"query","description":"Surface model. Defaults to 'svi'. Pass another model only when explicitly comparing model families.","schema":{"default":"svi","example":"svi","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2026-06-08T12:00:00.000Z","exchange":"deribit","currency":"BTC","margin":"inverse","model":"svi","index_price":104000.25,"n_slices":10,"n_forward_knots":7,"calendar_arb_pairs_checked":9,"calendar_arb_violating_pairs":0,"calendar_arb_in_range_violations":0,"calendar_arb_max_excess":0,"forward_curve":{"points":[{"tau":0.08,"forward":104250.1}]}}],"meta":{"next_cursor":null,"date":"2026-06-08T12:00:00.000Z"}}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Snapshots","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"margin":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"],"description":"Margin book. Inverse and linear surfaces are distinct and must not be combined."},"date":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp."},"start":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"end":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of rows to return in historical scan mode."},"cursor":{"type":"string","description":"Pagination cursor from meta.next_cursor."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction for historical scan mode."},"model":{"default":"svi","example":"svi","type":"string","description":"Surface model. Defaults to 'svi'. Pass another model only when explicitly comparing model families."}},"required":["exchange","currency"]}}}}}},"/api/v1/vol-surface/slices":{"get":{"description":"Returns per-expiry proprietary surface fits from `vol_surface_slices`, including model parameters, ATM/wing metrics, fit diagnostics, spread-model coefficients, quote-quality counts, quality tier, and fallback metadata. Filters `margin` and `model` by default to avoid mixing inverse/linear or SVI/SABR rows.","operationId":"Vol Surface Slices","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"margin","required":false,"in":"query","description":"Margin book. Inverse and linear surfaces are distinct and must not be combined.","schema":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"]}},{"name":"date","required":false,"in":"query","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of rows to return in historical scan mode.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from meta.next_cursor.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction for historical scan mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"model","required":false,"in":"query","description":"Surface model. Defaults to 'svi'. Pass another model only when explicitly comparing model families.","schema":{"default":"svi","example":"svi","type":"string"}},{"name":"expiry","required":false,"in":"query","description":"Expiry filter in ISO 8601 UTC. If omitted in snapshot mode, all expiries from the snapshot are returned.","schema":{"format":"date-time","example":"2026-06-26T08:00:00Z","type":"string"}},{"name":"quality_tier","required":false,"in":"query","description":"Filter by engine trust label: trusted, indicative, or untrusted.","schema":{"example":"trusted","type":"string","enum":["trusted","indicative","untrusted"]}},{"name":"slice_source","required":false,"in":"query","description":"Filter by slice source: fitted or fallback.","schema":{"example":"fitted","type":"string","enum":["fitted","fallback"]}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2026-06-08T12:00:00.000Z","exchange":"deribit","currency":"BTC","margin":"inverse","model":"svi","expiry":"2026-06-26T08:00:00.000Z","tau":0.0465,"forward":104250.1,"atm_iv":48.2,"skew_25d":-3.1,"butterfly_25d":1.4,"put_25d_iv":50.1,"call_25d_iv":47,"rmse":0.42,"n_strikes":64,"n_two_sided":55,"n_one_sided":9,"n_mark_only":0,"quality_tier":"trusted","slice_source":"fitted","fallback_age_seconds":0,"model_params":{"a":0.01,"b":0.2,"rho":-0.4,"m":0,"sigma":0.3}}],"meta":{"next_cursor":null,"date":"2026-06-08T12:00:00.000Z"}}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Slices","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"margin":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"],"description":"Margin book. Inverse and linear surfaces are distinct and must not be combined."},"date":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp."},"start":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"end":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of rows to return in historical scan mode."},"cursor":{"type":"string","description":"Pagination cursor from meta.next_cursor."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction for historical scan mode."},"model":{"default":"svi","example":"svi","type":"string","description":"Surface model. Defaults to 'svi'. Pass another model only when explicitly comparing model families."},"expiry":{"format":"date-time","example":"2026-06-26T08:00:00Z","type":"string","description":"Expiry filter in ISO 8601 UTC. If omitted in snapshot mode, all expiries from the snapshot are returned."},"quality_tier":{"example":"trusted","type":"string","enum":["trusted","indicative","untrusted"],"description":"Filter by engine trust label: trusted, indicative, or untrusted."},"slice_source":{"example":"fitted","type":"string","enum":["fitted","fallback"],"description":"Filter by slice source: fitted or fallback."}},"required":["exchange","currency"]}}}}}},"/api/v1/vol-surface/term-structure":{"get":{"description":"Returns constant-maturity proprietary term-structure rows from `vol_surface_term_structure`, including ATM IV, total variance, fixed-tenor skew metrics, forward, term slope, forward vol, and source label.","operationId":"Vol Surface Term Structure","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"margin","required":false,"in":"query","description":"Margin book. Inverse and linear surfaces are distinct and must not be combined.","schema":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"]}},{"name":"date","required":false,"in":"query","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of rows to return in historical scan mode.","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from meta.next_cursor.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction for historical scan mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"tenor_days","required":false,"in":"query","description":"Constant-maturity tenor in days.","schema":{"minimum":1,"example":30,"type":"number"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2026-06-08T12:00:00.000Z","exchange":"deribit","currency":"BTC","margin":"inverse","tenor_days":30,"atm_iv":49.1,"total_variance":0.198,"skew_25d":-3.4,"butterfly_25d":1.5,"forward":104500.2,"term_slope":0.7,"forward_vol":50.3,"forward_tenor":"30d-60d","source":"interpolated"}],"meta":{"next_cursor":null,"date":"2026-06-08T12:00:00.000Z"}}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Term Structure","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"margin":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"],"description":"Margin book. Inverse and linear surfaces are distinct and must not be combined."},"date":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns the latest row at or before this timestamp."},"start":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string","description":"Start time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"end":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"End time in ISO 8601 UTC. Providing start or end enables historical scan mode."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of rows to return in historical scan mode."},"cursor":{"type":"string","description":"Pagination cursor from meta.next_cursor."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction for historical scan mode."},"tenor_days":{"minimum":1,"example":30,"type":"number","description":"Constant-maturity tenor in days."}},"required":["exchange","currency"]}}}}}},"/api/v1/vol-surface/strikes":{"get":{"description":"Returns per-strike proprietary diagnostics and greeks from `vol_surface_strikes`. This is the heaviest table; latest snapshot mode is allowed broadly, while historical scans require `expiry` or `instrument`.","operationId":"Vol Surface Strikes","parameters":[{"name":"exchange","required":true,"in":"query","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive.","schema":{"example":"deribit","type":"string"}},{"name":"currency","required":true,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"margin","required":false,"in":"query","description":"Margin book. Inverse and linear surfaces are distinct and must not be combined.","schema":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"]}},{"name":"date","required":false,"in":"query","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns strikes at the latest fit at or before this timestamp.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"start","required":false,"in":"query","description":"Start time in ISO 8601 UTC. Historical strike scans require expiry or instrument.","schema":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End time in ISO 8601 UTC. Historical strike scans require expiry or instrument.","schema":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string"}},{"name":"expiry","required":false,"in":"query","description":"Expiry filter in ISO 8601 UTC.","schema":{"format":"date-time","example":"2026-06-26T08:00:00Z","type":"string"}},{"name":"instrument","required":false,"in":"query","description":"Option instrument identifier.","schema":{"example":"BTC-26JUN26-100000-C","type":"string"}},{"name":"strike","required":false,"in":"query","description":"Strike filter.","schema":{"example":100000,"type":"number"}},{"name":"option_type","required":false,"in":"query","description":"Option type filter.","schema":{"example":"C","type":"string","enum":["C","P"]}},{"name":"limit","required":false,"in":"query","description":"Maximum number of rows to return.","schema":{"minimum":1,"maximum":5000,"default":500,"example":500,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from meta.next_cursor.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction for historical scan mode.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"latest","required":false,"in":"query","description":"Whether snapshot mode should return only rows from the latest fit. Defaults to true.","schema":{"default":true,"type":"boolean"}}],"responses":{"200":{"content":{"application/json":{"example":{"data":[{"date":"2026-06-08T12:00:00.000Z","exchange":"deribit","currency":"BTC","margin":"inverse","expiry":"2026-06-26T08:00:00.000Z","instrument":"BTC-26JUN26-100000-C","strike":100000,"option_type":"C","log_moneyness":-0.0416,"bid_iv":47.5,"ask_iv":48.2,"mark_iv":47.9,"model_iv":48,"deviation_vol":-0.1,"bs_delta":0.55,"bs_gamma":0.00004,"bs_vega":155.2,"bs_theta":-120.4,"smile_delta":0.53,"mv_delta":0.52}],"meta":{"next_cursor":null,"date":"2026-06-08T12:00:00.000Z"}}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Strikes","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"example":"deribit","type":"string","description":"Exchange name. Examples: deribit, binance, okx, bybit, bullish, derive."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"margin":{"default":"inverse","example":"inverse","type":"string","enum":["inverse","linear"],"description":"Margin book. Inverse and linear surfaces are distinct and must not be combined."},"date":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"Snapshot cutoff time in ISO 8601 UTC. Snapshot mode returns strikes at the latest fit at or before this timestamp."},"start":{"format":"date-time","example":"2026-06-08T00:00:00Z","type":"string","description":"Start time in ISO 8601 UTC. Historical strike scans require expiry or instrument."},"end":{"format":"date-time","example":"2026-06-08T12:00:00Z","type":"string","description":"End time in ISO 8601 UTC. Historical strike scans require expiry or instrument."},"expiry":{"format":"date-time","example":"2026-06-26T08:00:00Z","type":"string","description":"Expiry filter in ISO 8601 UTC."},"instrument":{"example":"BTC-26JUN26-100000-C","type":"string","description":"Option instrument identifier."},"strike":{"example":100000,"type":"number","description":"Strike filter."},"option_type":{"example":"C","type":"string","enum":["C","P"],"description":"Option type filter."},"limit":{"minimum":1,"maximum":5000,"default":500,"example":500,"type":"number","description":"Maximum number of rows to return."},"cursor":{"type":"string","description":"Pagination cursor from meta.next_cursor."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction for historical scan mode."},"latest":{"default":true,"type":"boolean","description":"Whether snapshot mode should return only rows from the latest fit. Defaults to true."}},"required":["exchange","currency"]}}}}}},"/api/v1/vol-surface/risk/decompose":{"post":{"description":"Runs live portfolio risk decomposition through the proprietary vol-surface engine. Requires the same API-key authentication as GET data endpoints.","operationId":"Vol Surface Risk Decompose","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolSurfaceRiskDecomposeRequestDto"},"examples":{"default":{"value":{"exchange":"deribit","currency":"BTC","positions":[{"instrument":"BTC-31JUL26-62000-C","kind":"option","exchange":"deribit","currency":"BTC","margin":"inverse","strike":62000,"expiry":"2026-07-31T08:00:00Z","option_type":"C","quantity":1}]}}}}}},"responses":{"200":{"content":{"application/json":{"example":{"exchange":"deribit","currency":"BTC","margin":"inverse","position_count":1,"mark_value_usd":4048.0574817095476,"mark_value_coin":0.06562415469101558,"gross_value_usd":4048.0574817095476,"market_value_usd":4055.7195304898014,"model_edge_value_usd":-7.662048780253826,"total_mark_pnl_usd":4048.0574817095476,"total_funding_pnl_usd":0,"total_pnl_usd":4048.0574817095476,"total_delta":0.5298747339971175,"total_gamma":0.000038802800723917366,"total_theta":-39.54853334689837,"total_vega":92.5870843232772,"total_rho":34.91393048941768,"total_vanna":0.0008183791577023126,"total_volga":-0.014276290645167958,"total_charm":-0.0003495703061108222,"level_vega":10.904900106306162,"skew_vega":49.27619330071987,"curvature_vega":32.40599091625117,"total_smile_gamma":0.000042352439219740666,"total_smile_vanna":0.0008096251247532112,"total_pa_delta":0.4642505793061019,"total_pa_gamma":0.00003127670901957946,"total_pa_vega":0.0015009542654653445,"total_pa_theta":-0.0006411319705528492,"total_pa_vanna":-0.0006825751077630318,"buckets":[{"tenor_label":"60d","tenor_days":60,"total_vega":92.5870843232772,"level_vega":10.904900106306162,"skew_vega":49.27619330071987,"curvature_vega":32.40599091625117,"net_delta":0.5298747339971175,"net_gamma":0.000038802800723917366,"net_theta":-39.54853334689837,"positions":1}],"positions":[{"instrument":"BTC-31JUL26-62000-C","kind":"option","exchange":"deribit","currency":"BTC","margin":"inverse","strike":62000,"expiry":"2026-07-31T08:00:00Z","option_type":"C","quantity":1,"spot":61685.479999999996,"forward":61919.63800499999,"atm_iv":44.101471505515754,"model_iv":44.05210602686287,"market_iv":44.134861605065296,"model_price_usd":4048.0574817095476,"market_price_usd":4055.7195304898014,"model_edge_usd":-7.662048780253826,"delta":0.5298747339971175,"gamma":0.000038802800723917366,"theta":-39.54853334689837,"vega":92.5870843232772,"rho":34.91393048941768,"pa_delta":0.4642505793061019,"smile_delta":0.5866479117764257,"level_vega":10.904900106306162,"skew_vega":49.27619330071987,"curvature_vega":32.40599091625117,"bid_iv":43.80047281798966,"ask_iv":44.46925039214093,"deviation_vol":0.08275557820242341,"slice_source":"fitted","slice_quality_tier":"trusted","bucket_label":"60d","bucket_days":60}],"unrealized_pnl_usd":4048.0574817095476,"premium_pnl_usd":4048.0574817095476,"model":"svi"}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""},"502":{"description":"Bad Gateway - risk engine returned an unexpected error"},"503":{"description":"Service Unavailable - risk engine has no cached surface or is temporarily unavailable"},"504":{"description":"Gateway Timeout - risk request timed out"}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Risk Decompose","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/vol-surface/risk/scenario":{"post":{"description":"Reprices a portfolio under a spot/vol/skew/curvature/time shock through the proprietary vol-surface engine. Requires the same API-key authentication as GET data endpoints.","operationId":"Vol Surface Risk Scenario","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolSurfaceRiskScenarioRequestDto"},"examples":{"default":{"value":{"exchange":"deribit","currency":"BTC","positions":[{"instrument":"BTC-31JUL26-62000-C","kind":"option","exchange":"deribit","currency":"BTC","margin":"inverse","strike":62000,"expiry":"2026-07-31T08:00:00Z","option_type":"C","quantity":1}],"shock":{"name":"Spot down 10 vol up 5","spot_shift_pct":-10,"level_shift_vol":5,"skew_shift":0,"curvature_shift":0,"time_decay_days":0}}}}}}},"responses":{"200":{"content":{"application/json":{"example":{"shock":{"name":"Spot down 10 vol up 5","spot_shift_pct":-10,"level_shift_vol":5,"skew_shift":0,"curvature_shift":0,"time_decay_days":0},"exchange":"deribit","currency":"BTC","margin":"inverse","position_count":1,"base_value_usd":4048.0574817095476,"base_value_coin":0.06562415469101558,"shocked_value_usd":1689.5573821337857,"shocked_value_coin":0.030433190763023175,"pnl_usd":-2358.500099575762,"pnl_coin":-0.03519096392799241,"pnl_pct":-0.5826251505153371,"total_delta":0.29974008937747426,"total_gamma":0.000035800752388230626,"total_theta":-32.716834317584535,"total_driftless_theta":-32.716834317584535,"total_vega":72.79941739023384,"total_rho":18.824410639288853,"total_vanna":0.005244352743597323,"total_volga":0.576868209820335,"total_charm":-0.00235686803502168,"total_smile_delta":0.32063045230615406,"total_smile_gamma":0.0000434216818884387,"total_smile_vanna":0.005409889593989498,"total_shocked_atm_iv":49.10147150551577,"total_pa_delta":0.26930689861445106,"total_pa_gamma":0.00003094985575340846,"total_pa_vega":0.0013113011610626077,"total_pa_theta":-0.0005893127220644061,"total_pa_vanna":0.003933051582534716,"positions":[{"instrument":"BTC-31JUL26-62000-C","quantity":1,"contract_multiplier":1,"effective_quantity":1,"quantity_status":"metadata","slice_quality_tier":"trusted","base_price_usd":4048.0574817095476,"shocked_price_usd":1689.5573821337857,"shocked_atm_iv":49.10147150551577,"pnl_usd":-2358.500099575762,"delta":0.29974008937747426,"gamma":0.000035800752388230626,"theta":-32.716834317584535,"vega":72.79941739023384,"rho":18.824410639288853,"pa_delta":0.26930689861445106,"smile_delta":0.32063045230615406}]}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""},"502":{"description":"Bad Gateway - risk engine returned an unexpected error"},"503":{"description":"Service Unavailable - risk engine has no cached surface or is temporarily unavailable"},"504":{"description":"Gateway Timeout - risk request timed out"}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Risk Scenario","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/vol-surface/risk/ladder":{"post":{"description":"Reprices a portfolio across a spot x parallel-vol grid through the proprietary vol-surface engine. Requires the same API-key authentication as GET data endpoints. The grid is capped at 400 cells.","operationId":"Vol Surface Risk Ladder","parameters":[],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/VolSurfaceRiskLadderRequestDto"},"examples":{"default":{"value":{"exchange":"deribit","currency":"BTC","positions":[{"instrument":"BTC-31JUL26-62000-C","kind":"option","exchange":"deribit","currency":"BTC","margin":"inverse","strike":62000,"expiry":"2026-07-31T08:00:00Z","option_type":"C","quantity":1}],"spot_shifts_pct":[-10,0,10],"vol_shifts":[-5,0,5],"skew_shift":0,"curvature_shift":0,"time_decay_days":0}}}}}},"responses":{"200":{"content":{"application/json":{"example":{"exchange":"deribit","currency":"BTC","margin":"inverse","position_count":1,"spot_shifts_pct":[-10,0,10],"vol_shifts":[-5,0,5],"skew_shift":0,"curvature_shift":0,"time_decay_days":0,"cells":[{"spot_shift_pct":-10,"vol_shift":-5,"pnl_usd":-3100.130704472309,"pnl_coin":-0.04854960206196831,"pnl_pct":-0.7658316905033382,"total_delta":0.23250553927858042,"total_gamma":0.00004098821038404953,"total_theta":-22.077273192877684,"total_vega":63.987977535804085,"total_shocked_atm_iv":39.10147150551575,"slice_quality_tier":"trusted"},{"spot_shift_pct":0,"vol_shift":0,"pnl_usd":0,"pnl_coin":0,"pnl_pct":0,"total_delta":0.5298747339971175,"total_gamma":0.000038802800723917366,"total_theta":-39.54853334689837,"total_vega":92.5870843232772,"total_shocked_atm_iv":44.101471505515754,"slice_quality_tier":"trusted"},{"spot_shift_pct":10,"vol_shift":5,"pnl_usd":4716.611382299721,"pnl_coin":0.06354531574940202,"pnl_pct":1.1651542508007655,"total_delta":0.7165886093416941,"total_gamma":0.00002503491483006675,"total_theta":-44.40447141428705,"total_vega":86.68276911566157,"total_shocked_atm_iv":49.10147150551577,"slice_quality_tier":"trusted"}],"pnl_usd_matrix":[[-3100.130704472309,-2737.6842249998426,-2358.500099575762],[-463.6925637164677,0,463.21552979895205],[3942.1427372296457,4320.936753402966,4716.611382299721]],"pnl_coin_matrix":[[-0.04854960206196831,-0.04202102660912329,-0.03519096392799241],[-0.0075170455626910535,0,0.007509312236833557],[0.05213156968453943,0.057714053544942245,0.06354531574940202]],"pnl_pct_matrix":[[-0.7658316905033382,-0.6762957881328511,-0.5826251505153371],[-0.11454693166082322,0,0.11442908898698001],[0.9738356619295898,1.0674099300532112,1.1651542508007655]]}}},"description":""},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""},"502":{"description":"Bad Gateway - risk engine returned an unexpected error"},"503":{"description":"Service Unavailable - risk engine has no cached surface or is temporarily unavailable"},"504":{"description":"Gateway Timeout - risk request timed out"}},"security":[{"X-API-Key":[]}],"summary":"Vol Surface Risk Ladder","tags":["Vol Surface"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/fills":{"get":{"description":"Returns enriched per-fill Hyperliquid L1 HyperCore data with wallet attribution, fees, closed PnL, position direction, builder/deployer fees, and liquidation flags. Requires wallet. Covers perps, HIP-3 perps, and spot fills.\n\nRequired query parameter: wallet.","operationId":"HyperCore Fills","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by event time. Defaults to DESC for node history endpoints.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC).","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, NVDA, BASED).","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Hyperliquid node market type.","schema":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"wallet","required":true,"in":"query","description":"Wallet address. Required for raw Hyperliquid node fills.","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}},{"name":"side","required":false,"in":"query","description":"Aggressor side.","schema":{"type":"string","enum":["buy","sell"]}},{"name":"dir","required":false,"in":"query","description":"Position direction from the node fill (e.g. Open Long, Close Short, Buy, Sell).","schema":{"example":"Open Long","type":"string"}},{"name":"min_notional","required":false,"in":"query","description":"Minimum fill notional in USDC.","schema":{"example":10000,"type":"number"}},{"name":"crossed","required":false,"in":"query","description":"Filter taker fills. 1 = taker, 0 = maker.","schema":{"type":"number","enum":[0,1]}},{"name":"is_liquidation","required":false,"in":"query","description":"Filter liquidation fills. 1 = liquidation, 0 = non-liquidation.","schema":{"type":"number","enum":[0,1]}}],"responses":{"200":{"description":"Paginated node fills","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Fills","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by event time. Defaults to DESC for node history endpoints."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC)."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, NVDA, BASED)."},"market_type":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Hyperliquid node market type."},"wallet":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string","description":"Wallet address. Required for raw Hyperliquid node fills."},"side":{"type":"string","enum":["buy","sell"],"description":"Aggressor side."},"dir":{"example":"Open Long","type":"string","description":"Position direction from the node fill (e.g. Open Long, Close Short, Buy, Sell)."},"min_notional":{"example":10000,"type":"number","description":"Minimum fill notional in USDC."},"crossed":{"type":"number","enum":[0,1],"description":"Filter taker fills. 1 = taker, 0 = maker."},"is_liquidation":{"type":"number","enum":[0,1],"description":"Filter liquidation fills. 1 = liquidation, 0 = non-liquidation."}},"required":["wallet"]}}}},"x-required-query":["wallet"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/prediction-fills":{"get":{"description":"Returns HIP-4 prediction outcome fills enriched from Hyperliquid L1 HyperCore data, including condition/token identifiers and wallet attribution. Requires at least one of instrument_name, condition_id, or token_id.\n\nAt least one query parameter is required: instrument_name, condition_id, token_id.","operationId":"HyperCore Prediction Fills","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by fill time. Defaults to DESC.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Prediction instrument name.","schema":{"example":"fed-cuts-in-2026-YES","type":"string"}},{"name":"condition_id","required":false,"in":"query","description":"Prediction market condition ID.","schema":{"type":"string"}},{"name":"token_id","required":false,"in":"query","description":"Prediction outcome token ID.","schema":{"type":"string"}},{"name":"outcome","required":false,"in":"query","description":"Outcome side label.","schema":{"example":"YES","type":"string"}},{"name":"category","required":false,"in":"query","description":"Prediction category.","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Prediction event slug.","schema":{"type":"string"}},{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"type":"string"}},{"name":"side","required":false,"in":"query","description":"Aggressor side.","schema":{"type":"string","enum":["buy","sell"]}},{"name":"min_notional","required":false,"in":"query","description":"Minimum fill notional.","schema":{"example":1000,"type":"number"}}],"responses":{"200":{"description":"Paginated HIP-4 prediction fills","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Prediction Fills","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by fill time. Defaults to DESC."},"instrument_name":{"example":"fed-cuts-in-2026-YES","type":"string","description":"Prediction instrument name."},"condition_id":{"type":"string","description":"Prediction market condition ID."},"token_id":{"type":"string","description":"Prediction outcome token ID."},"outcome":{"example":"YES","type":"string","description":"Outcome side label."},"category":{"example":"crypto","type":"string","description":"Prediction category."},"event_slug":{"type":"string","description":"Prediction event slug."},"wallet":{"type":"string","description":"Wallet address."},"side":{"type":"string","enum":["buy","sell"],"description":"Aggressor side."},"min_notional":{"example":1000,"type":"number","description":"Minimum fill notional."}},"anyOf":[{"required":["instrument_name"]},{"required":["condition_id"]},{"required":["token_id"]}]}}}},"x-required-query-anyOf":["instrument_name","condition_id","token_id"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/liquidations":{"get":{"description":"Returns liquidation fills from HyperCore with liquidated user, liquidator wallet, mark price, method, fill price, closed PnL, role, and backstop labels. Raw event mode preserves the two-row liquidated/liquidator structure; dedupe=true returns one canonical row per event.","operationId":"HyperCore Liquidations","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by event time. Defaults to DESC for node history endpoints.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC).","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, NVDA, BASED).","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Hyperliquid node market type.","schema":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}},{"name":"liquidated_user","required":false,"in":"query","description":"Liquidated wallet address.","schema":{"type":"string"}},{"name":"liquidator","required":false,"in":"query","description":"Liquidator wallet address.","schema":{"type":"string"}},{"name":"min_notional","required":false,"in":"query","description":"Minimum liquidation notional in USDC.","schema":{"example":10000,"type":"number"}},{"name":"dedupe","required":false,"in":"query","description":"When true, returns one canonical liquidation row per event from the liquidated-user perspective. Defaults to false, preserving the raw two-row victim/counterparty structure.","schema":{"default":false,"type":"boolean"}},{"name":"resolution","required":false,"in":"query","description":"Optional aggregation resolution. When set, returns per-instrument liquidation buckets instead of event rows.","schema":{"type":"string","enum":["5m","15m","1h","1d"]}}],"responses":{"200":{"description":"Paginated node liquidations","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Liquidations","tags":["Hyperliquid - HyperCore"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by event time. Defaults to DESC for node history endpoints."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC)."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, NVDA, BASED)."},"market_type":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Hyperliquid node market type."},"wallet":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string","description":"Wallet address."},"liquidated_user":{"type":"string","description":"Liquidated wallet address."},"liquidator":{"type":"string","description":"Liquidator wallet address."},"min_notional":{"example":10000,"type":"number","description":"Minimum liquidation notional in USDC."},"dedupe":{"default":false,"type":"boolean","description":"When true, returns one canonical liquidation row per event from the liquidated-user perspective. Defaults to false, preserving the raw two-row victim/counterparty structure."},"resolution":{"type":"string","enum":["5m","15m","1h","1d"],"description":"Optional aggregation resolution. When set, returns per-instrument liquidation buckets instead of event rows."}}}}}}}},"/api/v1/hyperliquid/node/wallet-flow":{"get":{"description":"Returns per-wallet HyperCore flow rollups with buy/sell/net volume, buy/sell/net/total notional, trade count, realized PnL, and fees. Requires at least one of wallet, instrument_name, instrument_name_raw, or currency. Negative fees are maker rebates. Source table is the 1-minute materialized view from native fills. Time range caps by resolution: 1m=7d, 5m=14d, 15m=30d, 1h=90d, 4h=180d, 1d=365d.\n\nAt least one query parameter is required: wallet, instrument_name, instrument_name_raw, currency.","operationId":"HyperCore Wallet Flow","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by event time. Defaults to DESC for node history endpoints.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC).","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, NVDA, BASED).","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Hyperliquid node market type.","schema":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Aggregation resolution. Source table is 1-minute wallet flow. Maximum time range by resolution: 1m=7d, 5m=14d, 15m=30d, 1h=90d, 4h=180d, 1d=365d.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"sort_by","required":false,"in":"query","description":"Sort key for wallet flow rows. time preserves the historical time ordering; notional/PnL/count sorts rank wallets inside the selected window.","schema":{"default":"time","type":"string","enum":["time","total_notional","buy_notional","sell_notional","net_notional","realized_pnl","trade_count"]}},{"name":"min_notional","required":false,"in":"query","description":"Minimum total traded notional in USDC (buy_notional + sell_notional).","schema":{"example":100000,"type":"number"}}],"responses":{"200":{"description":"Paginated wallet flow rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Wallet Flow","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by event time. Defaults to DESC for node history endpoints."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC)."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, NVDA, BASED)."},"market_type":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Hyperliquid node market type."},"wallet":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string","description":"Wallet address."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Aggregation resolution. Source table is 1-minute wallet flow. Maximum time range by resolution: 1m=7d, 5m=14d, 15m=30d, 1h=90d, 4h=180d, 1d=365d."},"sort_by":{"default":"time","type":"string","enum":["time","total_notional","buy_notional","sell_notional","net_notional","realized_pnl","trade_count"],"description":"Sort key for wallet flow rows. time preserves the historical time ordering; notional/PnL/count sorts rank wallets inside the selected window."},"min_notional":{"example":100000,"type":"number","description":"Minimum total traded notional in USDC (buy_notional + sell_notional)."}},"anyOf":[{"required":["wallet"]},{"required":["instrument_name"]},{"required":["instrument_name_raw"]},{"required":["currency"]}]}}}},"x-required-query-anyOf":["wallet","instrument_name","instrument_name_raw","currency"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/wallet-positions":{"get":{"description":"Returns latest per-wallet HyperCore positions by instrument, ranked by absolute position size, with latest mark price, mark-time, position notional, nullable reconstructed entry price, and wallet labels. Requires at least one of wallet, instrument_name, instrument_name_raw, or currency. Response meta uses freshness_basis=ingestion_watermark with watermark_time and staleness_ms; row updated_at and last_fill_time remain wallet activity timestamps and do not drive freshness warnings. Stale ingestion watermarks and unresolved instrument filters are reported in meta.warnings.\n\nAt least one query parameter is required: wallet, instrument_name, instrument_name_raw, currency.","operationId":"HyperCore Wallet Positions","parameters":[{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name.","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin.","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Market type.","schema":{"type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"start","required":false,"in":"query","description":"Start date for last fill time filter.","schema":{"format":"date-time","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date for last fill time filter.","schema":{"format":"date-time","type":"string"}},{"name":"include_zero","required":false,"in":"query","description":"Include zero/flat positions.","schema":{"default":false,"type":"boolean"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of positions to return (1-1000).","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"description":"Latest wallet position rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}},"freshness_basis":{"type":"string","enum":["ingestion_watermark"],"description":"Basis used to compute staleness_ms."},"staleness_ms":{"type":"number","nullable":true,"description":"Milliseconds since the freshness basis timestamp."},"watermark_time":{"type":"string","nullable":true,"description":"Latest event ingestion watermark timestamp in UTC."},"watermark_time_iso":{"type":"string","nullable":true,"description":"Latest event ingestion watermark timestamp in ISO 8601 UTC."}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Wallet Positions","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","description":"Wallet address."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"market_type":{"type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Market type."},"start":{"format":"date-time","type":"string","description":"Start date for last fill time filter."},"end":{"format":"date-time","type":"string","description":"End date for last fill time filter."},"include_zero":{"default":false,"type":"boolean","description":"Include zero/flat positions."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of positions to return (1-1000)."}},"anyOf":[{"required":["wallet"]},{"required":["instrument_name"]},{"required":["instrument_name_raw"]},{"required":["currency"]}]}}}},"x-required-query-anyOf":["wallet","instrument_name","instrument_name_raw","currency"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/funding-payments":{"get":{"description":"Returns per-wallet hourly HyperCore funding payments from native misc events. Requires wallet. This is payment-level data, not just market-level funding rates.\n\nRequired query parameter: wallet.","operationId":"HyperCore Funding Payments","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by event time. Defaults to DESC for node history endpoints.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC).","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, NVDA, BASED).","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Hyperliquid node market type.","schema":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"wallet","required":true,"in":"query","description":"Wallet address. Required for Hyperliquid funding payments.","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}},{"name":"min_abs_usdc","required":false,"in":"query","description":"Minimum absolute funding payment in USDC.","schema":{"example":10,"type":"number"}}],"responses":{"200":{"description":"Paginated funding payment rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Funding Payments","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by event time. Defaults to DESC for node history endpoints."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC)."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, NVDA, BASED)."},"market_type":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Hyperliquid node market type."},"wallet":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string","description":"Wallet address. Required for Hyperliquid funding payments."},"min_abs_usdc":{"example":10,"type":"number","description":"Minimum absolute funding payment in USDC."}},"required":["wallet"]}}}},"x-required-query":["wallet"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/twap-events":{"get":{"description":"Returns HyperCore TWAP lifecycle events with wallet, status, target size, target notional, executed size/notional, duration, and reduce-only/randomize flags. If wallet/twap_id are omitted, the query defaults to the recent 24h window; use min_target_notional for large TWAP discovery. Broad discovery without wallet/instrument/twap_id is capped to 24h.","operationId":"HyperCore TWAP Events","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by event time. Defaults to DESC for node history endpoints.","schema":{"default":"DESC","type":"string","enum":["ASC","DESC"]}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC).","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency (e.g. BTC, NVDA, BASED).","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Hyperliquid node market type.","schema":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string"}},{"name":"twap_id","required":false,"in":"query","description":"TWAP ID.","schema":{"type":"number"}},{"name":"status","required":false,"in":"query","description":"TWAP status.","schema":{"example":"activated","type":"string"}},{"name":"side","required":false,"in":"query","description":"Order side.","schema":{"type":"string","enum":["B","A"]}},{"name":"min_target_notional","required":false,"in":"query","description":"Minimum target notional in USDC. For partially executed TWAPs this uses executed VWAP; otherwise it uses the latest available mark price. Broad TWAP discovery without wallet/instrument/twap_id is capped to a 24h window.","schema":{"example":1000000,"type":"number"}}],"responses":{"200":{"description":"Paginated TWAP lifecycle events","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore TWAP Events","tags":["Hyperliquid - HyperCore"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"DESC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by event time. Defaults to DESC for node history endpoints."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name (e.g. BTC-USD, xyz:NVDA-USD, BASED_USDC)."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"currency":{"example":"BTC","type":"string","description":"Base currency (e.g. BTC, NVDA, BASED)."},"market_type":{"example":"perp","type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Hyperliquid node market type."},"wallet":{"example":"0x1234567890abcdef1234567890abcdef12345678","type":"string","description":"Wallet address."},"twap_id":{"type":"number","description":"TWAP ID."},"status":{"example":"activated","type":"string","description":"TWAP status."},"side":{"type":"string","enum":["B","A"],"description":"Order side."},"min_target_notional":{"example":1000000,"type":"number","description":"Minimum target notional in USDC. For partially executed TWAPs this uses executed VWAP; otherwise it uses the latest available mark price. Broad TWAP discovery without wallet/instrument/twap_id is capped to a 24h window."}}}}}}}},"/api/v1/hyperliquid/node/resting-orders":{"get":{"description":"Returns the latest per-wallet resting order snapshot from HyperCore-derived L4 state, ranked by notional, including mark price, distance_from_mark_pct, machine-readable snapshot freshness metadata, and wallet labels. Requires at least one of wallet, instrument_name, instrument_name_raw, or currency. Snapshots are emitted every 60 seconds; latest requests without start/end are pruned to the most recent 15 minutes. Response meta uses freshness_basis=snapshot with snapshot_time, snapshot_interval_ms, and staleness_ms. Stale snapshots and unresolved instrument filters are reported in meta.warnings.\n\nAt least one query parameter is required: wallet, instrument_name, instrument_name_raw, currency.","operationId":"HyperCore Resting Orders","parameters":[{"name":"wallet","required":false,"in":"query","description":"Wallet address.","schema":{"type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name.","schema":{"example":"BTC-USD","type":"string"}},{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin.","schema":{"example":"BTC","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Market type.","schema":{"type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"side","required":false,"in":"query","description":"Order side.","schema":{"type":"string","enum":["B","A"]}},{"name":"min_notional","required":false,"in":"query","description":"Minimum resting order notional.","schema":{"example":100000,"type":"number"}},{"name":"max_distance_from_mark","required":false,"in":"query","description":"Maximum absolute distance from mark price in percent. Use this to exclude deep crash bids/asks from near-mark liquidity views.","schema":{"example":10,"type":"number"}},{"name":"start","required":false,"in":"query","description":"Restrict latest snapshot search to this start date.","schema":{"format":"date-time","type":"string"}},{"name":"end","required":false,"in":"query","description":"Restrict latest snapshot search to this end date.","schema":{"format":"date-time","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of resting orders to return (1-1000).","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"description":"Latest resting order snapshot rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}},"freshness_basis":{"type":"string","enum":["snapshot"],"description":"Basis used to compute staleness_ms."},"staleness_ms":{"type":"number","nullable":true,"description":"Milliseconds since the freshness basis timestamp."},"snapshot_time":{"type":"string","nullable":true,"description":"Latest snapshot timestamp in UTC."},"snapshot_time_iso":{"type":"string","nullable":true,"description":"Latest snapshot timestamp in ISO 8601 UTC."},"snapshot_interval_ms":{"type":"number","description":"Expected snapshot emission interval in milliseconds."}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Resting Orders","tags":["Hyperliquid - HyperCore"],"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"wallet":{"type":"string","description":"Wallet address."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name."},"instrument_name_raw":{"example":"BTC","type":"string","description":"Raw Hyperliquid node coin."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"market_type":{"type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Market type."},"side":{"type":"string","enum":["B","A"],"description":"Order side."},"min_notional":{"example":100000,"type":"number","description":"Minimum resting order notional."},"max_distance_from_mark":{"example":10,"type":"number","description":"Maximum absolute distance from mark price in percent. Use this to exclude deep crash bids/asks from near-mark liquidity views."},"start":{"format":"date-time","type":"string","description":"Restrict latest snapshot search to this start date."},"end":{"format":"date-time","type":"string","description":"Restrict latest snapshot search to this end date."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of resting orders to return (1-1000)."}},"anyOf":[{"required":["wallet"]},{"required":["instrument_name"]},{"required":["instrument_name_raw"]},{"required":["currency"]}]}}}},"x-required-query-anyOf":["wallet","instrument_name","instrument_name_raw","currency"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"}}},"/api/v1/hyperliquid/node/instruments":{"get":{"description":"Maps raw Hyperliquid node coins such as BTC, xyz:NVDA, @305, and #40 to normalized instrument names, market type, base currency, tick/lot sizing, HIP-3 display names, deployer, status, and last-seen time.","operationId":"HyperCore Instruments","parameters":[{"name":"instrument_name_raw","required":false,"in":"query","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40).","schema":{"example":"@305","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Normalized instrument name.","schema":{"example":"BTC-USD","type":"string"}},{"name":"currency","required":false,"in":"query","description":"Base currency.","schema":{"example":"BTC","type":"string"}},{"name":"market_type","required":false,"in":"query","description":"Market type.","schema":{"type":"string","enum":["perp","perp_hip3","spot","prediction"]}},{"name":"start","required":false,"in":"query","description":"Only include raw coins observed at or after this UTC datetime. Defaults to 24 hours ago for observed aliases; active perp/HIP-3 mappings also come from Hyperliquid metadata.","schema":{"format":"date-time","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of mappings to return (1-1000).","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}}],"responses":{"200":{"description":"Raw Hyperliquid coin mapping rows","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore Instruments","tags":["Hyperliquid - HyperCore"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instrument_name_raw":{"example":"@305","type":"string","description":"Raw Hyperliquid node coin (e.g. BTC, xyz:NVDA, @305, #40)."},"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name."},"currency":{"example":"BTC","type":"string","description":"Base currency."},"market_type":{"type":"string","enum":["perp","perp_hip3","spot","prediction"],"description":"Market type."},"start":{"format":"date-time","type":"string","description":"Only include raw coins observed at or after this UTC datetime. Defaults to 24 hours ago for observed aliases; active perp/HIP-3 mappings also come from Hyperliquid metadata."},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of mappings to return (1-1000)."}}}}}}}},"/api/v1/hyperliquid/node/l2-orderbook":{"get":{"description":"Returns the latest HyperCore-derived L2 orderbook snapshot for an instrument. Unambiguous inputs such as BTC resolve to canonical names such as BTC-USD when possible; ambiguous or unknown values return an UNRESOLVED_INSTRUMENT warning with an empty data array. Depth can reach 100 levels, compared with the standard WS-derived 20-level Hyperliquid book.","operationId":"HyperCore L2 Orderbook","parameters":[{"name":"instrument_name","required":true,"in":"query","description":"Normalized instrument name.","schema":{"example":"BTC-USD","type":"string"}},{"name":"date","required":false,"in":"query","description":"Snapshot time in ISO 8601 format. If omitted, returns latest available snapshot.","schema":{"format":"date-time","type":"string"}}],"responses":{"200":{"description":"Latest node-derived L2 snapshot","content":{"application/json":{"schema":{"type":"object","properties":{"data":{"type":"array","items":{"type":"object"}},"meta":{"type":"object","properties":{"next_cursor":{"type":"string","nullable":true,"description":"Opaque pagination cursor. Pass this value as the cursor query parameter for the next page."},"warnings":{"type":"array","description":"Structured response warnings. Omitted when there are no warnings.","items":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","enum":["STALE_SNAPSHOT","UNRESOLVED_INSTRUMENT"]},"message":{"type":"string"}}}}},"required":["next_cursor"]}},"required":["data","meta"]}}}},"400":{"content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}},"description":""},"401":{"content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}},"description":""},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}},"description":""}},"security":[{"X-API-Key":[]}],"summary":"HyperCore L2 Orderbook","tags":["Hyperliquid - HyperCore"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"instrument_name":{"example":"BTC-USD","type":"string","description":"Normalized instrument name."},"date":{"format":"date-time","type":"string","description":"Snapshot time in ISO 8601 format. If omitted, returns latest available snapshot."}},"required":["instrument_name"]}}}}}},"/api/v1/predictions/catalog":{"get":{"description":"Returns a list of available prediction market instruments. Supports filtering by exchange, category, event_slug, and keyword search.","operationId":"Predictions Catalog","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug (parent event grouping)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"keyword","required":false,"in":"query","description":"Keyword search to filter instruments by name (case-insensitive partial match)","schema":{"example":"bitcoin","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of instruments to return (1-1000)","schema":{"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor from a previous response","schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"success":true,"data":[{"instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","exchange":"polymarket"},{"instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-NO","exchange":"polymarket"},{"instrument_name":"btc-above-79980-20260505-0600","exchange":"hyperliquid"}]}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Catalog","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Filter by exchange (polymarket or hyperliquid)"},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug (parent event grouping)"},"keyword":{"example":"bitcoin","type":"string","description":"Keyword search to filter instruments by name (case-insensitive partial match)"},"limit":{"default":100,"example":100,"type":"number","description":"Maximum number of instruments to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor from a previous response"}}}}}}}},"/api/v1/predictions/categories":{"get":{"description":"Returns a list of all prediction market categories with instrument counts.","operationId":"Predictions Categories","parameters":[{"name":"exchange","required":false,"in":"query","description":"Filter by exchange (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}}],"responses":{"200":{"content":{"application/json":{"example":[{"category":"crypto","count":45},{"category":"politics","count":32},{"category":"sports","count":18}]}},"description":""},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Categories","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Filter by exchange (polymarket or hyperliquid)"}}}}}}}},"/api/v1/predictions/metadata":{"get":{"description":"Returns metadata for a specific prediction instrument including data availability, total record count, and pagination information.","operationId":"Predictions Metadata","parameters":[{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"limit","required":false,"in":"query","description":"Number of records per page for pagination calculation","schema":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number"}},{"name":"instrument_name","required":true,"in":"query","description":"Instrument name","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}}],"responses":{"200":{"description":"Metadata successfully retrieved","content":{"application/json":{"schema":{"$ref":"#/components/schemas/MetadataResponseEntity"}}}},"400":{"description":"Bad Request - Invalid parameters or no data found","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Metadata","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"limit":{"minimum":1,"maximum":100,"default":100,"example":100,"type":"number","description":"Number of records per page for pagination calculation"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Instrument name"}},"required":["instrument_name"]}}}}}},"/api/v1/predictions/ohlcvt":{"get":{"description":"Retrieves Open, High, Low, Close, Volume, Trades data for prediction market instruments. Prices represent probabilities (0.0-1.0).\n\n**Key Features:**\n- Historical probability-based OHLC candlestick data\n- Buy/sell volume breakdown\n- Trade count statistics\n- Support for multiple resolutions (1m, 5m, 15m, 1h, 4h, 1d)","operationId":"Predictions OHLCVT Market Data","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"instrument_name","required":false,"in":"query","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug (parent event grouping)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"outcome","required":false,"in":"query","description":"Filter by outcome side","schema":{"type":"string","enum":["YES","NO"]}}],"responses":{"200":{"description":"OHLCVT data successfully retrieved","content":{"application/json":{"example":{"success":true,"data":[{"date":"2026-02-20 12:00:00","exchange":"polymarket","instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","condition_id":"0xabc...","token_id":"12345","category":"crypto","event_slug":"will-bitcoin-reach-250000-by-december-31-2026","open":0.35,"high":0.38,"low":0.33,"close":0.37,"vwap":0.355,"volume":1250.5,"buy_volume":750.3,"sell_volume":500.2,"trades_count":85,"buy_trades_count":50,"sell_trades_count":35,"last_probability":0.37}],"meta":{"next_cursor":null}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions OHLCVT Market Data","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)"},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug (parent event grouping)"},"outcome":{"type":"string","enum":["YES","NO"],"description":"Filter by outcome side"}}}}}}}},"/api/v1/predictions/ticker-history":{"get":{"description":"Returns historical ticker data for prediction instruments including probability OHLC, bid/ask spread, and liquidity metrics.","operationId":"Predictions Ticker History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"instrument_name","required":false,"in":"query","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug (parent event grouping)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"outcome","required":false,"in":"query","description":"Filter by outcome side","schema":{"type":"string","enum":["YES","NO"]}}],"responses":{"200":{"content":{"application/json":{"example":{"success":true,"data":[{"date":"2026-02-20 12:00:00","exchange":"polymarket","instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","probability":0.37,"probability_open":0.35,"probability_high":0.38,"probability_low":0.33,"complement_probability":0.63,"bid_price":0.36,"ask_price":0.38,"bid_ask_spread":0.02,"total_liquidity":5000}],"meta":{"next_cursor":null}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Ticker History","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)"},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug (parent event grouping)"},"outcome":{"type":"string","enum":["YES","NO"],"description":"Filter by outcome side"}}}}}}}},"/api/v1/predictions/trades":{"get":{"description":"Returns individual prediction market trades with price (probability), size, side, and outcome information. Supports cursor-based pagination.","operationId":"Predictions Trade History","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"instrument_name","required":false,"in":"query","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug (parent event grouping)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"outcome","required":false,"in":"query","description":"Filter by outcome side","schema":{"type":"string","enum":["YES","NO"]}}],"responses":{"200":{"content":{"application/json":{"example":{"success":true,"data":[{"timestamp":1771523261437,"date":"2026-02-20T12:34:21.437Z","exchange":"polymarket","instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","outcome":"YES","category":"crypto","price":0.37,"size":100,"side":"buy","fee_rate_bps":0,"trade_hash":"abc123def456"}],"meta":{"next_cursor":null}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Trade History","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)"},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug (parent event grouping)"},"outcome":{"type":"string","enum":["YES","NO"],"description":"Filter by outcome side"}}}}}}}},"/api/v1/predictions/orderbook-raw":{"get":{"description":"Returns raw L2 orderbook snapshots for prediction instruments with full bid/ask arrays.\n\n**Key Features:**\n- Full bid/ask price levels\n- Pre-computed liquidity at 3 depth levels (10, 20, 50)\n- Order book imbalance per depth\n- Microprice (liquidity-weighted mid-price)","operationId":"Predictions L2 Orderbook Raw","parameters":[{"name":"start","required":false,"in":"query","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted.","schema":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string"}},{"name":"end","required":false,"in":"query","description":"End date in ISO 8601 format (UTC)","schema":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string"}},{"name":"limit","required":false,"in":"query","description":"Maximum number of records to return (1-1000)","schema":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number"}},{"name":"cursor","required":false,"in":"query","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response.","schema":{"type":"string"}},{"name":"sort_dir","required":false,"in":"query","description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan.","schema":{"default":"ASC","type":"string","enum":["ASC","DESC"]}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for bucketing results","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"instrument_name","required":false,"in":"query","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug (parent event grouping)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"outcome","required":false,"in":"query","description":"Filter by outcome side","schema":{"type":"string","enum":["YES","NO"]}}],"responses":{"200":{"description":"Raw L2 orderbook snapshots successfully retrieved","content":{"application/json":{"example":{"success":true,"data":[{"timestamp":1771523261437,"date":"2026-02-20T12:34:21.437Z","exchange":"polymarket","instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","bids":[{"price":0.36,"size":500},{"price":0.35,"size":300}],"asks":[{"price":0.38,"size":400},{"price":0.39,"size":250}],"depth":20,"bid_liquidity_10":2500,"ask_liquidity_10":2000,"microprice":0.371}],"meta":{"next_cursor":null}}}}},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions L2 Orderbook Raw Snapshots","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"start":{"format":"date-time","example":"2026-07-18T10:00:00.000Z","type":"string","description":"Start date in ISO 8601 format (UTC). Defaults to 24 hours ago when omitted."},"end":{"format":"date-time","example":"2026-07-25T10:00:00.000Z","type":"string","description":"End date in ISO 8601 format (UTC)"},"limit":{"minimum":1,"maximum":1000,"default":100,"example":100,"type":"number","description":"Maximum number of records to return (1-1000)"},"cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Use the value returned in meta.next_cursor from the previous response."},"sort_dir":{"default":"ASC","type":"string","enum":["ASC","DESC"],"description":"Sort direction by time bucket. ASC = oldest first (default, suited for backfills/charts). DESC = newest first (suited for \"latest N\" queries). Cursor pagination works in both directions; keep sort_dir constant within a paginated scan."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for bucketing results"},"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Full prediction instrument identifier (e.g., will-bitcoin-reach-250000-by-december-31-2026-YES)"},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug (parent event grouping)"},"outcome":{"type":"string","enum":["YES","NO"],"description":"Filter by outcome side"}}}}}}}},"/api/v1/predictions/snapshot":{"get":{"description":"Returns a snapshot of all prediction instruments for a given exchange at a single minute. If no date is provided, returns the latest available snapshot. Category and event_slug are optional filters.","operationId":"Predictions Snapshot","parameters":[{"name":"exchange","required":false,"in":"query","description":"Exchange name (polymarket or hyperliquid)","schema":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"]}},{"name":"date","required":false,"in":"query","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot.","schema":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string"}},{"name":"resolution","required":false,"in":"query","description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket.","schema":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}},{"name":"category","required":false,"in":"query","description":"Filter by market category (e.g., crypto, politics, sports)","schema":{"example":"crypto","type":"string"}},{"name":"event_slug","required":false,"in":"query","description":"Filter by event slug","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string"}},{"name":"keyword","required":false,"in":"query","description":"Keyword search to filter instruments by name (case-insensitive partial match)","schema":{"example":"bitcoin","type":"string"}},{"name":"instrument_name","required":false,"in":"query","description":"Filter to a specific instrument name (case-insensitive exact match)","schema":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string"}}],"responses":{"200":{"content":{"application/json":{"example":{"success":true,"data":[{"date":"2026-02-20 12:00:00","exchange":"polymarket","instrument_name":"will-bitcoin-reach-250000-by-december-31-2026-YES","probability":0.37,"bid_price":0.36,"ask_price":0.38,"total_liquidity":5000}],"meta":{"date":"2026-02-20T12:00:00.000Z","next_date":"2026-02-20T12:01:00.000Z"}}}},"description":""},"400":{"description":"Bad Request - Invalid parameters","content":{"application/json":{"example":{"statusCode":400,"message":["exchange must be a string","instrument_name must be a string","resolution must be one of: 1m, 5m, 1h","start must be a valid ISO 8601 date string"],"error":"Bad Request"}}}},"401":{"description":"Unauthorized - Invalid or missing API key","content":{"application/json":{"example":{"error":"unauthorized","message":"Missing or invalid API key"}}}},"402":{"description":"Payment Required","headers":{"payment-required":{"description":"Base64-encoded JSON with payment requirements (accepted networks, amounts, payTo address)","schema":{"type":"string"}}}},"429":{"description":"Too Many Requests - Rate limit exceeded","content":{"application/json":{"example":{"statusCode":429,"message":"Rate limit exceeded. Please retry after 60 seconds","error":"Too Many Requests"}}}}},"security":[{"X-API-Key":[]}],"summary":"Predictions Snapshot","tags":["Predictions"],"x-agentcash-auth":{"mode":"paid"},"x-payment-info":{"protocols":["x402"],"pricingMode":"fixed","price":"0.001"},"requestBody":{"content":{"application/json":{"schema":{"type":"object","properties":{"exchange":{"default":"polymarket","example":"polymarket","type":"string","enum":["polymarket","hyperliquid"],"description":"Exchange name (polymarket or hyperliquid)"},"date":{"format":"date-time","example":"2026-01-20T10:00:00Z","type":"string","description":"Exact date/time for the snapshot in ISO 8601 format (UTC). If omitted, returns the latest available snapshot."},"resolution":{"default":"1m","example":"1m","type":"string","enum":["1m","5m","15m","1h","4h","1d"],"description":"Time resolution for the snapshot. At 1m (default), returns raw minute-level data. At higher resolutions (5m, 1h, etc.), data is aggregated into the specified bucket."},"category":{"example":"crypto","type":"string","description":"Filter by market category (e.g., crypto, politics, sports)"},"event_slug":{"example":"will-bitcoin-reach-250000-by-december-31-2026","type":"string","description":"Filter by event slug"},"keyword":{"example":"bitcoin","type":"string","description":"Keyword search to filter instruments by name (case-insensitive partial match)"},"instrument_name":{"example":"will-bitcoin-reach-250000-by-december-31-2026-YES","type":"string","description":"Filter to a specific instrument name (case-insensitive exact match)"}}}}}}}},"/api/v1/mcp":{"post":{"description":"Model Context Protocol (MCP) Streamable HTTP transport. Accepts JSON-RPC 2.0 requests for methods: initialize, tools/list, tools/call. Use tools/call to invoke any of the 80+ market data and risk tools.","operationId":"MCP Streamable HTTP","parameters":[],"requestBody":{"required":true,"description":"JSON-RPC 2.0 request","content":{"application/json":{"schema":{"type":"object","required":["jsonrpc","id","method"],"properties":{"jsonrpc":{"type":"string","enum":["2.0"],"example":"2.0"},"id":{"type":"integer","example":1},"method":{"type":"string","enum":["initialize","tools/list","tools/call"],"example":"tools/list"},"params":{"type":"object","description":"Method-specific parameters. For tools/call: { name: \"<tool>\", arguments: { ... } }"}}}}}},"responses":{"200":{"description":"JSON-RPC 2.0 response or SSE stream"}},"summary":"MCP JSON-RPC endpoint","tags":["MCP"]},"get":{"description":"Server-Sent Events stream for MCP notifications.","operationId":"MCP SSE Stream","parameters":[],"responses":{"200":{"description":"SSE event stream"}},"summary":"MCP SSE stream endpoint","tags":["MCP"]},"delete":{"description":"Terminates an MCP session.","operationId":"MCP Session Delete","parameters":[],"responses":{"200":{"description":"Session terminated"}},"summary":"MCP session cleanup","tags":["MCP"]}},"/oauth/login":{"get":{"operationId":"OAuthLoginController_showLoginPage","parameters":[],"responses":{"200":{"description":""}},"tags":["OAuthLogin"]},"post":{"operationId":"OAuthLoginController_handleLogin","parameters":[],"responses":{"201":{"description":""}},"tags":["OAuthLogin"]}},"/oauth/revoke":{"post":{"operationId":"OAuthRevocationController_revoke","parameters":[],"responses":{"200":{"description":""}},"tags":["OAuthRevocation"]}},"/.well-known/oauth-protected-resource":{"get":{"operationId":"McpOAuthController_getProtectedResourceMetadata","parameters":[],"responses":{"200":{"description":""}},"tags":["McpOAuth"]}},"/.well-known/oauth-authorization-server":{"get":{"operationId":"McpOAuthController_getAuthorizationServerMetadata","parameters":[],"responses":{"200":{"description":""}},"tags":["McpOAuth"]}},"/oauth/register":{"post":{"operationId":"McpOAuthController_registerClient","parameters":[],"responses":{"201":{"description":""}},"tags":["McpOAuth"]}},"/oauth/authorize":{"get":{"operationId":"McpOAuthController_authorize","parameters":[],"responses":{"200":{"description":""}},"tags":["McpOAuth"]}},"/oauth/callback":{"get":{"operationId":"McpOAuthController_handleProviderCallback","parameters":[],"responses":{"200":{"description":""}},"tags":["McpOAuth"]}},"/oauth/token":{"post":{"operationId":"McpOAuthController_exchangeToken","parameters":[],"responses":{"200":{"description":""}},"tags":["McpOAuth"]}},"/api/v1/playground/top-pairs":{"get":{"description":"Powers the WebSocket playground pair picker. Returns the N most active instruments per exchange for the chosen market, computed from `v2_{market}_ohlcvt` over the last 24h. Requires an API key like any other endpoint — protected by the global `ApiKeyGuard` + rate limiter so the playground page can't be scraped anonymously. Server-side cached 1h (rankings barely shift hour-to-hour).","operationId":"PlaygroundController_getTopPairs","parameters":[{"name":"market","required":true,"in":"query","schema":{"enum":["futures","perpetuals","options","spot","predictions"],"type":"string"}},{"name":"limit","required":false,"in":"query","schema":{"type":"integer","minimum":1,"maximum":20,"default":5}}],"responses":{"200":{"description":"","content":{"application/json":{"schema":{"type":"object","properties":{"market":{"type":"string","enum":["futures","perpetuals","options","spot","predictions"]},"limit":{"type":"integer"},"exchanges":{"type":"object","additionalProperties":{"type":"array","items":{"type":"object","properties":{"instrument_name":{"type":"string"},"volume_24h":{"type":"number"},"last_price":{"type":"number"}}}}}}}}}}},"summary":"Top instruments by 24h volume per exchange","tags":["Playground"]}}},"info":{"title":"Laevitas API V2","description":"\nProfessional 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\nMost data endpoints also support x402 pay-per-request without an API key.\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| 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\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```\n","version":"1.33.0","contact":{"name":"Laevitas Support","url":"https://laevitas.ch","email":"support@laevitas.ch"}},"tags":[{"name":"Instruments","description":"Cross-market contract reference data — tick size, lot size, leverage, expiry, margin type"},{"name":"Macro","description":"Discovery for non-crypto perpetuals — equity (NVDA, TSLA, MSTR…), commodity (GOLD, OIL, SILVER…), forex (EURUSD, GBPUSD…), and index. Pull data via /perpetuals/* with the discovered instrument names."},{"name":"Spot","description":"Spot market data — OHLCVT, ticker, trades, volume, orderbook, and snapshots"},{"name":"Futures","description":"Futures market data, reference prices, and analytics"},{"name":"Perpetuals","description":"Perpetual swap market data, funding rates, basis, and carry"},{"name":"Options","description":"Options market data, Greeks, and volatility analytics"},{"name":"Vol Surface","description":"Proprietary volatility surface data and live portfolio risk — snapshots, slices, term structure, strikes, decomposition, scenarios, and ladders."},{"name":"Predictions","description":"Prediction market data — Polymarket events, categories, and ticker history"},{"name":"Hyperliquid - HyperCore","description":"Hyperliquid L1 native trading data from HyperCore — wallet-attributed fills, liquidations, positions, funding payments, TWAP events, resting orders, and deep HyperCore-derived L2 books."},{"name":"Analytics","description":"Computed cross-asset analytics and derived market metrics"},{"name":"MCP","description":"Model Context Protocol endpoint for AI agent tool calls (Streamable HTTP transport)"},{"name":"OAuthLogin","description":"OAuth 2.1 login flow for the MCP endpoint"},{"name":"McpOAuth","description":"OAuth 2.1 metadata, registration, authorization, and token endpoints for MCP clients"}],"servers":[{"url":"https://apiv2.laevitas.ch","description":"Production"},{"url":"https://apiv2.devitas.ch","description":"Development"}],"components":{"securitySchemes":{"X-API-Key":{"type":"apiKey","in":"header","name":"X-API-Key","description":"API key for authentication. Contact support to obtain a key."}},"schemas":{"WsPassResponseDto":{"type":"object","properties":{"expires_at":{"type":"number","example":1730412345678,"description":"New pass expiry as unix epoch milliseconds. Source of truth."},"expires_at_iso":{"type":"string","example":"2026-04-30T18:25:45.678Z","description":"Human-readable form of expires_at. Equivalent to new Date(expires_at).toISOString()."},"duration":{"type":"string","example":"hour","enum":["hour","day"],"description":"Which SKU was purchased on this call. Stacking is additive, so the resulting pass duration may exceed this single SKU."},"wallet":{"type":"string","example":"0xabcdef0123456789abcdef0123456789abcdef01","description":"Wallet that owns the pass (lowercase, EVM checksum stripped)."},"extended_from":{"type":"number","example":1730408745678,"description":"If this purchase extended an existing active pass, the previous expires_at. Omitted when no prior pass was active."}},"required":["expires_at","expires_at_iso","duration","wallet"]},"PaginationMetaEntity":{"type":"object","properties":{"next_cursor":{"type":"string","description":"Pagination cursor for fetching the next page of results. Pass this value as the cursor parameter in the next request. Null indicates no more pages.","example":"eyJpZCI6MTIzNDU2NzgsInRzIjoxNjQwOTk1MjAwfQ==","nullable":true}},"required":["next_cursor"]},"PaginatedResponse":{"type":"object","properties":{"data":{"type":"array","items":{"type":"array"}},"meta":{"$ref":"#/components/schemas/PaginationMetaEntity"}},"required":["data","meta"]},"OptionsOhlcvtEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-14AUG26"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"open":{"type":"number","description":"Opening trade price in the time bucket","example":42150.5},"high":{"type":"number","description":"Highest trade price in the time bucket","example":42890.75},"low":{"type":"number","description":"Lowest trade price in the time bucket","example":41920.25},"close":{"type":"number","description":"Closing trade price in the time bucket","example":42500},"vwap":{"type":"number","description":"Volume Weighted Average Price (VWAP)","example":42350.5},"volume":{"type":"number","description":"Total volume (buy + sell)","example":2700.8},"buy_volume":{"type":"number","description":"Buy-side volume (direction = buy)","example":1500.5},"sell_volume":{"type":"number","description":"Sell-side volume (direction = sell)","example":1200.3},"trades_count":{"type":"number","description":"Total number of trades (buy + sell)","example":270},"buy_trades_count":{"type":"number","description":"Number of buy trades","example":150},"sell_trades_count":{"type":"number","description":"Number of sell trades","example":120},"liquidation_short_volume":{"type":"number","description":"Volume from short liquidations (forced buy orders)","example":50.25,"nullable":true},"liquidation_long_volume":{"type":"number","description":"Volume from long liquidations (forced sell orders)","example":75.5,"nullable":true},"block_trade_buy_volume":{"type":"number","description":"Volume from block trade buys","example":100,"nullable":true},"block_trade_sell_volume":{"type":"number","description":"Volume from block trade sells","example":150,"nullable":true},"mark_price":{"type":"number","description":"Mark price at bar close (for reference)","example":42500.5,"nullable":true},"index_price":{"type":"number","description":"Index price at bar close (for reference)","example":42505,"nullable":true},"days_to_expiry":{"type":"number","description":"Days until expiry (NULL for PERPETUAL)","example":90.5,"nullable":true}},"required":["date","open","high","low","close","vwap","volume","buy_volume","sell_volume","trades_count","buy_trades_count","sell_trades_count"]},"BaseVolumeDataEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-14AUG26"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"volume_24h":{"type":"number","description":"24-hour rolling volume (base currency)","example":1500.25},"volume_usd_24h":{"type":"number","description":"24-hour rolling volume in USD terms","example":95000000.5,"nullable":true},"buy_volume":{"type":"number","description":"Buy volume in the resolution bucket","example":750.12,"nullable":true},"sell_volume":{"type":"number","description":"Sell volume in the resolution bucket","example":680.5,"nullable":true},"volume":{"type":"number","description":"Total volume (buy + sell) in the resolution bucket","example":1430.62,"nullable":true},"buy_trades_count":{"type":"number","description":"Number of buy trades in the resolution bucket","example":245,"nullable":true},"sell_trades_count":{"type":"number","description":"Number of sell trades in the resolution bucket","example":198,"nullable":true},"trades_count":{"type":"number","description":"Total number of trades in the resolution bucket","example":443,"nullable":true}},"required":["date","volume_24h"]},"OptionsTradeEntity":{"type":"object","properties":{"instrument_name":{"type":"string","description":"Instrument identifier","example":"BTC-14AUG26"},"timestamp":{"type":"number","description":"Unix timestamp in milliseconds","example":1234567890123},"date":{"type":"string","description":"ISO 8601 formatted date string","example":"2023-06-15T14:30:00.000Z"},"trade_id":{"type":"string","description":"Unique trade identifier","example":"trade_123456"},"block_trade_id":{"type":"string","description":"Block trade identifier if applicable","example":"block_123"},"combo_id":{"type":"string","description":"Combo trade identifier if applicable","example":"combo_123"},"combo_trade_id":{"type":"string","description":"Combo trade ID if part of combo","example":"combo_trade_123"},"strategy":{"type":"string","description":"Trading strategy identifier","example":"strategy_1"},"direction":{"type":"string","description":"Trade direction","enum":["buy","sell"],"example":"buy"},"tick_direction":{"type":"object","description":"Tick direction indicator","example":1,"nullable":true},"amount":{"type":"number","description":"Trade amount/size","example":1.5},"price":{"type":"number","description":"Trade execution price","example":45000.5},"index_price":{"type":"object","description":"Index price at time of trade","example":45010,"nullable":true},"oi_change":{"type":"object","description":"Change in open interest","example":100,"nullable":true},"open_interest":{"type":"object","description":"Open interest after trade","example":10000,"nullable":true},"oi_before":{"type":"object","description":"Open interest before trade","example":9900,"nullable":true}},"required":["instrument_name","timestamp","date","trade_id","direction","amount","price"]},"BaseOpenInterestEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-14AUG26"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"oi_open":{"type":"number","description":"Open interest at time bucket start (base units)","example":22000.1},"oi_high":{"type":"number","description":"Highest open interest during time bucket (base units)","example":22500.3},"oi_low":{"type":"number","description":"Lowest open interest during time bucket (base units)","example":21950},"oi_close":{"type":"number","description":"Open interest at time bucket end (base units)","example":22350.5}},"required":["date","oi_open","oi_high","oi_low","oi_close"]},"OptionsFlowBucketEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"trade_count":{"type":"number","description":"Total number of trades in bucket"},"buy_count":{"type":"number","description":"Number of buy trades"},"sell_count":{"type":"number","description":"Number of sell trades"},"total_amount":{"type":"number","description":"Total trade amount (contracts)"},"buy_amount":{"type":"number","description":"Buy side amount (contracts)"},"sell_amount":{"type":"number","description":"Sell side amount (contracts)"},"total_premium_usd":{"type":"number","description":"Total premium in USD"},"buy_premium_usd":{"type":"number","description":"Buy side premium in USD"},"sell_premium_usd":{"type":"number","description":"Sell side premium in USD"},"total_notional":{"type":"number","description":"Total notional in USD"},"buy_notional":{"type":"number","description":"Buy side notional in USD"},"sell_notional":{"type":"number","description":"Sell side notional in USD"},"call_premium_usd":{"type":"number","description":"Call option premium in USD"},"put_premium_usd":{"type":"number","description":"Put option premium in USD"},"call_count":{"type":"number","description":"Number of call option trades"},"put_count":{"type":"number","description":"Number of put option trades"},"block_trade_count":{"type":"number","description":"Number of block trades"},"block_premium_usd":{"type":"number","description":"Block trade premium in USD"},"net_oi_change":{"type":"number","description":"Net open interest change"},"avg_iv":{"type":"object","description":"Average implied volatility","nullable":true},"avg_abs_delta":{"type":"object","description":"Average absolute delta","nullable":true}},"required":["date","trade_count","buy_count","sell_count","total_amount","buy_amount","sell_amount","total_premium_usd","buy_premium_usd","sell_premium_usd","total_notional","buy_notional","sell_notional","call_premium_usd","put_premium_usd","call_count","put_count","block_trade_count","block_premium_usd","net_oi_change","avg_iv","avg_abs_delta"]},"OptionsFlowActiveStrikeEntity":{"type":"object","properties":{"instrument_name":{"type":"string","description":"Instrument name"},"trade_count":{"type":"number","description":"Number of trades on this instrument"},"premium_usd":{"type":"number","description":"Total premium in USD"},"net_oi_change":{"type":"number","description":"Net open interest change"}},"required":["instrument_name","trade_count","premium_usd","net_oi_change"]},"OptionsFlowSummaryEntity":{"type":"object","properties":{"start":{"type":"string","description":"Start of aggregation window (ISO 8601 UTC)","example":"2026-03-11T10:00:00.000Z"},"end":{"type":"string","description":"End of aggregation window (ISO 8601 UTC)","example":"2026-03-18T10:00:00.000Z"},"resolution":{"type":"string","description":"Resolution used for time buckets","example":"1h"},"total_trades":{"type":"number","description":"Total number of trades in window"},"total_premium_usd":{"type":"number","description":"Total premium across all trades in USD"},"total_notional_usd":{"type":"number","description":"Total notional across all trades in USD"},"call_premium_usd":{"type":"number","description":"Total premium for call options in USD"},"put_premium_usd":{"type":"number","description":"Total premium for put options in USD"},"buy_premium_usd":{"type":"number","description":"Total premium for buy-side trades in USD"},"sell_premium_usd":{"type":"number","description":"Total premium for sell-side trades in USD"},"net_delta":{"type":"number","description":"Net delta across all trades"},"net_gamma":{"type":"number","description":"Net gamma across all trades"},"net_vega":{"type":"number","description":"Net vega across all trades"},"opening_trades":{"type":"number","description":"Number of opening trades (strategy starts with Opened)"},"closing_trades":{"type":"number","description":"Number of closing trades (strategy starts with Closed)"},"net_oi_change":{"type":"number","description":"Net open interest change"},"block_trade_count":{"type":"number","description":"Number of block trades"},"block_trade_premium_usd":{"type":"number","description":"Block trade premium in USD"},"most_active_strikes":{"description":"Most active instruments by premium","type":"array","items":{"$ref":"#/components/schemas/OptionsFlowActiveStrikeEntity"}}},"required":["start","end","resolution","total_trades","total_premium_usd","total_notional_usd","call_premium_usd","put_premium_usd","buy_premium_usd","sell_premium_usd","net_delta","net_gamma","net_vega","opening_trades","closing_trades","net_oi_change","block_trade_count","block_trade_premium_usd","most_active_strikes"]},"OptionsGexCatalogEntity":{"type":"object","properties":{"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"first_date":{"type":"string","description":"Earliest available aggregate GEX timestamp","example":"2025-10-04T00:00:00.000Z"},"latest_date":{"type":"string","description":"Latest available aggregate GEX timestamp","example":"2026-06-15T10:06:00.000Z"},"row_count":{"type":"number","description":"Number of aggregate GEX rows available for this currency/venue","example":318224},"spot":{"type":"number","description":"Latest spot price used for the GEX calculation","example":65651.87},"total_gex":{"type":"number","description":"Latest total dealer gamma exposure per 1% underlying move","example":-4542768.08},"net_long_gex":{"type":"number","description":"Latest positive dealer GEX contribution","example":19984373.25},"net_short_gex":{"type":"number","description":"Latest negative dealer GEX contribution","example":-24527141.33},"regime":{"type":"string","description":"Latest dealer regime classification","example":"neutral"}},"required":["currency","exchange","market","first_date","latest_date","row_count","spot","total_gex","net_long_gex","net_short_gex","regime"]},"OptionsGexIndexEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"spot":{"type":"number","description":"Spot price used for the GEX calculation","example":65651.87},"total_gex":{"type":"number","description":"Total dealer gamma exposure per 1% underlying move, USD-normalized","example":-4542768.08},"net_long_gex":{"type":"number","description":"Positive dealer GEX contribution","example":19984373.25},"net_short_gex":{"type":"number","description":"Negative dealer GEX contribution","example":-24527141.33},"regime":{"type":"string","description":"Dealer regime classification","example":"neutral"}},"required":["date","currency","exchange","market","spot","total_gex","net_long_gex","net_short_gex","regime"]},"OptionsGexProfileEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"spot":{"type":"number","description":"Spot price used for the GEX calculation","example":65651.87},"total_gex":{"type":"number","description":"Total dealer gamma exposure per 1% underlying move, USD-normalized","example":-4542768.08},"net_long_gex":{"type":"number","description":"Positive dealer GEX contribution","example":19984373.25},"net_short_gex":{"type":"number","description":"Negative dealer GEX contribution","example":-24527141.33},"regime":{"type":"string","description":"Dealer regime classification","example":"neutral"},"profile_group":{"type":"string","description":"Profile group, usually 'all_expiries' or an expiry code","example":"all_expiries"},"strike_label":{"type":"string","description":"Original profile strike token produced by the dealer worker","example":"65000"},"strike":{"type":"number","description":"Numeric strike parsed from strike_label","example":65000},"gex":{"type":"number","description":"Legacy raw interpolated GEX value at this profile strike. Use weighted_gex for the dealer-model weighted profile.","example":-1200000},"raw_gex":{"type":"number","description":"Raw interpolated GEX value at this profile strike before dealer-model weighting","example":-1200000},"weighted_gex":{"type":"number","description":"Dealer-model weighted interpolated GEX value at this profile strike","example":-1037880},"min_strike":{"type":"number","description":"Minimum strike in the interpolated profile domain","example":40000},"max_strike":{"type":"number","description":"Maximum strike in the interpolated profile domain","example":90000},"interpolator":{"type":"string","description":"Interpolation method used by the dealer worker","example":"pchip"}},"required":["date","currency","exchange","market","spot","total_gex","net_long_gex","net_short_gex","regime","profile_group","strike_label","strike","gex","raw_gex","weighted_gex","min_strike","max_strike","interpolator"]},"OptionsGexRegimeChangeEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"spot":{"type":"number","description":"Spot price used for the GEX calculation","example":65651.87},"total_gex":{"type":"number","description":"Total dealer gamma exposure per 1% underlying move, USD-normalized","example":-4542768.08},"net_long_gex":{"type":"number","description":"Positive dealer GEX contribution","example":19984373.25},"net_short_gex":{"type":"number","description":"Negative dealer GEX contribution","example":-24527141.33},"regime":{"type":"string","description":"Dealer regime classification","example":"neutral"},"previous_regime":{"type":"string","description":"Previous regime before the transition","example":"positive"}},"required":["date","currency","exchange","market","spot","total_gex","net_long_gex","net_short_gex","regime","previous_regime"]},"OptionsGexStrikeContributionEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"spot":{"type":"number","description":"Spot price used for the GEX calculation","example":65651.87},"total_gex":{"type":"number","description":"Total dealer gamma exposure per 1% underlying move, USD-normalized","example":-4542768.08},"net_long_gex":{"type":"number","description":"Positive dealer GEX contribution","example":19984373.25},"net_short_gex":{"type":"number","description":"Negative dealer GEX contribution","example":-24527141.33},"regime":{"type":"string","description":"Dealer regime classification","example":"neutral"},"expiry":{"type":"string","description":"Expiry code, or 'all_expiries' for the aggregate view","example":"all_expiries"},"is_aggregate":{"type":"boolean","description":"True when this row belongs to the aggregate all-expiries view","example":true},"strike_label":{"type":"string","description":"Original strike token produced by the dealer worker","example":"65000"},"strike":{"type":"number","description":"Numeric strike parsed from strike_label","example":65000},"contribution":{"type":"number","description":"Legacy raw GEX contribution for this strike bucket. Use weighted_contribution to reconcile with aggregate total_gex.","example":-1500000},"pos_contribution":{"type":"number","description":"Legacy raw positive GEX contribution for this strike bucket.","example":200000},"neg_contribution":{"type":"number","description":"Legacy raw negative GEX contribution for this strike bucket.","example":-1700000},"raw_contribution":{"type":"number","description":"Raw GEX contribution before dealer-model weighting","example":-1500000},"raw_pos_contribution":{"type":"number","description":"Raw positive GEX contribution before dealer-model weighting","example":200000},"raw_neg_contribution":{"type":"number","description":"Raw negative GEX contribution before dealer-model weighting","example":-1700000},"weighted_contribution":{"type":"number","description":"Dealer-model weighted GEX contribution. Sum per-expiry weighted_contribution rows to reconcile with aggregate total_gex.","example":-1297350},"weighted_pos_contribution":{"type":"number","description":"Dealer-model weighted positive GEX contribution.","example":172980},"weighted_neg_contribution":{"type":"number","description":"Dealer-model weighted negative GEX contribution.","example":-1470330},"moneyness_weight":{"type":"number","description":"Moneyness weighting used by the dealer model","example":0.93},"expiry_weight":{"type":"number","description":"Expiry weighting used by the dealer model; zero on all_expiries rows","example":0}},"required":["date","currency","exchange","market","spot","total_gex","net_long_gex","net_short_gex","regime","expiry","is_aggregate","strike_label","strike","contribution","pos_contribution","neg_contribution","raw_contribution","raw_pos_contribution","raw_neg_contribution","weighted_contribution","weighted_pos_contribution","weighted_neg_contribution","moneyness_weight","expiry_weight"]},"OptionsGexTermStructureEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"currency":{"type":"string","description":"Dealer-worker currency","example":"BTC"},"exchange":{"type":"string","description":"Venue name resolved from dealer market id","example":"deribit"},"market":{"type":"number","description":"Dealer market id. 0 maps to Deribit.","example":0},"expiry":{"type":"string","description":"Expiry code","example":"27JUN26"},"total_gex":{"type":"number","description":"Legacy raw total GEX contribution for this expiry. Use weighted_total_gex to reconcile with aggregate total_gex.","example":-1500000},"net_long_gex":{"type":"number","description":"Legacy raw positive GEX contribution for this expiry","example":200000},"net_short_gex":{"type":"number","description":"Legacy raw negative GEX contribution for this expiry","example":-1700000},"raw_total_gex":{"type":"number","description":"Raw total GEX contribution for this expiry before dealer-model weighting","example":-1500000},"raw_net_long_gex":{"type":"number","description":"Raw positive GEX contribution for this expiry before dealer-model weighting","example":200000},"raw_net_short_gex":{"type":"number","description":"Raw negative GEX contribution for this expiry before dealer-model weighting","example":-1700000},"weighted_total_gex":{"type":"number","description":"Dealer-model weighted total GEX contribution for this expiry. Sum this field across expiries to reconcile with snapshot_total_gex.","example":-1297350},"weighted_net_long_gex":{"type":"number","description":"Dealer-model weighted positive GEX contribution for this expiry","example":172980},"weighted_net_short_gex":{"type":"number","description":"Dealer-model weighted negative GEX contribution for this expiry","example":-1470330},"strike_count":{"type":"number","description":"Number of strike buckets contributing to this expiry","example":43},"spot":{"type":"number","description":"Spot price used for this snapshot","example":65651.87},"snapshot_total_gex":{"type":"number","description":"Full-snapshot total GEX for context","example":-4542768.08}},"required":["date","currency","exchange","market","expiry","total_gex","net_long_gex","net_short_gex","raw_total_gex","raw_net_long_gex","raw_net_short_gex","weighted_total_gex","weighted_net_long_gex","weighted_net_short_gex","strike_count","spot","snapshot_total_gex"]},"MetadataResponseEntity":{"type":"object","properties":{"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-PERPETUAL"},"start_date":{"type":"string","description":"Start date of available data (ISO 8601 format)","example":"2020-01-01T00:00:00.000Z"},"end_date":{"type":"string","description":"End date of available data (ISO 8601 format)","example":"2025-11-21T23:59:00.000Z"},"total_count":{"type":"number","description":"Total count of records available","example":1500000},"total_pages":{"type":"number","description":"Total number of pages based on the provided limit","example":15000}},"required":["exchange","instrument_name","start_date","end_date","total_count","total_pages"]},"FuturesOhlcvtEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-14AUG26"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"open":{"type":"number","description":"Opening trade price in the time bucket","example":42150.5},"high":{"type":"number","description":"Highest trade price in the time bucket","example":42890.75},"low":{"type":"number","description":"Lowest trade price in the time bucket","example":41920.25},"close":{"type":"number","description":"Closing trade price in the time bucket","example":42500},"vwap":{"type":"number","description":"Volume Weighted Average Price (VWAP)","example":42350.5},"volume":{"type":"number","description":"Total volume (buy + sell)","example":2700.8},"buy_volume":{"type":"number","description":"Buy-side volume (direction = buy)","example":1500.5},"sell_volume":{"type":"number","description":"Sell-side volume (direction = sell)","example":1200.3},"trades_count":{"type":"number","description":"Total number of trades (buy + sell)","example":270},"buy_trades_count":{"type":"number","description":"Number of buy trades","example":150},"sell_trades_count":{"type":"number","description":"Number of sell trades","example":120},"liquidation_short_volume":{"type":"number","description":"Volume from short liquidations (forced buy orders)","example":50.25,"nullable":true},"liquidation_long_volume":{"type":"number","description":"Volume from long liquidations (forced sell orders)","example":75.5,"nullable":true},"block_trade_buy_volume":{"type":"number","description":"Volume from block trade buys","example":100,"nullable":true},"block_trade_sell_volume":{"type":"number","description":"Volume from block trade sells","example":150,"nullable":true},"mark_price":{"type":"number","description":"Mark price at bar close (for reference)","example":42500.5,"nullable":true},"index_price":{"type":"number","description":"Index price at bar close (for reference)","example":42505,"nullable":true},"days_to_expiry":{"type":"number","description":"Days until expiry (NULL for PERPETUAL)","example":90.5,"nullable":true}},"required":["date","open","high","low","close","vwap","volume","buy_volume","sell_volume","trades_count","buy_trades_count","sell_trades_count"]},"VolSurfaceEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"maturity":{"type":"string","description":"Maturity date string","example":"14AUG26"},"days_to_expiry":{"type":"number","description":"Days until expiry","example":25.5},"underlying_price":{"type":"number","description":"Underlying asset price","example":103722.83},"atm_iv":{"type":"number","description":"At-the-money implied volatility (call with delta closest to 0.5)","example":47.62,"nullable":true},"call_25d_iv":{"type":"number","description":"25-delta call implied volatility","example":43.8,"nullable":true},"put_25d_iv":{"type":"number","description":"25-delta put implied volatility","example":52.1,"nullable":true},"skew_25d":{"type":"number","description":"25-delta skew (put_25d_iv - call_25d_iv)","example":8.3,"nullable":true},"butterfly_25d":{"type":"number","description":"25-delta butterfly ((call_25d_iv + put_25d_iv) / 2 - atm_iv)","example":0.33,"nullable":true},"call_10d_iv":{"type":"number","description":"10-delta call implied volatility","example":40.1,"nullable":true},"put_10d_iv":{"type":"number","description":"10-delta put implied volatility","example":58.3,"nullable":true},"skew_10d":{"type":"number","description":"10-delta skew (put_10d_iv - call_10d_iv)","example":18.2,"nullable":true},"butterfly_10d":{"type":"number","description":"10-delta butterfly ((call_10d_iv + put_10d_iv) / 2 - atm_iv)","example":1.58,"nullable":true}},"required":["date","exchange","currency","maturity","days_to_expiry","underlying_price"]},"TermStructureEntity":{"type":"object","properties":{"date":{"type":"string","description":"ISO 8601 timestamp for this data point (present in time-series mode only)","example":"2026-02-01T12:00:00.000Z","nullable":true},"tenor":{"type":"number","description":"Constant-maturity tenor in days","example":30},"atm_iv":{"type":"number","description":"Interpolated ATM implied volatility at this tenor","example":38.55,"nullable":true},"call_25d_iv":{"type":"number","description":"Interpolated 25-delta call implied volatility at this tenor","example":36.2,"nullable":true},"put_25d_iv":{"type":"number","description":"Interpolated 25-delta put implied volatility at this tenor","example":41.9,"nullable":true},"skew_25d":{"type":"number","description":"25-delta skew (put_25d_iv - call_25d_iv)","example":5.7,"nullable":true},"butterfly_25d":{"type":"number","description":"25-delta butterfly ((call_25d_iv + put_25d_iv) / 2 - atm_iv)","example":0.5,"nullable":true},"call_10d_iv":{"type":"number","description":"Interpolated 10-delta call implied volatility at this tenor","example":33.1,"nullable":true},"put_10d_iv":{"type":"number","description":"Interpolated 10-delta put implied volatility at this tenor","example":48.5,"nullable":true},"skew_10d":{"type":"number","description":"10-delta skew (put_10d_iv - call_10d_iv)","example":15.4,"nullable":true},"butterfly_10d":{"type":"number","description":"10-delta butterfly ((call_10d_iv + put_10d_iv) / 2 - atm_iv)","example":2.25,"nullable":true}},"required":["tenor"]},"SpotOhlcvtEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"instrument_name":{"type":"string","description":"Instrument name","example":"BTC-14AUG26"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"open":{"type":"number","description":"Opening trade price in the time bucket","example":42150.5},"high":{"type":"number","description":"Highest trade price in the time bucket","example":42890.75},"low":{"type":"number","description":"Lowest trade price in the time bucket","example":41920.25},"close":{"type":"number","description":"Closing trade price in the time bucket","example":42500},"vwap":{"type":"number","description":"Volume Weighted Average Price (VWAP)","example":42350.5},"volume":{"type":"number","description":"Total volume in base currency (buy + sell)","example":2700.8},"buy_volume":{"type":"number","description":"Buy-side volume in base currency","example":1500.5},"sell_volume":{"type":"number","description":"Sell-side volume in base currency","example":1200.3},"quote_volume":{"type":"number","description":"Total volume in quote currency (buy + sell)","example":114500000},"buy_quote_volume":{"type":"number","description":"Buy-side volume in quote currency","example":63500000},"sell_quote_volume":{"type":"number","description":"Sell-side volume in quote currency","example":51000000},"trades_count":{"type":"number","description":"Total number of trades (buy + sell)","example":270},"buy_trades_count":{"type":"number","description":"Number of buy trades","example":150},"sell_trades_count":{"type":"number","description":"Number of sell trades","example":120},"first_trade_id":{"type":"string","description":"First trade ID in the time bucket","example":"trade_100001"},"last_trade_id":{"type":"string","description":"Last trade ID in the time bucket","example":"trade_100270"},"data_source":{"type":"string","description":"Data source identifier","example":"rest"},"quote_currency":{"type":"string","description":"Quote currency","example":"USDT"}},"required":["date","open","high","low","close","vwap","volume","buy_volume","sell_volume","quote_volume","buy_quote_volume","sell_quote_volume","trades_count","buy_trades_count","sell_trades_count","first_trade_id","last_trade_id","data_source","quote_currency"]},"RealizedVolatilityEntity":{"type":"object","properties":{"date":{"type":"string","description":"Date in ISO 8601 format (UTC)","example":"2024-12-10T00:00:00.000Z","format":"date-time"},"exchange":{"type":"string","description":"Exchange name","example":"deribit"},"currency":{"type":"string","description":"Base currency","example":"BTC"},"instrument_name":{"type":"string","description":"Full instrument identifier","example":"BTC-PERPETUAL"},"frequency":{"type":"string","description":"Sampling frequency used to compute realised volatility","example":"daily"},"window_days":{"type":"number","description":"Realised volatility lookback window in days","example":30},"estimator":{"type":"string","description":"Realised volatility estimator","example":"close_to_close"},"rv_annualized":{"type":"number","description":"Annualized realised volatility, expressed as a percentage (e.g. 38.76 = 38.76% annualised vol).","example":38.76},"sample_count":{"type":"number","description":"Number of samples used to compute the metric","example":30}},"required":["date","exchange","currency","instrument_name","frequency","window_days","estimator","rv_annualized","sample_count"]},"VolSurfaceCatalogEntity":{"type":"object","properties":{"exchange":{"type":"string","example":"deribit"},"currency":{"type":"string","example":"BTC"},"margin":{"type":"string","example":"inverse","enum":["inverse","linear"]},"model":{"type":"string","example":"svi"},"date":{"type":"object","example":"2026-06-08T12:00:00.000Z","format":"date-time"},"index_price":{"type":"object","example":104000.25},"n_slices":{"type":"object","example":10},"n_forward_knots":{"type":"object","example":7}},"required":["exchange","currency","margin","model","date","index_price","n_slices","n_forward_knots"]},"VolSurfaceSnapshotEntity":{"type":"object","properties":{"date":{"type":"object","example":"2026-06-08T12:00:00.000Z","format":"date-time"},"exchange":{"type":"string","example":"deribit"},"currency":{"type":"string","example":"BTC"},"margin":{"type":"string","example":"inverse","enum":["inverse","linear"]},"model":{"type":"string","example":"svi"},"index_price":{"type":"object","example":104000.25},"n_slices":{"type":"object","example":10},"n_forward_knots":{"type":"object","example":7},"calendar_arb_pairs_checked":{"type":"object","example":9},"calendar_arb_violating_pairs":{"type":"object","example":0},"calendar_arb_in_range_violations":{"type":"object","example":0},"calendar_arb_max_excess":{"type":"object","example":0},"forward_curve":{"type":"object","description":"Forward curve JSON decoded when possible."}},"required":["date","exchange","currency","margin","model","index_price","n_slices","n_forward_knots","calendar_arb_pairs_checked","calendar_arb_violating_pairs","calendar_arb_in_range_violations","calendar_arb_max_excess"]},"VolSurfaceSliceEntity":{"type":"object","properties":{"date":{"type":"object","example":"2026-06-08T12:00:00.000Z","format":"date-time"},"exchange":{"type":"string","example":"deribit"},"currency":{"type":"string","example":"BTC"},"margin":{"type":"string","example":"inverse","enum":["inverse","linear"]},"model":{"type":"string","example":"svi"},"model_params":{"type":"object","description":"Model-native parameter JSON decoded when possible."},"expiry":{"type":"object","example":"2026-06-26T08:00:00.000Z","format":"date-time"}},"required":["date","exchange","currency","margin","model","expiry"]},"VolSurfaceTermStructureRowEntity":{"type":"object","properties":{"date":{"type":"object","example":"2026-06-08T12:00:00.000Z","format":"date-time"},"exchange":{"type":"string","example":"deribit"},"currency":{"type":"string","example":"BTC"},"margin":{"type":"string","example":"inverse","enum":["inverse","linear"]},"tenor_days":{"type":"object","example":30}},"required":["date","exchange","currency","margin","tenor_days"]},"VolSurfaceStrikeEntity":{"type":"object","properties":{"date":{"type":"object","example":"2026-06-08T12:00:00.000Z","format":"date-time"},"exchange":{"type":"string","example":"deribit"},"currency":{"type":"string","example":"BTC"},"margin":{"type":"string","example":"inverse","enum":["inverse","linear"]},"expiry":{"type":"object","example":"2026-06-26T08:00:00.000Z","format":"date-time"},"instrument":{"type":"string","example":"BTC-26JUN26-100000-C"},"strike":{"type":"object","example":100000},"option_type":{"type":"string","example":"C","enum":["C","P"]}},"required":["date","exchange","currency","margin","expiry","instrument","strike","option_type"]},"VolSurfaceRiskPositionDto":{"type":"object","properties":{"instrument":{"type":"string","description":"Instrument identifier.","example":"BTC-26JUN26-100000-C"},"kind":{"type":"string","description":"Position kind. Empty defaults to option in the engine.","enum":["option","perpetual","future","spot"],"default":"option"},"exchange":{"type":"string","description":"Exchange. Defaults from the request if omitted.","example":"deribit"},"currency":{"type":"string","description":"Base currency. Defaults from the request if omitted.","example":"BTC"},"margin":{"type":"string","description":"Margin book. Spot must be linear; options/perps/futures default to inverse when omitted by the engine.","enum":["inverse","linear"],"example":"inverse"},"strike":{"type":"number","description":"Option strike. Required for option positions.","example":100000},"expiry":{"type":"string","description":"Option or dated future expiry. Accepts ISO 8601 (2026-06-26T08:00:00Z or 2026-06-26) or any exchange-native date code: DDMMMYY (26JUN26), YYMMDD (260626), YYYYMMDD (20260626). Date-only forms resolve to 08:00 UTC settlement. Omit on an option to derive it from the instrument name.","example":"26JUN26"},"option_type":{"type":"string","description":"Option type. Required for option positions.","enum":["C","P"],"example":"C"},"quantity":{"type":"number","description":"Position quantity. Positive is long, negative is short.","example":2.5},"entry_price":{"type":"number","description":"Entry price for PnL calculations.","example":0.075},"entry_spot":{"type":"number","description":"Entry spot used for inverse PnL conversion.","example":96000},"mark_price":{"type":"number","description":"Current mark price for delta-one positions.","example":104000},"funding_pnl_usd":{"type":"number","description":"Caller-supplied realized funding PnL in USD.","example":-12.5},"funding_pnl_coin":{"type":"number","description":"Caller-supplied realized funding PnL in coin.","example":-0.00012}},"required":["instrument","quantity"]},"VolSurfaceRiskDecomposeRequestDto":{"type":"object","properties":{"exchange":{"type":"string","description":"Exchange used for risk request routing.","example":"deribit"},"currency":{"type":"string","description":"Base currency used for risk request routing.","example":"BTC"},"positions":{"description":"Portfolio positions to price or risk-analyze.","type":"array","items":{"$ref":"#/components/schemas/VolSurfaceRiskPositionDto"}},"timeout_ms":{"type":"number","description":"Risk request timeout in milliseconds.","default":5000,"minimum":100,"maximum":30000}},"required":["exchange","currency","positions"]},"VolSurfaceScenarioShockDto":{"type":"object","properties":{"name":{"type":"string","description":"Scenario name.","example":"Crash"},"spot_shift_pct":{"type":"number","description":"Spot shift in percent.","example":-20},"level_shift_vol":{"type":"number","description":"Parallel volatility shift in vol points.","example":15,"default":0},"skew_shift":{"type":"number","description":"Skew shock.","example":-0.15,"default":0},"curvature_shift":{"type":"number","description":"Curvature shock.","example":0,"default":0},"time_decay_days":{"type":"number","description":"Time decay shock in days.","example":1,"default":0}},"required":["spot_shift_pct"]},"VolSurfaceRiskScenarioRequestDto":{"type":"object","properties":{"exchange":{"type":"string","description":"Exchange used for risk request routing.","example":"deribit"},"currency":{"type":"string","description":"Base currency used for risk request routing.","example":"BTC"},"positions":{"description":"Portfolio positions to price or risk-analyze.","type":"array","items":{"$ref":"#/components/schemas/VolSurfaceRiskPositionDto"}},"timeout_ms":{"type":"number","description":"Risk request timeout in milliseconds.","default":5000,"minimum":100,"maximum":30000},"shock":{"description":"Scenario shock definition.","allOf":[{"$ref":"#/components/schemas/VolSurfaceScenarioShockDto"}]}},"required":["exchange","currency","positions","shock"]},"VolSurfaceRiskLadderRequestDto":{"type":"object","properties":{"exchange":{"type":"string","description":"Exchange used for risk request routing.","example":"deribit"},"currency":{"type":"string","description":"Base currency used for risk request routing.","example":"BTC"},"positions":{"description":"Portfolio positions to price or risk-analyze.","type":"array","items":{"$ref":"#/components/schemas/VolSurfaceRiskPositionDto"}},"timeout_ms":{"type":"number","description":"Risk request timeout in milliseconds.","default":5000,"minimum":100,"maximum":30000},"spot_shifts_pct":{"description":"Spot-shift grid rows in percent.","example":[-20,-10,-5,0,5,10,20],"type":"array","items":{"type":"number"}},"vol_shifts":{"description":"Parallel vol-shift grid columns in vol points.","example":[-10,-5,0,5,10],"type":"array","items":{"type":"number"}},"skew_shift":{"type":"number","description":"Fixed skew shock applied to every cell.","example":0,"default":0},"curvature_shift":{"type":"number","description":"Fixed curvature shock applied to every cell.","example":0,"default":0},"time_decay_days":{"type":"number","description":"Fixed time decay applied to every cell, in days.","example":0,"default":0}},"required":["exchange","currency","positions","spot_shifts_pct","vol_shifts"]},"ErrorResponseDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP status code","example":400},"message":{"description":"Error message(s). Can be a string or array of validation errors","example":["symbol must be a string","exchange is required"],"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]},"error":{"type":"string","description":"Error type identifier","example":"Bad Request"},"timestamp":{"type":"string","description":"Timestamp when the error occurred","example":"2024-01-01T12:00:00Z","format":"date-time"},"path":{"type":"string","description":"API request path that caused the error","example":"/api/v1/ohlc/price"}},"required":["statusCode","message","error"]},"UnauthorizedErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP 401 status code","example":401,"default":401},"message":{"description":"Unauthorized error message","example":"Invalid API key","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"default":"Unauthorized"},"error":{"type":"string","description":"Error type","example":"Unauthorized","default":"Unauthorized"},"timestamp":{"type":"string","description":"Timestamp when the error occurred","example":"2024-01-01T12:00:00Z","format":"date-time"},"path":{"type":"string","description":"API request path that caused the error","example":"/api/v1/ohlc/price"}},"required":["statusCode","message","error"]},"RateLimitErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP 429 status code","example":429,"default":429},"message":{"description":"Rate limit error message","example":"Rate limit exceeded. Please retry after 60 seconds","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"default":"Too Many Requests"},"error":{"type":"string","description":"Error type","example":"Too Many Requests","default":"Too Many Requests"},"timestamp":{"type":"string","description":"Timestamp when the error occurred","example":"2024-01-01T12:00:00Z","format":"date-time"},"path":{"type":"string","description":"API request path that caused the error","example":"/api/v1/ohlc/price"},"retryAfter":{"type":"number","description":"Number of seconds to wait before retrying","example":60},"limit":{"type":"number","description":"Current rate limit quota","example":1000},"remaining":{"type":"number","description":"Number of requests remaining in current window","example":0}},"required":["statusCode","message","error"]},"ValidationErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP 400 status code","example":400,"default":400},"message":{"description":"Validation error messages","example":["symbol must be a string","interval must be one of: 1m, 5m, 15m, 30m, 1h, 4h, 6h, 1d"],"type":"array","items":{"oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}]}},"error":{"type":"string","description":"Error type","example":"Bad Request","default":"Bad Request"},"timestamp":{"type":"string","description":"Timestamp when the error occurred","example":"2024-01-01T12:00:00Z","format":"date-time"},"path":{"type":"string","description":"API request path that caused the error","example":"/api/v1/ohlc/price"}},"required":["statusCode","message","error"]},"ServerErrorDto":{"type":"object","properties":{"statusCode":{"type":"number","description":"HTTP 500 status code","example":500,"default":500},"message":{"description":"Internal server error message","example":"An unexpected error occurred. Please try again later.","oneOf":[{"type":"string"},{"type":"array","items":{"type":"string"}}],"default":"Internal Server Error"},"error":{"type":"string","description":"Error type","example":"Internal Server Error","default":"Internal Server Error"},"timestamp":{"type":"string","description":"Timestamp when the error occurred","example":"2024-01-01T12:00:00Z","format":"date-time"},"path":{"type":"string","description":"API request path that caused the error","example":"/api/v1/ohlc/price"},"errorId":{"type":"string","description":"Error tracking ID for support reference","example":"ERR-123456-ABCD"}},"required":["statusCode","message","error"]}}},"externalDocs":{"description":"Laevitas API documentation","url":"https://apiv2.laevitas.ch/redoc"}}