{ "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- **Testnet**: `https://testnet-api.hypercall.xyz`\n- **Production**: `https://api.hypercall.xyz`\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 has been approved via `POST /approve-agent` for the wallet (engine-owned state, read from lock-free snapshot)\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" }, { "url": "https://api.hypercall.xyz", "description": "Production" } ], "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", "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": [] } ] }, "put": { "tags": [ "Trading" ], "summary": "Replace multiple orders using cancel-all-then-create-all ordering.", "description": "Per-leg semantics mirror PUT /order (cancel old + place new), but across\na batch every leg's cancel is enqueued before any create, so the engine\ncannot match a new leg against a sibling's still-resting opposite. This\neliminates the self-trade-prevention kill path that fired when the bulk\ndispatched independent ReplaceOrder commands. A per-leg response is\nreturned in original index order; a leg whose cancel failed (already\nfilled / not found) is skipped for the create phase and returned with\nthe cancel rejection details. Not atomic across the batch: the gap\nbetween a leg's cancel committing and its create landing is per-leg.\nSee engineering-docs/docs/flows/order-lifecycle.mdx for tradeoffs vs.\nthe single-command PUT /order path.\nBulk replace orders.\n\nExecutes **cancel-all-then-create-all** ordering across the batch: every\nleg's cancel is enqueued before any create, so the engine is guaranteed\nto process all cancels (removing every old leg from the book) before any\nnew order matches. Without this, the engine's FIFO processing of\nindependent `OrderAction::ReplaceOrder` commands meant each command's\nphase-2 place could match against a sibling's still-resting opposite\nleg, triggering self-trade prevention and losing the new leg entirely.\n\nThe path is:\n1. `validate_replace_request` per leg (sig / auth / parse / precision).\n2. `orchestrate_bulk_replace` dispatches all `CancelOrder` commands,\nawaits responses, then dispatches `CreateOrder` commands only for\nlegs whose cancel actually reached `Canceled`.\n3. Per-leg results merge: prefer the create response; fall back to a\ncancel-only result when the cancel landed but the create didn't.\n\nSemantics vs. single-command `ReplaceOrder`: the `PUT /order` single-\nreplace path dispatches **one** `OrderAction::ReplaceOrder` engine command\nthat handles the cancel and place atomically within one engine tick and\none journal entry (`src/rsm/unified_engine/order_routing.rs:process_replace_order`).\nThe bulk path, by contrast, issues separate `CancelOrder` and `CreateOrder`\ncommands (2N journal entries per bulk of N), so there is a per-leg gap\nbetween a leg's cancel committing and its create landing. Real-world MMs\nre-quote every cycle, so a missed create is recovered on the next tick.\nThe `PUT /order` single-replace endpoint is unchanged.", "operationId": "bulk_replace_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkReplaceOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Bulk replace results (per-leg, in input order)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BulkReplaceOrderResponse" } } } }, "400": { "description": "Invalid request (e.g., too many replacements)" }, "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": [] } ] } }, "/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": { "type": "string", "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": { "type": "string", "nullable": true } }, { "name": "sort_order", "in": "query", "required": false, "schema": { "type": "string", "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": { "type": "string", "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.", "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", "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" } } } }, "503": { "description": "Service is shutting down", "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 }, { "name": "include_attribution", "in": "query", "description": "Return per-symbol attribution blobs on each point. Defaults to `false` because the blob is a few KB per row and sits in TOAST, opt in only when the caller actually renders the breakdown view.", "required": false, "schema": { "type": "boolean", "nullable": true }, "example": false } ], "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" } } } }, "/historical-theos/batch": { "get": { "tags": [ "Markets" ], "summary": "Get historical theoretical-price snapshots for multiple instruments in one request.", "operationId": "get_historical_theos_batch", "parameters": [ { "name": "instrument_names", "in": "query", "description": "Comma-separated list of instrument names", "required": true, "schema": { "type": "string" }, "example": "ETH-20260413-2000-C,ETH-20260413-2150-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 per instrument (default: 100, max: 100)", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 0 }, "example": 100 } ], "responses": { "200": { "description": "Batch historical theoretical-price snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchHistoricalTheoApiResponse" } } } }, "400": { "description": "Bad Request" }, "500": { "description": "Internal server error" } } } }, "/instrument-specs": { "get": { "tags": [ "Markets" ], "summary": "Get canonical instrument specifications for downstream services.", "operationId": "get_instrument_specs", "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 canonical instrument specifications", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentSpecResponse" } } } } }, "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" } } } }, "/liquidation/standard-margin": { "post": { "tags": [ "liquidation" ], "summary": "Submit a standard margin liquidation order.", "operationId": "submit_standard_margin_liquidation_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/StandardMarginLiquidationOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Standard margin liquidation order accepted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "400": { "description": "Invalid or stale liquidation order" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/liquidations": { "get": { "tags": [ "liquidation" ], "summary": "GET /liquidations - Get global public liquidation history", "operationId": "get_public_liquidations", "parameters": [ { "name": "cursor", "in": "query", "description": "Opaque cursor returned by the previous page.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "eyJ0aW1lc3RhbXAiOjE3MDAwMDAwMDAwMDAsImlkIjoxMjN9" }, { "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": "wallet", "in": "query", "description": "Wallet address to filter by.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "0x1234567890123456789012345678901234567890" }, { "name": "status", "in": "query", "description": "New liquidation state/status to filter by. Accepts `healthy`, `pre_liquidation`, `in_liquidation`, or `liquidated`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "pre_liquidation" }, { "name": "state", "in": "query", "description": "Alias for `status`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "pre_liquidation" }, { "name": "margin_mode", "in": "query", "description": "Margin mode to filter by: `standard` or `portfolio`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "standard" }, { "name": "liquidation_mode", "in": "query", "description": "Liquidation mode to filter by: `partial` or `full`.", "required": false, "schema": { "type": "string", "nullable": true }, "example": "partial" } ], "responses": { "200": { "description": "Global liquidation history retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PublicLiquidationsResponse" } } } }, "400": { "description": "Invalid cursor or page size" }, "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" }, "503": { "description": "Margin mode service unavailable" } }, "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 } }, { "name": "include_rfq_provider_quotes", "in": "query", "description": "Include raw per-provider RFQ indicative quotes in each option summary.", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "rfq_provider_quotes", "in": "query", "description": "Backward-compatible short alias for include_rfq_provider_quotes.", "required": false, "schema": { "type": "boolean", "nullable": true } }, { "name": "rfq_provider_quotes_limit", "in": "query", "description": "Optional cap for per-provider RFQ indicative quotes per instrument.", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "provider_quotes_limit", "in": "query", "description": "Backward-compatible short alias for rfq_provider_quotes_limit.", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Short GET param alias for rfq_provider_quotes_limit.", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 } } ], "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": [] } ] }, "put": { "tags": [ "Trading" ], "summary": "Atomically cancel an existing order and place a new one.", "description": "The old order is canceled first. If the cancel fails (order not found,\nalready filled), the new order is NOT placed and the endpoint returns\nan error. If the cancel succeeds, the new order is placed in the same\nengine tick with no gap.", "operationId": "replace_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReplaceOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Replace result (new order status)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderUpdateMessage" } } } }, "400": { "description": "Invalid request" }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] }, "delete": { "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": [] } ] } }, "/order_cloid": { "delete": { "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": [] } ] } }, "/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/image": { "post": { "tags": [ "Portfolio" ], "summary": "Set the authenticated wallet's profile image.", "operationId": "set_profile_image", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileImageRequest" } } }, "required": true }, "responses": { "200": { "description": "Profile image set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetProfileImageResponse" } } } }, "400": { "description": "Validation error" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/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 } }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProfileTradesResponse" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/push/preferences": { "post": { "tags": [ "Push Notifications" ], "summary": "Update notification preferences for an existing push subscription.", "operationId": "push_preferences", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPreferencesRequest" } } }, "required": true }, "responses": { "200": { "description": "Preferences updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushPreferencesResponse" } } } }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/push/subscribe": { "post": { "tags": [ "Push Notifications" ], "summary": "Register a Web Push subscription for the authenticated wallet.", "operationId": "push_subscribe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscribeRequest" } } }, "required": true }, "responses": { "200": { "description": "Subscription registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushSubscribeResponse" } } } }, "400": { "description": "Invalid request" }, "500": { "description": "Internal server error" } }, "security": [ { "eip712_signature": [] } ] } }, "/push/unsubscribe": { "post": { "tags": [ "Push Notifications" ], "summary": "Remove a Web Push subscription for the authenticated wallet.", "operationId": "push_unsubscribe", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushUnsubscribeRequest" } } }, "required": true }, "responses": { "200": { "description": "Subscription removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PushUnsubscribeResponse" } } } }, "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": { "delete": { "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" } } } }, "/risk/limits": { "get": { "tags": [ "Risk" ], "summary": "Get current public Standard Margin risk limits.", "description": "Returns whether Standard Margin option shorts are enabled, the platform cap\nwhen enabled, aggregate non-whitelisted short notional usage, and optional\nwallet-specific usage.", "operationId": "get_risk_limits", "parameters": [ { "name": "wallet", "in": "query", "description": "Optional wallet address to include wallet-specific Standard short usage.", "required": false, "schema": { "allOf": [ { "$ref": "#/components/schemas/WalletAddress" } ], "nullable": true }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "Current Standard Margin risk limits", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } }, "503": { "description": "Risk limits temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiResponse" } } } } } } }, "/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 } }, { "name": "account", "in": "query", "description": "Filter by wallet address, matching maker or taker.", "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": { "ApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "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" } } }, "BatchHistoricalTheoApiResponse": { "type": "object", "required": [ "success", "data" ], "properties": { "data": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/HistoricalTheoResponse" } }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "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" } } }, "BulkReplaceOrderRequest": { "type": "object", "required": [ "replacements" ], "properties": { "replacements": { "type": "array", "items": { "$ref": "#/components/schemas/ReplaceOrderRequest" }, "description": "Array of replace requests (max 50)" } } }, "BulkReplaceOrderResponse": { "type": "object", "required": [ "results" ], "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/BulkOrderResult" }, "description": "Results for each replace in the request" } } }, "CancelOrderByCloidRequest": { "type": "object", "description": "Request to cancel an order by client ID through the public cloid endpoint.", "required": [ "wallet", "client_id", "nonce", "signature" ], "properties": { "client_id": { "type": "string" }, "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "signature": { "type": "string" }, "wallet": { "type": "string" } } }, "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", "description": "Full metadata for a trading competition.", "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": "When this competition was created (ISO 8601)." }, "description": { "type": "string", "description": "Optional short description.", "nullable": true }, "end_ts_ms": { "type": "integer", "format": "int64", "description": "Competition end time in milliseconds since epoch." }, "id": { "type": "integer", "format": "int64", "description": "Unique competition identifier." }, "name": { "type": "string", "description": "Display name of the competition." }, "primary_win_condition": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "rules_content": { "type": "string", "description": "Optional inline rules content (Markdown).", "nullable": true }, "rules_url": { "type": "string", "description": "Optional URL to external rules page.", "nullable": true }, "start_ts_ms": { "type": "integer", "format": "int64", "description": "Competition start time in milliseconds since epoch." }, "state": { "$ref": "#/components/schemas/CompetitionStateValue" }, "updated_at": { "type": "string", "description": "When this competition was last updated (ISO 8601)." }, "win_conditions": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionWinConditionValue" }, "description": "Metrics tracked for ranking (e.g. `[\"pnl\", \"volume\"]`)." } } }, "CompetitionLeaderboardResponse": { "type": "object", "description": "Paginated competition leaderboard with optional connected-user context.", "required": [ "success", "competition_id", "sort_by", "sort_order", "data", "pagination" ], "properties": { "competition_id": { "type": "integer", "format": "int64", "description": "Competition this leaderboard belongs to." }, "connected_user": { "allOf": [ { "$ref": "#/components/schemas/ConnectedUserRank" } ], "nullable": true }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardRow" }, "description": "Leaderboard rows for the current page." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "sort_by": { "$ref": "#/components/schemas/CompetitionSortByValue" }, "sort_order": { "$ref": "#/components/schemas/CompetitionSortOrderValue" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "CompetitionResponse": { "type": "object", "description": "Response containing a single competition.", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/CompetitionData" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "CompetitionSortByValue": { "type": "string", "description": "Field to sort the leaderboard by. Serialized as lowercase.", "enum": [ "pnl", "volume", "efficiency" ] }, "CompetitionSortOrderValue": { "type": "string", "description": "Sort direction for leaderboard queries. Serialized as lowercase.", "enum": [ "asc", "desc" ] }, "CompetitionStateValue": { "type": "string", "description": "Lifecycle state of a trading competition. Serialized as lowercase.", "enum": [ "pre", "active", "post" ] }, "CompetitionWinConditionValue": { "type": "string", "description": "Metric used to determine competition winners. Serialized as lowercase.", "enum": [ "pnl", "volume", "efficiency" ] }, "CompetitionsResponse": { "type": "object", "description": "Paginated list of competitions.", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionData" }, "description": "Competition records for the current page." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "ConnectedUserRank": { "type": "object", "description": "The requesting (connected) user's own rank on the leaderboard.", "required": [ "wallet", "username" ], "properties": { "efficiency": { "type": "string", "description": "Capital efficiency. Serialized as a string.", "nullable": true }, "medal": { "type": "integer", "format": "int32", "description": "Medal tier, if awarded.", "nullable": true, "minimum": 0 }, "pnl": { "type": "string", "description": "Realized PnL in USD. Serialized as a string.", "nullable": true }, "rank": { "type": "integer", "description": "Current rank, if the user is on the leaderboard.", "nullable": true, "minimum": 0 }, "username": { "type": "string", "description": "Display username." }, "volume": { "type": "string", "description": "Traded volume in USD. Serialized as a string.", "nullable": true }, "wallet": { "type": "string", "description": "Connected user's wallet address (checksummed Ethereum address)." } } }, "CursorPage": { "type": "object", "description": "Cursor metadata for public liquidation history.", "required": [ "limit", "has_more" ], "properties": { "has_more": { "type": "boolean", "description": "Whether another page is available." }, "limit": { "type": "integer", "description": "Page size used by the request.", "minimum": 0 }, "next_cursor": { "type": "string", "description": "Opaque cursor for the next page, or null when no further page is known.", "nullable": true } } }, "DeleteMmpConfigRequest": { "type": "object", "description": "Signed request to delete an MMP configuration.", "required": [ "wallet", "currency", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Underlying currency to delete MMP config for." }, "nonce": { "type": "integer", "format": "int64", "description": "Monotonically increasing nonce for replay protection.", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature authorizing this request." }, "wallet": { "type": "string", "description": "Market maker wallet address (checksummed Ethereum address)." } } }, "DeleteUsernameResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "FillApiResponse": { "type": "object", "description": "A single fill (one side of a trade) for a specific wallet.", "required": [ "fill_id", "trade_id", "wallet_address", "symbol", "price", "size", "fee", "side", "is_taker", "timestamp", "created_at" ], "properties": { "builder_code_address": { "type": "string", "description": "Builder/referral code wallet, if a builder code was used (checksummed Ethereum address).", "nullable": true }, "builder_code_fee": { "type": "string", "description": "Fee rebate to the builder code wallet in USD. Serialized as a string.", "nullable": true }, "created_at": { "type": "string", "description": "When the fill was persisted (ISO 8601)." }, "explorer_url": { "type": "string", "description": "Link to the on-chain transaction, if settled.", "nullable": true }, "fee": { "type": "string", "description": "Fee charged for this fill in USD. Serialized as a string." }, "fill_id": { "type": "integer", "format": "int64", "description": "Unique fill identifier." }, "is_taker": { "type": "boolean", "description": "Whether this fill was on the taker side." }, "price": { "type": "string", "description": "Execution price in USD. Serialized as a string." }, "realized_pnl": { "type": "string", "description": "Realized PnL from this fill in USD, if a position was reduced. Serialized as a string.", "nullable": true }, "side": { "$ref": "#/components/schemas/Side" }, "size": { "type": "string", "description": "Fill size in contracts. Serialized as a string." }, "symbol": { "type": "string", "description": "Instrument symbol that was filled." }, "timestamp": { "type": "integer", "format": "int64", "description": "Fill timestamp in milliseconds since epoch." }, "trade_id": { "type": "integer", "format": "int64", "description": "Parent trade identifier that produced this fill." }, "wallet_address": { "type": "string", "description": "Wallet that received this fill (checksummed Ethereum address)." } } }, "FillsResponse": { "type": "object", "description": "Paginated list of fills.", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FillApiResponse" }, "description": "Fill records for the current page." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "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": "Simple health-check response from `GET /health`.", "required": [ "status" ], "properties": { "status": { "type": "string", "description": "Health status string (e.g. `\"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": { "attribution": { "type": "object", "description": "Per-symbol PnL attribution. Keys are symbol names, values are [position, entry_price, realized, unrealized, total].", "additionalProperties": { "type": "array", "items": { "type": "number", "format": "double" } }, "nullable": true }, "equity": { "type": "string", "description": "Total account equity at the bucket timestamp." }, "net_deposits": { "type": "string", "description": "Cumulative net deposits (deposits minus withdraws) as of this bucket's\ntimestamp. The frontend uses this as the P&L baseline so multi-deposit\nwallets stay correctly anchored historically; the delta between\nconsecutive points also surfaces deposit/withdraw events for annotation.", "nullable": true }, "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", "description": "Server-canonical representation of a tradable option instrument.", "required": [ "id", "underlying", "strike", "expiry", "option_type", "volume_24h", "open_interest" ], "properties": { "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp in seconds since epoch.", "minimum": 0 }, "id": { "type": "string", "description": "Human-readable instrument symbol (e.g. `\"BTC-20260101-100000-C\"`)." }, "instrument_id": { "type": "integer", "format": "int32", "description": "Internal numeric instrument identifier." }, "mark_iv": { "type": "string", "description": "Mark implied volatility as a decimal (e.g. `0.70` = 70%). Serialized as a string.", "nullable": true }, "open_interest": { "type": "string", "description": "Total open interest in contracts. Serialized as a string." }, "option_token_address": { "type": "string", "description": "On-chain option token contract address, if deployed (checksummed Ethereum address).", "nullable": true }, "option_type": { "type": "string", "description": "Option type: `\"call\"` or `\"put\"`." }, "status": { "$ref": "#/components/schemas/InstrumentStatus" }, "strike": { "type": "string", "description": "Strike price in USD. Serialized as a string." }, "trading_mode": { "type": "string", "description": "Trading mode flags for this instrument." }, "underlying": { "type": "string", "description": "Underlying asset (e.g. `\"BTC\"`, `\"ETH\"`)." }, "updated_at": { "type": "string", "description": "Last time this instrument's data was refreshed (ISO 8601)." }, "volume_24h": { "type": "string", "description": "Rolling 24-hour traded volume in contracts. Serialized as a string." } } }, "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)" }, "orderbook": { "type": "boolean", "description": "Orderbook enabled" }, "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" } } }, "InstrumentSpecResponse": { "type": "object", "description": "Canonical instrument specification for discovery, quoting, and lifecycle\nconsumers.", "required": [ "instrument_id", "instrument_numeric_id", "exchange_symbol", "sym", "exchange", "instrument_kind", "base_asset", "quote_asset", "strike", "expiry_ns", "contract_size", "min_trade_size", "tick_size", "min_price_increment_bands", "state", "is_tradable" ], "properties": { "base_asset": { "type": "string", "description": "Base asset for cross-venue mapping." }, "condition_id": { "type": "string", "description": "External condition identifier, if modeled.", "nullable": true }, "contract_size": { "type": "number", "format": "double", "description": "Contract size used for Greeks and notional scaling." }, "delivery": { "type": "string", "description": "Delivery mode, e.g. `\"CASH\"` or `\"PHYSICAL\"`.", "nullable": true }, "event_ts_ns": { "type": "integer", "format": "int64", "description": "Timestamp for this spec version in nanoseconds. Currently always\nnull: no persisted spec-change timestamp exists yet, and cache\nrebuild times would read as false spec changes.", "nullable": true }, "exchange": { "type": "string", "description": "Venue identifier, e.g. `\"HYPERCALL\"`." }, "exchange_symbol": { "type": "string", "description": "Native venue symbol used in REST and WebSocket calls." }, "expiry_ns": { "type": "integer", "format": "int64", "description": "Expiry timestamp in nanoseconds since epoch." }, "initial_margin_fraction": { "type": "number", "format": "double", "description": "Initial margin fraction, if configured per instrument.", "nullable": true }, "instrument_id": { "type": "string", "description": "Canonical string identifier used by downstream systems." }, "instrument_kind": { "type": "string", "description": "Instrument class: `\"OPTION\"`, `\"PERP\"`, `\"SPOT\"`, or `\"FUTURE\"`." }, "instrument_numeric_id": { "type": "integer", "format": "int32", "description": "Database numeric identifier for legacy joins." }, "is_tradable": { "type": "boolean", "description": "Whether the instrument can currently accept new trading activity." }, "listed_time_ns": { "type": "integer", "format": "int64", "description": "First-listed time in nanoseconds, if known.", "nullable": true }, "maintenance_margin_fraction": { "type": "number", "format": "double", "description": "Maintenance margin fraction, if configured per instrument.", "nullable": true }, "maker_fee_bps": { "type": "number", "format": "double", "description": "Maker fee in basis points, if configured per instrument.", "nullable": true }, "min_price_increment_bands": { "type": "array", "items": { "$ref": "#/components/schemas/TickSizeStep" }, "description": "Stepped tick rules, when any." }, "min_trade_size": { "type": "number", "format": "double", "description": "Minimum trade size." }, "option_kind": { "type": "string", "description": "Option side, `\"C\"` or `\"P\"` when this is an option.", "nullable": true }, "option_token_address": { "type": "string", "description": "Hypercall option token contract address, if deployed.", "nullable": true }, "position_limit": { "type": "number", "format": "double", "description": "Per-instrument position limit, if configured.", "nullable": true }, "price_decimals": { "type": "integer", "format": "int32", "description": "Decimal precision for wire price quantities.", "nullable": true, "minimum": 0 }, "quote_asset": { "type": "string", "description": "Quote asset for cross-venue mapping." }, "settle_asset": { "type": "string", "description": "Settlement asset for margin and PnL accounting.", "nullable": true }, "settlement_hour_utc": { "type": "integer", "format": "int32", "description": "UTC hour of day at which this instrument expires and settles.", "nullable": true, "minimum": 0 }, "settlement_oracle": { "type": "string", "description": "Settlement oracle identifier, if modeled.", "nullable": true }, "settlement_time_utc": { "type": "string", "description": "UTC time of day (\"HH:MM\") at which this instrument expires and\nsettles. Authoritative alongside expiry_ns; per-underlying policy.", "nullable": true }, "size_decimals": { "type": "integer", "format": "int32", "description": "Decimal precision for wire size quantities.", "nullable": true, "minimum": 0 }, "state": { "type": "string", "description": "Lifecycle state: `\"OPEN\"`, `\"SETTLEMENT\"`, or `\"DELIVERED\"`." }, "strike": { "type": "string", "description": "Strike price for derivatives. Serialized as a string." }, "sym": { "type": "string", "description": "Trading pair for grouping, e.g. `\"BTC-USD\"`." }, "taker_fee_bps": { "type": "number", "format": "double", "description": "Taker fee in basis points, if configured per instrument.", "nullable": true }, "tick_size": { "type": "number", "format": "double", "description": "Base tick size for price rounding." }, "underlying_resolution_source": { "type": "string", "description": "Source used to resolve the underlying at settlement, if modeled.", "nullable": true } } }, "InstrumentStatus": { "type": "string", "description": "Lifecycle state of a tradable instrument.\n\nSerializes as `SCREAMING_SNAKE_CASE` (e.g. `\"EXPIRED_PENDING_PRICE\"`).", "enum": [ "ACTIVE", "EXPIRED_PENDING_PRICE", "SETTLED" ] }, "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" } } }, "LeaderboardRow": { "type": "object", "description": "A single row on the competition leaderboard.", "required": [ "rank", "wallet", "username", "pnl", "volume", "efficiency" ], "properties": { "efficiency": { "type": "string", "description": "Capital efficiency (PnL / margin used). Serialized as a string." }, "medal": { "type": "integer", "format": "int32", "description": "Medal tier (1 = gold, 2 = silver, 3 = bronze), if awarded.", "nullable": true, "minimum": 0 }, "pnl": { "type": "string", "description": "Realized PnL during the competition in USD. Serialized as a string." }, "rank": { "type": "integer", "description": "1-based rank on the leaderboard.", "minimum": 0 }, "username": { "type": "string", "description": "Display username." }, "volume": { "type": "string", "description": "Total traded volume during the competition in USD. Serialized as a string." }, "wallet": { "type": "string", "description": "Participant wallet address (checksummed Ethereum address)." } } }, "LiquidationHistoryEntry": { "type": "object", "description": "Liquidation history transition entry.", "required": [ "id", "wallet", "previous_state", "new_state", "equity", "mm_required", "maintenance_margin", "shortfall", "details", "timestamp" ], "properties": { "auction_id": { "type": "string", "description": "Auction ID, if applicable.", "nullable": true }, "bonus": { "type": "string", "description": "Bonus credited on resolution, if any.", "nullable": true }, "details": { "type": "object", "description": "Serialized status snapshot for restart-safe debugging." }, "equity": { "type": "string", "description": "Equity at time of transition." }, "id": { "type": "integer", "format": "int64", "description": "History entry ID." }, "liquidation_mode": { "type": "string", "description": "Liquidation mode (`partial` or `full`) if applicable.", "nullable": true }, "maintenance_margin": { "type": "string", "description": "Maintenance margin at time of transition." }, "margin_needed": { "type": "string", "description": "Margin needed for full liquidation, when applicable.", "nullable": true }, "mm_required": { "type": "string", "description": "MM required at time of transition." }, "new_state": { "type": "string", "description": "New liquidation state." }, "previous_state": { "type": "string", "description": "Previous liquidation state." }, "request_id": { "type": "string", "description": "Request ID associated with the transition.", "nullable": true }, "shortfall": { "type": "string", "description": "Shortfall at time of transition." }, "timestamp": { "type": "integer", "format": "int64", "description": "Timestamp of transition." }, "tx_hash": { "type": "string", "description": "Transaction hash associated with the transition.", "nullable": true }, "wallet": { "type": "string", "description": "Wallet address." }, "winner_address": { "type": "string", "description": "Winning liquidator/manager, if resolved.", "nullable": true } } }, "MarginModeApiResponse": { "type": "object", "description": "API envelope for margin mode operations.", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/MarginModeResponse" } ], "nullable": true }, "error": { "type": "string", "description": "Error message, present on failure.", "nullable": true }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "MarginModeResponse": { "type": "object", "description": "Result of a margin mode switch.", "required": [ "wallet", "margin_mode", "previous_mode" ], "properties": { "margin_mode": { "type": "string", "description": "New margin mode after the switch." }, "previous_mode": { "type": "string", "description": "Margin mode before the switch." }, "wallet": { "type": "string", "description": "Wallet address that was updated." } } }, "MarginSummary": { "type": "object", "description": "Unified margin summary that works for both Standard and Portfolio modes.", "required": [ "mode", "equity", "position_im", "open_orders_im", "initial_margin", "maintenance_margin" ], "properties": { "equity": { "type": "string", "description": "Total account equity (balance + unrealized PnL)" }, "initial_margin": { "type": "string", "description": "Excess Initial Margin (equity - position_im - open_orders_im)" }, "maintenance_margin": { "type": "string", "description": "Excess Maintenance Margin (equity - position_mm)" }, "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", "nullable": true }, "position_im": { "type": "string", "description": "Initial Margin required from positions" } } }, "MarketInfo": { "type": "object", "description": "Summary of a single expiry's market data for one underlying.", "required": [ "underlying", "expiry", "instruments", "total_volume_24h", "total_open_interest" ], "properties": { "atm_vol": { "type": "string", "description": "At-the-money implied volatility as a decimal, if available. Serialized as a string.", "nullable": true }, "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp in seconds since epoch.", "minimum": 0 }, "index_price": { "type": "string", "description": "Current spot/index price of the underlying in USD. Serialized as a string.\nDefaults to zero if missing or null." }, "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/Instrument" }, "description": "All instruments listed under this underlying/expiry pair." }, "prev_day_price": { "type": "string", "description": "Previous day's closing index price in USD, if available. Serialized as a string.", "nullable": true }, "total_open_interest": { "type": "string", "description": "Aggregate open interest across all instruments in contracts. Serialized as a string." }, "total_volume_24h": { "type": "string", "description": "Aggregate 24-hour traded volume across all instruments in contracts. Serialized as a string." }, "underlying": { "type": "string", "description": "Underlying asset (e.g. `\"BTC\"`)." } } }, "MarketsResponse": { "type": "object", "description": "Response containing all available markets.", "required": [ "success", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MarketInfo" }, "description": "List of markets grouped by underlying and expiry." }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "MmpConfigData": { "type": "object", "description": "Market Maker Protection (MMP) configuration for a wallet and currency.", "required": [ "wallet_address", "currency", "interval_ms", "frozen_time_ms", "enabled" ], "properties": { "currency": { "type": "string", "description": "Underlying currency this config applies to (e.g. `\"BTC\"`)." }, "delta_limit": { "type": "string", "description": "Maximum net delta filled within the interval. Serialized as a string.", "nullable": true }, "enabled": { "type": "boolean", "description": "Whether MMP is currently active for this wallet/currency pair." }, "frozen_time_ms": { "type": "integer", "format": "int64", "description": "Duration in milliseconds to freeze quoting after a trigger." }, "interval_ms": { "type": "integer", "format": "int64", "description": "Rolling window length in milliseconds for fill monitoring." }, "qty_limit": { "type": "string", "description": "Maximum filled quantity in contracts within the interval. Serialized as a string.", "nullable": true }, "vega_limit": { "type": "string", "description": "Maximum net vega filled within the interval. Serialized as a string.", "nullable": true }, "wallet_address": { "type": "string", "description": "Market maker wallet address (checksummed Ethereum address)." } } }, "MmpConfigResponse": { "type": "object", "description": "Response listing MMP configurations for a wallet.", "required": [ "success", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/MmpConfigData" }, "description": "MMP configurations, one per currency." }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "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" }, "best_ask_size": { "type": "number", "format": "double", "description": "Best ask size on the orderbook, in human-readable contracts.", "nullable": true }, "best_bid_size": { "type": "number", "format": "double", "description": "Best bid size on the orderbook, in human-readable contracts.", "nullable": true }, "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 }, "indicative_ask_price": { "type": "number", "format": "double", "description": "Best indicative RFQ ask price from quote providers.", "nullable": true }, "indicative_ask_size": { "type": "number", "format": "double", "description": "Best indicative RFQ ask size, in human-readable contracts.", "nullable": true }, "indicative_bid_price": { "type": "number", "format": "double", "description": "Best indicative RFQ bid price from quote providers.", "nullable": true }, "indicative_bid_size": { "type": "number", "format": "double", "description": "Best indicative RFQ bid size, in human-readable contracts.", "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" }, "rfq_provider_quotes": { "type": "array", "items": { "$ref": "#/components/schemas/RfqProviderIndicativeQuote" }, "description": "Raw per-provider RFQ indicative quotes. Only included when requested.", "nullable": true }, "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" } } }, "OptionsChainGreeksAbs": { "type": "object", "description": "Absolute (per-contract) option Greeks.", "required": [ "delta", "gamma", "theta", "vega" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Delta: rate of change of option price with respect to underlying price." }, "gamma": { "type": "number", "format": "double", "description": "Gamma: rate of change of delta with respect to underlying price." }, "theta": { "type": "number", "format": "double", "description": "Theta: time decay per day." }, "vega": { "type": "number", "format": "double", "description": "Vega: sensitivity to 1-point change in implied volatility." } } }, "OptionsChainGreeksCash": { "type": "object", "description": "Cash-denominated option Greeks (dollar impact per unit move).", "required": [ "delta_1pct_usd", "gamma_1pct_usd", "theta_1d_usd", "vega_1vol_usd" ], "properties": { "delta_1pct_usd": { "type": "number", "format": "double", "description": "Dollar PnL for a 1% move in the underlying." }, "gamma_1pct_usd": { "type": "number", "format": "double", "description": "Dollar gamma impact for a 1% move in the underlying." }, "theta_1d_usd": { "type": "number", "format": "double", "description": "Dollar theta decay over one day." }, "vega_1vol_usd": { "type": "number", "format": "double", "description": "Dollar vega for a 1-vol-point move." } } }, "OptionsChainLeg": { "type": "object", "description": "A single call or put leg in the options chain, including top-of-book quotes and Greeks.", "required": [ "symbol" ], "properties": { "ask_iv": { "type": "number", "format": "double", "description": "Implied volatility at the best ask.", "nullable": true }, "ask_price_usd": { "type": "number", "format": "double", "description": "Best ask price in USD.", "nullable": true }, "ask_size_contracts": { "type": "number", "format": "double", "description": "Size at the best ask in contracts.", "nullable": true }, "ask_size_usd_notional": { "type": "number", "format": "double", "description": "Notional value of the best ask in USD.", "nullable": true }, "bid_iv": { "type": "number", "format": "double", "description": "Implied volatility at the best bid.", "nullable": true }, "bid_price_usd": { "type": "number", "format": "double", "description": "Best bid price in USD.", "nullable": true }, "bid_size_contracts": { "type": "number", "format": "double", "description": "Size at the best bid in contracts.", "nullable": true }, "bid_size_usd_notional": { "type": "number", "format": "double", "description": "Notional value of the best bid in USD.", "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", "description": "On-chain option token address, if deployed (checksummed Ethereum address).", "nullable": true }, "symbol": { "type": "string", "description": "Instrument symbol (e.g. `\"BTC-20260101-100000-C\"`)." } } }, "OptionsChainSnapshotResponse": { "type": "object", "description": "Full options chain snapshot for one underlying and expiry.", "required": [ "currency", "expiry", "rows" ], "properties": { "currency": { "type": "string", "description": "Underlying currency (e.g. `\"BTC\"`)." }, "expiry": { "type": "integer", "format": "int64", "description": "Expiry timestamp in seconds since epoch.", "minimum": 0 }, "rows": { "type": "array", "items": { "$ref": "#/components/schemas/OptionsChainStrikeRow" }, "description": "Strike rows ordered by strike price." } } }, "OptionsChainStrikeRow": { "type": "object", "description": "A single strike row in the options chain, pairing call and put legs.", "required": [ "strike" ], "properties": { "call": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainLeg" } ], "nullable": true }, "put": { "allOf": [ { "$ref": "#/components/schemas/OptionsChainLeg" } ], "nullable": true }, "strike": { "type": "number", "format": "double", "description": "Strike price in USD." } } }, "Order": { "type": "object", "description": "A resting or historical order on the matching engine.", "required": [ "order_id", "wallet_address", "symbol", "side", "price", "size", "tif", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64", "description": "Order creation timestamp in milliseconds since epoch." }, "filled_size": { "type": "string", "description": "Cumulative filled size in contracts. Serialized as a string.", "nullable": true }, "mmp_enabled": { "type": "boolean", "description": "Whether Market Maker Protection is enabled for this order." }, "order_id": { "type": "integer", "format": "int64", "description": "Unique order identifier assigned by the engine." }, "price": { "type": "string", "description": "Limit price in USD. Serialized as a string." }, "side": { "type": "string", "description": "Order side (`\"buy\"` or `\"sell\"`)." }, "size": { "type": "string", "description": "Order size in contracts. Serialized as a string." }, "status": { "type": "string", "description": "Current order status (e.g. `\"open\"`, `\"filled\"`, `\"cancelled\"`).", "nullable": true }, "symbol": { "type": "string", "description": "Instrument symbol the order is placed on." }, "tif": { "type": "string", "description": "Time-in-force policy (e.g. `\"GTC\"`, `\"IOC\"`, `\"FOK\"`)." }, "updated_at": { "type": "string", "description": "Timestamp of the last status change (ISO 8601).", "nullable": true }, "wallet_address": { "type": "string", "description": "Owner wallet address (checksummed Ethereum address)." } } }, "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 } } }, "OrderRoute": { "type": "string", "description": "Order routing preference for public order submission.", "enum": [ "best_execution", "book_only", "rfq_only" ] }, "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" ] }, "OrdersResponse": { "type": "object", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean" } } }, "Pagination": { "type": "object", "description": "Pagination info for list responses.", "required": [ "limit", "offset", "count" ], "properties": { "count": { "type": "integer", "minimum": 0 }, "limit": { "type": "integer", "minimum": 0 }, "offset": { "type": "integer", "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)" }, "route": { "allOf": [ { "$ref": "#/components/schemas/OrderRoute" } ], "nullable": true }, "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", "description": "Full portfolio snapshot for a single account.", "required": [ "wallet_address", "positions", "total_margin_used", "available_balance" ], "properties": { "available_balance": { "type": "string", "description": "Free collateral available for new trades in USD. Serialized as a string." }, "margin_mode": { "type": "string", "description": "Margin mode for this account (`\"standard\"` or `\"portfolio\"`). Defaults to `\"standard\"`." }, "margin_summary": { "allOf": [ { "$ref": "#/components/schemas/MarginSummary" } ], "nullable": true }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/PositionWithMetrics" }, "description": "All open positions with enriched risk metrics." }, "span_margin": { "allOf": [ { "$ref": "#/components/schemas/SpanMarginSummary" } ], "nullable": true }, "total_margin_used": { "type": "string", "description": "Total margin currently in use across all positions in USD. Serialized as a string." }, "wallet_address": { "type": "string", "description": "Account wallet address (checksummed Ethereum address)." } } }, "PortfolioGreeksAggregate": { "type": "object", "description": "Aggregate Greeks across all positions in a portfolio.", "required": [ "delta", "gamma", "theta", "vega" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Net portfolio delta." }, "gamma": { "type": "number", "format": "double", "description": "Net portfolio gamma." }, "iv": { "type": "number", "format": "double", "description": "Weighted-average implied volatility, if computable.", "nullable": true }, "theta": { "type": "number", "format": "double", "description": "Net portfolio theta (daily)." }, "vega": { "type": "number", "format": "double", "description": "Net portfolio 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": "Full portfolio Greeks breakdown: per-leg detail and aggregate totals.", "required": [ "wallet_address" ], "properties": { "aggregate": { "allOf": [ { "$ref": "#/components/schemas/PortfolioGreeksAggregate" } ], "nullable": true }, "per_leg": { "type": "array", "items": { "$ref": "#/components/schemas/PositionGreeksLeg" }, "description": "Greeks for each individual position leg." }, "wallet_address": { "type": "string", "description": "Account wallet address (checksummed Ethereum address)." } } }, "Position": { "type": "object", "description": "A single open position for one instrument.", "required": [ "wallet_address", "symbol", "amount", "entry_price", "margin_posted", "realized_pnl", "unrealized_pnl", "updated_at" ], "properties": { "amount": { "type": "string", "description": "Position size in contracts (positive = long, negative = short). Serialized as a string." }, "entry_price": { "type": "string", "description": "Volume-weighted average entry price in USD. Serialized as a string." }, "margin_posted": { "type": "string", "description": "Margin currently locked against this position in USD. Serialized as a string." }, "realized_pnl": { "type": "string", "description": "Cumulative realized PnL in USD. Serialized as a string." }, "symbol": { "type": "string", "description": "Instrument symbol (e.g. `\"BTC-20260101-100000-C\"`)." }, "unrealized_pnl": { "type": "string", "description": "Mark-to-market unrealized PnL in USD. Serialized as a string." }, "updated_at": { "type": "string", "description": "Timestamp of the last position update (ISO 8601)." }, "wallet_address": { "type": "string", "description": "Account wallet address (checksummed Ethereum address)." } } }, "PositionGreeksLeg": { "type": "object", "description": "Greeks for a single position leg in a portfolio.", "required": [ "symbol", "quantity", "delta", "gamma", "theta", "vega", "iv" ], "properties": { "delta": { "type": "number", "format": "double", "description": "Delta of this leg." }, "gamma": { "type": "number", "format": "double", "description": "Gamma of this leg." }, "iv": { "type": "number", "format": "double", "description": "Implied volatility used for this leg's Greeks." }, "quantity": { "type": "string", "description": "Position size in contracts (positive = long, negative = short). Serialized as a string." }, "symbol": { "type": "string", "description": "Instrument symbol." }, "theta": { "type": "number", "format": "double", "description": "Theta (daily time decay) of this leg." }, "vega": { "type": "number", "format": "double", "description": "Vega of this leg." } } }, "PositionWithMetrics": { "allOf": [ { "$ref": "#/components/schemas/Position" }, { "type": "object", "required": [ "notional_value", "maintenance_margin", "liquidation_price", "margin_ratio" ], "properties": { "liquidation_price": { "type": "string", "description": "Estimated liquidation price in USD. Serialized as a string." }, "maintenance_margin": { "type": "string", "description": "Maintenance margin requirement in USD. Serialized as a string." }, "margin_ratio": { "type": "string", "description": "Margin utilization ratio (margin_used / equity). Serialized as a string." }, "notional_value": { "type": "string", "description": "Dollar notional value of the position. Serialized as a string." } } } ], "description": "Position enriched with derived risk metrics. Flattened in JSON (no nested `position` key)." }, "ProfileCompetitionRankSummary": { "type": "object", "description": "Summary of a user's rank in a specific competition, shown on their profile.", "required": [ "competition_id", "competition_name", "competition_state", "rank", "pnl", "volume", "efficiency" ], "properties": { "competition_id": { "type": "integer", "format": "int64", "description": "Competition identifier." }, "competition_name": { "type": "string", "description": "Competition display name." }, "competition_state": { "$ref": "#/components/schemas/CompetitionStateValue" }, "efficiency": { "type": "string", "description": "User's capital efficiency in this competition. Serialized as a string." }, "medal": { "type": "integer", "format": "int32", "description": "Medal tier, if awarded.", "nullable": true, "minimum": 0 }, "pnl": { "type": "string", "description": "User's realized PnL in this competition in USD. Serialized as a string." }, "rank": { "type": "integer", "description": "User's rank in this competition.", "minimum": 0 }, "volume": { "type": "string", "description": "User's traded volume in this competition in USD. Serialized as a string." } } }, "ProfileData": { "type": "object", "description": "Aggregated profile data for a single user.", "required": [ "wallet", "username", "margin", "pnl", "platform_medals" ], "properties": { "account_age_days": { "type": "integer", "format": "int64", "description": "Number of days since the account was first seen.", "nullable": true }, "account_first_seen_ts_ms": { "type": "integer", "format": "int64", "description": "Timestamp when the account was first observed (ms since epoch).", "nullable": true }, "active_competition_rank": { "allOf": [ { "$ref": "#/components/schemas/ProfileCompetitionRankSummary" } ], "nullable": true }, "margin": { "$ref": "#/components/schemas/ProfileMarginStats" }, "medal": { "type": "integer", "format": "int32", "description": "Best overall medal tier across all competitions.", "nullable": true, "minimum": 0 }, "platform_medals": { "$ref": "#/components/schemas/ProfileMetricMedals" }, "pnl": { "$ref": "#/components/schemas/ProfilePnlStats" }, "profile_image_url": { "type": "string", "description": "Moderated profile image URL, if set.", "nullable": true }, "username": { "type": "string", "description": "Display username." }, "wallet": { "type": "string", "description": "User's wallet address (checksummed Ethereum address)." } } }, "ProfileMarginStats": { "type": "object", "description": "Margin statistics shown on a user's profile.", "required": [ "in_use", "available", "total", "deposits", "withdraws" ], "properties": { "available": { "type": "string", "description": "Free margin available for new trades in USD. Serialized as a string." }, "deposits": { "type": "string", "description": "Lifetime deposit total in USD. Serialized as a string." }, "in_use": { "type": "string", "description": "Margin currently locked in positions in USD. Serialized as a string." }, "total": { "type": "string", "description": "Total account equity (in_use + available) in USD. Serialized as a string." }, "withdraws": { "type": "string", "description": "Lifetime withdrawal total in USD. Serialized as a string." } } }, "ProfileMetricMedals": { "type": "object", "description": "Platform-wide medals earned by a user across all competitions.", "properties": { "efficiency": { "type": "integer", "format": "int32", "description": "Best efficiency medal tier.", "nullable": true, "minimum": 0 }, "pnl": { "type": "integer", "format": "int32", "description": "Best PnL medal tier (1 = gold, 2 = silver, 3 = bronze).", "nullable": true, "minimum": 0 }, "volume": { "type": "integer", "format": "int32", "description": "Best volume medal tier.", "nullable": true, "minimum": 0 } } }, "ProfilePnlStats": { "type": "object", "description": "PnL statistics shown on a user's profile.", "required": [ "unrealized", "pnl_24h", "lifetime_realized" ], "properties": { "lifetime_realized": { "type": "string", "description": "Lifetime cumulative realized PnL in USD. Serialized as a string." }, "pnl_24h": { "type": "string", "description": "Realized PnL over the last 24 hours in USD. Serialized as a string." }, "unrealized": { "type": "string", "description": "Current mark-to-market unrealized PnL in USD. Serialized as a string." } } }, "ProfileResponse": { "type": "object", "description": "Response containing a user's full profile.", "required": [ "success", "data" ], "properties": { "data": { "$ref": "#/components/schemas/ProfileData" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "ProfileTradesResponse": { "type": "object", "description": "Paginated list of a user's trade fills, shown on their profile.", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FillApiResponse" }, "description": "Fill records for the current page." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "PublicLiquidationsResponse": { "type": "object", "description": "Public global liquidation history response.", "required": [ "success", "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LiquidationHistoryEntry" }, "description": "Liquidation transition entries ordered newest first." }, "error": { "type": "string", "description": "Error message, if any.", "nullable": true }, "page": { "$ref": "#/components/schemas/CursorPage" }, "success": { "type": "boolean", "description": "Whether the request was successful." } } }, "PushPreferencesRequest": { "type": "object", "required": [ "endpoint", "preferences" ], "properties": { "endpoint": { "type": "string" }, "preferences": { "description": "Example: {\"fills\": true, \"liquidations\": true, \"settlements\": false}" } } }, "PushPreferencesResponse": { "type": "object", "required": [ "updated" ], "properties": { "updated": { "type": "boolean" } } }, "PushSubscribeRequest": { "type": "object", "required": [ "endpoint", "auth_key", "p256dh_key" ], "properties": { "auth_key": { "type": "string" }, "endpoint": { "type": "string" }, "p256dh_key": { "type": "string" }, "preferences": { "description": "Optional notification preferences. Defaults to all enabled.", "nullable": true } } }, "PushSubscribeResponse": { "type": "object", "required": [ "ok" ], "properties": { "ok": { "type": "boolean" } } }, "PushUnsubscribeRequest": { "type": "object", "required": [ "endpoint" ], "properties": { "endpoint": { "type": "string" } } }, "PushUnsubscribeResponse": { "type": "object", "required": [ "deleted" ], "properties": { "deleted": { "type": "boolean" } } }, "ReadinessComponentReport": { "type": "object", "description": "Readiness status of one internal component (DB, engine, oracles, etc.).", "required": [ "name", "ready" ], "properties": { "detail": { "type": "string", "description": "Optional detail string explaining the current state.", "nullable": true }, "name": { "type": "string", "description": "Component name." }, "ready": { "type": "boolean", "description": "Whether the component is ready to serve traffic." } } }, "ReadyResponse": { "type": "object", "description": "Aggregated readiness probe response from `GET /ready`.", "required": [ "status", "components" ], "properties": { "components": { "type": "array", "items": { "$ref": "#/components/schemas/ReadinessComponentReport" }, "description": "Per-component readiness reports." }, "message": { "type": "string", "description": "Human-readable message if not all components are ready.", "nullable": true }, "status": { "type": "string", "description": "Overall readiness status (e.g. `\"ready\"` or `\"not_ready\"`)." } } }, "ReplaceOrderRequest": { "type": "object", "description": "Request to atomically cancel an existing order and place a new one.", "required": [ "wallet", "order_id", "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", "description": "Optional client-provided order ID for the new order", "nullable": true }, "mmp_enabled": { "type": "boolean" }, "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "order_id": { "type": "integer", "format": "int64", "description": "ID of the order to cancel", "minimum": 0 }, "price": { "type": "string", "description": "New order price as string (must match signed value exactly)" }, "side": { "$ref": "#/components/schemas/Side" }, "signature": { "type": "string" }, "size": { "type": "string", "description": "New order size as string (must match signed value exactly)" }, "symbol": { "type": "string", "description": "New order symbol" }, "tif": { "$ref": "#/components/schemas/TimeInForce" }, "wallet": { "type": "string" } } }, "ResetMmpRequest": { "type": "object", "description": "Signed request to reset (unfreeze) a triggered MMP state.", "required": [ "wallet", "currency", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Underlying currency to reset MMP for." }, "nonce": { "type": "integer", "format": "int64", "description": "Monotonically increasing nonce for replay protection.", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature authorizing this request." }, "wallet": { "type": "string", "description": "Market maker wallet address (checksummed Ethereum 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" } } }, "RfqProviderIndicativeQuote": { "type": "object", "required": [ "wallet", "bid_price", "ask_price", "max_bid_size", "max_ask_size", "updated_at" ], "properties": { "ask_price": { "type": "string" }, "bid_price": { "type": "string" }, "max_ask_size": { "type": "string" }, "max_bid_size": { "type": "string" }, "updated_at": { "type": "integer", "format": "int64", "minimum": 0 }, "wallet": { "type": "string" } } }, "SetMarginModeRequest": { "type": "object", "description": "Request to set margin mode.", "required": [ "wallet", "margin_mode", "nonce", "signature" ], "properties": { "margin_mode": { "type": "string" }, "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "signature": { "type": "string" }, "wallet": { "type": "string" } } }, "SetMmpConfigRequest": { "type": "object", "description": "Signed request to create or update an MMP configuration.", "required": [ "wallet", "currency", "interval_ms", "frozen_time_ms", "nonce", "signature" ], "properties": { "currency": { "type": "string", "description": "Underlying currency (e.g. `\"BTC\"`)." }, "delta_limit": { "type": "string", "description": "Maximum net delta limit. Serialized as a string.", "nullable": true }, "frozen_time_ms": { "type": "integer", "format": "int64", "description": "Freeze duration in milliseconds after a trigger." }, "interval_ms": { "type": "integer", "format": "int64", "description": "Rolling window length in milliseconds." }, "nonce": { "type": "integer", "format": "int64", "description": "Monotonically increasing nonce for replay protection.", "minimum": 0 }, "qty_limit": { "type": "string", "description": "Maximum filled quantity limit. Serialized as a string.", "nullable": true }, "signature": { "type": "string", "description": "EIP-712 signature authorizing this request." }, "vega_limit": { "type": "string", "description": "Maximum net vega limit. Serialized as a string.", "nullable": true }, "wallet": { "type": "string", "description": "Market maker wallet address (checksummed Ethereum address)." } } }, "SetProfileImageRequest": { "type": "object", "required": [ "image_data_base64", "content_type", "image_sha256" ], "properties": { "content_type": { "type": "string" }, "image_data_base64": { "type": "string" }, "image_sha256": { "type": "string" } } }, "SetProfileImageResponse": { "type": "object", "required": [ "wallet", "profile_image_url" ], "properties": { "profile_image_url": { "type": "string" }, "wallet": { "$ref": "#/components/schemas/WalletAddress" } } }, "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." } } }, "Side": { "type": "string", "description": "Order side (buy or sell).", "enum": [ "Buy", "Sell" ] }, "SpanMarginSummary": { "type": "object", "description": "SPAN-based portfolio margin breakdown for an account.", "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": "Total account equity (balance + unrealized PnL) in USD. Serialized as a string." }, "gamma_overlay": { "type": "string", "description": "Gamma/curvature overlay charge in USD. Serialized as a string." }, "hypercore_margin_required": { "type": "string", "description": "Margin held on HyperCore for perp positions in USD. Serialized as a string." }, "initial_margin_required": { "type": "string", "description": "Initial margin required for existing positions in USD. Serialized as a string." }, "maintenance_margin_required": { "type": "string", "description": "Maintenance margin required for existing positions in USD. Serialized as a string." }, "open_orders_initial_margin": { "type": "string", "description": "Initial margin reserved for open (unfilled) orders. Defaults to zero. Serialized as a string." }, "option_floor": { "type": "string", "description": "Minimum option margin floor (short option value * factor) in USD. Serialized as a string." }, "option_margin_required": { "type": "string", "description": "Options-specific margin requirement in USD. Serialized as a string." }, "scanning_risk": { "type": "string", "description": "SPAN scanning risk (worst-case scenario loss) in USD. Serialized as a string." } } }, "StandardMarginLiquidationOrderRequest": { "type": "object", "required": [ "wallet", "liquidated_wallet", "request_id", "auction_id", "bid_usdc", "positions", "portfolio_hash", "auction_terms_hash", "auction_version", "valuation_timestamp_ms", "bid_intent_hash", "nonce", "signature" ], "properties": { "auction_id": { "type": "string" }, "auction_terms_hash": { "type": "string" }, "auction_version": { "type": "integer", "format": "int64", "minimum": 0 }, "bid_intent_hash": { "type": "string" }, "bid_usdc": { "type": "string" }, "liquidated_wallet": { "type": "string" }, "nonce": { "type": "integer", "format": "int64", "minimum": 0 }, "portfolio_hash": { "type": "string" }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/StandardMarginLiquidationPositionRequest" } }, "request_id": { "type": "string" }, "signature": { "type": "string" }, "valuation_timestamp_ms": { "type": "integer", "format": "int64", "minimum": 0 }, "wallet": { "type": "string" } } }, "StandardMarginLiquidationPositionRequest": { "type": "object", "required": [ "symbol", "quantity", "entry_price" ], "properties": { "entry_price": { "type": "string" }, "quantity": { "type": "string" }, "symbol": { "type": "string" } } }, "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", "description": "A matched trade between a maker and a taker.", "required": [ "trade_id", "symbol", "price", "size", "maker_address", "taker_address", "maker_fee", "taker_fee", "timestamp", "created_at" ], "properties": { "created_at": { "type": "string", "description": "When the trade was persisted (ISO 8601)." }, "maker_address": { "type": "string", "description": "Maker wallet address (checksummed Ethereum address)." }, "maker_fee": { "type": "string", "description": "Fee charged to the maker in USD. Serialized as a string." }, "price": { "type": "string", "description": "Execution price in USD. Serialized as a string." }, "size": { "type": "string", "description": "Trade size in contracts. Serialized as a string." }, "symbol": { "type": "string", "description": "Instrument symbol that was traded." }, "taker_address": { "type": "string", "description": "Taker wallet address (checksummed Ethereum address)." }, "taker_fee": { "type": "string", "description": "Fee charged to the taker in USD. Serialized as a string." }, "timestamp": { "type": "integer", "format": "int64", "description": "Trade timestamp in milliseconds since epoch." }, "trade_id": { "type": "integer", "format": "int64", "description": "Unique trade identifier." } } }, "TradesResponse": { "type": "object", "description": "Paginated list of trades.", "required": [ "success", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TradeApiResponse" }, "description": "Trade records for the current page." }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "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" } } }, "UsernameResponse": { "type": "object", "required": [ "wallet_address", "username" ], "properties": { "username": { "type": "string" }, "wallet_address": { "type": "string" } } }, "VersionResponse": { "type": "object", "description": "Build version and git metadata returned by `GET /version`.", "required": [ "version", "commit", "ref", "build_time" ], "properties": { "build_time": { "type": "string", "description": "Build timestamp string." }, "commit": { "type": "string", "description": "Short git commit SHA." }, "ref": { "type": "string", "description": "Git ref (branch or tag) from which the binary was built. Serialized as `\"ref\"`." }, "signing_chain_id": { "type": "integer", "format": "int64", "description": "Chain ID used for EIP-712 option order signing domain (998 = testnet, 999 = mainnet).\nAbsent on older servers; frontend should default to 998 if missing.", "nullable": true, "minimum": 0 }, "version": { "type": "string", "description": "Semantic version of the running binary." } } }, "WalletAddress": { "type": "string", "description": "Ethereum wallet address serialized as a checksummed `0x`-prefixed hex string.", "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." }, { "name": "Push Notifications", "description": "Web Push subscription management. Register browser push subscriptions to receive fill and liquidation notifications even when the app is not open." } ] }