SPB Git

Repository Public

TRADING-API-OPENAPI.md 74.6 KB 1,615 lines markdown

1# SP Trading API v1 — reference23> Generated by `node scripts/gen-openapi.mts` from `services/api/src/trading-api/spec.ts`. Do not edit by hand:4> a test compares this file and `docs/openapi/trading-v1.json` with what the code generates.56Version 1.0.0. Machine-readable document: [`docs/openapi/trading-v1.json`](openapi/trading-v1.json), also served at `GET /api/v1/trading/openapi.json`.78This file is the compact index (operations, raw JSON Schemas, error codes). The reference with getting started, concepts, a worked example per operation9and what each error means is [`TRADING-API-REFERENCE.md`](TRADING-API-REFERENCE.md), served at `GET /api/v1/trading/docs`.1011## Authentication1213`Authorization: Bearer spw_live_<key id>_<secret>`. No cookie, no CSRF header. The key is refused on every path outside14`/api/v1/trading/`.1516## Streaming1718Live market data (quotes, order books, trades, candles, venue statuses) is also served over a websocket, which the OpenAPI document cannot describe:19`GET /api/v1/trading/stream` — scope `markets:read`; the key in the `Authorization` header of the handshake, or `?ticket=` with a single-use ticket20from `POST /api/v1/trading/stream/ticket` (the way of a browser, which cannot set a header on a websocket). Protocol: [`V11-QUOTE-ENGINE.md`](V11-QUOTE-ENGINE.md); clients:21`SPWalletStream` in both SDKs.2223**A stream connection writes no row in the key's usage log**: it is counted in the stream's own statistics. The ticket request is an ordinary call and is24logged like any other.2526## Scopes2728| Scope | Execution scope (inert without an approved trading mandate bound to the key — except a cancel of the key's own order and the kill switch, which only remove risk) |29|---|---|30| `wallet:read` | no |31| `markets:read` | no |32| `orders:read` | no |33| `orders:prepare` | no |34| `orders:execute` | yes |35| `orders:cancel` | yes |36| `positions:read` | no |37| `positions:manage` | yes |38| `strategies:read` | no |39| `strategies:manage` | no |40| `agents:read` | no |41| `agents:manage` | no |4243## Operations4445| Method | Path | Scope | State | Idempotency-Key | Summary |46|---|---|---|---|---|---|47| GET | `/api/v1/trading/openapi.json` | any valid key | implemented | — | This document |48| GET | `/api/v1/trading/markets` | `markets:read` | implemented | — | Instruments across venues (perpetuals) and the spot market-data symbols |49| GET | `/api/v1/trading/markets/compare` | `markets:read` | implemented | — | Compare the estimated cost of one position across venues |50| GET | `/api/v1/trading/markets/{symbol}` | `markets:read` | implemented | — | One market: instrument, ticker and data quality |51| GET | `/api/v1/trading/markets/{symbol}/orderbook` | `markets:read` | implemented | — | Order book of one market |52| GET | `/api/v1/trading/markets/{symbol}/candles` | `markets:read` | implemented | — | Closed bars of one market |53| GET | `/api/v1/trading/private-markets` | `markets:read` | implemented | — | Synthetic contracts on private companies, venue by venue, with sourced valuations |54| GET | `/api/v1/trading/private-markets/companies/{slug}` | `markets:read` | implemented | — | Every contract on one private company, side by side (never merged) |55| GET | `/api/v1/trading/private-markets/{id}` | `markets:read` | implemented | — | One private-company contract: definition, valuation breakdown, candles, top of book |56| GET | `/api/v1/trading/portfolio` | `wallet:read` | implemented | — | Wallet value and derivative accounts, per mode |57| GET | `/api/v1/trading/balances` | `wallet:read` | implemented | — | On-chain balances of the wallet |58| GET | `/api/v1/trading/activity` | `wallet:read` | implemented | — | Wallet activity and fills, newest first |59| GET | `/api/v1/trading/nfts` | `wallet:read` | implemented | — | NFTs of the wallet (what the chain confirmed as held) |60| GET | `/api/v1/trading/nfts/item` | `wallet:read` | implemented | — | One NFT of the wallet: identity, ownership, creator metadata, sources |61| GET | `/api/v1/trading/nfts/activity` | `wallet:read` | implemented | — | On-chain events of one NFT of the wallet |62| GET | `/api/v1/trading/nfts/market` | `markets:read` | implemented | — | Market data of any NFT, one row per source |63| GET | `/api/v1/trading/nfts/market/events` | `markets:read` | implemented | — | Market events of any NFT (sales, listings, offers), per source |64| GET | `/api/v1/trading/positions` | `positions:read` | implemented | — | Open positions, paper and live separated by `mode` |65| GET | `/api/v1/trading/orders` | `orders:read` | implemented | — | Orders, newest first |66| GET | `/api/v1/trading/orders/{id}` | `orders:read` | implemented | — | One order and its fills |67| GET | `/api/v1/trading/strategies` | `strategies:read` | implemented | — | Strategy library and the versions pinned to agents |68| GET | `/api/v1/trading/agents` | `agents:read` | implemented | — | Trading agents |69| GET | `/api/v1/trading/risk` | `positions:read` | implemented | — | Risk state: kill switch, signer limits, capability locks, account policies |70| POST | `/api/v1/trading/orders/preview` | `orders:prepare` | implemented | — | Preview an order: every check it would meet, and an estimate |71| POST | `/api/v1/trading/orders` | `orders:execute` | implemented | required | Place an order |72| DELETE | `/api/v1/trading/orders/{id}` | `orders:cancel` | implemented | required | Cancel an order |73| POST | `/api/v1/trading/positions/{id}/close` | `positions:manage` | implemented | required | Close a position |74| POST | `/api/v1/trading/positions/{id}/reduce` | `positions:manage` | implemented | required | Reduce a position |75| POST | `/api/v1/trading/commands` | `orders:prepare` | implemented | required | Run one line of the trading command grammar |76| POST | `/api/v1/trading/risk/kill-switch` | `positions:manage` | implemented | — | Engage the global kill switch |77| POST | `/api/v1/trading/strategies` | `strategies:manage` | implemented | required | Register a library strategy version on an agent |78| POST | `/api/v1/trading/strategies/{id}/backtest` | `strategies:manage` | implemented | required | Run the backtest of a strategy version (asynchronous job) |79| POST | `/api/v1/trading/strategies/{id}/start` | `strategies:manage` | implemented | required | Start the agent a strategy version is pinned to |80| POST | `/api/v1/trading/strategies/{id}/stop` | `strategies:manage` | implemented | required | Stop the agent a strategy version is pinned to |81| GET | `/api/v1/trading/agents/templates` | `agents:read` | implemented | — | The seven built-in agents: family, engine, modes, installed strategies |82| GET | `/api/v1/trading/agents/{id}` | `agents:read` | implemented | — | One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state |83| GET | `/api/v1/trading/agents/{id}/signals` | `agents:read` | implemented | — | Signal history of one agent, ONE mode |84| GET | `/api/v1/trading/agents/{id}/journal` | `agents:read` | implemented | — | Activity journal of one agent, ONE mode |85| GET | `/api/v1/trading/agents/{id}/orders` | `agents:read` | implemented | — | Order history of one agent, ONE mode, in the unified order states |86| GET | `/api/v1/trading/agents/{id}/performance` | `agents:read` | implemented | — | Computed performance of one agent, ONE mode |87| GET | `/api/v1/trading/jobs/{id}` | `agents:read` | implemented | — | One agent job (backtest, wind-down): status and result |88| POST | `/api/v1/trading/agents` | `agents:manage` | implemented | required | Create an agent (from a template, or a perp agent) |89| POST | `/api/v1/trading/agents/{id}/start` | `agents:manage` | implemented | required | Start an agent in research, paper or live mode |90| POST | `/api/v1/trading/agents/{id}/pause` | `agents:manage` | implemented | required | Pause an agent |91| POST | `/api/v1/trading/agents/{id}/stop` | `agents:manage` | implemented | required | Stop an agent (always allowed) |92| POST | `/api/v1/trading/agents/{id}/backtest` | `agents:manage` | implemented | required | Run a backtest for an agent (asynchronous job) |9394## Parameters9596### GET `/api/v1/trading/markets`9798| Name | In | Required | Schema | Description |99|---|---|---|---|---|100| `venue` | query | no | `{"type":"string","maxLength":40}` | venue id: hyperliquid, gmx, dydx, spot |101| `kind` | query | no | `{"type":"string","enum":["perpetual","spot"]}` | perpetual = a venue instrument; spot = a market-data symbol |102| `q` | query | no | `{"type":"string","maxLength":40}` | case-insensitive match on id, symbol or base |103| `limit` | query | no | `{"default":2000,"type":"integer","minimum":1,"maximum":5000}` | rows returned at most; `total` and `truncated` say when it cut the list |104105### GET `/api/v1/trading/markets/compare`106107| Name | In | Required | Schema | Description |108|---|---|---|---|---|109| `underlying` | query | no | `{"default":"BTC","type":"string","pattern":"^[A-Za-z0-9]{1,15}$"}` | common underlying, e.g. BTC (see GET /markets-hub/underlyings) |110| `side` | query | no | `{"default":"long","type":"string","enum":["long","short"]}` | direction of the position compared |111| `notional` | query | no | `{"default":"1000","type":"string","pattern":"^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"}` | position notional in USD (not the collateral) |112| `leverage` | query | no | `{"default":"1","type":"string","pattern":"^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"}` | leverage of the position: collateral = notional / leverage |113| `horizonHours` | query | no | `{"default":"24","type":"string","pattern":"^(0|[1-9]\\d{0,3})(\\.\\d{1,4})?$"}` | expected holding period; funding is the current rate held constant over it |114| `liquidity` | query | no | `{"default":"taker","type":"string","enum":["taker","maker"]}` | how the entry and the exit are executed, for the fee |115| `minNetEdgeBps` | query | no | `{"default":"0","type":"string","pattern":"^(0|[1-9]\\d{0,4})(\\.\\d{1,4})?$"}` | a discrepancy estimate above this is flagged |116117### GET `/api/v1/trading/markets/{symbol}`118119| Name | In | Required | Schema | Description |120|---|---|---|---|---|121| `symbol` | path | yes | `{"type":"string","minLength":1,"maxLength":120}` | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous |122123### GET `/api/v1/trading/markets/{symbol}/orderbook`124125| Name | In | Required | Schema | Description |126|---|---|---|---|---|127| `symbol` | path | yes | `{"type":"string","minLength":1,"maxLength":120}` | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous |128| `depth` | query | no | `{"default":20,"type":"integer","minimum":1,"maximum":50}` | price levels per side |129130### GET `/api/v1/trading/markets/{symbol}/candles`131132| Name | In | Required | Schema | Description |133|---|---|---|---|---|134| `symbol` | path | yes | `{"type":"string","minLength":1,"maxLength":120}` | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous |135| `interval` | query | no | `{"default":"1h","type":"string","enum":["1m","5m","15m","1h","4h","1d"]}` | bar length |136| `limit` | query | no | `{"default":200,"type":"integer","minimum":1,"maximum":1000}` | most recent closed bars, oldest first in the answer |137138### GET `/api/v1/trading/private-markets`139140| Name | In | Required | Schema | Description |141|---|---|---|---|---|142| `delisted` | query | no | `{"type":"string","enum":["true","false"]}` | true: only delisted markets (frozen prices) |143| `size` | query | no | `{"type":"string","pattern":"^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"}` | hypothetical position size, contracts (default 1) |144| `side` | query | no | `{"type":"string","enum":["long","short"]}` | side of the hypothetical position (default long) |145146### GET `/api/v1/trading/private-markets/companies/{slug}`147148| Name | In | Required | Schema | Description |149|---|---|---|---|---|150| `slug` | path | yes | `{"type":"string","pattern":"^[a-z0-9-]{1,40}$"}` | company slug, from GET /private-markets (`companies[].slug`), e.g. `anthropic` |151| `size` | query | no | `{"type":"string","pattern":"^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"}` | hypothetical position size, contracts (default 1) |152| `side` | query | no | `{"type":"string","enum":["long","short"]}` | side of the hypothetical position (default long) |153| `interval` | query | no | `{"type":"string","enum":["1h","1d"]}` | candle length |154| `limit` | query | no | `{"type":"integer","minimum":1,"maximum":500}` | candles returned at most |155156### GET `/api/v1/trading/private-markets/{id}`157158| Name | In | Required | Schema | Description |159|---|---|---|---|---|160| `id` | path | yes | `{"type":"string","minLength":3,"maxLength":120,"pattern":"^[a-z]+:[A-Za-z0-9:._-]+$"}` | `venue:symbol`, e.g. `hyperliquid:io:ANTH`, `edgex:ANTHROPICUSDC` |161| `size` | query | no | `{"type":"string","pattern":"^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"}` | hypothetical position size, contracts (default 1) |162| `side` | query | no | `{"type":"string","enum":["long","short"]}` | side of the hypothetical position (default long) |163| `interval` | query | no | `{"type":"string","enum":["1h","1d"]}` | candle length |164| `limit` | query | no | `{"type":"integer","minimum":1,"maximum":500}` | candles returned at most |165166### GET `/api/v1/trading/balances`167168| Name | In | Required | Schema | Description |169|---|---|---|---|---|170| `network` | query | no | `{"type":"string","maxLength":24}` | one network id (e.g. `base`, `arbitrum`, `solana`); default: every network of the wallet |171172### GET `/api/v1/trading/activity`173174| Name | In | Required | Schema | Description |175|---|---|---|---|---|176| `limit` | query | no | `{"default":100,"type":"integer","minimum":1,"maximum":500}` | rows returned at most |177| `cursor` | query | no | `{"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$"}` | opaque position returned as `nextCursor` by the previous page; send it with the same filters |178179### GET `/api/v1/trading/nfts`180181| Name | In | Required | Schema | Description |182|---|---|---|---|---|183| `network` | query | no | `{"type":"string","maxLength":24}` | one network id; default: all |184| `collection` | query | no | `{"type":"string","maxLength":260}` | collection key |185| `status` | query | no | `{"type":"string","enum":["in_wallet","left","tracked"]}` | in_wallet: held now; left: was found in the wallet and is no longer held; tracked: added by hand. Default: held, tracked, or left within the last 30 days |186| `q` | query | no | `{"type":"string","maxLength":80}` | case-insensitive text matched on the name, the key or the collection name |187| `sort` | query | no | `{"default":"recent","type":"string","enum":["recent","name"]}` | order of the list |188| `spam` | query | no | `{"default":"hide","type":"string","enum":["hide","show","only"]}` | items an indexer flags as spam are hidden by default, never deleted |189| `limit` | query | no | `{"default":48,"type":"integer","minimum":1,"maximum":100}` | rows returned at most |190| `cursor` | query | no | `{"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$"}` | opaque position returned as `nextCursor` by the previous page; send it with the same filters |191192### GET `/api/v1/trading/nfts/item`193194| Name | In | Required | Schema | Description |195|---|---|---|---|---|196| `key` | query | yes | `{"type":"string","minLength":5,"maxLength":260}` | `family:network:asset-id`, as returned by GET /nfts |197198### GET `/api/v1/trading/nfts/activity`199200| Name | In | Required | Schema | Description |201|---|---|---|---|---|202| `key` | query | yes | `{"type":"string","minLength":5,"maxLength":260}` | `family:network:asset-id`, as returned by GET /nfts |203| `limit` | query | no | `{"default":20,"type":"integer","minimum":1,"maximum":50}` | rows returned at most |204| `cursor` | query | no | `{"type":"string","maxLength":400}` | `nextCursor` of the previous page |205| `type` | query | no | `{"type":"string","enum":["mint","transfer","transfer-in","transfer-out","burn","sale","unknown"]}` | only events of this type |206207### GET `/api/v1/trading/nfts/market`208209| Name | In | Required | Schema | Description |210|---|---|---|---|---|211| `network` | query | yes | `{"type":"string","maxLength":24}` | network id, e.g. `ethereum`, `base`, `solana` |212| `address` | query | yes | `{"type":"string","minLength":26,"maxLength":64}` | EVM: the contract; Solana: the mint / asset address |213| `tokenId` | query | no | `{"type":"string","maxLength":80}` | EVM: required, decimal or 0x-hex |214215### GET `/api/v1/trading/nfts/market/events`216217| Name | In | Required | Schema | Description |218|---|---|---|---|---|219| `network` | query | yes | `{"type":"string","maxLength":24}` | network id, e.g. `ethereum`, `base`, `solana` |220| `address` | query | yes | `{"type":"string","minLength":26,"maxLength":64}` | EVM: the contract; Solana: the mint / asset address |221| `tokenId` | query | no | `{"type":"string","maxLength":80}` | EVM: required, decimal or 0x-hex |222| `provider` | query | no | `{"type":"string","pattern":"^[a-z][a-z0-9-]{1,30}$"}` | only this source (its id is `sources[].status.provider`); required with `cursor` |223| `type` | query | no | `{"type":"string","maxLength":120,"pattern":"^[a-z,-]+$"}` | comma-separated: sale, list, delist, offer, cancel-offer, transfer, mint |224| `after` | query | no | `{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}` | only events after this instant (ISO 8601) |225| `before` | query | no | `{"type":"string","format":"date-time","pattern":"^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"}` | only events before this instant (ISO 8601) |226| `cursor` | query | no | `{"type":"string","maxLength":600}` | a position in ONE source's list: send it with `provider` |227| `limit` | query | no | `{"default":20,"type":"integer","minimum":1,"maximum":50}` | rows returned at most |228229### GET `/api/v1/trading/positions`230231| Name | In | Required | Schema | Description |232|---|---|---|---|---|233| `mode` | query | no | `{"type":"string","enum":["paper","live"]}` | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |234| `venue` | query | no | `{"type":"string","maxLength":40}` | venue id: hyperliquid, gmx, dydx, spot |235236### GET `/api/v1/trading/orders`237238| Name | In | Required | Schema | Description |239|---|---|---|---|---|240| `mode` | query | no | `{"type":"string","enum":["paper","live"]}` | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |241| `venue` | query | no | `{"type":"string","maxLength":40}` | venue id: hyperliquid, gmx, dydx, spot |242| `open` | query | no | `{"type":"string","enum":["true","false"]}` | true: only orders that are not final; false: only final orders |243| `limit` | query | no | `{"default":100,"type":"integer","minimum":1,"maximum":500}` | rows returned at most |244| `cursor` | query | no | `{"type":"string","minLength":1,"maxLength":400,"pattern":"^[A-Za-z0-9_-]+$"}` | opaque position returned as `nextCursor` by the previous page; send it with the same filters |245246### GET `/api/v1/trading/orders/{id}`247248| Name | In | Required | Schema | Description |249|---|---|---|---|---|250| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |251252### GET `/api/v1/trading/strategies`253254| Name | In | Required | Schema | Description |255|---|---|---|---|---|256| `kind` | query | no | `{"type":"string","enum":["spot","perp"]}` | only spot or only perp strategies |257258### POST `/api/v1/trading/orders/preview`259260Request body (JSON):261262```json263{264  "type": "object",265  "properties": {266    "mode": {267      "type": "string",268      "enum": [269        "paper",270        "live"271      ],272      "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."273    },274    "accountId": {275      "description": "paper account or venue account; required when the wallet has several on the venue",276      "type": "string",277      "format": "uuid",278      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"279    },280    "instrument": {281      "type": "string",282      "minLength": 1,283      "maxLength": 120,284      "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"285    },286    "side": {287      "type": "string",288      "enum": [289        "buy",290        "sell"291      ],292      "description": "buy opens or adds to a long (or reduces a short); sell the reverse"293    },294    "type": {295      "type": "string",296      "enum": [297        "limit",298        "market",299        "stop_market",300        "stop_limit",301        "take_profit_market",302        "take_profit_limit"303      ],304      "description": "market: immediate, bounded by `slippageBps`. limit: rests at `price`. stop_* and take_profit_*: wait for `triggerPrice`, then act as a market order or as a limit order at `price`"305    },306    "size": {307      "description": "quantity of the base asset. Exactly one of `size` and `notional` is required",308      "type": "string",309      "pattern": "^\\d+(\\.\\d+)?$"310    },311    "notional": {312      "description": "value of the order in the quote currency of the instrument (USD or a USD stablecoin on every venue of this wallet). The SERVER turns it into a size: notional / reference price, rounded DOWN to the lot size — the reference is the limit price, else the trigger price, else the mark price read now (503 `stale_data` when it is stale; 422 `below_min_size` under one lot). The answer carries the size that was used. Exactly one of `size` and `notional` is required. A SPOT order: a SELL names `size` (the quantity sold); a BUY names `notional` — the amount of the quote asset to spend — because a swap is exact-input",313      "type": "string",314      "pattern": "^\\d+(\\.\\d+)?$"315    },316    "price": {317      "description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",318      "type": "string",319      "pattern": "^\\d+(\\.\\d+)?$"320    },321    "triggerPrice": {322      "description": "price at which a stop or take-profit order is triggered; required by the four trigger types",323      "type": "string",324      "pattern": "^\\d+(\\.\\d+)?$"325    },326    "reduceOnly": {327      "default": false,328      "description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",329      "type": "boolean"330    },331    "tif": {332      "default": "gtc",333      "description": "time in force of a limit order: gtc = rests until cancelled, ioc = fills what it can at once and cancels the rest, alo = add liquidity only (post-only)",334      "type": "string",335      "enum": [336        "gtc",337        "ioc",338        "alo"339      ]340    },341    "slippageBps": {342      "description": "market orders: the worst acceptable price, in basis points from the reference price",343      "type": "integer",344      "minimum": 1,345      "maximum": 500346    },347    "leverage": {348      "description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",349      "type": "string",350      "pattern": "^\\d+(\\.\\d+)?$"351    },352    "maxFeeUsd": {353      "description": "highest fee accepted, USD; default: 10 bps of the notional",354      "type": "string",355      "pattern": "^\\d+(\\.\\d+)?$"356    },357    "clientOrderId": {358      "description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",359      "type": "string",360      "pattern": "^[A-Za-z0-9._:-]{8,100}$"361    }362  },363  "required": [364    "mode",365    "instrument",366    "side",367    "type"368  ],369  "additionalProperties": false370}371```372373### POST `/api/v1/trading/orders`374375Request body (JSON):376377```json378{379  "type": "object",380  "properties": {381    "mode": {382      "type": "string",383      "enum": [384        "paper",385        "live"386      ],387      "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."388    },389    "accountId": {390      "description": "paper account or venue account; required when the wallet has several on the venue",391      "type": "string",392      "format": "uuid",393      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"394    },395    "instrument": {396      "type": "string",397      "minLength": 1,398      "maxLength": 120,399      "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"400    },401    "side": {402      "type": "string",403      "enum": [404        "buy",405        "sell"406      ],407      "description": "buy opens or adds to a long (or reduces a short); sell the reverse"408    },409    "type": {410      "type": "string",411      "enum": [412        "limit",413        "market",414        "stop_market",415        "stop_limit",416        "take_profit_market",417        "take_profit_limit"418      ],419      "description": "market: immediate, bounded by `slippageBps`. limit: rests at `price`. stop_* and take_profit_*: wait for `triggerPrice`, then act as a market order or as a limit order at `price`"420    },421    "size": {422      "description": "quantity of the base asset. Exactly one of `size` and `notional` is required",423      "type": "string",424      "pattern": "^\\d+(\\.\\d+)?$"425    },426    "notional": {427      "description": "value of the order in the quote currency of the instrument (USD or a USD stablecoin on every venue of this wallet). The SERVER turns it into a size: notional / reference price, rounded DOWN to the lot size — the reference is the limit price, else the trigger price, else the mark price read now (503 `stale_data` when it is stale; 422 `below_min_size` under one lot). The answer carries the size that was used. Exactly one of `size` and `notional` is required. A SPOT order: a SELL names `size` (the quantity sold); a BUY names `notional` — the amount of the quote asset to spend — because a swap is exact-input",428      "type": "string",429      "pattern": "^\\d+(\\.\\d+)?$"430    },431    "price": {432      "description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",433      "type": "string",434      "pattern": "^\\d+(\\.\\d+)?$"435    },436    "triggerPrice": {437      "description": "price at which a stop or take-profit order is triggered; required by the four trigger types",438      "type": "string",439      "pattern": "^\\d+(\\.\\d+)?$"440    },441    "reduceOnly": {442      "default": false,443      "description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",444      "type": "boolean"445    },446    "tif": {447      "default": "gtc",448      "description": "time in force of a limit order: gtc = rests until cancelled, ioc = fills what it can at once and cancels the rest, alo = add liquidity only (post-only)",449      "type": "string",450      "enum": [451        "gtc",452        "ioc",453        "alo"454      ]455    },456    "slippageBps": {457      "description": "market orders: the worst acceptable price, in basis points from the reference price",458      "type": "integer",459      "minimum": 1,460      "maximum": 500461    },462    "leverage": {463      "description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",464      "type": "string",465      "pattern": "^\\d+(\\.\\d+)?$"466    },467    "maxFeeUsd": {468      "description": "highest fee accepted, USD; default: 10 bps of the notional",469      "type": "string",470      "pattern": "^\\d+(\\.\\d+)?$"471    },472    "clientOrderId": {473      "description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",474      "type": "string",475      "pattern": "^[A-Za-z0-9._:-]{8,100}$"476    }477  },478  "required": [479    "mode",480    "instrument",481    "side",482    "type"483  ],484  "additionalProperties": false485}486```487488### DELETE `/api/v1/trading/orders/{id}`489490| Name | In | Required | Schema | Description |491|---|---|---|---|---|492| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |493494### POST `/api/v1/trading/positions/{id}/close`495496| Name | In | Required | Schema | Description |497|---|---|---|---|---|498| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |499500Request body (JSON):501502```json503{504  "type": "object",505  "properties": {506    "slippageBps": {507      "description": "worst acceptable price of the closing market order, in basis points from the reference price",508      "type": "integer",509      "minimum": 1,510      "maximum": 500511    }512  },513  "additionalProperties": false514}515```516517### POST `/api/v1/trading/positions/{id}/reduce`518519| Name | In | Required | Schema | Description |520|---|---|---|---|---|521| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |522523Request body (JSON):524525```json526{527  "type": "object",528  "properties": {529    "fraction": {530      "type": "string",531      "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",532      "description": "share of the position to close, in (0, 1]"533    },534    "slippageBps": {535      "description": "worst acceptable price of the reducing market order, in basis points from the reference price",536      "type": "integer",537      "minimum": 1,538      "maximum": 500539    }540  },541  "required": [542    "fraction"543  ],544  "additionalProperties": false545}546```547548### POST `/api/v1/trading/commands`549550Request body (JSON):551552```json553{554  "type": "object",555  "properties": {556    "text": {557      "type": "string",558      "minLength": 1,559      "maxLength": 300,560      "description": "one line of the trading command grammar, English or French: LONG BTC-PERP 500 x2, CLOSE BTC-PERP 50%, CANCEL ORDER <id>, SHOW POSITIONS, KILL …"561    },562    "mode": {563      "default": "paper",564      "type": "string",565      "enum": [566        "paper",567        "live"568      ],569      "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."570    },571    "accountId": {572      "description": "paper account or venue account; required when the wallet has several on the venue",573      "type": "string",574      "format": "uuid",575      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"576    },577    "dryRun": {578      "default": false,579      "description": "true: answer the canonical order (or the control) the command resolves to, and do nothing",580      "type": "boolean"581    }582  },583  "required": [584    "text"585  ],586  "additionalProperties": false587}588```589590### POST `/api/v1/trading/risk/kill-switch`591592Request body (JSON):593594```json595{596  "type": "object",597  "properties": {598    "reason": {599      "default": "",600      "description": "why, for the audit trail and the `risk.kill_switch` webhook",601      "type": "string",602      "maxLength": 200603    }604  },605  "additionalProperties": false606}607```608609### POST `/api/v1/trading/strategies`610611Request body (JSON):612613```json614{615  "type": "object",616  "properties": {617    "kind": {618      "type": "string",619      "enum": [620        "spot",621        "perp"622      ],623      "description": "must be the kind of the agent (409 `wrong_kind` otherwise)"624    },625    "path": {626      "type": "string",627      "minLength": 1,628      "maxLength": 200,629      "description": "library path of the strategy, from GET /strategies (`library[].path`)"630    },631    "agentId": {632      "description": "the agent the version is registered on; required in practice (400 without it)",633      "type": "string",634      "format": "uuid",635      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"636    }637  },638  "required": [639    "kind",640    "path"641  ],642  "additionalProperties": false643}644```645646### POST `/api/v1/trading/strategies/{id}/backtest`647648| Name | In | Required | Schema | Description |649|---|---|---|---|---|650| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |651652Request body (JSON):653654```json655{656  "type": "object",657  "properties": {658    "symbols": {659      "description": "default: the agent's universe",660      "minItems": 1,661      "maxItems": 12,662      "type": "array",663      "items": {664        "type": "string",665        "pattern": "^[A-Z0-9]{2,15}$"666      }667    },668    "interval": {669      "description": "bar interval; default: the agent's",670      "type": "string",671      "enum": [672        "1h",673        "1d"674      ]675    }676  },677  "additionalProperties": false678}679```680681### POST `/api/v1/trading/strategies/{id}/start`682683| Name | In | Required | Schema | Description |684|---|---|---|---|---|685| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |686687Request body (JSON):688689```json690{691  "type": "object",692  "properties": {693    "mode": {694      "type": "string",695      "enum": [696        "research",697        "paper",698        "live"699      ],700      "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."701    },702    "agentId": {703      "description": "strategy operations only: the agent, when the version id alone does not name it",704      "type": "string",705      "format": "uuid",706      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"707    }708  },709  "required": [710    "mode"711  ],712  "additionalProperties": false713}714```715716### POST `/api/v1/trading/strategies/{id}/stop`717718| Name | In | Required | Schema | Description |719|---|---|---|---|---|720| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |721722Request body (JSON):723724```json725{726  "type": "object",727  "properties": {728    "reason": {729      "default": "",730      "description": "why, for the agent's journal",731      "type": "string",732      "maxLength": 200733    }734  },735  "additionalProperties": false736}737```738739### GET `/api/v1/trading/agents/{id}`740741| Name | In | Required | Schema | Description |742|---|---|---|---|---|743| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |744745### GET `/api/v1/trading/agents/{id}/signals`746747| Name | In | Required | Schema | Description |748|---|---|---|---|---|749| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |750| `mode` | query | no | `{"type":"string","enum":["research","paper","live"]}` | default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it. |751| `limit` | query | no | `{"default":100,"type":"integer","minimum":1,"maximum":500}` | rows returned at most |752| `before` | query | no | `{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}` | unix ms: rows strictly before it |753754### GET `/api/v1/trading/agents/{id}/journal`755756| Name | In | Required | Schema | Description |757|---|---|---|---|---|758| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |759| `mode` | query | no | `{"type":"string","enum":["research","paper","live"]}` | default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it. |760| `limit` | query | no | `{"default":100,"type":"integer","minimum":1,"maximum":500}` | rows returned at most |761| `before` | query | no | `{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}` | unix ms: rows strictly before it |762763### GET `/api/v1/trading/agents/{id}/orders`764765| Name | In | Required | Schema | Description |766|---|---|---|---|---|767| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |768| `mode` | query | no | `{"type":"string","enum":["research","paper","live"]}` | default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it. |769| `limit` | query | no | `{"default":100,"type":"integer","minimum":1,"maximum":500}` | rows returned at most |770| `before` | query | no | `{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991}` | unix ms: rows strictly before it |771| `open` | query | no | `{"type":"string","enum":["true","false"]}` | true: only the orders that are not final |772773### GET `/api/v1/trading/agents/{id}/performance`774775| Name | In | Required | Schema | Description |776|---|---|---|---|---|777| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |778| `mode` | query | no | `{"type":"string","enum":["research","paper","live"]}` | default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it. |779780### GET `/api/v1/trading/jobs/{id}`781782| Name | In | Required | Schema | Description |783|---|---|---|---|---|784| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |785786### POST `/api/v1/trading/agents`787788Request body (JSON):789790```json791{792  "type": "object",793  "properties": {794    "kind": {795      "description": "without a template: perp (a spot agent needs a vault from the signer: owner only)",796      "type": "string",797      "enum": [798        "spot",799        "perp"800      ]801    },802    "template": {803      "description": "one of GET /agents/templates",804      "type": "string",805      "maxLength": 40806    },807    "name": {808      "type": "string",809      "minLength": 2,810      "maxLength": 40,811      "description": "shown in the app and in the lists"812    },813    "mission": {814      "default": "",815      "description": "free text for people; it changes nothing the agent does",816      "type": "string",817      "maxLength": 400818    },819    "universe": {820      "description": "asset symbols the agent trades, e.g. [\"BTC\"]; a fixed-universe strategy needs its exact universe (422 `universe_mismatch`); default: the template's",821      "minItems": 1,822      "maxItems": 12,823      "type": "array",824      "items": {825        "type": "string",826        "pattern": "^[A-Z0-9]{2,15}$"827      }828    },829    "venues": {830      "description": "venues the agent reads; default: the template's",831      "minItems": 1,832      "maxItems": 2,833      "type": "array",834      "items": {835        "type": "string",836        "enum": [837          "hyperliquid",838          "edgex",839          "dydx",840          "gmx"841        ]842      }843    },844    "strategyPath": {845      "description": "bar templates: which of the template's installed strategies to bind, from GET /agents/templates",846      "type": "string",847      "maxLength": 60848    },849    "interval": {850      "description": "bar agents: bar length; default 1h",851      "type": "string",852      "enum": [853        "1h",854        "4h",855        "1d"856      ]857    },858    "capitalUsdc": {859      "description": "simulated capital of the agent, a decimal string; default 1000",860      "type": "string",861      "pattern": "^\\d{1,7}(\\.\\d{1,6})?$"862    },863    "risk": {864      "description": "overrides of the agent's own risk limits, by name (the limits in force are in GET /agents/{id}: `riskLimits`)",865      "type": "object",866      "propertyNames": {867        "type": "string"868      },869      "additionalProperties": {870        "type": [871          "number",872          "string",873          "boolean"874        ]875      }876    },877    "config": {878      "description": "overrides of the template's parameters, by name",879      "type": "object",880      "propertyNames": {881        "type": "string"882      },883      "additionalProperties": {}884    },885    "mode": {886      "default": "research",887      "description": "research (default): the agent is created and not running. paper: an agent created from a stream or supervisor template is started on paper at once; a bar agent (momentum, mean reversion, …, or `kind: perp`) is created and NOT started — it needs a backtested strategy version first, then POST /agents/{id}/start. `live` is refused (400 `bad_request`): an agent goes live only through POST /agents/{id}/start, under a mandate the owner approved.",888      "type": "string",889      "enum": [890        "research",891        "paper"892      ]893    }894  },895  "required": [896    "name"897  ],898  "additionalProperties": false899}900```901902### POST `/api/v1/trading/agents/{id}/start`903904| Name | In | Required | Schema | Description |905|---|---|---|---|---|906| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |907908Request body (JSON):909910```json911{912  "type": "object",913  "properties": {914    "mode": {915      "type": "string",916      "enum": [917        "research",918        "paper",919        "live"920      ],921      "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."922    },923    "agentId": {924      "description": "strategy operations only: the agent, when the version id alone does not name it",925      "type": "string",926      "format": "uuid",927      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"928    }929  },930  "required": [931    "mode"932  ],933  "additionalProperties": false934}935```936937### POST `/api/v1/trading/agents/{id}/pause`938939| Name | In | Required | Schema | Description |940|---|---|---|---|---|941| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |942943Request body (JSON):944945```json946{947  "type": "object",948  "properties": {949    "reason": {950      "default": "",951      "description": "why, for the agent's journal",952      "type": "string",953      "maxLength": 200954    }955  },956  "additionalProperties": false957}958```959960### POST `/api/v1/trading/agents/{id}/stop`961962| Name | In | Required | Schema | Description |963|---|---|---|---|---|964| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |965966Request body (JSON):967968```json969{970  "type": "object",971  "properties": {972    "reason": {973      "default": "",974      "description": "why, for the agent's journal",975      "type": "string",976      "maxLength": 200977    }978  },979  "additionalProperties": false980}981```982983### POST `/api/v1/trading/agents/{id}/backtest`984985| Name | In | Required | Schema | Description |986|---|---|---|---|---|987| `id` | path | yes | `{"type":"string","minLength":1,"maxLength":200}` | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) |988989Request body (JSON):990991```json992{993  "type": "object",994  "properties": {995    "versionId": {996      "description": "bar agents: the strategy version to backtest; default: the agent's current one",997      "type": "string",998      "format": "uuid",999      "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"1000    },1001    "hours": {1002      "description": "stream agents: how many hours of recorded snapshots to replay",1003      "type": "integer",1004      "minimum": 1,1005      "maximum": 1681006    }1007  },1008  "additionalProperties": false1009}1010```10111012## Errors10131014A 400 `bad_request` produced by input validation carries `data.fields`: one `{ path, code, message }` per refused member (what is expected, never the value that was sent).10151016Every error is `{ "error": "<code>", "message": "<sentence>" }`; a refusal about an order also carries `data` (`data.order`, `data.reasons`, `data.failed`, `data.checks`, `data.questions`).1017A path that is not an operation (or a known path with another method) answers 404 `not_found`.10181019The codes each operation can answer (the document's `x-spw-errors`). "open": the venue engine that executes the order can add a refusal code of its own rules.10201021### GET `/api/v1/trading/openapi.json`10221023| Status | Codes |1024|---|---|1025| 401 | `unauthenticated` |1026| 403 | `ip_not_allowed`, `mixed_credentials` |1027| 429 | `auth_throttled`, `rate_limited` |1028| 500 | `internal` |10291030### GET `/api/v1/trading/markets`10311032| Status | Codes |1033|---|---|1034| 400 | `bad_request` |1035| 401 | `unauthenticated` |1036| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1037| 404 | `unknown_venue` |1038| 429 | `auth_throttled`, `rate_limited` |1039| 500 | `internal` |1040| 503 | `markets_unavailable`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |10411042### GET `/api/v1/trading/markets/compare`10431044| Status | Codes |1045|---|---|1046| 400 | `bad_request` |1047| 401 | `unauthenticated` |1048| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1049| 404 | `unknown_underlying` |1050| 429 | `auth_throttled`, `rate_limited` |1051| 500 | `internal` |1052| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |10531054### GET `/api/v1/trading/markets/{symbol}`10551056| Status | Codes |1057|---|---|1058| 400 | `bad_request` |1059| 401 | `unauthenticated` |1060| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1061| 404 | `unknown_instrument`, `unknown_market`, `unknown_venue` |1062| 409 | `ambiguous_symbol` |1063| 422 | `venue_rejected` |1064| 429 | `auth_throttled`, `rate_limited` |1065| 500 | `internal` |1066| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |10671068### GET `/api/v1/trading/markets/{symbol}/orderbook`10691070| Status | Codes |1071|---|---|1072| 400 | `bad_request` |1073| 401 | `unauthenticated` |1074| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1075| 404 | `unknown_instrument`, `unknown_market`, `unknown_venue` |1076| 409 | `ambiguous_symbol` |1077| 422 | `no_orderbook`, `venue_rejected` |1078| 429 | `auth_throttled`, `rate_limited` |1079| 500 | `internal` |1080| 503 | `stale_data`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |10811082### GET `/api/v1/trading/markets/{symbol}/candles`10831084| Status | Codes |1085|---|---|1086| 400 | `bad_request` |1087| 401 | `unauthenticated` |1088| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1089| 404 | `unknown_instrument`, `unknown_market`, `unknown_venue` |1090| 409 | `ambiguous_symbol` |1091| 422 | `unsupported_interval`, `venue_rejected` |1092| 429 | `auth_throttled`, `rate_limited` |1093| 500 | `internal` |1094| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |10951096### GET `/api/v1/trading/private-markets`10971098| Status | Codes |1099|---|---|1100| 400 | `bad_request` |1101| 401 | `unauthenticated` |1102| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1103| 429 | `auth_throttled`, `rate_limited` |1104| 500 | `internal` |1105| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |11061107### GET `/api/v1/trading/private-markets/companies/{slug}`11081109| Status | Codes |1110|---|---|1111| 400 | `bad_request` |1112| 401 | `unauthenticated` |1113| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1114| 404 | `unknown_company` |1115| 429 | `auth_throttled`, `rate_limited` |1116| 500 | `internal` |1117| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |11181119### GET `/api/v1/trading/private-markets/{id}`11201121| Status | Codes |1122|---|---|1123| 400 | `bad_request` |1124| 401 | `unauthenticated` |1125| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1126| 404 | `not_a_private_market`, `unknown_private_market` |1127| 429 | `auth_throttled`, `rate_limited` |1128| 500 | `internal` |1129| 503 | `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |11301131### GET `/api/v1/trading/portfolio`11321133| Status | Codes |1134|---|---|1135| 401 | `unauthenticated` |1136| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1137| 429 | `auth_throttled`, `rate_limited` |1138| 500 | `internal` |1139| 503 | `service_unavailable`, `signer_unreachable` |11401141### GET `/api/v1/trading/balances`11421143| Status | Codes |1144|---|---|1145| 400 | `bad_request` |1146| 401 | `unauthenticated` |1147| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1148| 404 | `unknown_network` |1149| 429 | `auth_throttled`, `rate_limited` |1150| 500 | `internal` |1151| 503 | `service_unavailable`, `signer_unreachable` |11521153### GET `/api/v1/trading/activity`11541155| Status | Codes |1156|---|---|1157| 400 | `bad_request`, `invalid_cursor` |1158| 401 | `unauthenticated` |1159| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1160| 429 | `auth_throttled`, `rate_limited` |1161| 500 | `internal` |11621163### GET `/api/v1/trading/nfts`11641165| Status | Codes |1166|---|---|1167| 400 | `bad_request`, `invalid_cursor` |1168| 401 | `unauthenticated` |1169| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1170| 404 | `unknown_network`, `unknown_nft` |1171| 429 | `auth_throttled`, `rate_limited` |1172| 500 | `internal` |1173| 503 | `nft_disabled`, `signer_unreachable` |11741175### GET `/api/v1/trading/nfts/item`11761177| Status | Codes |1178|---|---|1179| 400 | `bad_request`, `invalid_cursor` |1180| 401 | `unauthenticated` |1181| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1182| 404 | `unknown_network`, `unknown_nft` |1183| 429 | `auth_throttled`, `rate_limited` |1184| 500 | `internal` |1185| 503 | `nft_disabled`, `signer_unreachable` |11861187### GET `/api/v1/trading/nfts/activity`11881189| Status | Codes |1190|---|---|1191| 400 | `bad_request`, `invalid_cursor`, `nft_bad_identifier` |1192| 401 | `unauthenticated` |1193| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1194| 404 | `nft_not_found`, `unknown_network`, `unknown_nft` |1195| 422 | `nft_unsupported_chain`, `nft_unsupported_standard` |1196| 429 | `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited` |1197| 500 | `internal` |1198| 502 | `nft_provider_bad_answer`, `nft_provider_disagreement` |1199| 503 | `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable` |12001201### GET `/api/v1/trading/nfts/market`12021203| Status | Codes |1204|---|---|1205| 400 | `bad_request`, `nft_bad_identifier` |1206| 401 | `unauthenticated` |1207| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1208| 404 | `nft_not_found`, `unknown_network` |1209| 422 | `nft_unsupported_chain`, `nft_unsupported_standard` |1210| 429 | `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited` |1211| 500 | `internal` |1212| 502 | `nft_provider_bad_answer`, `nft_provider_disagreement` |1213| 503 | `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable` |12141215### GET `/api/v1/trading/nfts/market/events`12161217| Status | Codes |1218|---|---|1219| 400 | `bad_request`, `nft_bad_identifier` |1220| 401 | `unauthenticated` |1221| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1222| 404 | `nft_not_found`, `unknown_network` |1223| 422 | `nft_unsupported_chain`, `nft_unsupported_standard` |1224| 429 | `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited` |1225| 500 | `internal` |1226| 502 | `nft_provider_bad_answer`, `nft_provider_disagreement` |1227| 503 | `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable` |12281229### GET `/api/v1/trading/positions`12301231| Status | Codes |1232|---|---|1233| 400 | `bad_request` |1234| 401 | `unauthenticated` |1235| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1236| 429 | `auth_throttled`, `rate_limited` |1237| 500 | `internal` |1238| 503 | `service_unavailable` |12391240### GET `/api/v1/trading/orders`12411242| Status | Codes |1243|---|---|1244| 400 | `bad_request`, `invalid_cursor` |1245| 401 | `unauthenticated` |1246| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1247| 429 | `auth_throttled`, `rate_limited` |1248| 500 | `internal` |12491250### GET `/api/v1/trading/orders/{id}`12511252| Status | Codes |1253|---|---|1254| 400 | `bad_request` |1255| 401 | `unauthenticated` |1256| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1257| 404 | `unknown_order` |1258| 429 | `auth_throttled`, `rate_limited` |1259| 500 | `internal` |12601261### GET `/api/v1/trading/strategies`12621263| Status | Codes |1264|---|---|1265| 400 | `bad_request` |1266| 401 | `unauthenticated` |1267| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1268| 429 | `auth_throttled`, `rate_limited` |1269| 500 | `internal` |12701271### GET `/api/v1/trading/agents`12721273| Status | Codes |1274|---|---|1275| 401 | `unauthenticated` |1276| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1277| 429 | `auth_throttled`, `rate_limited` |1278| 500 | `internal` |12791280### GET `/api/v1/trading/risk`12811282| Status | Codes |1283|---|---|1284| 401 | `unauthenticated` |1285| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1286| 429 | `auth_throttled`, `rate_limited` |1287| 500 | `internal` |12881289### POST `/api/v1/trading/orders/preview`12901291| Status | Codes |1292|---|---|1293| 400 | `bad_request`, `invalid_order` |1294| 401 | `unauthenticated` |1295| 403 | `insufficient_scope`, `ip_not_allowed`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted` |1296| 404 | `unknown_account`, `unknown_instrument`, `unknown_market`, `unknown_venue` |1297| 409 | `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_symbol` |1298| 422 | `below_min_size`, `fee_cap_not_expressible`, `gmx_leverage_required`, `inconsistent_prices`, `invalid_order`, `missing_balance`, `missing_reference_price`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `swap_not_enabled`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size` |1299| 429 | `auth_throttled`, `rate_limited` |1300| 500 | `internal` |1301| 501 | `execution_not_wired` |1302| 502 | `swap_flow_failed` |1303| 503 | `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |13041305### POST `/api/v1/trading/orders` (open)13061307| Status | Codes |1308|---|---|1309| 400 | `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request` |1310| 401 | `unauthenticated` |1311| 403 | `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted` |1312| 404 | `unknown_account`, `unknown_instrument`, `unknown_market`, `unknown_venue` |1313| 409 | `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_symbol`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1314| 422 | `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size` |1315| 423 | `halted`, `kill_switch_active`, `read_only_mode` |1316| 429 | `auth_throttled`, `rate_limited` |1317| 500 | `internal` |1318| 501 | `execution_not_wired` |1319| 502 | `swap_flow_failed` |1320| 503 | `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |13211322### DELETE `/api/v1/trading/orders/{id}`13231324| Status | Codes |1325|---|---|1326| 400 | `bad_request`, `idempotency`, `stale_request` |1327| 401 | `unauthenticated` |1328| 403 | `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `not_your_order`, `owner_session_required` |1329| 404 | `unknown_order` |1330| 409 | `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1331| 422 | `cancel_in_app`, `venue_rejected` |1332| 429 | `auth_throttled`, `rate_limited` |1333| 500 | `internal` |1334| 503 | `signer_unreachable`, `venue_unavailable` |13351336### POST `/api/v1/trading/positions/{id}/close` (open)13371338| Status | Codes |1339|---|---|1340| 400 | `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request` |1341| 401 | `unauthenticated` |1342| 403 | `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted` |1343| 404 | `unknown_account`, `unknown_instrument`, `unknown_position`, `unknown_venue` |1344| 409 | `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_position`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1345| 422 | `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `close_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size` |1346| 423 | `halted`, `kill_switch_active`, `read_only_mode` |1347| 429 | `auth_throttled`, `rate_limited` |1348| 500 | `internal` |1349| 501 | `execution_not_wired` |1350| 502 | `swap_flow_failed` |1351| 503 | `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |13521353### POST `/api/v1/trading/positions/{id}/reduce` (open)13541355| Status | Codes |1356|---|---|1357| 400 | `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request` |1358| 401 | `unauthenticated` |1359| 403 | `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted` |1360| 404 | `unknown_account`, `unknown_instrument`, `unknown_position`, `unknown_venue` |1361| 409 | `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_position`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1362| 422 | `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `close_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size` |1363| 423 | `halted`, `kill_switch_active`, `read_only_mode` |1364| 429 | `auth_throttled`, `rate_limited` |1365| 500 | `internal` |1366| 501 | `execution_not_wired` |1367| 502 | `swap_flow_failed` |1368| 503 | `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |13691370### POST `/api/v1/trading/commands` (open)13711372| Status | Codes |1373|---|---|1374| 400 | `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `parse_error`, `stale_request` |1375| 401 | `unauthenticated` |1376| 403 | `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `not_your_order`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted` |1377| 404 | `unknown_account`, `unknown_instrument`, `unknown_order`, `unknown_venue` |1378| 409 | `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1379| 422 | `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `cancel_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size` |1380| 423 | `halted`, `kill_switch_active`, `read_only_mode` |1381| 429 | `auth_throttled`, `rate_limited` |1382| 500 | `internal` |1383| 501 | `execution_not_wired` |1384| 502 | `swap_flow_failed` |1385| 503 | `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `service_unavailable`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable` |13861387### POST `/api/v1/trading/risk/kill-switch`13881389| Status | Codes |1390|---|---|1391| 400 | `bad_request` |1392| 401 | `unauthenticated` |1393| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1394| 429 | `auth_throttled`, `rate_limited` |1395| 500 | `internal` |13961397### POST `/api/v1/trading/strategies`13981399| Status | Codes |1400|---|---|1401| 400 | `bad_request`, `idempotency`, `stale_request` |1402| 401 | `unauthenticated` |1403| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1404| 404 | `not_found` |1405| 409 | `idempotency_conflict`, `idempotency_in_progress`, `wrong_kind` |1406| 422 | `bad_strategy` |1407| 429 | `auth_throttled`, `rate_limited` |1408| 500 | `internal` |14091410### POST `/api/v1/trading/strategies/{id}/backtest`14111412| Status | Codes |1413|---|---|1414| 400 | `bad_request`, `idempotency`, `stale_request` |1415| 401 | `unauthenticated` |1416| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1417| 404 | `not_found` |1418| 409 | `idempotency_conflict`, `idempotency_in_progress` |1419| 429 | `auth_throttled`, `rate_limited` |1420| 500 | `internal` |14211422### POST `/api/v1/trading/strategies/{id}/start`14231424| Status | Codes |1425|---|---|1426| 400 | `bad_request`, `idempotency`, `stale_request` |1427| 401 | `unauthenticated` |1428| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required`, `restricted` |1429| 404 | `not_found` |1430| 409 | `bad_report`, `bad_request`, `bad_state`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy`, `other_version` |1431| 429 | `auth_throttled`, `rate_limited` |1432| 500 | `internal` |14331434### POST `/api/v1/trading/strategies/{id}/stop`14351436| Status | Codes |1437|---|---|1438| 400 | `bad_request`, `idempotency`, `stale_request` |1439| 401 | `unauthenticated` |1440| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1441| 404 | `not_found` |1442| 409 | `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1443| 429 | `auth_throttled`, `rate_limited` |1444| 500 | `internal` |14451446### GET `/api/v1/trading/agents/templates`14471448| Status | Codes |1449|---|---|1450| 401 | `unauthenticated` |1451| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials` |1452| 429 | `auth_throttled`, `rate_limited` |1453| 500 | `internal` |14541455### GET `/api/v1/trading/agents/{id}`14561457| Status | Codes |1458|---|---|1459| 400 | `bad_request` |1460| 401 | `unauthenticated` |1461| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1462| 404 | `not_found` |1463| 429 | `auth_throttled`, `rate_limited` |1464| 500 | `internal` |14651466### GET `/api/v1/trading/agents/{id}/signals`14671468| Status | Codes |1469|---|---|1470| 400 | `bad_request` |1471| 401 | `unauthenticated` |1472| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1473| 404 | `not_found` |1474| 429 | `auth_throttled`, `rate_limited` |1475| 500 | `internal` |14761477### GET `/api/v1/trading/agents/{id}/journal`14781479| Status | Codes |1480|---|---|1481| 400 | `bad_request` |1482| 401 | `unauthenticated` |1483| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1484| 404 | `not_found` |1485| 429 | `auth_throttled`, `rate_limited` |1486| 500 | `internal` |14871488### GET `/api/v1/trading/agents/{id}/orders`14891490| Status | Codes |1491|---|---|1492| 400 | `bad_request` |1493| 401 | `unauthenticated` |1494| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1495| 404 | `not_found` |1496| 429 | `auth_throttled`, `rate_limited` |1497| 500 | `internal` |14981499### GET `/api/v1/trading/agents/{id}/performance`15001501| Status | Codes |1502|---|---|1503| 400 | `bad_request` |1504| 401 | `unauthenticated` |1505| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1506| 404 | `not_found` |1507| 429 | `auth_throttled`, `rate_limited` |1508| 500 | `internal` |15091510### GET `/api/v1/trading/jobs/{id}`15111512| Status | Codes |1513|---|---|1514| 400 | `bad_request` |1515| 401 | `unauthenticated` |1516| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1517| 404 | `not_found` |1518| 429 | `auth_throttled`, `rate_limited` |1519| 500 | `internal` |15201521### POST `/api/v1/trading/agents`15221523| Status | Codes |1524|---|---|1525| 400 | `bad_request`, `idempotency`, `stale_request` |1526| 401 | `unauthenticated` |1527| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required` |1528| 409 | `bad_report`, `bad_state`, `exists`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy`, `strategy_not_installed`, `wrong_kind` |1529| 422 | `bad_request`, `universe_mismatch` |1530| 429 | `auth_throttled`, `rate_limited` |1531| 500 | `internal` |15321533### POST `/api/v1/trading/agents/{id}/start`15341535| Status | Codes |1536|---|---|1537| 400 | `bad_request`, `idempotency`, `stale_request` |1538| 401 | `unauthenticated` |1539| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required`, `restricted` |1540| 404 | `not_found` |1541| 409 | `bad_report`, `bad_state`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy` |1542| 429 | `auth_throttled`, `rate_limited` |1543| 500 | `internal` |15441545### POST `/api/v1/trading/agents/{id}/pause`15461547| Status | Codes |1548|---|---|1549| 400 | `bad_request`, `idempotency`, `stale_request` |1550| 401 | `unauthenticated` |1551| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1552| 404 | `not_found` |1553| 409 | `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1554| 429 | `auth_throttled`, `rate_limited` |1555| 500 | `internal` |15561557### POST `/api/v1/trading/agents/{id}/stop`15581559| Status | Codes |1560|---|---|1561| 400 | `bad_request`, `idempotency`, `stale_request` |1562| 401 | `unauthenticated` |1563| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1564| 404 | `not_found` |1565| 409 | `bad_state`, `idempotency_conflict`, `idempotency_in_progress` |1566| 429 | `auth_throttled`, `rate_limited` |1567| 500 | `internal` |15681569### POST `/api/v1/trading/agents/{id}/backtest`15701571| Status | Codes |1572|---|---|1573| 400 | `bad_request`, `idempotency`, `stale_request` |1574| 401 | `unauthenticated` |1575| 403 | `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted` |1576| 404 | `not_found` |1577| 409 | `idempotency_conflict`, `idempotency_in_progress`, `no_strategy`, `wrong_kind` |1578| 429 | `auth_throttled`, `rate_limited` |1579| 500 | `internal` |15801581## Order states15821583| `status` | `final` |1584|---|---|1585| `CREATED` | no |1586| `VALIDATED` | no |1587| `AWAITING_APPROVAL` | no |1588| `APPROVED` | no |1589| `SUBMITTING` | no |1590| `SUBMITTED` | no |1591| `PARTIALLY_FILLED` | no |1592| `FILLED` | yes |1593| `CANCELLED` | yes |1594| `REJECTED` | yes |1595| `FAILED` | yes |1596| `UNKNOWN` | no |15971598`UNKNOWN`: the outcome at the venue is not known yet. It is not final and it is not a failure; the server resolves it by asking the venue.15991600## Refusal detail16011602`mandate_denied` — `data.reasons`: `INVALID_INPUT`, `MANDATE_NOT_YET_VALID`, `MANDATE_ENDED`, `MANDATE_REVOKED`, `WIND_DOWN_REDUCING_ONLY`, `PRINCIPAL_MISMATCH`, `MANDATE_ID_MISMATCH`, `MODE_MISMATCH`, `ACCOUNT_NOT_ALLOWED`, `VENUE_NOT_ALLOWED`, `NETWORK_NOT_ALLOWED`, `INSTRUMENT_NOT_ALLOWED`, `MARKET_KIND_NOT_ALLOWED`, `ORDER_TYPE_NOT_ALLOWED`, `NOTIONAL_UNKNOWN`, `ORDER_NOTIONAL_EXCEEDED`, `POSITION_NOTIONAL_EXCEEDED`, `CAPITAL_EXCEEDED`, `LEVERAGE_EXCEEDED`, `LEVERAGE_UNKNOWN`, `DAILY_LOSS_REACHED`, `BELOW_FLOOR_EQUITY`, `RATE_PER_MINUTE`, `RATE_PER_HOUR`, `RATE_PER_DAY`, `SLIPPAGE_ABOVE_MANDATE`, `FEE_ABOVE_MANDATE`, `ORDER_OUTLIVES_MANDATE`, `STOP_LOSS_GTE`, `STOP_DRAWDOWN_GTE`, `STOP_CONSECUTIVE_REJECTS_GTE`, `STOP_DATA_STALE_GTE`, `STOP_SIGNER_UNREACHABLE_GTE`.16031604`risk_denied`, `kill_switch_active`, `read_only_mode` — `data.failed` (ids of `data.checks`): `input_valid`, `read_only`, `kill_switch`, `reduce_only_valid`, `venue_allowed`, `instrument_allowed`, `instrument_status`, `signer_status`, `venue_connection`, `price_freshness`, `price_consistency`, `order_notional`, `daily_notional`, `order_rate_minute`, `order_rate_hour`, `order_rate_day`, `position_size`, `order_leverage`, `account_leverage`, `gross_exposure`, `net_exposure`, `asset_exposure`, `venue_exposure`, `collateral_concentration`, `daily_loss`, `total_loss`, `drawdown`, `liquidation_distance`, `slippage`, `min_liquidity`, `context_complete`.16051606## Webhook events16071608| Event | Emitted in this version | Payload (`data`) | Description |1609|---|---|---|---|1610| `key.revoked` | yes | `{ keyId, name, reason }` | an API key was revoked (or replaced by a rotation) |1611| `risk.kill_switch` | yes | `{ source: "signer", halted: true } | { source: "risk_engine", engaged, by, reason }` | the emergency halt of the signer was triggered (source "signer"), or the global kill switch of the risk engine was engaged or released (source "risk_engine") |1612| `agent.updated` | yes | `{ agentId, kind, state, mode }` | an agent was started, paused or stopped (by the owner, an API key or the risk-management agent) |1613| `risk.proposal` | yes | `{ supervisorId, agentId, mode, action, code, acted, message, metrics }` | the risk-management agent proposes a reduction or a pause, or acted (paused an agent, engaged the kill switch) |1614| `order.updated` | yes | `{ orderId, mode, venue, instrument, status, previous, event, reason, seq, principal, mandateId }` | an order changed state: one event per transition of the unified order state machine, for every principal, mode and venue |1615
Files main
Menu

Theme