{ "openapi": "3.0.3", "info": { "title": "Ondo Perps REST API", "version": "1.0", "description": "REST API for Ondo Perps: account, wallet, deposits/withdrawals, API keys, and perpetual futures trading." }, "servers": [ { "url": "https://api.ondoperps.xyz" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/status": { "get": { "summary": "Get Status", "security": [], "description": "Returns public API and system status.", "operationId": "getStatus", "tags": [ "Tool" ], "responses": { "200": { "description": "Status response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/StatusResult" } } } ] }, "example": { "success": true, "result": { "marketStatus": "open" } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/hello": { "get": { "summary": "Hello", "security": [], "description": "Simple health check. Returns a static JSON payload.", "operationId": "hello", "tags": [ "Tool" ], "responses": { "200": { "description": "Hello response", "content": { "application/json": { "schema": { "type": "object", "properties": { "hello": { "type": "string", "example": "world" } } }, "example": { "hello": "world" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/account": { "get": { "summary": "Get Account", "description": "Returns account information for the authenticated user.", "operationId": "getAccount", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Account info", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AccountInfo" } } } ] }, "example": { "success": true, "result": { "accountID": "10458932786832481", "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "authType": "web3", "accountState": "open", "withdrawalFeeUSD": "1", "disabledFunctionality": { "disableTransfers": false, "disableWallet": false, "disableBalance": false, "disablePerps": false, "disableAPIKeys": false, "disableSubaccounts": true, "disableNetworkLink": true, "disableReferrals": true, "disableAlphaStrategies": true, "disableAlphaStrategiesCreation": true, "disableWalletLogins": true, "disableChat": true, "disableMAC": true, "disableBasisTradeAccounts": true }, "termsVersion": 2, "termsUnixSecs": 1704067200, "privacyVersion": 1, "privacyUnixSecs": 1704067200, "marketingConsent": "accepted", "subaccountsLimit": 256, "cooldownPeriodSecs": 0, "pointsState": 0 } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/auth/erc-4361/login/get_challenge": { "post": { "summary": "Get SIWE Login Challenge", "security": [], "description": "Get a Sign-In with Ethereum (ERC-4361) challenge for login.", "operationId": "getSIWEChallenge", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginGetChallengeRequest" } } } }, "responses": { "200": { "description": "Challenge message for signing", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AuthChallengeResult" } } } ] }, "example": { "success": true, "result": { "id": "chg_9f8e7d6c5b4a3210", "message": "api.ondoperps.xyz wants you to sign in with your Ethereum account:\n0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18\n\nSign in to Ondo Perps\n\nURI: https://api.ondoperps.xyz\nVersion: 1\nChain ID: 1\nNonce: abc123\nIssued At: 2025-03-05T14:30:00Z" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "challenge_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "challenge_not_found" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/auth/erc-4361/login/complete_challenge": { "post": { "summary": "Complete SIWE Login", "security": [], "description": "Complete Sign-In with Ethereum by submitting the signed challenge. Returns JWT.", "operationId": "completeSIWEChallenge", "tags": [ "Auth" ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LoginCompleteChallengeRequest" } } } }, "responses": { "200": { "description": "Auth token", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AuthToken" } } } ] }, "example": { "success": true, "result": { "identifier": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "authType": "web3", "accountId": "10458932786832481", "issuedAtSecs": 1709648400, "expirationSecs": 1709734800, "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9...", "newAccount": false } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_cannot_be_verified", "challenge_not_found", "invite_code_already_used", "invite_code_invalid" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_cannot_be_verified" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/auth/erc-4361/address_book/get_challenge": { "post": { "summary": "Get SIWE Address Book Challenge", "description": "Get a Sign-In with Ethereum challenge for adding a withdrawal address.", "operationId": "getSIWEAddressBookChallenge", "tags": [ "Auth" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookGetChallengeRequest" } } } }, "responses": { "200": { "description": "Challenge for signing", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AuthChallengeResult" } } } ] }, "example": { "success": true, "result": { "id": "chg_ab12cd34ef56", "message": "Sign this message to add withdrawal address 0x054A94b753CBf65D1Bc484F6D41897b48251fbfF to your address book." } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/auth/erc-4361/address_book/complete_challenge": { "post": { "summary": "Complete SIWE Address Book Challenge", "description": "Complete the signed challenge to add a withdrawal address.", "operationId": "completeSIWEAddressBookChallenge", "tags": [ "Auth" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddressBookCompleteChallengeRequest" } } } }, "responses": { "200": { "description": "Result", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found", "bad_label", "bad_withdrawal_address", "challenge_not_found", "empty_label", "internal_withdrawal_address", "withdrawal_address_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/auth/invalidate_jwt": { "get": { "summary": "Invalidate JWT", "description": "Invalidates all JWTs for the authenticated account.", "operationId": "invalidateJWT", "tags": [ "Auth" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/markets": { "get": { "summary": "Get Markets", "security": [], "description": "Returns available trading markets. For the list of supported markets, see [Markets](/markets).\n\nIf called with authentication, some fields are updated to reflect account-specific values.", "operationId": "getMarkets", "tags": [ "Markets" ], "responses": { "200": { "description": "Markets response", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/MarketsResult" } } } ] }, "example": { "success": true, "result": { "perps": { "tradingPairs": [ { "market": "AAPL-USD.P", "baseIncrement": "0.01", "quoteIncrement": "0.01" } ] }, "tokenConfig": [ { "id": "USDC", "name": "USD Coin", "decimals": 2, "tokenDecimals": 6, "networks": {} } ] } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/sandbox_deposit": { "post": { "summary": "Sandbox Deposit", "description": "Credits the account with funds in sandbox environment only.", "operationId": "sandboxDeposit", "tags": [ "Sandbox" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxDepositRequest" } } } }, "responses": { "200": { "description": "Deposit result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/SandboxDepositResult" } } } ] }, "example": { "success": true, "result": { "deposit_address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "txn_hash": "0xabc123def456..." } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_network", "invalid_symbol" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_network" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/sandbox_withdrawal": { "post": { "summary": "Sandbox Withdrawal", "description": "Debits the account in sandbox environment only.", "operationId": "sandboxWithdrawal", "tags": [ "Sandbox" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SandboxWithdrawalRequest" } } } }, "responses": { "200": { "description": "Withdrawal result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WithdrawalResult" } } } ] }, "example": { "success": true, "result": { "withdrawal_status": "pending", "withdrawal_id": "w_9f8e7d6c5b4a3210", "customer_withdrawal_id": "my-withdrawal-001" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_withdrawal_address", "insufficient_funds", "internal_withdrawal_address", "invalid_network", "invalid_symbol", "invalid_withdrawal_network", "transfer_amount_precision_overflow", "withdrawal_address_not_found", "withdrawal_amount_too_small", "withdrawal_duplicate_customer_withdrawal_id", "withdrawal_error_insufficient_balance", "withdrawal_failed", "withdrawal_invalid_amount", "withdrawal_limit_exceeded", "withdrawal_missing_customer_withdrawal_id", "withdrawal_system_error", "withdrawal_try_later" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_withdrawal_address" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/withdraw": { "post": { "summary": "Withdraw", "description": "Submit a withdrawal request. Rate limited per account. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "withdraw", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "customer_withdrawal_id", "symbol", "network", "amount", "address" ], "properties": { "customer_withdrawal_id": { "type": "string", "description": "Unique ID for this withdrawal" }, "symbol": { "type": "string", "description": "Coin to withdraw (e.g. USDC, SOL)" }, "network": { "type": "string", "description": "Target network (e.g. ethereum, solana)", "enum": [ "avalanche", "ethereum", "solana" ] }, "amount": { "type": "string", "description": "Amount to withdraw" }, "address": { "type": "string", "description": "Withdrawal destination address" }, "from": { "$ref": "#/components/schemas/AccountWalletKey" } } } } } }, "responses": { "200": { "description": "Withdrawal result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WithdrawalResult" } } } ] }, "example": { "success": true, "result": { "withdrawal_status": "pending", "withdrawal_id": "w_9f8e7d6c5b4a3210", "customer_withdrawal_id": "my-withdrawal-001" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_withdrawal_address", "insufficient_funds", "internal_withdrawal_address", "invalid_network", "invalid_symbol", "invalid_withdrawal_network", "service_unavailable", "transfer_amount_precision_overflow", "withdrawal_address_not_found", "withdrawal_amount_too_small", "withdrawal_duplicate_customer_withdrawal_id", "withdrawal_error_insufficient_balance", "withdrawal_failed", "withdrawal_invalid_amount", "withdrawal_limit_exceeded", "withdrawal_missing_customer_withdrawal_id", "withdrawal_system_error", "withdrawal_try_later" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_withdrawal_address" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/provision_address": { "post": { "summary": "Provision Deposit Address", "description": "Provision a new deposit address for a given symbol/chain. For supported assets and deposit steps, see [Funding Ondo Perps](/funding-ondo-perps).", "operationId": "provisionAddress", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProvisionAddressRequest" } } } }, "responses": { "200": { "description": "Provisioned address", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ProvisionAddressResult" } } } ] }, "example": { "success": true, "result": { "chain": "ethereum", "accountId": "10458932786832481", "symbol": "USDC", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_network", "invalid_symbol" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_network" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/get_withdrawal_status": { "post": { "summary": "Get Withdrawal Status", "description": "Get status of one or more withdrawals. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "getWithdrawalStatus", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetWithdrawalStatusRequest" } } } }, "responses": { "200": { "description": "Withdrawal status result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WithdrawalStatusResult" } } } ] }, "example": { "success": true, "result": { "original_request": { "account_id": "10458932786832481", "customer_withdrawal_id": "my-withdrawal-001", "symbol": "USDC", "amount": "100.00", "address": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "network": "ethereum" }, "withdrawal_id": "w_9f8e7d6c5b4a3210", "txid": "0xabc123...", "confirmation_number": 12, "withdrawal_status": "complete" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/deposits": { "get": { "summary": "List Deposits", "description": "Returns deposit history for the authenticated account. For supported assets and deposit steps, see [Funding Ondo Perps](/funding-ondo-perps).", "operationId": "listDeposits", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of deposits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WalletDeposit" } } } } ] }, "example": { "success": true, "result": [ { "coin": "USDC", "size": "1000.00", "status": "confirmed", "txid": "0xabc123...", "fromAddress": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "time": "2025-01-15T10:30:00Z", "currentConfirmations": 64, "requiredConfirmations": 64, "chainId": "1", "usdValue": "1000.00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/deposits/{depositID}": { "get": { "summary": "Get Deposit by ID", "description": "Returns a single deposit by transaction ID. For supported assets and deposit steps, see [Funding Ondo Perps](/funding-ondo-perps).", "operationId": "getDepositById", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "depositID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deposit", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WalletDeposit" } } } ] }, "example": { "success": true, "result": { "coin": "USDC", "size": "1000.00", "status": "confirmed", "txid": "0xabc123...", "fromAddress": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "time": "2025-01-15T10:30:00Z", "currentConfirmations": 64, "requiredConfirmations": 64, "chainId": "1", "usdValue": "1000.00" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "deposit_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "deposit_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/withdrawals": { "get": { "summary": "List Withdrawals", "description": "Returns withdrawal history for the authenticated account. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "listWithdrawals", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of withdrawals", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/WalletWithdrawal" } } } } ] }, "example": { "success": true, "result": [ { "coin": "USDC", "size": "500.00", "status": "complete", "address": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "withdrawal_id": "w_9f8e7d6c5b4a3210", "txid": "0xdef456...", "customer_withdrawal_id": "my-withdrawal-001", "time": "2025-02-20T15:45:00Z", "usdValue": "500.00", "usdFee": "0.00", "chainId": "1", "from": { "id": "10458932786832481", "wallet": "margin" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/withdrawals/limit": { "get": { "summary": "Get Withdrawal Limits", "description": "Returns withdrawal limits for the authenticated account. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "getWithdrawalLimits", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Withdrawal limits", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WithdrawalLimits" } } } ] }, "example": { "success": true, "result": { "currentWithdrawalsUsd": "500.00", "withdrawalLimitUsd": "50000.00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/withdrawals/{withdrawalID}": { "get": { "summary": "Get Withdrawal by ID", "description": "Returns a single withdrawal by transaction ID. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "getWithdrawalById", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "withdrawalID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Withdrawal", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/WalletWithdrawal" } } } ] }, "example": { "success": true, "result": { "coin": "USDC", "size": "500.00", "status": "complete", "address": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "withdrawal_id": "w_9f8e7d6c5b4a3210", "txid": "0xdef456...", "customer_withdrawal_id": "my-withdrawal-001", "time": "2025-02-20T15:45:00Z", "usdValue": "500.00", "usdFee": "0.00", "chainId": "1", "from": { "id": "10458932786832481", "wallet": "margin" } } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "withdrawal_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "withdrawal_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/deposit_address/list": { "post": { "summary": "List Deposit Addresses", "description": "Returns the list of deposit addresses for the account. For supported assets and deposit steps, see [Funding Ondo Perps](/funding-ondo-perps).", "operationId": "listDepositAddresses", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DepositAddressListRequest" } } } }, "responses": { "200": { "description": "List of deposit addresses", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/DepositAddress" } } } } ] }, "example": { "success": true, "result": [ { "coin": "USDC", "network": "ethereum", "address": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18", "depositDestination": { "id": "10458932786832481", "wallet": "margin" } } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_network", "invalid_symbol", "too_few_items" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_network" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/deposits/csv": { "post": { "summary": "Export Deposits CSV", "description": "Exports the account's deposit history as a downloadable CSV for the given time range. Columns: `id`, `time` (RFC 3339, UTC), `coin`, `size`, `status`. For supported assets and deposit steps, see [Funding Ondo Perps](/funding-ondo-perps).", "operationId": "exportDepositsCsv", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnixTimeRangeRequest" } } } }, "responses": { "200": { "description": "CSV file of deposits for the requested time range.", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV text with a header row followed by one row per deposit." }, "example": "id,time,coin,size,status\n0xabc123...,2025-01-15T10:30:00Z,USDC,1000.00,confirmed\n0x9f8e7d...,2025-01-10T08:05:00Z,USDC,250.00,confirmed\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/withdrawals/csv": { "post": { "summary": "Export Withdrawals CSV", "description": "Exports the account's withdrawal history as a downloadable CSV for the given time range. Columns: `time` (RFC 3339, UTC), `coin`, `size`, `address`, `status`. For the withdrawal process and timing, see [Withdrawals](/withdrawals).", "operationId": "exportWithdrawalsCsv", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UnixTimeRangeRequest" } } } }, "responses": { "200": { "description": "CSV file of withdrawals for the requested time range.", "content": { "text/csv": { "schema": { "type": "string", "description": "CSV text with a header row followed by one row per withdrawal." }, "example": "time,coin,size,address,status\n2025-02-20T15:45:00Z,USDC,500.00,0x054A94b753CBf65D1Bc484F6D41897b48251fbfF,complete\n2025-02-18T11:20:00Z,USDC,750.00,0x054A94b753CBf65D1Bc484F6D41897b48251fbfF,pending\n" } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/wallet/address_book": { "get": { "summary": "Get Address Book", "description": "Returns withdrawal address book entries for the authenticated account.", "operationId": "getAddressBook", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Address book", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/AddressBookResult" } } } ] }, "example": { "success": true, "result": { "addressBook": [ { "withdrawalAddress": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF", "label": "My Ledger", "lastUpdated": "2025-01-10T08:00:00Z" } ] } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "put": { "summary": "Edit Address Book Entry", "description": "Update label for a withdrawal address.", "operationId": "editAddressBookEntry", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/EditWithdrawalAddressRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found", "bad_label", "empty_label", "withdrawal_address_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Remove Address Book Entry", "description": "Remove a withdrawal address from the address book.", "operationId": "deleteAddressBookEntry", "tags": [ "Wallet" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/DeleteWithdrawalAddressRequest" } } } }, "responses": { "200": { "description": "Removed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found", "withdrawal_address_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api_keys": { "get": { "summary": "List API Keys", "description": "Returns API keys for the authenticated account.", "operationId": "listApiKeys", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of API keys", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyInfo" } } } } ] }, "example": { "success": true, "result": [ { "keyId": "ondoKeyId_abc123", "name": "Trading Bot", "createdAt": "2025-01-01T00:00:00Z", "scopes": [ "trade", "transfer" ], "whitelistedIPs": [ "192.168.1.1" ] } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Create API Key", "description": "Create a new API key. The secret is returned only once.", "operationId": "createApiKey", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeysCreateRequest" } } } }, "responses": { "200": { "description": "Created API key (includes secret)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiKeyCreateResult" } } } ] }, "example": { "success": true, "result": { "keyId": "ondoKeyId_abc123", "name": "Trading Bot", "createdAt": "2025-01-01T00:00:00Z", "scopes": [ "trade", "transfer" ], "secretKey": "ondoApiSecret_abc123def456ghi789..." } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api_keys/{apiKeyID}": { "delete": { "summary": "Delete API Key", "description": "Delete an API key by ID.", "operationId": "deleteApiKey", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "apiKeyID", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Deleted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "api_key_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "api_key_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/api_keys/{apiKeyID}/ip_whitelist": { "post": { "summary": "Set API Key IP Whitelist", "description": "Set or update IP whitelist for an API key.", "operationId": "setApiKeyIpWhitelist", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "apiKeyID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ApiKeyWhitelistRequest" } } } }, "responses": { "200": { "description": "Updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "api_key_not_found", "too_many_ips" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "api_key_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Remove API Key IP Whitelist Entry", "description": "Remove an IP address from the whitelist for an API key.", "operationId": "deleteApiKeyIpWhitelist", "tags": [ "API Keys" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "apiKeyID", "in": "path", "required": true, "schema": { "type": "string" } } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "type": "string", "description": "IP address to remove from the whitelist" } } } } } }, "responses": { "200": { "description": "IP removed from whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "api_key_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "api_key_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/counts/orders": { "get": { "summary": "Get Open Order Counts", "description": "Returns open order counts per market/product for the authenticated account.", "operationId": "getOrderCounts", "tags": [ "Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Order counts", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/OpenOrderCounts" } } } ] }, "example": { "success": true, "result": { "spot": { "open": 0 }, "perps": { "open": 3 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders": { "post": { "summary": "Create Order", "description": "Creates a limit or market order. Change the \"type\" field to switch between order types. If `postOnly` is `true` and an order would match at placement, a 400 is returned with error `post_only_has_match`. For the available order types and their behavior, see [Order types](/order-types).", "operationId": "createOrder", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AddOrderReq" }, "example": { "clientOrderId": "order123", "market": "AAPL-USD.P", "price": "1.55", "side": "buy", "size": "20.30" } } } }, "responses": { "200": { "description": "Created order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiOrder" } } } ] }, "example": { "success": true, "result": { "orderId": "197ec08e001658690721be129e7fa595", "clientOrderId": "order123", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "0.00", "lastFillSize": "0.00", "filledCost": "0.00", "fee": "0.00", "status": "open", "createdAt": "2025-03-05T14:30:00Z", "type": "limit", "timeInForce": "GTC", "reduceOnly": false } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_in_liquidation", "clientOrderID_chars_invalid", "clientOrderID_collision", "clientOrderID_length_invalid", "deprecated_field", "insufficient_funds", "insufficient_liquidity", "insufficient_margin", "invalid_market", "invalid_market_order_fields", "invalid_order_type", "invalid_stop_order", "invalid_time_in_force", "mark_price_not_available", "market_orders_disabled", "must_use_delayed_path", "net_position_too_large", "order_invalid_price", "order_invalid_size", "order_matches_against_self", "order_negative_price", "order_negative_size", "order_price_outside_min_max_bounds", "order_price_outside_safe_bounds", "post_only_has_match", "price_over_ui_limit_10MM", "redirect", "reduce_only_flipping_position", "reduce_only_increasing_position", "reduce_only_invalid_tif", "reduce_only_no_open_position", "stop_order_crosses_mark_price", "stop_order_crosses_order_price", "stop_order_trigger_price_exceeds_max", "stop_order_trigger_price_invalid_increment", "stop_order_trigger_price_negative", "too_many_open_orders", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_in_liquidation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "get": { "summary": "Get Orders", "description": "Returns a paginated list of orders matching the given parameters.", "operationId": "getOrders", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 1000 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "market", "in": "query", "description": "Filter by trading market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "status", "in": "query", "description": "Filter by order status", "required": false, "schema": { "type": "string", "enum": [ "open", "canceled", "fullyfilled" ], "example": "open" } }, { "name": "startTime", "in": "query", "description": "Filter orders placed at or after this time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "Filter orders placed at or before this time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of orders, reverse chronological", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiOrder" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "orderId": "197ec08e001658690721be129e7fa595", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "5.00", "lastFillSize": "2.50", "filledCost": "1137.50", "fee": "0.57", "status": "open", "createdAt": "2025-03-05T14:30:00Z", "type": "limit", "timeInForce": "GTC", "reduceOnly": false } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====", "prevCursor": "O4ZTGM3RGM2DG===" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor", "invalid_market" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Cancel All Orders", "description": "Cancels all orders for the authenticated user. Optionally restricted to a single market.\n", "operationId": "cancelAllOrders", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "If specified, only cancel orders for this market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } } ], "responses": { "200": { "description": "Orders cancelled successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders/batch": { "post": { "summary": "Create Batched Orders", "description": "Creates multiple orders in a single API call. Some orders may succeed while others fail. The response code is 2XX as long as there is no internal server error. Returns 400 with `error_code=batch_order_empty` if the `orders` array is empty. Returns 400 with `error_code=batch_order_too_many_orders` if too many orders are provided (max 20). For the available order types and their behavior, see [Order types](/order-types).", "operationId": "createBatchOrders", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAddOrderReq" } } } }, "responses": { "200": { "description": "Batch order result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/BatchAddOrderRes" } } } ] }, "example": { "success": true, "result": { "addedOrders": [ { "orderId": "197ec08e001658690721be129e7fa595", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "0.00", "lastFillSize": "0.00", "filledCost": "0.00", "fee": "0.00", "status": "open", "createdAt": "2025-03-05T14:30:00Z", "type": "limit" } ], "failedOrders": [] } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_in_liquidation", "batch_order_empty", "batch_order_too_many_orders", "clientOrderID_chars_invalid", "clientOrderID_collision", "clientOrderID_length_invalid", "deprecated_field", "insufficient_funds", "insufficient_liquidity", "insufficient_margin", "invalid_market", "invalid_market_order_fields", "invalid_order_type", "invalid_stop_order", "invalid_time_in_force", "mark_price_not_available", "market_orders_disabled", "net_position_too_large", "order_invalid_price", "order_invalid_size", "order_matches_against_self", "order_negative_price", "order_negative_size", "order_price_outside_min_max_bounds", "order_price_outside_safe_bounds", "post_only_has_match", "price_over_ui_limit_10MM", "redirect", "reduce_only_flipping_position", "reduce_only_increasing_position", "reduce_only_invalid_tif", "reduce_only_no_open_position", "stop_order_crosses_mark_price", "stop_order_crosses_order_price", "stop_order_trigger_price_exceeds_max", "stop_order_trigger_price_invalid_increment", "stop_order_trigger_price_negative", "too_many_open_orders", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_in_liquidation" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Batch Cancel Orders", "description": "Cancels multiple orders in a single call. Returns results for each order. Provide a comma-separated list of order IDs via the `orderIDs` query parameter. Each entry can be an internal order ID or `client:{clientOrderID}`.\n", "operationId": "batchCancelOrders", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderIDs", "in": "query", "description": "Comma-separated list of order IDs to cancel", "required": true, "schema": { "type": "string", "example": "abc123,def456" } } ], "responses": { "200": { "description": "Batch cancel result", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/BatchCancelResult" } } } ] }, "example": { "success": true, "result": { "successfulCancels": [ { "orderId": "197ec08e001658690721be129e7fa595", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "0.00", "lastFillSize": "0.00", "filledCost": "0.00", "fee": "0.00", "status": "canceled", "createdAt": "2025-03-05T14:30:00Z", "canceledAt": "2025-03-05T14:35:00Z", "type": "limit" } ], "failedCancels": [] } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "batch_cancel_empty", "batch_cancel_too_many_orders", "order_already_canceled", "order_already_fully_filled", "order_not_found", "order_not_in_cancelable_state", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "batch_cancel_empty" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/twap/order": { "post": { "summary": "Create TWAP Order", "description": "Creates a new TWAP (Time-Weighted Average Price) order. The order is split into child orders placed at regular intervals over the specified running time. Running time must be between 5 minutes and 24 hours and a multiple of the frequency. The number of child orders (runningTime / frequency) must be between 2 and 200. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "createTWAPOrder", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateTWAPOrderReq" } } } }, "responses": { "200": { "description": "Created TWAP order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/TWAPOrderApiResp" } } } ] }, "example": { "success": true, "result": { "twapId": "twap_70a37d8f972f2494837f9dba8364cbb4", "market": "AAPL-USD.P", "side": "buy", "startTime": "2025-03-05T14:00:00Z", "runningTime": 3600, "frequency": 60, "avgFilledPrice": "0.00", "filledSize": "0.00", "totalSize": "20.00", "totalFees": "0.00", "orderStatus": "running", "reduceOnly": false } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "feature_disabled", "invalid_market", "invalid_twap_order_request", "too_many_twap_orders" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "feature_disabled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/twap/order/{orderID}": { "get": { "summary": "Get TWAP Order by ID", "description": "Returns a single TWAP order by its ID. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "getTWAPOrderByID", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "TWAP order ID (prefixed with `twap_`)", "required": true, "schema": { "type": "string", "example": "twap_70a37d8f972f2494837f9dba8364cbb4" } } ], "responses": { "200": { "description": "TWAP order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/TWAPOrderApiResp" } } } ] }, "example": { "success": true, "result": { "twapId": "twap_70a37d8f972f2494837f9dba8364cbb4", "market": "AAPL-USD.P", "side": "buy", "startTime": "2025-03-05T14:00:00Z", "runningTime": 3600, "frequency": 60, "avgFilledPrice": "227.42", "filledSize": "10.00", "totalSize": "20.00", "totalFees": "1.14", "orderStatus": "running", "reduceOnly": false, "successfulOrders": 30, "failedOrders": 0 } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "feature_disabled", "invalid_twap_order_id", "missing_twap_order_id", "twap_order_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "feature_disabled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Cancel TWAP Order", "description": "Cancels a running TWAP order. Child orders already placed are not affected. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "cancelTWAPOrder", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "TWAP order ID (prefixed with `twap_`)", "required": true, "schema": { "type": "string", "example": "twap_70a37d8f972f2494837f9dba8364cbb4" } } ], "responses": { "200": { "description": "TWAP order cancelled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "feature_disabled", "invalid_twap_order_id", "missing_twap_order_id", "twap_order_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "feature_disabled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/twap/order/{orderID}/fills": { "get": { "summary": "Get TWAP Order Fills", "description": "Returns all fills for all child orders of a TWAP order. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "getTWAPOrderFills", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "TWAP order ID (prefixed with `twap_`)", "required": true, "schema": { "type": "string", "example": "twap_70a37d8f972f2494837f9dba8364cbb4" } } ], "responses": { "200": { "description": "List of fills for all child orders", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiFill" } } } } ] }, "example": { "success": true, "result": [ { "id": "70a37d8f972f2494837f9dba8364cbb4", "orderId": "child_abc123", "parentOrderID": "twap_70a37d8f972f2494837f9dba8364cbb4", "market": "AAPL-USD.P", "price": "227.50", "size": "0.33", "side": "buy", "filledCost": "75.08", "fee": "0.04", "time": "2025-03-05T14:01:00Z", "isMaker": false } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "feature_disabled", "invalid_twap_order_id", "missing_twap_order_id", "twap_order_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "feature_disabled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/twap/orders/running": { "get": { "summary": "Get Running TWAP Orders", "description": "Returns all currently running TWAP orders for the authenticated account. Optionally filter by market. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "getTWAPRunningOrders", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } } ], "responses": { "200": { "description": "Array of running TWAP orders", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/TWAPOrderApiResp" } } } } ] }, "example": { "success": true, "result": [ { "twapId": "twap_70a37d8f972f2494837f9dba8364cbb4", "market": "AAPL-USD.P", "side": "buy", "startTime": "2025-03-05T14:00:00Z", "runningTime": 3600, "frequency": 60, "avgFilledPrice": "227.42", "filledSize": "10.00", "totalSize": "20.00", "totalFees": "1.14", "orderStatus": "running", "reduceOnly": false, "successfulOrders": 30, "failedOrders": 0 } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "feature_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/twap/orders/history": { "get": { "summary": "Get TWAP Order History", "description": "Returns a paginated list of completed or cancelled TWAP orders for the authenticated account. For how TWAP execution works, see [TWAP orders](/time-weighted-average-price).", "operationId": "getTWAPOrderHistory", "tags": [ "TWAP Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 100 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "startTime", "in": "query", "description": "Start time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "End time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of TWAP orders", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/TWAPOrderApiResp" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "twapId": "twap_70a37d8f972f2494837f9dba8364cbb4", "market": "AAPL-USD.P", "side": "buy", "startTime": "2025-03-05T14:00:00Z", "finishTime": "2025-03-05T15:00:00Z", "runningTime": 3600, "frequency": 60, "avgFilledPrice": "227.42", "filledSize": "20.00", "totalSize": "20.00", "totalFees": "2.27", "orderStatus": "completed", "reduceOnly": false, "successfulOrders": 60, "failedOrders": 0 } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "feature_disabled", "invalid_cursor" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders/{orderID}": { "get": { "summary": "Get Order by ID", "description": "Gets an individual order by order ID. The `orderID` path parameter can be:\n\n- An internal order ID (e.g. `197ec08e001658690721be129e7fa595`).\n- A client order ID prefixed with `client:` (e.g. `client:abc123`).\n", "operationId": "getOrderByID", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "Internal order ID, or `client:{clientOrderID}` for client order ID lookup", "required": true, "schema": { "type": "string", "example": "197ec08e001658690721be129e7fa595" } } ], "responses": { "200": { "description": "Order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiOrder" } } } ] }, "example": { "success": true, "result": { "orderId": "197ec08e001658690721be129e7fa595", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "10.00", "lastFillSize": "5.00", "filledCost": "2275.00", "fee": "1.14", "status": "fullyfilled", "createdAt": "2025-03-05T14:30:00Z", "filledAt": "2025-03-05T14:30:05Z", "type": "limit", "timeInForce": "GTC", "reduceOnly": false } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "order_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "order_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Cancel Order by ID", "description": "Cancels an individual order by order ID. The `orderID` path parameter can be:\n\n- An internal order ID (e.g. `197ec08e001658690721be129e7fa595`).\n- A client order ID prefixed with `client:` (e.g. `client:abc123`).\n\nReturns a 400 with error code `order_already_cancelled`, `order_not_in_cancellable_state`, or `order_already_filled` if the order cannot be cancelled.\n", "operationId": "cancelOrderByID", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "Internal order ID, or `client:{clientOrderID}` for client order ID lookup", "required": true, "schema": { "type": "string", "example": "197ec08e001658690721be129e7fa595" } } ], "responses": { "200": { "description": "Cancelled order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiOrder" } } } ] }, "example": { "success": true, "result": { "orderId": "197ec08e001658690721be129e7fa595", "side": "buy", "price": "227.50", "size": "10.00", "market": "AAPL-USD.P", "filledSize": "0.00", "lastFillSize": "0.00", "filledCost": "0.00", "fee": "0.00", "status": "canceled", "createdAt": "2025-03-05T14:30:00Z", "canceledAt": "2025-03-05T14:35:00Z", "type": "limit" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "order_already_canceled", "order_already_fully_filled", "order_not_found", "order_not_in_cancelable_state", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "order_already_canceled" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders/csv": { "get": { "summary": "Get Orders CSV", "description": "Export filled orders as CSV, sorted reverse chronologically.", "operationId": "getOrdersCSV", "tags": [ "Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by trading market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "status", "in": "query", "description": "Filter by order status", "required": false, "schema": { "type": "string", "example": "open" } }, { "name": "startTime", "in": "query", "description": "Filter by start time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "Filter by end time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "CSV formatted orders", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/fills": { "get": { "summary": "Get Fills", "description": "Returns a paginated list of fills for the authenticated account.", "operationId": "getFills", "tags": [ "Fills" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by trading market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 1000 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "startTime", "in": "query", "description": "Filter by start time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "Filter by end time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of fills, most recent first", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiFill" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "id": "70a37d8f972f2494837f9dba8364cbb4", "orderId": "197ec08e001658690721be129e7fa595", "market": "AAPL-USD.P", "price": "227.50", "size": "5.00", "side": "buy", "direction": "open long", "filledCost": "1137.50", "fee": "0.57", "time": "2025-03-05T14:30:00Z", "isMaker": false } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders/{orderID}/fills": { "get": { "summary": "Get Fills by Order ID", "description": "Returns all fills for a given order. The `orderID` path parameter can be:\n\n- An internal order ID (e.g. `197ec08e001658690721be129e7fa595`).\n- A client order ID prefixed with `client:` (e.g. `client:abc123`).\n", "operationId": "getFillsByOrderID", "tags": [ "Fills" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "orderID", "in": "path", "description": "Internal order ID, or `client:{clientOrderID}` for client order ID lookup", "required": true, "schema": { "type": "string", "example": "197ec08e001658690721be129e7fa595" } } ], "responses": { "200": { "description": "List of fills for the order", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiFill" } } } } ] }, "example": { "success": true, "result": [ { "id": "70a37d8f972f2494837f9dba8364cbb4", "orderId": "197ec08e001658690721be129e7fa595", "market": "AAPL-USD.P", "price": "227.50", "size": "5.00", "side": "buy", "direction": "open long", "filledCost": "1137.50", "fee": "0.57", "time": "2025-03-05T14:30:00Z", "isMaker": true } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "order_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "order_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/fills/csv": { "get": { "summary": "Get Fills CSV", "description": "Export fills as CSV, sorted reverse chronologically.", "operationId": "getFillsCSV", "tags": [ "Fills" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by trading market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "startTime", "in": "query", "description": "Filter by start time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "Filter by end time (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "CSV formatted fills", "content": { "text/csv": { "schema": { "type": "string" } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/trades": { "get": { "summary": "Get Trades", "security": [], "description": "Returns a paginated list of public trades for a market.", "operationId": "getTrades", "tags": [ "Market Data" ], "parameters": [ { "name": "market", "in": "query", "description": "Trading market to query", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 100 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } } ], "responses": { "200": { "description": "Paginated list of trades, most recent first", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiTrade" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "price": "227.50", "size": "5.00", "cost": "1137.50", "aggressor_side": "buy", "time": "2025-03-05T14:30:00Z", "id": "70a37d8f972f2494837f9dba8364cbb4" } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/depth": { "get": { "summary": "Get Order Book Depth", "security": [ {}, { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Returns the current order book depth snapshot for a market.", "operationId": "getDepth", "tags": [ "Market Data" ], "parameters": [ { "name": "market", "in": "query", "description": "Trading market to query", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "depth", "in": "query", "description": "Number of price levels to return per side. Defaults to 10. Maximum 100.", "required": false, "schema": { "type": "integer", "example": 10, "maximum": 100 } } ], "responses": { "200": { "description": "Order book snapshot", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiBookSnapshot" } } } ] }, "example": { "success": true, "result": { "market": "AAPL-USD.P", "time": "2025-03-05T14:30:00Z", "bids": [ [ "227.40", "100.0" ], [ "227.30", "250.0" ] ], "asks": [ [ "227.60", "80.0" ], [ "227.70", "150.0" ] ] } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_market", "invalid_symbol" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_market" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/candles": { "get": { "summary": "Get Candles", "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Returns OHLCV candlestick data for a perpetual futures market as an array of objects, each with the full field names `startTime`, `open`, `high`, `low`, `close`, and `volume` (values are strings). If you need the TradingView UDF format instead (parallel `o`/`h`/`l`/`c`/`v` arrays of numbers), use `GET /v1/perps/history` (Get Price History).", "operationId": "getPerpsCandles", "tags": [ "Market Data" ], "parameters": [ { "name": "market", "in": "query", "description": "Perps trading market", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "resolution", "in": "query", "description": "Bar resolution. If the string has no \"D\", \"W\", or \"M\" suffix it is interpreted as minutes (e.g. 1, 5, 15, 30, 60, 240). Use suffixes for daily (e.g. 1D), weekly (1W), or monthly (1M).", "required": true, "schema": { "type": "string", "example": "1" } }, { "name": "from", "in": "query", "description": "Start of the requested time range (Unix timestamp in seconds)", "required": true, "schema": { "type": "integer", "example": 1684814400 } }, { "name": "to", "in": "query", "description": "End of the requested time range (Unix timestamp in seconds)", "required": true, "schema": { "type": "integer", "example": 1684900800 } } ], "responses": { "200": { "description": "Array of OHLCV candles", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiCandle" } } } } ] }, "example": { "success": true, "result": [ { "startTime": "2025-03-05T14:00:00Z", "open": "226.80", "high": "228.10", "low": "226.50", "close": "227.50", "volume": "12345.67" } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/symbol_info": { "get": { "summary": "Get Symbol Info (TradingView)", "security": [], "description": "Returns symbol metadata in TradingView UDF format. See https://www.tradingview.com/rest-api-spec/#operation/getSymbolInfo.", "operationId": "getPerpsSymbolInfo", "tags": [ "Market Data" ], "responses": { "200": { "description": "TradingView symbol info response", "content": { "application/json": { "schema": { "type": "object", "description": "TradingView UDF symbol info response. Contains arrays of values for each symbol.", "properties": { "s": { "type": "string", "description": "Status", "example": "ok" }, "symbol": { "type": "array", "items": { "type": "string" } }, "description": { "type": "array", "items": { "type": "string" } }, "ticker": { "type": "array", "items": { "type": "string" } }, "currency": { "type": "array", "items": { "type": "string" } }, "base-currency": { "type": "array", "items": { "type": "string" } }, "type": { "type": "array", "items": { "type": "string" } }, "session-regular": { "type": "array", "items": { "type": "string" } }, "timezone": { "type": "array", "items": { "type": "string" } }, "minmovement": { "type": "array", "items": { "type": "integer" } }, "pricescale": { "type": "array", "items": { "type": "integer" } }, "has-intraday": { "type": "array", "items": { "type": "boolean" } }, "has-no-volume": { "type": "array", "items": { "type": "boolean" } }, "supported-resolutions": { "type": "array", "items": { "type": "array", "items": { "type": "string" } } } } }, "example": { "s": "ok", "symbol": [ "AAPL-USD.P", "TSLA-USD.P" ], "description": [ "Apple Inc. Perpetual", "Tesla Inc. Perpetual" ], "ticker": [ "AAPL-USD.P", "TSLA-USD.P" ], "currency": [ "USDC", "USDC" ], "base-currency": [ "AAPL", "TSLA" ], "type": [ "perpetual", "perpetual" ], "session-regular": [ "24x7", "24x7" ], "timezone": [ "Etc/UTC", "Etc/UTC" ], "minmovement": [ 1, 1 ], "pricescale": [ 100, 100 ], "has-intraday": [ true, true ], "has-no-volume": [ false, false ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/history": { "get": { "summary": "Get Price History (TradingView)", "security": [], "description": "Returns historical bar data in TradingView UDF format, as required by the TradingView charting library: a single object with parallel arrays keyed `t`, `o`, `h`, `l`, `c`, and `v` (values are numbers), plus a status field `s`. For a standard array-of-objects representation with full field names (`open`, `high`, `low`, `close`, `volume`), use `GET /v1/perps/candles` (Get Candles).", "operationId": "getPerpsHistory", "tags": [ "Market Data" ], "parameters": [ { "name": "symbol", "in": "query", "description": "TradingView symbol identifier", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Bar resolution", "required": true, "schema": { "type": "string" } }, { "name": "from", "in": "query", "description": "Start Unix timestamp", "required": true, "schema": { "type": "integer" } }, { "name": "to", "in": "query", "description": "End Unix timestamp", "required": true, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "TradingView UDF history response", "content": { "application/json": { "schema": { "type": "object", "description": "TradingView UDF history response with parallel arrays of OHLCV data.", "properties": { "s": { "type": "string", "description": "Status ('ok' or 'no_data')", "example": "ok" }, "t": { "type": "array", "description": "Array of Unix timestamps", "items": { "type": "integer" } }, "o": { "type": "array", "description": "Array of open prices", "items": { "type": "number" } }, "h": { "type": "array", "description": "Array of high prices", "items": { "type": "number" } }, "l": { "type": "array", "description": "Array of low prices", "items": { "type": "number" } }, "c": { "type": "array", "description": "Array of close prices", "items": { "type": "number" } }, "v": { "type": "array", "description": "Array of volumes", "items": { "type": "number" } } } }, "example": { "s": "ok", "t": [ 1709640000, 1709643600 ], "o": [ 226.8, 227.5 ], "h": [ 228.1, 228.5 ], "l": [ 226.5, 227 ], "c": [ 227.5, 228 ], "v": [ 12345.67, 9876.54 ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/positions": { "get": { "summary": "Get Positions", "description": "Returns all open positions for the authenticated account. For how positions and balances work, see [Positions and balances](/positions-balances).", "operationId": "getPerpsPositions", "tags": [ "Positions" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of positions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiPosition" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "direction": "long", "netQuantity": "10.00", "averageEntryPrice": "225.00", "usedMargin": "1125.00", "unrealizedPnl": "25.00", "markPrice": "227.50", "liquidationPrice": "180.00", "bankruptcyPrice": "170.00", "maintenanceMargin": "112.50", "notionalValue": "2275.00", "leverage": "2.0", "netFundingSinceNeutral": "-1.23", "returnOnEquity": "0.022" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/balance": { "get": { "summary": "Get Balance", "description": "Get a summary of the balance for a margin account. For how positions and balances work, see [Positions and balances](/positions-balances).", "operationId": "getPerpsBalance", "tags": [ "Margin Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Margin account balance summary", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/MarginAccountBalanceSummary" } } } ] }, "example": { "success": true, "result": { "walletBalance": "5000.00", "realizedPnl": "250.00", "unrealizedPnl": "-50.00", "marginBalance": "4950.00", "usedMargin": "1125.00", "availableMargin": "3825.00", "withdrawableMargin": "3825.00", "maintenanceMarginRequirement": "112.50", "totalMaintenanceMargin": "200.00", "marginRatio": "0.04", "leverage": "0.46", "underLiquidation": false, "totalFundingPayments": "-5.67", "totalTradingFees": "12.34", "totalPnL": "232.00", "netInvested": "4750.00" } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/funding_rates": { "get": { "summary": "Get Funding Rates", "security": [], "description": "Get an estimate of the current-interval funding rate in a given market, as well as when the next funding is and what premium index measurements make up the funding rate. For how funding is calculated and applied, see [Funding rates](/funding-rates).", "operationId": "getFundingRates", "tags": [ "Funding Rate" ], "parameters": [ { "name": "market", "in": "query", "description": "Market to query", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } } ], "responses": { "200": { "description": "Current funding rate estimate", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/FundingRate" } } } ] }, "example": { "success": true, "result": { "market": "AAPL-USD.P", "rate": "0.0000125", "intervalEnds": "2025-03-05T16:00:00Z", "premiums": [ { "time": "2025-03-05T15:00:00Z", "premiumIndex": "0.000025" }, { "time": "2025-03-05T15:30:00Z", "premiumIndex": "0.000015" } ] } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/funding_rate_history": { "get": { "summary": "Get Funding Rate History", "security": [], "description": "Get the historical funding rates for a market. For how funding is calculated and applied, see [Funding rates](/funding-rates).", "operationId": "getFundingRateHistory", "tags": [ "Funding Rate" ], "parameters": [ { "name": "market", "in": "query", "description": "Perps trading market", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 1000 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "startTime", "in": "query", "description": "Start time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "End time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of historical funding rates, most recent first", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/FundingRateValue" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "time": "2025-03-05T12:00:00Z", "fundingRate": "0.0000125" } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor", "invalid_market" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/funding_fees": { "get": { "summary": "Get Funding Fee Payments", "description": "Get a paginated history of funding fee payments for the authenticated account. For how funding is calculated and applied, see [Funding rates](/funding-rates).", "operationId": "getFundingFees", "tags": [ "Funding Rate" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Trading market to filter by", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 1000 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "startTime", "in": "query", "description": "Start time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "End time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of funding fee payments, most recent first", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/FundingFeeTransfer" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "time": "2025-03-05T12:00:00Z", "markPrice": "227.50", "positionSize": "10.00", "positionDirection": "long", "rate": "0.0000125", "payer": "long", "amount": "-0.02844" } ], "pageInfo": { "nextCursor": "NQ5WWO3THN3Q====" } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/mark_prices": { "get": { "summary": "Get Mark Prices", "security": [], "description": "Get the current mark prices for all perpetual futures markets. For how mark prices are derived, see [External pricing derivations](/pricing-derivations).", "operationId": "getMarkPrices", "tags": [ "Funding Rate" ], "responses": { "200": { "description": "Map from market to mark price", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/MarkPrice" } } } } ] }, "example": { "success": true, "result": { "AAPL-USD.P": { "market": "AAPL-USD.P", "pair": { "base": "AAPL", "quote": "USD" }, "price": "308.019994", "markPrice": "308.019994", "oraclePrice": "308.01999499999998975", "lastExternalPrice": "308.01999499999998975", "lastUpdatedTime": "2026-06-05T21:27:11.077320736Z" }, "TSLA-USD.P": { "market": "TSLA-USD.P", "pair": { "base": "TSLA", "quote": "USD" }, "price": "180.25", "markPrice": "180.25", "oraclePrice": "180.24500000000000001", "lastExternalPrice": "180.24500000000000001", "lastUpdatedTime": "2026-06-05T21:27:11.077320736Z" } } } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/orders_summaries": { "get": { "summary": "Get Orders Summaries", "description": "Returns a summary of resting orders, position, and market order margin requirements for each market.", "operationId": "getPerpsOrdersSummaries", "tags": [ "Margin Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Array of per-market order summaries", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/GetOrdersSummariesRes" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "restingOrdersSummary": { "bidsInitialMargin": "100.00", "asksInitialMargin": "80.00", "bidsOpenLoss": "5.00", "asksOpenLoss": "3.00", "bidsBaseSize": "10.00", "asksBaseSize": "8.00", "bidsMaintenanceMargin": "50.00", "asksMaintenanceMargin": "40.00" }, "positionSummary": { "bidsInitialMargin": "1125.00", "asksInitialMargin": "0.00", "bidsBaseSize": "10.00", "asksBaseSize": "0.00" }, "marketOrderSummary": { "maxBidQuoteSize": "10000.00", "maxBidBaseSize": "43.96", "maxAskQuoteSize": "10000.00", "maxAskBaseSize": "43.96" } } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/max_order_size": { "get": { "summary": "Get Max Order Size", "description": "Get a summary of the maximum order size that can be placed given the current state of the order book and available margin. For how size limits are determined, see [Position size limits](/maximum-position-sizes).", "operationId": "getMaxOrderSize", "tags": [ "Margin Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Market to estimate max order size for", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "buffer", "in": "query", "description": "Factor to scale returned sizes to guard against fluctuations between calling this endpoint and placing the order. Must be a decimal between 0 and 1. Defaults to 0.9.\n", "required": false, "schema": { "type": "string", "example": "0.9" } } ], "responses": { "200": { "description": "Maximum order sizes", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/MaxOrderSizesRes" } } } ] }, "example": { "success": true, "result": { "percent100": { "maxBidBaseSize": "43.96", "maxAskBaseSize": "43.96" }, "percent75": { "maxBidBaseSize": "32.97", "maxAskBaseSize": "32.97" }, "percent50": { "maxBidBaseSize": "21.98", "maxAskBaseSize": "21.98" }, "percent25": { "maxBidBaseSize": "10.99", "maxAskBaseSize": "10.99" } } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "insufficient_margin", "invalid_market" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/stop_order": { "get": { "summary": "Get Stop Orders", "description": "Gets a list of all stop orders for all markets. This section covers Position-Level stop orders only (take-profit and stop-loss attached to open positions). For TP/SL attached to limit orders, see the order creation payload (takeProfit, stopLoss, etc.). For how stop orders work, see [Take profit and stop loss](/take-profit-and-stop-loss).", "operationId": "getStopOrders", "tags": [ "Stop Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "List of stop orders across all markets and position directions", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiStopOrders" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "positionDirection": "long", "stopLoss": "200.00", "takeProfit": "260.00" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Set Stop Order", "description": "Set a stop order for a particular position defined by market and direction. Optionally pass builderCode to attribute the eventual triggered close to a builder for commission. For how stop orders work, see [Take profit and stop loss](/take-profit-and-stop-loss).", "operationId": "setStopOrder", "tags": [ "Stop Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetStopOrderReq" } } } }, "responses": { "200": { "description": "Updated stop orders for the market", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiStopOrders" } } } ] }, "example": { "success": true, "result": { "market": "AAPL-USD.P", "positionDirection": "long", "stopLoss": "200.00", "takeProfit": null } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_market", "invalid_stop_order", "order_invalid_price", "price_over_ui_limit_10MM", "stop_order_crosses_mark_price", "stop_order_crosses_order_price", "stop_order_trigger_price_exceeds_max", "stop_order_trigger_price_invalid_increment", "stop_order_trigger_price_negative", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_market" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "delete": { "summary": "Remove Stop Order", "description": "Remove a stop order. If no type is specified, removes both stop loss and take profit. For how stop orders work, see [Take profit and stop loss](/take-profit-and-stop-loss).", "operationId": "removeStopOrder", "tags": [ "Stop Orders" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Perps market", "required": true, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "type", "in": "query", "description": "The type of stop order to remove. Either \"stopLoss\" or \"takeProfit\". If not set, removes both stop loss and take profit orders.\n", "required": false, "schema": { "type": "string", "enum": [ "stopLoss", "takeProfit" ], "example": "stopLoss" } } ], "responses": { "200": { "description": "Remaining stop orders for the market after removal", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/ApiStopOrders" } } } ] }, "example": { "success": true, "result": { "market": "AAPL-USD.P", "positionDirection": "long", "stopLoss": null, "takeProfit": null } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "invalid_market", "trading_disabled" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/liquidation_history": { "get": { "summary": "Get Liquidation History", "description": "Returns a paginated history of liquidation events for the authenticated account. For how liquidations work, see [Liquidations](/def).", "operationId": "getLiquidationHistory", "tags": [ "Margin Account" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } }, { "name": "limit", "in": "query", "description": "Maximum number of results to return", "required": false, "schema": { "type": "integer", "example": 100 } }, { "name": "cursor", "in": "query", "description": "Pagination cursor", "required": false, "schema": { "type": "string", "example": "NQ5WWO3THN3Q====" } }, { "name": "startTime", "in": "query", "description": "Start time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1684814400000 } }, { "name": "endTime", "in": "query", "description": "End time filter (UTC milliseconds)", "required": false, "schema": { "type": "integer", "example": 1672549200000 } } ], "responses": { "200": { "description": "Paginated list of liquidation events", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/LiquidationEvent" } }, "pageInfo": { "$ref": "#/components/schemas/PageInfo" } } } ] }, "example": { "success": true, "result": [ { "id": "liq_70a37d8f972f2494837f9dba8364cbb4", "time": "2025-02-15T08:00:00Z", "initiatedAt": "2025-02-15T07:59:55Z", "accountId": "10458932786832481", "status": "finished", "insuranceFundUsed": "0.00", "adl": false, "retryCount": 0, "filledQuoteSize": "5000.00", "filledQuantity": "22.00", "reclaimOrderMargin": false } ], "pageInfo": {} } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param", "failed_to_parse_timestamp", "invalid_cursor" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/leverage": { "get": { "summary": "Get Leverage", "description": "Returns the current leverage setting(s) for the authenticated account. If `market` is provided, returns leverage for that market only; otherwise returns leverage for all markets. For how leverage and margin work, see [Leverage](/leverage).", "operationId": "getPerpsLeverage", "tags": [ "Positions" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "market", "in": "query", "description": "Filter by market. If omitted, returns leverage for all markets.", "required": false, "schema": { "type": "string", "example": "AAPL-USD.P" } } ], "responses": { "200": { "description": "Array of leverage settings", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/ApiLeverage" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "leverage": "10" }, { "market": "TSLA-USD.P", "leverage": "5" } ] } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } }, "post": { "summary": "Set Leverage", "description": "Sets the leverage for a market. Leverage must be a positive integer and cannot exceed the market's maximum leverage. Reducing leverage while insufficient margin is available will return 400 with `error_code=insufficient_margin`. For how leverage and margin work, see [Leverage](/leverage).", "operationId": "setPerpsLeverage", "tags": [ "Positions" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLeverageReq" } } } }, "responses": { "200": { "description": "Leverage updated successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": true } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "invalid_leverage", "invalid_market" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "invalid_leverage" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/portfolio/summary": { "get": { "summary": "Get Portfolio Summary", "description": "Returns current portfolio metrics for the authenticated account: margin balance, net invested, PnL, volume metrics, and Sharpe ratios (when enabled and sufficient data).", "operationId": "getPortfolioSummary", "tags": [ "Portfolio" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "responses": { "200": { "description": "Portfolio summary with metrics and optional Sharpe ratio data", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "$ref": "#/components/schemas/PortfolioSummaryRes" } } } ] }, "example": { "success": true, "result": { "marginBalance": "4950.00", "netInvested": "4750.00", "totalPnL": "232.00", "realizedPnl": "250.00", "volume7d": "15000.00", "volume30d": "85000.00", "volumeAllTime": "250000.00", "sharpe30d": { "sharpeRatio": "1.85", "daysOfData": 30, "meanDailyROI": "0.0012", "stdDevROI": "0.0065" } } } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/portfolio/summary/graph": { "get": { "summary": "Get Portfolio Summary Graph", "description": "Returns time-series portfolio snapshots for the authenticated account. Optional query parameter `range` controls the bucket size: 7d (default), 24h, 30d, or all.", "operationId": "getPortfolioSummaryGraph", "tags": [ "Portfolio" ], "security": [ { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "parameters": [ { "name": "range", "in": "query", "description": "Time range for bucketing: 7d (default), 24h, 30d, or all", "required": false, "schema": { "type": "string", "enum": [ "7d", "24h", "30d", "all" ], "default": "7d" } } ], "responses": { "200": { "description": "Array of portfolio graph points (time-series)", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/PortfolioGraphPoint" } } } } ] }, "example": { "success": true, "result": [ { "time": "2025-03-04T00:00:00Z", "marginBalance": "4800.00", "totalPnL": "180.00", "realizedPnl": "200.00", "netInvested": "4620.00", "fillVolume": "240000.00", "allTimeDeposits": "5000.00", "allTimeWithdrawals": "500.00" }, { "time": "2025-03-05T00:00:00Z", "marginBalance": "4950.00", "totalPnL": "232.00", "realizedPnl": "250.00", "netInvested": "4750.00", "fillVolume": "250000.00", "allTimeDeposits": "5000.00", "allTimeWithdrawals": "500.00" } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_not_found" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_found" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "$ref": "#/components/responses/Forbidden" }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/open_interest": { "get": { "summary": "Get Open Interest", "security": [], "description": "Get open interest across all perpetual futures markets.", "operationId": "getOpenInterest", "tags": [ "Market Data" ], "responses": { "200": { "description": "Array of open interest objects per market", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/OpenInterestRes" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "openInterest": "2394.23", "notionalValue": "544683.50" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/volume": { "get": { "summary": "Get Volume", "security": [], "description": "Get 24-hour trading volume across all perpetual futures markets.", "operationId": "getVolume", "tags": [ "Market Data" ], "responses": { "200": { "description": "Array of volume objects per market", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/VolumeRes" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "volume": "12500.00", "quoteVolume": "2843750.00" } ] } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } }, "/v1/perps/contracts": { "get": { "summary": "Get Contracts", "security": [ {}, { "BearerAuth": [] }, { "ApiKeyAuth": [] } ], "description": "Gets a list of perpetual futures contracts and their current market data. For the list of supported markets, see [Markets](/markets).", "operationId": "getContracts", "tags": [ "Market Data" ], "parameters": [ { "name": "sparkline", "in": "query", "description": "If true, include sparkline price data in the response", "required": false, "schema": { "type": "boolean", "example": false } } ], "responses": { "200": { "description": "List of perpetual futures contracts", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/GenericResponse" }, { "type": "object", "properties": { "result": { "type": "array", "items": { "$ref": "#/components/schemas/Contract" } } } } ] }, "example": { "success": true, "result": [ { "market": "AAPL-USD.P", "productType": "perpetual", "contractType": "linear", "baseCurrency": "AAPL", "quoteCurrency": "USDC", "disabled": false, "lastPrice": "227.50", "baseVolume": "12500.00", "quoteVolume": "2843750.00", "usdVolume": "2843750.00", "bid": "227.40", "ask": "227.60", "high": "230.00", "low": "225.00", "openInterest": "2394.23", "openInterestUsd": "544683.50", "indexPrice": "227.55", "indexCurrency": "USD", "fundingRate": "0.0000125", "nextFundingRate": "0.0000130", "nextFundingRateTimestamp": "2025-03-05T16:00:00Z", "makerFee": "0.0002", "takerFee": "0.0005", "priceChangePercent": "1.12" } ] } } } }, "400": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "bad_query_param" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "bad_query_param" } } } }, "429": { "$ref": "#/components/responses/TooManyRequests" }, "500": { "$ref": "#/components/responses/InternalServerError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" }, "ApiKeyAuth": { "type": "apiKey", "in": "header", "name": "X-API-KEY-ID" } }, "schemas": { "GenericResponse": { "type": "object", "required": [ "success" ], "properties": { "success": { "type": "boolean", "description": "Whether the request was successful", "example": true }, "error": { "type": "string", "description": "Error message, present only on failure", "example": "" }, "error_code": { "type": "string", "description": "Semantic error code. See each endpoint's error responses for the specific codes it can return." }, "deprecated": { "type": "string", "description": "Deprecation notice, if applicable", "example": "" } } }, "PageInfo": { "type": "object", "properties": { "prevCursor": { "type": "string", "description": "Cursor value to get the previous page of results", "example": "O4ZTGM3RGM2DG===" }, "nextCursor": { "type": "string", "description": "Cursor value to get the next page of results", "example": "NQ5WWO3THN3Q====" } } }, "SharpeRatioData": { "type": "object", "description": "Calculated Sharpe ratio and related metadata", "properties": { "sharpeRatio": { "type": "string", "description": "Annualized Sharpe ratio" }, "daysOfData": { "type": "integer", "description": "Number of days of data used in the calculation" }, "meanDailyROI": { "type": "string", "description": "Mean daily return" }, "stdDevROI": { "type": "string", "description": "Standard deviation of daily returns" } } }, "PortfolioSummaryRes": { "type": "object", "description": "Current portfolio metrics and optional Sharpe ratios", "properties": { "marginBalance": { "type": "string", "description": "Current margin account balance" }, "netInvested": { "type": "string", "description": "Net invested amount" }, "totalPnL": { "type": "string", "description": "Total unrealized + realized PnL" }, "realizedPnl": { "type": "string", "description": "Realized PnL" }, "volume7d": { "type": "string", "description": "Trading volume over last 7 days" }, "volume30d": { "type": "string", "description": "Trading volume over last 30 days" }, "volumeAllTime": { "type": "string", "description": "All-time trading volume" }, "sharpe30d": { "$ref": "#/components/schemas/SharpeRatioData" }, "sharpeAllTime": { "$ref": "#/components/schemas/SharpeRatioData" } } }, "PortfolioGraphPoint": { "type": "object", "description": "Single time-series point for portfolio graph", "properties": { "time": { "type": "string", "format": "date-time", "description": "Timestamp of the snapshot" }, "marginBalance": { "type": "string", "description": "Margin balance at this time" }, "totalPnL": { "type": "string", "description": "Total PnL at this time" }, "realizedPnl": { "type": "string", "description": "Realized PnL at this time" }, "netInvested": { "type": "string", "description": "Net invested at this time" }, "fillVolume": { "type": "string", "description": "Cumulative fill volume at this time" }, "allTimeDeposits": { "type": "string", "description": "All-time deposits at this time" }, "allTimeWithdrawals": { "type": "string", "description": "All-time withdrawals at this time" } } }, "AccountWalletKey": { "type": "object", "required": [ "id", "wallet" ], "properties": { "id": { "type": "string", "description": "The account ID", "example": "10458932786832481" }, "wallet": { "type": "string", "description": "The wallet type", "enum": [ "main", "margin" ], "example": "margin" } } }, "ApiPosition": { "type": "object", "required": [ "market", "direction", "netQuantity", "averageEntryPrice", "usedMargin", "unrealizedPnl", "markPrice", "liquidationPrice", "bankruptcyPrice", "maintenanceMargin", "notionalValue", "leverage", "netFundingSinceNeutral", "returnOnEquity" ], "properties": { "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "direction": { "type": "string", "description": "Position direction", "enum": [ "long", "short", "neutral" ], "example": "short" }, "netQuantity": { "type": "string", "description": "Size of the position in base currency", "example": "1.5489" }, "averageEntryPrice": { "type": "string", "description": "Average entry price", "example": "20566.84" }, "usedMargin": { "type": "string", "description": "Margin used for the position", "example": "2566.84" }, "unrealizedPnl": { "type": "string", "description": "Unrealized PNL relative to the mark price. Positive is profit, negative is loss.", "example": "-900.54" }, "markPrice": { "type": "string", "description": "Current mark price", "example": "20000.54" }, "liquidationPrice": { "type": "string", "description": "Price at which the position will be liquidated", "example": "9000.87" }, "bankruptcyPrice": { "type": "string", "description": "Price at which bankruptcy occurs during liquidation", "example": "6000.11" }, "maintenanceMargin": { "type": "string", "description": "Maintenance margin required for this position", "example": "1500.22" }, "notionalValue": { "type": "string", "description": "Notional value of the position", "example": "30000.00" }, "leverage": { "type": "string", "description": "Current effective leverage for this position", "example": "10.0" }, "netFundingSinceNeutral": { "type": "string", "description": "Net funding payments since the position was opened", "example": "-12.34" }, "returnOnEquity": { "type": "string", "description": "Return on equity for this position", "example": "-0.35" }, "stopLossTriggerPrice": { "type": "string", "description": "Triggering price for stop loss order (optional)", "example": "18000.00" }, "takeProfitTriggerPrice": { "type": "string", "description": "Triggering price for take profit order (optional)", "example": "25000.00" } } }, "MarginAccountBalanceSummary": { "type": "object", "required": [ "walletBalance", "realizedPnl", "unrealizedPnl", "marginBalance", "usedMargin", "availableMargin", "withdrawableMargin", "maintenanceMarginRequirement", "totalMaintenanceMargin", "marginRatio", "leverage", "underLiquidation", "totalFundingPayments", "totalTradingFees", "totalPnL" ], "properties": { "walletBalance": { "type": "string", "description": "The amount in USDC resulting from transfers in/out, realized PnL, and fees. wallet_balance = deposits - withdrawals + realized_pnl + trading_fees + funding_rate_fees\n", "example": "2000" }, "realizedPnl": { "type": "string", "description": "Total realized PNL in USDC", "example": "600" }, "unrealizedPnl": { "type": "string", "description": "The current unrealized PNL in USDC at mark price for open positions", "example": "-500" }, "marginBalance": { "type": "string", "description": "Margin balance in USDC. margin_balance = wallet_balance + unrealized_pnl\n", "example": "1500" }, "usedMargin": { "type": "string", "description": "Amount of used margin in USDC for resting orders and positions. used_margin = sum_for_all_markets(max(position_ask + resting_orders_ask, position_bid + resting_orders_bid) + open_loss_total)\n", "example": "200" }, "availableMargin": { "type": "string", "description": "Amount of margin in USDC available for new positions. available_balance = margin_balance - used_margin. Will not be negative.\n", "example": "1300" }, "withdrawableMargin": { "type": "string", "description": "Amount in USDC available for withdrawal. withdrawable_amount = max(0, min(available_balance, wallet_balance))\n", "example": "100" }, "maintenanceMarginRequirement": { "type": "string", "description": "Total maintenance margin requirement for all open positions", "example": "150" }, "totalMaintenanceMargin": { "type": "string", "description": "Total maintenance margin requirement for all open positions and resting orders", "example": "200" }, "marginRatio": { "type": "string", "description": "Margin ratio (0–100%) indicating liquidation proximity. margin_ratio = maintenance_margin / margin_balance. Returns 9999 if margin balance is negative or zero.\n", "example": "0.13" }, "leverage": { "type": "string", "description": "Effective leverage for the entire account (notional value of all positions / margin balance)", "example": "5.0" }, "underLiquidation": { "type": "boolean", "description": "Whether the account is currently under liquidation", "example": false }, "totalFundingPayments": { "type": "string", "description": "Sum of all funding payments applied to this account", "example": "123" }, "totalTradingFees": { "type": "string", "description": "Sum of all trading fees paid. A negative value implies a net rebate.", "example": "123" }, "totalPnL": { "type": "string", "description": "All-time PnL including realized/unrealized PnL, fees, and funding payments", "example": "477" }, "netInvested": { "type": "string", "description": "Net amount invested", "example": "1000" } } }, "MaxOrderSizesRes": { "type": "object", "required": [ "percent100", "percent75", "percent50", "percent25" ], "properties": { "percent100": { "$ref": "#/components/schemas/OrderSizes" }, "percent75": { "$ref": "#/components/schemas/OrderSizes" }, "percent50": { "$ref": "#/components/schemas/OrderSizes" }, "percent25": { "$ref": "#/components/schemas/OrderSizes" } } }, "OrderSizes": { "type": "object", "required": [ "maxBidBaseSize", "maxAskBaseSize" ], "properties": { "maxBidBaseSize": { "type": "string", "description": "Allowed buy order size in base asset", "example": "123.4" }, "maxAskBaseSize": { "type": "string", "description": "Allowed ask order size in base asset", "example": "123.4" } } }, "MarkPrice": { "type": "object", "required": [ "market", "pair", "price", "markPrice", "oraclePrice", "lastExternalPrice", "lastUpdatedTime" ], "properties": { "market": { "type": "string", "description": "The market identifier", "example": "AAPL-USD.P" }, "pair": { "type": "object", "description": "Currency pair", "properties": { "base": { "type": "string", "example": "AAPL" }, "quote": { "type": "string", "example": "USD" } } }, "price": { "type": "string", "description": "Current mark price (alias of `markPrice`)", "example": "308.019994" }, "markPrice": { "type": "string", "description": "Current mark price used for PnL, margin, and liquidation calculations", "example": "308.019994" }, "oraclePrice": { "type": "string", "description": "Latest oracle price for the market", "example": "308.01999499999998975" }, "lastExternalPrice": { "type": "string", "description": "Most recent external reference price observed for the market", "example": "308.01999499999998975" }, "lastUpdatedTime": { "type": "string", "format": "date-time", "description": "Time the mark price was last updated", "example": "2026-06-05T21:27:11.077320736Z" } } }, "FundingRate": { "type": "object", "required": [ "market", "rate", "intervalEnds" ], "properties": { "market": { "type": "string", "description": "The market the funding rate applies to", "example": "AAPL-USD.P" }, "rate": { "type": "string", "description": "The current estimated funding rate", "example": "0.0000125" }, "intervalEnds": { "type": "string", "format": "date-time", "description": "The time the current funding interval ends and the funding rate will be paid", "example": "2022-06-16T12:35:10.123456Z" }, "premiums": { "type": "array", "description": "Premium index measurements that make up the funding rate", "items": { "$ref": "#/components/schemas/PremiumIndexValue" } } } }, "PremiumIndexValue": { "type": "object", "properties": { "time": { "type": "string", "format": "date-time", "description": "Time of the premium index measurement", "example": "2022-06-16T12:00:00Z" }, "premiumIndex": { "type": "string", "description": "The premium index value", "example": "0.000025" } } }, "FundingRateValue": { "type": "object", "required": [ "market", "time", "fundingRate" ], "properties": { "market": { "type": "string", "description": "Perps trading market", "example": "AAPL-USD.P" }, "time": { "type": "string", "format": "date-time", "description": "The time funding was paid", "example": "2022-06-16T12:35:10.123456Z" }, "fundingRate": { "type": "string", "description": "The funding rate as a fraction", "example": "0.0000125" } } }, "FundingFeeTransfer": { "type": "object", "required": [ "market", "time", "markPrice", "positionSize", "positionDirection", "rate", "payer", "amount" ], "properties": { "market": { "type": "string", "description": "Market that the fee was paid in", "example": "AAPL-USD.P" }, "time": { "type": "string", "format": "date-time", "description": "The time that the funding fee was paid", "example": "2022-06-16T12:35:10.123456Z" }, "markPrice": { "type": "string", "description": "The mark price at the time the fee was paid", "example": "12.03" }, "positionSize": { "type": "string", "description": "The base size of the position at the time the fee was paid", "example": "1.00" }, "positionDirection": { "type": "string", "description": "The direction of the position at the time the fee was paid", "enum": [ "long", "short", "neutral" ], "example": "long" }, "rate": { "type": "string", "description": "The funding rate that led to this fee", "example": "0.0000125" }, "payer": { "type": "string", "description": "The side that paid the fee", "enum": [ "long", "short", "neutral" ], "example": "long" }, "amount": { "type": "string", "description": "The actual amount of USDC transferred. Positive indicates a fee you earned, negative a fee you paid.\n", "example": "-0.16402" } } }, "ApiStopOrders": { "type": "object", "required": [ "market", "positionDirection" ], "properties": { "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "positionDirection": { "type": "string", "description": "Position direction this stop order watches", "enum": [ "long", "short", "neutral" ], "example": "long" }, "stopLoss": { "type": "string", "nullable": true, "description": "Stop loss trigger price, if set", "example": "8.00" }, "takeProfit": { "type": "string", "nullable": true, "description": "Take profit trigger price, if set", "example": "9.00" } } }, "SetStopOrderReq": { "type": "object", "required": [ "market", "positionDirection", "type", "triggerPrice" ], "properties": { "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "positionDirection": { "type": "string", "description": "Position direction this stop order watches", "enum": [ "long", "short" ], "example": "long" }, "type": { "type": "string", "description": "The type of stop order to set", "enum": [ "stopLoss", "takeProfit" ], "example": "stopLoss" }, "triggerPrice": { "type": "string", "description": "The trigger price", "example": "9.00" }, "quantity": { "type": "string", "description": "Optional. Sets a partial stop order for this quantity of the position instead of the full position. Omit to close the full position when triggered.", "example": "0.5" }, "builderCode": { "allOf": [ { "$ref": "#/components/schemas/BuilderCodeReq" } ], "description": "Optional. Attributes the eventual triggered close to a builder for commission. Must be set explicitly on this request for the close to carry builder commission; it is not inherited from the builderCode on the order(s) that originally opened the position." } } }, "Contract": { "type": "object", "required": [ "market", "productType", "contractType", "baseCurrency", "quoteCurrency", "disabled" ], "properties": { "market": { "type": "string", "description": "Perps market identifier", "example": "AAPL-USD.P" }, "displayName": { "type": "string", "description": "Human-readable display name for the contract", "example": "Apple Inc." }, "productType": { "type": "string", "description": "Type of product", "example": "perpetual" }, "contractType": { "type": "string", "description": "Type of contract", "example": "linear" }, "baseCurrency": { "type": "string", "description": "The base currency of the contract", "example": "AAPL" }, "quoteCurrency": { "type": "string", "description": "The quote currency of the contract", "example": "USDC" }, "disabled": { "type": "boolean", "description": "If true, the market is currently unavailable for trading", "example": false }, "lastPrice": { "type": "string", "description": "Price of the last trade", "example": "20000.54" }, "baseVolume": { "type": "string", "description": "24-hour trading volume in base currency", "example": "1089.12" }, "quoteVolume": { "type": "string", "description": "24-hour trading volume in quote currency", "example": "120400.65" }, "usdVolume": { "type": "string", "description": "24-hour trading volume in USD", "example": "120400.65" }, "bid": { "type": "string", "description": "Current best bid price", "example": "1500.22" }, "ask": { "type": "string", "description": "Current best ask price", "example": "1600.20" }, "high": { "type": "string", "description": "Highest traded price in the last 24 hours", "example": "1600.20" }, "low": { "type": "string", "description": "Lowest traded price in the last 24 hours", "example": "1400.20" }, "openInterest": { "type": "string", "description": "Open interest in base currency", "example": "2394.2301" }, "openInterestUsd": { "type": "string", "description": "Open interest in USD", "example": "24311.72" }, "indexPrice": { "type": "string", "description": "Current price of the underlying market", "example": "1600.20" }, "indexCurrency": { "type": "string", "description": "Currency of the underlying market", "example": "USD" }, "fundingRate": { "type": "string", "description": "Funding rate at the last completed funding interval", "example": "0.00152" }, "nextFundingRate": { "type": "string", "description": "Estimated funding rate at the end of the current funding interval", "example": "0.00152" }, "nextFundingRateTimestamp": { "type": "string", "format": "date-time", "description": "Timestamp when the next funding payments will occur", "example": "2022-06-16T12:35:10.123456Z" }, "makerFee": { "type": "string", "description": "Fee on a filled resting (maker) order", "example": "0.0002" }, "takerFee": { "type": "string", "description": "Fee on a filled aggressive (taker) order", "example": "0.0005" }, "priceChangePercent": { "type": "string", "description": "Price change as a percentage in the last 24 hours", "example": "-5" }, "isClosed": { "type": "boolean", "description": "If true, the underlying market is currently closed (e.g. outside trading hours for equities)", "example": false }, "sparkline": { "$ref": "#/components/schemas/Sparkline" }, "tags": { "type": "array", "description": "Optional tags describing the contract (e.g. category labels)", "items": { "type": "string" }, "example": ["equity", "tech"] } } }, "Sparkline": { "type": "object", "properties": { "price": { "type": "array", "description": "Array of price values for the sparkline", "items": { "type": "string" } } } }, "OpenInterestRes": { "type": "object", "required": [ "market", "openInterest", "notionalValue" ], "properties": { "market": { "type": "string", "description": "Perpetual futures market", "example": "AAPL-USD.P" }, "openInterest": { "type": "string", "description": "The open interest in base size", "example": "2394.2301" }, "notionalValue": { "type": "string", "description": "The notional value of the open interest at the current mark price", "example": "24311.72" } } }, "VolumeRes": { "type": "object", "required": [ "market", "volume", "quoteVolume" ], "properties": { "market": { "type": "string", "description": "Perpetual futures market", "example": "AAPL-USD.P" }, "volume": { "type": "string", "description": "24-hour trading volume in base size", "example": "2394.2301" }, "quoteVolume": { "type": "string", "description": "24-hour trading volume in quote currency (last price × base volume)", "example": "38310297.12" } } }, "StopOrderReq": { "type": "object", "required": [ "triggerPrice" ], "properties": { "triggerPrice": { "type": "string", "description": "Trigger price for the stop order", "example": "18000.00" } } }, "BuilderCodeReq": { "type": "object", "required": [ "code" ], "description": "Attributes the order (and, for TP/SL, its eventual triggered close) to a builder for commission. Contact the Ondo Perps team to get a builder code activated. There is no centrally configured default fee rate for a builder code — feeRateBpsFractional must be set on this request for the fill to earn any commission. Field name subject to change before v1.", "properties": { "code": { "type": "string", "description": "Builder code to attribute this order to.", "example": "yourCode" }, "feeRateBps": { "type": "integer", "deprecated": true, "description": "Deprecated: use feeRateBpsFractional instead. Sets the fee rate for this order (positive integer bps, e.g. 5 = 5 bps = 0.05%). Required to earn commission — there is no default rate applied if omitted.", "example": 5 }, "feeRateBpsFractional": { "type": "number", "description": "Sets the fee rate for this order (bps, e.g. 5 = 5 bps = 0.05%; fractional values allowed). Required to earn commission on this fill — there is no default rate applied if omitted. Takes precedence over feeRateBps if both are set.", "example": 2.5 } } }, "AddOrderReq": { "type": "object", "required": [ "side", "market" ], "properties": { "side": { "type": "string", "description": "buy or sell", "enum": [ "buy", "sell" ], "example": "buy" }, "price": { "type": "string", "description": "Limit price. Must be aligned with quoteIncrement from /v1/markets. Omit for market orders.", "example": "1.55" }, "size": { "type": "string", "description": "Order quantity in base currency. Used for both limit and market orders. Must be aligned with baseIncrement from /v1/markets.\n", "example": "20.30" }, "quoteSize": { "type": "string", "description": "Order quantity in quote currency. Can only be set for market order buys.", "example": "13.0967" }, "market": { "type": "string", "description": "Trading market pair", "example": "AAPL-USD.P" }, "clientOrderId": { "type": "string", "description": "Optional client-provided order ID. Must be alphanumeric including underscores and dashes, and at most 64 characters.\n", "example": "order123" }, "type": { "type": "string", "description": "Order type. Defaults to \"limit\".", "enum": [ "limit", "market" ], "example": "limit" }, "timeInForce": { "type": "string", "description": "\"GTC\" (Good until cancelled) or \"IOC\" (Immediate or cancel). Cannot be set for market orders. Defaults to \"GTC\".\n", "enum": [ "GTC", "IOC" ], "example": "GTC" }, "postOnly": { "type": "boolean", "description": "If true, the order is rejected if it would match at placement. Returns 400 with error `post_only_has_match` if it would match.\n", "example": false }, "reduceOnly": { "type": "boolean", "description": "If true, the order can only reduce an existing position.", "example": false }, "takeProfit": { "$ref": "#/components/schemas/StopOrderReq" }, "stopLoss": { "$ref": "#/components/schemas/StopOrderReq" }, "builderCode": { "allOf": [ { "$ref": "#/components/schemas/BuilderCodeReq" } ], "description": "Attributes this order to a builder for commission. If this order carries takeProfit and/or stopLoss, the same builder code is inherited by the resulting TP/SL close when it triggers." } } }, "BatchAddOrderReq": { "type": "object", "required": [ "orders" ], "properties": { "orders": { "type": "array", "description": "Array of order requests. Must have at least 1 element and at most 20.\n", "minItems": 1, "maxItems": 20, "items": { "$ref": "#/components/schemas/AddOrderReq" } } } }, "ErroredAddOrderReq": { "type": "object", "properties": { "order": { "$ref": "#/components/schemas/AddOrderReq" }, "error": { "type": "string", "description": "Error message explaining why the order failed", "example": "insufficient margin" }, "errorCode": { "type": "string", "description": "Semantic error code, empty if not a semantic error", "example": "insufficient_margin" } } }, "BatchAddOrderRes": { "type": "object", "properties": { "addedOrders": { "type": "array", "description": "Orders that were successfully added", "items": { "$ref": "#/components/schemas/ApiOrder" } }, "failedOrders": { "type": "array", "description": "Orders that were not added and the reason why", "items": { "$ref": "#/components/schemas/ErroredAddOrderReq" } } } }, "ApiOrder": { "type": "object", "required": [ "orderId", "side", "price", "size", "market", "filledSize", "lastFillSize", "filledCost", "fee", "status", "createdAt", "type" ], "properties": { "orderId": { "type": "string", "description": "Internal order ID", "example": "70a37d8f972f2494837f9dba8364cbb4" }, "clientOrderId": { "type": "string", "description": "Client-provided order ID (if set)", "example": "order123" }, "parentOrderId": { "type": "string", "description": "Parent order ID (e.g. for TWAP child orders)", "example": "twap_70a37d8f972f2494837f9dba8364cbb4" }, "side": { "type": "string", "description": "buy or sell", "enum": [ "buy", "sell" ], "example": "buy" }, "price": { "type": "string", "description": "Limit price", "example": "1.55" }, "size": { "type": "string", "description": "Order quantity in base currency", "example": "20.30" }, "market": { "type": "string", "description": "Trading market", "example": "AAPL-USD.P" }, "filledSize": { "type": "string", "description": "Quantity of the order that has been filled", "example": "5.403" }, "lastFillSize": { "type": "string", "description": "Quantity filled in the most recent trade", "example": "5.403" }, "filledCost": { "type": "string", "description": "Cost of the filled portion of the order (filledSize × fill price)", "example": "8.37465" }, "realizedPnl": { "type": "string", "description": "Realized PNL for this order (perps only)", "example": "1.2345" }, "fee": { "type": "string", "description": "Fees incurred on this order", "example": "0.0837" }, "feeRebate": { "type": "string", "description": "Fee rebate earned on this order (perps only)", "example": "0.0042" }, "status": { "type": "string", "description": "Order status", "enum": [ "open", "fullyfilled", "canceled", "pending", "untriggered" ], "example": "open" }, "createdAt": { "type": "string", "format": "date-time", "description": "Order creation time", "example": "2022-06-16T12:35:11.123456Z" }, "filledAt": { "type": "string", "format": "date-time", "description": "Time when the order was fully filled (if applicable)", "example": "2022-06-16T12:35:11.123456Z" }, "canceledAt": { "type": "string", "format": "date-time", "description": "Order cancellation time (if cancelled)", "example": "2022-06-16T12:35:11.123456Z" }, "cancelReason": { "type": "string", "description": "Reason the order was cancelled. Possible values: \"\" (user cancelled), \"liquidation\", \"selfmatchprevention\", \"cancelaftertimeout\", \"startupbadprice\", \"immediateorcancel\"\n", "example": "liquidation", "enum": [ "", "liquidation", "selfMatchPrevention", "cancelAfterTimeout", "startupBadPrice", "immediateOrCancel", "cancelAfterTimeoutOnShutdown", "cancelOnStartup", "cancelByAdmin", "positionClosed", "stopOrderPositionNeutral", "stopOrderPositionDirectionMismatch", "stopOrderInLiquidation", "stopOrderInternalError" ] }, "type": { "type": "string", "description": "Order type", "enum": [ "limit", "market", "stopMarket", "takeProfitMarket" ], "example": "limit" }, "timeInForce": { "type": "string", "description": "Time in force (GTC or IOC). Not returned for market orders.", "enum": [ "GTC", "IOC" ], "example": "GTC" }, "reduceOnly": { "type": "boolean", "description": "Whether the order is reduce-only", "example": false }, "liquidationId": { "type": "string", "description": "ID of the liquidation event this order participated in (perps only)", "example": "a1b2c3d4e5f60718293a4b5c6d7e8f90" }, "closePosition": { "type": "boolean", "description": "True if this is a position-level TP/SL order", "example": false }, "stopOrderType": { "type": "string", "description": "Stop order type (stopLoss or takeProfit), if applicable", "enum": [ "stopLoss", "takeProfit" ] }, "triggerPrice": { "type": "string", "description": "Trigger price for stop orders", "example": "125.50" } } }, "BatchCancelResult": { "type": "object", "properties": { "successfulCancels": { "type": "array", "description": "Orders that were successfully cancelled", "items": { "$ref": "#/components/schemas/ApiOrder" } }, "failedCancels": { "type": "array", "description": "Cancel attempts that failed", "items": { "$ref": "#/components/schemas/CancelError" } } } }, "CancelError": { "type": "object", "properties": { "orderId": { "type": "string", "description": "Order ID that failed to cancel", "example": "70a37d8f972f2494837f9dba8364cbb4" }, "error": { "type": "string", "description": "Error message explaining why the cancel failed", "example": "order_already_canceled" }, "errorCode": { "type": "string", "description": "Semantic error code (empty if not a semantic error)", "example": "order_already_canceled" } } }, "ApiFill": { "type": "object", "required": [ "id", "orderId", "market", "price", "size", "side", "filledCost", "fee", "time", "isMaker" ], "properties": { "id": { "type": "string", "description": "Fill ID", "example": "70a37d8f972f2494837f9dba8364cbb4" }, "orderId": { "type": "string", "description": "Order ID this fill belongs to", "example": "197ec08e001658690721be129e7fa595" }, "clientOrderId": { "type": "string", "description": "Client order ID (if set on the order)", "example": "order123" }, "parentOrderID": { "type": "string", "description": "Parent order ID (e.g. for TWAP child orders)", "example": "70a37d8f972f2494837f9dba8364cbb4" }, "market": { "type": "string", "description": "Trading market", "example": "AAPL-USD.P" }, "price": { "type": "string", "description": "Fill price", "example": "1.55" }, "size": { "type": "string", "description": "Fill quantity in base currency", "example": "5.403" }, "side": { "type": "string", "description": "buy or sell", "enum": [ "buy", "sell" ], "example": "buy" }, "direction": { "type": "string", "description": "Trade direction for perps fills. One of: \"open long\", \"open short\", \"close long\", \"close short\", \"flip long to short\", \"flip short to long\"\n", "example": "openLong", "enum": [ "openLong", "openShort", "closeLong", "closeShort", "flipLongToShort", "flipShortToLong" ] }, "filledCost": { "type": "string", "description": "Total cost of the fill in quote currency", "example": "8.37465" }, "fee": { "type": "string", "description": "Fees incurred on this fill", "example": "0.0837" }, "feeRebate": { "type": "string", "description": "Fee rebate earned on this fill (perps only)", "example": "0.0042" }, "pnl": { "type": "string", "description": "Realized PNL for this fill (perps only)", "example": "1.2345" }, "time": { "type": "string", "format": "date-time", "description": "Time the fill occurred", "example": "2022-06-16T12:35:11.123456Z" }, "isMaker": { "type": "boolean", "description": "True if this was a maker (resting) fill", "example": false }, "isADL": { "type": "boolean", "description": "True if this was an auto-deleveraging fill (perps only)", "example": false } } }, "ApiTrade": { "type": "object", "required": [ "market", "price", "size", "cost", "aggressor_side", "time", "id" ], "properties": { "market": { "type": "string", "description": "Trading market", "example": "AAPL-USD.P" }, "price": { "type": "string", "description": "Trade price", "example": "1.55" }, "size": { "type": "string", "description": "Trade size in base currency", "example": "5.403" }, "cost": { "type": "string", "description": "Trade cost in quote currency", "example": "8.37465" }, "aggressor_side": { "type": "string", "description": "Side of the aggressing (taker) order", "enum": [ "buy", "sell" ], "example": "buy" }, "time": { "type": "string", "format": "date-time", "description": "Time the trade occurred", "example": "2022-06-16T12:35:11.123456Z" }, "id": { "type": "string", "description": "Trade/fill ID", "example": "70a37d8f972f2494837f9dba8364cbb4" } } }, "ApiBookSnapshot": { "type": "object", "required": [ "market", "time", "bids", "asks" ], "properties": { "market": { "type": "string", "description": "Trading market", "example": "AAPL-USD.P" }, "time": { "type": "string", "format": "date-time", "description": "Snapshot timestamp", "example": "2022-06-16T12:35:11.123456Z" }, "bids": { "type": "array", "description": "Best bid price levels, sorted descending by price", "items": { "$ref": "#/components/schemas/BookLevel" } }, "asks": { "type": "array", "description": "Best ask price levels, sorted ascending by price", "items": { "$ref": "#/components/schemas/BookLevel" } } } }, "BookLevel": { "type": "array", "description": "Price level represented as [price, quantity]", "items": { "type": "string" }, "minItems": 2, "maxItems": 2, "example": [ "1.55", "100.0" ] }, "ApiCandle": { "type": "object", "required": [ "startTime", "open", "high", "low", "close", "volume" ], "properties": { "startTime": { "type": "string", "format": "date-time", "description": "Start time of the candle", "example": "2024-01-04T16:00:00Z" }, "open": { "type": "string", "description": "Opening price", "example": "150.25" }, "high": { "type": "string", "description": "Highest price during the interval", "example": "152.10" }, "low": { "type": "string", "description": "Lowest price during the interval", "example": "149.80" }, "close": { "type": "string", "description": "Closing price", "example": "151.45" }, "volume": { "type": "string", "description": "Trading volume in base currency during the interval", "example": "1234.56" } } }, "LiquidationEvent": { "type": "object", "required": [ "id", "time", "initiatedAt", "accountId", "status", "insuranceFundUsed", "adl", "retryCount" ], "properties": { "id": { "type": "string", "description": "Liquidation event ID", "example": "liq_70a37d8f972f2494837f9dba8364cbb4" }, "time": { "type": "string", "format": "date-time", "description": "Time the liquidation completed", "example": "2024-01-04T16:13:34Z" }, "initiatedAt": { "type": "string", "format": "date-time", "description": "Time the liquidation was initiated", "example": "2024-01-04T16:13:30Z" }, "accountId": { "type": "string", "description": "Account that was liquidated", "example": "10458932786832481" }, "status": { "type": "string", "description": "Status of the liquidation event", "example": "start", "enum": [ "queued", "start", "retry", "stop" ] }, "insuranceFundUsed": { "type": "string", "description": "Amount drawn from the insurance fund to cover losses", "example": "0.00" }, "adl": { "type": "boolean", "description": "Whether auto-deleveraging (ADL) was triggered", "example": false }, "retryCount": { "type": "integer", "description": "Number of retry attempts before the liquidation completed", "example": 0 }, "triggeringPositions": { "type": "array", "description": "Positions that triggered the liquidation (populated for events after August 2024)", "items": { "$ref": "#/components/schemas/ApiPosition" } }, "filledQuoteSize": { "type": "string", "description": "Total quote value of positions closed during liquidation (populated for events after February 2025)", "example": "5000.00" }, "filledQuantity": { "type": "string", "description": "Total base quantity of positions closed during liquidation (populated for events after February 2025)", "example": "0.25" }, "reclaimOrderMargin": { "type": "boolean", "description": "If true, the liquidation only cancelled resting orders to free up margin without closing positions", "example": false } } }, "OrdersSummary": { "type": "object", "properties": { "bidsInitialMargin": { "type": "string", "description": "Initial margin required for all bid (buy) resting orders", "example": "100.00" }, "asksInitialMargin": { "type": "string", "description": "Initial margin required for all ask (sell) resting orders", "example": "80.00" }, "bidsOpenLoss": { "type": "string", "description": "Unrealized open loss on the bid side that counts toward margin", "example": "5.00" }, "asksOpenLoss": { "type": "string", "description": "Unrealized open loss on the ask side that counts toward margin", "example": "3.00" }, "bidsBaseSize": { "type": "string", "description": "Total base size of all bid resting orders", "example": "10.00" }, "asksBaseSize": { "type": "string", "description": "Total base size of all ask resting orders", "example": "8.00" }, "bidsMaintenanceMargin": { "type": "string", "description": "Maintenance margin required for all bid resting orders", "example": "50.00" }, "asksMaintenanceMargin": { "type": "string", "description": "Maintenance margin required for all ask resting orders", "example": "40.00" } } }, "MarketOrdersSummary": { "type": "object", "properties": { "maxBidQuoteSize": { "type": "string", "description": "Maximum buy market order size in quote currency", "example": "10000.00" }, "maxBidBaseSize": { "type": "string", "description": "Maximum buy market order size in base currency", "example": "5.00" }, "maxBidPositionLeverage": { "type": "string", "description": "Maximum leverage available for a buy market order", "example": "10.0" }, "maxAskQuoteSize": { "type": "string", "description": "Maximum sell market order size in quote currency", "example": "10000.00" }, "maxAskBaseSize": { "type": "string", "description": "Maximum sell market order size in base currency", "example": "5.00" }, "maxAskPositionLeverage": { "type": "string", "description": "Maximum leverage available for a sell market order", "example": "10.0" } } }, "GetOrdersSummariesRes": { "type": "object", "required": [ "market" ], "properties": { "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "restingOrdersSummary": { "$ref": "#/components/schemas/OrdersSummary" }, "positionSummary": { "$ref": "#/components/schemas/OrdersSummary" }, "marketOrderSummary": { "$ref": "#/components/schemas/MarketOrdersSummary" } } }, "ApiLeverage": { "type": "object", "required": [ "market", "leverage" ], "properties": { "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "leverage": { "type": "string", "description": "Current leverage setting for this market", "example": "10" } } }, "SetLeverageReq": { "type": "object", "required": [ "market", "leverage" ], "properties": { "market": { "type": "string", "description": "Perps market to set leverage for", "example": "AAPL-USD.P" }, "leverage": { "type": "string", "description": "New leverage value. Must be a positive integer not exceeding the market maximum.", "example": "10" } } }, "CreateTWAPOrderReq": { "type": "object", "required": [ "market", "side", "size", "runningTime", "frequency" ], "properties": { "market": { "type": "string", "description": "Perps trading market", "example": "AAPL-USD.P" }, "side": { "type": "string", "description": "Order side", "enum": [ "buy", "sell" ], "example": "buy" }, "size": { "type": "string", "description": "Total order size in base currency to execute over the TWAP duration", "example": "20.30" }, "runningTime": { "type": "integer", "description": "Total duration of the TWAP order in seconds. Must be between 300 (5 minutes) and 86400 (24 hours) and a multiple of `frequency`.", "example": 3600 }, "frequency": { "type": "integer", "description": "Interval between child orders in seconds. runningTime / frequency gives the number of child orders, which must be between 2 and 200.", "example": 60 }, "reduceOnly": { "type": "boolean", "description": "If true, child orders are reduce-only", "example": false }, "maxPrice": { "type": "string", "description": "Maximum allowed price for child orders. Child orders will not be placed above this price.", "example": "160.00" }, "minPrice": { "type": "string", "description": "Minimum allowed price for child orders. Child orders will not be placed below this price.", "example": "140.00" } } }, "TWAPOrderApiResp": { "type": "object", "required": [ "twapId", "market", "side", "startTime", "runningTime", "frequency", "avgFilledPrice", "filledSize", "totalSize", "totalFees", "orderStatus", "reduceOnly" ], "properties": { "twapId": { "type": "string", "description": "TWAP order ID", "example": "twap_70a37d8f972f2494837f9dba8364cbb4" }, "market": { "type": "string", "description": "Perps market", "example": "AAPL-USD.P" }, "side": { "type": "string", "description": "Order side", "enum": [ "buy", "sell" ], "example": "buy" }, "startTime": { "type": "string", "format": "date-time", "description": "Time the TWAP order was created", "example": "2024-01-04T16:00:00Z" }, "finishTime": { "type": "string", "format": "date-time", "description": "Time the TWAP order completed or was cancelled (omitted if still running)", "example": "2024-01-04T17:00:00Z" }, "runningTime": { "type": "integer", "description": "Total duration of the TWAP order in seconds", "example": 3600 }, "frequency": { "type": "integer", "description": "Interval between child orders in seconds", "example": 60 }, "avgFilledPrice": { "type": "string", "description": "Volume-weighted average fill price across all child orders", "example": "150.25" }, "filledSize": { "type": "string", "description": "Total base size filled across all child orders", "example": "10.00" }, "totalSize": { "type": "string", "description": "Total target base size of the TWAP order", "example": "20.30" }, "totalFees": { "type": "string", "description": "Total fees paid across all child orders", "example": "0.152" }, "orderStatus": { "type": "string", "description": "Status of the TWAP order", "example": "running" }, "reduceOnly": { "type": "boolean", "description": "Whether child orders are reduce-only", "example": false }, "maxPrice": { "type": "string", "description": "Maximum allowed price for child orders (omitted if not set)", "example": "160.00" }, "minPrice": { "type": "string", "description": "Minimum allowed price for child orders (omitted if not set)", "example": "140.00" }, "successfulOrders": { "type": "integer", "description": "Number of successfully placed child orders (omitted if zero)", "example": 30 }, "failedOrders": { "type": "integer", "description": "Number of failed child order placements (omitted if zero)", "example": 0 }, "twapCancelReason": { "type": "integer", "description": "Reason the TWAP order was cancelled (only set if cancelled). Values: `0` not cancelled, `1` cancelled by user, `2` cancelled after too many failed child orders.", "enum": [ 0, 1, 2 ], "example": 1 }, "lastChildOrderError": { "type": "string", "description": "Error code of the last failed child order (only set for running orders, never for historical)", "example": "twap_child_order_not_fully_filled" } } }, "StatusResult": { "type": "object", "properties": { "marketStatus": { "type": "string", "description": "Current market status information" } } }, "AccountInfo": { "type": "object", "required": [ "accountID", "identifier", "authType", "accountState", "withdrawalFeeUSD", "termsVersion", "termsUnixSecs", "privacyVersion", "privacyUnixSecs", "marketingConsent" ], "properties": { "accountID": { "type": "string", "description": "Account ID", "example": "10458932786832481" }, "identifier": { "type": "string", "description": "Account identifier (wallet address or email)" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "web3", "web2:email_pass", "web2:google", "unknown" ] }, "accountState": { "type": "string", "description": "Account state", "enum": [ "open", "disabled", "offboarding", "closed" ] }, "withdrawalFeeUSD": { "type": "string", "description": "Withdrawal fee in USD" }, "disabledFunctionality": { "$ref": "#/components/schemas/DisabledFunctionality" }, "termsVersion": { "type": "integer", "description": "Terms of service version accepted" }, "termsUnixSecs": { "type": "integer", "description": "Unix timestamp when terms were accepted" }, "privacyVersion": { "type": "integer", "description": "Privacy policy version accepted" }, "privacyUnixSecs": { "type": "integer", "description": "Unix timestamp when privacy policy was accepted" }, "marketingConsent": { "type": "string", "description": "Marketing consent value" }, "subaccountsLimit": { "type": "integer", "description": "Maximum number of subaccounts this account is allowed to create", "example": 256 }, "cooldownPeriodSecs": { "type": "integer", "description": "Withdrawal-address cooldown duration in seconds. `0` means no cooldown is currently active.", "example": 0 }, "pointsState": { "type": "integer", "description": "User-facing state of the points product. The frontend uses this to decide whether to render the points link and what content to show.", "enum": [0, 1, 2], "x-enum-descriptions": { "0": "disabled", "1": "coming soon", "2": "live" }, "example": 0 } } }, "DisabledFunctionality": { "type": "object", "properties": { "disableTransfers": { "type": "boolean" }, "disableWallet": { "type": "boolean" }, "disableBalance": { "type": "boolean" }, "disablePerps": { "type": "boolean" }, "disableAPIKeys": { "type": "boolean" }, "disableSubaccounts": { "type": "boolean", "description": "If true, subaccount creation and management is disabled for this account." }, "disableNetworkLink": { "type": "boolean" }, "disableReferrals": { "type": "boolean", "description": "If true, the referrals feature is disabled for this account." }, "disableAlphaStrategies": { "type": "boolean", "description": "If true, the alpha strategies feature is disabled for this account." }, "disableAlphaStrategiesCreation": { "type": "boolean", "description": "If true, creation of new alpha strategies is disabled for this account." }, "disableWalletLogins": { "type": "boolean" }, "disableChat": { "type": "boolean", "description": "If true, in-app chat is disabled for this account." }, "disableMAC": { "type": "boolean", "description": "If true, multi-asset collateral (MAC) is disabled for this account." }, "disableBasisTradeAccounts": { "type": "boolean", "description": "If true, basis-trade account creation and management is disabled for this account." } } }, "ApiKeyScope": { "type": "string", "enum": [ "trade", "transfer" ], "description": "API key permission scope" }, "ApiKeyInfo": { "type": "object", "required": [ "keyId", "name", "createdAt", "scopes" ], "properties": { "keyId": { "type": "string", "description": "API key ID" }, "name": { "type": "string", "description": "Key name" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the key was created" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "description": "Permitted scopes" }, "whitelistedIPs": { "type": "array", "items": { "type": "string" }, "description": "Whitelisted IP addresses" } } }, "ApiKeyCreateResult": { "type": "object", "required": [ "keyId", "name", "createdAt", "scopes", "secretKey" ], "properties": { "keyId": { "type": "string", "description": "API key ID" }, "name": { "type": "string", "description": "Key name" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the key was created" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "description": "Permitted scopes" }, "secretKey": { "type": "string", "description": "API secret key. Only returned once at creation time." } } }, "OpenOrderCounts": { "type": "object", "properties": { "spot": { "type": "object", "properties": { "open": { "type": "integer", "description": "Number of open spot orders" } } }, "perps": { "type": "object", "properties": { "open": { "type": "integer", "description": "Number of open perps orders" } } } } }, "WithdrawalStatusResult": { "type": "object", "required": [ "original_request", "withdrawal_id", "txid", "confirmation_number", "withdrawal_status" ], "properties": { "original_request": { "type": "object", "description": "The original withdrawal request", "properties": { "account_id": { "type": "string" }, "customer_withdrawal_id": { "type": "string" }, "symbol": { "type": "string" }, "amount": { "type": "string" }, "address": { "type": "string" }, "network": { "type": "string", "enum": [ "avalanche", "ethereum", "solana" ] }, "from": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "withdrawal_id": { "type": "string", "description": "Internal withdrawal ID" }, "txid": { "type": "string", "description": "On-chain transaction ID" }, "confirmation_number": { "type": "integer", "description": "Number of confirmations" }, "withdrawal_status": { "type": "string", "description": "Current withdrawal status", "enum": [ "complete", "failure", "pending", "cancelled", "unknown" ] } } }, "PerpsTradingPair": { "type": "object", "description": "Perpetual futures trading pair configuration", "properties": { "market": { "type": "string", "description": "Market identifier (e.g. AAPL-USD.P)", "example": "AAPL-USD.P" }, "baseIncrement": { "type": "string", "description": "Minimum size increment in base currency", "example": "0.01" }, "quoteIncrement": { "type": "string", "description": "Minimum price increment in quote currency", "example": "0.01" } } }, "MarketsResult": { "type": "object", "properties": { "perps": { "type": "object", "description": "Perpetual futures markets", "properties": { "tradingPairs": { "type": "array", "items": { "$ref": "#/components/schemas/PerpsTradingPair" }, "description": "Available perps trading pairs and their configuration" } } }, "tokenConfig": { "type": "array", "description": "Token configuration for supported assets", "items": { "$ref": "#/components/schemas/TokenConfig" } } } }, "TokenConfig": { "type": "object", "properties": { "id": { "type": "string", "description": "Token symbol identifier", "example": "USDC" }, "name": { "type": "string", "description": "Token display name", "example": "USD Coin" }, "decimals": { "type": "integer", "description": "Display decimals" }, "tokenDecimals": { "type": "integer", "description": "On-chain token decimals" }, "networks": { "type": "object", "description": "Supported networks and contract addresses", "additionalProperties": { "type": "object", "properties": { "contractAddresses": { "type": "object", "additionalProperties": { "type": "string" } } } } }, "ucid": { "type": "integer", "description": "Unified coin ID" }, "coinGeckoId": { "type": "string" }, "coinGeckoCurrency": { "type": "string" }, "bridgeInfoUrl": { "type": "string" }, "description": { "type": "string" } } }, "ProvisionAddressResult": { "type": "object", "required": [ "chain", "accountId", "symbol", "address" ], "properties": { "chain": { "type": "string", "description": "Blockchain network", "example": "ethereum" }, "accountId": { "type": "string", "description": "Account ID" }, "symbol": { "type": "string", "description": "Token symbol", "example": "USDC" }, "address": { "type": "string", "description": "Provisioned deposit address" } } }, "SandboxDepositResult": { "type": "object", "properties": { "deposit_address": { "type": "string", "description": "Deposit address used" }, "txn_hash": { "type": "string", "description": "Transaction hash of the sandbox deposit" } } }, "WithdrawalResult": { "type": "object", "required": [ "withdrawal_status", "withdrawal_id", "customer_withdrawal_id" ], "properties": { "withdrawal_status": { "type": "string", "description": "Status of the withdrawal", "example": "pending", "enum": [ "complete", "failure", "pending", "cancelled", "unknown" ] }, "withdrawal_id": { "type": "string", "description": "Internal withdrawal ID" }, "customer_withdrawal_id": { "type": "string", "description": "Customer-provided withdrawal ID" }, "hash": { "type": "string", "description": "On-chain transaction hash (when available)" } } }, "AddressBookResult": { "type": "object", "properties": { "addressBook": { "type": "array", "description": "List of withdrawal addresses", "items": { "$ref": "#/components/schemas/AddressBookEntry" } } } }, "AddressBookEntry": { "type": "object", "required": [ "withdrawalAddress", "label", "lastUpdated" ], "properties": { "withdrawalAddress": { "type": "string", "description": "Withdrawal address" }, "label": { "type": "string", "description": "User-defined label for the address" }, "lastUpdated": { "type": "string", "format": "date-time", "description": "When the entry was last updated" } } }, "DepositAddress": { "type": "object", "required": [ "coin", "network", "address", "depositDestination" ], "properties": { "coin": { "type": "string", "description": "Token symbol", "example": "USDC" }, "network": { "type": "string", "description": "Blockchain network", "example": "ethereum", "enum": [ "avalanche", "ethereum", "solana" ] }, "address": { "type": "string", "description": "Deposit address" }, "depositDestination": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "WalletDeposit": { "type": "object", "required": [ "coin", "size", "status", "txid", "fromAddress", "time", "chainId", "usdValue" ], "properties": { "coin": { "type": "string", "description": "Token symbol", "example": "USDC" }, "size": { "type": "string", "description": "Deposit amount", "example": "100.00" }, "status": { "type": "string", "description": "Deposit status", "enum": [ "pending", "confirmed" ], "example": "confirmed" }, "txid": { "type": "string", "description": "On-chain transaction ID" }, "fromAddress": { "type": "string", "description": "Sender address" }, "time": { "type": "string", "format": "date-time", "description": "Deposit time" }, "currentConfirmations": { "type": "integer", "description": "Current number of confirmations" }, "requiredConfirmations": { "type": "integer", "description": "Required confirmations for finality" }, "accountId": { "type": "string", "description": "Account ID" }, "chainId": { "type": "string", "description": "Chain ID", "enum": [ "avax-c-chain", "avax-fuji-c-chain", "eth-mainnet", "eth-sepolia", "btc-mainnet", "btc-testnet", "sol-mainnet", "sol-testnet", "bsc-mainnet", "bsc-testnet" ], "example": "eth-mainnet" }, "usdValue": { "type": "string", "description": "USD value of the deposit" }, "logIndex": { "type": "string", "description": "Log index in the transaction" } } }, "WalletWithdrawal": { "type": "object", "required": [ "coin", "size", "status", "address", "withdrawal_id", "txid", "customer_withdrawal_id", "time", "chainId" ], "properties": { "coin": { "type": "string", "description": "Token symbol", "example": "USDC" }, "size": { "type": "string", "description": "Withdrawal amount", "example": "100.00" }, "status": { "type": "string", "description": "Withdrawal status", "enum": [ "complete", "failure", "pending", "cancelled", "unknown" ], "example": "complete" }, "address": { "type": "string", "description": "Destination address" }, "withdrawal_id": { "type": "string", "description": "Internal withdrawal ID" }, "txid": { "type": "string", "description": "On-chain transaction ID" }, "customer_withdrawal_id": { "type": "string", "description": "Customer-provided withdrawal ID" }, "time": { "type": "string", "format": "date-time", "description": "Withdrawal time" }, "accountId": { "type": "string", "description": "Account ID" }, "usdValue": { "type": "string", "description": "USD value of the withdrawal" }, "usdFee": { "type": "string", "description": "USD fee for the withdrawal" }, "chainId": { "type": "string", "description": "Chain ID", "enum": [ "avax-c-chain", "avax-fuji-c-chain", "eth-mainnet", "eth-sepolia", "btc-mainnet", "btc-testnet", "sol-mainnet", "sol-testnet", "bsc-mainnet", "bsc-testnet" ], "example": "eth-mainnet" }, "from": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "WithdrawalLimits": { "type": "object", "required": [ "currentWithdrawalsUsd", "withdrawalLimitUsd" ], "properties": { "currentWithdrawalsUsd": { "type": "string", "description": "Current withdrawal amount used in this period (USD)", "example": "500.00" }, "withdrawalLimitUsd": { "type": "string", "description": "Maximum withdrawal amount allowed in this period (USD)", "example": "50000.00" } } }, "AuthChallengeResult": { "type": "object", "required": [ "id", "message" ], "properties": { "id": { "type": "string", "description": "Challenge ID", "example": "abc123" }, "message": { "type": "string", "description": "Message to be signed by the wallet" } } }, "AuthToken": { "type": "object", "required": [ "identifier", "authType", "accountId", "issuedAtSecs", "expirationSecs", "token", "newAccount" ], "properties": { "identifier": { "type": "string", "description": "Wallet address or email" }, "authType": { "type": "string", "description": "Authentication type", "enum": [ "web3", "web2:email_pass", "web2:google", "unknown" ] }, "accountId": { "type": "string", "description": "Account ID" }, "issuedAtSecs": { "type": "integer", "description": "Token issue time (Unix seconds)" }, "expirationSecs": { "type": "integer", "description": "Token expiration time (Unix seconds)" }, "token": { "type": "string", "description": "JWT token" }, "newAccount": { "type": "boolean", "description": "True if a new account was created during this login" } } }, "ApiKeysCreateRequest": { "type": "object", "required": [ "name", "scopes" ], "properties": { "name": { "type": "string", "description": "Human-readable name for the API key", "example": "Trading Bot" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyScope" }, "description": "Permission scopes for the API key", "example": [ "trade", "transfer" ] } } }, "ApiKeyWhitelistRequest": { "type": "object", "required": [ "ip" ], "properties": { "ip": { "type": "string", "description": "IP address to whitelist", "example": "192.168.1.1" } } }, "AddressBookCompleteChallengeRequest": { "type": "object", "required": [ "id", "signature" ], "properties": { "id": { "type": "string", "description": "The ID of the challenge", "example": "chg_ab12cd34ef56" }, "signature": { "type": "string", "description": "The signed challenge proving wallet ownership", "example": "d5ee68784479z8n5utzebecfbd6926a89d7e24e9z5nut313611186z0da4206be4e57b809cbb3372d52b865bda7f372ea0808286009e572a66c8ab717cf85cdbc1b" }, "addressLabel": { "type": "string", "description": "Optional label for the withdrawal address", "example": "My Ledger Nano X" } } }, "AddressBookGetChallengeRequest": { "type": "object", "required": [ "walletAddress", "chainId", "withdrawalAddress" ], "properties": { "walletAddress": { "type": "string", "description": "The wallet address requesting to add a withdrawal address", "example": "0x505D602729B932959935C1efd350Cea74527d3D1" }, "chainId": { "type": "string", "description": "EVM chain ID (1=Ethereum, 43114=Avalanche)", "example": "43114", "enum": [ "1", "43114" ] }, "withdrawalAddress": { "type": "string", "description": "The address to add to the withdrawal address book", "example": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF" } } }, "LoginCompleteChallengeRequest": { "type": "object", "required": [ "id", "signature" ], "properties": { "id": { "type": "string", "description": "The ID of the login challenge", "example": "ub6EabCuCiw9HvYyhsZhWzv8mntMgZ-vDGzZKvvCi_o=" }, "signature": { "type": "string", "description": "The signed challenge proving wallet ownership", "example": "8650fc18ca35d1e3c358b566ff786783978dc16519c055ba2085a2345bed89f46719876e3e01cf3bbf94c50f6b5524c3df3d9881386f11910ddb3a15bfade5f21c" }, "source": { "type": "string", "description": "Optional source identifier", "example": "web" } } }, "LoginGetChallengeRequest": { "type": "object", "required": [ "walletAddress", "chainId" ], "properties": { "walletAddress": { "type": "string", "description": "The wallet address requesting to sign in", "example": "0x742d35Cc6634C0532925a3b844Bc9e7595f2bD18" }, "chainId": { "type": "string", "description": "EVM chain ID (1=Ethereum, 43114=Avalanche)", "example": "1", "enum": [ "1", "43114" ] } } }, "GetWithdrawalStatusRequest": { "type": "object", "description": "Provide exactly one of withdrawal_id or customer_withdrawal_id", "properties": { "withdrawal_id": { "type": "string", "description": "The platform-assigned withdrawal ID", "example": "w_9f8e7d6c5b4a3210" }, "customer_withdrawal_id": { "type": "string", "description": "The user-specified withdrawal ID", "example": "my-withdrawal-001" } } }, "ProvisionAddressRequest": { "type": "object", "required": [ "network", "symbol", "deposit_destination" ], "properties": { "network": { "type": "string", "description": "Blockchain network", "example": "ethereum", "enum": [ "avalanche", "ethereum", "solana" ] }, "symbol": { "type": "string", "description": "Token symbol", "example": "USDC" }, "deposit_destination": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "SandboxDepositRequest": { "type": "object", "required": [ "amount", "symbol", "deposit_destination", "chain_id" ], "properties": { "amount": { "type": "string", "description": "Deposit amount as a decimal string", "example": "1000.00" }, "symbol": { "type": "string", "description": "Token symbol", "example": "USDC" }, "deposit_destination": { "$ref": "#/components/schemas/AccountWalletKey" }, "chain_id": { "type": "string", "description": "Chain ID for the deposit", "example": "eth-mainnet", "enum": [ "avax-c-chain", "avax-fuji-c-chain", "eth-mainnet", "eth-sepolia", "btc-mainnet", "btc-testnet", "sol-mainnet", "sol-testnet", "bsc-mainnet", "bsc-testnet" ] } } }, "SandboxWithdrawalRequest": { "type": "object", "required": [ "customer_withdrawal_id", "symbol", "amount", "from" ], "properties": { "customer_withdrawal_id": { "type": "string", "description": "User-specified withdrawal identifier", "example": "my-withdrawal-001" }, "symbol": { "type": "string", "description": "Token symbol", "example": "USDC" }, "amount": { "type": "string", "description": "Withdrawal amount as a decimal string", "example": "500.00" }, "from": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "EditWithdrawalAddressRequest": { "type": "object", "required": [ "withdrawalAddress" ], "properties": { "withdrawalAddress": { "type": "string", "description": "The withdrawal address to edit", "example": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF" }, "addressLabel": { "type": "string", "description": "Updated label for the address", "example": "My Ledger Nano X" } } }, "DeleteWithdrawalAddressRequest": { "type": "object", "required": [ "withdrawalAddress" ], "properties": { "withdrawalAddress": { "type": "string", "description": "The withdrawal address to remove", "example": "0x054A94b753CBf65D1Bc484F6D41897b48251fbfF" } } }, "DepositAddressListRequest": { "type": "object", "required": [ "coins" ], "properties": { "coins": { "type": "array", "items": { "type": "string" }, "description": "List of token symbols to retrieve deposit addresses for", "example": [ "USDC" ] }, "network": { "type": "string", "description": "Filter by network; omit to list all networks", "example": "ethereum", "enum": [ "avalanche", "ethereum", "solana" ] }, "depositDestination": { "$ref": "#/components/schemas/AccountWalletKey" } } }, "UnixTimeRangeRequest": { "type": "object", "properties": { "start_time": { "type": "integer", "format": "int64", "description": "Start time as Unix timestamp in seconds", "example": 1666203390 }, "end_time": { "type": "integer", "format": "int64", "description": "End time as Unix timestamp in seconds", "example": 1709734800 } } } }, "responses": { "BadRequest": { "description": "Bad request. The request was malformed or failed validation.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": false, "error": "Description of the validation error", "error_code": "bad_query_param" } } } }, "Unauthorized": { "description": "Authentication required. Provide a valid JWT or API key.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "api_key_not_found", "auth_expired", "auth_invalid", "auth_missing", "failed_to_decode_hex_signature", "failed_to_parse_timestamp", "signature_mismatch", "timestamp_too_far" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "auth_missing" } } } }, "Forbidden": { "description": "Access denied. The authenticated account does not have permission.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "account_closed", "account_not_allowed", "forbidden", "ip_not_permitted", "key_doesnt_have_scope" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "account_not_allowed" } } } }, "NotFound": { "description": "The requested resource was not found.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GenericResponse" }, "example": { "success": false, "error": "Resource not found", "error_code": "not_found" } } } }, "TooManyRequests": { "description": "Rate limit exceeded. Slow down request frequency.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "too_many_requests" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "too_many_requests" } } } }, "InternalServerError": { "description": "Internal server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "success": { "type": "boolean", "example": false }, "error": { "type": "string", "description": "Human-readable error message" }, "error_code": { "type": "string", "enum": [ "server_is_busy", "service_unavailable", "unknown" ] } } }, "example": { "success": false, "error": "Description of the error", "error_code": "unknown" } } } } } } }