{ "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", "x-hypercall-error-codes": { "version": 1, "code_format": "lower_snake_case", "codes": [ { "code": "bad_request", "http_statuses": [ 400 ], "description": "Generic malformed request when no more-specific code applies" }, { "code": "invalid_json", "http_statuses": [ 400, 422 ], "description": "JSON parsing failed" }, { "code": "missing_field", "http_statuses": [ 400 ], "description": "A required request field is missing" }, { "code": "invalid_wallet", "http_statuses": [ 400 ], "description": "Wallet string could not be parsed" }, { "code": "invalid_parameter", "http_statuses": [ 400 ], "description": "A request parameter has an invalid value or type" }, { "code": "invalid_field", "http_statuses": [ 400 ], "description": "A required field is missing or invalid" }, { "code": "unsupported_action", "http_statuses": [ 400 ], "description": "Requested directive action is unsupported by this API" }, { "code": "unknown_account", "http_statuses": [ 400 ], "description": "Requested account is not known on-chain" }, { "code": "signature_verification_failed", "http_statuses": [ 400 ], "description": "EIP-712 signature recovery failed" }, { "code": "invalid_signature", "http_statuses": [ 400 ], "description": "Agent or directive signature could not be verified" }, { "code": "unsupported_endpoint", "http_statuses": [ 400 ], "description": "Request cannot be signed for this endpoint" }, { "code": "unauthorized", "http_statuses": [ 401 ], "description": "Caller is not authorized for the requested action" }, { "code": "forbidden", "http_statuses": [ 403 ], "description": "Caller is authenticated but cannot perform the action" }, { "code": "referral_balance_required", "http_statuses": [ 403 ], "description": "Referral-code creation requires a non-zero engine balance" }, { "code": "not_found", "http_statuses": [ 404 ], "description": "Route or requested resource does not exist" }, { "code": "referral_code_not_found", "http_statuses": [ 404 ], "description": "Requested referral code does not exist" }, { "code": "method_not_allowed", "http_statuses": [ 405 ], "description": "Route exists but does not accept the HTTP method" }, { "code": "not_acceptable", "http_statuses": [ 406 ], "description": "Requested response representation is not accepted" }, { "code": "request_timeout", "http_statuses": [ 408 ], "description": "Request timed out before the server completed it" }, { "code": "conflict", "http_statuses": [ 409 ], "description": "Generic resource conflict when no more-specific code applies" }, { "code": "invalid_nonce", "http_statuses": [ 409 ], "description": "Signed referral nonce is stale, invalid, or outside acceptable time bounds" }, { "code": "referral_code_exists", "http_statuses": [ 409 ], "description": "Requested referral code is already registered" }, { "code": "referral_wallet_has_code", "http_statuses": [ 409 ], "description": "Wallet already owns a referral code" }, { "code": "referral_code_owner_mismatch", "http_statuses": [ 409 ], "description": "Signed referrer does not own the supplied referral code" }, { "code": "self_referral", "http_statuses": [ 409 ], "description": "Wallet cannot refer itself" }, { "code": "referral_already_bound", "http_statuses": [ 409 ], "description": "Wallet is already bound to a different referrer" }, { "code": "username_taken", "http_statuses": [ 409 ], "description": "Requested username is already assigned to another wallet" }, { "code": "precondition_failed", "http_statuses": [ 412 ], "description": "Request precondition did not hold" }, { "code": "payload_too_large", "http_statuses": [ 413 ], "description": "Request body exceeds its endpoint limit" }, { "code": "unsupported_media_type", "http_statuses": [ 415 ], "description": "Request does not use an accepted content type" }, { "code": "unprocessable_entity", "http_statuses": [ 422 ], "description": "Request body cannot be processed" }, { "code": "rate_limit_exceeded", "http_statuses": [ 429 ], "description": "Request limit exceeded, inspect Retry-After" }, { "code": "client_error", "http_statuses": [], "status_note": "other 4xx", "description": "Generic fallback for an otherwise-unmapped client error" }, { "code": "internal_error", "http_statuses": [ 500 ], "status_note": "other 5xx", "description": "Unexpected server failure, including an otherwise-unmapped server error" }, { "code": "not_implemented", "http_statuses": [ 501 ], "description": "Requested server behavior is not implemented" }, { "code": "bad_gateway", "http_statuses": [ 502 ], "description": "Required upstream service returned an invalid response" }, { "code": "service_not_ready", "http_statuses": [ 503 ], "description": "Service startup has not completed" }, { "code": "service_unavailable", "http_statuses": [ 503 ], "description": "Required service or capability is unavailable" }, { "code": "trading_halted", "http_statuses": [ 503 ], "description": "Trading is halted for the requested market or globally" }, { "code": "read_not_ready", "http_statuses": [ 503 ], "description": "Requested fenced read is not ready, retry shortly" }, { "code": "gateway_timeout", "http_statuses": [ 504 ], "description": "Required upstream operation timed out" } ], "json_rpc_codes": [ { "code": 13020, "message": "not_found", "description": "Requested orderbook instrument does not exist" } ] } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "eip712_signature": [] } ] } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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": { "allOf": [ { "$ref": "#/components/schemas/GasProviderErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } }, "500": { "description": "Upstream RPC fee estimation failed", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GasProviderErrorResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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": { "allOf": [ { "$ref": "#/components/schemas/HealthResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Instrument not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "Margin mode service unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Unauthorized", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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": "JSON-RPC orderbook data. A missing instrument is returned as a JSON-RPC error with code 13020.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderBookJsonRpcResponse" } } } }, "400": { "description": "Missing query parameter: instrument_id or instrument_name", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/orders/status": { "get": { "tags": [ "Trading" ], "summary": "Get HyperCore order status for a master-account wallet.", "operationId": "get_hypercore_order_status", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to resolve to the HyperCore account.", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" }, { "name": "order_id", "in": "query", "description": "HyperCore order id or client order id.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "HyperCore order status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderStatusResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "HyperCore info unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "Portfolio margin data unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/profile": { "get": { "tags": [ "Portfolio" ], "summary": "Get a wallet profile.", "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/realized-pnl": { "get": { "tags": [ "Portfolio" ], "summary": "Get realized PnL by symbol for a wallet.", "operationId": "get_realized_pnl", "parameters": [ { "name": "wallet", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" } }, { "name": "from_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "to_ts_ms", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RealizedPnlResponse" } } } } } } }, "/profile/trades": { "get": { "tags": [ "Portfolio" ], "summary": "List a wallet's 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": "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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": { "allOf": [ { "$ref": "#/components/schemas/ReadyResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/referrals/binding": { "get": { "tags": [ "Referrals" ], "summary": "Return a wallet's projected referral binding, if one exists.", "operationId": "get_binding", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet whose referral binding should be returned.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Projected referral binding. Cache staleness is up to 60 seconds, projection lag can add further delay, and an accepted signed SetReferrer remains authoritative.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=60; response may be up to 60 seconds stale" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralBindingStatusResponse" } } } }, "400": { "description": "Missing or invalid wallet", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Referral persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/referrals/code": { "get": { "tags": [ "Referrals" ], "summary": "Load the permanent referral code owned by a wallet.", "operationId": "get_code_by_owner", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet that owns the requested referral code.", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral code owned by the wallet, or null when none exists", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ReferralCodeResponse" } ], "nullable": true } } } }, "500": { "description": "Referral persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "post": { "tags": [ "Referrals" ], "summary": "Create the one referral code owned by an account through an owner or delegated-wallet signature.", "operationId": "create_code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReferralCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Referral code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralCodeResponse" } } } }, "400": { "description": "Invalid request or signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Account owner or delegated API wallet authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Non-zero engine balance required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Code or wallet already registered", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Referral persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "Referral eligibility temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "eip712_signature": [] } ] } }, "/referrals/code/{code}": { "get": { "tags": [ "Referrals" ], "summary": "Resolve and validate a referral code before the wallet signs SetReferrer.", "operationId": "get_code", "parameters": [ { "name": "code", "in": "path", "description": "Referral code", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralCodeResponse" } } } }, "400": { "description": "Invalid referral code", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Referral code not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Referral persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/referrals/referred": { "get": { "tags": [ "Referrals" ], "summary": "Return referred wallets and their projected lifetime Hypercall fill volume.", "description": "Results use offset pagination and deterministic newest-binding-first order.", "operationId": "list_referred_wallets", "parameters": [ { "name": "wallet", "in": "query", "description": "Referrer whose referred wallets should be returned.", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Maximum rows to return. Defaults to 50 and cannot exceed 100.", "required": false, "schema": { "type": "integer", "nullable": true, "maximum": 100, "minimum": 1 }, "example": 50 }, { "name": "offset", "in": "query", "description": "Number of rows to skip. Defaults to zero.", "required": false, "schema": { "type": "integer", "nullable": true, "minimum": 0 }, "example": 0 } ], "responses": { "200": { "description": "Projected referred-wallet Hypercall fill-volume page. Current PM manager identities resolve to their projected canonical Account.sol. Cache staleness is up to 60 seconds, projection lag can add further delay, and accepted signed SetReferrer writes remain authoritative.", "headers": { "Cache-Control": { "schema": { "type": "string" }, "description": "public, max-age=60; response may be up to 60 seconds stale" } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferredWalletsResponse" } } } }, "400": { "description": "Invalid wallet or pagination", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Referral persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/referrals/set-referrer": { "post": { "tags": [ "Referrals" ], "summary": "Permanently set a wallet's referrer through an owner or delegated-wallet signature.", "operationId": "set_referrer", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetReferrerRequest" } } }, "required": true }, "responses": { "200": { "description": "Accepted engine referral binding", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralBindingResponse" } } } }, "400": { "description": "Invalid request or signature", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Account owner or delegated API wallet authorization required", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "Referral code not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Self-referral or wallet already bound", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Referral engine or persistence failure", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "Referral engine temporarily unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "504": { "description": "Referral engine command timed out", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "eip712_signature": [] } ] } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/revoke-all-agents": { "delete": { "tags": [ "Agents" ], "summary": "Revoke every agent authorization owned by the signing wallet.", "operationId": "revoke_all_agents", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAllAgentsRequest" } } }, "required": true }, "responses": { "200": { "description": "All agents revoked", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RevokeAllAgentsResponse" } } } }, "400": { "description": "Invalid signature", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBody" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/risk/grid": { "get": { "tags": [ "Risk" ], "summary": "Get extended risk grid for a wallet.", "description": "Returns detailed margin breakdown and scenario P&L for risk analysis.\nThis is similar to Deribit's risk grid endpoint.\n\nThe response includes:\n- `equity`: Executed PM equity = cash + executed option UPNL + executed perp UPNL\n- `position_initial_margin`: IM from executed positions only\n- `position_maintenance_margin`: MM threshold for liquidation\n- `open_orders_initial_margin`: Additional IM from open orders\n- `underlyings`: one aligned scenario and instrument matrix per underlying", "operationId": "get_risk_grid", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet address to get risk grid for", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" }, "example": "0x1234567890abcdef1234567890abcdef12345678" } ], "responses": { "200": { "description": "Risk grid response", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiRiskGridResponse" } } } }, "503": { "description": "Portfolio margin data unavailable", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/OpenApiRiskGridResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/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": { "allOf": [ { "$ref": "#/components/schemas/ApiResponse" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "403": { "description": "Wallet mismatch", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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": "after_trade_id", "in": "query", "description": "Exclusive global trade cursor. Returns trades ordered by trade ID ascending.", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "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" } } } }, "400": { "description": "Invalid or incompatible pagination parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/trades/{trade_id}": { "get": { "tags": [ "Trading" ], "summary": "Get one trade by its unique trade ID.", "operationId": "get_trade_by_id", "parameters": [ { "name": "trade_id", "in": "path", "description": "Unique trade ID", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Trade details", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OpenApiTradeResponse" } } } }, "400": { "description": "Malformed trade ID", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBody" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } }, "404": { "description": "Trade not found", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBody" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/ApiErrorBody" }, { "$ref": "#/components/schemas/ApiErrorBody" } ] } } } } } } }, "/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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "404": { "description": "No username found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "Username already taken", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "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", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "eip712_signature": [] } ] } }, "/v1/tee-api-wallet/approval": { "post": { "tags": [ "TEE API Wallets" ], "summary": "Verify the manager signature and enqueue the API-wallet approval directive.", "operationId": "submit_approval", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalSubmitRequest" } } }, "required": true }, "responses": { "200": { "description": "API-wallet approval directive accepted or rejected", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SubmitResponse" } } } }, "400": { "description": "Invalid wallet identity, nonce, signature, or request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Manager authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "409": { "description": "An identical approval submission is still in progress", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "TEE API wallet approval submission rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "TEE API wallet provider or directive submitter unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/tee-api-wallet/approval-request": { "post": { "tags": [ "TEE API Wallets" ], "summary": "Allocate the account's TEE API wallet and return its approval payload.", "operationId": "request_approval", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequest" } } }, "required": true }, "responses": { "200": { "description": "TEE API wallet identity and EIP-712 approval payload", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApprovalRequestResponse" } } } }, "400": { "description": "Account is not a canonical portfolio-margin Account.sol account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "401": { "description": "Manager authentication failed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "429": { "description": "TEE API wallet enrollment rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "503": { "description": "TEE API wallet provider unavailable", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } } } }, "/v1/transfers": { "get": { "tags": [ "Portfolio" ], "summary": "Return unified transfer history for a wallet.", "operationId": "get_transfer_history", "parameters": [ { "name": "wallet", "in": "query", "description": "Wallet or manager address, resolved to the canonical account.", "required": true, "schema": { "$ref": "#/components/schemas/WalletAddress" } }, { "name": "transaction_type", "in": "query", "description": "Comma-separated deposit, withdrawal, or internal_transfer values.", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "asset", "in": "query", "description": "Comma-separated USDC or exact option symbols, case-insensitive.", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "status", "in": "query", "description": "Comma-separated pending, completed, failed, or manual_review values.", "required": false, "schema": { "type": "string", "nullable": true } }, { "name": "limit", "in": "query", "description": "Page size. Defaults to 50 and is capped at 100.", "required": false, "schema": { "type": "integer", "format": "int64", "nullable": true } }, { "name": "cursor", "in": "query", "description": "Opaque versioned base64url cursor.", "required": false, "schema": { "type": "string", "nullable": true } } ], "responses": { "200": { "description": "Unified transfer history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TransferHistoryResponse" } } } }, "400": { "description": "Invalid filter, cursor, or limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } }, "500": { "description": "Persisted transfer history could not be decoded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiErrorBody" } } } } }, "security": [ { "wallet_query": [] } ] } }, "/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": { "ApiErrorBody": { "type": "object", "description": "API error response body", "required": [ "code", "message" ], "properties": { "code": { "type": "string", "description": "Stable machine-readable error code. Clients should branch on this field\nwhen this structured envelope is returned. The published catalog lists\ncurrent values, while this remains an open string for future codes." }, "error": { "type": "string", "description": "Legacy error identifier retained when an endpoint already returned one.", "nullable": true }, "message": { "type": "string", "description": "Human-readable explanation for display and diagnostics." } } }, "ApiResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "ApprovalRequest": { "type": "object", "required": [ "account", "manager", "timestamp", "signature" ], "properties": { "account": { "$ref": "#/components/schemas/WalletAddress" }, "manager": { "$ref": "#/components/schemas/WalletAddress" }, "signature": { "type": "string", "description": "Manager signature over Hypercall's timestamped authentication message." }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp in seconds included in the EIP-191 authentication message." } }, "additionalProperties": false }, "ApprovalRequestResponse": { "type": "object", "required": [ "teeWalletId", "apiWalletAddress", "apiWalletName", "nonce", "issuedAtMs", "expiresAtMs", "typedData" ], "properties": { "apiWalletAddress": { "$ref": "#/components/schemas/WalletAddress" }, "apiWalletName": { "type": "string", "description": "Stable name registered for the API wallet on HyperLiquid." }, "expiresAtMs": { "type": "integer", "format": "int64", "description": "Last Unix millisecond at which the signed approval may be submitted.", "example": 1785672300000, "minimum": 0 }, "issuedAtMs": { "type": "integer", "format": "int64", "description": "Server issuance time encoded into `nonce`, as Unix milliseconds.", "example": 1785672000000, "minimum": 0 }, "nonce": { "type": "string", "description": "Nonce included in the EIP-712 approval payload. Copy it without modification.", "example": "18446744073709551615" }, "teeWalletId": { "type": "string", "description": "Opaque TEE wallet identity. Echo this value when submitting the signature.", "example": "0x2222222222222222222222222222222222222222222222222222222222222222" }, "typedData": { "type": "object", "description": "EIP-712 payload for the account manager to sign." } } }, "ApprovalSubmitRequest": { "type": "object", "required": [ "account", "manager", "timestamp", "authenticationSignature", "teeWalletId", "nonce", "signature" ], "properties": { "account": { "$ref": "#/components/schemas/WalletAddress" }, "authenticationSignature": { "type": "string", "description": "Manager signature over Hypercall's timestamped authentication message." }, "manager": { "$ref": "#/components/schemas/WalletAddress" }, "nonce": { "type": "string", "description": "Nonce returned by the approval-request endpoint.", "example": "18446744073709551615" }, "signature": { "type": "string", "description": "Account manager's EIP-712 signature over the returned typed data." }, "teeWalletId": { "type": "string", "description": "Opaque identity returned by `POST /v1/tee-api-wallet/approval-request`.", "example": "0x2222222222222222222222222222222222222222222222222222222222222222" }, "timestamp": { "type": "integer", "format": "int64", "description": "Unix timestamp in seconds included in the EIP-191 authentication message." } }, "additionalProperties": false }, "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" } } }, "CreateReferralCodeRequest": { "type": "object", "required": [ "wallet", "code", "nonce", "signature" ], "properties": { "code": { "type": "string", "description": "Requested code. The signature covers this exact submitted string; after\nauthentication the server trims it and normalizes it to uppercase." }, "nonce": { "type": "integer", "format": "int64", "description": "Time-bound replay-protection nonce included in the CreateReferralCode EIP-712 value.", "minimum": 0 }, "signature": { "type": "string", "description": "Owner or delegated API wallet's CreateReferralCode EIP-712 signature." }, "wallet": { "type": "string", "description": "Account that will own the normalized referral code." } } }, "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" } } }, "DirectiveFill": { "type": "object", "description": "A fill from HyperLiquid (best-effort, queried after submission).", "required": [ "coin", "side", "size", "price", "time" ], "properties": { "coin": { "type": "string" }, "price": { "type": "string" }, "side": { "type": "string" }, "size": { "type": "string" }, "time": { "type": "integer", "format": "int64", "minimum": 0 } } }, "DirectiveRejection": { "type": "object", "required": [ "code", "message" ], "properties": { "code": { "type": "string" }, "message": { "type": "string" } } }, "DirectiveStage": { "type": "string", "description": "How far the directive got in the pipeline.", "enum": [ "rejected", "enqueued", "submitted" ] }, "ExtendedRiskMatrixResponse": { "type": "object", "description": "Full risk matrix showing per-instrument PnL across all SPAN scenarios.", "required": [ "scenarios", "instruments", "total_pnls", "worst_scenario_index", "worst_scenario_pnl" ], "properties": { "instruments": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentRiskRowResponse" }, "description": "Per-instrument risk rows (rows of the matrix)." }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/ScenarioDefinition" }, "description": "Scenario definitions (columns of the matrix)." }, "total_pnls": { "type": "array", "items": { "type": "string" }, "description": "Aggregate portfolio PnL for each scenario. Serialized as strings." }, "worst_scenario_index": { "type": "integer", "description": "Index into `scenarios` of the worst aggregate shared-shock diagnostic.\nThis index does not drive scanning risk for a multi-underlying portfolio.", "minimum": 0 }, "worst_scenario_pnl": { "type": "string", "description": "Weighted PnL of the worst aggregate shared-shock diagnostic in USD.\nThe margin-driving independent-underlying charge is `RiskGridResponse::scanning_risk`.\nSerialized as a string." } } }, "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." }, "instrument_type": { "type": "string", "description": "Instrument family that produced this fill (`\"option\"` or `\"perp\"`)." }, "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" } } }, "InstrumentRiskRowResponse": { "type": "object", "description": "Per-instrument row in the extended risk matrix.", "required": [ "symbol", "underlying", "amount", "base_amount", "current_value", "scenario_pnls" ], "properties": { "amount": { "type": "string", "description": "Position size in contracts. Serialized as a string." }, "base_amount": { "type": "string", "description": "Position size in base asset units. Serialized as a string." }, "current_value": { "type": "string", "description": "Current mark-to-market value of the position in USD. Serialized as a string." }, "scenario_pnls": { "type": "array", "items": { "type": "string" }, "description": "PnL under each scenario, ordered to match `ExtendedRiskMatrixResponse::scenarios`. Serialized as strings." }, "symbol": { "type": "string", "description": "Instrument symbol." }, "underlying": { "type": "string", "description": "Underlying asset (e.g. `\"BTC\"`, `\"ETH\"`)." } } }, "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" } } }, "JsonRpcError": { "type": "object", "description": "JSON-RPC error information.", "required": [ "code", "message" ], "properties": { "code": { "type": "integer", "format": "int32", "description": "Error code" }, "data": { "description": "Additional error data", "nullable": true }, "message": { "type": "string", "description": "Error message" } } }, "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." } } }, "OpenApiRiskGridResponse": { "type": "object", "description": "Concrete response envelope that keeps the risk-grid payload reachable in\nthe published OpenAPI component graph.", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/RiskGridResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "OpenApiTradeResponse": { "type": "object", "description": "Concrete response envelope for one trade lookup.", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/TradeApiResponse" } ], "nullable": true }, "error": { "type": "string", "nullable": true }, "success": { "type": "boolean" } } }, "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", "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 }, "instrument_type": { "type": "string", "description": "Instrument family that produced this order (`\"option\"` or `\"perp\"`)." }, "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\"`), when the source exposes it.", "nullable": true }, "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" } } }, "OrderBookJsonRpcResponse": { "type": "object", "description": "Concrete OpenAPI shape for the JSON-RPC orderbook response.\n\nThe handler uses the shared generic `JsonRpcResponse`, while the schema\nuses this concrete form so generated public OpenAPI references remain\nresolvable after schema pruning.", "required": [ "jsonrpc", "testnet", "usDiff", "usIn", "usOut" ], "properties": { "error": { "allOf": [ { "$ref": "#/components/schemas/JsonRpcError" } ], "nullable": true }, "jsonrpc": { "type": "string" }, "result": { "allOf": [ { "$ref": "#/components/schemas/OrderBookResponse" } ], "nullable": true }, "testnet": { "type": "boolean" }, "usDiff": { "type": "integer", "format": "int64" }, "usIn": { "type": "integer", "format": "int64" }, "usOut": { "type": "integer", "format": "int64" } } }, "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" ] }, "OrderStatusResponse": { "type": "object", "required": [ "success" ], "properties": { "data": { "allOf": [ { "$ref": "#/components/schemas/Order" } ], "nullable": true }, "success": { "type": "boolean" } } }, "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)" }, "reduce_only": { "type": "boolean" }, "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", "portfolio_snapshot_timestamp_ms" ], "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 }, "portfolio_snapshot_timestamp_ms": { "type": "integer", "format": "int64", "description": "Source timestamp of the authoritative portfolio snapshot.", "nullable": true, "minimum": 0 }, "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)." }, "withdrawable_usdc": { "type": "string", "description": "HyperCore Account.sol USDC currently eligible for a direct PM withdrawal.\nThis excludes engine-local cash until the sweeper credits Account.sol.", "nullable": true } } }, "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)." }, "ProfileData": { "type": "object", "description": "Aggregated profile data for a single user.", "required": [ "wallet", "account_wallet", "username", "margin", "pnl" ], "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 }, "account_wallet": { "type": "string", "description": "Resolved trading account whose financial statistics are returned." }, "margin": { "$ref": "#/components/schemas/ProfileMarginStats" }, "pnl": { "$ref": "#/components/schemas/ProfilePnlStats" }, "username": { "type": "string", "description": "Display username." }, "wallet": { "type": "string", "description": "Requested identity 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." } } }, "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\"`)." } } }, "RealizedPnlResponse": { "type": "object", "description": "Response containing per-symbol realized PnL.", "required": [ "success", "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/RealizedPnlRow" }, "description": "Per-symbol realized PnL rows." }, "success": { "type": "boolean", "description": "Whether the request succeeded." } } }, "RealizedPnlRow": { "type": "object", "description": "Realized PnL breakdown for one instrument symbol.", "required": [ "symbol", "realized_pnl", "event_count" ], "properties": { "event_count": { "type": "integer", "format": "int64", "description": "Number of PnL events (fills, settlements) contributing to the total." }, "realized_pnl": { "type": "string", "description": "Total realized PnL for this symbol in USD. Serialized as a string." }, "symbol": { "type": "string", "description": "Instrument symbol." } } }, "ReferralBindingResponse": { "type": "object", "required": [ "referred_wallet", "referrer_wallet" ], "properties": { "referred_wallet": { "type": "string" }, "referrer_wallet": { "type": "string" } } }, "ReferralBindingStatusResponse": { "type": "object", "description": "Public, projection-backed referral binding lookup.\n\nThis response may be served from a public cache up to 60 seconds stale,\nand projection lag can add further delay. An accepted signed SetReferrer\nwrite remains authoritative while this read catches up.", "required": [ "referred_wallet" ], "properties": { "referred_wallet": { "type": "string", "description": "Wallet whose referral binding was requested." }, "referrer_wallet": { "type": "string", "description": "Permanently bound referrer, or null when the wallet is not yet bound.", "nullable": true } } }, "ReferralCodeResponse": { "type": "object", "required": [ "code", "owner_wallet", "created_at" ], "properties": { "code": { "type": "string" }, "created_at": { "type": "string", "format": "date-time" }, "owner_wallet": { "type": "string" } } }, "ReferredWalletVolumeRow": { "type": "object", "description": "Public referred-wallet volume row.", "required": [ "referred_wallet", "volume_usd" ], "properties": { "referred_wallet": { "type": "string", "description": "Wallet referred by the requested referrer." }, "volume_usd": { "type": "string", "description": "Lifetime notional from persisted Hypercall fills, denominated in USD.\nA portfolio-margin manager resolves through the current projected\ncanonical Account.sol. Upstream-only HyperCore fills are not included." } } }, "ReferredWalletsResponse": { "type": "object", "description": "Public, projection-backed referred-wallet volume page.\n\nThis response may be served from a public cache up to 60 seconds stale,\nand projection lag can add further delay. Accepted signed SetReferrer\nwrites remain authoritative while attribution reads catch up.", "required": [ "referrer_wallet", "data", "pagination" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/ReferredWalletVolumeRow" } }, "pagination": { "$ref": "#/components/schemas/Pagination" }, "referrer_wallet": { "type": "string", "description": "Referrer whose referred wallets were requested." } } }, "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)" }, "reduce_only": { "type": "boolean" }, "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" } } }, "RevokeAllAgentsRequest": { "type": "object", "description": "Request to revoke every agent wallet authorized by the signer.", "required": [ "nonce", "signature" ], "properties": { "nonce": { "type": "integer", "format": "int64", "description": "Nonce for replay protection", "minimum": 0 }, "signature": { "type": "string", "description": "EIP-712 signature from wallet owner" } } }, "RevokeAllAgentsResponse": { "type": "object", "description": "Response for revoking every agent authorized by a wallet.", "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" } } }, "RiskGridResponse": { "type": "object", "description": "Top-level SPAN risk grid response for an account.", "required": [ "equity", "position_initial_margin", "position_maintenance_margin", "open_orders_initial_margin", "total_initial_margin", "scanning_risk", "option_floor", "gamma_overlay", "underlyings" ], "properties": { "equity": { "type": "string", "description": "Total account equity in USD. Serialized as a string." }, "gamma_overlay": { "type": "string", "description": "Gamma overlay charge in USD. Serialized as a string." }, "open_orders_initial_margin": { "type": "string", "description": "Direct additive price-band and perp-factor reservation for open orders in USD.\nSerialized as a string." }, "option_floor": { "type": "string", "description": "Option margin floor in USD. Serialized as a string." }, "position_initial_margin": { "type": "string", "description": "Initial margin for existing positions in USD. Serialized as a string." }, "position_maintenance_margin": { "type": "string", "description": "Maintenance margin for existing positions in USD. Serialized as a string." }, "scanning_risk": { "type": "string", "description": "Margin-driving SPAN scanning risk in USD. This sums each underlying's\nindependently worst weighted loss. Serialized as a string." }, "total_initial_margin": { "type": "string", "description": "Combined initial margin (positions + open orders) in USD. Serialized as a string." }, "underlyings": { "type": "array", "items": { "$ref": "#/components/schemas/UnderlyingRiskGridResponse" }, "description": "Independently configured executed-position scenario and instrument grids by underlying." } } }, "RiskGridScenario": { "type": "object", "description": "A single SPAN risk-grid scenario with its computed PnL.", "required": [ "id", "spot_shock_pct", "vol_shock_pct", "pnl_weight", "is_tail", "total_pnl" ], "properties": { "id": { "type": "string", "description": "Unique scenario identifier (e.g. `\"S1\"`)." }, "is_tail": { "type": "boolean", "description": "Whether this is a tail/extreme scenario." }, "pnl_weight": { "type": "string", "description": "Weight applied to this scenario's PnL in the scanning risk calculation. Serialized as a string." }, "spot_shock_pct": { "type": "string", "description": "Spot price shock as a fraction (e.g. `-0.15` = -15%). Serialized as a string." }, "total_pnl": { "type": "string", "description": "Total portfolio PnL under this scenario in USD. Serialized as a string." }, "vol_shock_pct": { "type": "string", "description": "Implied volatility shock as a fraction (e.g. `0.30` = +30%). Serialized as a string." } } }, "ScenarioDefinition": { "type": "object", "description": "Definition of a risk scenario (without computed PnL).", "required": [ "id", "spot_shock_pct", "vol_shock_pct", "pnl_weight", "is_tail" ], "properties": { "id": { "type": "string", "description": "Unique scenario identifier." }, "is_tail": { "type": "boolean", "description": "Whether this is a tail/extreme scenario." }, "pnl_weight": { "type": "string", "description": "Weight applied to this scenario in the scanning risk calculation. Serialized as a string." }, "spot_shock_pct": { "type": "string", "description": "Spot price shock as a fraction. Serialized as a string." }, "vol_shock_pct": { "type": "string", "description": "Implied volatility shock as a fraction. Serialized as a 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)." } } }, "SetReferrerRequest": { "type": "object", "required": [ "wallet", "code", "referrer", "nonce", "signature" ], "properties": { "code": { "type": "string", "description": "Control-plane code used to resolve the referrer. This field is intentionally\nnot signed; the server requires its owner to equal the signed referrer." }, "nonce": { "type": "integer", "format": "int64", "description": "Per-signer replay-protection nonce included in the SetReferrer EIP-712 value.", "minimum": 0 }, "referrer": { "type": "string", "description": "Final referrer address included in the SetReferrer EIP-712 value." }, "signature": { "type": "string", "description": "Owner or delegated API wallet's SetReferrer signature over wallet, referrer, and nonce." }, "wallet": { "type": "string", "description": "Account permanently setting its referrer." } } }, "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" } } }, "SubmitResponse": { "type": "object", "description": "Single honest response for directive submission.\nEvery field is populated with whatever we know. Nulls mean we don't know.", "required": [ "stage", "directiveId", "actionKey", "account", "nonce" ], "properties": { "account": { "$ref": "#/components/schemas/WalletAddress" }, "actionKey": { "type": "string", "description": "Which action was submitted." }, "directiveId": { "type": "string", "description": "Unique directive identifier." }, "fills": { "type": "array", "items": { "$ref": "#/components/schemas/DirectiveFill" }, "description": "Best-effort fills from HyperLiquid. Null means we don't know, not \"no fills.\"", "nullable": true }, "nonce": { "type": "string", "description": "Nonce used for the directive.", "example": "18446744073709551615" }, "recoveredSigner": { "allOf": [ { "$ref": "#/components/schemas/WalletAddress" } ], "nullable": true }, "rejection": { "allOf": [ { "$ref": "#/components/schemas/DirectiveRejection" } ], "nullable": true }, "stage": { "$ref": "#/components/schemas/DirectiveStage" }, "txHash": { "type": "string", "description": "On-chain transaction hash (null if not submitted yet or async path used).", "nullable": true } } }, "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", "taker_side", "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." }, "taker_side": { "$ref": "#/components/schemas/Side" }, "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." } } }, "TransferHistoryEntry": { "type": "object", "description": "One canonical deposit, withdrawal, or internal transfer.", "required": [ "id", "transaction_type", "subtype", "asset_type", "asset_symbol", "amount", "status", "tx_hash_type", "created_at" ], "properties": { "amount": { "type": "string", "description": "Positive decimal string in asset units." }, "asset_symbol": { "type": "string" }, "asset_type": { "type": "string" }, "created_at": { "type": "string", "description": "Non-null RFC3339 creation timestamp." }, "delivery_status": { "type": "string", "nullable": true }, "domain_status": { "type": "string", "nullable": true }, "id": { "type": "string" }, "status": { "type": "string" }, "subtype": { "type": "string" }, "transaction_type": { "type": "string" }, "tx_hash": { "type": "string", "nullable": true }, "tx_hash_type": { "type": "string", "description": "Namespace used to interpret tx_hash: hyper_evm or hypercore." } } }, "TransferHistoryResponse": { "type": "object", "description": "Unified transfer-history response.", "required": [ "success", "data", "page" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/TransferHistoryEntry" } }, "error": { "type": "string", "nullable": true }, "page": { "$ref": "#/components/schemas/CursorPage" }, "success": { "type": "boolean" } } }, "UnderlyingRiskGridResponse": { "type": "object", "description": "SPAN scenarios and aligned instrument matrix for one underlying.", "required": [ "underlying", "scenarios", "extended_risk_matrix" ], "properties": { "extended_risk_matrix": { "$ref": "#/components/schemas/ExtendedRiskMatrixResponse" }, "scenarios": { "type": "array", "items": { "$ref": "#/components/schemas/RiskGridScenario" }, "description": "Scenario results using this underlying's exact configured shocks." }, "underlying": { "type": "string", "description": "Underlying symbol whose configured shocks produced this matrix." } } }, "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": "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| `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| `rfq` | Yes | RFQ quotes and status updates |\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**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**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": "Referrals", "description": "Referral-code lookup and permanent engine-owned wallet attribution." }, { "name": "TEE API Wallets", "description": "Allocate a TEE-controlled HyperLiquid API wallet and submit the account manager's EIP-712 approval." }, { "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." } ] }