Repository Public
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