{ "openapi": "3.1.0", "info": { "title": "ekiden-gateway", "description": "API Gateway and WebSocket proxy based on Axum and Utoipa, handling auth, rate limiting, and connection buffering.", "license": { "name": "" }, "version": "0.1.1" }, "servers": [ { "url": "https://api.ekiden.fi/", "description": "Production" }, { "url": "https://api.cnt.ekiden.fi/", "description": "Testnet" }, { "url": "https://api.canton.ekiden.fi/", "description": "Staging" } ], "paths": { "/api/v1/access/activate": { "post": { "tags": [ "Access" ], "summary": "Activate a closed-launch access code", "operationId": "activate", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessActivateRequest" } } }, "required": true }, "responses": { "200": { "description": "Wallet activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessActivateResponse" } } } }, "400": { "description": "Invalid, expired, or revoked code" }, "401": { "description": "Bad or stale signature" }, "404": { "description": "Access module disabled" }, "409": { "description": "Code already used or wallet already activated" }, "429": { "description": "Rate limited" } } } }, "/api/v1/account/balance": { "get": { "tags": [ "Account" ], "summary": "Get Account Balance", "description": "Query account balances. Returns all subaccounts' vault balances.", "operationId": "get_account_balance", "responses": { "200": { "description": "Balances", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAccountBalanceResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/account/fund": { "post": { "tags": [ "Account" ], "operationId": "fund", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundRequest" } } }, "required": true }, "responses": { "200": { "description": "Funding request successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundResult" } } } }, "400": { "description": "Invalid request", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "429": { "description": "Rate limit exceeded", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } }, "500": { "description": "Internal server error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } } } }, "/api/v1/account/statistics": { "get": { "tags": [ "Account" ], "summary": "Get Account Statistics", "description": "Query account equity, PnL, volume, and ROI. Optional step: hour/day/week/month. Newest `limit` rows (default 100, max 1000).", "operationId": "get_account_statistics", "parameters": [ { "name": "sub_account_address", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "step", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Temporal resolution for statistics. Single-letter shorthands are allowed(h/d/w/m).", "enum": [ "hour", "day", "week", "month" ] } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "sorting_order", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "type": "string", "description": "Sort direction for account statistics snapshots (older/newer first).", "enum": [ "asc", "desc" ] } ] } } ], "responses": { "200": { "description": "Account statistics", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAccountStatisticsResponse" } } } }, "400": { "description": "Bad Request" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/authorize": { "post": { "tags": [ "User" ], "summary": "Authorize User", "description": "Authorize and obtain an access token", "operationId": "authorize", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeRequest" } } }, "required": true }, "responses": { "200": { "description": "Successfully authorized and token generated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthorizeResponse" } } } } } } }, "/api/v1/authorize/provision": { "post": { "tags": [ "User" ], "summary": "Provision Canton OIDC Ledger User", "description": "Verify an OIDC id_token and ensure a Ledger API user/party exists for its `sub`", "operationId": "provision", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CantonProvisionRequest" } } }, "required": true }, "responses": { "200": { "description": "Ledger user ensured", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CantonProvisionResponse" } } } } } } }, "/api/v1/authorize/whitelist/check": { "get": { "tags": [ "User" ], "operationId": "check_root_whitelist", "parameters": [ { "name": "root_address", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "root_public_key", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Whitelist status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootWhitelistResponse" } } } }, "400": { "description": "Bad request" } } } }, "/api/v1/authorize/whitelist/{root_address}": { "put": { "tags": [ "User" ], "operationId": "add_root_whitelist_entry", "parameters": [ { "name": "root_address", "in": "path", "description": "Canonical or short Aptos root address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Root address added to whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootWhitelistResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "root_whitelist_basic_auth": [] } ] }, "delete": { "tags": [ "User" ], "operationId": "remove_root_whitelist_entry", "parameters": [ { "name": "root_address", "in": "path", "description": "Canonical or short Aptos root address", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Root address removed from whitelist", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RootWhitelistResponse" } } } }, "401": { "description": "Unauthorized" }, "500": { "description": "Internal server error" } }, "security": [ { "root_whitelist_basic_auth": [] } ] } }, "/api/v1/competitions": { "get": { "tags": [ "competitions" ], "operationId": "get_public_competitions", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompetitionStatus" } ] } } ], "responses": { "200": { "description": "Public competitions list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompetitionsResponse" } } } } } } }, "/api/v1/competitions/{competition_slug}": { "get": { "tags": [ "competitions" ], "operationId": "get_public_competition", "parameters": [ { "name": "competition_slug", "in": "path", "description": "Competition slug", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Public competition detail", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionSummary" } } } }, "404": { "description": "Competition not found" } } } }, "/api/v1/competitions/{competition_slug}/leaderboard": { "get": { "tags": [ "competitions" ], "operationId": "get_public_competition_leaderboard", "parameters": [ { "name": "competition_slug", "in": "path", "description": "Competition slug", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "sub_account", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Public competition leaderboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionLeaderboardResponse" } } } }, "404": { "description": "Competition not found" } } } }, "/api/v1/execution/list": { "get": { "tags": [ "Trade" ], "summary": "Get Trade History", "description": "Query users' execution records, sorted by execTime in descending order.", "operationId": "get_trade_history", "parameters": [ { "name": "sub_account_address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "order_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] } }, { "name": "order_link_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Trade history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTradeHistoryResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/info": { "get": { "tags": [ "System" ], "summary": "Get system configuration and discovery info", "operationId": "get_system_info", "responses": { "200": { "description": "System info retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SystemInfo" } } } } } } }, "/api/v1/market/account-ratio": { "get": { "tags": [ "Market" ], "summary": "Get Long Short Ratio", "description": "This refers to the net long and short positions as percentages of all position holders during the selected time.\nLong account ratio = Number of holders with long positions / Total number of holders\nShort account ratio = Number of holders with short positions / Total number of holders\nLong-short account ratio = Long account ratio / Short account ratio", "operationId": "get_long_short_ratio", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "period", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/IntervalTime" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Cursor. Use the next_page_cursor token from the response to retrieve the next page of the data set", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Long short ratio data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetLongShortRatioResponse" } } } } } } }, "/api/v1/market/adl-alert": { "get": { "tags": [ "Market" ], "summary": "Get ADL Alerts", "description": "Get the latest ADL alert snapshot for one symbol or all pools.", "operationId": "get_adl_alert", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } } ], "responses": { "200": { "description": "ADL alert snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAdlAlertsResponse" } } } }, "503": { "description": "Trading temporarily unavailable" } } } }, "/api/v1/market/adl-alert/history": { "get": { "tags": [ "Market" ], "summary": "Get ADL Alert History", "description": "Get archived ADL alert snapshots for one symbol or all pools.", "operationId": "get_adl_alert_history", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "ADL alert history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetAdlAlertsHistoryResponse" } } } } } } }, "/api/v1/market/funding/history": { "get": { "tags": [ "Market" ], "summary": "Get Funding Rate History", "description": "Query for historical funding rates. Each symbol has a different funding interval. For example, if the interval is 8 hours and the current time is UTC 12, then it returns the last funding rate, which settled at UTC 8.", "operationId": "get_funding_rate_history", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Funding rate history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetFundingRateHistoryResponse" } } } } } } }, "/api/v1/market/index-price-kline": { "get": { "tags": [ "Market" ], "summary": "Get Index Price Kline", "description": "Query for historical index price klines. Charts are returned in groups based on the requested interval.", "operationId": "get_index_price_kline", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "interval", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Interval" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Klines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPriceKlineResponse" } } } } } } }, "/api/v1/market/instruments-info": { "get": { "tags": [ "Market" ], "operationId": "get_instruments_info", "responses": { "200": { "description": "Get all instruments information", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInstrumentsInfoResponse" } } } } } } }, "/api/v1/market/insurance-pool": { "get": { "tags": [ "Market" ], "summary": "Get Insurance Pool", "description": "Get the latest insurance pool snapshot for one symbol or all pools.", "operationId": "get_insurance_pool", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } } ], "responses": { "200": { "description": "Insurance pool snapshots", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsurancePoolResponse" } } } }, "503": { "description": "Trading temporarily unavailable" } } } }, "/api/v1/market/insurance-pool/history": { "get": { "tags": [ "Market" ], "summary": "Get Insurance Pool History", "description": "Get archived insurance pool snapshots for one symbol or all pools.", "operationId": "get_insurance_pool_history", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Insurance pool history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetInsurancePoolHistoryResponse" } } } } } } }, "/api/v1/market/kline": { "get": { "tags": [ "Market" ], "summary": "Get Kline", "description": "Query for historical klines (also known as candles/candlesticks). Charts are returned in groups based on the requested interval.", "operationId": "get_kline", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "interval", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Interval" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Klines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetKlineResponse" } } } } } } }, "/api/v1/market/mark-price-kline": { "get": { "tags": [ "Market" ], "summary": "Get Mark Price Kline", "description": "Query for historical mark price klines. Charts are returned in groups based on the requested interval.", "operationId": "get_mark_price_kline", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "interval", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Interval" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Klines", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPriceKlineResponse" } } } } } } }, "/api/v1/market/open-interest": { "get": { "tags": [ "Market" ], "summary": "Get Open Interest", "description": "Get historical open interest snapshots for one symbol. Values are returned as closed interval buckets sorted newest first.", "operationId": "get_open_interest", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "interval", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/IntervalTime" } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Open interest data", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOpenInterestResponse" } } } } } } }, "/api/v1/market/orderbook": { "get": { "tags": [ "Market" ], "summary": "Get Orderbook", "description": "Query for orderbook depth data.", "operationId": "get_orderbook", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } }, { "name": "depth", "in": "query", "description": "Depth level", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Depth" } ] } } ], "responses": { "200": { "description": "Orderbook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetOrderBookResponse" } } } } } } }, "/api/v1/market/price-limit": { "get": { "tags": [ "Market" ], "summary": "Get Order Price Limit", "description": "Query for order price limit parameters.", "operationId": "get_order_price_limit", "parameters": [ { "name": "symbol", "in": "query", "required": true, "schema": { "$ref": "#/components/schemas/Symbol" } } ], "responses": { "200": { "description": "Order price limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderPriceLimit" } } } } } } }, "/api/v1/market/recent-trade": { "get": { "tags": [ "Market" ], "summary": "Get Recent Trades", "description": "Query for recent public trades, optionally filtered by symbol.", "operationId": "get_recent_trade", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } ], "responses": { "200": { "description": "Recent trades", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRecentTradeResponse" } } } }, "400": { "description": "Bad Request" } } } }, "/api/v1/market/risk-limit": { "get": { "tags": [ "Market" ], "summary": "Get Risk Limit", "description": "Query for the risk limit margin parameters.", "operationId": "get_risk_limit", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "cursor", "in": "query", "description": "Cursor. Use the next_page_cursor token from the response to retrieve the next page of the data set", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Risk limit", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRiskLimitResponse" } } } } } } }, "/api/v1/market/stats": { "get": { "tags": [ "Market" ], "summary": "Get Stats", "description": "Query for period-filtered turnover, trades, open interest, and per-market stats.", "operationId": "get_stats", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "description": "Stats period. `24h`, `7d`, `30d`, or `all_time`.", "enum": [ "24h", "7d", "30d", "all_time" ] } } ], "responses": { "200": { "description": "Stats", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStatsResponse" } } } }, "400": { "description": "Bad Request" } } } }, "/api/v1/market/stats/volume": { "get": { "tags": [ "Market" ], "summary": "Get Stats Volume", "description": "Query for turnover time series and 24h/7d/30d/all_time aggregates.", "operationId": "get_stats_volume", "parameters": [ { "name": "period", "in": "query", "required": true, "schema": { "type": "string", "description": "Stats period. `24h`, `7d`, `30d`, or `all_time`.", "enum": [ "24h", "7d", "30d", "all_time" ] } }, { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } } ], "responses": { "200": { "description": "Turnover series", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetStatsVolumeResponse" } } } }, "400": { "description": "Bad Request" } } } }, "/api/v1/market/tickers": { "get": { "tags": [ "Market" ], "summary": "Get Tickers", "description": "Query for the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.", "operationId": "get_tickers", "parameters": [ { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } } ], "responses": { "200": { "description": "Tickers", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetTickersResponse" } } } }, "400": { "description": "Bad Request" }, "404": { "description": "Not Found: tickers" } } } }, "/api/v1/order/amend": { "post": { "tags": [ "Trade" ], "summary": "Amend Order", "description": "Amend an existing order", "operationId": "amend_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmendOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Order amended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AmendOrderResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/amend-batch": { "post": { "tags": [ "Trade" ], "summary": "Batch Amend Orders", "description": "Amend multiple existing orders in a single request", "operationId": "batch_amend_orders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAmendOrdersRequest" } } }, "required": true }, "responses": { "200": { "description": "Orders amended", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchAmendOrdersResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/cancel": { "post": { "tags": [ "Trade" ], "summary": "Cancel Order", "description": "Cancel an existing order", "operationId": "cancel_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Order canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelOrderResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/cancel-all": { "post": { "tags": [ "Trade" ], "summary": "Cancel All Orders", "description": "Cancel all existing orders for a sub-account. Optionally filtered by symbol; omit symbol to cancel open orders across all markets.", "operationId": "cancel_all_orders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllOrdersRequest" } } }, "required": true }, "responses": { "200": { "description": "Orders canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelAllOrdersResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/cancel-batch": { "post": { "tags": [ "Trade" ], "summary": "Batch Cancel Orders", "description": "Cancel multiple existing orders in a single request", "operationId": "batch_cancel_orders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCancelOrdersRequest" } } }, "required": true }, "responses": { "200": { "description": "Orders canceled", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchCancelOrdersResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/history": { "get": { "tags": [ "Trade" ], "summary": "Get Order History", "description": "Query order history. As order creation/cancellation is asynchronous, the data returned from this endpoint may delay.", "operationId": "get_history_orders", "parameters": [ { "name": "sub_account_address", "in": "query", "description": "Trading vault address (subaccount) to query against.", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "order_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] } }, { "name": "order_link_id", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } }, { "name": "order_filter", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderFilter" } ] } }, { "name": "order_status", "in": "query", "required": false, "schema": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/OrderStatus" } } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/place": { "post": { "tags": [ "Trade" ], "summary": "Place Order", "description": "Create a new order", "operationId": "place_order", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderRequest" } } }, "required": true }, "responses": { "200": { "description": "Order placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceOrderResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/place-batch": { "post": { "tags": [ "Trade" ], "summary": "Batch Place Orders", "description": "Create multiple new orders in a single request", "operationId": "batch_place_orders", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPlaceOrdersRequest" } } }, "required": true }, "responses": { "200": { "description": "Orders placed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BatchPlaceOrdersResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/order/realtime": { "get": { "tags": [ "Trade" ], "summary": "Get Open & Closed Orders", "description": "Primarily query unfilled or partially filled orders in real-time, but also supports querying recent 500 closed status (Cancelled, Filled) orders. Please see the usage of request param open_only.", "operationId": "get_realtime_orders", "parameters": [ { "name": "sub_account_address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "description": "Symbol name", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "order_id", "in": "query", "description": "Order ID", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] } }, { "name": "order_link_id", "in": "query", "description": "User customised order ID", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } }, { "name": "open_only", "in": "query", "description": "* `true` (default): query open status orders (New or PartiallyFilled).\n* `false`: query a maximum of recent 500 closed status orders (Cancelled, Rejected, Filled).", "required": false, "schema": { "type": "boolean" } }, { "name": "order_filter", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderFilter" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Orders", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderListResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/position/closed-pnl": { "get": { "tags": [ "Position" ], "summary": "Get Closed PnL", "description": "Query user's closed profit and loss records", "operationId": "get_closed_pnl", "parameters": [ { "name": "sub_account_address", "in": "query", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "start_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "end_time", "in": "query", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Closed PnL", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetClosedPnlResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/position/list": { "get": { "tags": [ "Position" ], "summary": "Get Position Info", "description": "Query real-time position data, such as position size, cumulative realized PNL, etc.", "operationId": "get_position_info", "parameters": [ { "name": "sub_account_address", "in": "query", "description": "Trading vault address (subaccount) to query against.", "required": true, "schema": { "type": "string" } }, { "name": "symbol", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol" } ] } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Positions", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetPositionInfoResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/position/set-leverage": { "post": { "tags": [ "Position" ], "summary": "Set leverage", "description": "Set leverage for a symbol", "operationId": "set_leverage", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLeverageRequest" } } }, "required": true }, "responses": { "200": { "description": "Leverage updated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetLeverageResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/position/trading-stop": { "post": { "tags": [ "Position" ], "summary": "Set Trading Stop", "description": "Set the take profit, stop loss or trailing stop for the position.", "operationId": "set_trading_stop", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTradingStopRequest" } } }, "required": true }, "responses": { "200": { "description": "Trading stop set", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SetTradingStopResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/referral/click": { "post": { "tags": [ "User" ], "operationId": "record_referral_click", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RecordReferralClickRequest" } } }, "required": true }, "responses": { "200": { "description": "Click recorded" }, "400": { "description": "Malformed code" } } } }, "/api/v1/user/access": { "get": { "tags": [ "User" ], "operationId": "get_user_access", "responses": { "200": { "description": "Stage-1 access standing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessStatusResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/access/activate": { "post": { "tags": [ "User" ], "operationId": "activate_user_access", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateAccessRequest" } } }, "required": true }, "responses": { "200": { "description": "Wallet activated", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AccessActivateResponse" } } } }, "400": { "description": "Invalid, expired, or revoked code" }, "403": { "description": "Bound sub-account session" }, "404": { "description": "Access module disabled" }, "409": { "description": "Code already used or wallet already activated" }, "429": { "description": "Rate limited" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/affiliate": { "get": { "tags": [ "User" ], "operationId": "get_user_affiliate", "responses": { "200": { "description": "Affiliate dashboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AffiliateDashboardResponse" } } } }, "404": { "description": "Not an affiliate" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/api-keys": { "get": { "tags": [ "user" ], "operationId": "list_api_keys", "responses": { "200": { "description": "List API keys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListApiKeysResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "user" ], "operationId": "create_api_key", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyRequest" } } }, "required": true }, "responses": { "200": { "description": "API key created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateApiKeyResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/api-keys/{id}": { "delete": { "tags": [ "user" ], "operationId": "revoke_api_key", "parameters": [ { "name": "id", "in": "path", "description": "API Key ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "API key revoked" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "API key not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/competitions": { "get": { "tags": [ "user" ], "operationId": "get_competitions", "parameters": [ { "name": "status", "in": "query", "required": false, "schema": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompetitionStatus" } ] } } ], "responses": { "200": { "description": "Competitions list", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListCompetitionsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/competitions/{competition_id}/leaderboard": { "get": { "tags": [ "user" ], "operationId": "get_competition_leaderboard", "parameters": [ { "name": "competition_id", "in": "path", "description": "Competition UUID", "required": true, "schema": { "type": "string" } }, { "name": "offset", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "sub_account", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Competition leaderboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionLeaderboardResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Competition not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/competitions/{competition_id}/placement": { "get": { "tags": [ "user" ], "operationId": "get_competition_placement", "parameters": [ { "name": "competition_id", "in": "path", "description": "Competition UUID", "required": true, "schema": { "type": "string" } }, { "name": "sub_account", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Own competition placement", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CompetitionPlacementResponse" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "404": { "description": "Competition not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/invite-codes": { "get": { "tags": [ "User" ], "operationId": "get_user_invite_codes", "responses": { "200": { "description": "Earned invite-code standing", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/InviteCodesResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "User" ], "operationId": "post_user_invite_codes", "responses": { "200": { "description": "One earned code minted", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MintInviteCodeResponse" } } } }, "409": { "description": "No earned code available to claim" }, "429": { "description": "Rate limited" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/leaderboard": { "get": { "tags": [ "Leaderboard" ], "summary": "Get Leaderboard", "description": "Paginated subaccount leaderboard ranked by PnL. Realized + unrealized (mark-to-market). Timeframe required: today, 7d, 30d, all. Default limit 10, max 100.", "operationId": "get_leaderboard", "parameters": [ { "name": "offset", "in": "query", "description": "Pagination offset (default 0).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "limit", "in": "query", "description": "Max number of entries to return (default 10, max 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "timeframe", "in": "query", "description": "Ranking window.", "required": true, "schema": { "type": "string", "description": "Leaderboard ranking window: today, last 7 days, last 30 days, or all time.", "enum": [ "today", "7d", "30d", "all" ] } } ], "responses": { "200": { "description": "Leaderboard", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardResponse" } } } } } } }, "/api/v1/user/leaderboard/placement": { "get": { "tags": [ "Leaderboard" ], "summary": "Get Leaderboard Placement", "description": "Placement(s) for the authenticated user. When sub_account is omitted, returns one entry per user trading subaccount; otherwise exactly one entry. When the user has no trading subaccounts, data is an empty array. If the account is not ranked, ranked is false and place is \"0\".", "operationId": "get_leaderboard_placement", "parameters": [ { "name": "sub_account", "in": "query", "description": "When set, return placement for this subaccount only; otherwise one entry per subaccount.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "timeframe", "in": "query", "description": "Ranking window.", "required": true, "schema": { "type": "string", "description": "Leaderboard ranking window: today, last 7 days, last 30 days, or all time.", "enum": [ "today", "7d", "30d", "all" ] } } ], "responses": { "200": { "description": "Placements (ranked false when not on board)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/LeaderboardPlacementResponse" } } } }, "400": { "description": "Bad Request (invalid sub_account or address)" }, "401": { "description": "Unauthorized" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/quests": { "get": { "tags": [ "User" ], "operationId": "get_user_quests", "responses": { "200": { "description": "Active quests with claim state", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/UserQuestsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/quests/{quest_id}/claim": { "post": { "tags": [ "User" ], "operationId": "claim_user_quest", "parameters": [ { "name": "quest_id", "in": "path", "description": "Quest UUID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Quest claimed", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ClaimQuestResponse" } } } }, "400": { "description": "Repeat, inactive, or ineligible claim" }, "404": { "description": "Unknown quest" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/referral": { "get": { "tags": [ "User" ], "operationId": "get_referral_summary", "responses": { "200": { "description": "Referral summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSummaryResponse" } } } } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "User" ], "operationId": "bind_referral", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BindReferralRequest" } } }, "required": true }, "responses": { "200": { "description": "Referral summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralSummaryResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/referral-codes": { "get": { "tags": [ "User" ], "operationId": "list_referral_codes", "responses": { "200": { "description": "List referral codes", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ListReferralCodesResponse" } } } }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] }, "post": { "tags": [ "User" ], "operationId": "create_referral_code", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CreateReferralCodeRequest" } } }, "required": true }, "responses": { "200": { "description": "Referral code created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralCodeInfo" } } } }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/referral-codes/{code_id}": { "delete": { "tags": [ "User" ], "operationId": "delete_referral_code", "parameters": [ { "name": "code_id", "in": "path", "description": "Referral code ID", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Referral code deleted" }, "400": { "description": "Bad request" }, "401": { "description": "Unauthorized" }, "403": { "description": "Forbidden" }, "404": { "description": "Referral code not found" } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/rewards": { "get": { "tags": [ "User" ], "operationId": "get_rewards_summary", "parameters": [ { "name": "limit", "in": "query", "description": "Ledger page size (default 20, max 100).", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } }, { "name": "cursor", "in": "query", "description": "Opaque cursor from a previous response's `next_cursor`.", "required": false, "schema": { "type": [ "string", "null" ] } } ], "responses": { "200": { "description": "Reward summary", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RewardSummaryResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/root-account": { "get": { "tags": [ "User" ], "summary": "Get Root Account", "description": "Return the Root Account address for the current user", "operationId": "get_root_account", "responses": { "200": { "description": "Root Account", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetRootAccountResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/season-claim/redeem": { "post": { "tags": [ "User" ], "summary": "`POST /user/season-claim/redeem` — verifies a season-claim voucher issued\nby the testnet side and redeems it (merging the testnet root's XP into\nthe caller's mainnet account), or dry-runs the entitlement when\n`preview` is set. Root-only, same as the issue side.", "operationId": "redeem_season_claim", "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemSeasonClaimRequest" } } }, "required": true }, "responses": { "200": { "description": "Redemption outcome", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RedeemSeasonClaimResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/season-claim/voucher": { "post": { "tags": [ "User" ], "summary": "`POST /user/season-claim/voucher` — issues a short-lived, server-signed\nvoucher attesting the caller's testnet root address. Root-only: a signed\nbearer proof of the wallet's identity is only meaningful for the wallet\nthat owns it.", "operationId": "issue_season_claim_voucher", "responses": { "200": { "description": "Season-claim voucher", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SeasonClaimVoucherResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } }, "/api/v1/user/sub-accounts": { "get": { "tags": [ "User" ], "summary": "Get Sub Accounts", "description": "List Sub Accounts under the Root Account", "operationId": "get_sub_accounts", "responses": { "200": { "description": "Sub Accounts", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetSubAccountsResponse" } } } } }, "security": [ { "bearer_auth": [] } ] } } }, "components": { "schemas": { "AccessActivateRequest": { "type": "object", "description": "Public Stage 1 activation request (spec §4). The caller is NOT yet\nwhitelisted. The wallet signs a canonical message that binds the code hash,\nits root address, and `signed_at`:\n`ekiden-stage1-activate:{sha256(normalized code)}:{root_address}:{signed_at}`\nusing the same wallet-signature scheme JWT login uses. The root address is\nderived from `public_key` (never trusted from the client), exactly as\n`/authorize` does.", "required": [ "code", "public_key", "signed_at", "signature" ], "properties": { "code": { "type": "string", "description": "Plaintext access code. Normalized (trim + uppercase) and hashed\nserver-side; the plaintext is never persisted (S1-D5)." }, "nonce": { "type": [ "string", "null" ], "description": "Replay nonce bound into the Canton activation message. REQUIRED on the\nCanton rail, ignored on Aptos." }, "party_id": { "type": [ "string", "null" ], "description": "Canton party id (`::`). REQUIRED on the Canton rail,\nignored on Aptos.\n\nCanton has no address derivable from the public key alone, so the wallet\nsigns for its party and the server derives the root from that party —\nthe same identity `/authorize` uses. The party's `::` suffix\ncommits to the public key, so a caller cannot claim someone else's party." }, "public_key": { "type": "string", "description": "Wallet public key, same encoding as `/authorize`'s `public_key`." }, "signature": { "type": "string", "description": "Wallet signature over the canonical activation message." }, "signed_at": { "type": "integer", "format": "int64", "description": "Unix seconds at which the message was signed. Must be within the\nconfigured signature window of server time." } } }, "AccessActivateResponse": { "type": "object", "required": [ "activated", "multiplier_bps", "badge" ], "properties": { "activated": { "type": "boolean" }, "badge": { "type": "boolean" }, "multiplier_bps": { "type": "integer", "format": "int32", "minimum": 0 } } }, "AccessStatusResponse": { "type": "object", "description": "`GET /user/access` response (spec §6): the authenticated wallet's Stage-1\nstanding — whether it activated, its cosmetic badge, and its granted\nmultiplier (null when never activated).", "required": [ "activated", "stage1_badge", "allocation_reserved" ], "properties": { "activated": { "type": "boolean", "description": "True once this wallet has activated a closed-launch access code." }, "allocation_reserved": { "type": "boolean", "description": "Whether a future airdrop allocation is reserved for this wallet\n(season1-conversion §5, S2-D3): true for every activated wallet, false\notherwise. The allocation itself is out of scope; this is the persistence\nhook that survives the Stage-1 gate-off." }, "multiplier_bps": { "type": [ "integer", "null" ], "format": "int32", "description": "Granted activation multiplier in bps; null when never activated.", "minimum": 0 }, "stage1_badge": { "type": "boolean", "description": "Cosmetic Stage-1 badge (spec §6); false for un-activated wallets." } } }, "AccountBalance": { "type": "object", "description": "Account-wide wallet and margin metrics.", "required": [ "sub_account_address", "account_type", "equity", "vault_balance", "margin_balance", "available_balance", "accrued_interest", "total_order_im", "total_position_im", "total_position_mm", "unrealised_pnl", "unrealized_funding", "realised_pnl_cum" ], "properties": { "account_type": { "type": "string", "description": "Account type (e.g. Funding, Trading)" }, "accrued_interest": { "type": "string", "description": "Accrued interest" }, "available_balance": { "type": "string", "description": "The amount of an asset that can be used to open USDC Perpetual positions (USDC)" }, "equity": { "type": "string", "description": "Equity under the account without considering the collateral value ratio (calculated in USDC).\nEquity = Vault Balance + Perp & Futures Unrealized P&L + Unrealized Funding" }, "margin_balance": { "type": "string", "description": "Amount that can be used as margin under the account\nafter considering the collateral value ratio (calculated in USDC)\nTotal Vault Balance + Perp Unrealized P&L" }, "realised_pnl_cum": { "type": "string", "description": "Cumulative Realised P&L" }, "sub_account_address": { "type": "string", "description": "Sub-Account address (the owner of the technical vault)" }, "total_order_im": { "type": "string", "description": "Pre-occupied margin for order. Locked balance (USDC)" }, "total_position_im": { "type": "string", "description": "Sum of initial margin of all positions." }, "total_position_mm": { "type": "string", "description": "Sum of maintenance margin for all positions, including estimated close fees." }, "unrealised_pnl": { "type": "string", "description": "Unrealised P&L" }, "unrealized_funding": { "type": "string", "description": "Aggregated unrealized funding across all positions (USDC)" }, "vault_balance": { "type": "string", "description": "Vault Balance (USDC)" } } }, "AccountStatistics": { "type": "object", "required": [ "sub_account_address", "equity", "realised_pnl_cum", "unrealised_pnl", "volume", "roi", "timestamp" ], "properties": { "equity": { "type": "string" }, "realised_pnl_cum": { "type": "string", "description": "Cumulative realized PnL of the closed positions, fees, and funding." }, "roi": { "type": "string" }, "sub_account_address": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" }, "unrealised_pnl": { "type": "string", "description": "Unrealized PnL of the current open positions." }, "volume": { "type": "string" } } }, "AccountStatisticsOrder": { "type": "string", "description": "Sort direction for account statistics snapshots (older/newer first).", "enum": [ "asc", "desc" ] }, "AccountStatisticsStep": { "type": "string", "description": "Temporal resolution for statistics. Single-letter shorthands are allowed(h/d/w/m).", "enum": [ "hour", "day", "week", "month" ] }, "ActivateAccessRequest": { "type": "object", "description": "`POST /user/access/activate` — redeem a closed-launch code for the\nauthenticated wallet.\n\nIdentity is the session, so the body carries nothing but the code. This\nreplaces the pre-auth signature ceremony below, which custodial (Auth0)\nwallets could never satisfy: they hold no signing key.", "required": [ "code" ], "properties": { "code": { "type": "string", "description": "Plaintext access code. Normalized (trim + uppercase) and hashed\nserver-side; the plaintext is never persisted (S1-D5)." } } }, "AdlAlertSnapshot": { "type": "object", "required": [ "pool_id", "pool_group_id", "symbol", "adl_mode", "equity", "updated_time" ], "properties": { "adl_mode": { "type": "string" }, "adl_trigger_reason": { "type": [ "string", "null" ] }, "equity": { "type": "string" }, "latest_pnl_ratio": { "type": [ "string", "null" ] }, "pool_group_id": { "type": "string" }, "pool_id": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "updated_time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "AdlRankIndicator": { "type": "string", "description": "Auto-deleverage rank indicator.", "enum": [ "Zero", "One", "Two", "Three", "Four", "Five" ] }, "AffiliateDashboardDownline": { "type": "object", "description": "Downline user counts at referral levels 1/2/3 below the affiliate (spec §7\n`downline`).", "required": [ "l1", "l2", "l3" ], "properties": { "l1": { "type": "integer", "format": "int64", "minimum": 0 }, "l2": { "type": "integer", "format": "int64", "minimum": 0 }, "l3": { "type": "integer", "format": "int64", "minimum": 0 } } }, "AffiliateDashboardRates": { "type": "object", "description": "Positional commission rates in bps (spec §7 `rates_bps`).", "required": [ "l1", "l2", "l3" ], "properties": { "l1": { "type": "integer", "format": "int32" }, "l2": { "type": "integer", "format": "int32" }, "l3": { "type": "integer", "format": "int32" } } }, "AffiliateDashboardResponse": { "type": "object", "description": "`GET /user/affiliate` response (spec §7). Returned only for an affiliate; a\nnon-affiliate wallet gets 404.", "required": [ "status", "rates_bps", "downline", "weeks", "pending_usdt" ], "properties": { "downline": { "$ref": "#/components/schemas/AffiliateDashboardDownline" }, "lifetime_paid_usdt_micro": { "type": "integer", "format": "int64", "description": "Lifetime SETTLED commission — the sum of `amount_usdt_micro` over this\naffiliate's `paid` weeks, in integer micro-USDT (6dp). Summed at the\ndatabase so it is exact regardless of the `weeks` page size. Integer\nmicro (not the decimal string the sibling money fields use) so the client\ncan total/compare it without parsing; `0` for an affiliate never paid." }, "pending_usdt": { "type": "string", "description": "Total computed-but-unpaid commission across all weeks, decimal USDT." }, "rates_bps": { "$ref": "#/components/schemas/AffiliateDashboardRates" }, "status": { "type": "string", "description": "Lifecycle status: `active` or `suspended`." }, "volume": { "$ref": "#/components/schemas/AffiliateDashboardVolume", "description": "Per-level downline volume (decimal USDC). Additive + defaulted." }, "weeks": { "type": "array", "items": { "$ref": "#/components/schemas/AffiliateDashboardWeek" }, "description": "Weekly commission history, newest week first." } } }, "AffiliateDashboardVolume": { "type": "object", "description": "Lifetime downline trading volume at levels 1/2/3, as decimal USDC strings\n(6dp). Strings because the totals can exceed a JS safe integer.", "required": [ "l1", "l2", "l3" ], "properties": { "l1": { "type": "string" }, "l2": { "type": "string" }, "l3": { "type": "string" } } }, "AffiliateDashboardWeek": { "type": "object", "description": "One week of the affiliate's commission history (spec §7 `weeks[]`).", "required": [ "week_start", "amount_usdt", "status", "breakdown" ], "properties": { "amount_usdt": { "type": "string", "description": "This week's commission for the affiliate, decimal USDT (e.g. `\"412.51\"`)." }, "breakdown": { "description": "Auditable `{l1,l2,l3}:{fees,bps,amount}` split (micro-USDT integers)." }, "paid_at_ms": { "type": [ "integer", "null" ], "format": "int64", "description": "PAYOUT RECEIPT — when the week was marked `paid`, epoch millis (the\ndashboard's ms convention). `null` while still `computed`." }, "status": { "type": "string", "description": "Per-affiliate payout status: `computed` (pending) or `paid`." }, "transfer_ref": { "type": [ "string", "null" ], "description": "PAYOUT RECEIPT — the settling transfer's reference (`tb:` on the\nTigerBeetle rail). `null` while the week is still `computed`. Additive:\nan older client that ignores it is unaffected." }, "week_start": { "type": "string", "description": "RFC3339 week start (Monday 00:00 UTC)." } } }, "AmendOrderRequest": { "type": "object", "description": "Request to amend an order.", "required": [ "sub_account_address", "symbol", "qty", "price" ], "properties": { "order_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] }, "order_iv": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] }, "price": { "type": "string" }, "qty": { "type": "string" }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "tpsl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSl" } ] }, "trigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalOrder" } ] } } }, "AmendOrderResponse": { "type": "object", "description": "Response for amending an order.", "properties": { "order_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } } }, "ApiKeyInfo": { "type": "object", "required": [ "id", "name", "public_key", "scopes", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "expires_at": { "type": [ "integer", "null" ], "format": "int64" }, "id": { "type": "string" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } } }, "AuthorizeRequest": { "type": "object", "required": [ "signature", "public_key", "timestamp_ms", "nonce" ], "properties": { "full_message": { "type": [ "string", "null" ], "description": "Optional Aptos Wallet Standard full message (APTOS-prefixed, newline-delimited).\nIf provided, the backend will verify the signature against this exact string\nand also validate that it contains `message: AUTHORIZE|{timestamp_ms}|{nonce}` and a matching `nonce:`.\n\nExample:\n\nAPTOS\\nmessage: AUTHORIZE|1731541800000|b7d1c2e8f5a94f3db2f8c6a9d1e4\\nnonce: b7d1c2e8f5a94f3db2f8c6a9d1e4" }, "id_token": { "type": [ "string", "null" ], "description": "Optional Auth0/OIDC `id_token` (RS256) for hosted Canton party auth." }, "nonce": { "type": "string", "description": "Example: b7d1c2e8f5a94f3db2f8c6a9d1e4" }, "party_id": { "type": [ "string", "null" ], "description": "Optional Canton party id (`::`) for Console (CIP-103) auth." }, "public_key": { "type": "string", "description": "Ed25519 public key as hex (`0x` optional) or standard base64.\n\nExample: 0xa9d81da788977638194c857b918f12ff2233c7a86e82b44705761b2d02426f6d" }, "signature": { "type": "string", "description": "Ed25519 signature as hex (`0x` optional) or standard base64.\nCanton Console: signs `EKIDEN-CANTON-AUTHORIZE|{party_id}|{timestamp_ms}|{nonce}`.\n\nExample: 0xf5ec808e52d014f5193eccf680acf84c6256bdddb0159088e7cb18d74b9c590b92eb4381e10307fccc0868612993dfb9a542257aab22d7a3decfda33045fb905" }, "timestamp_ms": { "type": "integer", "format": "int64", "description": "Example: 1731541800000" } } }, "AuthorizeResponse": { "type": "object", "required": [ "token", "user_id" ], "properties": { "token": { "type": "string" }, "user_id": { "$ref": "#/components/schemas/UserId" } } }, "BatchAmendOrdersRequest": { "type": "object", "description": "Batch amend order request.\nYou can amend unfilled or partially filled orders.\nTODO: Maximum 20 orders per request", "required": [ "request" ], "properties": { "await_outcome": { "type": "boolean", "description": "If true, gateway waits up to a server-defined timeout (currently 3s)\nfor final engine outcomes and maps them into `exit_info`.\n\nIf false (default), `exit_info` reports edge outcomes\n(validation + publish ack)." }, "request": { "type": "array", "items": { "$ref": "#/components/schemas/AmendOrderRequest" } } } }, "BatchAmendOrdersResponse": { "type": "object", "description": "Response of batch amend orders.", "required": [ "result", "exit_info", "time" ], "properties": { "exit_info": { "type": "array", "items": { "$ref": "#/components/schemas/ExitMessage" }, "description": "Information about the exit status of each order in the batch." }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/AmendOrderResponse" } }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "BatchCancelOrdersRequest": { "type": "object", "description": "Batch cancel order request.\nYou can cancel unfilled or partially filled orders.\nTODO: Maximum 20 orders per request", "required": [ "request" ], "properties": { "await_outcome": { "type": "boolean", "description": "If true, gateway waits up to a server-defined timeout (currently 3s)\nfor final engine outcomes and maps them into `exit_info`.\n\nIf false (default), `exit_info` reports edge outcomes\n(validation + publish ack)." }, "request": { "type": "array", "items": { "$ref": "#/components/schemas/CancelOrderRequest" } } } }, "BatchCancelOrdersResponse": { "type": "object", "description": "Response of batch cancel orders.", "required": [ "result", "exit_info", "time" ], "properties": { "exit_info": { "type": "array", "items": { "$ref": "#/components/schemas/ExitMessage" }, "description": "Information about the exit status of each order in the batch." }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CancelOrderResponse" } }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "BatchPlaceOrdersRequest": { "type": "object", "description": "Batch place order request.\nTODO: Maximum 20 orders per request\nTODO: Rate limiting (10 reqs per sec, 20 * 10 = 200 orders in one sec)", "required": [ "request" ], "properties": { "await_outcome": { "type": "boolean", "description": "If true, gateway waits up to a server-defined timeout (currently 3s)\nfor final engine outcomes and maps them into `exit_info`.\n\nIf false (default), `exit_info` reports edge outcomes\n(validation + publish ack)." }, "request": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceOrderRequest" } } } }, "BatchPlaceOrdersResponse": { "type": "object", "description": "Response of batch place orders.", "required": [ "result", "exit_info", "time" ], "properties": { "exit_info": { "type": "array", "items": { "$ref": "#/components/schemas/ExitMessage" }, "description": "Information about the exit status of each order in the batch." }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/PlaceOrderResponse" } }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "BindReferralRequest": { "type": "object", "required": [ "referral_code" ], "properties": { "referral_code": { "type": "string" } } }, "CancelAllOrdersRequest": { "type": "object", "description": "Request to cancel all orders, optionally filtered by symbol.\n\nOmit `symbol` to cancel every open order on the sub-account.\nSet `symbol` to cancel only open orders on that market.\nTODO: Cancels up to 500 orders per request\nTODO: System picks up 500 orders randomly to cancel when you have over 500 orders", "required": [ "sub_account_address" ], "properties": { "sub_account_address": { "type": "string" }, "symbol": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Symbol", "description": "Optional market filter. Omit to cancel open orders across all markets." } ] } } }, "CancelAllOrdersResponse": { "type": "object", "required": [ "result", "exit_info", "time" ], "properties": { "exit_info": { "$ref": "#/components/schemas/ExitMessage", "description": "Information about the exit status of the cancel all operation." }, "result": { "type": "array", "items": { "$ref": "#/components/schemas/CancelOrderResponse" } }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "CancelOrderRequest": { "type": "object", "description": "Request to cancel an order.", "required": [ "sub_account_address", "symbol" ], "properties": { "order_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "CancelOrderResponse": { "type": "object", "description": "Response for canceling an order.", "properties": { "order_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderId" } ] }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } } }, "CancelType": { "type": "string", "description": "Reason/Source of the order cancellation.", "enum": [ "CancelByUser", "CancelByAdmin", "CancelBySystem", "CancelByReduceOnly", "CancelByPrepareLiq", "CancelAllBeforeLiq", "CancelByPrepareAdl", "CancelAllBeforeAdl", "CancelBySettle", "CancelByTpSlTsClear", "CancelBySmp", "CancelByDcp", "CancelByRebalance", "CancelByOcoTpCanceledBySlTriggered", "CancelByOcoSlCanceledByTpTriggered" ] }, "CantonProvisionRequest": { "type": "object", "required": [ "id_token" ], "properties": { "id_token": { "type": "string" } } }, "CantonProvisionResponse": { "type": "object", "required": [ "party_id", "created" ], "properties": { "created": { "type": "boolean" }, "party_id": { "type": "string" } } }, "ClaimQuestResponse": { "type": "object", "description": "`POST /user/quests/{quest_id}/claim` response (spec §10): the credited\nreward. Repeat/inactive/ineligible claims are 400s, not bodies.", "required": [ "quest_id", "reward_xp" ], "properties": { "day": { "type": [ "string", "null" ], "description": "UTC day the claim is scoped to (daily quests only)." }, "quest_id": { "type": "string" }, "reward_xp": { "type": "string", "description": "XP credited by this claim." } } }, "ClosedPnl": { "type": "object", "description": "Closed PnL entry.", "required": [ "symbol", "order_id", "sub_account_address", "side", "qty", "order_price", "order_type", "exec_type", "closed_size", "cum_entry_value", "avg_entry_price", "cum_exit_value", "avg_exit_price", "closed_pnl", "fill_count", "leverage", "open_fee", "close_fee", "created_time", "updated_time" ], "properties": { "avg_entry_price": { "type": "string", "description": "Average entry price" }, "avg_exit_price": { "type": "string", "description": "Average exit price" }, "close_fee": { "type": "string", "description": "Close position trading fee" }, "closed_pnl": { "type": "string", "description": "Closed PnL" }, "closed_size": { "type": "string" }, "created_time": { "type": "string", "format": "date-time", "example": "1672531200000" }, "cum_entry_value": { "type": "string", "description": "Cumulated Position value" }, "cum_exit_value": { "type": "string", "description": "Cumulated exit position value" }, "exec_type": { "$ref": "#/components/schemas/ExecType" }, "fill_count": { "type": "string", "description": "The number of fills in a single order" }, "leverage": { "type": "string", "description": "Leverage" }, "open_fee": { "type": "string", "description": "Open position trading fee" }, "order_id": { "$ref": "#/components/schemas/OrderId" }, "order_price": { "type": "string" }, "order_type": { "$ref": "#/components/schemas/OrderType" }, "qty": { "type": "string" }, "side": { "$ref": "#/components/schemas/Side" }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "updated_time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "CompetitionLeaderboardData": { "type": "object", "required": [ "sub_account_address", "score", "metric_value", "active_days", "eligible", "projected_xp" ], "properties": { "active_days": { "type": "integer", "format": "int32", "description": "Number of days that met the daily-activity threshold.", "minimum": 0 }, "eligible": { "type": "boolean", "description": "Whether this entry is eligible to be ranked (min active days met, score > 0)." }, "ineligible_reason": { "type": [ "string", "null" ] }, "metric_value": { "type": "string", "description": "Raw metric total. For metric=pnl: closed PnL + fees + funding (excludes unrealized)." }, "projected_xp": { "type": "string", "description": "Live display-only XP projected from the current eligible leaderboard scores." }, "rank": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "score": { "type": "string", "description": "Weighted, capped score summed across all days." }, "sub_account_address": { "type": "string" } } }, "CompetitionLeaderboardMeta": { "type": "object", "required": [ "offset", "limit", "total" ], "properties": { "limit": { "type": "integer", "format": "int32", "minimum": 0 }, "offset": { "type": "integer", "format": "int32", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "minimum": 0 } } }, "CompetitionLeaderboardResponse": { "type": "object", "required": [ "competition", "data", "meta" ], "properties": { "competition": { "$ref": "#/components/schemas/CompetitionSummary" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionLeaderboardData" } }, "meta": { "$ref": "#/components/schemas/CompetitionLeaderboardMeta" } } }, "CompetitionMetric": { "type": "string", "enum": [ "volume", "pnl" ] }, "CompetitionPlacementResponse": { "type": "object", "required": [ "competition", "data" ], "properties": { "competition": { "$ref": "#/components/schemas/CompetitionSummary" }, "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionLeaderboardData" } } } }, "CompetitionScoringConfig": { "type": "object", "description": "Parameters that drive score calculation.\n\n- min_daily_activity_units is raw USDC 1e6 units.\n- All bps values are basis points (1 bp = 0.01%).", "required": [ "metric", "min_daily_activity_units", "min_active_days", "max_daily_contribution_bps", "start_weight_bps", "end_weight_bps" ], "properties": { "consistency_max_bonus_bps": { "type": [ "integer", "null" ], "format": "int32", "description": "Max bonus (bps) granted when a participant hits `consistency_target_days`.", "minimum": 0 }, "consistency_target_days": { "type": [ "integer", "null" ], "format": "int32", "description": "Target active day count for maximum bonus; required when `use_consistency_multiplier`.", "minimum": 0 }, "end_weight_bps": { "type": "integer", "format": "int32", "description": "Weight applied to the last day, in bps. Linear interpolation between start and end.", "minimum": 0 }, "max_daily_contribution_bps": { "type": "integer", "format": "int32", "description": "Per-day contribution cap as a fraction (bps) of the positive sum across the window.", "minimum": 0 }, "metric": { "$ref": "#/components/schemas/CompetitionMetric", "description": "Which metric to score." }, "min_active_days": { "type": "integer", "format": "int32", "description": "Required active days for a sub-account to qualify for a rank.", "minimum": 0 }, "min_daily_activity_units": { "type": "integer", "format": "int64", "description": "Minimum daily raw metric value (USDC 1e6 units) for a day to count toward `active_days`.", "minimum": 0 }, "start_weight_bps": { "type": "integer", "format": "int32", "description": "Weight applied to the first day, in bps (typical: 10000 = 100%).", "minimum": 0 }, "use_consistency_multiplier": { "type": "boolean", "description": "Whether to apply the consistency multiplier (scales with active days)." } } }, "CompetitionStatus": { "type": "string", "enum": [ "draft", "scheduled", "active", "ended", "cancelled" ] }, "CompetitionSummary": { "type": "object", "required": [ "id", "slug", "title", "status", "start_time_ms", "end_time_ms", "prize_usdc", "description_md", "scoring" ], "properties": { "description_md": { "type": "string" }, "end_time_ms": { "type": "integer", "format": "int64" }, "id": { "type": "string" }, "prize_usdc": { "type": "integer", "format": "int32", "minimum": 0 }, "scoring": { "$ref": "#/components/schemas/CompetitionScoringConfig" }, "slug": { "type": "string" }, "start_time_ms": { "type": "integer", "format": "int64" }, "status": { "$ref": "#/components/schemas/CompetitionStatus" }, "symbol": { "type": [ "string", "null" ] }, "title": { "type": "string" } } }, "ConditionalOrder": { "type": "object", "required": [ "trigger_price", "trigger_direction", "trigger_by" ], "properties": { "trigger_by": { "$ref": "#/components/schemas/TriggerBy", "description": "Last Price, Mark Price, or Index Price." }, "trigger_direction": { "$ref": "#/components/schemas/TriggerDirection", "description": "Up or Down." }, "trigger_price": { "type": "string", "description": "The price level that activates the order." } } }, "CreateApiKeyRequest": { "type": "object", "required": [ "name", "public_key", "scopes" ], "properties": { "expires_at": { "type": [ "integer", "null" ], "format": "int64" }, "name": { "type": "string" }, "public_key": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } } }, "CreateApiKeyResponse": { "type": "object", "required": [ "id", "public_key", "scopes", "created_at" ], "properties": { "created_at": { "type": "integer", "format": "int64" }, "expires_at": { "type": [ "integer", "null" ], "format": "int64" }, "id": { "type": "string" }, "public_key": { "type": "string" }, "scopes": { "type": "array", "items": { "$ref": "#/components/schemas/Scope" } } } }, "CreateReferralCodeRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" }, "label": { "type": [ "string", "null" ] } } }, "CreateType": { "type": "string", "enum": [ "CreateByUser", "CreateByFutureSpread", "CreateByAdminClosing", "CreateBySettle", "CreateByStopOrder", "CreateByTakeProfit", "CreateByPartialTakeProfit", "CreateByStopLoss", "CreateByPartialStopLoss", "CreateByTrailingStop", "CreateByTrailingProfit", "CreateByLiq", "CreateByTakeOverPassThrough", "CreateByAdlPassThrough", "CreateByBlockPassThrough", "CreateByBlockTradeMovePositionPassThrough", "CreateByClosing", "CreateByFGridBot", "CloseByFGridBot", "CreateByTWAP", "CreateByTVSignal", "CreateByMmRateClose", "CreateByMartingaleBot", "CloseByMartingaleBot", "CreateByIceBerg", "CreateByArbitrage", "CreateByDdh", "CreateByBboOrder" ] }, "ErrorResponse": { "type": "object", "required": [ "error", "message" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "reset_time": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "retry_after": { "type": [ "string", "null" ] } } }, "ExecType": { "type": "string", "description": "Execution type for trade history entries.", "enum": [ "Trade", "AdlTrade", "Funding", "BustTrade", "Delivery", "Settle", "BlockTrade", "MovePosition", "FutureSpread" ] }, "Execution": { "type": "object", "description": "Single execution (trade fill) record.", "required": [ "exec_id", "symbol", "order_id", "side", "sub_account_address", "order_price", "order_qty", "leaves_qty", "order_type", "exec_price", "exec_qty", "exec_value", "exec_type", "exec_time", "is_maker", "fee_rate", "base_fee", "mark_price", "index_price", "seq" ], "properties": { "base_fee": { "type": "string", "description": "Flat base fee charged on order creation." }, "closed_size": { "type": [ "string", "null" ], "description": "Closed position size" }, "create_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateType", "description": "Order create type" } ] }, "exec_id": { "$ref": "#/components/schemas/ExecutionId", "description": "Execution ID" }, "exec_price": { "type": "string", "description": "Execution price" }, "exec_qty": { "type": "string", "description": "Execution quantity" }, "exec_time": { "type": "string", "format": "date-time", "description": "Executed timestamp (ms)", "example": "1672531200000" }, "exec_type": { "$ref": "#/components/schemas/ExecType", "description": "Execution type (e.g. Trade, Adl, Bust)" }, "exec_value": { "type": "string", "description": "Executed value (price * qty)" }, "fee_rate": { "type": "string", "description": "Trading fee rate" }, "index_price": { "type": "string", "description": "Index price at execution" }, "is_maker": { "type": "boolean", "description": "Is maker order. true: maker, false: taker" }, "leaves_qty": { "type": "string", "description": "Remaining quantity not yet executed after this fill" }, "mark_price": { "type": "string", "description": "Mark price at execution" }, "order_id": { "$ref": "#/components/schemas/OrderId" }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] }, "order_price": { "type": "string", "description": "Original order price" }, "order_qty": { "type": "string", "description": "Original order quantity" }, "order_type": { "$ref": "#/components/schemas/OrderType", "description": "Order type. Market or Limit" }, "seq": { "type": "integer", "format": "int64", "description": "Cross sequence, used to associate each fill and each position update\n* The seq will be the same when conclude multiple transactions at the same time\n* Different symbols may have the same seq, please use seq + symbol to check unique", "minimum": 0 }, "side": { "$ref": "#/components/schemas/Side", "description": "Side. Buy or Sell" }, "stop_order_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StopOrderType", "description": "Stop order type if this was a stop order" } ] }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name, e.g. BTC-USDCx" } } }, "ExecutionId": { "type": "string", "format": "uuid" }, "ExitMessage": { "oneOf": [ { "type": "object", "required": [ "Error" ], "properties": { "Error": { "type": "object", "required": [ "code", "msg" ], "properties": { "code": { "type": "integer", "format": "int32", "minimum": 0 }, "msg": { "$ref": "#/components/schemas/String" } } } } }, { "type": "object", "required": [ "Success" ], "properties": { "Success": { "type": "object", "required": [ "code", "msg" ], "properties": { "code": { "type": "integer", "format": "int32", "minimum": 0 }, "msg": { "type": "string" } } } } } ] }, "FundRequest": { "type": "object", "required": [ "receiver", "metadatas", "amounts" ], "properties": { "amounts": { "type": "array", "items": { "type": "integer", "format": "int64", "minimum": 0 } }, "metadatas": { "type": "array", "items": { "type": "string" } }, "receiver": { "type": "string" }, "request_id": { "type": [ "string", "null" ] } } }, "FundResult": { "type": "object", "required": [ "txid" ], "properties": { "txid": { "type": "string" } } }, "FundingRateHistory": { "type": "object", "required": [ "symbol", "funding_rate", "funding_time" ], "properties": { "funding_rate": { "type": "string" }, "funding_time": { "type": "string", "format": "date-time", "example": "1672531200000" }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "GetAccountBalanceResponse": { "type": "object", "description": "Account balance response structure.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/AccountBalance" } } } }, "GetAccountStatisticsResponse": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/AccountStatistics" } } } }, "GetAdlAlertsHistoryResponse": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/AdlAlertSnapshot" } } } }, "GetAdlAlertsResponse": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/AdlAlertSnapshot" } } } }, "GetClosedPnlResponse": { "type": "object", "description": "Closed PnL response.", "required": [ "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/ClosedPnl" } }, "next_page_cursor": { "type": "string" } } }, "GetCompetitionLeaderboardParams": { "type": "object", "properties": { "limit": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "offset": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "sub_account": { "type": [ "string", "null" ] } } }, "GetCompetitionPlacementParams": { "type": "object", "properties": { "sub_account": { "type": [ "string", "null" ] } } }, "GetFundingRateHistoryResponse": { "type": "object", "description": "Funding rate history response.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/FundingRateHistory" } } } }, "GetInstrumentsInfoResponse": { "allOf": [ { "$ref": "#/components/schemas/SystemInfo" }, { "type": "object", "required": [ "category", "list" ], "properties": { "category": { "type": "string" }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/InstrumentInfo" } } } } ] }, "GetInsurancePoolHistoryResponse": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/InsurancePoolSnapshot" } } } }, "GetInsurancePoolResponse": { "type": "object", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/InsurancePoolSnapshot" } } } }, "GetKlineResponse": { "type": "object", "description": "Kline response.", "required": [ "symbol", "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/KlineSnapshot" } }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "GetLongShortRatioResponse": { "type": "object", "description": "This refers to the net long and short positions as percentages of all position holders during the selected time.", "required": [ "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/LongShortRatio" } }, "next_page_cursor": { "type": "string" } } }, "GetOpenInterestResponse": { "type": "object", "description": "Open interest response.", "required": [ "symbol", "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/OpenInterest" } }, "next_page_cursor": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "GetOrderBookResponse": { "type": "object", "description": "Get OrderBook response.", "required": [ "result", "time" ], "properties": { "result": { "$ref": "#/components/schemas/OrderBookSnapshot" }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "GetPositionInfoResponse": { "type": "object", "description": "Position info response.", "required": [ "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Position" } }, "next_page_cursor": { "type": "string", "description": "Cursor. Use the next_page_cursor token from the response to retrieve the next page of the data set" } } }, "GetPriceKlineResponse": { "type": "object", "description": "Price-only kline response.", "required": [ "symbol", "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/PriceKlineSnapshot" } }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "GetRecentTradeResponse": { "type": "object", "description": "Response for recent public trades.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/PublicTrade" } } } }, "GetRiskLimitResponse": { "type": "object", "description": "Risk limit response.", "required": [ "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/RiskLimit" } }, "next_page_cursor": { "type": "string" } } }, "GetRootAccountResponse": { "type": "object", "required": [ "root_addr" ], "properties": { "root_addr": { "type": "string" } } }, "GetStatsResponse": { "type": "object", "description": "Stats response.", "required": [ "period", "summary", "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/StatsMarket" } }, "period": { "$ref": "#/components/schemas/StatsPeriod" }, "summary": { "$ref": "#/components/schemas/StatsSummary" } } }, "GetStatsVolumeResponse": { "type": "object", "description": "Turnover series response.", "required": [ "period", "list", "aggregates" ], "properties": { "aggregates": { "$ref": "#/components/schemas/StatsVolumeAggregates" }, "list": { "type": "array", "items": { "$ref": "#/components/schemas/StatsVolumePoint" } }, "period": { "$ref": "#/components/schemas/StatsPeriod" } } }, "GetSubAccountsResponse": { "type": "object", "required": [ "sub_account_addresses" ], "properties": { "sub_account_addresses": { "type": "array", "items": { "type": "string" } } } }, "GetTickersResponse": { "type": "object", "description": "Ticker snapshots response.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/TickerSnapshot" } } } }, "GetTradeHistoryResponse": { "type": "object", "description": "Response for trade history queries.", "required": [ "list" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Execution" } }, "next_page_cursor": { "type": [ "string", "null" ] } } }, "InstrumentInfo": { "type": "object", "required": [ "symbol", "status", "base_coin", "quote_coin", "launch_time", "delivery_time", "delivery_fee_rate", "price_scale", "leverage_filter", "price_filter", "lot_size_filter", "unified_margin_trade", "funding_interval", "settle_coin", "addr", "quote_addr", "maker_fee_rate", "taker_fee_rate", "maker_base_fee", "taker_base_fee", "base_scale", "quote_scale", "default_slippage_tolerance" ], "properties": { "addr": { "type": "string" }, "base_coin": { "type": "string" }, "base_scale": { "type": "integer", "format": "int32", "minimum": 0 }, "default_slippage_tolerance": { "$ref": "#/components/schemas/SlippageTolerance" }, "delivery_fee_rate": { "type": "string" }, "delivery_time": { "type": "string" }, "funding_interval": { "type": "integer", "format": "int32", "minimum": 0 }, "launch_time": { "type": "string" }, "leverage_filter": { "$ref": "#/components/schemas/LeverageFilter" }, "lot_size_filter": { "$ref": "#/components/schemas/LotSizeFilter" }, "maker_base_fee": { "type": "string" }, "maker_fee_rate": { "type": "string" }, "price_filter": { "$ref": "#/components/schemas/PriceFilter" }, "price_scale": { "type": "integer", "format": "int32", "minimum": 0 }, "quote_addr": { "type": "string" }, "quote_coin": { "type": "string" }, "quote_scale": { "type": "integer", "format": "int32", "minimum": 0 }, "settle_coin": { "type": "string" }, "status": { "type": "string" }, "symbol": { "type": "string" }, "taker_base_fee": { "type": "string" }, "taker_fee_rate": { "type": "string" }, "unified_margin_trade": { "type": "boolean" } } }, "InsurancePoolInventoryPosition": { "type": "object", "required": [ "symbol", "side", "size", "avg_entry_price", "unrealized_pnl" ], "properties": { "avg_entry_price": { "type": "string" }, "side": { "$ref": "#/components/schemas/Side" }, "size": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "unrealized_pnl": { "type": "string" } } }, "InsurancePoolSnapshot": { "type": "object", "required": [ "pool_id", "pool_group_id", "cash_balance", "realized_pnl_cum", "unrealized_pnl", "base_equity", "equity", "group_redistribution_in", "group_redistribution_out", "group_adl_obligation", "adl_mode", "updated_time", "inventory" ], "properties": { "adl_mode": { "type": "string" }, "adl_trigger_reason": { "type": [ "string", "null" ] }, "base_equity": { "type": "string" }, "cash_balance": { "type": "string" }, "equity": { "type": "string" }, "group_adl_obligation": { "type": "string" }, "group_redistribution_in": { "type": "string" }, "group_redistribution_out": { "type": "string" }, "inventory": { "type": "array", "items": { "$ref": "#/components/schemas/InsurancePoolInventoryPosition" } }, "latest_pnl_ratio": { "type": [ "string", "null" ] }, "pool_group_id": { "type": "string" }, "pool_id": { "type": "string" }, "realized_pnl_cum": { "type": "string" }, "unrealized_pnl": { "type": "string" }, "updated_time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "Interval": { "type": "string", "enum": [ "1m", "3m", "5m", "15m", "30m", "1h", "2h", "4h", "6h", "12h", "1d", "3d", "1w", "1M" ] }, "InviteCodeEntry": { "type": "object", "required": [ "code", "status", "createdAtMs" ], "properties": { "code": { "type": "string" }, "createdAtMs": { "type": "integer", "format": "int64" }, "redeemedBy": { "type": [ "string", "null" ] }, "status": { "type": "string", "description": "`active` or `used`." } } }, "InviteCodesResponse": { "type": "object", "required": [ "volumeUsdc", "earned", "claimed", "available", "cap", "gatingEnabled", "codes" ], "properties": { "available": { "type": "integer", "format": "int64", "minimum": 0 }, "cap": { "type": "integer", "format": "int64", "minimum": 0 }, "claimed": { "type": "integer", "format": "int64", "minimum": 0 }, "codes": { "type": "array", "items": { "$ref": "#/components/schemas/InviteCodeEntry" } }, "earned": { "type": "integer", "format": "int64", "minimum": 0 }, "gatingEnabled": { "type": "boolean", "description": "Root-whitelist enforcement. When false, invite codes are unused." }, "volumeUsdc": { "type": "string" } } }, "KlineSnapshot": { "type": "object", "required": [ "t", "i", "o", "h", "l", "c", "T", "v", "V", "Q", "n" ], "properties": { "Q": { "type": "string", "description": "Taker buy quote asset volume. Binance `Q` field." }, "T": { "type": "string", "format": "date-time", "description": "Candle close time (ms).", "example": "1672531200000" }, "V": { "type": "string", "description": "Taker buy base asset volume. Binance `V` field." }, "c": { "type": "string", "description": "Close - the price of the last trade in this candle (closing price)." }, "h": { "type": "string", "description": "High - the highest trade price within this interval." }, "i": { "$ref": "#/components/schemas/Interval", "description": "Candle interval - timeframe." }, "l": { "type": "string", "description": "Low - the minimum trade price within this interval." }, "n": { "type": "string", "description": "Trade count. The number of trades included in this candle" }, "o": { "type": "string", "description": "Open - the price of the first trade in this candle (opening price)." }, "t": { "type": "string", "format": "date-time", "description": "Candle open time (ms).", "example": "1672531200000" }, "v": { "type": "string", "description": "Volume. the trading volume for the candle" } } }, "LeaderboardData": { "type": "object", "description": "A single leaderboard row: subaccount, rank, and metrics.", "required": [ "account_value", "place", "pnl", "ranked", "roi", "sub_account_address", "volume", "trading_xp", "referral_xp", "other_xp", "total_xp" ], "properties": { "account_value": { "type": "string", "description": "Equity in quote units (e.g. USDC)." }, "other_xp": { "type": "integer", "format": "int64", "description": "XP that is neither — quests today, plus admin adjustments. Reported\nseparately so it cannot inflate `trading_xp`, which is what it used to do." }, "place": { "type": "string", "description": "Rank position (1-based), or \"0\" when not ranked." }, "pnl": { "type": "string", "description": "PnL for the selected timeframe. Realized + unrealized (mark-to-market)." }, "ranked": { "type": "boolean", "description": "Whether this entry is on the board (false when not ranked)." }, "referral_xp": { "type": "integer", "format": "int64", "description": "XP earned from referral bonuses." }, "roi": { "type": "string", "description": "Return on investment as a decimal string (e.g. \"0.05\" for 5%)." }, "sub_account_address": { "type": "string", "description": "Subaccount address." }, "total_xp": { "type": "integer", "format": "int64", "description": "Total XP balance. Equals `trading_xp + referral_xp + other_xp`." }, "trading_xp": { "type": "integer", "format": "int64", "description": "XP earned from trading activity: taker/maker fees and position holding." }, "volume": { "type": "string", "description": "Cumulative volume in quote units." } } }, "LeaderboardMeta": { "type": "object", "description": "Pagination metadata for a leaderboard list response.", "required": [ "offset", "limit", "total" ], "properties": { "limit": { "type": "integer", "format": "int32", "description": "Applied limit.", "minimum": 0 }, "offset": { "type": "integer", "format": "int32", "description": "Applied offset.", "minimum": 0 }, "total": { "type": "integer", "format": "int64", "description": "Total number of entries in the window.", "minimum": 0 } } }, "LeaderboardPlacementResponse": { "type": "object", "description": "Response for the current user's placement(s) on the leaderboard.", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardData" }, "description": "One row per subaccount (or single row when sub_account query is set)." } } }, "LeaderboardResponse": { "type": "object", "description": "Paginated leaderboard list response.", "required": [ "data", "meta" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/LeaderboardData" }, "description": "Leaderboard rows." }, "meta": { "$ref": "#/components/schemas/LeaderboardMeta", "description": "Pagination info." } } }, "LeverageFilter": { "type": "object", "required": [ "min_leverage", "max_leverage", "leverage_step" ], "properties": { "leverage_step": { "type": "string" }, "max_leverage": { "type": "string" }, "min_leverage": { "type": "string" } } }, "ListApiKeysResponse": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiKeyInfo" } } } }, "ListCompetitionsParams": { "type": "object", "properties": { "status": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CompetitionStatus" } ] } } }, "ListCompetitionsResponse": { "type": "object", "required": [ "data" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CompetitionSummary" } } } }, "ListReferralCodesResponse": { "type": "object", "required": [ "codes" ], "properties": { "codes": { "type": "array", "items": { "$ref": "#/components/schemas/ReferralCodeInfo" } } } }, "LongShortRatio": { "type": "object", "required": [ "symbol", "buy_ratio", "sell_ratio", "timestamp" ], "properties": { "buy_ratio": { "type": "string", "description": "The ratio of the number of long position" }, "sell_ratio": { "type": "string", "description": "The ratio of the number of short position" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "timestamp": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "LotSizeFilter": { "type": "object", "required": [ "max_order_qty", "min_order_qty", "qty_step", "post_only_max_order_qty", "max_mkt_order_qty", "min_notional_value" ], "properties": { "max_mkt_order_qty": { "type": "string" }, "max_order_qty": { "type": "string" }, "min_notional_value": { "type": "string" }, "min_order_qty": { "type": "string" }, "post_only_max_order_qty": { "type": "string" }, "qty_step": { "type": "string" } } }, "MarginMode": { "type": "string", "enum": [ "Cross", "Isolated" ] }, "MintInviteCodeResponse": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "OpenInterest": { "type": "object", "required": [ "open_interest", "open_interest_value", "timestamp" ], "properties": { "open_interest": { "type": "string" }, "open_interest_value": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "Order": { "type": "object", "description": "Summary information about an order.", "required": [ "order_id", "symbol", "sub_account_address", "price", "qty", "side", "margin_mode", "order_status", "avg_price", "leaves_qty", "leaves_value", "cum_exec_qty", "cum_exec_value", "cum_exec_fee", "time_in_force", "order_type", "last_price_on_created", "post_only", "reduce_only", "close_on_trigger", "created_time", "updated_time" ], "properties": { "avg_price": { "type": "string", "description": "Average price at which part (or all) of the order has been executed (i.e. filled)" }, "cancel_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CancelType" } ] }, "close_on_trigger": { "type": "boolean" }, "closed_pnl": { "type": [ "string", "null" ], "description": "Closed profit and loss for each close position order.\nValid only in order WebSocket" }, "create_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CreateType" } ] }, "created_time": { "type": "string", "format": "date-time", "example": "1672531200000" }, "cum_exec_fee": { "type": "string", "description": "Cumulative executed trading fee: the total fees charged so far for the executed portion of this order" }, "cum_exec_qty": { "type": "string", "description": "Cumulative executed quantity: total amount of the order\nthat has already been filled/executed so far" }, "cum_exec_value": { "type": "string", "description": "Cumulative executed value: the total value corresponding to the part of\nthe order that has already been filled. Basically: how much worth in total has been executed so far" }, "expire_time": { "type": [ "string", "null" ], "format": "date-time", "description": "Expiration time for orders with a time-in-force of Good-Til-Date (GTD)", "example": "1672531200000" }, "last_price_on_created": { "type": "string", "description": "Last price at the time the order was created" }, "leaves_qty": { "type": "string", "description": "Remaining quantity from the order that has not yet been executed" }, "leaves_value": { "type": "string", "description": "Estimated value of the remaining quantity (leavesQty)\nthat remains unfilled. Basically: how much the unfilled portion is “worth”" }, "margin_mode": { "$ref": "#/components/schemas/MarginMode" }, "order_id": { "$ref": "#/components/schemas/OrderId" }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] }, "order_status": { "$ref": "#/components/schemas/OrderStatus" }, "order_type": { "$ref": "#/components/schemas/OrderType", "description": "Order type. Market, Limit. For TP/SL orders, is the order type after the order was triggered" }, "post_only": { "type": "boolean" }, "price": { "type": "string" }, "qty": { "type": "string" }, "reduce_only": { "type": "boolean" }, "reject_reason": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/RejectReason" } ] }, "side": { "$ref": "#/components/schemas/Side" }, "stop_order_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/StopOrderType", "description": "Stop order type. For example, Stop Market or Stop Limit." } ] }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "time_in_force": { "$ref": "#/components/schemas/TimeInForce" }, "tpsl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSl", "description": "Take Profit / Stop Loss details if set" } ] }, "trigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalOrder", "description": "Conditional order details if this is a conditional order" } ] }, "updated_time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "OrderBookLevel": { "type": "array", "items": { "type": "string", "description": "Order book level consisting of price and size." }, "description": "Order book level consisting of price and size.", "maxItems": 2, "minItems": 2 }, "OrderBookSnapshot": { "type": "object", "description": "Order book Snapshot at a specific point in time.", "required": [ "s", "ts", "b", "a", "u", "seq", "mts" ], "properties": { "a": { "type": "array", "items": { "$ref": "#/components/schemas/OrderBookLevel" }, "description": "Ask levels" }, "b": { "type": "array", "items": { "$ref": "#/components/schemas/OrderBookLevel" }, "description": "Bid levels" }, "mts": { "type": "string", "format": "date-time", "description": "The timestamp from the matching engine when this orderbook data is produced.\nIt can be correlated with T from public trade channel", "example": "1672531200000" }, "s": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name" }, "seq": { "type": "integer", "format": "int64", "example": 21, "minimum": 0 }, "ts": { "type": "string", "format": "date-time", "description": "The timestamp (ms) that the system generates the data", "example": "1672531200000" }, "u": { "type": "integer", "format": "int64", "description": "Update ID, is always in sequence", "example": 1, "minimum": 0 } } }, "OrderId": { "type": "string", "format": "uuid" }, "OrderLinkId": { "type": "string" }, "OrderListResponse": { "type": "object", "description": "Response for order list and order history requests.", "required": [ "list", "next_page_cursor" ], "properties": { "list": { "type": "array", "items": { "$ref": "#/components/schemas/Order" } }, "next_page_cursor": { "type": "string" } } }, "OrderPriceLimit": { "type": "object", "description": "Order price limits for a given trading symbol.", "required": [ "symbol", "buy_limit", "sell_limit", "ts" ], "properties": { "buy_limit": { "type": "string", "description": "Highest Bid Price" }, "sell_limit": { "type": "string", "description": "Lowest Ask Price" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "ts": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "OrderStatus": { "type": "string", "enum": [ "New", "PartiallyFilled", "Untriggered", "CancelRequested", "Rejected", "PartiallyFilledCanceled", "Filled", "Canceled", "Triggered", "Deactivated", "Expired" ] }, "OrderType": { "type": "string", "description": "Order type: Limit, Market.", "enum": [ "Limit", "Market" ] }, "PlaceOrderRequest": { "type": "object", "description": "Request to place an order.", "required": [ "sub_account_address", "symbol", "side", "order_type", "qty", "price", "margin_mode", "time_in_force" ], "properties": { "close_on_trigger": { "type": "boolean" }, "expire_time": { "type": [ "string", "null" ], "format": "date-time", "example": "1672531200000" }, "margin_mode": { "$ref": "#/components/schemas/MarginMode" }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] }, "order_type": { "$ref": "#/components/schemas/OrderType" }, "post_only": { "type": "boolean" }, "price": { "type": "string" }, "qty": { "type": "string" }, "reduce_only": { "type": "boolean" }, "side": { "$ref": "#/components/schemas/Side" }, "slippage_tolerance": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SlippageTolerance" } ] }, "smp_group": { "type": [ "integer", "null" ], "format": "int64", "description": "Self-match prevention group id. Orders with the same `(user_id, smp_group)` are eligible\nfor SMP checks.", "minimum": 0 }, "smp_type": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SmpType", "description": "Self-match prevention (SMP/STP) strategy. If unset, SMP is disabled." } ] }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "time_in_force": { "$ref": "#/components/schemas/TimeInForce" }, "tpsl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSl" } ] }, "trigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalOrder" } ] } } }, "PlaceOrderResponse": { "type": "object", "description": "Response for placing an order.", "required": [ "order_id" ], "properties": { "order_id": { "$ref": "#/components/schemas/OrderId" }, "order_link_id": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/OrderLinkId" } ] } } }, "Position": { "type": "object", "description": "Position information.\n\n* risk_id: numeric identifier of the current risk tier your position is on for that symbol.\n* risk_limit_value: the maximum position value allowed under that tier (the tier’s limit). If your position value grows beyond this, the tier steps up (higher requirements).\n\nDetails:\n* Meaning: Bybit enforces “risk limit tiers” to cap position value and scale maintenance margin. The tier is referenced by riskId, and its cap is riskLimitValue.\n* Effects: Higher tiers allow larger positions but increase maintenance margin and may constrain leverage.\n* Portfolio margin note: In portfolio margin mode, both fields are not meaningful and are returned as 0 (docs: “risk limit rules are invalid”).", "required": [ "risk_id", "risk_limit_value", "symbol", "sub_account_address", "side", "size", "avg_price", "position_value", "margin_mode", "position_balance", "position_status", "leverage", "mark_price", "liq_price", "bust_price", "position_im", "position_im_by_mp", "position_mm", "position_mm_by_mp", "unrealized_pnl", "unrealized_funding", "realized_pnl_cur", "realized_pnl_cum", "cum_funding", "adl_rank_indicator", "is_reduce_only", "created_time", "updated_time", "seq" ], "properties": { "adl_rank_indicator": { "$ref": "#/components/schemas/AdlRankIndicator", "description": "Auto-deleverage rank indicator." }, "avg_price": { "type": "string", "description": "Average entry price." }, "bust_price": { "type": "string", "description": "Bankruptcy price" }, "created_time": { "type": "string", "format": "date-time", "description": "Timestamp of the first time a position was created on this symbol (ms)", "example": "1672531200000" }, "cum_funding": { "type": "string", "description": "Net realized funding PnL accumulated for this position (receive positive, pay negative)." }, "is_reduce_only": { "type": "boolean" }, "leverage": { "type": "string", "description": "Position leverage" }, "leverage_sys_updated_time": { "type": [ "string", "null" ], "format": "date-time", "example": "1672531200000" }, "liq_price": { "type": "string", "description": "Position liquidation price" }, "margin_mode": { "$ref": "#/components/schemas/MarginMode", "description": "Is position cross margin or isolated margin" }, "mark_price": { "type": "string", "description": "Mark price" }, "mmr_sys_update_time": { "type": [ "string", "null" ], "format": "date-time", "example": "1672531200000" }, "position_balance": { "type": "string", "description": "Position margin" }, "position_im": { "type": "string", "description": "Initial margin" }, "position_im_by_mp": { "type": "string", "description": "Initial margin calculated by mark price" }, "position_mm": { "type": "string", "description": "Maintenance margin" }, "position_mm_by_mp": { "type": "string", "description": "Maintenance margin calculated by mark price" }, "position_status": { "$ref": "#/components/schemas/PositionStatus", "description": "Position status. Normal, Liq, Adl" }, "position_value": { "type": "string", "description": "Position value" }, "realized_pnl_cum": { "type": "string", "description": "Sum of all historical Current Realized PnLs (and the latest one)." }, "realized_pnl_cur": { "type": "string", "description": "Sum of Fill Realized PnL for position of this symbol/side\nsince this position was created last time" }, "risk_id": { "type": "integer", "format": "int32", "description": "Risk tier ID", "minimum": 0 }, "risk_limit_value": { "type": "string", "description": "Risk limit value" }, "seq": { "type": "integer", "format": "int64", "description": "Cross sequence, used to associate each fill and each position update\n* Different symbols may have the same seq, please use seq + symbol to check unique", "minimum": 0 }, "side": { "$ref": "#/components/schemas/Side", "description": "Position side. Buy: long, Sell: short" }, "size": { "type": "string", "description": "Position size, always positive" }, "stop_loss": { "type": [ "string", "null" ], "description": "Stop loss price" }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name" }, "take_profit": { "type": [ "string", "null" ], "description": "Take profit price" }, "trailing_stop": { "type": [ "string", "null" ], "description": "Trailing stop (The distance from market price)" }, "unrealized_funding": { "type": "string", "description": "Net unsettled funding PnL for this position (receive positive, pay negative)." }, "unrealized_pnl": { "type": "string", "description": "How much USDC an account will receive (or pay if negative)\nif the position is closed at the current MarkPrice" }, "updated_time": { "type": "string", "format": "date-time", "description": "Position data updated timestamp (ms)", "example": "1672531200000" } } }, "PositionStatus": { "type": "string", "enum": [ "Normal", "Liq", "Adl" ] }, "PriceFilter": { "type": "object", "required": [ "min_price", "max_price", "tick_size" ], "properties": { "max_price": { "type": "string" }, "min_price": { "type": "string" }, "tick_size": { "type": "string" } } }, "PriceKlineSnapshot": { "type": "object", "description": "Price-only kline entry. Used for mark price and index price klines.", "required": [ "t", "o", "h", "l", "c" ], "properties": { "c": { "type": "string" }, "h": { "type": "string" }, "l": { "type": "string" }, "o": { "type": "string" }, "t": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "PublicTrade": { "type": "object", "description": "A single trade entry from the public trade stream.", "required": [ "i", "s", "S", "v", "p", "seq", "T" ], "properties": { "S": { "$ref": "#/components/schemas/Side", "description": "Side of taker." }, "T": { "type": "integer", "format": "int64", "description": "The timestamp (ms) that the order is filled.", "example": "1672531200000", "minimum": 0 }, "i": { "type": "string", "description": "Trade ID." }, "p": { "type": "string", "description": "Trade price." }, "s": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name." }, "seq": { "type": "integer", "format": "int64", "description": "Cross sequence.", "minimum": 0 }, "v": { "type": "string", "description": "Trade size." } } }, "RecordReferralClickRequest": { "type": "object", "required": [ "code" ], "properties": { "code": { "type": "string" } } }, "RedeemSeasonClaimRequest": { "type": "object", "description": "`POST /season-claim/redeem` — redeem (or, with `preview`, dry-run) a\nseason-claim voucher.", "required": [ "voucher" ], "properties": { "preview": { "type": "boolean" }, "voucher": { "type": "string" } } }, "RedeemSeasonClaimResponse": { "type": "object", "description": "`status` is one of `\"preview\"`, `\"granted\"`, or `\"already_claimed\"`.", "required": [ "status", "merged_xp", "multiplier_bps" ], "properties": { "merged_xp": { "type": "integer", "format": "int64" }, "multiplier_bps": { "type": "integer", "format": "int32" }, "status": { "type": "string" } } }, "ReferralCodeInfo": { "type": "object", "required": [ "code_id", "code", "is_default", "created_at", "clicks", "binds", "downline_count" ], "properties": { "binds": { "type": "integer", "format": "int64", "description": "Number of users who bound through this specific code (`users.bound_via_code_id`).", "minimum": 0 }, "clicks": { "type": "integer", "format": "int64", "description": "Number of recorded clicks that resolved to this code (`referral_clicks.code_id`).", "minimum": 0 }, "code": { "type": "string" }, "code_id": { "type": "string" }, "created_at": { "type": "integer", "format": "int64" }, "downline_count": { "type": "integer", "format": "int64", "description": "Total direct downline of this code's owner (`users.referrer_id`). Owner-level, so it is\nidentical across all of the owner's codes.", "minimum": 0 }, "is_default": { "type": "boolean" }, "label": { "type": [ "string", "null" ] } } }, "ReferralStatus": { "type": "object", "description": "Referral program status for the viewer as a referrer.", "required": [ "l1_bps_effective", "downline_count" ], "properties": { "downline_count": { "type": "integer", "format": "int64", "description": "Direct (L1) referrals.", "minimum": 0 }, "l1_bps_effective": { "type": "integer", "format": "int32", "description": "L1 cut in bps — flat for everyone (ranks removed 2026-07-20).", "minimum": 0 } } }, "ReferralSummaryResponse": { "type": "object", "required": [ "referral_code", "downline_count" ], "properties": { "downline_count": { "type": "integer", "format": "int64", "minimum": 0 }, "referral_code": { "type": "string" }, "referrer_code": { "type": [ "string", "null" ] }, "referrer_user_id": { "type": [ "string", "null" ] } } }, "RejectReason": { "type": "string", "enum": [ "EcNoError", "EcOthers", "EcInsufficientFunds", "EcUnknownMessageType", "EcMissingClOrdId", "EcMissingOrigClOrdId", "EcClOrdIdOrigClOrdIdAreTheSame", "EcDuplicatedClOrdId", "EcOrigClOrdIdDoesNotExist", "EcTooLateToCancel", "EcUnknownOrderType", "EcUnknownSide", "EcUnknownTimeInForce", "EcWronglyRouted", "EcMarketOrderPriceIsNotZero", "EcLimitOrderInvalidPrice", "EcNoEnoughQtyToFill", "EcNoImmediateQtyToFill", "EcPerCancelRequest", "EcMarketOrderCannotBePostOnly", "EcPostOnlyWillTakeLiquidity", "EcReduceOnlyNoPosition", "EcReduceOnlyWouldIncreasePosition", "EcReduceOnlyExceedsPosition", "EcReduceOnlyMode", "EcTradingHalted", "EcCancelReplaceOrder", "EcInvalidSymbolStatus", "EcCancelForNoFullFill", "EcBySelfMatch", "EcInCallAuctionStatus", "EcQtyCannotBeZero", "EcMarketOrderNoSupportTif", "EcReachMaxTradeNum", "EcInvalidPriceScale", "EcBitIndexInvalid", "EcStopBySelfMatch", "EcInvalidSmpType", "EcCancelByMmp", "EcInvalidUserType", "EcInvalidMirrorOid", "EcInvalidMirrorUid", "EcPriceNotMultipleOfTick", "EcQtyBelowMin", "EcQtyNotMultipleOfLot", "EcQtyAboveMax", "EcInvalidAmount", "EcLoadOrderCancel", "EcMarketQuoteNoSuppSell", "EcDisorderOrderId", "EcInvalidBaseValue", "EcLoadOrderCanMatch", "EcSecurityStatusFail", "EcReachRiskPriceLimit", "EcOrderNotExist", "EcCancelByOrderValueZero", "EcCancelByMatchValueZero", "EcReachMarketPriceLimit" ] }, "RewardSummaryResponse": { "type": "object", "description": "`GET /user/rewards` response (spec §10).", "required": [ "xp_balance", "closed_tournament_eligible", "breakdown", "ledger", "referral" ], "properties": { "breakdown": { "$ref": "#/components/schemas/XpBreakdown" }, "closed_tournament_eligible": { "type": "boolean", "description": "Closed-tournament eligibility: XP at/above the configured floor\n(`gateway.closed_tournament_min_xp`). Ranks removed 2026-07-20." }, "ledger": { "type": "array", "items": { "$ref": "#/components/schemas/RewardsLedgerEntry" }, "description": "One ledger page, newest first." }, "next_cursor": { "type": [ "string", "null" ], "description": "Cursor for the next ledger page; null when this page is the last." }, "referral": { "$ref": "#/components/schemas/ReferralStatus" }, "season": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/SeasonStatus", "description": "Season-1 starting multiplier (season1-conversion §5); omitted entirely\nwhen the wallet's active-season multiplier is 1.0× (no positive band)." } ] }, "xp_balance": { "type": "string" } } }, "RewardsLedgerEntry": { "type": "object", "description": "One instant-XP ledger entry.", "required": [ "reason", "delta_xp", "created_at" ], "properties": { "created_at": { "type": "string", "description": "RFC 3339 UTC timestamp." }, "delta_xp": { "type": "string" }, "reason": { "type": "string" } } }, "RiskLimit": { "type": "object", "required": [ "symbol", "risk_id", "risk_limit_value", "maintenance_margin", "initial_margin", "is_lowest_risk", "max_leverage", "mm_duration" ], "properties": { "initial_margin": { "type": "string", "description": "Initial margin rate" }, "is_lowest_risk": { "type": "boolean" }, "maintenance_margin": { "type": "string", "description": "Maintain margin rate" }, "max_leverage": { "type": "string", "description": "Allowed max leverage" }, "mm_duration": { "type": "string", "description": "The maintenance margin deduction value when risk limit tier changed" }, "risk_id": { "type": "integer", "format": "int32", "description": "Risk ID", "minimum": 0 }, "risk_limit_value": { "type": "string", "description": "Position limit" }, "symbol": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name" } } }, "RootWhitelistCheckQuery": { "type": "object", "properties": { "root_address": { "type": [ "string", "null" ] }, "root_public_key": { "type": [ "string", "null" ] } } }, "RootWhitelistResponse": { "type": "object", "required": [ "root_address", "whitelisted" ], "properties": { "root_address": { "type": "string" }, "whitelisted": { "type": "boolean" } } }, "Scope": { "type": "string", "enum": [ "full", "read", "trade", "withdraw", "admin" ] }, "SeasonClaimVoucherResponse": { "type": "object", "description": "`POST /season-claim/voucher` — a signed, time-boxed voucher the mainnet\nside redeems to merge a testnet root's XP into the caller's mainnet\naccount.", "required": [ "voucher", "expires_at_ms" ], "properties": { "expires_at_ms": { "type": "integer", "format": "int64" }, "voucher": { "type": "string" } } }, "SeasonStatus": { "type": "object", "description": "Season-1 starting-multiplier block for `GET /user/rewards`\n(season1-conversion §5). Present only when the wallet's active-season\nmultiplier is above 1.0× (a positive band); the whole block is omitted at\n1.0×.", "required": [ "name", "multiplier_bps", "source" ], "properties": { "multiplier_bps": { "type": "integer", "format": "int32", "description": "The wallet's Season-1 starting multiplier in bps (always > 0 when the\nblock is present).", "minimum": 0 }, "name": { "type": "string", "description": "Active season label (config `active_season`, e.g. `season1`)." }, "source": { "type": "string", "description": "The band the wallet's merged Total XP fell into, e.g. `band_2000bps` —\nthe source of the multiplier." } } }, "SetLeverageRequest": { "type": "object", "description": "Request to set leverage.", "required": [ "sub_account_address", "symbol", "leverage" ], "properties": { "leverage": { "type": "string" }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" } } }, "SetLeverageResponse": { "type": "object", "description": "Set leverage response.", "required": [ "success", "time" ], "properties": { "success": { "type": "boolean" }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "SetTradingStopRequest": { "type": "object", "description": "Set the take profit, stop loss or trailing stop for the position.", "required": [ "symbol", "sub_account_address" ], "properties": { "active_price": { "type": [ "string", "null" ] }, "sl_size": { "type": [ "string", "null" ], "description": "Stop loss size\nvalid for TP/SL partial mode, note: the value of tpSize and slSize must equal" }, "sub_account_address": { "type": "string" }, "symbol": { "$ref": "#/components/schemas/Symbol" }, "tp_size": { "type": [ "string", "null" ], "description": "Take profit size\nvalid for TP/SL partial mode, note: the value of tpSize and slSize must equal" }, "tpsl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSl" } ] }, "trailing_stop": { "type": [ "string", "null" ] } } }, "SetTradingStopResponse": { "type": "object", "description": "Response for setting trading stop.", "required": [ "success", "time" ], "properties": { "success": { "type": "boolean" }, "time": { "type": "string", "format": "date-time", "example": "1672531200000" } } }, "Side": { "type": "string", "description": "Order side: buy or sell.", "enum": [ "Sell", "Buy" ] }, "SlippageTolerance": { "oneOf": [ { "type": "object", "required": [ "tick_size" ], "properties": { "tick_size": { "type": "integer", "format": "int64", "minimum": 0 } } }, { "type": "object", "required": [ "percent" ], "properties": { "percent": { "type": "number", "format": "double" } } } ] }, "SmpType": { "type": "string", "description": "Self Match Prevention strategy.", "enum": [ "CancelMaker", "CancelTaker", "CancelBoth" ] }, "StatsMarket": { "type": "object", "required": [ "symbol", "last_price", "price_change", "avg_funding_rate", "turnover", "open_interest_value", "buy_ratio", "sell_ratio", "next_funding_time" ], "properties": { "avg_funding_rate": { "type": "string", "description": "Average funding rate" }, "buy_ratio": { "type": "string", "description": "The ratio of the number of long position" }, "last_price": { "type": "string", "description": "Last traded price" }, "next_funding_time": { "type": "string", "format": "date-time", "description": "Next funding time (ms)", "example": "1672531200000" }, "open_interest_value": { "type": "string", "description": "Open interest value" }, "price_change": { "type": "string", "description": "Price change" }, "sell_ratio": { "type": "string", "description": "The ratio of the number of short position" }, "symbol": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name" }, "turnover": { "type": "string", "description": "Turnover" } } }, "StatsPeriod": { "type": "string", "description": "Stats period. `24h`, `7d`, `30d`, or `all_time`.", "enum": [ "24h", "7d", "30d", "all_time" ] }, "StatsSummary": { "type": "object", "required": [ "turnover", "turnover_change", "active_traders", "active_traders_change", "trades", "trades_change", "open_interest_value", "open_interest_value_change" ], "properties": { "active_traders": { "type": "string", "description": "Active traders" }, "active_traders_change": { "type": "string", "description": "Active traders change" }, "open_interest_value": { "type": "string", "description": "Open interest value" }, "open_interest_value_change": { "type": "string", "description": "Open interest value change" }, "trades": { "type": "string", "description": "Matched trades" }, "trades_change": { "type": "string", "description": "Matched trades change" }, "turnover": { "type": "string", "description": "Turnover" }, "turnover_change": { "type": "string", "description": "Turnover change" } } }, "StatsVolumeAggregates": { "type": "object", "required": [ "turnover_24h", "turnover_7d", "turnover_30d", "turnover_all_time" ], "properties": { "turnover_24h": { "type": "string", "description": "Turnover for 24h" }, "turnover_30d": { "type": "string", "description": "Turnover for 30d" }, "turnover_7d": { "type": "string", "description": "Turnover for 7d" }, "turnover_all_time": { "type": "string", "description": "Turnover for all time" } } }, "StatsVolumePoint": { "type": "object", "required": [ "timestamp", "turnover" ], "properties": { "timestamp": { "type": "string", "format": "date-time", "example": "1672531200000" }, "turnover": { "type": "string", "description": "Turnover" } } }, "StopOrderType": { "type": "string", "enum": [ "TakeProfit", "StopLoss", "TrailingStop", "Stop", "PartialTakeProfit", "PartialStopLoss", "TpslOrder", "OcoOrder", "MmRateClose", "BidirectionalTpslOrder" ] }, "String": { "type": "string" }, "Symbol": { "type": "string", "example": "BTC-USDCx" }, "SystemInfo": { "type": "object", "required": [ "build_id", "aptos_network", "quote_asset_metadata", "runtime_manifest_generation", "runtime_manifest_phase" ], "properties": { "aptos_network": { "type": "string" }, "build_id": { "type": "string", "description": "Build identifier for the running backend (e.g. git commit SHA).\n\nIdentifies the deployed build for release/version verification without disclosing source code." }, "package_id": { "type": [ "string", "null" ], "description": "Deployed Ekiden Daml package id. Set on Canton backends only." }, "perpetual_addr": { "type": "string", "description": "Aptos perpetual contract address. Omitted on Canton backends." }, "quote_asset_metadata": { "type": "string" }, "runtime_manifest_generation": { "type": "integer", "format": "int64", "minimum": 0 }, "runtime_manifest_phase": { "type": "string" } } }, "TickerSnapshot": { "type": "object", "description": "Query for the latest price snapshot, best bid/ask price, and trading volume in the last 24 hours.", "required": [ "symbol", "addr", "last_price", "index_price", "mark_price", "prev_price_24h", "high_price_24h", "low_price_24h", "prev_price_1h", "volume_24h", "turnover_24h", "trades_24h", "open_interest", "open_interest_value", "funding_rate", "next_funding_time", "best_ask_size", "best_ask_price", "best_bid_size", "best_bid_price" ], "properties": { "addr": { "type": "string", "description": "Market address" }, "best_ask_price": { "type": "string", "description": "Best ask price" }, "best_ask_size": { "type": "string", "description": "Best ask size" }, "best_bid_price": { "type": "string", "description": "Best bid price" }, "best_bid_size": { "type": "string", "description": "Best bid size" }, "funding_rate": { "type": "string", "description": "Funding rate" }, "high_price_24h": { "type": "string", "description": "The highest price in the last 24 hours" }, "index_price": { "type": "string", "description": "Index price" }, "last_price": { "type": "string", "description": "Last traded price" }, "low_price_24h": { "type": "string", "description": "The lowest price in the last 24 hours" }, "mark_price": { "type": "string", "description": "Mark price" }, "next_funding_time": { "type": "string", "format": "date-time", "description": "Next funding time (ms)", "example": "1672531200000" }, "open_interest": { "type": "string", "description": "Open interest size" }, "open_interest_value": { "type": "string", "description": "Open interest value" }, "prev_price_1h": { "type": "string", "description": "Market price 1 hour ago" }, "prev_price_24h": { "type": "string", "description": "Market price 24 hours ago" }, "symbol": { "$ref": "#/components/schemas/Symbol", "description": "Symbol name" }, "trades_24h": { "type": "integer", "format": "int64", "description": "Matched trades for 24h", "minimum": 0 }, "turnover_24h": { "type": "string", "description": "Turnover for 24h" }, "volume_24h": { "type": "string", "description": "Volume for 24h" } } }, "TimeInForce": { "oneOf": [ { "type": "string", "description": "Good Till Cancel", "enum": [ "GTC" ] }, { "type": "string", "description": "Immediate or Cancel", "enum": [ "IOC" ] }, { "type": "string", "description": "Fill or Kill", "enum": [ "FOK" ] }, { "type": "object", "description": "Good Till Date", "required": [ "GTD" ], "properties": { "GTD": { "type": "integer", "format": "int64", "description": "Good Till Date", "minimum": 0 } } }, { "type": "string", "description": "Good For Day", "enum": [ "Day" ] } ], "description": "Time in Force instructions." }, "Timeframe": { "type": "string", "description": "Leaderboard ranking window: today, last 7 days, last 30 days, or all time.", "enum": [ "today", "7d", "30d", "all" ] }, "TpSl": { "type": "object", "required": [ "mode" ], "properties": { "mode": { "$ref": "#/components/schemas/TpSlMode" }, "stop_loss": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSlSpec" } ] }, "take_profit": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSlSpec" } ] } } }, "TpSlMode": { "type": "string", "enum": [ "Full", "Partial" ] }, "TpSlSpec": { "oneOf": [ { "type": "object", "required": [ "market" ], "properties": { "market": { "type": "object", "required": [ "trigger_price", "trigger_by" ], "properties": { "trigger_by": { "$ref": "#/components/schemas/TriggerBy" }, "trigger_price": { "type": "string" } } } } }, { "type": "object", "required": [ "limit" ], "properties": { "limit": { "type": "object", "required": [ "trigger_price", "limit_price", "trigger_by" ], "properties": { "limit_price": { "type": "string" }, "trigger_by": { "$ref": "#/components/schemas/TriggerBy" }, "trigger_price": { "type": "string" } } } } } ] }, "TriggerBy": { "type": "string", "enum": [ "LastPrice", "IndexPrice", "MarkPrice" ] }, "TriggerDirection": { "type": "string", "enum": [ "Up", "Down" ] }, "UserId": { "type": "string", "format": "uuid" }, "UserQuestSummary": { "type": "object", "description": "One active quest with the viewer's claim state (`GET /user/quests`,\nspec §10).", "required": [ "quest_id", "kind", "trigger", "reward_xp", "params", "claimed" ], "properties": { "claimed": { "type": "boolean", "description": "One-shot quests: ever claimed. Daily quests: claimed for the current\nUTC day." }, "kind": { "type": "string", "description": "`one_shot` or `daily`." }, "last_claimed_at": { "type": [ "string", "null" ], "description": "RFC 3339 UTC timestamp of the most recent claim, if any." }, "params": { "description": "Quest parameters (e.g. `{\"min_volume_usdc\": 1000}`)." }, "quest_id": { "type": "string" }, "reward_xp": { "type": "string", "description": "XP paid per claim; string-encoded like every XP amount on the wire." }, "trigger": { "type": "string", "description": "`first_referral_active`, `manual_claim` or `volume_threshold`." } } }, "UserQuestsResponse": { "type": "object", "description": "`GET /user/quests` response.", "required": [ "quests" ], "properties": { "quests": { "type": "array", "items": { "$ref": "#/components/schemas/UserQuestSummary" } } } }, "XpBreakdown": { "type": "object", "description": "Lifetime XP per source group (spec §10 `breakdown`). String-encoded\nintegers like every XP amount on the wire.", "required": [ "taker", "maker", "position", "quest", "referral" ], "properties": { "maker": { "type": "string" }, "position": { "type": "string" }, "quest": { "type": "string" }, "referral": { "type": "string" }, "taker": { "type": "string" } } } }, "securitySchemes": { "api_key_auth": { "type": "apiKey", "in": "header", "name": "X-API-KEY" }, "bearer_auth": { "type": "http", "scheme": "bearer" }, "root_whitelist_basic_auth": { "type": "http", "scheme": "basic" } } } }