{ "openapi": "3.1.0", "info": { "title": "Phoenix Eternal API", "description": "RESTful API for accessing Phoenix Eternal perpetual trading data. Provides real-time orderbook levels, asset information, and market metadata.", "termsOfService": "https://www.phoenix.trade/terms-of-service", "contact": { "name": "Phoenix Development Team", "url": "https://github.com/Ellipsis-Labs/phoenix" }, "license": { "name": "Proprietary" }, "version": "1.0.0" }, "servers": [ { "url": "https://perp-api.phoenix.trade", "description": "Phoenix Eternal Perp API" } ], "paths": { "/v1/view/exchange": { "get": { "tags": [ "Exchange" ], "summary": "Get exchange", "description": "Handles `GET /v1/view/exchange` via `get.v1.view.exchange`.", "operationId": "get.v1.view.exchange", "responses": { "200": { "description": "Phoenix Eternal exchange configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeView" } } } }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get exchange", "sidebarTitle": "Get exchange" } } } }, "/v1/view/exchange/keys": { "get": { "tags": [ "Exchange" ], "summary": "Get exchange keys", "description": "Handles `GET /v1/view/exchange/keys` via `get.v1.view.exchange.keys`.", "operationId": "get.v1.view.exchange.keys", "responses": { "200": { "description": "Exchange pubkeys", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeKeysView" } } } }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get exchange keys", "sidebarTitle": "Get exchange keys" } } } }, "/v1/view/exchange/markets": { "get": { "tags": [ "Exchange" ], "summary": "List markets", "description": "Handles `GET /v1/view/exchange/markets` via `get.v1.view.exchange.markets`.", "operationId": "get.v1.view.exchange.markets", "responses": { "200": { "description": "Exchange market configurations", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeMarketConfig" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "List markets", "sidebarTitle": "List markets" } } } }, "/v1/view/exchange/market/{symbol}": { "get": { "tags": [ "Exchange" ], "summary": "Get market", "description": "Handles `GET /v1/view/exchange/market/{symbol}` via `get.v1.view.exchange.market.by_symbol`.", "operationId": "get.v1.view.exchange.market.by_symbol", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol (e.g., SOL-PERP)", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market configuration", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeMarketConfig" } } } }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get market", "sidebarTitle": "Get market" } } } }, "/v1/view/exchange/status": { "get": { "tags": [ "Exchange" ], "summary": "Get exchange status", "description": "Handles `GET /v1/view/exchange/status` via `get.v1.view.exchange.status`.", "operationId": "get.v1.view.exchange.status", "responses": { "200": { "description": "Exchange status", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeStatusView" } } } }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get exchange status", "sidebarTitle": "Get exchange status" } } } }, "/v1/exchange/snapshot": { "get": { "tags": [ "Exchange" ], "summary": "Get exchange snapshot", "description": "Handles `GET /v1/exchange/snapshot` via `get.v1.exchange.snapshot`.", "operationId": "get.v1.exchange.snapshot", "responses": { "200": { "description": "Exchange snapshot", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ExchangeSnapshotView" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get exchange snapshot", "sidebarTitle": "Get exchange snapshot" } } } }, "/v1/exchange/build-register-ixs": { "post": { "tags": [ "Exchange" ], "summary": "Build register trader instructions", "description": "Returns the register and delegated-onboarding instructions for the default trader account without a referral code. The caller chooses the transaction fee payer, builds the transaction locally, and signs it with the trader authority and fee payer.", "operationId": "post.v1.exchange.build_register_ixs", "requestBody": { "description": "JSON request payload for `post.v1.exchange.build_register_ixs`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildRegisterIxsRequest" }, "example": { "traderAuthority": "string", "txFeePayer": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/BuildRegisterIxsResponse" } } } } }, "x-mint": { "metadata": { "title": "Build register trader instructions", "sidebarTitle": "Build register trader instructions" } } } }, "/v1/exchange/send-register-ixs": { "post": { "tags": [ "Exchange" ], "summary": "Submit register trader transaction", "description": "Validates a base64-encoded transaction for the default trader account, signs it with the Phoenix onboarder, simulates it to ensure the onboarder pays no lamports, sends it to Phoenix's RPC, and returns the transaction signature.", "operationId": "post.v1.exchange.send_register_ixs", "requestBody": { "description": "JSON request payload for `post.v1.exchange.send_register_ixs`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRegisterIxsRequest" }, "example": { "traderAuthority": "string", "transaction": "string", "txFeePayer": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/SendRegisterIxsResponse" } } } } }, "x-mint": { "metadata": { "title": "Submit register trader transaction", "sidebarTitle": "Submit register trader transaction" } } } }, "/v1/view/orderbook/{symbol}": { "get": { "tags": [ "Exchange" ], "summary": "Get orderbook", "description": "Handles `GET /v1/view/orderbook/{symbol}` via `get.v1.view.orderbook.by_symbol`.", "operationId": "get.v1.view.orderbook.by_symbol", "parameters": [ { "name": "symbol", "in": "path", "description": "Trading symbol (BTC, ETH, SOL)", "required": true, "schema": { "type": "string" } }, { "name": "include_splines", "in": "query", "description": "Whether to include splines in response and use them for parsed orderbook", "required": false, "schema": { "type": "boolean" } }, { "name": "bypass_execution_band", "in": "query", "description": "Opt in to receive the full orderbook during commodities after-hours (no-op otherwise)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Phoenix Eternal orderbook", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/OrderbookView" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get orderbook", "sidebarTitle": "Get orderbook" } } } }, "/v1/market/{symbol}/mark-price": { "get": { "tags": [ "Exchange" ], "summary": "Get mark price", "description": "Handles `GET /v1/market/{symbol}/mark-price` via `get.v1.market.by_symbol.mark_price`.", "operationId": "get.v1.market.by_symbol.mark_price", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Mark price", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarkPriceResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get mark price", "sidebarTitle": "Get mark price" } } } }, "/v1/market/{symbol}/stats": { "get": { "tags": [ "Exchange" ], "summary": "Get market stats history", "description": "Handles `GET /v1/market/{symbol}/stats` via `get.v1.market.by_symbol.stats`.", "operationId": "get.v1.market.by_symbol.stats", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol", "required": true, "schema": { "type": "string" }, "example": "SOL-PERP" }, { "name": "start_time", "in": "query", "description": "Start time for market stats history (defaults to 1 hour ago)", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "example": "2025-05-29T19:20:00.000Z" }, { "name": "end_time", "in": "query", "description": "End time for market stats history (defaults to now)", "required": false, "schema": { "type": [ "string", "null" ], "format": "date-time" }, "example": "2025-05-29T19:25:00.000Z" }, { "name": "limit", "in": "query", "description": "Maximum number of data points to return (max 10000, default 1000)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" }, "example": 1000 }, { "name": "timeframe", "in": "query", "description": "Timeframe for aggregating stats (1s, 5s, 1m, 5m, 15m, 30m, 1h, 4h, 1d)", "required": false, "schema": { "type": [ "string", "null" ] }, "example": "1h" } ], "responses": { "200": { "description": "Successfully retrieved market stats history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketStatsHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get market stats history", "sidebarTitle": "Get market stats history" } } } }, "/v1/market/{symbol}/next-market-calendar-transition": { "get": { "tags": [ "Exchange" ], "summary": "Get next market calendar transition", "description": "Handles `GET /v1/market/{symbol}/next-market-calendar-transition` via `get.v1.market.by_symbol.next_market_calendar_transition`.", "operationId": "get.v1.market.by_symbol.next_market_calendar_transition", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Next market calendar transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextMarketCalendarTransition" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get next market calendar transition", "sidebarTitle": "Get next market calendar transition" } } } }, "/v1/market/next-commodity-market-transition": { "get": { "tags": [ "Exchange" ], "summary": "Get next commodity market transition", "description": "Handles `GET /v1/market/next-commodity-market-transition` via `get.v1.market.next_commodity_market_transition`.", "operationId": "get.v1.market.next_commodity_market_transition", "responses": { "200": { "description": "Next commodity market transition", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/NextCommodityMarketTransition" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get next commodity market transition", "sidebarTitle": "Get next commodity market transition" } } } }, "/v1/market/{symbol}/market-calendar": { "get": { "tags": [ "Exchange" ], "summary": "Get market calendar", "description": "Handles `GET /v1/market/{symbol}/market-calendar` via `get.v1.market.by_symbol.market_calendar`.", "operationId": "get.v1.market.by_symbol.market_calendar", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketCalendarResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get market calendar", "sidebarTitle": "Get market calendar" } } } }, "/v1/market-calendar/{market_calendar_id}": { "get": { "tags": [ "Exchange" ], "summary": "Get market calendar by ID", "description": "Handles `GET /v1/market-calendar/{market_calendar_id}` via `get.v1.market_calendar.by_market_calendar_id`.", "operationId": "get.v1.market_calendar.by_market_calendar_id", "parameters": [ { "name": "market_calendar_id", "in": "path", "description": "Market calendar id", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Market calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/MarketCalendarRecord" } } } }, "404": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get market calendar by ID", "sidebarTitle": "Get market calendar by ID" } } } }, "/v1/market/commodity-calendar": { "get": { "tags": [ "Exchange" ], "summary": "Get commodity market calendar", "description": "Handles `GET /v1/market/commodity-calendar` via `get.v1.market.commodity_calendar`.", "operationId": "get.v1.market.commodity_calendar", "responses": { "200": { "description": "Commodity market calendar", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CommodityMarketCalendarResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get commodity market calendar", "sidebarTitle": "Get commodity market calendar" } } } }, "/v1/candles/{symbol}": { "get": { "tags": [ "Exchange" ], "summary": "Get candles", "description": "Handles `GET /v1/candles/{symbol}` via `get.v1.candles.by_symbol`.", "operationId": "get.v1.candles.by_symbol", "parameters": [ { "name": "symbol", "in": "path", "description": "Trading symbol", "required": true, "schema": { "type": "string" } }, { "name": "timeframe", "in": "query", "description": "Timeframe", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of candles (default: 2500)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "enableExternalSource", "in": "query", "description": "Opt-in external candles stored in the DB (default: false)", "required": false, "schema": { "type": "boolean" } } ], "responses": { "200": { "description": "Asset candles", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiCandle" } } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get candles", "sidebarTitle": "Get candles" } } } }, "/v1/view/trader/{pubkey}": { "get": { "tags": [ "Trader" ], "summary": "Get trader", "description": "Handles `GET /v1/view/trader/{pubkey}` via `get.v1.view.trader.by_pubkey`.", "operationId": "get.v1.view.trader.by_pubkey", "parameters": [ { "name": "pubkey", "in": "path", "description": "Base58 encoded trader account pubkey", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Phoenix Eternal trader", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraderView" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader", "sidebarTitle": "Get trader" } } } }, "/v1/view/trader-capabilities": { "get": { "tags": [ "Trader" ], "summary": "Get trader capabilities", "description": "Handles `GET /v1/view/trader-capabilities` via `get.v1.view.trader_capabilities`.", "operationId": "get.v1.view.trader_capabilities", "responses": { "200": { "description": "Trader capability descriptors", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraderCapabilitiesMetadata" } } } }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader capabilities", "sidebarTitle": "Get trader capabilities" } } } }, "/v1/trader/state/{authority_pubkey}": { "get": { "tags": [ "Trader" ], "summary": "Get trader state", "description": "Handles `GET /v1/trader/state/{authority_pubkey}` via `get.v1.trader.state.by_authority_pubkey`.", "operationId": "get.v1.trader.state.by_authority_pubkey", "parameters": [ { "name": "traderPdaIndex", "in": "query", "description": "Optional trader PDA index under the authority.", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "authority_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraderStateSnapshotResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader state", "sidebarTitle": "Get trader state" } } } }, "/v1/users/{user_pubkey}/pnl": { "get": { "tags": [ "Trader" ], "summary": "Get user PnL", "description": "Handles `GET /v1/users/{user_pubkey}/pnl` via `get.v1.users.by_user_pubkey.pnl`.", "operationId": "get.v1.users.by_user_pubkey.pnl", "parameters": [ { "name": "user_pubkey", "in": "path", "description": "User public key (base58 encoded)", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Resolution/timeframe: 1m, 1d", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of data points (default: 1000, max: 1440)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PnLPoint" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get user PnL", "sidebarTitle": "Get user PnL" } } } }, "/v1/traders/{trader_pubkey}/portfolio-values": { "get": { "tags": [ "Trader" ], "summary": "Get trader portfolio values", "description": "Handles `GET /v1/traders/{trader_pubkey}/portfolio-values` via `get.v1.traders.by_trader_pubkey.portfolio_values`.", "operationId": "get.v1.traders.by_trader_pubkey.portfolio_values", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader public key (base58 encoded)", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Resolution/timeframe: 1m (testing only), 15m, 30m, 1h, 4h, 1d, 1w, 1M (month)", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of data points (default: 1440, max: 2000)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PortfolioValuePoint" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader portfolio values", "sidebarTitle": "Get trader portfolio values" } } } }, "/v1/traders/{trader_pubkey}/pnl": { "get": { "tags": [ "Trader" ], "summary": "Get trader PnL", "description": "Handles `GET /v1/traders/{trader_pubkey}/pnl` via `get.v1.traders.by_trader_pubkey.pnl`.", "operationId": "get.v1.traders.by_trader_pubkey.pnl", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader public key (base58 encoded)", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Resolution/timeframe: 1m, 1d", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of data points (default: 1000, max: 1440)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/PnLPoint" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader PnL", "sidebarTitle": "Get trader PnL" } } } }, "/v1/traders/{trader_pubkey}/pnl/markets": { "get": { "tags": [ "Trader" ], "summary": "Get trader market PnL", "description": "Handles `GET /v1/traders/{trader_pubkey}/pnl/markets` via `get.v1.traders.by_trader_pubkey.pnl.markets`.", "operationId": "get.v1.traders.by_trader_pubkey.pnl.markets", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader public key (base58 encoded)", "required": true, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "description": "Resolution/timeframe: 1m, 5m, 15m, 1h, 4h, 1d", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of data points per market (default: 1000, max: 1000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "symbols", "in": "query", "description": "Comma separated list of market symbols to filter (defaults to all)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/TraderMarketPnLSeries" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader market PnL", "sidebarTitle": "Get trader market PnL" } } } }, "/v1/users/{user_pubkey}/collateral-history": { "get": { "tags": [ "Trader" ], "summary": "Get user collateral history", "description": "Handles `GET /v1/users/{user_pubkey}/collateral-history` via `get.v1.users.by_user_pubkey.collateral_history`.", "operationId": "get.v1.users.by_user_pubkey.collateral_history", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to return (max 1000)", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "nextCursor", "in": "query", "description": "Cursor for older events (base64-encoded).", "required": false, "schema": { "type": "string" } }, { "name": "prevCursor", "in": "query", "description": "Cursor for newer events (base64-encoded).", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Deprecated cursor parameter (older events).", "required": false, "schema": { "type": "string" } }, { "name": "user_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollateralHistoryResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get user collateral history", "sidebarTitle": "Get user collateral history" } } } }, "/v1/trader/{authority}/collateral-history": { "get": { "tags": [ "Trader" ], "summary": "Get trader collateral history", "description": "Handles `GET /v1/trader/{authority}/collateral-history` via `get.v1.trader.by_authority.collateral_history`.", "operationId": "get.v1.trader.by_authority.collateral_history", "parameters": [ { "name": "authority", "in": "path", "description": "Trader authority pubkey. Use /v1/traders/{trader_pubkey}/collateral-history for direct trader PDA lookups.", "required": true, "schema": { "type": "string" } }, { "name": "pdaIndex", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "nextCursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "prevCursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Collateral history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollateralHistoryResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader collateral history", "sidebarTitle": "Get trader collateral history" } } } }, "/v1/traders/{trader_pubkey}/collateral-history": { "get": { "tags": [ "Trader" ], "summary": "Get trader collateral history", "description": "Handles `GET /v1/traders/{trader_pubkey}/collateral-history` via `get.v1.traders.by_trader_pubkey.collateral_history`.", "operationId": "get.v1.traders.by_trader_pubkey.collateral_history", "parameters": [ { "name": "limit", "in": "query", "description": "Number of items to return (max 1000)", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "nextCursor", "in": "query", "description": "Cursor for older events (base64-encoded).", "required": false, "schema": { "type": "string" } }, { "name": "prevCursor", "in": "query", "description": "Cursor for newer events (base64-encoded).", "required": false, "schema": { "type": "string" } }, { "name": "cursor", "in": "query", "description": "Deprecated cursor parameter (older events).", "required": false, "schema": { "type": "string" } }, { "name": "trader_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CollateralHistoryResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader collateral history", "sidebarTitle": "Get trader collateral history" } } } }, "/v1/users/{user_pubkey}/liquidation-history": { "get": { "tags": [ "Trader" ], "summary": "Get user liquidation history", "description": "Handles `GET /v1/users/{user_pubkey}/liquidation-history` via `get.v1.users.by_user_pubkey.liquidation_history`.", "operationId": "get.v1.users.by_user_pubkey.liquidation_history", "parameters": [ { "name": "pdaIndex", "in": "query", "description": "Trader PDA index to scope history. Defaults to 0.", "required": false, "schema": { "type": "integer", "format": "int32" }, "example": 0 }, { "name": "subaccountIndex", "in": "query", "description": "Optional subaccount index. If omitted, all subaccounts under the PDA are\nincluded.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int32" } }, { "name": "symbol", "in": "query", "description": "Optional market symbol filter.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "limit", "in": "query", "description": "Maximum number of events to return (max 100, default 100).", "required": false, "schema": { "type": "integer", "format": "int64" }, "example": 100 }, { "name": "cursor", "in": "query", "description": "Opaque cursor for older or newer pagination.", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "user_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_UserLiquidationHistoryPoint" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get user liquidation history", "sidebarTitle": "Get user liquidation history" } } } }, "/v1/trader/{authority}/funding-history": { "get": { "tags": [ "Trader" ], "summary": "Get trader funding history", "description": "Handles `GET /v1/trader/{authority}/funding-history` via `get.v1.trader.by_authority.funding_history`.", "operationId": "get.v1.trader.by_authority.funding_history", "parameters": [ { "name": "authority", "in": "path", "description": "Authority pubkey", "required": true, "schema": { "type": "string" } }, { "name": "traderPdaIndex", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "symbol", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "resolution", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Funding history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/TraderFundingHistoryResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader funding history", "sidebarTitle": "Get trader funding history" } } } }, "/v1/users/{user_pubkey}/funding-hourly": { "get": { "tags": [ "Trader" ], "summary": "Get user hourly funding", "description": "Handles `GET /v1/users/{user_pubkey}/funding-hourly` via `get.v1.users.by_user_pubkey.funding_hourly`.", "operationId": "get.v1.users.by_user_pubkey.funding_hourly", "parameters": [ { "name": "user_pubkey", "in": "path", "description": "User public key (base58 encoded)", "required": true, "schema": { "type": "string" } }, { "name": "traderPdaIndex", "in": "query", "description": "Trader PDA index (default 0)", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "symbol", "in": "query", "description": "Optional market symbol (e.g., 'SOL-PERP')", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of hourly rows to return (1-200, default: 50)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Opaque pagination cursor (base64url-encoded; do not parse)", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingHourlyHistoryResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get user hourly funding", "sidebarTitle": "Get user hourly funding" } } } }, "/v1/funding/{symbol}/rates": { "get": { "tags": [ "Exchange" ], "summary": "Get funding rate history", "description": "Handles `GET /v1/funding/{symbol}/rates` via `get.v1.funding.by_symbol.rates`.", "operationId": "get.v1.funding.by_symbol.rates", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol (e.g., 'SOL-PERP')", "required": true, "schema": { "type": "string" } }, { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (default: now - 7 days, max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (default: now)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "limit", "in": "query", "description": "Max number of funding rate points (default: 1000, max: 10000)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Funding rate history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingRateHistoryResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get funding rate history", "sidebarTitle": "Get funding rate history" } } } }, "/v1/funding/overview": { "get": { "tags": [ "Exchange" ], "summary": "Get funding overview", "description": "Handles `GET /v1/funding/overview` via `get.v1.funding.overview`.", "operationId": "get.v1.funding.overview", "parameters": [ { "name": "startTime", "in": "query", "description": "Start time in milliseconds since Unix epoch (default: now - 7 days, max range: 1 year)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "endTime", "in": "query", "description": "End time in milliseconds since Unix epoch (default: now)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "perMarketLimit", "in": "query", "description": "Max number of points to return per market (default: 500, max: 5000)", "required": false, "schema": { "type": "integer", "format": "int64" } } ], "responses": { "200": { "description": "Funding overview history grouped by market", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FundingOverviewResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get funding overview", "sidebarTitle": "Get funding overview" } } } }, "/v1/trader/{authority}/order-history": { "get": { "tags": [ "Trader" ], "summary": "Get order history", "description": "Handles `GET /v1/trader/{authority}/order-history` via `get.v1.trader.by_authority.order_history`.", "operationId": "get.v1.trader.by_authority.order_history", "parameters": [ { "name": "authority", "in": "path", "description": "Authority pubkey", "required": true, "schema": { "type": "string" } }, { "name": "traderPdaIndex", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "marketSymbol", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "privyId", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "orderStatus", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Order history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_OrderHistoryItem" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get order history", "sidebarTitle": "Get order history" } } } }, "/v1/traders/{trader_pubkey}/orders_v2": { "get": { "tags": [ "Trader" ], "summary": "Get order history v2", "description": "Handles `GET /v1/traders/{trader_pubkey}/orders_v2` via `get.v1.traders.by_trader_pubkey.orders_v2`.", "operationId": "get.v1.traders.by_trader_pubkey.orders_v2", "parameters": [ { "name": "market_symbol", "in": "query", "description": "Optional market symbol filter", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "description": "Number of items to return (max 1000)", "required": true, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Optional base64-encoded cursor for pagination. Returns items older than (exclusive of) this cursor.", "required": false, "schema": { "type": "string" } }, { "name": "trader_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_OrderHistoryV2Item" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get order history v2", "sidebarTitle": "Get order history v2" } } } }, "/v1/trader/{authority}/trades-history": { "get": { "tags": [ "Trader" ], "summary": "Get trade history", "description": "Handles `GET /v1/trader/{authority}/trades-history` via `get.v1.trader.by_authority.trades_history`.", "operationId": "get.v1.trader.by_authority.trades_history", "parameters": [ { "name": "authority", "in": "path", "description": "Authority pubkey", "required": true, "schema": { "type": "string" } }, { "name": "pdaIndex", "in": "query", "required": false, "schema": { "type": "integer", "format": "int32", "minimum": 0 } }, { "name": "marketSymbol", "in": "query", "required": false, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Trade history", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_TradeHistoryV2Item" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trade history", "sidebarTitle": "Get trade history" } } } }, "/v1/users/{user_pubkey}/trades_v2": { "get": { "tags": [ "Trader" ], "summary": "Get user trade history v2", "description": "Handles `GET /v1/users/{user_pubkey}/trades_v2` via `get.v1.users.by_user_pubkey.trades_v2`.", "operationId": "get.v1.users.by_user_pubkey.trades_v2", "parameters": [ { "name": "market_symbol", "in": "query", "description": "Optional market symbol to filter by (e.g., \"SOL-PERP\")", "required": false, "schema": { "type": "string" } }, { "name": "trader_pda_index", "in": "query", "description": "Optional trader PDA index to scope results for a specific trader PDA", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "Number of items to return (max 1000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Optional cursor for pagination (format: \"slot\" or \"slot,slot_index\")\nItems returned will be older than (exclusive of) this cursor", "required": false, "schema": { "type": "string" } }, { "name": "privy_id", "in": "query", "description": "Privy user ID (optional)", "required": false, "schema": { "type": "string" } }, { "name": "user_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_TradeHistoryV2Item" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get user trade history v2", "sidebarTitle": "Get user trade history v2" } } } }, "/v1/traders/{trader_pubkey}/trades_v2": { "get": { "tags": [ "Trader" ], "summary": "Get trader trade history v2", "description": "Handles `GET /v1/traders/{trader_pubkey}/trades_v2` via `get.v1.traders.by_trader_pubkey.trades_v2`.", "operationId": "get.v1.traders.by_trader_pubkey.trades_v2", "parameters": [ { "name": "market_symbol", "in": "query", "description": "Optional market symbol to filter by (e.g., \"SOL-PERP\")", "required": false, "schema": { "type": "string" } }, { "name": "trader_pda_index", "in": "query", "description": "Optional trader PDA index to scope results for a specific trader PDA", "required": false, "schema": { "type": "integer", "format": "int32" } }, { "name": "limit", "in": "query", "description": "Number of items to return (max 1000)", "required": false, "schema": { "type": "integer", "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Optional cursor for pagination (format: \"slot\" or \"slot,slot_index\")\nItems returned will be older than (exclusive of) this cursor", "required": false, "schema": { "type": "string" } }, { "name": "privy_id", "in": "query", "description": "Privy user ID (optional)", "required": false, "schema": { "type": "string" } }, { "name": "trader_pubkey", "in": "path", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PaginatedResponse_Vec_TradeHistoryV2Item" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get trader trade history v2", "sidebarTitle": "Get trader trade history v2" } } } }, "/v1/trades/{symbol}/fills": { "get": { "tags": [ "Exchange" ], "summary": "Get market fills", "description": "Returns unaggregated fill records for a market, ordered by time descending.\nOnly fills with valid transaction signatures are included.", "operationId": "get.v1.trades.by_symbol.fills", "parameters": [ { "name": "symbol", "in": "path", "description": "Market symbol", "required": true, "schema": { "type": "string" }, "example": "SOL" }, { "name": "limit", "in": "query", "description": "Maximum number of trade records to return (default: 100, max: 10000)", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "cursor", "in": "query", "description": "Optional opaque cursor returned by a previous request", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "startTime", "in": "query", "description": "Inclusive start time in milliseconds since Unix epoch.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "endTime", "in": "query", "description": "Exclusive end time in milliseconds since Unix epoch.", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } } ], "responses": { "200": { "description": "Market fills retrieved successfully", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/FillsResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Get market fills", "sidebarTitle": "Get market fills" } } } }, "/v1/traders/{trader_pubkey}/notifications": { "get": { "tags": [ "Notifications" ], "summary": "List trader notifications", "description": "Handles `GET /v1/traders/{trader_pubkey}/notifications` via `get.v1.traders.by_trader_pubkey.notifications`.", "operationId": "get.v1.traders.by_trader_pubkey.notifications", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader pubkey (base58)", "required": true, "schema": { "type": "string" } }, { "name": "limit", "in": "query", "required": false, "schema": { "type": [ "integer", "null" ], "format": "int64" } }, { "name": "cursor", "in": "query", "required": false, "schema": { "type": [ "string", "null" ] } }, { "name": "unackedOnly", "in": "query", "description": "When true, return only unacked notifications with a fixed cap of 1000\n(cursor and limit are ignored).", "required": false, "schema": { "type": [ "boolean", "null" ] } } ], "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/GetNotificationsResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "List trader notifications", "sidebarTitle": "List trader notifications" } } } }, "/v1/traders/{trader_pubkey}/notifications/ack/up-to": { "post": { "tags": [ "Notifications" ], "summary": "Acknowledge notifications up to timestamp", "description": "Handles `POST /v1/traders/{trader_pubkey}/notifications/ack/up-to` via `post.v1.traders.by_trader_pubkey.notifications.ack.up_to`.", "operationId": "post.v1.traders.by_trader_pubkey.notifications.ack.up_to", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader pubkey (base58)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request payload for `post.v1.traders.by_trader_pubkey.notifications.ack.up_to`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AckBeforeTimestampBody" }, "example": { "beforeTimestamp": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": {} } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Acknowledge notifications up to timestamp", "sidebarTitle": "Acknowledge notifications up to timestamp" } } } }, "/v1/traders/{trader_pubkey}/notifications/ack/notifications": { "post": { "tags": [ "Notifications" ], "summary": "Acknowledge notifications", "description": "Handles `POST /v1/traders/{trader_pubkey}/notifications/ack/notifications` via `post.v1.traders.by_trader_pubkey.notifications.ack.notifications`.", "operationId": "post.v1.traders.by_trader_pubkey.notifications.ack.notifications", "parameters": [ { "name": "trader_pubkey", "in": "path", "description": "Trader pubkey (base58)", "required": true, "schema": { "type": "string" } } ], "requestBody": { "description": "JSON request payload for `post.v1.traders.by_trader_pubkey.notifications.ack.notifications`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AckNotificationsBody" }, "example": { "items": [ { "type": "event" } ] } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": {} } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Acknowledge notifications", "sidebarTitle": "Acknowledge notifications" } } } }, "/v1/ix/place-isolated-limit-order": { "post": { "tags": [ "Trader" ], "summary": "Build isolated limit order transaction", "description": "Handles `POST /v1/ix/place-isolated-limit-order` via `post.v1.ix.place_isolated_limit_order`.", "operationId": "post.v1.ix.place_isolated_limit_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_isolated_limit_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedLimitOrderRequest" }, "example": { "authority": "string", "side": "string", "symbol": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build isolated limit order transaction", "sidebarTitle": "Build isolated limit order transaction" } }, "x-sdk-path": "/ix/place-isolated-limit-order" } }, "/v1/ix/place-isolated-market-order": { "post": { "tags": [ "Trader" ], "summary": "Build isolated market order transaction", "description": "Handles `POST /v1/ix/place-isolated-market-order` via `post.v1.ix.place_isolated_market_order`.", "operationId": "post.v1.ix.place_isolated_market_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_isolated_market_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedMarketOrderRequest" }, "example": { "authority": "string", "side": "string", "symbol": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build isolated market order transaction", "sidebarTitle": "Build isolated market order transaction" } }, "x-sdk-path": "/ix/place-isolated-market-order" } }, "/v1/ix/cancel-conditional-order": { "post": { "tags": [ "Trader" ], "summary": "Build cancel conditional order transaction", "description": "Handles `POST /v1/ix/cancel-conditional-order` via `post.v1.ix.cancel_conditional_order`.", "operationId": "post.v1.ix.cancel_conditional_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.cancel_conditional_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelConditionalOrderRequest" }, "example": { "authority": "string", "conditionalOrderIndex": 0, "executionDirection": "string", "symbol": "string", "traderPdaIndex": 0 } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build cancel conditional order transaction", "sidebarTitle": "Build cancel conditional order transaction" } } } }, "/v1/ix/place-stop-loss-order": { "post": { "tags": [ "Trader" ], "summary": "Build stop loss order transaction", "description": "Handles `POST /v1/ix/place-stop-loss-order` via `post.v1.ix.place_stop_loss_order`.", "operationId": "post.v1.ix.place_stop_loss_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_stop_loss_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceStopLossOrderRequest" }, "example": { "numBaseLots": 0 } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build stop loss order transaction", "sidebarTitle": "Build stop loss order transaction" } } } }, "/v1/ix/cancel-stop-loss-order": { "post": { "tags": [ "Trader" ], "summary": "Build cancel stop loss order transaction", "description": "Handles `POST /v1/ix/cancel-stop-loss-order` via `post.v1.ix.cancel_stop_loss_order`.", "operationId": "post.v1.ix.cancel_stop_loss_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.cancel_stop_loss_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CancelStopLossOrderRequest" }, "example": { "authority": "string", "executionDirection": "string", "symbol": "string", "traderPdaIndex": 0 } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build cancel stop loss order transaction", "sidebarTitle": "Build cancel stop loss order transaction" } } } }, "/v1/ix/place-attached-conditional-order": { "post": { "tags": [ "Trader" ], "summary": "Build attached conditional order transaction", "description": "Handles `POST /v1/ix/place-attached-conditional-order` via `post.v1.ix.place_attached_conditional_order`.", "operationId": "post.v1.ix.place_attached_conditional_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_attached_conditional_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceAttachedConditionalOrderRequest" }, "example": { "authority": "string", "orderPriceInTicks": 0, "orderSequenceNumber": "string", "symbol": "string", "traderPdaIndex": 0 } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build attached conditional order transaction", "sidebarTitle": "Build attached conditional order transaction" } } } }, "/v1/ix/place-position-conditional-order": { "post": { "tags": [ "Trader" ], "summary": "Build position conditional order transaction", "description": "Handles `POST /v1/ix/place-position-conditional-order` via `post.v1.ix.place_position_conditional_order`.", "operationId": "post.v1.ix.place_position_conditional_order", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_position_conditional_order`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlacePositionConditionalOrderRequest" }, "example": { "authority": "string", "symbol": "string", "traderPdaIndex": 0 } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build position conditional order transaction", "sidebarTitle": "Build position conditional order transaction" } } } }, "/v1/ix/place-isolated-limit-order-with-conditionals": { "post": { "tags": [ "Trader" ], "summary": "Build isolated limit order transaction with conditionals", "description": "Handles `POST /v1/ix/place-isolated-limit-order-with-conditionals` via `post.v1.ix.place_isolated_limit_order_with_conditionals`.", "operationId": "post.v1.ix.place_isolated_limit_order_with_conditionals", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_isolated_limit_order_with_conditionals`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedLimitOrderWithConditionalsRequest" }, "example": { "authority": "string", "side": "string", "symbol": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build isolated limit order transaction with conditionals", "sidebarTitle": "Build isolated limit order transaction with conditionals" } } } }, "/v1/ix/place-isolated-limit-order-enhanced": { "post": { "tags": [ "Trader" ], "summary": "Build isolated limit order transaction with liquidation estimate", "description": "Handles `POST /v1/ix/place-isolated-limit-order-enhanced` via `post.v1.ix.place_isolated_limit_order_enhanced`.", "operationId": "post.v1.ix.place_isolated_limit_order_enhanced", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_isolated_limit_order_enhanced`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedLimitOrderRequest" }, "example": { "authority": "string", "side": "string", "symbol": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedLimitOrderEnhancedResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build isolated limit order transaction with liquidation estimate", "sidebarTitle": "Build isolated limit order transaction with liquidation estimate" } } } }, "/v1/ix/place-isolated-market-order-enhanced": { "post": { "tags": [ "Trader" ], "summary": "Build isolated market order transaction with liquidation estimate", "description": "Handles `POST /v1/ix/place-isolated-market-order-enhanced` via `post.v1.ix.place_isolated_market_order_enhanced`.", "operationId": "post.v1.ix.place_isolated_market_order_enhanced", "requestBody": { "description": "JSON request payload for `post.v1.ix.place_isolated_market_order_enhanced`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedMarketOrderRequest" }, "example": { "authority": "string", "side": "string", "symbol": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PlaceIsolatedMarketOrderEnhancedResponse" } } } } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Build isolated market order transaction with liquidation estimate", "sidebarTitle": "Build isolated market order transaction with liquidation estimate" } } } }, "/v1/invite/validate": { "post": { "tags": [ "Invite" ], "summary": "Validate invite", "description": "Validates an invite code and whitelists the wallet if the code is valid and unused.", "operationId": "post.v1.invite.validate", "requestBody": { "description": "JSON request payload for `post.v1.invite.validate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInviteRequest" }, "example": { "code": "string", "wallet_address": "string" } } }, "required": true }, "responses": { "200": { "description": "Validation successful", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ValidateInviteResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Validate invite", "sidebarTitle": "Validate invite" } } } }, "/v1/invite/check/{wallet}": { "get": { "tags": [ "Invite" ], "summary": "Check wallet invite status", "description": "Checks whether a wallet address is whitelisted and returns associated information.", "operationId": "get.v1.invite.check.by_wallet", "parameters": [ { "name": "wallet", "in": "path", "description": "Solana wallet address to check", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Whitelist status retrieved", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/CheckWalletResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Check wallet invite status", "sidebarTitle": "Check wallet invite status" } } } }, "/v1/referral/activate": { "post": { "tags": [ "Invite" ], "summary": "Activate referral (deprecated June 30, 2026)", "description": "Deprecated on June 30, 2026. New onboarding should use delegated on-chain permission accounts or `/v1/referral/activate-tx` instead.", "operationId": "post.v1.referral.activate", "requestBody": { "description": "JSON request payload for `post.v1.referral.activate`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateInviteWithReferralRequest" }, "example": { "authority": "string", "referral_code": "string" } } }, "required": true }, "responses": { "200": { "description": "Trader created", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateInviteResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "429": { "$ref": "#/components/responses/ErrorResponse" }, "504": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Activate referral (deprecated June 30, 2026)", "sidebarTitle": "Activate referral (deprecated June 30, 2026)" } } } }, "/v1/referral/activation-permission": { "get": { "tags": [ "Invite" ], "summary": "Get referral activation permission", "description": "Returns the trader onboarder, risk authority, and permission account needed to build a referral activation transaction.", "operationId": "get.v1.referral.activation_permission", "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ReferralActivationPermissionResponse" } } } } }, "x-mint": { "metadata": { "title": "Get referral activation permission", "sidebarTitle": "Get referral activation permission" } } } }, "/v1/referral/activate-tx": { "post": { "tags": [ "Invite" ], "summary": "Activate referral with user-funded transaction", "description": "Activates a trader with a valid referral code by validating a user-funded transaction, signing it with the referral activation onboarder, and submitting it. The trader authority or another non-Phoenix payer must pay fees and trader-account rent.", "operationId": "post.v1.referral.activate_tx", "requestBody": { "description": "JSON request payload for `post.v1.referral.activate_tx`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateReferralTxRequest" }, "example": { "recent_blockhash": "string", "referral_code": "string", "trader_authority": "string", "transaction": "string" } } }, "required": true }, "responses": { "200": { "description": "", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ActivateReferralTxResponse" } } } } }, "x-mint": { "metadata": { "title": "Activate referral with user-funded transaction", "sidebarTitle": "Activate referral with user-funded transaction" } } } }, "/v1/auth/login/privy": { "post": { "tags": [ "Auth" ], "summary": "Log in with Privy token", "description": "Handles `POST /v1/auth/login/privy` via `post.v1.auth.login.privy`.", "operationId": "post.v1.auth.login.privy", "requestBody": { "description": "JSON request payload for `post.v1.auth.login.privy`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/PrivyLoginRequest" }, "example": { "privy_token": "string" } } }, "required": true }, "responses": { "200": { "description": "Phoenix JWT pair issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "502": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Log in with Privy token", "sidebarTitle": "Log in with Privy token" } } } }, "/v1/auth/wallet/transaction-challenge": { "post": { "tags": [ "Auth" ], "summary": "Create wallet transaction challenge", "description": "Handles `POST /v1/auth/wallet/transaction-challenge` via `post.v1.auth.wallet.transaction_challenge`.", "operationId": "post.v1.auth.wallet.transaction_challenge", "requestBody": { "description": "JSON request payload for `post.v1.auth.wallet.transaction_challenge`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionChallengeRequest" }, "example": { "wallet_pubkey": "string" } } }, "required": true }, "responses": { "200": { "description": "Challenge issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionChallengeResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Create wallet transaction challenge", "sidebarTitle": "Create wallet transaction challenge" } } } }, "/v1/auth/login/wallet/transaction": { "post": { "tags": [ "Auth" ], "summary": "Log in with signed wallet transaction", "description": "Handles `POST /v1/auth/login/wallet/transaction` via `post.v1.auth.login.wallet.transaction`.", "operationId": "post.v1.auth.login.wallet.transaction", "requestBody": { "description": "JSON request payload for `post.v1.auth.login.wallet.transaction`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletTransactionLoginRequest" }, "example": { "nonce_id": "string", "signed_transaction": "string", "wallet_pubkey": "string" } } }, "required": true }, "responses": { "200": { "description": "Phoenix JWT pair issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "403": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" }, "503": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Log in with signed wallet transaction", "sidebarTitle": "Log in with signed wallet transaction" } } } }, "/v1/auth/login/service/challenge": { "post": { "tags": [ "Auth" ], "summary": "Create service login challenge", "description": "Handles `POST /v1/auth/login/service/challenge` via `post.v1.auth.login.service.challenge`.", "operationId": "post.v1.auth.login.service.challenge", "requestBody": { "description": "JSON request payload for `post.v1.auth.login.service.challenge`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceChallengeRequest" }, "example": { "client_id": "string" } } }, "required": true }, "responses": { "200": { "description": "Challenge issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceChallengeResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Create service login challenge", "sidebarTitle": "Create service login challenge" } } } }, "/v1/auth/login/service": { "post": { "tags": [ "Auth" ], "summary": "Log in with service signature", "description": "Handles `POST /v1/auth/login/service` via `post.v1.auth.login.service`.", "operationId": "post.v1.auth.login.service", "requestBody": { "description": "JSON request payload for `post.v1.auth.login.service`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ServiceLoginRequest" }, "example": { "client_id": "string", "nonce": "string", "signature": "string", "timestamp": "string" } } }, "required": true }, "responses": { "200": { "description": "Phoenix JWT pair issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Log in with service signature", "sidebarTitle": "Log in with service signature" } } } }, "/v1/auth/nonce": { "get": { "tags": [ "Auth" ], "summary": "Get wallet login nonce", "description": "Handles `GET /v1/auth/nonce` via `get.v1.auth.nonce`.", "operationId": "get.v1.auth.nonce", "parameters": [ { "name": "wallet_pubkey", "in": "query", "required": true, "schema": { "type": "string" } } ], "responses": { "200": { "description": "Nonce issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletNonceResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Get wallet login nonce", "sidebarTitle": "Get wallet login nonce" } } } }, "/v1/auth/login/wallet": { "post": { "tags": [ "Auth" ], "summary": "Log in with wallet signature", "description": "Handles `POST /v1/auth/login/wallet` via `post.v1.auth.login.wallet`.", "operationId": "post.v1.auth.login.wallet", "requestBody": { "description": "JSON request payload for `post.v1.auth.login.wallet`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/WalletLoginRequest" }, "example": { "nonce_id": "string", "signature": "string", "wallet_pubkey": "string" } } }, "required": true }, "responses": { "200": { "description": "Phoenix JWT pair issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "400": { "$ref": "#/components/responses/ErrorResponse" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Log in with wallet signature", "sidebarTitle": "Log in with wallet signature" } } } }, "/v1/auth/refresh": { "post": { "tags": [ "Auth" ], "summary": "Refresh session", "description": "Handles `POST /v1/auth/refresh` via `post.v1.auth.refresh`.", "operationId": "post.v1.auth.refresh", "requestBody": { "description": "JSON request payload for `post.v1.auth.refresh`.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/RefreshRequest" }, "example": { "refresh_token": "string" } } }, "required": true }, "responses": { "200": { "description": "New token pair issued", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AuthResponse" } } } }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "409": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Refresh session", "sidebarTitle": "Refresh session" } } } }, "/v1/auth/logout": { "post": { "tags": [ "Auth" ], "summary": "Log out", "description": "Handles `POST /v1/auth/logout` via `post.v1.auth.logout`.", "operationId": "post.v1.auth.logout", "responses": { "204": { "description": "Session revoked" }, "401": { "$ref": "#/components/responses/ErrorResponse" }, "404": { "$ref": "#/components/responses/ErrorResponse" }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "security": [ { "PhoenixBearerAuth": [] } ], "x-mint": { "metadata": { "title": "Log out", "sidebarTitle": "Log out" } } } }, "/v1/auth/jwks": { "get": { "tags": [ "Auth" ], "summary": "Get JWKS", "description": "Handles `GET /v1/auth/jwks` via `get.v1.auth.jwks`.", "operationId": "get.v1.auth.jwks", "responses": { "200": { "description": "JWKS returned", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/JwksResponse" } } } }, "500": { "$ref": "#/components/responses/ErrorResponse" } }, "x-mint": { "metadata": { "title": "Get JWKS", "sidebarTitle": "Get JWKS" } } } } }, "components": { "schemas": { "AckBeforeTimestampBody": { "type": "object", "required": [ "beforeTimestamp" ], "properties": { "beforeTimestamp": { "type": "string", "format": "date-time" } } }, "AckNotificationItem": { "oneOf": [ { "type": "object", "required": [ "type" ], "properties": { "eventIndex": { "type": [ "integer", "null" ], "format": "int32" }, "id": { "type": [ "integer", "null" ], "format": "int64" }, "instructionIndex": { "type": [ "integer", "null" ], "format": "int32" }, "recipientIndex": { "type": [ "integer", "null" ], "format": "int32" }, "slot": { "type": [ "integer", "null" ], "format": "int64" }, "slotIndex": { "type": [ "integer", "null" ], "format": "int32" }, "type": { "type": "string", "enum": [ "event" ] } } }, { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "admin" ] } } }, { "type": "object", "required": [ "id", "type" ], "properties": { "id": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "general" ] } } } ], "description": "Event ack: by DB id or by composite index (slot, slotIndex,\ninstructionIndex, eventIndex, recipientIndex). JSON uses camelCase for\nfield names and lowercase for the \"type\" discriminant (\"event\" | \"admin\" |\n\"general\")." }, "AckNotificationsBody": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/AckNotificationItem" } } } }, "ActivateInviteResponse": { "type": "object", "required": [ "trader_pda" ], "properties": { "trader_pda": { "type": "string" } } }, "ActivateInviteWithReferralRequest": { "type": "object", "required": [ "authority", "referral_code" ], "properties": { "authority": { "type": "string" }, "referral_code": { "type": "string" } } }, "ActivateReferralTxRequest": { "type": "object", "required": [ "referral_code", "trader_authority", "recent_blockhash", "transaction" ], "properties": { "recent_blockhash": { "type": "string" }, "referral_code": { "type": "string" }, "trader_authority": { "type": "string" }, "trader_pda_index": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "trader_subaccount_index": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "transaction": { "type": "string" } } }, "ActivateReferralTxResponse": { "type": "object", "required": [ "trader_pda", "referral_code", "status" ], "properties": { "referral_code": { "type": "string" }, "signature": { "type": [ "string", "null" ] }, "status": { "$ref": "#/components/schemas/ActivateReferralTxStatus" }, "trader_pda": { "type": "string" } } }, "ActivateReferralTxStatus": { "type": "string", "enum": [ "activated", "submitted", "already_activated" ] }, "AggregatedTrades": { "type": "object", "description": "Aggregated trades summary for an instruction", "required": [ "totalBaseQtyFilled", "totalQuoteQtyFilled", "totalTakerFee", "totalNumFills", "numTrades" ], "properties": { "numTrades": { "type": "integer", "format": "int32" }, "totalBaseQtyFilled": { "type": "string" }, "totalNumFills": { "type": "integer", "format": "int32" }, "totalQuoteQtyFilled": { "type": "string" }, "totalTakerFee": { "type": "string" } } }, "ApiAccountMeta": { "type": "object", "description": "Account metadata returned from instruction-building endpoints.", "required": [ "pubkey", "isSigner", "isWritable" ], "properties": { "isSigner": { "type": "boolean" }, "isWritable": { "type": "boolean" }, "pubkey": { "type": "string" } } }, "ApiCandle": { "type": "object", "description": "API Candle structure (Trading View Bar interface)\nNote: This is a simplified version. The full implementation with From\nconversions is in eternal-api/src/api/candles.rs to avoid heavy\ndependencies.", "required": [ "time", "low", "high", "open", "close" ], "properties": { "close": { "type": "number", "format": "double" }, "externalSource": { "type": [ "string", "null" ], "description": "External candle source name (e.g., \"binance\", \"coinbase\").\nOmitted from JSON for exchange candles to preserve backward\ncompatibility." }, "high": { "type": "number", "format": "double" }, "low": { "type": "number", "format": "double" }, "markClose": { "type": "number", "format": "double" }, "markHigh": { "type": "number", "format": "double" }, "markLow": { "type": "number", "format": "double" }, "markOpen": { "type": "number", "format": "double" }, "open": { "type": "number", "format": "double" }, "time": { "type": "integer", "format": "int64", "description": "Candle timestamp as a Unix timestamp in milliseconds (UTC)." }, "tradeCount": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "volume": { "type": [ "number", "null" ], "format": "double" }, "volumeQuote": { "type": [ "number", "null" ], "format": "double", "description": "Quote currency volume (e.g. USDC) for the candle period." } } }, "ApiInstructionResponse": { "type": "object", "description": "API representation of a Solana instruction.\n\nNote: this is a pure DTO. When needed, clients/servers can enable the\nappropriate conversion logic in the consumer crate to avoid forcing a\nSolana dependency in `phoenix-api-types`.", "required": [ "data", "keys", "programId" ], "properties": { "data": { "type": "array", "items": { "type": "integer", "format": "int32", "minimum": 0 } }, "keys": { "type": "array", "items": { "$ref": "#/components/schemas/ApiAccountMeta" } }, "programId": { "type": "string" } } }, "AuthResponse": { "type": "object", "required": [ "token_type", "access_token", "expires_in", "refresh_token", "refresh_expires_in", "pop_key" ], "properties": { "access_token": { "type": "string" }, "expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "pop_key": { "type": "string" }, "refresh_expires_in": { "type": "integer", "format": "int64", "minimum": 0 }, "refresh_token": { "type": "string" }, "token_type": { "type": "string" } } }, "AuthoritySetView": { "type": "object", "description": "View for authority set containing all authority pubkeys", "required": [ "rootAuthority", "riskAuthority", "marketAuthority", "oracleAuthority", "adlAuthority", "cancelAuthority", "backstopAuthority" ], "properties": { "adlAuthority": { "type": "string", "description": "ADL authority public key." }, "backstopAuthority": { "type": "string", "description": "Backstop authority public key." }, "cancelAuthority": { "type": "string", "description": "Cancel authority public key." }, "marketAuthority": { "type": "string", "description": "Market authority public key." }, "oracleAuthority": { "type": "string", "description": "Oracle authority public key." }, "riskAuthority": { "type": "string", "description": "Risk authority public key." }, "rootAuthority": { "type": "string", "description": "Root authority public key." } } }, "BuildRegisterIxsRequest": { "type": "object", "description": "Request payload for /exchange/build-register-ixs.", "required": [ "traderAuthority", "txFeePayer" ], "properties": { "maxPositions": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "traderAuthority": { "type": "string" }, "txFeePayer": { "type": "string" } } }, "BuildRegisterIxsResponse": { "type": "object", "description": "Response payload for /exchange/build-register-ixs.", "required": [ "instructions", "traderPda", "traderOnboarder", "txFeePayer", "maxPositions", "includeRegisterTrader" ], "properties": { "includeRegisterTrader": { "type": "boolean" }, "instructions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } }, "maxPositions": { "type": "integer", "format": "int32", "minimum": 0 }, "traderOnboarder": { "type": "string" }, "traderPda": { "type": "string" }, "txFeePayer": { "type": "string" } } }, "CancelConditionalOrderRequest": { "type": "object", "description": "Request payload for /v1/ix/cancel-conditional-order.", "required": [ "authority", "traderPdaIndex", "symbol", "conditionalOrderIndex", "executionDirection" ], "properties": { "authority": { "type": "string" }, "conditionalOrderIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "executionDirection": { "type": "string" }, "isIsolated": { "type": "boolean" }, "positionAuthority": { "type": [ "string", "null" ] }, "symbol": { "type": "string" }, "traderPdaIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CancelStopLossOrderRequest": { "type": "object", "description": "Request payload for /ix/cancel-stop-loss-order.", "required": [ "authority", "traderPdaIndex", "symbol", "executionDirection" ], "properties": { "authority": { "type": "string" }, "executionDirection": { "type": "string", "description": "Which trigger direction to cancel: e.g. \"greater_than\" or \"less_than\"." }, "isIsolated": { "type": "boolean" }, "positionAuthority": { "type": [ "string", "null" ] }, "symbol": { "type": "string" }, "traderPdaIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "CapabilityAccessView": { "type": "object", "description": "Capability exposure for the current trader state. `immediate` indicates the\naction can be taken without additional state transitions, while\n`via_cold_activation` signals the action will succeed if the trader warms\nfrom `InitializedCold` to `InitializedHot` during processing.", "required": [ "immediate" ], "properties": { "immediate": { "type": "boolean", "description": "Whether this capability is currently available." }, "viaColdActivation": { "type": "boolean", "description": "Whether this capability becomes available after cold activation." } } }, "CheckWalletResponse": { "type": "object", "required": [ "whitelisted" ], "properties": { "invite_code_used": { "type": [ "string", "null" ] }, "whitelisted": { "type": "boolean" }, "whitelisted_at": { "type": [ "string", "null" ], "format": "date-time" } } }, "CollateralEvent": { "type": "object", "description": "A single collateral event (deposit or withdrawal)", "required": [ "slot", "slotIndex", "eventIndex", "traderPdaIndex", "traderSubaccountIndex", "eventType", "amount", "collateralAfter", "timestamp" ], "properties": { "amount": { "type": "integer", "format": "int64", "description": "Amount deposited or withdrawn (in quote lots, 6 decimals)" }, "collateralAfter": { "type": "integer", "format": "int64", "description": "Collateral balance after this event (in quote lots, 6 decimals)" }, "eventIndex": { "type": "integer", "format": "int32", "description": "Event index for ordering within the slot" }, "eventType": { "type": "string", "description": "Event type: 'deposit' or 'withdrawal'" }, "slot": { "type": "integer", "format": "int64", "description": "Solana slot when the event occurred" }, "slotIndex": { "type": "integer", "format": "int32", "description": "Index within the slot" }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." }, "traderPdaIndex": { "type": "integer", "format": "int32", "description": "Trader PDA index (usually 0)" }, "traderSubaccountIndex": { "type": "integer", "format": "int32", "description": "Trader subaccount index" } } }, "CollateralHistoryResponse": { "type": "object", "description": "Response for collateral event history queries", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/CollateralEvent" }, "description": "The data payload (array of items)" }, "hasMore": { "type": "boolean", "description": "Whether there are more results in the requested direction" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching older results" }, "prevCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching newer results" } } }, "CommodityMarketCalendarResponse": { "type": "object", "required": [ "market", "loadedAt", "rawJson", "calendar" ], "properties": { "calendar": { "$ref": "#/components/schemas/CommodityMarketCalendarView" }, "loadedAt": { "type": "string", "format": "date-time" }, "market": { "type": "string" }, "rawJson": { "type": "string" } } }, "CommodityMarketCalendarView": { "type": "object", "required": [ "weeklySchedule", "dateOverrides" ], "properties": { "dateOverrides": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CommodityMarketDaySchedule" }, "propertyNames": { "type": "string" } }, "weeklySchedule": { "type": "object", "additionalProperties": { "$ref": "#/components/schemas/CommodityMarketDaySchedule" }, "propertyNames": { "type": "string" } } } }, "CommodityMarketDaySchedule": { "type": "object", "required": [ "sessions" ], "properties": { "sessions": { "type": "array", "items": { "$ref": "#/components/schemas/CommodityMarketSessionRange" } } } }, "CommodityMarketSessionRange": { "type": "object", "description": "A single named session within a [`CommodityMarketDaySchedule`].", "required": [ "start", "end", "mode" ], "properties": { "end": { "type": "string" }, "mode": { "type": "string", "description": "Serialized calendar mode name, e.g. `\"EXTERNAL\"`, `\"INTERNAL\"`." }, "start": { "type": "string" } } }, "CommodityMarketState": { "type": "string", "description": "Represents the state of a RWA market. This type is shared between on-chain\nand off-chain components", "enum": [ "active", "afterHours", "reopen" ] }, "CommodityMarketStateView": { "type": "string", "enum": [ "open", "afterHours" ] }, "CommodityMetadata": { "type": "object", "description": "Commodity-specific market metadata.", "required": [ "isCommodity", "isReopen", "isAfterHours", "status", "afterHoursRadius" ], "properties": { "afterHoursRadius": { "type": "string", "description": "Commodity after-hours radius in price units." }, "executionPriceBand": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketPriceBand", "description": "Price band currently applied to execution-visible orderbook levels." } ] }, "isAfterHours": { "type": "boolean", "description": "Parsed after-hours flag." }, "isCommodity": { "type": "boolean", "description": "Parsed commodity flag. Always true when this object is present." }, "isReopen": { "type": "boolean", "description": "Parsed reopen flag." }, "lastIndexExpiryTimestamp": { "type": [ "integer", "null" ], "format": "int64", "description": "Unix timestamp when the last known index price expires.", "minimum": 0 }, "lastKnownIndexPrice": { "type": [ "string", "null" ], "description": "Last index price used for commodity after-hours/reopen behavior." }, "markPriceBand": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketPriceBand", "description": "Mark-price clamp band around the last known index price." } ] }, "status": { "$ref": "#/components/schemas/CommodityMarketState", "description": "Derived commodity state." } } }, "ConditionalTriggerRequest": { "type": "object", "description": "Trigger configuration for attached conditional orders.", "required": [ "side" ], "properties": { "executionPrice": { "type": [ "number", "null" ], "format": "double" }, "executionPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "orderKind": { "type": [ "string", "null" ] }, "side": { "type": "string" }, "triggerPrice": { "type": [ "number", "null" ], "format": "double" }, "triggerPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "CooldownStatus": { "type": "object", "description": "Withdrawal cooldown status for a trader PDA.\n\nIndicates whether the trader can withdraw based on the time elapsed since\ntheir last deposit. This applies at the PDA level (main account), not\nper-subaccount.\n\nClients should compute withdrawal eligibility as:\n`canWithdraw = (currentSlot >= lastDepositSlot + cooldownPeriodInSlots) &&\ncapabilities.withdraw`", "required": [ "lastDepositSlot", "cooldownPeriodInSlots" ], "properties": { "cooldownPeriodInSlots": { "type": "integer", "format": "int64", "description": "Number of slots required to wait after a deposit before withdrawing.", "minimum": 0 }, "lastDepositSlot": { "type": "integer", "format": "int64", "description": "Slot when the trader last deposited collateral.", "minimum": 0 } } }, "CurrentOrderState": { "type": "object", "description": "Current order state from orders table", "required": [ "orderSequenceNumber", "side", "price", "baseQty", "remainingBaseQty", "filledBaseQty", "releasedBaseQty", "orderStatus" ], "properties": { "baseQty": { "type": "string" }, "cancelledAt": { "type": [ "string", "null" ], "format": "date-time" }, "filledBaseQty": { "type": "string" }, "lastFillAt": { "type": [ "string", "null" ], "format": "date-time" }, "orderSequenceNumber": { "type": "integer", "format": "int64" }, "orderStatus": { "type": "string", "description": "\"active\", \"filled\", \"cancelled\"" }, "placedAt": { "type": [ "string", "null" ], "format": "date-time" }, "price": { "type": "string" }, "releasedBaseQty": { "type": "string", "description": "base_qty - remaining_base_qty" }, "remainingBaseQty": { "type": "string" }, "side": { "type": "string" } } }, "ErrorResponse": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" } } }, "ExchangeKeysView": { "type": "object", "required": [ "globalConfig", "currentAuthorities", "pendingAuthorities", "canonicalMint", "globalVault", "perpAssetMap", "globalTraderIndex", "activeTraderBuffer", "withdrawQueue" ], "properties": { "activeTraderBuffer": { "type": "array", "items": { "type": "string" }, "description": "Active trader buffer account public keys." }, "canonicalMint": { "type": "string", "description": "Canonical quote mint public key." }, "currentAuthorities": { "$ref": "#/components/schemas/AuthoritySetView", "description": "Currently active authority set." }, "globalConfig": { "type": "string", "description": "Global configuration account public key." }, "globalTraderIndex": { "type": "array", "items": { "type": "string" }, "description": "Global trader index account public keys." }, "globalVault": { "type": "string", "description": "Global vault public key." }, "pendingAuthorities": { "$ref": "#/components/schemas/AuthoritySetView", "description": "Pending authority set awaiting activation." }, "perpAssetMap": { "type": "string", "description": "Perp asset map public key." }, "withdrawQueue": { "type": "string", "description": "Withdraw queue account public key." } } }, "ExchangeLeverageTier": { "type": "object", "description": "Leverage tier with risk factors as f64 percentages.\nUsed by the `/exchange` endpoint.", "required": [ "maxLeverage", "maxSizeBaseLots", "limitOrderRiskFactor" ], "properties": { "limitOrderRiskFactor": { "type": "number", "format": "double", "description": "The limit order risk factor as a percentage (e.g., 60.0 = 60%)." }, "limitOrderRiskFactorBps": { "type": [ "integer", "null" ], "format": "int32", "description": "The limit order risk factor in basis points (e.g., 6000 = 60%).", "minimum": 0 }, "maxLeverage": { "type": "number", "format": "double", "description": "Maximum leverage for this tier." }, "maxSizeBaseLots": { "type": "integer", "format": "int64", "description": "Maximum size in base lots for this tier.", "minimum": 0 } } }, "ExchangeMarketConfig": { "type": "object", "description": "Static market configuration without live data like prices or open interest.\nUsed by the `/exchange` endpoint to return market parameters.", "required": [ "symbol", "assetId", "marketStatus", "marketPubkey", "splinePubkey", "tickSize", "baseLotsDecimals", "takerFee", "makerFee", "leverageTiers", "riskFactors", "fundingIntervalSeconds", "fundingPeriodSeconds", "maxFundingRatePerInterval", "openInterestCapBaseLots", "maxLiquidationSizeBaseLots", "isolatedOnly" ], "properties": { "assetId": { "type": "integer", "format": "int32", "description": "Numeric asset identifier.", "minimum": 0 }, "baseLotsDecimals": { "type": "integer", "format": "int32", "description": "Base-lot decimal exponent." }, "commodityMetadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommodityMetadata", "description": "Commodity-specific metadata, present only for commodity markets." } ] }, "fundingIntervalSeconds": { "type": "integer", "format": "int32", "description": "Funding interval length in seconds.", "minimum": 0 }, "fundingPeriodSeconds": { "type": "integer", "format": "int32", "description": "Funding period length in seconds.", "minimum": 0 }, "isolatedOnly": { "type": "boolean", "description": "Whether this market only supports isolated margin positions" }, "leverageTiers": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeLeverageTier" }, "description": "Configured leverage tiers." }, "makerFee": { "type": "number", "format": "double", "description": "Maker fee (percent)." }, "marketPubkey": { "type": "string", "description": "The orderbook account pubkey (base58 encoded)" }, "marketStatus": { "$ref": "#/components/schemas/MarketStatus", "description": "Current market status." }, "maxFundingRatePerInterval": { "type": "integer", "format": "int64", "description": "Maximum absolute funding rate per interval." }, "maxFundingRatePerIntervalPercentage": { "type": "number", "format": "double", "description": "Maximum absolute funding rate per interval as a percentage of notional\nat the current mark price." }, "maxLiquidationSizeBaseLots": { "$ref": "#/components/schemas/JsSafeU64", "description": "Maximum size for a single liquidation (in base lots)" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketPublicMetadata", "description": "Public market metadata configured off-chain." } ] }, "openInterestCapBaseLots": { "$ref": "#/components/schemas/JsSafeU64", "description": "Maximum open interest allowed for this market (in base lots)" }, "riskFactors": { "$ref": "#/components/schemas/ExchangeRiskFactors", "description": "Risk factors as percentages." }, "splinePubkey": { "type": "string", "description": "The spline collection PDA (derived from market_pubkey)" }, "statsSnapshot": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketStatsSnapshot", "description": "Optional live stats snapshot for seeding clients before websocket\nupdates." } ] }, "symbol": { "type": "string", "description": "Market symbol (for example, \"SOL-PERP\")." }, "takerFee": { "type": "number", "format": "double", "description": "Taker fee (percent)." }, "tickSize": { "type": "integer", "format": "int64", "description": "Tick size in quote lots per base lot per tick.", "minimum": 0 } } }, "ExchangeMarketSnapshot": { "type": "object", "required": [ "symbol", "assetId", "marketStatus", "marketPubkey", "splinePubkey", "tickSize", "baseLotsDecimals", "takerFee", "makerFee", "leverageTiers", "riskFactors", "fundingConfig", "openInterestCapBaseLots", "maxLiquidationSizeBaseLots", "isolatedOnly", "markPriceParameters" ], "properties": { "assetId": { "type": "integer", "format": "int32", "minimum": 0 }, "baseLotsDecimals": { "type": "integer", "format": "int32" }, "commodityMetadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExchangeWsCommodityMetadata" } ] }, "fundingConfig": { "$ref": "#/components/schemas/ExchangeWsFundingConfig" }, "isolatedOnly": { "type": "boolean" }, "leverageTiers": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeWsLeverageTier" } }, "makerFee": { "type": "number", "format": "double" }, "markPriceParameters": { "$ref": "#/components/schemas/ExchangeWsMarkPriceParameters" }, "marketPubkey": { "type": "string" }, "marketStatus": { "$ref": "#/components/schemas/MarketStatus" }, "maxLiquidationSizeBaseLots": { "$ref": "#/components/schemas/JsSafeU64" }, "metadata": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketPublicMetadata" } ] }, "openInterestCapBaseLots": { "$ref": "#/components/schemas/JsSafeU64" }, "riskFactors": { "$ref": "#/components/schemas/ExchangeWsRiskFactors" }, "splinePubkey": { "type": "string" }, "symbol": { "type": "string" }, "takerFee": { "type": "number", "format": "double" }, "tickSize": { "type": "integer", "format": "int64", "minimum": 0 } } }, "ExchangeRiskFactors": { "type": "object", "description": "Risk factors as percentages.\nUsed by the `/exchange` endpoint.", "required": [ "maintenance", "backstop", "highRisk", "upnl", "upnlForWithdrawals", "cancelOrder" ], "properties": { "backstop": { "type": "number", "format": "double", "description": "Backstop liquidation risk factor as a percentage." }, "backstopBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Backstop liquidation risk factor in basis points.", "minimum": 0 }, "cancelOrder": { "type": "number", "format": "double", "description": "Cancel order risk factor as a percentage." }, "cancelOrderBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Cancel order risk factor in basis points.", "minimum": 0 }, "highRisk": { "type": "number", "format": "double", "description": "High risk threshold as a percentage." }, "highRiskBps": { "type": [ "integer", "null" ], "format": "int32", "description": "High risk threshold in basis points.", "minimum": 0 }, "maintenance": { "type": "number", "format": "double", "description": "Maintenance margin risk factor as a percentage (e.g., 50.0 = 50%)." }, "maintenanceBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Maintenance margin risk factor in basis points (e.g., 5000 = 50%).", "minimum": 0 }, "upnl": { "type": "number", "format": "double", "description": "Risk factor for positive unrealized PnL penalty as a percentage." }, "upnlBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Risk factor for positive unrealized PnL penalty in basis points.", "minimum": 0 }, "upnlForWithdrawals": { "type": "number", "format": "double", "description": "Risk factor for positive unrealized PnL penalty during withdrawals as a\npercentage." }, "upnlForWithdrawalsBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Risk factor for positive unrealized PnL penalty during withdrawals in\nbasis points.", "minimum": 0 } } }, "ExchangeSnapshotView": { "type": "object", "required": [ "version", "slot", "slotIndex", "exchange", "markets" ], "properties": { "exchange": { "$ref": "#/components/schemas/ExchangeStateSnapshot" }, "markets": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeMarketSnapshot" } }, "sequenceNumber": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/JsSafeU64" } ] }, "slot": { "type": "integer", "format": "int64", "minimum": 0 }, "slotIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "version": { "type": "integer", "format": "int32", "minimum": 0 } } }, "ExchangeStateSnapshot": { "type": "object", "required": [ "programId", "globalConfig", "currentAuthorities", "canonicalMint", "usdcMint", "globalVault", "perpAssetMap", "globalTraderIndex", "activeTraderBuffer", "withdrawQueue", "exchangeStatusBits", "exchangeStatusFeatures", "active", "gated" ], "properties": { "active": { "type": "boolean" }, "activeTraderBuffer": { "type": "array", "items": { "type": "string" } }, "canonicalMint": { "type": "string" }, "currentAuthorities": { "$ref": "#/components/schemas/AuthoritySetView" }, "exchangeStatusBits": { "type": "integer", "format": "int32", "minimum": 0 }, "exchangeStatusFeatures": { "type": "array", "items": { "type": "string" } }, "gated": { "type": "boolean" }, "globalConfig": { "type": "string" }, "globalTraderIndex": { "type": "array", "items": { "type": "string" } }, "globalVault": { "type": "string" }, "perpAssetMap": { "type": "string" }, "programId": { "type": "string" }, "usdcMint": { "type": "string" }, "withdrawQueue": { "type": "string" }, "withdrawalsAvailable": { "type": "boolean" } } }, "ExchangeStatusView": { "type": "object", "description": "Exchange status view containing the current operational status of the\nexchange.", "required": [ "active", "gated" ], "properties": { "active": { "type": "boolean", "description": "Whether the exchange is active (accepting orders)" }, "gated": { "type": "boolean", "description": "Whether the exchange is in gated mode (restricted access)" }, "withdrawalsAvailable": { "type": "boolean", "description": "Whether withdrawals are currently available." } } }, "ExchangeView": { "type": "object", "description": "Full exchange configuration response containing keys and market configs.\nDoes NOT include live data like mark prices or current open interest.", "required": [ "keys", "markets" ], "properties": { "keys": { "$ref": "#/components/schemas/ExchangeKeysView", "description": "Exchange-level account keys and authorities." }, "markets": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeMarketConfig" }, "description": "Static per-market configuration entries." } } }, "ExchangeWsCommodityMetadata": { "type": "object", "required": [ "isCommodity", "isReopen", "isAfterHours", "status", "afterHoursRadius" ], "properties": { "afterHoursRadius": { "type": "string" }, "executionPriceBand": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExchangeWsMarketPriceBand" } ] }, "isAfterHours": { "type": "boolean" }, "isCommodity": { "type": "boolean" }, "isReopen": { "type": "boolean" }, "lastIndexExpiryTimestamp": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "lastKnownIndexPrice": { "type": [ "string", "null" ] }, "markPriceBand": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ExchangeWsMarketPriceBand" } ] }, "status": { "$ref": "#/components/schemas/CommodityMarketState" } } }, "ExchangeWsFundingConfig": { "type": "object", "required": [ "fundingIntervalSeconds", "fundingPeriodSeconds", "maxFundingRatePerInterval" ], "properties": { "fundingIntervalSeconds": { "type": "integer", "format": "int64", "minimum": 0 }, "fundingPeriodSeconds": { "type": "integer", "format": "int64", "minimum": 0 }, "maxFundingRatePerInterval": { "type": "integer", "format": "int64" } } }, "ExchangeWsLeverageTier": { "type": "object", "required": [ "maxLeverage", "maxSizeBaseLots", "limitOrderRiskFactor" ], "properties": { "limitOrderRiskFactor": { "type": "integer", "format": "int32", "minimum": 0 }, "maxLeverage": { "type": "integer", "format": "int64", "minimum": 0 }, "maxSizeBaseLots": { "$ref": "#/components/schemas/JsSafeU64" } } }, "ExchangeWsMarkPriceParameters": { "type": "object", "required": [ "emaPeriodSlots", "emaDiffRadius", "bookPriceRadius", "commoditiesAfterHoursRadius", "commoditiesAfterHoursRadiusBps", "adjustedExchangeSpotPriceWeight", "bookPriceWeight", "exchangePerpPriceWeight", "spotPriceStaleThreshold", "bookPriceStaleThreshold", "perpPriceStaleThreshold", "riskActionPriceValidityRules", "oracleDivergenceRadius", "minOracleResponses" ], "properties": { "adjustedExchangeSpotPriceWeight": { "$ref": "#/components/schemas/JsSafeU64" }, "bookHardStaleMultiplier": { "type": "integer", "format": "int32", "minimum": 0 }, "bookPriceRadius": { "$ref": "#/components/schemas/JsSafeU64" }, "bookPriceStaleThreshold": { "$ref": "#/components/schemas/JsSafeU64" }, "bookPriceWeight": { "$ref": "#/components/schemas/JsSafeU64" }, "commoditiesAfterHoursRadius": { "$ref": "#/components/schemas/JsSafeU64" }, "commoditiesAfterHoursRadiusBps": { "$ref": "#/components/schemas/JsSafeU64" }, "emaDiffRadius": { "$ref": "#/components/schemas/JsSafeU64" }, "emaPeriodSlots": { "$ref": "#/components/schemas/JsSafeU64" }, "exchangePerpPriceWeight": { "$ref": "#/components/schemas/JsSafeU64" }, "minOracleResponses": { "type": "integer", "format": "int32", "minimum": 0 }, "oracleDivergenceRadius": { "type": "integer", "format": "int32", "minimum": 0 }, "oracleHardStaleMultiplier": { "type": "integer", "format": "int32", "minimum": 0 }, "perpPriceStaleThreshold": { "$ref": "#/components/schemas/JsSafeU64" }, "riskActionPriceValidityRules": { "type": "array", "items": { "type": "array", "items": { "type": "array", "items": { "$ref": "#/components/schemas/ExchangeWsValidationRule" } } } }, "spotPriceStaleThreshold": { "$ref": "#/components/schemas/JsSafeU64" } } }, "ExchangeWsMarketPriceBand": { "type": "object", "required": [ "lower", "upper" ], "properties": { "lower": { "type": "string" }, "upper": { "type": "string" } } }, "ExchangeWsRiskFactors": { "type": "object", "required": [ "maintenance", "backstop", "highRisk", "upnl", "upnlForWithdrawals", "cancelOrder" ], "properties": { "backstop": { "type": "number", "format": "double", "description": "Backstop liquidation risk factor as a percentage." }, "backstopBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Backstop liquidation risk factor in basis points.", "minimum": 0 }, "cancelOrder": { "type": "number", "format": "double", "description": "Cancel order risk factor as a percentage." }, "cancelOrderBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Cancel order risk factor in basis points.", "minimum": 0 }, "highRisk": { "type": "number", "format": "double", "description": "High-risk threshold as a percentage." }, "highRiskBps": { "type": [ "integer", "null" ], "format": "int32", "description": "High-risk threshold in basis points.", "minimum": 0 }, "maintenance": { "type": "number", "format": "double", "description": "Maintenance margin risk factor as a percentage (e.g., 50.0 = 50%)." }, "maintenanceBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Maintenance margin risk factor in basis points (e.g., 5000 = 50%).", "minimum": 0 }, "upnl": { "type": "number", "format": "double", "description": "Risk factor for positive unrealized PnL penalty as a percentage." }, "upnlBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Risk factor for positive unrealized PnL penalty in basis points.", "minimum": 0 }, "upnlForWithdrawals": { "type": "number", "format": "double", "description": "Risk factor for positive unrealized PnL penalty during withdrawals in\npercentage terms." }, "upnlForWithdrawalsBps": { "type": [ "integer", "null" ], "format": "int32", "description": "Risk factor for positive unrealized PnL penalty during withdrawals in\nbasis points.", "minimum": 0 } } }, "ExchangeWsValidationRule": { "type": "string", "enum": [ "ignore", "require", "forbid" ] }, "FillRecord": { "type": "object", "description": "Individual fill record returned by the fills channel.", "required": [ "marketSymbol", "baseQty", "quoteQty", "price", "timestamp", "transactionSignature", "instructionType" ], "properties": { "baseQty": { "type": "string", "description": "Human-readable base quantity." }, "instructionType": { "type": "string", "description": "Instruction type that emitted this fill (e.g., PlaceMarketOrder,\nLiquidateViaMarketOrder)." }, "marketSymbol": { "type": "string", "description": "Market symbol associated with the fill (e.g., \"SOL-PERP\")." }, "price": { "type": "string", "description": "Human-readable price derived from the fill quantities." }, "quoteQty": { "type": "string", "description": "Human-readable quote quantity." }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." }, "transactionSignature": { "type": "string", "description": "Transaction signature containing the fill." } } }, "FillsResponse": { "type": "object", "description": "Fills response with pagination metadata.", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "$ref": "#/components/schemas/FillRecord" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "prevCursor": { "type": [ "string", "null" ] } } }, "FundingHourlyEvent": { "type": "object", "description": "Individual hourly funding accrual entry", "required": [ "timestamp", "symbol", "fundingPayment", "fundingRatePercentage", "positionSize", "positionSide" ], "properties": { "fundingPayment": { "type": "string", "description": "Funding payment amount in USDC (negative = paid, positive = received)" }, "fundingRatePercentage": { "type": "string", "description": "Funding rate applied for the hour (percentage of USD notional)" }, "positionSide": { "type": "string", "description": "Position side (\"Long\", \"Short\", or \"Flat\")" }, "positionSize": { "type": "string", "description": "Position size in base units" }, "symbol": { "type": "string", "description": "Market symbol (e.g., \"SOL-PERP\")" }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." } } }, "FundingHourlyHistoryResponse": { "type": "object", "description": "Response containing hourly funding accruals", "required": [ "events", "hasMore" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/FundingHourlyEvent" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching older items (for pagination)" }, "prevCursor": { "type": [ "string", "null" ], "description": "Cursor for fetching newer items (for polling)" } } }, "FundingOverviewPoint": { "type": "object", "description": "Individual funding overview data point for a market", "required": [ "timestamp", "fundingAmountPerUnit", "markPrice", "fundingRate" ], "properties": { "fundingAmountPerUnit": { "type": "string", "description": "Funding amount per base unit in quote units." }, "fundingRate": { "type": "string", "description": "Funding rate for the interval as a decimal." }, "markPrice": { "type": "string", "description": "Mark price in quote units per base unit." }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." } } }, "FundingOverviewResponse": { "type": "object", "description": "Response containing funding overview series for multiple markets", "required": [ "series" ], "properties": { "series": { "type": "array", "items": { "$ref": "#/components/schemas/FundingOverviewSeries" } } } }, "FundingOverviewSeries": { "type": "object", "description": "Funding overview series for a single market", "required": [ "marketId", "symbol", "points" ], "properties": { "marketId": { "type": "integer", "format": "int64" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/FundingOverviewPoint" } }, "symbol": { "type": "string" } } }, "FundingRateHistoryResponse": { "type": "object", "description": "Response containing historical funding rates", "required": [ "marketId", "symbol", "rates" ], "properties": { "marketId": { "type": "integer", "format": "int64" }, "rates": { "type": "array", "items": { "$ref": "#/components/schemas/FundingRatePoint" } }, "symbol": { "type": "string" } } }, "FundingRatePoint": { "type": "object", "description": "Individual funding rate data point", "required": [ "timestamp", "fundingRatePercentage" ], "properties": { "fundingRatePercentage": { "type": "string", "description": "Funding rate applied for the interval (percentage, USD notional terms)" }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." } } }, "GetNotificationsResponse": { "type": "object", "required": [ "items" ], "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/NotificationItem" } }, "nextCursor": { "type": [ "string", "null" ] } } }, "HashMap": { "type": "object", "additionalProperties": { "type": "object", "description": "Position data for a single market stored in snapshots", "required": [ "baseLots", "quoteLots", "positionValue", "initialMargin" ], "properties": { "baseLots": { "type": "string", "description": "Base lots as a formatted string" }, "initialMargin": { "type": "string", "description": "Initial margin as a formatted string" }, "positionValue": { "type": "string", "description": "Position value as a formatted string" }, "quoteLots": { "type": "string", "description": "Virtual quote lots as a formatted string" } } }, "propertyNames": { "type": "string" } }, "IntendedOrder": { "type": "object", "description": "Intended order details from order_packets", "required": [ "orderKind", "side", "hasPriceLimit", "baseLots", "baseQty", "orderFlags", "isReduceOnly", "isStopLoss", "isPostOnly", "isTakeOnly", "cancelExisting" ], "properties": { "baseLots": { "type": "integer", "format": "int64" }, "baseQty": { "type": "string" }, "cancelExisting": { "type": "boolean" }, "clientOrderId": { "type": [ "string", "null" ] }, "hasPriceLimit": { "type": "boolean" }, "isConditionalOrder": { "type": "boolean" }, "isPostOnly": { "type": "boolean" }, "isReduceOnly": { "type": "boolean" }, "isStopLoss": { "type": "boolean" }, "isStopLossDirection": { "type": "boolean" }, "isTakeOnly": { "type": "boolean" }, "lastValidSlot": { "type": [ "integer", "null" ], "format": "int64" }, "matchLimit": { "type": [ "integer", "null" ], "format": "int64" }, "orderFlags": { "type": "integer", "format": "int32" }, "orderKind": { "type": "string" }, "priceInTicks": { "type": [ "integer", "null" ], "format": "int64" }, "priceUsd": { "type": [ "string", "null" ] }, "quoteLotBudget": { "type": [ "integer", "null" ], "format": "int64" }, "side": { "type": "string" } } }, "JsSafeI64": { "type": "integer", "format": "int64", "description": "Wrapper for signed 64-bit values that need to survive JSON transport without\ntripping JavaScript's safe-integer limits. When `serde` is enabled, this can\ndeserialize from a string or number to accommodate clients that stringify\nlarge values." }, "JsSafeU64": { "type": "integer", "format": "int64", "description": "Wrapper for unsigned 64-bit values that must be JSON-safe for consumers\nwritten in JavaScript/TypeScript. Mirrors [`JsSafeI64`] but for unsigned\nPhoenix quantities such as base lots, quote lots, and slots.", "minimum": 0 }, "JwksResponse": { "type": "object", "required": [ "keys" ], "properties": { "keys": { "type": "array", "items": {} } } }, "LimitOrder": { "type": "object", "description": "A trader's limit order.", "required": [ "price", "side", "orderSequenceNumber", "initialTradeSize", "tradeSizeRemaining", "marginRequirement", "marginFactor", "isReduceOnly" ], "properties": { "initialTradeSize": { "type": "string" }, "isConditionalOrder": { "type": "boolean" }, "isReduceOnly": { "type": "boolean" }, "isStopLoss": { "type": "boolean" }, "isStopLossDirection": { "type": "boolean" }, "marginFactor": { "type": "string", "description": "The margin factor applied to limit orders (0.75 = 75% margin required)." }, "marginRequirement": { "type": "string", "description": "The margin requirement for this specific limit order." }, "orderSequenceNumber": { "type": "string" }, "price": { "type": "string" }, "side": { "$ref": "#/components/schemas/Side" }, "tradeSizeRemaining": { "type": "string" } } }, "LiquidityRole": { "type": "string", "description": "Liquidity role for the tracked account's fill.", "enum": [ "maker", "taker" ] }, "MarkPriceResponse": { "type": "object", "required": [ "slot", "slotIndex", "symbol" ], "properties": { "markPrice": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/Price" } ] }, "slot": { "type": "integer", "format": "int64", "minimum": 0 }, "slotIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "symbol": { "type": "string" } } }, "MarketCalendar": { "type": "object", "description": "Public metadata for a market calendar associated with a market.", "required": [ "id", "description", "calendarUri", "contentSha256" ], "properties": { "calendarUri": { "type": "string", "description": "URI where the full market calendar can be fetched." }, "contentSha256": { "type": "string", "description": "SHA-256 hash of the calendar content." }, "description": { "type": "string", "description": "Human-readable calendar description." }, "id": { "type": "string", "description": "Market calendar identifier configured off-chain." }, "nextMarketTransitionUtc": { "type": [ "string", "null" ], "format": "date-time", "description": "Next UTC timestamp at which this calendar changes market state." } } }, "MarketCalendarRecord": { "type": "object", "required": [ "marketCalendarId", "kind", "description", "s3Path", "calendarUri", "contentSha256", "loadedAt", "updatedAt", "rawJson" ], "properties": { "calendar": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommodityMarketCalendarView" } ] }, "calendarUri": { "type": "string" }, "contentSha256": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "loadedAt": { "type": "string", "format": "date-time" }, "marketCalendarId": { "type": "string" }, "rawJson": { "type": "string" }, "s3Path": { "type": "string" }, "updatedAt": { "type": "string", "format": "date-time" } } }, "MarketCalendarResponse": { "type": "object", "required": [ "market", "marketCalendarId", "kind", "description", "calendarUri", "contentSha256", "loadedAt", "rawJson" ], "properties": { "calendar": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommodityMarketCalendarView" } ] }, "calendarUri": { "type": "string" }, "contentSha256": { "type": "string" }, "description": { "type": "string" }, "kind": { "type": "string" }, "loadedAt": { "type": "string", "format": "date-time" }, "market": { "type": "string" }, "marketCalendarId": { "type": "string" }, "rawJson": { "type": "string" } } }, "MarketCalendarStateView": { "type": "string", "enum": [ "open", "afterHours" ] }, "MarketPriceBand": { "type": "object", "description": "Inclusive lower/upper price bounds for market-specific execution rules.", "required": [ "min", "max" ], "properties": { "max": { "type": "string" }, "min": { "type": "string" } } }, "MarketPublicMetadata": { "type": "object", "description": "Public off-chain metadata for a market.", "properties": { "calendar": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketCalendar", "description": "Market calendar metadata derived from the configured calendar id." } ] }, "coinGeckoId": { "type": [ "string", "null" ], "description": "CoinGecko asset identifier." }, "coinMarketCapId": { "type": [ "integer", "null" ], "format": "int64", "description": "CoinMarketCap numeric asset identifier." }, "description": { "type": [ "string", "null" ], "description": "Human-readable market description." }, "displayColor": { "type": [ "string", "null" ], "description": "Preferred display color for this market." }, "logoUri": { "type": [ "string", "null" ], "description": "Logo URI for this market." }, "name": { "type": [ "string", "null" ], "description": "Human-readable market name." }, "tokensXyzAssetId": { "type": [ "string", "null" ], "description": "tokens.xyz asset identifier." } } }, "MarketStatsHistoryResponse": { "type": "object", "description": "Response for market stats history endpoint", "required": [ "market_id", "symbol", "stats" ], "properties": { "market_id": { "type": "integer", "format": "int64" }, "stats": { "type": "array", "items": { "$ref": "#/components/schemas/MarketStatsPoint" } }, "symbol": { "type": "string" }, "timeframe": { "type": [ "string", "null" ] } } }, "MarketStatsPoint": { "type": "object", "description": "Individual market stats data point", "required": [ "open_interest", "mark_price", "spot_price", "timestamp", "slot" ], "properties": { "mark_price": { "type": "number", "format": "double" }, "open_interest": { "type": "number", "format": "double" }, "slot": { "type": "integer", "format": "int64" }, "spot_price": { "type": "number", "format": "double" }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." }, "total_maker_fees": { "type": [ "number", "null" ], "format": "double" }, "total_taker_fees": { "type": [ "number", "null" ], "format": "double" } } }, "MarketStatsSnapshot": { "type": "object", "description": "Live market stats captured alongside an exchange market config response.", "required": [ "slot", "slotIndex", "openInterestBaseLots", "fundingStartIntervalTimestamp", "cumulativeFundingRate" ], "properties": { "cumulativeFundingRate": { "$ref": "#/components/schemas/JsSafeI64", "description": "Current cumulative funding rate." }, "fundingStartIntervalTimestamp": { "$ref": "#/components/schemas/JsSafeU64", "description": "Unix timestamp in seconds for the current funding interval start." }, "openInterestBaseLots": { "$ref": "#/components/schemas/JsSafeU64", "description": "Current open interest in base lots." }, "slot": { "type": "integer", "format": "int64", "description": "Solana slot of the state snapshot used to build these stats.", "minimum": 0 }, "slotIndex": { "type": "integer", "format": "int32", "description": "Intra-slot sequence index of the state snapshot used to build these\nstats.", "minimum": 0 } } }, "MarketStatus": { "type": "string", "enum": [ "uninitialized", "active", "postOnly", "paused", "closed", "tombstoned" ] }, "NextCommodityMarketTransition": { "type": "object", "required": [ "market", "loadedAt", "currentState" ], "properties": { "currentState": { "$ref": "#/components/schemas/CommodityMarketStateView" }, "loadedAt": { "type": "string", "format": "date-time" }, "market": { "type": "string" }, "nextMarketState": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CommodityMarketStateView" } ] }, "utcNextTransition": { "type": [ "string", "null" ], "format": "date-time" } } }, "NextMarketCalendarTransition": { "type": "object", "required": [ "market", "marketCalendarId", "calendarUri", "loadedAt", "currentState" ], "properties": { "calendarUri": { "type": "string" }, "currentState": { "$ref": "#/components/schemas/MarketCalendarStateView" }, "loadedAt": { "type": "string", "format": "date-time" }, "market": { "type": "string" }, "marketCalendarId": { "type": "string" }, "nextMarketState": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/MarketCalendarStateView" } ] }, "utcNextTransition": { "type": [ "string", "null" ], "format": "date-time" } } }, "NotificationFromEventDetails": { "oneOf": [ { "type": "object", "required": [ "symbol", "side", "base_lots_filled", "price", "type" ], "properties": { "base_lots_filled": { "type": "integer", "format": "int64" }, "price": { "type": "number", "format": "double" }, "side": { "type": "string" }, "symbol": { "type": "string" }, "type": { "type": "string", "enum": [ "orderFilled" ] } } }, { "type": "object", "required": [ "symbol", "side", "base_lots_released", "type" ], "properties": { "base_lots_released": { "type": "integer", "format": "int64" }, "side": { "type": "string" }, "symbol": { "type": "string" }, "type": { "type": "string", "enum": [ "riskEngineCancelOrder" ] } } }, { "type": "object", "required": [ "symbol", "side", "base_amount", "quote_amount", "type" ], "properties": { "base_amount": { "type": "number", "format": "double" }, "quote_amount": { "type": "number", "format": "double" }, "side": { "type": "string" }, "symbol": { "type": "string" }, "trigger_type": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "stopLossExecuted" ] } } }, { "type": "object", "required": [ "symbol", "side", "base_amount", "quote_amount", "type" ], "properties": { "base_amount": { "type": "number", "format": "double" }, "quote_amount": { "type": "number", "format": "double" }, "side": { "type": "string" }, "symbol": { "type": "string" }, "trigger_type": { "type": [ "string", "null" ] }, "type": { "type": "string", "enum": [ "conditionalOrderExecuted" ] } } }, { "type": "object", "required": [ "symbol", "side", "base_amount", "quote_amount", "type" ], "properties": { "base_amount": { "type": "number", "format": "double" }, "quote_amount": { "type": "number", "format": "double" }, "side": { "type": "string" }, "symbol": { "type": "string" }, "type": { "type": "string", "enum": [ "liquidation" ] } } }, { "type": "object", "required": [ "asset_id", "base_lots_closed", "type" ], "properties": { "asset_id": { "type": "integer", "format": "int64", "minimum": 0 }, "base_lots_closed": { "type": "integer", "format": "int64" }, "type": { "type": "string", "enum": [ "adl" ] } } }, { "type": "object", "required": [ "asset_id", "base_lots_transferred", "virtual_quote_lots_transferred", "haircut_rate", "type" ], "properties": { "asset_id": { "type": "integer", "format": "int64", "minimum": 0 }, "base_lots_transferred": { "type": "integer", "format": "int64" }, "haircut_rate": { "type": "integer", "format": "int32", "minimum": 0 }, "type": { "type": "string", "enum": [ "backstopLiquidation" ] }, "virtual_quote_lots_transferred": { "type": "integer", "format": "int64" } } }, { "type": "object", "description": "DB fallback for old rows. Never serialized to the API response.", "required": [ "type" ], "properties": { "type": { "type": "string", "enum": [ "unknown" ] } } } ], "description": "Structured details for each notification type. Serialized to JSON for the\n`details` DB column and API response field." }, "NotificationItem": { "oneOf": [ { "type": "object", "required": [ "id", "slot", "slotIndex", "instructionIndex", "eventIndex", "recipientIndex", "notificationType", "data", "createdAt", "acked", "source" ], "properties": { "acked": { "type": "boolean" }, "createdAt": { "type": "string", "format": "date-time" }, "data": {}, "details": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/NotificationFromEventDetails", "description": "Structured details per notification type. None for legacy rows." } ] }, "eventIndex": { "type": "integer", "format": "int32" }, "id": { "type": "integer", "format": "int64" }, "instructionIndex": { "type": "integer", "format": "int32" }, "notificationType": { "type": "string" }, "recipientIndex": { "type": "integer", "format": "int32" }, "slot": { "type": "integer", "format": "int64", "description": "Composite index for dedupe/ack; matches DB unique key and WS\ntemporary id." }, "slotIndex": { "type": "integer", "format": "int32" }, "source": { "type": "string", "enum": [ "event" ] } } }, { "type": "object", "required": [ "id", "notificationType", "data", "createdAt", "acked", "source" ], "properties": { "acked": { "type": "boolean" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": {}, "id": { "type": "integer", "format": "int64" }, "notificationType": { "type": "string" }, "source": { "type": "string", "enum": [ "admin" ] }, "title": { "type": [ "string", "null" ] } } }, { "type": "object", "description": "General notification: user-specific, real-time (e.g. from Redis), not\nfrom on-chain events nor global admin announcements.", "required": [ "id", "notificationType", "data", "createdAt", "acked", "source" ], "properties": { "acked": { "type": "boolean" }, "body": { "type": [ "string", "null" ] }, "createdAt": { "type": "string", "format": "date-time" }, "data": {}, "id": { "type": "integer", "format": "int64" }, "notificationType": { "type": "string" }, "source": { "type": "string", "enum": [ "general" ] }, "title": { "type": [ "string", "null" ] } } } ], "description": "Notification item: discriminated union by source (event vs admin vs\ngeneral)." }, "OrderStatus": { "type": "string", "enum": [ "active", "cancelled", "filled" ] }, "OrderbookView": { "type": "object", "description": "View orderbook", "required": [ "slot", "symbol", "bids", "asks" ], "properties": { "asks": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "number", "format": "double" }, { "type": "number", "format": "double" } ] }, "description": "Ask levels as `(price, size)`." }, "bids": { "type": "array", "items": { "type": "array", "items": false, "prefixItems": [ { "type": "number", "format": "double" }, { "type": "number", "format": "double" } ] }, "description": "Bid levels as `(price, size)`." }, "mid": { "type": [ "number", "null" ], "format": "double", "description": "Mid price, if both sides exist." }, "slot": { "type": "integer", "format": "int64", "description": "Solana slot of this orderbook snapshot.", "minimum": 0 }, "splines": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/Spline" }, "description": "Optional spline levels." }, "symbol": { "type": "string", "description": "Market symbol." } } }, "PaginatedResponse_Vec_OrderHistoryItem": { "type": "object", "description": "Generic paginated response wrapper with bidirectional cursor support.\n\nThe cursor system supports both forward (newer) and backward (older)\npagination:\n- `prev_cursor`: Use this cursor to poll for new items (items newer than the\n current result set)\n- `next_cursor`: Use this cursor to load more items (items older than the\n current result set)\n\nThe direction is embedded in the cursor itself, so clients just need to pass\nthe appropriate cursor to the `cursor` parameter.", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Individual order in order history", "required": [ "orderSequenceNumber", "marketSymbol", "status", "side", "isReduceOnly", "price", "baseQty", "remainingBaseQty", "filledBaseQty" ], "properties": { "baseQty": { "type": "string", "description": "Base quantity (human-readable, decimal format)" }, "completedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the order was completed (ISO 8601)" }, "filledBaseQty": { "type": "string", "description": "Total filled base quantity (human-readable, decimal format)" }, "isConditionalOrder": { "type": "boolean", "description": "Indicates whether the order originated from a conditional trigger" }, "isReduceOnly": { "type": "boolean", "description": "Indicates whether the order was marked reduce-only at placement time" }, "isStopLoss": { "type": "boolean", "description": "Indicates whether the order originated from a stop loss trigger" }, "isStopLossDirection": { "type": "boolean", "description": "Indicates whether the TP/SL trigger used stop-loss direction" }, "marketSymbol": { "type": "string", "description": "Market symbol (e.g., \"SOL-PERP\")" }, "orderSequenceNumber": { "type": "string", "description": "Order sequence number" }, "placedAt": { "type": [ "string", "null" ], "format": "date-time", "description": "Timestamp when the order was placed (ISO 8601)" }, "price": { "type": "string", "description": "Order price (human-readable, decimal format)" }, "remainingBaseQty": { "type": "string", "description": "Remaining base quantity (human-readable, decimal format)" }, "side": { "$ref": "#/components/schemas/Side", "description": "Order side (\"buy\" or \"sell\")" }, "status": { "$ref": "#/components/schemas/OrderStatus", "description": "Order status" } } } }, "hasMore": { "type": "boolean", "description": "Whether there are more results available after this page" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page of older results.\nPass this value as the `cursor` parameter in the next request to load\nmore." }, "prevCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching newer items (for polling).\nPass this value as the `cursor` parameter to get items newer than the\nfirst item in data." } } }, "PaginatedResponse_Vec_OrderHistoryV2Item": { "type": "object", "description": "Generic paginated response wrapper with bidirectional cursor support.\n\nThe cursor system supports both forward (newer) and backward (older)\npagination:\n- `prev_cursor`: Use this cursor to poll for new items (items newer than the\n current result set)\n- `next_cursor`: Use this cursor to load more items (items older than the\n current result set)\n\nThe direction is embedded in the cursor itself, so clients just need to pass\nthe appropriate cursor to the `cursor` parameter.", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "Order history V2 item showing intended order (from packet), actual placed\norder (from event), and current state (from orders table)", "required": [ "userId", "traderId", "traderPdaIndex", "traderSubaccountIndex", "slot", "slotIndex", "instructionIndex", "eventIndex", "marketSymbol", "instructionType", "orderType", "createdAt", "price", "intended", "isReduceOnly", "isStopLoss", "isStopLossDirection", "isConditionalOrder", "status" ], "properties": { "createdAt": { "type": "string", "format": "date-time" }, "currentOrderState": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CurrentOrderState" } ] }, "eventIndex": { "type": "integer", "format": "int32" }, "fillBeforePlacement": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/AggregatedTrades" } ] }, "instructionIndex": { "type": "integer", "format": "int32" }, "instructionType": { "type": "string" }, "intended": { "$ref": "#/components/schemas/IntendedOrder" }, "isConditionalOrder": { "type": "boolean" }, "isReduceOnly": { "type": "boolean" }, "isStopLoss": { "type": "boolean" }, "isStopLossDirection": { "type": "boolean" }, "marketSymbol": { "type": "string" }, "orderType": { "type": "string" }, "placedOrder": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PlacedOrder" } ] }, "price": { "type": "string" }, "slot": { "type": "integer", "format": "int64" }, "slotIndex": { "type": "integer", "format": "int32" }, "status": { "type": "string" }, "traderId": { "type": "integer", "format": "int64" }, "traderPdaIndex": { "type": "integer", "format": "int32" }, "traderSubaccountIndex": { "type": "integer", "format": "int32" }, "userId": { "type": "integer", "format": "int64" } } } }, "hasMore": { "type": "boolean", "description": "Whether there are more results available after this page" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page of older results.\nPass this value as the `cursor` parameter in the next request to load\nmore." }, "prevCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching newer items (for polling).\nPass this value as the `cursor` parameter to get items newer than the\nfirst item in data." } } }, "PaginatedResponse_Vec_TradeHistoryV2Item": { "type": "object", "description": "Generic paginated response wrapper with bidirectional cursor support.\n\nThe cursor system supports both forward (newer) and backward (older)\npagination:\n- `prev_cursor`: Use this cursor to poll for new items (items newer than the\n current result set)\n- `next_cursor`: Use this cursor to load more items (items older than the\n current result set)\n\nThe direction is embedded in the cursor itself, so clients just need to pass\nthe appropriate cursor to the `cursor` parameter.", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A single flattened trade history item with PnL and position data", "required": [ "userId", "traderId", "traderPdaIndex", "subaccountIndex", "marketSymbol", "timestamp", "slot", "slotIndex", "eventIndex", "instructionIndex", "instructionType", "baseLotsBefore", "baseLotsAfter", "baseLotsDelta", "virtualQuoteLotsBefore", "virtualQuoteLotsAfter", "virtualQuoteLotsDelta", "price", "realizedPnl", "fees", "liquidity", "tradeType" ], "properties": { "baseLotsAfter": { "type": "string", "description": "Base lots after the trade (human readable)" }, "baseLotsBefore": { "type": "string", "description": "Base lots before the trade (human readable)" }, "baseLotsDelta": { "type": "string", "description": "Base lots delta (human readable, signed)" }, "eventIndex": { "type": "integer", "format": "int32" }, "fees": { "type": "string" }, "fillId": { "type": [ "string", "null" ], "description": "Deterministic UUID v3 derived from the raw fill coordinates." }, "instructionIndex": { "type": "integer", "format": "int32" }, "instructionType": { "type": "string", "description": "Instruction type (e.g., \"PlaceLimitOrder\", \"PlaceMarketOrder\")" }, "liquidity": { "$ref": "#/components/schemas/LiquidityRole" }, "marketSymbol": { "type": "string", "description": "Market symbol" }, "orderSequenceNumber": { "type": [ "integer", "null" ], "format": "int64" }, "price": { "type": "string" }, "realizedPnl": { "type": "string", "description": "Realized PnL from this trade (human readable USD)" }, "signature": { "type": [ "string", "null" ], "description": "Transaction signature" }, "slot": { "type": "integer", "format": "int64", "description": "Slot coordinates for cursor" }, "slotIndex": { "type": "integer", "format": "int32" }, "splineSequenceNumber": { "type": [ "integer", "null" ], "format": "int64" }, "subaccountIndex": { "type": "integer", "format": "int32", "description": "Subaccount index" }, "timestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." }, "tradeType": { "$ref": "#/components/schemas/TradeType" }, "traderId": { "type": "integer", "format": "int64", "description": "Trader ID" }, "traderPdaIndex": { "type": "integer", "format": "int32", "description": "Trader PDA index" }, "userId": { "type": "integer", "format": "int64", "description": "User ID" }, "virtualQuoteLotsAfter": { "type": "string", "description": "Virtual quote lots after (human readable)" }, "virtualQuoteLotsBefore": { "type": "string", "description": "Virtual quote lots before (human readable)" }, "virtualQuoteLotsDelta": { "type": "string", "description": "Virtual quote lots delta (human readable, signed)" } } } }, "hasMore": { "type": "boolean", "description": "Whether there are more results available after this page" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page of older results.\nPass this value as the `cursor` parameter in the next request to load\nmore." }, "prevCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching newer items (for polling).\nPass this value as the `cursor` parameter to get items newer than the\nfirst item in data." } } }, "PaginatedResponse_Vec_UserLiquidationHistoryPoint": { "type": "object", "description": "Generic paginated response wrapper with bidirectional cursor support.\n\nThe cursor system supports both forward (newer) and backward (older)\npagination:\n- `prev_cursor`: Use this cursor to poll for new items (items newer than the\n current result set)\n- `next_cursor`: Use this cursor to load more items (items older than the\n current result set)\n\nThe direction is embedded in the cursor itself, so clients just need to pass\nthe appropriate cursor to the `cursor` parameter.", "required": [ "data", "hasMore" ], "properties": { "data": { "type": "array", "items": { "type": "object", "description": "A normalized liquidation, backstop, or ADL event for one user authority.", "required": [ "kind", "type", "ixName", "role", "slot", "slotIndex", "eventIndex", "timestamp", "symbol", "market" ], "properties": { "atLossCloseValue": { "type": [ "string", "null" ] }, "atLossCollateralChange": { "type": [ "string", "null" ] }, "baseLotsFilled": { "type": [ "string", "null" ] }, "caller": { "type": [ "string", "null" ] }, "closedLong": { "type": [ "string", "null" ] }, "closedShort": { "type": [ "string", "null" ] }, "eventIndex": { "type": "integer", "format": "int32" }, "haircutRateBps": { "type": [ "integer", "null" ], "format": "int32" }, "inProfitAccount": { "type": [ "string", "null" ] }, "inProfitCloseValue": { "type": [ "string", "null" ] }, "inProfitCollateralChange": { "type": [ "string", "null" ] }, "ixName": { "type": "string", "description": "Indexed instruction name that emitted this event." }, "kind": { "$ref": "#/components/schemas/UserLiquidationHistoryKind" }, "liquidatee": { "type": [ "string", "null" ] }, "liquidateeCollateralChange": { "type": [ "string", "null" ] }, "liquidator": { "type": [ "string", "null" ] }, "liquidatorCollateralChange": { "type": [ "string", "null" ] }, "market": { "type": "string", "description": "Alias for `symbol`, included for clients that present this field as the\nmarket." }, "positionClosed": { "type": [ "boolean", "null" ] }, "price": { "type": [ "string", "null" ] }, "quoteLotsFilled": { "type": [ "string", "null" ] }, "quoteSize": { "type": [ "string", "null" ] }, "role": { "$ref": "#/components/schemas/UserLiquidationHistoryRole" }, "side": { "type": [ "string", "null" ] }, "signature": { "type": [ "string", "null" ] }, "size": { "type": [ "string", "null" ] }, "slot": { "type": "integer", "format": "int64" }, "slotIndex": { "type": "integer", "format": "int32" }, "subaccountIndex": { "type": [ "integer", "null" ], "format": "int32" }, "symbol": { "type": "string", "description": "Market symbol, for example `SOL-PERP`." }, "timestamp": { "type": "integer", "format": "int64" }, "type": { "$ref": "#/components/schemas/UserLiquidationHistoryType", "description": "High-level event type: `market`, `adl`, or `backstop`." } } } }, "hasMore": { "type": "boolean", "description": "Whether there are more results available after this page" }, "nextCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching the next page of older results.\nPass this value as the `cursor` parameter in the next request to load\nmore." }, "prevCursor": { "type": [ "string", "null" ], "description": "Opaque cursor for fetching newer items (for polling).\nPass this value as the `cursor` parameter to get items newer than the\nfirst item in data." } } }, "PlaceAttachedConditionalOrderRequest": { "type": "object", "description": "Request payload for /v1/ix/place-attached-conditional-order.", "required": [ "authority", "traderPdaIndex", "symbol", "orderSequenceNumber", "orderPriceInTicks" ], "properties": { "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "greaterTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "isIsolated": { "type": "boolean" }, "lessTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "orderPriceInTicks": { "type": "integer", "format": "int64", "minimum": 0 }, "orderSequenceNumber": { "type": "string" }, "positionAuthority": { "type": [ "string", "null" ] }, "symbol": { "type": "string" }, "traderPdaIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "PlaceIsolatedLimitOrderEnhancedResponse": { "type": "object", "required": [ "instructions" ], "properties": { "estimatedLiquidationPriceUsd": { "type": [ "number", "null" ], "format": "double" }, "instructions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } }, "PlaceIsolatedLimitOrderRequest": { "type": "object", "description": "Request payload for /ix/place-isolated-limit-order.", "required": [ "authority", "symbol", "side" ], "properties": { "allowCrossAndIsolatedForAsset": { "type": [ "boolean", "null" ] }, "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "isPostOnly": { "type": [ "boolean", "null" ], "description": "If true, the order will be post-only (maker only, will not match against\nexisting orders)." }, "isReduceOnly": { "type": [ "boolean", "null" ] }, "numBaseLots": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "pdaIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "positionAuthority": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ], "format": "double" }, "priceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "quantity": { "type": [ "number", "null" ], "format": "double" }, "side": { "type": "string" }, "skipTransferToParent": { "type": [ "boolean", "null" ] }, "slide": { "type": [ "boolean", "null" ], "description": "For post-only orders: if true, slide to best price when order would\ncross. Defaults to true." }, "symbol": { "type": "string" }, "tpSl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSlOrderConfig" } ] }, "transferAmount": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PlaceIsolatedLimitOrderWithConditionalsRequest": { "type": "object", "description": "Request payload for /v1/ix/place-isolated-limit-order-with-conditionals.", "required": [ "authority", "symbol", "side" ], "properties": { "allowCrossAndIsolatedForAsset": { "type": [ "boolean", "null" ] }, "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "greaterTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "isPostOnly": { "type": [ "boolean", "null" ], "description": "If true, the order will be post-only (maker only, will not match against\nexisting orders)." }, "lessTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "numBaseLots": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "pdaIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "positionAuthority": { "type": [ "string", "null" ] }, "price": { "type": [ "number", "null" ], "format": "double" }, "priceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "quantity": { "type": [ "number", "null" ], "format": "double" }, "side": { "type": "string" }, "skipTransferToParent": { "type": [ "boolean", "null" ] }, "slide": { "type": [ "boolean", "null" ], "description": "For post-only orders: if true, slide to best price when order would\ncross. Defaults to true." }, "symbol": { "type": "string" }, "transferAmount": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PlaceIsolatedMarketOrderEnhancedResponse": { "type": "object", "required": [ "instructions" ], "properties": { "estimatedLiquidationPriceUsd": { "type": [ "number", "null" ], "format": "double" }, "instructions": { "type": "array", "items": { "$ref": "#/components/schemas/ApiInstructionResponse" } } } }, "PlaceIsolatedMarketOrderRequest": { "type": "object", "description": "Request payload for /ix/place-isolated-market-order.", "required": [ "authority", "symbol", "side" ], "properties": { "allowCrossAndIsolatedForAsset": { "type": [ "boolean", "null" ] }, "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "isReduceOnly": { "type": [ "boolean", "null" ] }, "maxPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "numBaseLots": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "pdaIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "positionAuthority": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ], "format": "double" }, "side": { "type": "string" }, "skipTransferToParent": { "type": [ "boolean", "null" ] }, "symbol": { "type": "string" }, "tpSl": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TpSlOrderConfig" } ] }, "transferAmount": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PlacePositionConditionalOrderRequest": { "type": "object", "description": "Request payload for /v1/ix/place-position-conditional-order.", "required": [ "authority", "traderPdaIndex", "symbol" ], "properties": { "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "greaterTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "isIsolated": { "type": "boolean" }, "lessTrigger": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/ConditionalTriggerRequest" } ] }, "numBaseLots": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "positionAuthority": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ], "format": "double" }, "sizePercent": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "symbol": { "type": "string" }, "traderPdaIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } }, "PlaceStopLossOrderRequest": { "allOf": [ { "$ref": "#/components/schemas/TpSlOrderConfig" }, { "type": "object", "required": [ "authority", "traderPdaIndex", "symbol", "side" ], "properties": { "authority": { "type": "string" }, "feePayer": { "type": [ "string", "null" ] }, "flightBuilderAuthority": { "type": [ "string", "null" ] }, "flightFeeCollectorTrader": { "type": [ "string", "null" ] }, "isIsolated": { "type": "boolean" }, "positionAuthority": { "type": [ "string", "null" ] }, "side": { "type": "string" }, "symbol": { "type": "string" }, "traderPdaIndex": { "type": "integer", "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 } } } ], "description": "Request payload for /ix/place-stop-loss-order." }, "PlacedOrder": { "type": "object", "description": "Actual placed order details from order_events", "required": [ "orderSequenceNumber", "eventIndex", "side", "price", "baseQty", "transactionTimestamp" ], "properties": { "baseQty": { "type": "string" }, "eventIndex": { "type": "integer", "format": "int32" }, "initialSlot": { "type": [ "integer", "null" ], "format": "int64" }, "lastValidSlot": { "type": [ "integer", "null" ], "format": "int64" }, "orderFlags": { "type": [ "integer", "null" ], "format": "int32" }, "orderSequenceNumber": { "type": "integer", "format": "int64" }, "price": { "type": "string" }, "side": { "type": "string" }, "transactionTimestamp": { "type": "string", "format": "date-time", "description": "Formatted datetime string (ISO 8601)." } } }, "PnLPoint": { "type": "object", "description": "PnL data point", "required": [ "timestamp", "startTime", "endTime", "cumulativePnl", "unrealizedPnl", "cumulativeFundingPayment", "cumulativeTakerFee" ], "properties": { "cumulativeFundingPayment": { "type": "number", "format": "double", "description": "Cumulative funding payment up to this point" }, "cumulativePnl": { "type": "number", "format": "double", "description": "Cumulative realized PnL up to this point" }, "cumulativeTakerFee": { "type": "number", "format": "double", "description": "Cumulative taker fees paid up to this point" }, "endTime": { "type": "integer", "format": "int64", "description": "End time in seconds since Unix epoch" }, "startTime": { "type": "integer", "format": "int64", "description": "Start time in seconds since Unix epoch" }, "timestamp": { "type": "integer", "format": "int64", "description": "Deprecated: Unix timestamp in seconds." }, "unrealizedPnl": { "type": "number", "format": "double", "description": "unrealized PnL up to this point" } } }, "PortfolioValuePoint": { "type": "object", "description": "Portfolio value data point", "required": [ "timestamp", "startTime", "endTime", "value" ], "properties": { "endTime": { "type": "integer", "format": "int64", "description": "End time in seconds since Unix epoch" }, "positions": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/HashMap", "description": "Positions snapshot for this point in time" } ] }, "startTime": { "type": "integer", "format": "int64", "description": "Start time in seconds since Unix epoch" }, "timestamp": { "type": "integer", "format": "int64", "description": "Deprecated: Unix timestamp in seconds." }, "value": { "type": "number", "format": "double", "description": "Portfolio value as a floating-point number" } } }, "Price": { "type": "object", "description": "A price for an asset.", "required": [ "price", "slot" ], "properties": { "price": { "type": "number", "format": "double" }, "slot": { "type": "integer", "format": "int64", "minimum": 0 } } }, "PrivyLoginRequest": { "type": "object", "required": [ "privy_token" ], "properties": { "privy_token": { "type": "string" }, "wallet_proof": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/PrivyWalletProof", "description": "Proof of ownership of `wallet_pubkey`, obtained by signing the\ntransaction returned from `POST /v1/auth/privy/wallet-challenge`. When\nsupplied this satisfies the first-time binding ownership check\nwithout needing the Privy linked-accounts lookup." } ] }, "wallet_pubkey": { "type": [ "string", "null" ], "description": "Optional Solana wallet pubkey the caller is asserting ownership of.\nFor first-time bindings ownership must be proved either by including\n`wallet_proof` (a Solana memo transaction signed by the wallet \u2014 works\nfor Ledger which cannot sign off-chain messages) or, absent a proof,\nby Privy's `linked_accounts` API confirming the wallet is linked to\nthe authenticated user. An unverified pubkey is rejected with\n`wallet_not_linked`. For returning users, if supplied, it must match\nthe bound pubkey. If omitted when no mapping exists, login still\nsucceeds but the issued token will not carry a `wallet` claim and so\ncannot satisfy user-scoped authorization." } } }, "PrivyWalletProof": { "type": "object", "required": [ "nonce_id", "signed_transaction" ], "properties": { "nonce_id": { "type": "string", "description": "The `nonce_id` returned from the wallet-challenge endpoint." }, "signed_transaction": { "type": "string", "description": "The full signed Solana transaction, base64-encoded (legacy bincode\nformat). The transaction must be the same one returned from the\nwallet-challenge endpoint, signed by `wallet_pubkey`." } } }, "ReferralActivationPermissionResponse": { "type": "object", "required": [ "trader_onboarder", "risk_authority", "permission_account" ], "properties": { "permission_account": { "type": "string" }, "risk_authority": { "type": "string" }, "trader_onboarder": { "type": "string" } } }, "RefreshRequest": { "type": "object", "required": [ "refresh_token" ], "properties": { "refresh_token": { "type": "string" } } }, "RiskState": { "type": "string", "enum": [ "healthy", "unhealthy", "underwater", "zeroCollateralNoPositions" ] }, "RiskTier": { "type": "string", "enum": [ "safe", "atRisk", "cancellable", "liquidatable", "backstopLiquidatable", "highRisk" ] }, "SendRegisterIxsRequest": { "type": "object", "description": "Request payload for /exchange/send-register-ixs.", "required": [ "transaction", "traderAuthority", "txFeePayer" ], "properties": { "maxPositions": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "traderAuthority": { "type": "string" }, "traderPdaIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "traderSubaccountIndex": { "type": [ "integer", "null" ], "format": "int32", "minimum": 0 }, "transaction": { "type": "string", "description": "Base64-encoded Solana transaction wire bytes signed by the user-owned\nrequired signers. The API validates, signs as onboarder, simulates, and\nsubmits it." }, "txFeePayer": { "type": "string" } } }, "SendRegisterIxsResponse": { "type": "object", "description": "Response payload for /exchange/send-register-ixs.", "required": [ "signature", "traderPda", "traderOnboarder", "txFeePayer", "maxPositions", "includeRegisterTrader" ], "properties": { "includeRegisterTrader": { "type": "boolean" }, "maxPositions": { "type": "integer", "format": "int32", "minimum": 0 }, "signature": { "type": "string" }, "traderOnboarder": { "type": "string" }, "traderPda": { "type": "string" }, "txFeePayer": { "type": "string" } } }, "ServiceChallengeRequest": { "type": "object", "required": [ "client_id" ], "properties": { "client_id": { "type": "string" }, "key_id": { "type": [ "string", "null" ] } } }, "ServiceChallengeResponse": { "type": "object", "required": [ "nonce", "message", "expires_at", "key_id" ], "properties": { "expires_at": { "type": "string" }, "key_id": { "type": "string" }, "message": { "type": "string" }, "nonce": { "type": "string" } } }, "ServiceLoginRequest": { "type": "object", "required": [ "client_id", "nonce", "timestamp", "signature" ], "properties": { "client_id": { "type": "string" }, "key_id": { "type": [ "string", "null" ] }, "nonce": { "type": "string" }, "signature": { "type": "string" }, "timestamp": { "type": "string" } } }, "Side": { "type": "string", "enum": [ "bid", "ask" ] }, "Spline": { "type": "object", "required": [ "traderKey", "midPrice", "bidFilledAmount", "askFilledAmount", "bidRegions", "askRegions" ], "properties": { "askFilledAmount": { "type": "string" }, "askRegions": { "type": "array", "items": { "$ref": "#/components/schemas/TickRegion" } }, "bidFilledAmount": { "type": "string" }, "bidRegions": { "type": "array", "items": { "$ref": "#/components/schemas/TickRegion" } }, "midPrice": { "type": "number", "format": "double" }, "traderKey": { "type": "string" } } }, "StopLossOrderKind": { "type": "string", "enum": [ "ioc", "limit" ] }, "TickRegion": { "type": "object", "required": [ "start", "end", "density", "totalSize", "filledSize" ], "properties": { "density": { "type": "number", "format": "double" }, "end": { "type": "number", "format": "double" }, "filledSize": { "type": "string" }, "start": { "type": "number", "format": "double" }, "totalSize": { "type": "string" } } }, "TpSlOrderConfig": { "type": "object", "description": "TP/SL configuration shared across endpoints.", "properties": { "numBaseLots": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "orderKind": { "type": [ "string", "null" ] }, "quantity": { "type": [ "number", "null" ], "format": "double" }, "stopLossExecutionPrice": { "type": [ "number", "null" ], "format": "double" }, "stopLossExecutionPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "stopLossTriggerPrice": { "type": [ "number", "null" ], "format": "double" }, "stopLossTriggerPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "takeProfitExecutionPrice": { "type": [ "number", "null" ], "format": "double" }, "takeProfitExecutionPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 }, "takeProfitTriggerPrice": { "type": [ "number", "null" ], "format": "double" }, "takeProfitTriggerPriceInTicks": { "type": [ "integer", "null" ], "format": "int64", "minimum": 0 } } }, "TradeType": { "type": "string", "enum": [ "limit", "market", "liquidation", "adl" ] }, "TraderActivityStateView": { "type": "string", "description": "Serializable representation of a trader's high-level activity state.", "enum": [ "uninitialized", "cold", "active", "reduceOnly", "frozen" ] }, "TraderCapabilitiesMetadata": { "type": "object", "description": "Metadata response that enumerates all trader capability descriptors.", "required": [ "capabilities" ], "properties": { "capabilities": { "type": "array", "items": { "$ref": "#/components/schemas/TraderCapabilityDescriptor" }, "description": "Supported capability descriptors." } } }, "TraderCapabilitiesView": { "type": "object", "description": "Capability matrix exposed alongside a trader's status. Each field is a\nnested object that reports whether the action is immediately available\n(`immediate`) and whether it becomes available after activating a cold\ntrader (`viaColdActivation`).", "required": [ "placeLimitOrder", "placeMarketOrder", "riskIncreasingTrade", "riskReducingTrade", "depositCollateral", "withdrawCollateral" ], "properties": { "depositCollateral": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to deposit collateral." }, "placeLimitOrder": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to place limit orders." }, "placeMarketOrder": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to place market orders." }, "riskIncreasingTrade": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to execute risk-increasing trades." }, "riskReducingTrade": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to execute risk-reducing trades." }, "withdrawCollateral": { "$ref": "#/components/schemas/CapabilityAccessView", "description": "Capability to withdraw collateral." } } }, "TraderCapabilityDescriptor": { "type": "object", "description": "Describes a trader capability in a forward-compatible, human readable way.", "required": [ "key", "displayName", "description" ], "properties": { "deprecated": { "type": "boolean", "description": "Whether this capability key is deprecated." }, "description": { "type": "string", "description": "Human-readable capability description." }, "displayName": { "type": "string", "description": "Human-readable display name." }, "key": { "type": "string", "description": "Stable capability key." } } }, "TraderCapabilityFlags": { "type": "integer", "format": "int32", "description": "Canonical capability mask stored in every trader header. The derived preset\nconstructors (`cold`, `hot_active`, `reduce_only`, `frozen`) preserve the\nintended behavioural guarantees: cold traders operate from their local\nbuffer until warmed, active traders have full matching-engine access,\nreduce-only traders may only take risk-reducing actions (but can still move\ncollateral), and frozen traders are fully quarantined with balance transfers\ndisabled.", "minimum": 0 }, "TraderFundingHistoryEvent": { "type": "object", "required": [ "timestamp", "symbol", "fundingPayment", "fundingRatePercentage", "positionSize", "positionSide" ], "properties": { "fundingPayment": { "type": "string" }, "fundingRatePercentage": { "type": "string" }, "positionSide": { "type": "string" }, "positionSize": { "type": "string" }, "symbol": { "type": "string" }, "timestamp": { "type": "string", "format": "date-time" } } }, "TraderFundingHistoryResponse": { "type": "object", "required": [ "events", "hasMore" ], "properties": { "events": { "type": "array", "items": { "$ref": "#/components/schemas/TraderFundingHistoryEvent" } }, "hasMore": { "type": "boolean" }, "nextCursor": { "type": [ "string", "null" ] }, "prevCursor": { "type": [ "string", "null" ] } } }, "TraderMarketPnLPoint": { "type": "object", "description": "Per-market PnL point including position context", "required": [ "timestamp", "startTime", "endTime", "realizedPnl", "cumulativePnl", "cumulativeFundingPayment", "totalTakerFee", "cumulativeTakerFee", "unrealizedPnl", "baseLots", "virtualQuoteLots", "markPrice" ], "properties": { "baseLots": { "type": "integer", "format": "int64", "description": "Base lots position at the end of the bucket" }, "cumulativeFundingPayment": { "type": "number", "format": "double", "description": "Cumulative funding payments up to this point" }, "cumulativePnl": { "type": "number", "format": "double", "description": "Cumulative PnL up to this point" }, "cumulativeTakerFee": { "type": "number", "format": "double", "description": "Cumulative taker fees paid up to this point" }, "endTime": { "type": "integer", "format": "int64", "description": "End time in seconds since Unix epoch" }, "markPrice": { "type": "integer", "format": "int64", "description": "Mark price in ticks at the end of the bucket" }, "realizedPnl": { "type": "number", "format": "double", "description": "Realized PnL accrued inside the bucket" }, "startTime": { "type": "integer", "format": "int64", "description": "Start time in seconds since Unix epoch" }, "timestamp": { "type": "integer", "format": "int64", "description": "Deprecated: Unix timestamp in seconds." }, "totalTakerFee": { "type": "number", "format": "double", "description": "Taker fees paid inside the bucket" }, "unrealizedPnl": { "type": "number", "format": "double", "description": "Unrealized PnL at the end of the bucket" }, "virtualQuoteLots": { "type": "integer", "format": "int64", "description": "Virtual quote lots position at the end of the bucket" } } }, "TraderMarketPnLSeries": { "type": "object", "description": "Per-market PnL time-series for a trader", "required": [ "marketId", "symbol", "tickSize", "baseDecimals", "points" ], "properties": { "baseDecimals": { "type": "integer", "format": "int32", "description": "Base decimals used for this market" }, "marketId": { "type": "integer", "format": "int64", "description": "Market identifier" }, "points": { "type": "array", "items": { "$ref": "#/components/schemas/TraderMarketPnLPoint" }, "description": "Time-series points" }, "symbol": { "type": "string", "description": "Market symbol (e.g. BTC, SOL, ETH)" }, "tickSize": { "type": "integer", "format": "int32", "description": "Tick size in quote lots per base lot per tick" } } }, "TraderPositionView": { "type": "object", "description": "A trader's position view.", "required": [ "symbol", "positionSize", "virtualQuotePosition", "entryPrice", "unrealizedPnl", "discountedUnrealizedPnl", "positionInitialMargin", "initialMargin", "maintenanceMargin", "backstopMargin", "limitOrderMargin", "positionValue", "unsettledFunding", "accumulatedFunding", "liquidationPrice" ], "properties": { "accumulatedFunding": { "type": "string", "description": "Accumulated funding amount." }, "backstopMargin": { "type": "string", "description": "The backstop margin threshold for transfer mechanism." }, "discountedUnrealizedPnl": { "type": "string", "description": "Unrealized PnL after risk discounting." }, "entryPrice": { "type": "string", "description": "Average entry price." }, "initialMargin": { "type": "string", "description": "The total initial margin required for position + limit orders." }, "limitOrderMargin": { "type": "string", "description": "The margin required for current limit orders." }, "liquidationPrice": { "type": "string", "description": "Estimated liquidation price." }, "maintenanceMargin": { "type": "string", "description": "The maintenance margin required to avoid liquidation." }, "positionInitialMargin": { "type": "string", "description": "The initial margin required for just the position (excluding limit\norders)." }, "positionSize": { "type": "string", "description": "Net position size in base units." }, "positionValue": { "type": "string", "description": "Current position notional value." }, "stopLossPrice": { "type": [ "string", "null" ], "description": "Best stop-loss trigger price, if configured." }, "symbol": { "type": "string", "description": "Market symbol (for example, \"SOL-PERP\")." }, "takeProfitPrice": { "type": [ "string", "null" ], "description": "Best take-profit trigger price, if configured." }, "unrealizedPnl": { "type": "string", "description": "Current unrealized PnL." }, "unsettledFunding": { "type": "string", "description": "Unsettled funding amount.\n- Positive value = funding you will receive when settled (increases\n collateral)\n- Negative value = funding you owe when settled (decreases collateral)" }, "virtualQuotePosition": { "type": "string", "description": "Virtual quote position in quote units." } } }, "TraderStateCapabilities": { "type": "object", "description": "Trader capability flags for a subaccount along with convenient derived\nviews.", "required": [ "flags", "state", "capabilities" ], "properties": { "capabilities": { "$ref": "#/components/schemas/TraderCapabilitiesView", "description": "Derived capability booleans." }, "flags": { "$ref": "#/components/schemas/TraderCapabilityFlags", "description": "Raw trader capability bitflags." }, "state": { "$ref": "#/components/schemas/TraderActivityStateView", "description": "Derived trader activity state." } } }, "TraderStateConditionalStopLossTrigger": { "type": "object", "description": "Conditional stop-loss trigger rows scoped to a position.", "required": [ "conditionalStopLossId", "trigger", "status" ], "properties": { "conditionalStopLossId": { "type": "string", "description": "Conditional stop-loss trigger identifier." }, "status": { "type": "string", "description": "Trigger status." }, "trigger": { "$ref": "#/components/schemas/TraderStateConditionalTrigger", "description": "Trigger configuration and conditional metadata." } } }, "TraderStateConditionalTakeProfitTrigger": { "type": "object", "description": "Conditional take-profit trigger rows scoped to a position.", "required": [ "conditionalTakeProfitId", "trigger", "status" ], "properties": { "conditionalTakeProfitId": { "type": "string", "description": "Conditional take-profit trigger identifier." }, "status": { "type": "string", "description": "Trigger status." }, "trigger": { "$ref": "#/components/schemas/TraderStateConditionalTrigger", "description": "Trigger configuration and conditional metadata." } } }, "TraderStateConditionalTrigger": { "allOf": [ { "$ref": "#/components/schemas/TraderStateTrigger", "description": "Base trigger configuration." }, { "type": "object", "required": [ "maxSizeLots", "fillableSizeLots", "filledSizeLots", "usePercent", "percent" ], "properties": { "attachedOrderSequenceNumber": { "type": [ "string", "null" ], "description": "Attached order sequence number when present." }, "fillableSizeLots": { "type": "string", "description": "Remaining fillable trigger size in base lots." }, "filledSizeLots": { "type": "string", "description": "Filled trigger size in base lots." }, "maxSizeLots": { "type": "string", "description": "Max trigger size in base lots." }, "percent": { "type": "integer", "format": "int32", "description": "Percentage used when `use_percent` is true.", "minimum": 0 }, "usePercent": { "type": "boolean", "description": "Whether trigger sizing uses a percentage of margin." } } } ], "description": "Trigger configuration for conditional trigger orders." }, "TraderStateLimitOrderEvent": { "type": "object", "description": "Order grouping used for snapshots.", "required": [ "symbol", "orders" ], "properties": { "orders": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateMarketLimitOrderEvent" }, "description": "Orders currently associated with the symbol." }, "symbol": { "type": "string", "description": "Market symbol for this order group." } } }, "TraderStateMarketLimitOrderEvent": { "type": "object", "description": "Detailed limit order representation.\nWire representation of a single limit-order row grouped by symbol.", "required": [ "orderSequenceNumber", "side", "orderType", "priceTicks", "priceUsd", "sizeRemainingLots", "initialSizeLots", "reduceOnly", "status" ], "properties": { "change": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TraderStateRowChangeKind", "description": "Row-level change kind for delta payloads." } ] }, "conditionalKind": { "type": [ "string", "null" ], "description": "Conditional order kind when present." }, "initialSizeLots": { "type": "string", "description": "Initial order size in lots." }, "isConditionalOrder": { "type": "boolean", "description": "Whether this order originated from a conditional trigger." }, "isStopLoss": { "type": "boolean", "description": "Whether this order is a stop-loss order." }, "isStopLossDirection": { "type": "boolean", "description": "Whether this TP/SL order uses stop-loss direction." }, "orderSequenceNumber": { "type": "string", "description": "Order sequence number." }, "orderType": { "type": "string", "description": "Order type (for example, limit/market variants)." }, "priceTicks": { "type": "string", "description": "Price in ticks." }, "priceUsd": { "type": "string", "description": "Price in USD (decimal string)." }, "reduceOnly": { "type": "boolean", "description": "Whether the order is reduce-only." }, "side": { "$ref": "#/components/schemas/Side", "description": "Side of the order." }, "sizeRemainingLots": { "type": "string", "description": "Remaining order size in lots." }, "status": { "type": "string", "description": "Current order status." } } }, "TraderStatePositionRow": { "type": "object", "description": "Position row used for snapshots and deltas.", "required": [ "positionSequenceNumber", "basePositionLots", "entryPriceTicks", "entryPriceUsd", "virtualQuotePositionLots", "unsettledFundingQuoteLots", "accumulatedFundingQuoteLots", "takeProfitTriggers", "stopLossTriggers" ], "properties": { "accumulatedFundingQuoteLots": { "type": "string", "description": "Accumulated funding amount in quote lots (signed decimal string)." }, "basePositionLots": { "type": "string", "description": "Base position size in lots (signed decimal string)." }, "conditionalStopLossTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateConditionalStopLossTrigger" }, "description": "Configured conditional stop-loss triggers." }, "conditionalTakeProfitTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateConditionalTakeProfitTrigger" }, "description": "Configured conditional take-profit triggers." }, "entryPriceTicks": { "type": "string", "description": "Entry price in ticks." }, "entryPriceUsd": { "type": "string", "description": "Entry price in USD (decimal string)." }, "positionSequenceNumber": { "type": "string", "description": "Position sequence number used for ordering/versioning." }, "stopLossTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateStopLossTrigger" }, "description": "Configured stop-loss triggers." }, "takeProfitTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateTakeProfitTrigger" }, "description": "Configured take-profit triggers." }, "unsettledFundingQuoteLots": { "type": "string", "description": "Unsettled funding amount in quote lots (signed decimal string)." }, "virtualQuotePositionLots": { "type": "string", "description": "Virtual quote position in lots (signed decimal string)." } } }, "TraderStatePositionSnapshot": { "allOf": [ { "$ref": "#/components/schemas/TraderStatePositionRow", "description": "Position row values for the symbol." }, { "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "type": "string", "description": "Market symbol for this position row." } } } ], "description": "Snapshot entry keyed by market symbol.\nFlattened position entry keyed by market symbol.\n\nUsed by snapshots so clients can store each symbol's latest values without\ndealing with nested arrays." }, "TraderStateRowChangeKind": { "type": "string", "description": "Change indicator used for row-level deltas.", "enum": [ "updated", "closed" ] }, "TraderStateSnapshot": { "type": "object", "description": "Snapshot payload covering every subaccount belonging to a trader PDA.", "required": [ "version", "capabilities", "makerFeeOverrideMultiplier", "takerFeeOverrideMultiplier", "subaccounts" ], "properties": { "capabilities": { "$ref": "#/components/schemas/TraderStateCapabilities", "description": "Trader capability flags and derived views (shared across subaccounts)." }, "makerFeeOverrideMultiplier": { "type": "number", "format": "double", "description": "Maker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium)." }, "subaccounts": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateSubaccountSnapshot" }, "description": "Per-subaccount snapshots for this trader PDA." }, "takerFeeOverrideMultiplier": { "type": "number", "format": "double", "description": "Taker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium)." }, "version": { "type": "integer", "format": "int32", "description": "Snapshot schema version.", "minimum": 0 } } }, "TraderStateSnapshotResponse": { "type": "object", "description": "REST response wrapper for a trader-state snapshot.", "required": [ "authority", "traderPdaIndex", "slot", "slotIndex", "snapshot" ], "properties": { "authority": { "type": "string", "description": "Trader authority public key." }, "slot": { "type": "integer", "format": "int64", "description": "Solana slot for this snapshot.", "minimum": 0 }, "slotIndex": { "type": "integer", "format": "int32", "description": "Slot-local index used for deterministic ordering.", "minimum": 0 }, "snapshot": { "$ref": "#/components/schemas/TraderStateSnapshot", "description": "Full trader-state snapshot." }, "traderPdaIndex": { "type": "integer", "format": "int32", "description": "Trader PDA index under the authority.", "minimum": 0 } } }, "TraderStateSplineRow": { "type": "object", "description": "Spline row containing the spline parameters and fill state.", "required": [ "midPriceTicks", "bidFilledAmountLots", "askFilledAmountLots" ], "properties": { "askFilledAmountLots": { "type": "string", "description": "Total filled ask amount in lots." }, "askRegions": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateTickRegion" }, "description": "Ask-side spline regions." }, "bidFilledAmountLots": { "type": "string", "description": "Total filled bid amount in lots." }, "bidRegions": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateTickRegion" }, "description": "Bid-side spline regions." }, "midPriceTicks": { "type": "string", "description": "Mid price in ticks." } } }, "TraderStateSplineSnapshot": { "allOf": [ { "$ref": "#/components/schemas/TraderStateSplineRow", "description": "Spline row values for the symbol." }, { "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "type": "string", "description": "Market symbol for this spline row." } } } ], "description": "Spline snapshot grouped by market symbol." }, "TraderStateStopLossTrigger": { "type": "object", "description": "Stop-loss trigger rows scoped to a position.", "required": [ "stopLossId", "trigger", "status" ], "properties": { "status": { "type": "string", "description": "Trigger status." }, "stopLossId": { "type": "string", "description": "Stop-loss trigger identifier." }, "trigger": { "$ref": "#/components/schemas/TraderStateTrigger", "description": "Trigger configuration." } } }, "TraderStateSubaccountSnapshot": { "type": "object", "description": "Complete subaccount view contained in a snapshot.\nSnapshot of a single subaccount in the `traderState` channel.\n\nCaptures collateral plus the latest known rows for every resource while also\nsurfacing the per-subaccount sequence watermark so clients can detect drift.", "required": [ "subaccountIndex", "sequence", "collateral" ], "properties": { "capabilities": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/TraderStateCapabilities", "description": "Trader capability flags and derived views. Optional for backwards\ncompatibility." } ] }, "collateral": { "type": "string", "description": "Collateral balance (human-readable decimal string)." }, "cooldownStatus": { "oneOf": [ { "type": "null" }, { "$ref": "#/components/schemas/CooldownStatus", "description": "Withdrawal cooldown status. Optional for backwards compatibility." } ] }, "orders": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateLimitOrderEvent" }, "description": "Limit-order rows grouped by symbol." }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStatePositionSnapshot" }, "description": "Position rows keyed by symbol." }, "sequence": { "type": "integer", "format": "int64", "description": "Monotonic sequence for subaccount state updates.", "minimum": 0 }, "splines": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateSplineSnapshot" }, "description": "Spline rows grouped by symbol." }, "subaccountIndex": { "type": "integer", "format": "int32", "description": "Subaccount index under the trader PDA.", "minimum": 0 }, "triggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateTriggerSnapshot" }, "description": "Trigger rows grouped by symbol (TP/SL and conditional triggers)." } } }, "TraderStateTakeProfitTrigger": { "type": "object", "description": "Take-profit trigger rows scoped to a position.", "required": [ "takeProfitId", "trigger", "status" ], "properties": { "status": { "type": "string", "description": "Trigger status." }, "takeProfitId": { "type": "string", "description": "Take-profit trigger identifier." }, "trigger": { "$ref": "#/components/schemas/TraderStateTrigger", "description": "Trigger configuration." } } }, "TraderStateTickRegion": { "type": "object", "description": "Tick region for spline configuration.", "required": [ "startPriceTicks", "endPriceTicks", "densityLotsPerTick", "totalSizeLots", "filledSizeLots" ], "properties": { "densityLotsPerTick": { "type": "string", "description": "Density in lots per tick." }, "endPriceTicks": { "type": "string", "description": "End price of the region in ticks." }, "filledSizeLots": { "type": "string", "description": "Filled region size in lots." }, "startPriceTicks": { "type": "string", "description": "Start price of the region in ticks." }, "totalSizeLots": { "type": "string", "description": "Total region size in lots." } } }, "TraderStateTrigger": { "type": "object", "description": "Trigger configuration for TP/SL orders.", "required": [ "triggerPriceTicks", "executionPriceTicks", "side", "kind" ], "properties": { "executionPriceTicks": { "type": "string", "description": "Execution price in ticks when the trigger fires." }, "kind": { "$ref": "#/components/schemas/StopLossOrderKind", "description": "Stop-loss order kind." }, "side": { "$ref": "#/components/schemas/Side", "description": "Order side for the trigger." }, "triggerPriceTicks": { "type": "string", "description": "Trigger price in ticks." } } }, "TraderStateTriggerRow": { "type": "object", "description": "All trigger data for a single market symbol.", "required": [ "takeProfitTriggers", "stopLossTriggers" ], "properties": { "conditionalStopLossTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateConditionalStopLossTrigger" }, "description": "Configured conditional stop-loss triggers." }, "conditionalTakeProfitTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateConditionalTakeProfitTrigger" }, "description": "Configured conditional take-profit triggers." }, "stopLossTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateStopLossTrigger" }, "description": "Configured stop-loss triggers." }, "takeProfitTriggers": { "type": "array", "items": { "$ref": "#/components/schemas/TraderStateTakeProfitTrigger" }, "description": "Configured take-profit triggers." } } }, "TraderStateTriggerSnapshot": { "allOf": [ { "$ref": "#/components/schemas/TraderStateTriggerRow", "description": "Trigger rows for the symbol." }, { "type": "object", "required": [ "symbol" ], "properties": { "symbol": { "type": "string", "description": "Market symbol for this trigger group." } } } ], "description": "Trigger snapshot grouped by market symbol.\n\nTop-level subaccount entry containing all TP/SL and conditional triggers\nfor a single market. This is the canonical location for trigger data;\nthe trigger fields still present on `TraderStatePositionRow` are deprecated." }, "TraderView": { "type": "object", "description": "Trader view with all trading information", "required": [ "flags", "state", "capabilities", "slot", "slotIndex", "traderKey", "traderPdaIndex", "traderSubaccountIndex", "authority", "collateralBalance", "effectiveCollateral", "effectiveCollateralForWithdrawals", "unrealizedPnl", "discountedUnrealizedPnl", "unsettledFundingOwed", "accumulatedFunding", "portfolioValue", "maintenanceMargin", "cancelMargin", "initialMargin", "initialMarginForWithdrawals", "riskState", "riskTier", "positions", "limitOrders", "makerFeeOverrideMultiplier", "takerFeeOverrideMultiplier", "maxPositions", "lastDepositSlot", "isInActiveTraders", "numMarketsWithSplines" ], "properties": { "accumulatedFunding": { "type": "string", "description": "Accumulated funding amount." }, "authority": { "type": "string", "description": "Trader authority public key." }, "cancelMargin": { "type": "string", "description": "Margin threshold used for cancellation checks." }, "capabilities": { "$ref": "#/components/schemas/TraderCapabilitiesView", "description": "Derived capability matrix." }, "collateralBalance": { "type": "string", "description": "Collateral balance." }, "discountedUnrealizedPnl": { "type": "string", "description": "Discounted unrealized PnL used in risk calculations." }, "effectiveCollateral": { "type": "string", "description": "Effective collateral used for risk checks." }, "effectiveCollateralForWithdrawals": { "type": "string", "description": "Effective collateral used for withdrawal checks." }, "flags": { "$ref": "#/components/schemas/TraderCapabilityFlags", "description": "Raw trader capability flags." }, "initialMargin": { "type": "string", "description": "Required initial margin." }, "initialMarginForWithdrawals": { "type": "string", "description": "Initial margin used for withdrawal checks." }, "isInActiveTraders": { "type": "boolean", "description": "Whether trader is currently in the active-trader buffer." }, "lastDepositSlot": { "type": "integer", "format": "int64", "description": "Last collateral deposit slot.", "minimum": 0 }, "limitOrders": { "type": "object", "description": "Open limit orders grouped by symbol.", "additionalProperties": { "type": "array", "items": { "$ref": "#/components/schemas/LimitOrder" } }, "propertyNames": { "type": "string" } }, "maintenanceMargin": { "type": "string", "description": "Required maintenance margin." }, "makerFeeOverrideMultiplier": { "type": "number", "format": "double", "description": "Maker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium)." }, "maxPositions": { "type": "integer", "format": "int64", "description": "Maximum number of positions allowed.", "minimum": 0 }, "numMarketsWithSplines": { "type": "integer", "format": "int32", "description": "Number of markets where this trader has registered splines", "minimum": 0 }, "portfolioValue": { "type": "string", "description": "Current portfolio value." }, "positions": { "type": "array", "items": { "$ref": "#/components/schemas/TraderPositionView" }, "description": "Open positions." }, "riskState": { "$ref": "#/components/schemas/RiskState", "description": "Current risk state." }, "riskTier": { "$ref": "#/components/schemas/RiskTier", "description": "Current risk tier." }, "slot": { "type": "integer", "format": "int64", "description": "Solana slot of the state snapshot used to build this trader view.", "minimum": 0 }, "slotIndex": { "type": "integer", "format": "int32", "description": "Intra-slot sequence index of the state snapshot used to build this\ntrader view.", "minimum": 0 }, "state": { "$ref": "#/components/schemas/TraderActivityStateView", "description": "Derived high-level trader state." }, "takerFeeOverrideMultiplier": { "type": "number", "format": "double", "description": "Taker fee multiplier (1.0 = default, <1.0 = discount, >1.0 = premium)." }, "traderKey": { "type": "string", "description": "Trader PDA public key." }, "traderPdaIndex": { "type": "integer", "format": "int32", "description": "Trader PDA index under the authority.", "minimum": 0 }, "traderSubaccountIndex": { "type": "integer", "format": "int32", "description": "Trader subaccount index.", "minimum": 0 }, "unrealizedPnl": { "type": "string", "description": "Total unrealized PnL." }, "unsettledFundingOwed": { "type": "string", "description": "Unsettled funding amount owed to the trader.\n- Positive value = funding you will receive when settled (increases\n collateral)\n- Negative value = funding you owe when settled (decreases collateral)" } } }, "UserLiquidationHistoryKind": { "type": "string", "description": "User-scoped liquidation history event kind.", "enum": [ "market_order", "adl", "backstop" ] }, "UserLiquidationHistoryRole": { "type": "string", "description": "Role the requested user played in a liquidation-related event.", "enum": [ "liquidatee", "backstop_liquidatee", "adl_closed_short", "adl_closed_long", "adl_in_profit", "adl_caller" ] }, "UserLiquidationHistoryType": { "type": "string", "description": "High-level liquidation-related event type.", "enum": [ "market", "adl", "backstop" ] }, "ValidateInviteRequest": { "type": "object", "required": [ "code", "wallet_address" ], "properties": { "code": { "type": "string" }, "transaction_signature": { "type": [ "string", "null" ], "description": "Optional transaction signature if the client has already submitted an\non-chain transaction" }, "wallet_address": { "type": "string" } } }, "ValidateInviteResponse": { "type": "object", "required": [ "success", "message", "whitelisted" ], "properties": { "message": { "type": "string" }, "success": { "type": "boolean" }, "whitelisted": { "type": "boolean" } } }, "WalletLoginRequest": { "type": "object", "required": [ "wallet_pubkey", "signature", "nonce_id" ], "properties": { "nonce_id": { "type": "string" }, "signature": { "type": "string" }, "wallet_pubkey": { "type": "string" } } }, "WalletNonceResponse": { "type": "object", "required": [ "nonce_id", "message", "expires_at" ], "properties": { "expires_at": { "type": "string" }, "message": { "type": "string" }, "nonce_id": { "type": "string" } } }, "WalletTransactionChallengeRequest": { "type": "object", "required": [ "wallet_pubkey" ], "properties": { "wallet_pubkey": { "type": "string", "description": "Solana wallet pubkey the caller intends to authenticate as. The\nchallenge transaction is built with this pubkey as the fee payer /\nsole signer." } } }, "WalletTransactionChallengeResponse": { "type": "object", "required": [ "nonce_id", "unsigned_transaction", "expires_at" ], "properties": { "expires_at": { "type": "string", "description": "RFC3339 timestamp at which this challenge expires." }, "nonce_id": { "type": "string", "description": "Opaque server-issued nonce identifier. Echo on the subsequent login\ncall." }, "unsigned_transaction": { "type": "string", "description": "Base64-encoded unsigned Solana legacy transaction (bincode wire\nformat) containing a single Memo program instruction that encodes the\nlogin challenge. Wallets are allowed to include additional\nComputeBudget or Lighthouse instructions before signing (some inject\nthese automatically, in arbitrary positions), but the Memo\ninstruction, the recent blockhash, and the wallet's required-signer\nslot must be preserved. The transaction uses a deterministic,\nnon-recent blockhash and is never submitted on-chain." } } }, "WalletTransactionLoginRequest": { "type": "object", "required": [ "wallet_pubkey", "nonce_id", "signed_transaction" ], "properties": { "nonce_id": { "type": "string", "description": "Echo of the `nonce_id` returned from the challenge endpoint." }, "signed_transaction": { "type": "string", "description": "Base64-encoded fully-signed Solana legacy transaction (bincode wire\nformat). Must be the challenge transaction signed by `wallet_pubkey`.\nWallets are permitted to include additional ComputeBudget or\nLighthouse instructions before signing (in any position); any other\ninstruction (other than the Memo issued by the server) is rejected.\nThe server verifies the signature, the memo payload, and that the\nmessage still uses the issued blockhash so the signed bytes are\nnever broadcastable on-chain." }, "wallet_pubkey": { "type": "string" } } } }, "responses": { "ErrorResponse": { "description": "Standard JSON error payload.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ErrorResponse" } } } } }, "securitySchemes": { "PhoenixBearerAuth": { "type": "http", "scheme": "bearer", "description": "Bearer access token issued by `/v1/auth/*` login endpoints." } } }, "tags": [ { "name": "Auth", "description": "Wallet and session authentication." }, { "name": "Exchange", "description": "Exchange, market, candle, and no-referral register-instruction workflows." }, { "name": "Invite", "description": "Invite validation, referral activation, and wallet allowlist checks." }, { "name": "Notifications", "description": "Trader notification reads and acknowledgement helpers." }, { "name": "Trader", "description": "Trader state, account history, and transaction builders." } ], "externalDocs": { "url": "https://docs.phoenix.trade", "description": "Phoenix developer documentation" } }