{ "openapi": "3.0.3", "info": { "title": "Hypercall Trading API", "description": "Options and perpetuals trading API with EIP-712 signature authentication.\n\n## Base URLs\n\n- **Local**: `http://localhost:3000`\n- **Staging**: `https://hypertheta-api-staging.fly.dev`\n\n## Content Types\n\n- **Requests**: `application/json` for write endpoints\n- **Responses**: `application/json`\n\n## Authentication\n\n### EIP-712 Signature (Write Operations)\n\nWrite operations require an EIP-712 typed signature in the request body:\n- `wallet`: The wallet address performing the action\n- `nonce`: Unique nonce for replay protection\n- `signature`: EIP-712 signature from wallet owner or authorized agent\n\n**Bulk endpoints** verify signatures per-item in the handler (not via middleware).\n\n### Wallet Query Parameter (Read Operations)\n\nRead endpoints are public and accept query parameters (including `wallet`) without proof of ownership. No ownership verification for read endpoints; treat as sensitive data.\n\n### Agent Authorization\n\nA signer is authorized if:\n- `signer == wallet` (direct signing), OR\n- Signer is listed in `agent_authorizations` table with `is_active=true` and not expired\n\n## Price and Size Encoding\n\n**For signed endpoints**:\n- `price` and `size` **MUST be strings** in JSON\n- Must match exactly what was signed (string formatting matters)\n- Price must have ≤ 5 significant figures\n\n**Size conversion**: Human-readable size → contract units: `(size * 1_000_000) as u64` (truncates)\n\n**Orderbook size units**: `/orderbook`, `/expiry-summary`, and WebSocket `OrderbookUpdate` sizes are human-readable contracts.\n\n## Symbol Format\n\nOptions symbols: `UNDERLYING-YYYYMMDD-STRIKE-(C|P)`\n\nAlso accepts Deribit-style expiry `DDMMMYY` (e.g., `BTC-30AUG25-95000-C`)\n\n## Time in Force\n\n- `gtc`: Good Till Cancelled\n- `ioc`: Immediate or Cancel\n- `fok`: Fill or Kill\n\n## Rate Limits\n\nRate limiting is not enforced; self-throttle as needed.", "contact": { "name": "Hypercall", "url": "https://hypercall.xyz" }, "license": { "name": "Proprietary" }, "version": "0.0.1" }, "servers": [ { "url": "https://testnet-api.hypercall.xyz", "description": "Testnet" } ], "paths": { "/approve-agent": { "post": { "tags": [ "Agents" ], "summary": "Approve an agent to act on behalf of a wallet", "operationId": "approve_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent approved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApproveAgentResponse" } } } }, "400": { "description": "Invalid signature" } } } }, "/authorized-agents": { "get": { "tags": [ "Agents" ], "summary": "Get list of authorized agents for a wallet", "operationId": "get_authorized_agents", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to get authorized agents for", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "List of authorized agents", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizedAgentsResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/bulk_order": { "post": { "tags": [ "Trading" ], "summary": "Place multiple orders in a single request", "operationId": "bulk_place_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPlaceOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk order results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkPlaceOrderResponse" } } } }, "400": { "description": "Invalid request (e.g., too many orders)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] }, "delete": { "tags": [ "Trading" ], "summary": "Cancel multiple orders by order_id in a single request", "operationId": "bulk_cancel_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCancelOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk cancel results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCancelOrderResponse" } } } }, "400": { "description": "Invalid request (e.g., too many cancels)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/bulk_order_cloid": { "delete": { "tags": [ "Trading" ], "summary": "Cancel multiple orders by client_id in a single request", "operationId": "bulk_cancel_order_by_cloid", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCancelOrderByCloidRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk cancel results", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkCancelOrderResponse" } } } }, "400": { "description": "Invalid request (e.g., too many cancels)" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/cancel": { "post": { "tags": [ "Trading" ], "summary": "Cancel an order by order ID", "operationId": "cancel_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Order cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateMessage" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/cancel-by-cloid": { "post": { "tags": [ "Trading" ], "summary": "Cancel an order by client order ID", "operationId": "cancel_order_by_cloid", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderByCloidRequest" } } }, "required": true }, "responses": { "200": { "description": "Order cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateMessage" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/candles": { "get": { "tags": [ "Markets" ], "summary": "Get historical OHLCV candles for an underlying.", "operationId": "get_candles", "parameters": [ { "name": "underlying", "in": "query", "description": "Underlying symbol (e.g., \"BTC\", \"ETH\")", "required": false, "schema": { "type": "string", "nullable": true }, "example": "BTC" }, { "name": "instrument_name", "in": "query", "description": "Option instrument symbol. No longer supported on `/candles`, use `/historical-theos`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "BTC-20260331-100000-C" }, { "name": "resolution", "in": "query", "description": "Candle interval (`1m`, `5m`, `15m`, `1h`, `4h`, `1d`)", "required": true, "schema": { "$ref": "#/components/schemas/CandleResolution" }, "example": "1m" }, { "name": "start_time_ms", "in": "query", "description": "Inclusive start timestamp in milliseconds", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1710000000000 }, { "name": "end_time_ms", "in": "query", "description": "Exclusive end timestamp in milliseconds", "required": true, "schema": { "type": "integer", "format": "int64" }, "example": 1710003600000 } ], "responses": { "200": { "description": "Historical underlying candles", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CandlesApiResponse" } } } }, "400": { "description": "Invalid query parameters" }, "502": { "description": "Upstream candle source failure" } } } }, "/competitions": { "get": { "tags": [ "Competition" ], "summary": "List competitions.", "operationId": "list_competitions", "parameters": [ { "name": "state", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/CompetitionStateValue" } ], "nullable": true } }, { "name": "from_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "to_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionsResponse" } } } } } } }, "/competitions/leaderboard": { "get": { "tags": [ "Competition" ], "summary": "Get competition leaderboard.", "operationId": "get_competition_leaderboard", "parameters": [ { "name": "competition_id", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "sort_by", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/CompetitionSortByValue" } ], "nullable": true } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/CompetitionSortOrderValue" } ], "nullable": true } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "wallet", "in": "query", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletAddress" } ], "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionLeaderboardResponse" } } } } } } }, "/competitions/{id}": { "get": { "tags": [ "Competition" ], "summary": "Get competition by id.", "operationId": "get_competition", "parameters": [ { "name": "id", "in": "path", "description": "Competition id", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionResponse" } } } } } } }, "/expiry-summary": { "get": { "tags": [ "Markets" ], "summary": "Get instruments by expiry date with orderbook data", "operationId": "get_expiry_summary", "parameters": [ { "name": "currency", "in": "query", "description": "Currency (e.g., \"BTC\", \"ETH\")", "required": true, "schema": { "type": "string" }, "example": "BTC" }, { "name": "expiry", "in": "query", "description": "Expiry date in ISO format", "required": true, "schema": { "type": "string" }, "example": "2025-01-31" }, { "name": "depth", "in": "query", "description": "Orderbook depth", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Instruments with orderbook data", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentWithOrderbook" } } } } }, "400": { "description": "Invalid expiry date format" }, "500": { "description": "Internal server error" } } } }, "/fills": { "get": { "tags": [ "Portfolio" ], "summary": "Get fills for a wallet", "operationId": "get_fills", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to get fills for", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "limit", "in": "query", "description": "Maximum number of fills to return (default: 100, max: 1000)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 1000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "List of fills", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillsResponse" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "wallet_query": [] } ] } }, "/gas-provider/{chain_id}": { "get": { "tags": [ "Markets" ], "summary": "Return gas fee estimates for the configured EVM RPC chain in rrelayer custom-provider format.", "operationId": "get_gas_provider", "parameters": [ { "name": "chain_id", "in": "path", "description": "Startup-resolved chain id supported by this gas provider", "required": true, "schema": { "type": "integer", "format": "int64", "minimum": 0 } } ], "responses": { "200": { "description": "Gas fee estimates in rrelayer custom-provider format", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GasProviderResponse" } } } }, "404": { "description": "Unsupported chain id", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GasProviderErrorResponse" } } } }, "500": { "description": "Upstream RPC fee estimation failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GasProviderErrorResponse" } } } } } } }, "/greeks": { "get": { "tags": [ "Markets" ], "summary": "Get Greeks for an instrument", "operationId": "get_greeks", "parameters": [ { "name": "symbol", "in": "query", "description": "Instrument symbol (e.g., \"BTC-20250131-100000-C\")", "required": true, "schema": { "type": "string" }, "example": "BTC-20250131-100000-C" } ], "responses": { "200": { "description": "Greeks data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GreeksApiResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/health": { "get": { "tags": [ "Health" ], "summary": "Health check endpoint", "operationId": "health", "responses": { "200": { "description": "Health status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HealthResponse" } } } } } } }, "/historical-pnl": { "get": { "tags": [ "Portfolio" ], "summary": "Get historical equity snapshots for a wallet.", "operationId": "get_historical_pnl", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to query", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "interval", "in": "query", "description": "Interval bucket size (`5m`, `1h`, `1d`)", "required": true, "schema": { "$ref": "#/components/schemas/HistoricalPnlInterval" }, "example": "1h" }, { "name": "limit", "in": "query", "description": "Maximum number of periods to return (default: 100, max: 100)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "example": 100 } ], "responses": { "200": { "description": "Historical equity snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalPnlApiResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } }, "security": [ { "wallet_query": [] } ] } }, "/historical-theos": { "get": { "tags": [ "Markets" ], "summary": "Get historical theoretical-price snapshots for an option instrument.", "operationId": "get_historical_theos", "parameters": [ { "name": "instrument_name", "in": "query", "description": "Option instrument symbol.", "required": true, "schema": { "type": "string" }, "example": "BTC-20260331-100000-C" }, { "name": "interval", "in": "query", "description": "Interval bucket size (`5m`, `1h`, `1d`)", "required": true, "schema": { "$ref": "#/components/schemas/HistoricalTheoInterval" }, "example": "1h" }, { "name": "limit", "in": "query", "description": "Maximum number of periods to return (default: 100, max: 100)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "example": 100 } ], "responses": { "200": { "description": "Historical theoretical-price snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/HistoricalTheoApiResponse" } } } }, "400": { "description": "Bad Request - invalid or blank instrument_name" }, "404": { "description": "Instrument not found" }, "500": { "description": "Internal server error" } } } }, "/instruments": { "get": { "tags": [ "Markets" ], "summary": "Get list of instruments (Deribit-compatible format)", "operationId": "get_instruments", "parameters": [ { "name": "currency", "in": "query", "description": "Filter by currency (e.g., \"BTC\", \"ETH\"). Defaults to \"BTC\" when omitted.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "BTC" }, { "name": "_kind", "in": "query", "description": "Option kind (unused)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Filter by instrument status. Defaults to \"ACTIVE\" to hide expired/settled instruments.\nUse \"all\" to return instruments in any status, or specify a comma-separated list\n(e.g., \"ACTIVE,EXPIRED_PENDING_PRICE\").", "required": false, "schema": { "type": "string", "nullable": true }, "example": "ACTIVE" } ], "responses": { "200": { "description": "List of instruments", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentResponse" } } } } }, "500": { "description": "Internal server error" } } } }, "/limit_iv": { "post": { "tags": [ "Trading" ], "summary": "Get a theoretical limit price for a symbol and implied volatility.", "operationId": "limit_iv", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitIvRequest" } } }, "required": true }, "responses": { "200": { "description": "Limit price quote generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LimitIvApiResponse" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal server error" } } } }, "/margin-mode": { "post": { "tags": [ "Account" ], "summary": "Set margin mode for a wallet (requires zero open positions)", "operationId": "set_margin_mode", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMarginModeRequest" } } }, "required": true }, "responses": { "200": { "description": "Margin mode updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarginModeApiResponse" } } } }, "400": { "description": "Invalid margin mode or has open positions" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/markets": { "get": { "tags": [ "Markets" ], "summary": "Get all available markets with their instruments", "operationId": "get_markets", "parameters": [ { "name": "include_instruments", "in": "query", "description": "Whether to include individual instruments in the response. Defaults to true.", "required": false, "schema": { "type": "boolean", "nullable": true }, "example": "false" } ], "responses": { "200": { "description": "List of markets", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketsResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/mmp/config": { "get": { "tags": [ "MMP" ], "summary": "Get MMP configuration(s) for a wallet", "operationId": "get_mmp_config", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address", "required": true, "schema": { "type": "string" } }, { "name": "currency", "in": "query", "description": "Currency filter", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "MMP configuration(s)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MmpConfigResponse" } } } }, "500": { "description": "Internal server error" } } }, "post": { "tags": [ "MMP" ], "summary": "Set or update MMP configuration", "operationId": "set_mmp_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetMmpConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "MMP config updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MmpConfigData" } } } }, "403": { "description": "Wallet mismatch" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] }, "delete": { "tags": [ "MMP" ], "summary": "Delete (disable) MMP configuration", "operationId": "delete_mmp_config", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteMmpConfigRequest" } } }, "required": true }, "responses": { "200": { "description": "MMP config deleted" }, "403": { "description": "Wallet mismatch" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/mmp/reset": { "post": { "tags": [ "MMP" ], "summary": "Reset MMP state (clear fills and unfreeze)", "operationId": "reset_mmp", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ResetMmpRequest" } } }, "required": true }, "responses": { "200": { "description": "MMP state reset" }, "403": { "description": "Wallet mismatch" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/options-chain": { "get": { "tags": [ "Markets" ], "summary": "Get a full options chain snapshot by underlying and expiry.", "operationId": "get_options_chain", "parameters": [ { "name": "currency", "in": "query", "description": "Currency (e.g., \"BTC\", \"ETH\")", "required": true, "schema": { "type": "string" }, "example": "BTC" }, { "name": "expiry", "in": "query", "description": "Expiry date in ISO format", "required": true, "schema": { "type": "string" }, "example": "2026-03-31" }, { "name": "option_type", "in": "query", "description": "Filter by option type (call, put, both). Defaults to both.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "both" }, { "name": "side", "in": "query", "description": "Filter by side (buy, sell, both). Defaults to both.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "both" } ], "responses": { "200": { "description": "Options chain snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OptionsChainSnapshotResponse" } } } }, "400": { "description": "Invalid query parameters" }, "500": { "description": "Internal server error" } } } }, "/options-summary": { "get": { "tags": [ "Markets" ], "summary": "Get options summary (Deribit-compatible format)", "operationId": "get_options_summary", "parameters": [ { "name": "currency", "in": "query", "description": "Filter by currency (e.g., \"BTC\", \"ETH\"). Supports comma-separated values and \"ALL\".\nWhen omitted, returns options for all active underlyings.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "BTC" }, { "name": "kind", "in": "query", "description": "Option kind", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Options summary", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/OptionSummary" } } } } }, "500": { "description": "Internal server error" } } } }, "/order": { "post": { "tags": [ "Trading" ], "summary": "Place an options order", "operationId": "place_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateMessage" } } } }, "400": { "description": "Invalid order parameters" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/orderbook": { "get": { "tags": [ "Markets" ], "summary": "Get orderbook for an instrument", "operationId": "get_orderbook", "parameters": [ { "name": "instrument_id", "in": "query", "description": "Instrument ID to get orderbook for", "required": false, "schema": { "type": "integer", "format": "int32", "nullable": true } }, { "name": "instrument_name", "in": "query", "description": "Instrument name to get orderbook for (e.g., BTC-20250228-50000-C)", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "depth", "in": "query", "description": "Orderbook depth (default: 20)", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "Orderbook data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBookResponse" } } } }, "400": { "description": "Missing query parameter: instrument_id or instrument_name" }, "404": { "description": "Instrument not found" } } } }, "/orders": { "get": { "tags": [ "Trading" ], "summary": "Get orders for a wallet", "operationId": "get_orders", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to get orders for", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "status", "in": "query", "description": "Filter by order status", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "limit", "in": "query", "description": "Maximum number of orders to return (default: 50, max: 50)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 50, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "responses": { "200": { "description": "List of orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrdersResponse" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "wallet_query": [] } ] } }, "/portfolio": { "get": { "tags": [ "Portfolio" ], "summary": "Get portfolio for a wallet", "operationId": "get_portfolio", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to get portfolio for", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "Portfolio data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Portfolio" } } } }, "500": { "description": "Internal server error" }, "503": { "description": "Portfolio margin data unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/portfolio/greeks": { "get": { "tags": [ "Portfolio" ], "summary": "Get per-position and aggregate portfolio Greeks with optional simulated orders.", "operationId": "get_portfolio_greeks", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to calculate portfolio Greeks for.", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "simulated_orders", "in": "query", "description": "Optional JSON array of simulated orders.\nExample: [{\"symbol\":\"BTC-20260131-100000-C\",\"side\":\"Buy\",\"size\":\"1.0\"}]", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Portfolio Greeks data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PortfolioGreeksApiResponse" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "wallet_query": [] } ] } }, "/profile": { "get": { "tags": [ "Portfolio" ], "summary": "Get profile stats.", "operationId": "get_profile", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileResponse" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/profile/trades": { "get": { "tags": [ "Portfolio" ], "summary": "Get profile trade history.", "operationId": "get_profile_trades", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "competition_id", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "from_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "to_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileTradesResponse" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/profile/username-request": { "post": { "tags": [ "Portfolio" ], "summary": "Submit a username change request.", "operationId": "submit_username_request", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsernameChangeRequestSubmit" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsernameChangeRequestResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "409": { "description": "Conflict" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/ready": { "get": { "tags": [ "Health" ], "summary": "Readiness check endpoint", "description": "Returns 200 OK when all components are ready to serve requests,\nor 503 Service Unavailable when the service is still starting up.", "operationId": "ready", "responses": { "200": { "description": "Service is ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } }, "503": { "description": "Service is not ready", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReadyResponse" } } } } } } }, "/revoke-agent": { "post": { "tags": [ "Agents" ], "summary": "Revoke an agent's authorization", "operationId": "revoke_agent", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAgentRequest" } } }, "required": true }, "responses": { "200": { "description": "Agent revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAgentResponse" } } } }, "400": { "description": "Invalid signature" } } } }, "/settlement-payouts": { "get": { "tags": [ "Portfolio" ], "summary": "GET /settlement-payouts - Get settlement payout history for a wallet.", "operationId": "get_settlement_payouts", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to query.", "required": true, "schema": { "type": "string" }, "example": "0x1234567890123456789012345678901234567890" }, { "name": "limit", "in": "query", "description": "Maximum number of results to return (default: 50, max: 100).", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true }, "example": 50 }, { "name": "offset", "in": "query", "description": "Number of results to skip for pagination.", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true }, "example": 0 }, { "name": "symbol", "in": "query", "description": "Optional symbol filter.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "BTC-20260131-100000-C" }, { "name": "ledger_applied", "in": "query", "description": "Optional ledger applied filter.", "required": false, "schema": { "type": "boolean", "nullable": true }, "example": true } ], "responses": { "200": { "description": "Settlement payouts retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementPayoutsResponse" } } } }, "400": { "description": "Invalid wallet address" }, "500": { "description": "Internal server error" } }, "security": [ { "wallet_query": [] } ] } }, "/settlement-payouts/seen": { "post": { "tags": [ "Portfolio" ], "summary": "POST /settlement-payouts/seen - Mark settlement payouts as seen for a wallet.", "operationId": "mark_settlement_payouts_seen", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementPayoutSeenRequest" } } }, "required": true }, "responses": { "200": { "description": "Settlement payouts marked as seen", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SettlementPayoutSeenMutationResponse" } } } }, "400": { "description": "Invalid request payload" }, "403": { "description": "Wallet mismatch" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/trades": { "get": { "tags": [ "Trading" ], "summary": "Get a list of recent trades", "operationId": "get_trades", "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of trades to return (default: 100, max: 1000)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 1000, "minimum": 0 } }, { "name": "offset", "in": "query", "description": "Pagination offset", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "symbol", "in": "query", "description": "Filter by specific option symbol", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "underlying", "in": "query", "description": "Filter by underlying asset (e.g., \"BTC\", \"ETH\")", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "List of trades", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TradesResponse" } } } }, "500": { "description": "Internal server error" } } } }, "/username": { "get": { "tags": [ "Username" ], "summary": "Lookup username by wallet or reverse-lookup wallet by username.", "operationId": "get_username", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to look up", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "username", "in": "query", "description": "Username to reverse-look up", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Username found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsernameResponse" } } } }, "400": { "description": "Must provide wallet or username query param" }, "404": { "description": "No username found" } } }, "post": { "tags": [ "Username" ], "summary": "Set the display username for the authenticated wallet.", "operationId": "set_username", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetUsernameRequest" } } }, "required": true }, "responses": { "200": { "description": "Username set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UsernameResponse" } } } }, "400": { "description": "Validation error" }, "409": { "description": "Username already taken" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] }, "delete": { "tags": [ "Username" ], "summary": "Delete the display username for the authenticated wallet.", "operationId": "delete_username", "responses": { "200": { "description": "Username deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteUsernameResponse" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/version": { "get": { "tags": [ "Health" ], "summary": "Version information endpoint", "operationId": "version", "responses": { "200": { "description": "Version information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/VersionResponse" } } } } } } } }, "components": { "schemas": { "AccountBalance": { "type": "object", "required": [ "wallet_address", "balance", "updated_at" ], "properties": { "balance": { "type": "string", "description": "Account balance in USD" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "ApproveAgentRequest": { "type": "object", "description": "Request to approve an agent wallet.", "required": [ "agent", "nonce", "signature" ], "properties": { "agent": { "type": "string", "description": "Agent wallet address to authorize" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for replay protection", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature from wallet owner" } } }, "ApproveAgentResponse": { "type": "object", "description": "Response for approving an agent.", "required": [ "success" ], "properties": { "error": { "type": "string", "description": "Error message if failed", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request succeeded" } } }, "AuthorizedAgentsResponse": { "type": "object", "description": "Response listing authorized agents.", "required": [ "agents" ], "properties": { "agents": { "type": "array", "items": { "type": "string" }, "description": "List of authorized agent wallet addresses" } } }, "BulkCancelOrderByCloidRequest": { "type": "object", "required": [ "cancels" ], "properties": { "cancels": { "type": "array", "items": { "$ref": "#/components/schemas/CancelOrderByCloidRequest" }, "description": "Array of cancel requests by client_id (max 50)" } } }, "BulkCancelOrderRequest": { "type": "object", "required": [ "cancels" ], "properties": { "cancels": { "type": "array", "items": { "$ref": "#/components/schemas/CancelOrderRequest" }, "description": "Array of cancel requests by order_id (max 50)" } } }, "BulkCancelOrderResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkOrderResult" }, "description": "Results for each cancel in the request" } } }, "BulkOrderResult": { "type": "object", "required": [ "index", "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/OrderUpdateMessage" } ], "nullable": true }, "error": { "type": "string", "description": "Error message if failed", "nullable": true }, "index": { "type": "integer", "description": "Index of the order in the original request", "minimum": 0 }, "success": { "type": "boolean", "description": "Whether the operation succeeded" } } }, "BulkPlaceOrderRequest": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceOrderRequest" }, "description": "Array of orders to place (max 50)" } } }, "BulkPlaceOrderResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkOrderResult" }, "description": "Results for each order in the request" } } }, "CancelOrderByCloidRequest": { "type": "object", "required": [ "wallet", "client_id", "nonce", "signature" ], "properties": { "client_id": { "type": "string", "description": "Client order ID to cancel" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for replay protection", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "CancelOrderRequest": { "type": "object", "description": "Request to cancel an order.", "required": [ "wallet", "order_id", "nonce", "signature" ], "properties": { "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "order_id": { "type": "integer", "format": "int64", "minimum": 0 }, "signature": { "type": "string" }, "wallet": { "type": "string" } } }, "CandleResolution": { "type": "string", "enum": [ "1m", "5m", "15m", "1h", "4h", "1d" ] }, "CandlesApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/CandlesResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "CandlesResponse": { "oneOf": [ { "$ref": "#/components/schemas/UnderlyingCandlesResponse" } ] }, "CompetitionData": { "type": "object", "required": [ "id", "name", "win_conditions", "primary_win_condition", "start_ts_ms", "end_ts_ms", "state", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string" }, "description": { "type": "string", "nullable": true }, "end_ts_ms": { "type": "integer", "format": "int64" }, "id": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "primary_win_condition": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "rules_content": { "type": "string", "nullable": true }, "rules_url": { "type": "string", "nullable": true }, "start_ts_ms": { "type": "integer", "format": "int64" }, "state": { "$ref": "#/components/schemas/CompetitionStateValue" }, "updated_at": { "type": "string" }, "win_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionWinConditionValue" } } } }, "CompetitionLeaderboardResponse": { "type": "object", "required": [ "success", "competition_id", "sort_by", "sort_order", "data", "pagination" ], "properties": { "competition_id": { "type": "integer", "format": "int64" }, "connected_user": { "allOf": [ { "$ref": "#/components/schemas/ConnectedUserRank" } ], "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "sort_by": { "$ref": "#/components/schemas/CompetitionSortByValue" }, "sort_order": { "$ref": "#/components/schemas/CompetitionSortOrderValue" }, "success": { "type": "boolean" } } }, "CompetitionResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/CompetitionData" }, "success": { "type": "boolean" } } }, "CompetitionSortByValue": { "type": "string", "enum": [ "pnl", "volume", "efficiency" ] }, "CompetitionSortOrderValue": { "type": "string", "enum": [ "asc", "desc" ] }, "CompetitionStateValue": { "type": "string", "enum": [ "pre", "active", "post" ] }, "CompetitionUpdateRequest": { "type": "object", "properties": { "description": { "type": "string", "nullable": true }, "end_ts_ms": { "type": "integer", "format": "int64", "nullable": true }, "name": { "type": "string", "nullable": true }, "primary_win_condition": { "allOf": [ { "$ref": "#/components/schemas/CompetitionWinConditionValue" } ], "nullable": true }, "rules_content": { "type": "string", "nullable": true }, "rules_url": { "type": "string", "nullable": true }, "start_ts_ms": { "type": "integer", "format": "int64", "nullable": true }, "win_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "minItems": 1, "nullable": true } } }, "CompetitionUpsertRequest": { "type": "object", "required": [ "name", "win_conditions", "primary_win_condition", "start_ts_ms", "end_ts_ms" ], "properties": { "description": { "type": "string", "nullable": true }, "end_ts_ms": { "type": "integer", "format": "int64" }, "name": { "type": "string" }, "primary_win_condition": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "rules_content": { "type": "string", "nullable": true }, "rules_url": { "type": "string", "nullable": true }, "start_ts_ms": { "type": "integer", "format": "int64" }, "win_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "minItems": 1 } } }, "CompetitionWinConditionValue": { "type": "string", "enum": [ "pnl", "volume", "efficiency" ] }, "CompetitionsResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionData" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } } }, "ConnectedUserRank": { "type": "object", "required": [ "wallet", "username" ], "properties": { "efficiency": { "type": "string", "nullable": true }, "medal": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "pnl": { "type": "string", "nullable": true }, "rank": { "type": "integer", "nullable": true, "minimum": 0 }, "username": { "type": "string" }, "volume": { "type": "string", "nullable": true }, "wallet": { "type": "string" } } }, "CrossedOrderbook": { "type": "object", "description": "Crossed orderbook details for debugging", "required": [ "symbol", "best_bid", "best_ask", "spread", "age_seconds", "bid_levels", "ask_levels", "top_bids", "top_asks" ], "properties": { "age_seconds": { "type": "integer", "format": "int64", "description": "Age of last update in seconds" }, "ask_levels": { "type": "integer", "description": "Number of ask price levels", "minimum": 0 }, "best_ask": { "type": "number", "format": "double", "description": "Best ask price" }, "best_bid": { "type": "number", "format": "double", "description": "Best bid price" }, "bid_levels": { "type": "integer", "description": "Number of bid price levels", "minimum": 0 }, "last_l2_seq": { "type": "integer", "format": "int64", "description": "Last L2 update sequence number", "nullable": true }, "spread": { "type": "number", "format": "double", "description": "Spread (ask - bid, negative if crossed)" }, "symbol": { "type": "string", "description": "Symbol (e.g., \"BTC-20260131-100000-C\")" }, "top_asks": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "number", "format": "double" }, { "type": "number", "format": "double" } ] } }, "description": "Top 10 ask levels (price, size)" }, "top_bids": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "number", "format": "double" }, { "type": "number", "format": "double" } ] } }, "description": "Top 10 bid levels (price, size)" } } }, "DeleteMmpConfigRequest": { "type": "object", "description": "Request to delete MMP configuration", "required": [ "wallet", "currency", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Currency to delete config for" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "DeleteUserTierRequest": { "type": "object", "description": "Request to delete user tier", "required": [ "wallet", "nonce", "signature" ], "properties": { "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "DeleteUsernameResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "DeltaCurveExport": { "type": "object", "description": "Exported delta curve for a single expiry.", "required": [ "expiry", "points" ], "properties": { "expiry": { "type": "integer", "format": "int64" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/DeltaIvExport" } } } }, "DeltaIvExport": { "type": "object", "description": "Exported delta-IV pair for API responses.", "required": [ "delta", "iv" ], "properties": { "delta": { "type": "number", "format": "double" }, "iv": { "type": "number", "format": "double" } } }, "FillApiResponse": { "type": "object", "required": [ "fill_id", "trade_id", "wallet_address", "symbol", "price", "size", "fee", "is_taker", "timestamp", "created_at" ], "properties": { "builder_code_address": { "type": "string", "description": "Builder code wallet address for fee sharing (if any)", "nullable": true }, "builder_code_fee": { "type": "string", "description": "Fee paid to builder code (if any)", "nullable": true }, "created_at": { "type": "string", "description": "Record creation timestamp" }, "explorer_url": { "type": "string", "description": "Optional explorer URL for this trade.", "nullable": true }, "fee": { "type": "string", "description": "Fee charged for this fill" }, "fill_id": { "type": "integer", "format": "int64", "description": "Unique fill identifier" }, "is_taker": { "type": "boolean", "description": "Whether this fill was taker side" }, "price": { "type": "string", "description": "Execution price" }, "size": { "type": "string", "description": "Fill size in contracts (human-readable units)" }, "symbol": { "type": "string", "description": "Instrument symbol" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds" }, "trade_id": { "type": "integer", "format": "int64", "description": "Associated trade ID" }, "wallet_address": { "type": "string", "description": "Wallet address that received the fill" } } }, "FillsResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FillApiResponse" }, "description": "List of fills" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "GasProviderErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string", "example": "not_found" }, "message": { "type": "string", "example": "Gas provider only supports chain_id 1" } } }, "GasProviderFeeTierResponse": { "type": "object", "required": [ "suggestedMaxPriorityFeePerGas", "suggestedMaxFeePerGas" ], "properties": { "suggestedMaxFeePerGas": { "type": "string", "example": "120" }, "suggestedMaxPriorityFeePerGas": { "type": "string", "example": "1.2" } } }, "GasProviderResponse": { "type": "object", "required": [ "slow", "medium", "fast", "superFast" ], "properties": { "fast": { "$ref": "#/components/schemas/GasProviderFeeTierResponse" }, "medium": { "$ref": "#/components/schemas/GasProviderFeeTierResponse" }, "slow": { "$ref": "#/components/schemas/GasProviderFeeTierResponse" }, "superFast": { "$ref": "#/components/schemas/GasProviderFeeTierResponse" } } }, "GreeksApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/GreeksResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "GreeksResponse": { "type": "object", "description": "Greeks response for an instrument", "required": [ "symbol", "delta", "gamma", "theta", "vega", "rho", "implied_vol", "theoretical_price" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Delta - rate of change of option price with respect to underlying" }, "gamma": { "type": "number", "format": "double", "description": "Gamma - rate of change of delta with respect to underlying" }, "implied_vol": { "type": "number", "format": "double", "description": "Implied volatility" }, "mid_price": { "type": "number", "format": "double", "description": "Live market mid when a quote is available.", "nullable": true }, "rho": { "type": "number", "format": "double", "description": "Rho - sensitivity to interest rate changes" }, "symbol": { "type": "string", "description": "Instrument symbol" }, "theoretical_price": { "type": "number", "format": "double", "description": "Theoretical Black-Scholes price used for greeks." }, "theta": { "type": "number", "format": "double", "description": "Theta - rate of decay of option value over time" }, "vega": { "type": "number", "format": "double", "description": "Vega - sensitivity to volatility changes" } } }, "HealthResponse": { "type": "object", "description": "Health check response", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Health status (\"ok\")" } } }, "HistoricalPnlApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/HistoricalPnlResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "HistoricalPnlInterval": { "type": "string", "description": "Historical equity interval identifier.", "enum": [ "5m", "1h", "1d" ] }, "HistoricalPnlPoint": { "type": "object", "description": "A single historical equity point.", "required": [ "timestamp", "equity" ], "properties": { "equity": { "type": "string", "description": "Total account equity at the bucket timestamp." }, "timestamp": { "type": "integer", "format": "int64", "description": "Interval bucket start timestamp in milliseconds since epoch." } } }, "HistoricalPnlResponse": { "type": "object", "description": "Historical equity response for a wallet and interval.", "required": [ "wallet_address", "interval" ], "properties": { "interval": { "$ref": "#/components/schemas/HistoricalPnlInterval" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalPnlPoint" }, "description": "Returned points in ascending timestamp order." }, "wallet_address": { "type": "string", "description": "Account wallet address." } } }, "HistoricalTheoApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/HistoricalTheoResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "HistoricalTheoInterval": { "type": "string", "description": "Historical theo interval identifier.", "enum": [ "5m", "1h", "1d" ] }, "HistoricalTheoPoint": { "type": "object", "description": "A single historical theoretical-price point.", "required": [ "timestamp", "theoretical_price" ], "properties": { "theoretical_price": { "type": "number", "format": "double", "description": "Theoretical option price at the bucket timestamp." }, "timestamp": { "type": "integer", "format": "int64", "description": "Interval bucket start timestamp in milliseconds since epoch." } } }, "HistoricalTheoResponse": { "type": "object", "description": "Historical theo response for an instrument and interval.", "required": [ "instrument_name", "interval" ], "properties": { "instrument_name": { "type": "string", "description": "Option instrument symbol." }, "interval": { "$ref": "#/components/schemas/HistoricalTheoInterval" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/HistoricalTheoPoint" }, "description": "Returned points in ascending timestamp order." } } }, "Instrument": { "type": "object", "required": [ "instrument_id", "id", "underlying", "strike", "expiry", "option_type", "volume_24h", "open_interest", "updated_at", "status" ], "properties": { "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp", "minimum": 0 }, "id": { "type": "string", "description": "Instrument symbol (e.g., \"BTC-20250131-100000-C\")" }, "instrument_id": { "type": "integer", "format": "int32", "description": "Unique instrument identifier" }, "mark_iv": { "type": "string", "description": "Mark implied volatility", "nullable": true }, "open_interest": { "type": "string", "description": "Open interest" }, "option_token_address": { "type": "string", "description": "Option token contract address", "nullable": true }, "option_type": { "type": "string", "description": "Option type (\"call\" or \"put\")" }, "status": { "$ref": "#/components/schemas/InstrumentStatus" }, "strike": { "type": "string", "description": "Strike price" }, "underlying": { "type": "string", "description": "Underlying asset" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "volume_24h": { "type": "string", "description": "24-hour volume" } } }, "InstrumentResponse": { "type": "object", "description": "Instrument information response.", "required": [ "price_index", "rfq", "kind", "instrument_name", "maker_commission", "taker_commission", "instrument_type", "expiration_timestamp", "creation_timestamp", "is_active", "option_type", "contract_size", "tick_size", "strike", "instrument_id", "settlement_period", "min_trade_amount", "block_trade_commission", "block_trade_min_trade_amount", "block_trade_tick_size", "settlement_currency", "base_currency", "counter_currency", "quote_currency", "tick_size_steps" ], "properties": { "base_currency": { "type": "string", "description": "Base currency" }, "block_trade_commission": { "type": "number", "format": "double", "description": "Block trade commission" }, "block_trade_min_trade_amount": { "type": "number", "format": "double", "description": "Block trade minimum amount" }, "block_trade_tick_size": { "type": "number", "format": "double", "description": "Block trade tick size" }, "contract_size": { "type": "number", "format": "double", "description": "Contract size" }, "counter_currency": { "type": "string", "description": "Counter currency" }, "creation_timestamp": { "type": "integer", "format": "int64", "description": "Creation timestamp" }, "expiration_timestamp": { "type": "integer", "format": "int64", "description": "Expiration timestamp" }, "instrument_id": { "type": "integer", "format": "int32", "description": "Instrument ID" }, "instrument_name": { "type": "string", "description": "Instrument name/symbol" }, "instrument_type": { "type": "string", "description": "Instrument type" }, "is_active": { "type": "boolean", "description": "Whether instrument is active" }, "kind": { "type": "string", "description": "Instrument kind" }, "maker_commission": { "type": "number", "format": "double", "description": "Maker commission rate" }, "min_trade_amount": { "type": "number", "format": "double", "description": "Minimum trade amount" }, "option_token_address": { "type": "string", "description": "Option token contract address", "nullable": true }, "option_type": { "type": "string", "description": "Option type (call/put)" }, "price_index": { "type": "string", "description": "Price index name" }, "quote_currency": { "type": "string", "description": "Quote currency" }, "rfq": { "type": "boolean", "description": "RFQ enabled" }, "settlement_currency": { "type": "string", "description": "Settlement currency" }, "settlement_period": { "type": "string", "description": "Settlement period" }, "strike": { "type": "number", "format": "double", "description": "Strike price" }, "taker_commission": { "type": "number", "format": "double", "description": "Taker commission rate" }, "tick_size": { "type": "number", "format": "double", "description": "Tick size" }, "tick_size_steps": { "type": "array", "items": { "$ref": "#/components/schemas/TickSizeStep" }, "description": "Tick size steps" } } }, "InstrumentWithOrderbook": { "type": "object", "required": [ "instrument_id", "instrument_name", "strike", "option_type", "expiration_timestamp", "bid_price", "ask_price", "mark_price", "underlying_price", "underlying_index", "open_interest", "volume", "volume_usd", "interest_rate", "estimated_delivery_price", "creation_timestamp", "base_currency", "quote_currency", "mid_price", "bids", "asks" ], "properties": { "ask_iv": { "type": "number", "format": "double", "description": "Quote-derived ask-side implied volatility", "nullable": true }, "ask_price": { "type": "number", "format": "double", "description": "Best ask price" }, "asks": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } }, "description": "Ask orders [price, size], where size is in human-readable contracts" }, "base_currency": { "type": "string", "description": "Base currency" }, "bid_iv": { "type": "number", "format": "double", "description": "Quote-derived bid-side implied volatility", "nullable": true }, "bid_price": { "type": "number", "format": "double", "description": "Best bid price" }, "bids": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } }, "description": "Bid orders [price, size], where size is in human-readable contracts" }, "creation_timestamp": { "type": "integer", "format": "int64", "description": "Creation timestamp" }, "estimated_delivery_price": { "type": "number", "format": "double", "description": "Estimated delivery price" }, "expiration_timestamp": { "type": "integer", "format": "int64", "description": "Expiration timestamp" }, "high": { "type": "number", "format": "double", "description": "24h high", "nullable": true }, "instrument_id": { "type": "integer", "format": "int32", "description": "Instrument ID" }, "instrument_name": { "type": "string", "description": "Instrument name/symbol" }, "interest_rate": { "type": "number", "format": "double", "description": "Interest rate" }, "last": { "type": "number", "format": "double", "description": "Last trade price", "nullable": true }, "low": { "type": "number", "format": "double", "description": "24h low", "nullable": true }, "mark_iv": { "type": "number", "format": "double", "description": "Theoretical implied volatility used for mark price and greeks", "nullable": true }, "mark_price": { "type": "number", "format": "double", "description": "Mark price" }, "mid_price": { "type": "number", "format": "double", "description": "Mid price" }, "open_interest": { "type": "number", "format": "double", "description": "Open interest" }, "option_token_address": { "type": "string", "description": "Option token contract address", "nullable": true }, "option_type": { "type": "string", "description": "Option type (call/put)" }, "price_change": { "type": "number", "format": "double", "description": "24h price change", "nullable": true }, "quote_currency": { "type": "string", "description": "Quote currency" }, "strike": { "type": "number", "format": "double", "description": "Strike price" }, "theoretical_price": { "type": "number", "format": "double", "description": "Theoretical option price derived from the vol oracle, when available.", "nullable": true }, "underlying_index": { "type": "string", "description": "Underlying index name" }, "underlying_price": { "type": "number", "format": "double", "description": "Underlying price" }, "volume": { "type": "number", "format": "double", "description": "24h volume" }, "volume_usd": { "type": "number", "format": "double", "description": "24h volume in USD" } } }, "IntegrityCheck": { "type": "object", "description": "Individual integrity check result", "required": [ "name", "status", "message" ], "properties": { "details": { "type": "object", "description": "Additional details (varies by check type)", "nullable": true }, "message": { "type": "string", "description": "Human-readable description of the result" }, "name": { "type": "string", "description": "Name of the check performed" }, "status": { "$ref": "#/components/schemas/IntegrityStatus" } } }, "IntegrityReport": { "type": "object", "description": "Detailed integrity report for the margin engine.", "required": [ "timestamp", "overall_status", "checks", "ledger_summary", "position_summary", "settlement_summary" ], "properties": { "checks": { "type": "array", "items": { "$ref": "#/components/schemas/IntegrityCheck" }, "description": "Individual integrity checks performed" }, "ledger_summary": { "$ref": "#/components/schemas/LedgerSummary" }, "overall_status": { "$ref": "#/components/schemas/IntegrityStatus" }, "position_summary": { "$ref": "#/components/schemas/PositionSummary" }, "settlement_summary": { "$ref": "#/components/schemas/SettlementSummary" }, "timestamp": { "type": "string", "description": "ISO 8601 timestamp of when the report was generated" } } }, "IntegrityStatus": { "type": "string", "description": "System health status level", "enum": [ "HEALTHY", "WARNING", "CRITICAL" ] }, "LeaderboardRow": { "type": "object", "required": [ "rank", "wallet", "username", "pnl", "volume", "efficiency" ], "properties": { "efficiency": { "type": "string" }, "medal": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "pnl": { "type": "string" }, "rank": { "type": "integer", "minimum": 0 }, "username": { "type": "string" }, "volume": { "type": "string" }, "wallet": { "type": "string" } } }, "LedgerSummary": { "type": "object", "description": "Summary of ledger balances across all accounts", "required": [ "total_balance", "account_count", "total_fills", "total_volume" ], "properties": { "account_count": { "type": "integer", "format": "int64", "description": "Number of accounts with balances" }, "total_balance": { "type": "string", "description": "Total balance across all accounts (USD)" }, "total_fills": { "type": "integer", "format": "int64", "description": "Total number of fills processed" }, "total_volume": { "type": "string", "description": "Total trading volume (USD)" } } }, "LimitIvApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/LimitIvResponse" } ], "nullable": true }, "error": { "type": "string", "description": "Error message when `success` is false", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "LimitIvRequest": { "type": "object", "required": [ "symbol", "limit_iv" ], "properties": { "limit_iv": { "type": "number", "format": "double", "description": "Implied volatility as decimal (e.g., 0.8 for 80%)" }, "symbol": { "type": "string", "description": "Option symbol (e.g., \"BTC-20260331-100000-C\")" } } }, "LimitIvResponse": { "type": "object", "required": [ "symbol", "limit_iv", "limit_price" ], "properties": { "limit_iv": { "type": "number", "format": "double", "description": "Implied volatility as decimal" }, "limit_price": { "type": "number", "format": "double", "description": "Theoretical limit price from Black-Scholes" }, "symbol": { "type": "string", "description": "Option symbol" } } }, "MarginModeApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/MarginModeResponse" } ], "nullable": true }, "error": { "type": "string", "description": "Error message when success=false", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "MarginModeResponse": { "type": "object", "description": "Response for margin mode change", "required": [ "wallet", "margin_mode", "previous_mode" ], "properties": { "margin_mode": { "type": "string", "description": "New margin mode" }, "previous_mode": { "type": "string", "description": "Previous margin mode" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "MarginSummary": { "type": "object", "description": "Unified margin summary that works for both Standard and Portfolio modes.\n\nThis provides a consistent interface for the frontend regardless of margin mode.", "required": [ "mode", "equity", "position_im", "open_orders_im", "initial_margin", "maintenance_margin" ], "properties": { "equity": { "type": "string", "description": "Total account equity. In portfolio mode this means executed PM equity only." }, "initial_margin": { "type": "string", "description": "Excess Initial Margin (equity - position_im - open_orders_im)\nPositive = can open new risk, Negative = need to reduce risk" }, "maintenance_margin": { "type": "string", "description": "Excess Maintenance Margin (equity - position_mm)\nNegative = liquidation territory" }, "mode": { "type": "string", "description": "Margin mode: \"standard\" or \"portfolio\"" }, "open_orders_im": { "type": "string", "description": "Initial Margin from open orders" }, "open_orders_premium_reserved": { "type": "string", "description": "(Standard mode only) USDC premium reserved for open BUY orders.\nThis amount is \"locked\" until orders fill or cancel.\nFor Portfolio mode, this will be None (premium not pre-paid).", "nullable": true }, "position_im": { "type": "string", "description": "Initial Margin required from positions" } } }, "Market": { "type": "object", "description": "Market information.", "required": [ "symbol", "underlying", "expiry", "strike", "option_type" ], "properties": { "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp", "minimum": 0 }, "option_type": { "$ref": "#/components/schemas/OptionType" }, "strike": { "type": "string", "description": "Strike price" }, "symbol": { "type": "string", "description": "Market symbol (e.g., \"BTC-20250131-100000-C\")" }, "underlying": { "type": "string", "description": "Underlying asset (e.g., \"BTC\")" } } }, "MarketInfo": { "type": "object", "required": [ "underlying", "expiry", "index_price", "instruments", "total_volume_24h", "total_open_interest" ], "properties": { "atm_vol": { "type": "string", "description": "At-the-money volatility", "nullable": true }, "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp", "minimum": 0 }, "index_price": { "type": "string", "description": "Current index price" }, "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/Instrument" }, "description": "List of instruments for this market" }, "total_open_interest": { "type": "string", "description": "Total open interest" }, "total_volume_24h": { "type": "string", "description": "Total 24-hour volume" }, "underlying": { "type": "string", "description": "Underlying asset" } } }, "MarketResponse": { "type": "object", "description": "Simple market response (for create/delete).", "required": [ "success", "message" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" } } }, "MarketUpdateMessage": { "type": "object", "description": "Market update message.", "required": [ "market", "status", "timestamp" ], "properties": { "market": { "$ref": "#/components/schemas/Market" }, "reason": { "type": "string", "description": "Reason for failure (if status is MarketCreationFailed or MarketDeletionFailed)", "nullable": true }, "status": { "$ref": "#/components/schemas/MarketUpdateStatus" }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds", "minimum": 0 } } }, "MarketUpdateStatus": { "type": "string", "description": "Market update status.", "enum": [ "MARKET_CREATED", "MARKET_ALREADY_EXISTS", "MARKET_DELETED", "MARKET_EXPIRED", "MARKET_PENDING_SETTLEMENT", "MARKET_CREATION_FAILED", "MARKET_DELETION_FAILED" ] }, "MarketsResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInfo" }, "description": "List of markets with their instruments" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "MmpConfigData": { "type": "object", "required": [ "wallet_address", "currency", "interval_ms", "frozen_time_ms", "enabled" ], "properties": { "currency": { "type": "string", "description": "Currency for MMP (e.g., \"BTC\", \"ETH\")" }, "delta_limit": { "type": "string", "description": "Delta limit (optional)", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether MMP is enabled" }, "frozen_time_ms": { "type": "integer", "format": "int64", "description": "Frozen time in milliseconds after MMP triggers" }, "interval_ms": { "type": "integer", "format": "int64", "description": "Monitoring interval in milliseconds" }, "qty_limit": { "type": "string", "description": "Quantity limit (optional)", "nullable": true }, "vega_limit": { "type": "string", "description": "Vega limit (optional)", "nullable": true }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "MmpConfigResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MmpConfigData" }, "description": "List of MMP configurations" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "MonitoringAccountSummary": { "type": "object", "description": "Account summary for monitoring", "required": [ "wallet", "position_count", "total_notional" ], "properties": { "equity": { "type": "string", "description": "Account equity when margin could be computed", "nullable": true }, "margin_error": { "type": "string", "description": "Margin build or compute error", "nullable": true }, "margin_used": { "type": "string", "description": "Margin used when margin could be computed", "nullable": true }, "position_count": { "type": "integer", "description": "Number of open positions", "minimum": 0 }, "total_notional": { "type": "string", "description": "Total notional value of positions" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "MonitoringAccountsResponse": { "type": "object", "description": "Response for monitoring/accounts endpoint", "required": [ "account_count", "accounts" ], "properties": { "account_count": { "type": "integer", "description": "Total number of accounts", "minimum": 0 }, "accounts": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringAccountSummary" }, "description": "List of account summaries" } } }, "MonitoringPositionHolder": { "type": "object", "description": "Position holder details", "required": [ "wallet", "amount", "entry_price", "unrealized_pnl" ], "properties": { "amount": { "type": "string", "description": "Position amount (positive for long, negative for short)" }, "entry_price": { "type": "string", "description": "Entry price" }, "unrealized_pnl": { "type": "string", "description": "Unrealized PnL" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "MonitoringPositionsResponse": { "type": "object", "description": "Response for monitoring/positions endpoint", "required": [ "symbol_count", "symbols" ], "properties": { "symbol_count": { "type": "integer", "description": "Total number of symbols with positions", "minimum": 0 }, "symbols": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringSymbolPosition" }, "description": "Position summaries by symbol" } } }, "MonitoringSymbolPosition": { "type": "object", "description": "Symbol position summary for monitoring", "required": [ "symbol", "total_long", "total_short", "net_position", "is_balanced", "holder_count", "holders" ], "properties": { "holder_count": { "type": "integer", "description": "Number of position holders", "minimum": 0 }, "holders": { "type": "array", "items": { "$ref": "#/components/schemas/MonitoringPositionHolder" }, "description": "List of position holders" }, "is_balanced": { "type": "boolean", "description": "Whether positions are balanced" }, "net_position": { "type": "string", "description": "Net position (should be zero for balanced book)" }, "symbol": { "type": "string", "description": "Option symbol" }, "total_long": { "type": "string", "description": "Total long position size" }, "total_short": { "type": "string", "description": "Total short position size" } } }, "OptionSummary": { "type": "object", "required": [ "instrument_id", "instrument_name", "expiration_timestamp", "bid_price", "ask_price", "mark_price", "underlying_price", "underlying_index", "open_interest", "volume", "volume_usd", "interest_rate", "estimated_delivery_price", "creation_timestamp", "base_currency", "quote_currency", "mid_price" ], "properties": { "ask_iv": { "type": "number", "format": "double", "description": "Quote-derived ask-side implied volatility", "nullable": true }, "ask_price": { "type": "number", "format": "double", "description": "Best ask price" }, "base_currency": { "type": "string", "description": "Base currency" }, "bid_iv": { "type": "number", "format": "double", "description": "Quote-derived bid-side implied volatility", "nullable": true }, "bid_price": { "type": "number", "format": "double", "description": "Best bid price" }, "creation_timestamp": { "type": "integer", "format": "int64", "description": "Creation timestamp" }, "estimated_delivery_price": { "type": "number", "format": "double", "description": "Estimated delivery price" }, "expiration_timestamp": { "type": "integer", "format": "int64", "description": "Expiration timestamp" }, "greeks": { "allOf": [ { "$ref": "#/components/schemas/OrderBookGreeks" } ], "nullable": true }, "high": { "type": "number", "format": "double", "description": "24h high", "nullable": true }, "instrument_id": { "type": "integer", "format": "int32", "description": "Instrument ID" }, "instrument_name": { "type": "string", "description": "Instrument name/symbol" }, "interest_rate": { "type": "number", "format": "double", "description": "Interest rate" }, "last": { "type": "number", "format": "double", "description": "Last trade price", "nullable": true }, "low": { "type": "number", "format": "double", "description": "24h low", "nullable": true }, "mark_iv": { "type": "number", "format": "double", "description": "Theoretical implied volatility used for mark price and greeks", "nullable": true }, "mark_price": { "type": "number", "format": "double", "description": "Mark price" }, "mid_price": { "type": "number", "format": "double", "description": "Mid price" }, "open_interest": { "type": "number", "format": "double", "description": "Open interest" }, "option_token_address": { "type": "string", "description": "Option token contract address", "nullable": true }, "price_change": { "type": "number", "format": "double", "description": "24h price change in percentage points, computed as:\n`((current_best_bid - reference_best_ask_near_24h_ago) / reference_best_ask_near_24h_ago) * 100`.", "nullable": true }, "quote_currency": { "type": "string", "description": "Quote currency" }, "theoretical_price": { "type": "number", "format": "double", "description": "Theoretical option price derived from the vol oracle, when available.", "nullable": true }, "underlying_index": { "type": "string", "description": "Underlying index name" }, "underlying_price": { "type": "number", "format": "double", "description": "Underlying price" }, "volume": { "type": "number", "format": "double", "description": "24h volume" }, "volume_usd": { "type": "number", "format": "double", "description": "24h volume in USD" } } }, "OptionType": { "type": "string", "description": "Option type (call or put).", "enum": [ "CALL", "PUT" ] }, "OptionsChainGreeksAbs": { "type": "object", "required": [ "delta", "gamma", "theta", "vega" ], "properties": { "delta": { "type": "number", "format": "double" }, "gamma": { "type": "number", "format": "double" }, "theta": { "type": "number", "format": "double" }, "vega": { "type": "number", "format": "double" } } }, "OptionsChainGreeksCash": { "type": "object", "required": [ "delta_1pct_usd", "gamma_1pct_usd", "theta_1d_usd", "vega_1vol_usd" ], "properties": { "delta_1pct_usd": { "type": "number", "format": "double" }, "gamma_1pct_usd": { "type": "number", "format": "double" }, "theta_1d_usd": { "type": "number", "format": "double" }, "vega_1vol_usd": { "type": "number", "format": "double" } } }, "OptionsChainLeg": { "type": "object", "required": [ "symbol" ], "properties": { "ask_iv": { "type": "number", "format": "double", "nullable": true }, "ask_price_usd": { "type": "number", "format": "double", "nullable": true }, "ask_size_contracts": { "type": "number", "format": "double", "nullable": true }, "ask_size_usd_notional": { "type": "number", "format": "double", "nullable": true }, "bid_iv": { "type": "number", "format": "double", "nullable": true }, "bid_price_usd": { "type": "number", "format": "double", "nullable": true }, "bid_size_contracts": { "type": "number", "format": "double", "nullable": true }, "bid_size_usd_notional": { "type": "number", "format": "double", "nullable": true }, "greeks_abs": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainGreeksAbs" } ], "nullable": true }, "greeks_cash": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainGreeksCash" } ], "nullable": true }, "option_token_address": { "type": "string", "nullable": true }, "symbol": { "type": "string" } } }, "OptionsChainSnapshotResponse": { "type": "object", "required": [ "currency", "expiry", "rows" ], "properties": { "currency": { "type": "string" }, "expiry": { "type": "integer", "format": "int64", "minimum": 0 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/OptionsChainStrikeRow" } } } }, "OptionsChainStrikeRow": { "type": "object", "required": [ "strike" ], "properties": { "call": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainLeg" } ], "nullable": true }, "put": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainLeg" } ], "nullable": true }, "strike": { "type": "number", "format": "double" } } }, "Order": { "type": "object", "required": [ "order_id", "wallet_address", "symbol", "side", "price", "size", "tif", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Creation timestamp" }, "filled_size": { "type": "string", "description": "Amount filled (human-readable, serialized as string)", "nullable": true }, "mmp_enabled": { "type": "boolean", "description": "Whether MMP is enabled for this order" }, "order_id": { "type": "integer", "format": "int64", "description": "Unique order identifier" }, "price": { "type": "string", "description": "Order price" }, "side": { "type": "string", "description": "Order side (\"Buy\" or \"Sell\")" }, "size": { "type": "string", "description": "Order size (human-readable, serialized as string)" }, "status": { "type": "string", "description": "Order status", "nullable": true }, "symbol": { "type": "string", "description": "Instrument symbol" }, "tif": { "type": "string", "description": "Time in force (\"gtc\", \"ioc\", \"fok\")" }, "updated_at": { "type": "string", "description": "Last update timestamp", "nullable": true }, "wallet_address": { "type": "string", "description": "Wallet address that placed the order" } } }, "OrderBookGreeks": { "type": "object", "description": "Option Greeks for order book.", "required": [ "delta", "gamma", "vega", "theta", "rho" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Delta" }, "gamma": { "type": "number", "format": "double", "description": "Gamma" }, "rho": { "type": "number", "format": "double", "description": "Rho" }, "theta": { "type": "number", "format": "double", "description": "Theta" }, "vega": { "type": "number", "format": "double", "description": "Vega" } } }, "OrderBookResponse": { "type": "object", "description": "Orderbook response.", "required": [ "timestamp", "state", "stats", "change_id", "index_price", "instrument_name", "bids", "asks", "settlement_price", "min_price", "max_price", "open_interest", "mark_price", "best_bid_price", "best_ask_price", "underlying_price", "underlying_index", "interest_rate", "estimated_delivery_price", "best_ask_amount", "best_bid_amount" ], "properties": { "ask_iv": { "type": "number", "format": "double", "description": "Quote-derived ask-side implied volatility", "nullable": true }, "asks": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } }, "description": "Ask orders [price, size], where size is in human-readable contracts." }, "best_ask_amount": { "type": "number", "format": "double", "description": "Best ask amount in human-readable contracts." }, "best_ask_price": { "type": "number", "format": "double", "description": "Best ask price" }, "best_bid_amount": { "type": "number", "format": "double", "description": "Best bid amount in human-readable contracts." }, "best_bid_price": { "type": "number", "format": "double", "description": "Best bid price" }, "bid_iv": { "type": "number", "format": "double", "description": "Quote-derived bid-side implied volatility", "nullable": true }, "bids": { "type": "array", "items": { "type": "array", "items": { "type": "number", "format": "double" } }, "description": "Bid orders [price, size], where size is in human-readable contracts." }, "change_id": { "type": "integer", "format": "int64", "description": "Change ID for incremental updates" }, "estimated_delivery_price": { "type": "number", "format": "double", "description": "Estimated delivery price" }, "greeks": { "allOf": [ { "$ref": "#/components/schemas/OrderBookGreeks" } ], "nullable": true }, "index_price": { "type": "number", "format": "double", "description": "Index price" }, "instrument_name": { "type": "string", "description": "Instrument name" }, "interest_rate": { "type": "number", "format": "double", "description": "Interest rate" }, "last_price": { "type": "number", "format": "double", "description": "Last trade price", "nullable": true }, "mark_iv": { "type": "number", "format": "double", "description": "Theoretical implied volatility used for mark price and greeks.", "nullable": true }, "mark_price": { "type": "number", "format": "double", "description": "Mark price" }, "max_price": { "type": "number", "format": "double", "description": "Maximum price" }, "min_price": { "type": "number", "format": "double", "description": "Minimum price" }, "open_interest": { "type": "number", "format": "double", "description": "Open interest" }, "option_token_address": { "type": "string", "description": "Option token contract address", "nullable": true }, "settlement_price": { "type": "number", "format": "double", "description": "Settlement price" }, "state": { "type": "string", "description": "Market state" }, "stats": { "$ref": "#/components/schemas/OrderBookStats" }, "theoretical_price": { "type": "number", "format": "double", "description": "Theoretical option price derived from the vol oracle, when available.", "nullable": true }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp" }, "underlying_index": { "type": "string", "description": "Underlying index name" }, "underlying_price": { "type": "number", "format": "double", "description": "Underlying price" } } }, "OrderBookStats": { "type": "object", "description": "Order book statistics.", "required": [ "volume", "volume_usd" ], "properties": { "high": { "type": "number", "format": "double", "description": "24h high", "nullable": true }, "low": { "type": "number", "format": "double", "description": "24h low", "nullable": true }, "price_change": { "type": "number", "format": "double", "description": "24h price change", "nullable": true }, "volume": { "type": "number", "format": "double", "description": "24h volume" }, "volume_usd": { "type": "number", "format": "double", "description": "24h volume in USD" } } }, "OrderInfo": { "type": "object", "description": "Order information.", "required": [ "symbol", "price", "size", "side", "tif", "is_perp" ], "properties": { "builder_code_address": { "type": "string", "description": "Optional builder code address for fee rebates", "nullable": true }, "client_id": { "type": "string", "description": "Client-provided order ID", "nullable": true }, "is_perp": { "type": "boolean", "description": "Whether this is a perp order (required - must be explicitly set)" }, "mmp_enabled": { "type": "boolean", "description": "Whether MMP is enabled" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "nullable": true, "minimum": 0 }, "order_id": { "type": "integer", "format": "int64", "description": "Exchange-assigned order ID", "nullable": true, "minimum": 0 }, "price": { "type": "string", "description": "Order price" }, "reduce_only": { "type": "boolean", "description": "Reduce-only flag for perp orders", "nullable": true }, "side": { "$ref": "#/components/schemas/Side" }, "signature": { "type": "string", "description": "EIP-712 signature", "nullable": true }, "size": { "type": "string", "description": "Order size in raw units" }, "symbol": { "type": "string", "description": "Instrument symbol" }, "tif": { "$ref": "#/components/schemas/TimeInForce" }, "underlying": { "type": "string", "description": "Underlying asset for perp orders", "nullable": true } } }, "OrderUpdateMessage": { "type": "object", "description": "Order update message.", "required": [ "timestamp", "info", "status", "filled_size", "wallet_address" ], "properties": { "filled_size": { "type": "string", "description": "Amount filled so far" }, "info": { "$ref": "#/components/schemas/OrderInfo" }, "mmp_triggered": { "type": "boolean", "description": "Whether MMP triggered this update" }, "order_id": { "type": "integer", "format": "int64", "description": "Exchange-assigned order ID", "nullable": true, "minimum": 0 }, "reason": { "type": "string", "description": "Reason for rejection or cancellation", "nullable": true }, "request_id": { "type": "string", "description": "Request ID for correlating this update with the original command.\nPopulated from the triggering OrderActionMessage's request_id.", "nullable": true }, "status": { "$ref": "#/components/schemas/OrderUpdateStatus" }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp in milliseconds", "minimum": 0 }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "OrderUpdateStatus": { "type": "string", "description": "Order update status (used in order update messages).", "enum": [ "ACKED", "OPEN", "PARTIALLY_FILLED", "FILLED", "CANCELED", "REJECTED" ] }, "OrderbookIntegrityReport": { "type": "object", "description": "Orderbook integrity report", "required": [ "timestamp", "total_orderbooks", "crossed_count", "stale_count", "crossed_orderbooks" ], "properties": { "crossed_count": { "type": "integer", "description": "Number of crossed orderbooks (bid >= ask)", "minimum": 0 }, "crossed_orderbooks": { "type": "array", "items": { "$ref": "#/components/schemas/CrossedOrderbook" }, "description": "Details of each crossed orderbook" }, "stale_count": { "type": "integer", "description": "Number of stale orderbooks (>60s since last update)", "minimum": 0 }, "timestamp": { "type": "string", "description": "Timestamp of the report" }, "total_orderbooks": { "type": "integer", "description": "Total number of orderbooks in cache", "minimum": 0 } } }, "OrdersResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" }, "description": "List of orders" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "Pagination": { "type": "object", "required": [ "limit", "offset", "count" ], "properties": { "count": { "type": "integer", "description": "Total number of results returned", "minimum": 0 }, "limit": { "type": "integer", "description": "Number of results per page", "minimum": 0 }, "offset": { "type": "integer", "description": "Number of results to skip", "minimum": 0 } } }, "PlaceOrderRequest": { "type": "object", "description": "Request body for placing an order.", "required": [ "wallet", "price", "size", "symbol", "side", "nonce", "signature" ], "properties": { "builder_code_address": { "type": "string", "description": "Optional builder code address for fee rebates", "nullable": true }, "client_id": { "type": "string", "nullable": true }, "mmp_enabled": { "type": "boolean" }, "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "price": { "type": "string", "description": "Price as string (must match signed value exactly)" }, "side": { "$ref": "#/components/schemas/Side" }, "signature": { "type": "string" }, "size": { "type": "string", "description": "Size as string (must match signed value exactly)" }, "symbol": { "type": "string" }, "tif": { "$ref": "#/components/schemas/TimeInForce" }, "wallet": { "type": "string" } } }, "Portfolio": { "type": "object", "required": [ "wallet_address", "positions", "total_margin_used", "available_balance" ], "properties": { "available_balance": { "type": "string", "description": "Available balance for new positions = max(equity - position_im - open_orders_im, 0)" }, "margin_mode": { "type": "string", "description": "Margin mode for this account (\"standard\" or \"portfolio\")\nStandard = Deribit-style linear margin\nPortfolio = SPAN-based scenario margin" }, "margin_summary": { "allOf": [ { "$ref": "#/components/schemas/MarginSummary" } ], "nullable": true }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PositionWithMetrics" }, "description": "List of positions with metrics" }, "span_margin": { "allOf": [ { "$ref": "#/components/schemas/SpanMarginSummary" } ], "nullable": true }, "total_margin_used": { "type": "string", "description": "Total margin used across all positions (IM + open orders IM)" }, "wallet_address": { "type": "string", "description": "Account wallet address" } } }, "PortfolioGreeksAggregate": { "type": "object", "description": "Aggregate Greeks across all legs in a portfolio Greeks response.", "required": [ "delta", "gamma", "theta", "vega" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Aggregate delta" }, "gamma": { "type": "number", "format": "double", "description": "Aggregate gamma" }, "iv": { "type": "number", "format": "double", "description": "Aggregate implied volatility (vega-weighted), null when total vega is zero", "nullable": true }, "theta": { "type": "number", "format": "double", "description": "Aggregate theta" }, "vega": { "type": "number", "format": "double", "description": "Aggregate vega" } } }, "PortfolioGreeksApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/PortfolioGreeksResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "PortfolioGreeksResponse": { "type": "object", "description": "Portfolio Greeks response.", "required": [ "wallet_address" ], "properties": { "aggregate": { "allOf": [ { "$ref": "#/components/schemas/PortfolioGreeksAggregate" } ], "nullable": true }, "per_leg": { "type": "array", "items": { "$ref": "#/components/schemas/PositionGreeksLeg" }, "description": "Per-leg Greeks" }, "wallet_address": { "type": "string", "description": "Account wallet address" } } }, "Position": { "type": "object", "required": [ "wallet_address", "symbol", "amount", "entry_price", "margin_posted", "realized_pnl", "unrealized_pnl", "updated_at" ], "properties": { "amount": { "type": "string", "description": "Position size in contracts" }, "entry_price": { "type": "string", "description": "Average entry price" }, "margin_posted": { "type": "string", "description": "Margin posted for this position" }, "realized_pnl": { "type": "string", "description": "Realized profit/loss from closed positions" }, "symbol": { "type": "string", "description": "Option symbol" }, "unrealized_pnl": { "type": "string", "description": "Unrealized profit/loss from mark-to-market" }, "updated_at": { "type": "string", "description": "Last update timestamp" }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "PositionGreeksLeg": { "type": "object", "description": "Per-leg Greeks in a portfolio Greeks response.", "required": [ "symbol", "quantity", "delta", "gamma", "theta", "vega", "iv" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Delta for this leg" }, "gamma": { "type": "number", "format": "double", "description": "Gamma for this leg" }, "iv": { "type": "number", "format": "double", "description": "Implied volatility for this leg" }, "quantity": { "type": "string", "description": "Net position quantity for this leg (human-readable contracts)" }, "symbol": { "type": "string", "description": "Option symbol" }, "theta": { "type": "number", "format": "double", "description": "Theta for this leg" }, "vega": { "type": "number", "format": "double", "description": "Vega for this leg" } } }, "PositionImbalance": { "type": "object", "description": "Position imbalance details for a symbol", "required": [ "symbol", "net_position", "severity" ], "properties": { "net_position": { "type": "string", "description": "Net position (should be zero for balanced book)" }, "severity": { "$ref": "#/components/schemas/IntegrityStatus" }, "symbol": { "type": "string", "description": "Option symbol" } } }, "PositionSummary": { "type": "object", "description": "Summary of open positions across all accounts", "required": [ "total_open_interest", "unique_instruments", "net_position_imbalances" ], "properties": { "net_position_imbalances": { "type": "array", "items": { "$ref": "#/components/schemas/PositionImbalance" }, "description": "List of symbols with position imbalances (should be empty)" }, "total_open_interest": { "type": "string", "description": "Total open interest across all instruments" }, "unique_instruments": { "type": "integer", "format": "int64", "description": "Number of unique instruments with positions" } } }, "PositionWithMetrics": { "allOf": [ { "$ref": "#/components/schemas/Position" }, { "type": "object", "required": [ "notional_value", "maintenance_margin", "liquidation_price", "margin_ratio" ], "properties": { "liquidation_price": { "type": "string", "description": "Price at which position will be liquidated" }, "maintenance_margin": { "type": "string", "description": "Required maintenance margin" }, "margin_ratio": { "type": "string", "description": "Current margin ratio" }, "notional_value": { "type": "string", "description": "Notional value of position" } } } ] }, "ProfileCompetitionRankSummary": { "type": "object", "required": [ "competition_id", "competition_name", "competition_state", "rank", "pnl", "volume", "efficiency" ], "properties": { "competition_id": { "type": "integer", "format": "int64" }, "competition_name": { "type": "string" }, "competition_state": { "$ref": "#/components/schemas/CompetitionStateValue" }, "efficiency": { "type": "string" }, "medal": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "pnl": { "type": "string" }, "rank": { "type": "integer", "minimum": 0 }, "volume": { "type": "string" } } }, "ProfileData": { "type": "object", "required": [ "wallet", "username", "margin", "pnl", "platform_medals" ], "properties": { "account_age_days": { "type": "integer", "format": "int64", "nullable": true }, "account_first_seen_ts_ms": { "type": "integer", "format": "int64", "nullable": true }, "active_competition_rank": { "allOf": [ { "$ref": "#/components/schemas/ProfileCompetitionRankSummary" } ], "nullable": true }, "margin": { "$ref": "#/components/schemas/ProfileMarginStats" }, "medal": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "platform_medals": { "$ref": "#/components/schemas/ProfileMetricMedals" }, "pnl": { "$ref": "#/components/schemas/ProfilePnlStats" }, "username": { "type": "string" }, "wallet": { "type": "string" } } }, "ProfileMarginStats": { "type": "object", "required": [ "in_use", "available", "total", "deposits", "withdraws" ], "properties": { "available": { "type": "string" }, "deposits": { "type": "string" }, "in_use": { "type": "string" }, "total": { "type": "string" }, "withdraws": { "type": "string" } } }, "ProfileMetricMedals": { "type": "object", "properties": { "efficiency": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "pnl": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 }, "volume": { "type": "integer", "format": "int32", "nullable": true, "minimum": 0 } } }, "ProfilePnlStats": { "type": "object", "required": [ "unrealized", "pnl_24h", "lifetime_realized" ], "properties": { "lifetime_realized": { "type": "string" }, "pnl_24h": { "type": "string" }, "unrealized": { "type": "string" } } }, "ProfileResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProfileData" }, "success": { "type": "boolean" } } }, "ProfileTradesResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FillApiResponse" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } } }, "ReadinessComponentReport": { "type": "object", "description": "Component readiness report", "required": [ "name", "ready" ], "properties": { "detail": { "type": "string", "description": "Optional detail about the component's state", "nullable": true }, "name": { "type": "string", "description": "Name of the component" }, "ready": { "type": "boolean", "description": "Whether the component is ready" } } }, "ReadyResponse": { "type": "object", "description": "Readiness check response", "required": [ "status", "components" ], "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessComponentReport" }, "description": "Component readiness reports" }, "message": { "type": "string", "description": "Optional message (present when not ready)", "nullable": true }, "status": { "type": "string", "description": "Readiness status (\"ready\" or \"not_ready\")" } } }, "ResetMmpRequest": { "type": "object", "description": "Request to reset MMP state", "required": [ "wallet", "currency", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Currency to reset MMP for" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "RevokeAgentRequest": { "type": "object", "description": "Request to revoke an agent wallet.", "required": [ "agent", "nonce", "signature" ], "properties": { "agent": { "type": "string", "description": "Agent wallet address to revoke" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for replay protection", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature from wallet owner" } } }, "RevokeAgentResponse": { "type": "object", "description": "Response for revoking an agent.", "required": [ "success" ], "properties": { "error": { "type": "string", "description": "Error message if failed", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request succeeded" } } }, "SetGlobalTradingHaltRequest": { "type": "object", "required": [ "halted", "reason" ], "properties": { "halted": { "type": "boolean" }, "reason": { "type": "string" } } }, "SetMarginModeRequest": { "type": "object", "description": "Request to change margin mode", "required": [ "wallet", "margin_mode", "nonce", "signature" ], "properties": { "margin_mode": { "type": "string", "description": "New margin mode (\"standard\" or \"portfolio\")" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "SetMarketTradingHaltRequest": { "type": "object", "required": [ "symbol", "halted", "reason" ], "properties": { "halted": { "type": "boolean" }, "reason": { "type": "string" }, "symbol": { "type": "string" } } }, "SetMmpConfigRequest": { "type": "object", "description": "Request to set MMP configuration", "required": [ "wallet", "currency", "interval_ms", "frozen_time_ms", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Currency (e.g., \"BTC\", \"ETH\")" }, "delta_limit": { "type": "string", "description": "Delta limit (optional)", "nullable": true }, "frozen_time_ms": { "type": "integer", "format": "int64", "description": "Frozen time in milliseconds after MMP triggers" }, "interval_ms": { "type": "integer", "format": "int64", "description": "Monitoring interval in milliseconds" }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "qty_limit": { "type": "string", "description": "Quantity limit (optional)", "nullable": true }, "signature": { "type": "string", "description": "EIP-712 signature" }, "vega_limit": { "type": "string", "description": "Vega limit (optional)", "nullable": true }, "wallet": { "type": "string", "description": "Wallet address" } } }, "SetUserTierRequest": { "type": "object", "description": "Request to set user tier", "required": [ "wallet", "tier", "nonce", "signature" ], "properties": { "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature" }, "tier": { "type": "string", "description": "Tier (\"tier1\" or \"tier2\")" }, "wallet": { "type": "string", "description": "Wallet address" } } }, "SetUsernameRequest": { "type": "object", "required": [ "username" ], "properties": { "username": { "type": "string" } } }, "SettlementPayoutEntry": { "type": "object", "description": "Settlement payout entry.", "required": [ "id", "wallet", "symbol", "expiry_ts", "position_size", "settlement_price", "settlement_value", "ledger_applied", "is_seen" ], "properties": { "cost_basis": { "type": "string", "description": "Position cost basis at settlement.", "nullable": true }, "created_at": { "type": "integer", "format": "int64", "description": "Creation time in milliseconds since epoch.", "nullable": true }, "expiry_ts": { "type": "integer", "format": "int64", "description": "Expiry timestamp (seconds since epoch)." }, "id": { "type": "integer", "format": "int64", "description": "Settlement payout row ID." }, "is_seen": { "type": "boolean", "description": "Whether this payout has been marked seen by the wallet." }, "ledger_applied": { "type": "boolean", "description": "Whether this payout was applied to the ledger." }, "net_pnl": { "type": "string", "description": "Net settlement PnL (excluding fees).", "nullable": true }, "position_size": { "type": "string", "description": "Position size settled." }, "settlement_entry_price": { "type": "string", "description": "User per-contract entry price at settlement time.", "nullable": true }, "settlement_price": { "type": "string", "description": "Settlement price used." }, "settlement_value": { "type": "string", "description": "Settlement value credited/debited." }, "symbol": { "type": "string", "description": "Option symbol." }, "wallet": { "type": "string", "description": "Wallet address." } } }, "SettlementPayoutSeenMutationResponse": { "type": "object", "description": "Response for marking payouts as seen.", "required": [ "success", "requested", "affected" ], "properties": { "affected": { "type": "integer", "description": "Number of rows affected in storage.", "minimum": 0 }, "error": { "type": "string", "description": "Error message (if any).", "nullable": true }, "requested": { "type": "integer", "description": "Number of IDs requested in the payload.", "minimum": 0 }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "SettlementPayoutSeenRequest": { "type": "object", "description": "Request body for marking payouts as seen.", "required": [ "wallet", "ids", "nonce", "signature" ], "properties": { "ids": { "type": "array", "items": { "type": "integer", "format": "int64" }, "description": "Settlement payout IDs to update.\nSignature verification hashes IDs as a comma-separated string in request order." }, "nonce": { "type": "integer", "format": "int64", "description": "Nonce for EIP-712 signature verification.", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature." }, "wallet": { "type": "string", "description": "Wallet performing the action.", "example": "0x1234567890123456789012345678901234567890" } } }, "SettlementPayoutsResponse": { "type": "object", "description": "Settlement payouts response.", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/SettlementPayoutEntry" }, "description": "Settlement payout entries." }, "error": { "type": "string", "description": "Error message (if any).", "nullable": true }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request was successful." } } }, "SettlementSummary": { "type": "object", "description": "Summary of settlement processing", "required": [ "total", "applied", "pending", "total_value" ], "properties": { "applied": { "type": "integer", "format": "int64", "description": "Number of settlements applied" }, "pending": { "type": "integer", "format": "int64", "description": "Number of settlements pending" }, "total": { "type": "integer", "format": "int64", "description": "Total number of settlements" }, "total_value": { "type": "string", "description": "Total value of settlements (USD)" } } }, "Side": { "type": "string", "description": "Order side (buy or sell).", "enum": [ "Buy", "Sell" ] }, "SignatureRequest": { "type": "object", "description": "Request with signature for authentication", "required": [ "wallet_address", "timestamp", "signature" ], "properties": { "signature": { "type": "string", "description": "Signature from wallet" }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp for signature verification" }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "SimulatedGreeksOrder": { "type": "object", "description": "Simulated order input used for portfolio Greeks what-if calculations.", "required": [ "symbol", "side", "size" ], "properties": { "side": { "$ref": "#/components/schemas/Side" }, "size": { "type": "string", "description": "Order size in human-readable contracts" }, "symbol": { "type": "string", "description": "Option symbol (e.g., \"BTC-20260115-100000-C\")" } } }, "SpanMarginSummary": { "type": "object", "description": "Portfolio Margin summary from the engine.\n\nThis provides the margin requirements computed via SPAN-style scenario analysis.\nOrder admission requires: `equity >= initial_margin_required`", "required": [ "equity", "initial_margin_required", "maintenance_margin_required", "option_margin_required", "scanning_risk", "option_floor", "gamma_overlay", "hypercore_margin_required" ], "properties": { "equity": { "type": "string", "description": "Executed PM equity = cash + executed option UPNL + executed perp UPNL.\nSpot collateral is excluded in this phase." }, "gamma_overlay": { "type": "string", "description": "Additive short-dated contingency margin" }, "hypercore_margin_required": { "type": "string", "description": "Perp margin component (deprecated, always 0.0)" }, "initial_margin_required": { "type": "string", "description": "Initial margin required from executed positions\n(= max(scanning_risk, option_floor) + gamma_overlay)" }, "maintenance_margin_required": { "type": "string", "description": "Maintenance margin required to maintain positions (= IM * 0.85)\nLiquidation triggers when equity < maintenance_margin_required." }, "open_orders_initial_margin": { "type": "string", "description": "Additional IM from hypothetical open orders.\nOpen orders affect IM and scenario outputs, never equity." }, "option_floor": { "type": "string", "description": "Minimum contingency margin for net short options" }, "option_margin_required": { "type": "string", "description": "Scenario-based risk component before PM contingencies" }, "scanning_risk": { "type": "string", "description": "Weighted worst-case loss across PM scenarios" } } }, "SymbolIvPoint": { "type": "object", "required": [ "timestamp_ms" ], "properties": { "iv": { "type": "number", "format": "double", "nullable": true }, "timestamp_ms": { "type": "integer", "format": "int64" } } }, "TickSizeStep": { "type": "object", "description": "Tick size step for instrument pricing.", "required": [ "tick_size", "above_price" ], "properties": { "above_price": { "type": "number", "format": "double", "description": "Price above which this tick size applies" }, "tick_size": { "type": "number", "format": "double", "description": "Tick size at this level" } } }, "TimeInForce": { "type": "string", "description": "Time in force for orders.", "enum": [ "gtc", "ioc", "fok" ] }, "TradeApiResponse": { "type": "object", "required": [ "trade_id", "symbol", "price", "size", "maker_address", "taker_address", "maker_fee", "taker_fee", "timestamp", "created_at" ], "properties": { "created_at": { "type": "string", "description": "Record creation timestamp" }, "maker_address": { "type": "string", "description": "Maker wallet address" }, "maker_fee": { "type": "string", "description": "Maker fee in USD" }, "price": { "type": "string", "description": "Execution price in USD" }, "size": { "type": "string", "description": "Trade size in contracts (human-readable units)" }, "symbol": { "type": "string", "description": "Option symbol (e.g., \"BTC-20250131-100000-C\")" }, "taker_address": { "type": "string", "description": "Taker wallet address" }, "taker_fee": { "type": "string", "description": "Taker fee in USD" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp in milliseconds" }, "trade_id": { "type": "integer", "format": "int64", "description": "Unique trade identifier" } } }, "TradesResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TradeApiResponse" }, "description": "List of trades" }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "TradingHaltActivation": { "type": "object", "required": [ "scope", "halted", "reason", "activated_by", "activated_at" ], "properties": { "activated_at": { "type": "string", "format": "date-time" }, "activated_by": { "type": "string" }, "halted": { "type": "boolean" }, "reason": { "type": "string" }, "scope": { "$ref": "#/components/schemas/TradingHaltScope" }, "symbol": { "type": "string", "nullable": true } } }, "TradingHaltScope": { "type": "string", "enum": [ "global", "market" ] }, "TradingHaltsResponse": { "type": "object", "required": [ "halted_markets", "audit_log" ], "properties": { "audit_log": { "type": "array", "items": { "$ref": "#/components/schemas/TradingHaltActivation" } }, "global_halt": { "allOf": [ { "$ref": "#/components/schemas/TradingHaltActivation" } ], "nullable": true }, "halted_markets": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/TradingHaltActivation" } } } }, "UnderlyingCandle": { "type": "object", "required": [ "start_time_ms", "end_time_ms", "open", "high", "low", "close", "volume" ], "properties": { "close": { "type": "number", "format": "double" }, "end_time_ms": { "type": "integer", "format": "int64" }, "high": { "type": "number", "format": "double" }, "low": { "type": "number", "format": "double" }, "open": { "type": "number", "format": "double" }, "start_time_ms": { "type": "integer", "format": "int64" }, "volume": { "type": "number", "format": "double" } } }, "UnderlyingCandlesResponse": { "type": "object", "required": [ "underlying", "resolution", "candles" ], "properties": { "candles": { "type": "array", "items": { "$ref": "#/components/schemas/UnderlyingCandle" } }, "resolution": { "$ref": "#/components/schemas/CandleResolution" }, "underlying": { "type": "string" } } }, "UserTierData": { "type": "object", "required": [ "wallet_address", "tier" ], "properties": { "tier": { "type": "string", "description": "User tier (\"tier1\" or \"tier2\")" }, "wallet_address": { "type": "string", "description": "Wallet address" } } }, "UserTierResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/UserTierData" }, "success": { "type": "boolean", "description": "Whether the request was successful" } } }, "UsernameChangeRequestData": { "type": "object", "required": [ "id", "wallet_address", "requested_username", "status", "created_at", "updated_at" ], "properties": { "created_at": { "type": "string" }, "id": { "type": "integer", "format": "int64" }, "moderator_note": { "type": "string", "nullable": true }, "requested_username": { "type": "string" }, "reviewed_at": { "type": "string", "nullable": true }, "reviewed_by": { "type": "string", "nullable": true }, "status": { "type": "string" }, "updated_at": { "type": "string" }, "wallet_address": { "type": "string" } } }, "UsernameChangeRequestResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/UsernameChangeRequestData" }, "success": { "type": "boolean" } } }, "UsernameChangeRequestReview": { "type": "object", "required": [ "decision" ], "properties": { "decision": { "type": "string" }, "moderator_note": { "type": "string", "nullable": true } } }, "UsernameChangeRequestSubmit": { "type": "object", "required": [ "wallet", "requested_username", "nonce", "signature" ], "properties": { "nonce": { "type": "integer", "format": "int64", "description": "Nonce for signature verification", "minimum": 0 }, "requested_username": { "type": "string" }, "signature": { "type": "string", "description": "EIP-712 signature" }, "wallet": { "type": "string" } } }, "UsernameChangeRequestsResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/UsernameChangeRequestData" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } } }, "UsernameResponse": { "type": "object", "required": [ "wallet_address", "username" ], "properties": { "username": { "type": "string" }, "wallet_address": { "type": "string" } } }, "VersionResponse": { "type": "object", "description": "Version information response", "required": [ "version", "commit", "ref", "build_time" ], "properties": { "build_time": { "type": "string", "description": "Build timestamp" }, "commit": { "type": "string", "description": "Git commit hash" }, "ref": { "type": "string", "description": "Git ref (branch or tag)" }, "version": { "type": "string", "description": "Application version from Cargo.toml" } } }, "VolOracleStatusResponse": { "type": "object", "required": [ "underlying", "provider", "connected", "ready", "surface_points", "messages_received" ], "properties": { "connected": { "type": "boolean" }, "last_error": { "type": "string", "nullable": true }, "last_update_ts_ms": { "type": "integer", "format": "int64", "nullable": true }, "messages_received": { "type": "integer", "format": "int64", "minimum": 0 }, "provider": { "type": "string" }, "ready": { "type": "boolean" }, "staleness_seconds": { "type": "number", "format": "double", "nullable": true }, "surface_points": { "type": "integer", "minimum": 0 }, "underlying": { "type": "string" } } }, "VolOracleStatusesResponse": { "type": "object", "required": [ "statuses" ], "properties": { "statuses": { "type": "array", "items": { "$ref": "#/components/schemas/VolOracleStatusResponse" } } } }, "VolPoint": { "type": "object", "description": "A single point on the volatility surface.", "required": [ "strike", "expiry", "iv", "timestamp" ], "properties": { "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp in Unix seconds" }, "iv": { "type": "number", "format": "double", "description": "Implied volatility as decimal (0.80 = 80%)" }, "strike": { "type": "number", "format": "double", "description": "Strike price in USD" }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp when this point was last updated (milliseconds)" } } }, "VolSurfaceApiResponse": { "type": "object", "required": [ "surfaces" ], "properties": { "surfaces": { "type": "array", "items": { "$ref": "#/components/schemas/VolSurfaceSnapshot" } } } }, "VolSurfaceHistoryPoint": { "type": "object", "required": [ "timestamp_ms", "surface_json" ], "properties": { "surface_json": {}, "timestamp_ms": { "type": "integer", "format": "int64" } } }, "VolSurfaceHistoryResponse": { "type": "object", "required": [ "underlying", "interval_ms", "points" ], "properties": { "interval_ms": { "type": "integer", "format": "int64" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/VolSurfaceHistoryPoint" } }, "underlying": { "type": "string" } } }, "VolSurfaceSnapshot": { "type": "object", "description": "Full snapshot of a volatility surface for a single underlying, used for\npersistence and API serialisation.", "required": [ "underlying", "expiries", "strike_points", "delta_curves", "atm_vols" ], "properties": { "atm_vols": { "type": "array", "items": { "type": "array", "items": { "allOf": [ { "type": "integer", "format": "int64" }, { "type": "number", "format": "double" } ] } } }, "delta_curves": { "type": "array", "items": { "$ref": "#/components/schemas/DeltaCurveExport" } }, "expiries": { "type": "array", "items": { "type": "integer", "format": "int64" } }, "last_update_ts_ms": { "type": "integer", "format": "int64", "nullable": true }, "spot_price": { "type": "number", "format": "double", "nullable": true }, "strike_points": { "type": "array", "items": { "$ref": "#/components/schemas/VolPoint" } }, "underlying": { "type": "string" } } }, "VolSurfaceSymbolResponse": { "type": "object", "required": [ "symbol", "underlying", "strike", "expiry", "interval_ms", "points" ], "properties": { "expiry": { "type": "integer", "format": "int64" }, "interval_ms": { "type": "integer", "format": "int64" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/SymbolIvPoint" } }, "strike": { "type": "number", "format": "double" }, "symbol": { "type": "string" }, "underlying": { "type": "string" } } }, "WalletAddress": { "type": "string", "description": "Canonical representation of an Ethereum wallet address for Hypertheta.\n\nThis wraps alloy's [`Address`] type so we consistently work with the\n20-byte value internally while keeping serde compatibility with hex strings.\n\nStorage:\n- In-memory: 20-byte alloy `Address`\n- JSON/Kafka: Checksummed hex string with `0x` prefix (via serde)\n- PostgreSQL: BYTEA (20 bytes) via Diesel and sqlx", "example": "0x1234567890abcdef1234567890abcdef12345678" } }, "securitySchemes": { "eip712_signature": { "type": "http", "scheme": "bearer", "bearerFormat": "EIP-712", "description": "EIP-712 typed signature authentication. Include 'wallet', 'nonce', and 'signature' fields in the request body." }, "wallet_query": { "type": "apiKey", "in": "query", "name": "wallet" } } }, "tags": [ { "name": "Health", "description": "Health check and readiness endpoints for monitoring and load balancers." }, { "name": "Markets", "description": "Market data, instruments, orderbooks, and greeks. Public endpoints with no authentication required." }, { "name": "Trading", "description": "Order placement and cancellation. Requires EIP-712 signature authentication. Price and size must be strings for signature verification." }, { "name": "Portfolio", "description": "Account portfolio, open orders, and trade history. Public endpoints accepting wallet query parameter." }, { "name": "MMP", "description": "Market Maker Protection configuration. Allows setting limits on cumulative delta, vega, and quantity within a time window to automatically freeze trading." }, { "name": "Agents", "description": "Agent authorization management. Allows delegating signing authority to agent wallets." }, { "name": "Competition", "description": "Competition lifecycle, leaderboard rankings, and profile competition stats." }, { "name": "WebSocket", "description": "Real-time data streaming via WebSocket.\n\n## Connection\n\nConnect to `ws://HOST/ws` (or `wss://` for TLS). Query parameters:\n- `wallet` (optional): Wallet address for authenticated channels\n\n## Message Format\n\nAll messages are JSON with a `type` field.\n\n### Client Messages\n\n**Subscribe**: `{\"type\": \"Subscribe\", \"channel\": \"orderbook\"}`\n\n**Subscribe (options chain with filters)**: `{\"type\": \"Subscribe\", \"channel\": \"options_chain\", \"symbols\": [\"BTC-20260331-100000-C\"], \"expiry\": \"2026-03-31\", \"option_type\": \"both\"}`\n\n**Unsubscribe**: `{\"type\": \"Unsubscribe\", \"channel\": \"orderbook\"}`\n\n**Unsubscribe (options chain with filters)**: `{\"type\": \"Unsubscribe\", \"channel\": \"options_chain\", \"symbols\": [\"BTC-20260331-100000-C\"], \"expiry\": \"2026-03-31\", \"option_type\": \"both\"}`\n\nFor `options_chain`, all filter fields are optional. `symbols` supports multiple symbols, `expiry` uses `YYYY-MM-DD`, and `option_type` is `call|put|both`.\n\n### Available Channels\n\n| Channel | Auth | Description |\n|---------|------|-------------|\n| `orderbook` | No | L2 orderbook updates (all symbols) |\n| `options_chain` | No | Incremental options chain updates |\n| `trades` | No | Public trade feed |\n| `market_updates` | No | Market listing changes |\n| `candles::` | No | Realtime underlying candle updates |\n| `order_updates` | Yes | Your order status changes |\n| `fills` | Yes | Your trade fills |\n| `portfolio` | Yes | Your position/balance updates |\n| `liquidation` | Yes | Your liquidation state changes |\n| `competition` | Yes | Your competition rank/final stats |\n| `competition_engagement` | Yes | Your rank jumps, gap-to-next, and final standing |\n\n### Server Messages\n\n**Subscribed**: `{\"type\": \"Subscribed\", \"channel\": \"orderbook\"}`\n\n**OrderbookUpdate**: `{\"type\": \"OrderbookUpdate\", \"symbol\": \"BTC-...\", \"option_token_address\": \"0x...\", \"bids\": [[price, size]], \"asks\": [[price, size]], \"timestamp\": 123}`\n\n**OptionsChainUpdate (Upsert)**: `{\"type\": \"OptionsChainUpdate\", \"action\": \"Upsert\", \"currency\": \"BTC\", \"expiry\": 1774944000, \"row\": {\"strike\": 100000.0, \"call\": {\"symbol\": \"BTC-20260331-100000-C\", \"bid_price_usd\": 100.0, \"ask_price_usd\": 101.0}, \"put\": null}, \"timestamp\": 123}`\n\n**OptionsChainUpdate (Remove)**: `{\"type\": \"OptionsChainUpdate\", \"action\": \"Remove\", \"currency\": \"BTC\", \"expiry\": 1774944000, \"strike\": 100000.0, \"option_type\": \"call\", \"symbol\": \"BTC-20260331-100000-C\", \"timestamp\": 124}`\n\n**Trade**: `{\"type\": \"Trade\", \"symbol\": \"BTC-...\", \"price\": \"100.5\", \"size\": \"1.0\", \"side\": \"buy\", \"timestamp\": 123}`\n\n**CandleUpdate**: `{\"type\": \"CandleUpdate\", \"underlying\": \"BTC\", \"resolution\": \"1m\", \"start_time_ms\": 123, \"end_time_ms\": 456, \"open\": 100.0, \"high\": 101.0, \"low\": 99.0, \"close\": 100.5, \"volume\": 12.3}`\n\n**OrderUpdate**: `{\"type\": \"OrderUpdate\", \"order_id\": 123, \"status\": \"filled\", ...}`\n\n**Fill**: `{\"type\": \"Fill\", \"order_id\": 123, \"fill_id\": 456, \"price\": \"100.5\", \"size\": \"1.0\", ...}`\n\n**PortfolioUpdate**: `{\"type\": \"PortfolioUpdate\", \"wallet\": \"0x...\", \"positions\": {...}, \"balance\": {...}}`\n\n**CompetitionRankChange**: `{\"type\": \"CompetitionRankChange\", \"wallet_address\": \"0x...\", \"competition_id\": 12, \"from_rank\": 20, \"to_rank\": 17, \"delta_places\": 3, \"pnl\": \"125.5\", \"timestamp\": 123}`\n\n**CompetitionGapUpdate**: `{\"type\": \"CompetitionGapUpdate\", \"wallet_address\": \"0x...\", \"competition_id\": 12, \"rank\": 17, \"next_rank\": 16, \"gap_metric_value\": \"200\", \"timestamp\": 123}` (gap measured in the competition's `primary_win_condition` metric)\n\n**CompetitionFinalStanding**: `{\"type\": \"CompetitionFinalStanding\", \"wallet_address\": \"0x...\", \"competition_id\": 12, \"rank\": 2, \"pnl\": \"320.1\", \"volume\": \"1500\", \"efficiency\": \"0.2134\", \"medal\": 2, \"timestamp\": 123}`\n\n**Error**: `{\"type\": \"Error\", \"message\": \"...\"}`" }, { "name": "Username", "description": "Wallet display-name management. Public lookup by wallet or username; authenticated set/delete via EIP-712 signature." } ] }