# SP Trading API v1 — reference
Generated by node scripts/gen-openapi.mts from services/api/src/trading-api/spec.ts. Do not edit by hand:
a test compares this file and docs/openapi/trading-v1.json with what the code generates.
Version 1.0.0. Machine-readable document: docs/openapi/trading-v1.json, also served at GET /api/v1/trading/openapi.json.
This file is the compact index (operations, raw JSON Schemas, error codes). The reference with getting started, concepts, a worked example per operation
and what each error means is TRADING-API-REFERENCE.md, served at GET /api/v1/trading/docs.
# Authentication
Authorization: Bearer spw_live_<key id>_<secret>. No cookie, no CSRF header. The key is refused on every path outside
/api/v1/trading/.
# Streaming
Live market data (quotes, order books, trades, candles, venue statuses) is also served over a websocket, which the OpenAPI document cannot describe:
GET /api/v1/trading/stream — scope markets:read; the key in the Authorization header of the handshake, or ?ticket= with a single-use ticket
from POST /api/v1/trading/stream/ticket (the way of a browser, which cannot set a header on a websocket). Protocol: V11-QUOTE-ENGINE.md; clients:
SPWalletStream in both SDKs.
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 is
logged like any other.
# Scopes
| 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) |
wallet:read |
no |
markets:read |
no |
orders:read |
no |
orders:prepare |
no |
orders:execute |
yes |
orders:cancel |
yes |
positions:read |
no |
positions:manage |
yes |
strategies:read |
no |
strategies:manage |
no |
agents:read |
no |
agents:manage |
no |
# Operations
| Method |
Path |
Scope |
State |
Idempotency-Key |
Summary |
| GET |
/api/v1/trading/openapi.json |
any valid key |
implemented |
— |
This document |
| GET |
/api/v1/trading/markets |
markets:read |
implemented |
— |
Instruments across venues (perpetuals) and the spot market-data symbols |
| GET |
/api/v1/trading/markets/compare |
markets:read |
implemented |
— |
Compare the estimated cost of one position across venues |
| GET |
/api/v1/trading/markets/{symbol} |
markets:read |
implemented |
— |
One market: instrument, ticker and data quality |
| GET |
/api/v1/trading/markets/{symbol}/orderbook |
markets:read |
implemented |
— |
Order book of one market |
| GET |
/api/v1/trading/markets/{symbol}/candles |
markets:read |
implemented |
— |
Closed bars of one market |
| GET |
/api/v1/trading/private-markets |
markets:read |
implemented |
— |
Synthetic contracts on private companies, venue by venue, with sourced valuations |
| GET |
/api/v1/trading/private-markets/companies/{slug} |
markets:read |
implemented |
— |
Every contract on one private company, side by side (never merged) |
| GET |
/api/v1/trading/private-markets/{id} |
markets:read |
implemented |
— |
One private-company contract: definition, valuation breakdown, candles, top of book |
| GET |
/api/v1/trading/portfolio |
wallet:read |
implemented |
— |
Wallet value and derivative accounts, per mode |
| GET |
/api/v1/trading/balances |
wallet:read |
implemented |
— |
On-chain balances of the wallet |
| GET |
/api/v1/trading/activity |
wallet:read |
implemented |
— |
Wallet activity and fills, newest first |
| GET |
/api/v1/trading/nfts |
wallet:read |
implemented |
— |
NFTs of the wallet (what the chain confirmed as held) |
| GET |
/api/v1/trading/nfts/item |
wallet:read |
implemented |
— |
One NFT of the wallet: identity, ownership, creator metadata, sources |
| GET |
/api/v1/trading/nfts/activity |
wallet:read |
implemented |
— |
On-chain events of one NFT of the wallet |
| GET |
/api/v1/trading/nfts/market |
markets:read |
implemented |
— |
Market data of any NFT, one row per source |
| GET |
/api/v1/trading/nfts/market/events |
markets:read |
implemented |
— |
Market events of any NFT (sales, listings, offers), per source |
| GET |
/api/v1/trading/positions |
positions:read |
implemented |
— |
Open positions, paper and live separated by mode |
| GET |
/api/v1/trading/orders |
orders:read |
implemented |
— |
Orders, newest first |
| GET |
/api/v1/trading/orders/{id} |
orders:read |
implemented |
— |
One order and its fills |
| GET |
/api/v1/trading/strategies |
strategies:read |
implemented |
— |
Strategy library and the versions pinned to agents |
| GET |
/api/v1/trading/agents |
agents:read |
implemented |
— |
Trading agents |
| GET |
/api/v1/trading/risk |
positions:read |
implemented |
— |
Risk state: kill switch, signer limits, capability locks, account policies |
| POST |
/api/v1/trading/orders/preview |
orders:prepare |
implemented |
— |
Preview an order: every check it would meet, and an estimate |
| POST |
/api/v1/trading/orders |
orders:execute |
implemented |
required |
Place an order |
| DELETE |
/api/v1/trading/orders/{id} |
orders:cancel |
implemented |
required |
Cancel an order |
| POST |
/api/v1/trading/positions/{id}/close |
positions:manage |
implemented |
required |
Close a position |
| POST |
/api/v1/trading/positions/{id}/reduce |
positions:manage |
implemented |
required |
Reduce a position |
| POST |
/api/v1/trading/commands |
orders:prepare |
implemented |
required |
Run one line of the trading command grammar |
| POST |
/api/v1/trading/risk/kill-switch |
positions:manage |
implemented |
— |
Engage the global kill switch |
| POST |
/api/v1/trading/strategies |
strategies:manage |
implemented |
required |
Register a library strategy version on an agent |
| POST |
/api/v1/trading/strategies/{id}/backtest |
strategies:manage |
implemented |
required |
Run the backtest of a strategy version (asynchronous job) |
| POST |
/api/v1/trading/strategies/{id}/start |
strategies:manage |
implemented |
required |
Start the agent a strategy version is pinned to |
| POST |
/api/v1/trading/strategies/{id}/stop |
strategies:manage |
implemented |
required |
Stop the agent a strategy version is pinned to |
| GET |
/api/v1/trading/agents/templates |
agents:read |
implemented |
— |
The seven built-in agents: family, engine, modes, installed strategies |
| GET |
/api/v1/trading/agents/{id} |
agents:read |
implemented |
— |
One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state |
| GET |
/api/v1/trading/agents/{id}/signals |
agents:read |
implemented |
— |
Signal history of one agent, ONE mode |
| GET |
/api/v1/trading/agents/{id}/journal |
agents:read |
implemented |
— |
Activity journal of one agent, ONE mode |
| GET |
/api/v1/trading/agents/{id}/orders |
agents:read |
implemented |
— |
Order history of one agent, ONE mode, in the unified order states |
| GET |
/api/v1/trading/agents/{id}/performance |
agents:read |
implemented |
— |
Computed performance of one agent, ONE mode |
| GET |
/api/v1/trading/jobs/{id} |
agents:read |
implemented |
— |
One agent job (backtest, wind-down): status and result |
| POST |
/api/v1/trading/agents |
agents:manage |
implemented |
required |
Create an agent (from a template, or a perp agent) |
| POST |
/api/v1/trading/agents/{id}/start |
agents:manage |
implemented |
required |
Start an agent in research, paper or live mode |
| POST |
/api/v1/trading/agents/{id}/pause |
agents:manage |
implemented |
required |
Pause an agent |
| POST |
/api/v1/trading/agents/{id}/stop |
agents:manage |
implemented |
required |
Stop an agent (always allowed) |
| POST |
/api/v1/trading/agents/{id}/backtest |
agents:manage |
implemented |
required |
Run a backtest for an agent (asynchronous job) |
# Parameters
# GET /api/v1/trading/markets
| Name |
In |
Required |
Schema |
Description |
venue |
query |
no |
{"type":"string","maxLength":40} |
venue id: hyperliquid, gmx, dydx, spot |
kind |
query |
no |
{"type":"string","enum":["perpetual","spot"]} |
perpetual = a venue instrument; spot = a market-data symbol |
q |
query |
no |
{"type":"string","maxLength":40} |
case-insensitive match on id, symbol or base |
limit |
query |
no |
{"default":2000,"type":"integer","minimum":1,"maximum":5000} |
rows returned at most; total and truncated say when it cut the list |
# GET /api/v1/trading/markets/compare
| Name |
In |
Required |
Schema |
Description |
underlying |
query |
no |
{"default":"BTC","type":"string","pattern":"^[A-Za-z0-9]{1,15}$"} |
common underlying, e.g. BTC (see GET /markets-hub/underlyings) |
side |
query |
no |
{"default":"long","type":"string","enum":["long","short"]} |
direction of the position compared |
notional |
query |
no |
`{"default":"1000","type":"string","pattern":"^(0 |
[1-9]\d{0,11})(\.\d{1,8})?$"}` |
leverage |
query |
no |
`{"default":"1","type":"string","pattern":"^(0 |
[1-9]\d{0,11})(\.\d{1,8})?$"}` |
horizonHours |
query |
no |
`{"default":"24","type":"string","pattern":"^(0 |
[1-9]\d{0,3})(\.\d{1,4})?$"}` |
liquidity |
query |
no |
{"default":"taker","type":"string","enum":["taker","maker"]} |
how the entry and the exit are executed, for the fee |
minNetEdgeBps |
query |
no |
`{"default":"0","type":"string","pattern":"^(0 |
[1-9]\d{0,4})(\.\d{1,4})?$"}` |
# GET /api/v1/trading/markets/{symbol}
| Name |
In |
Required |
Schema |
Description |
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 |
# GET /api/v1/trading/markets/{symbol}/orderbook
| Name |
In |
Required |
Schema |
Description |
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 |
depth |
query |
no |
{"default":20,"type":"integer","minimum":1,"maximum":50} |
price levels per side |
# GET /api/v1/trading/markets/{symbol}/candles
| Name |
In |
Required |
Schema |
Description |
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 |
interval |
query |
no |
{"default":"1h","type":"string","enum":["1m","5m","15m","1h","4h","1d"]} |
bar length |
limit |
query |
no |
{"default":200,"type":"integer","minimum":1,"maximum":1000} |
most recent closed bars, oldest first in the answer |
# GET /api/v1/trading/private-markets
| Name |
In |
Required |
Schema |
Description |
delisted |
query |
no |
{"type":"string","enum":["true","false"]} |
true: only delisted markets (frozen prices) |
size |
query |
no |
`{"type":"string","pattern":"^(0 |
[1-9]\d{0,11})(\.\d{1,8})?$"}` |
side |
query |
no |
{"type":"string","enum":["long","short"]} |
side of the hypothetical position (default long) |
# GET /api/v1/trading/private-markets/companies/{slug}
| Name |
In |
Required |
Schema |
Description |
slug |
path |
yes |
{"type":"string","pattern":"^[a-z0-9-]{1,40}$"} |
company slug, from GET /private-markets (companies[].slug), e.g. anthropic |
size |
query |
no |
`{"type":"string","pattern":"^(0 |
[1-9]\d{0,11})(\.\d{1,8})?$"}` |
side |
query |
no |
{"type":"string","enum":["long","short"]} |
side of the hypothetical position (default long) |
interval |
query |
no |
{"type":"string","enum":["1h","1d"]} |
candle length |
limit |
query |
no |
{"type":"integer","minimum":1,"maximum":500} |
candles returned at most |
# GET /api/v1/trading/private-markets/{id}
| Name |
In |
Required |
Schema |
Description |
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 |
size |
query |
no |
`{"type":"string","pattern":"^(0 |
[1-9]\d{0,11})(\.\d{1,8})?$"}` |
side |
query |
no |
{"type":"string","enum":["long","short"]} |
side of the hypothetical position (default long) |
interval |
query |
no |
{"type":"string","enum":["1h","1d"]} |
candle length |
limit |
query |
no |
{"type":"integer","minimum":1,"maximum":500} |
candles returned at most |
# GET /api/v1/trading/balances
| Name |
In |
Required |
Schema |
Description |
network |
query |
no |
{"type":"string","maxLength":24} |
one network id (e.g. base, arbitrum, solana); default: every network of the wallet |
# GET /api/v1/trading/activity
| Name |
In |
Required |
Schema |
Description |
limit |
query |
no |
{"default":100,"type":"integer","minimum":1,"maximum":500} |
rows returned at most |
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 |
# GET /api/v1/trading/nfts
| Name |
In |
Required |
Schema |
Description |
network |
query |
no |
{"type":"string","maxLength":24} |
one network id; default: all |
collection |
query |
no |
{"type":"string","maxLength":260} |
collection key |
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 |
q |
query |
no |
{"type":"string","maxLength":80} |
case-insensitive text matched on the name, the key or the collection name |
sort |
query |
no |
{"default":"recent","type":"string","enum":["recent","name"]} |
order of the list |
spam |
query |
no |
{"default":"hide","type":"string","enum":["hide","show","only"]} |
items an indexer flags as spam are hidden by default, never deleted |
limit |
query |
no |
{"default":48,"type":"integer","minimum":1,"maximum":100} |
rows returned at most |
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 |
# GET /api/v1/trading/nfts/item
| Name |
In |
Required |
Schema |
Description |
key |
query |
yes |
{"type":"string","minLength":5,"maxLength":260} |
family:network:asset-id, as returned by GET /nfts |
# GET /api/v1/trading/nfts/activity
| Name |
In |
Required |
Schema |
Description |
key |
query |
yes |
{"type":"string","minLength":5,"maxLength":260} |
family:network:asset-id, as returned by GET /nfts |
limit |
query |
no |
{"default":20,"type":"integer","minimum":1,"maximum":50} |
rows returned at most |
cursor |
query |
no |
{"type":"string","maxLength":400} |
nextCursor of the previous page |
type |
query |
no |
{"type":"string","enum":["mint","transfer","transfer-in","transfer-out","burn","sale","unknown"]} |
only events of this type |
# GET /api/v1/trading/nfts/market
| Name |
In |
Required |
Schema |
Description |
network |
query |
yes |
{"type":"string","maxLength":24} |
network id, e.g. ethereum, base, solana |
address |
query |
yes |
{"type":"string","minLength":26,"maxLength":64} |
EVM: the contract; Solana: the mint / asset address |
tokenId |
query |
no |
{"type":"string","maxLength":80} |
EVM: required, decimal or 0x-hex |
# GET /api/v1/trading/nfts/market/events
| Name |
In |
Required |
Schema |
Description |
network |
query |
yes |
{"type":"string","maxLength":24} |
network id, e.g. ethereum, base, solana |
address |
query |
yes |
{"type":"string","minLength":26,"maxLength":64} |
EVM: the contract; Solana: the mint / asset address |
tokenId |
query |
no |
{"type":"string","maxLength":80} |
EVM: required, decimal or 0x-hex |
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 |
type |
query |
no |
{"type":"string","maxLength":120,"pattern":"^[a-z,-]+$"} |
comma-separated: sale, list, delist, offer, cancel-offer, transfer, mint |
after |
query |
no |
`{"type":"string","format":"date-time","pattern":"^(?😦?:\d\d[2468][048] |
\d\d[13579][26] |
before |
query |
no |
`{"type":"string","format":"date-time","pattern":"^(?😦?:\d\d[2468][048] |
\d\d[13579][26] |
cursor |
query |
no |
{"type":"string","maxLength":600} |
a position in ONE source's list: send it with provider |
limit |
query |
no |
{"default":20,"type":"integer","minimum":1,"maximum":50} |
rows returned at most |
# GET /api/v1/trading/positions
| Name |
In |
Required |
Schema |
Description |
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. |
venue |
query |
no |
{"type":"string","maxLength":40} |
venue id: hyperliquid, gmx, dydx, spot |
# GET /api/v1/trading/orders
| Name |
In |
Required |
Schema |
Description |
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. |
venue |
query |
no |
{"type":"string","maxLength":40} |
venue id: hyperliquid, gmx, dydx, spot |
open |
query |
no |
{"type":"string","enum":["true","false"]} |
true: only orders that are not final; false: only final orders |
limit |
query |
no |
{"default":100,"type":"integer","minimum":1,"maximum":500} |
rows returned at most |
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 |
# GET /api/v1/trading/orders/{id}
| Name |
In |
Required |
Schema |
Description |
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) |
# GET /api/v1/trading/strategies
| Name |
In |
Required |
Schema |
Description |
kind |
query |
no |
{"type":"string","enum":["spot","perp"]} |
only spot or only perp strategies |
# POST /api/v1/trading/orders/preview
Request body (JSON):
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"paper",
"live"
],
"description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."
},
"accountId": {
"description": "paper account or venue account; required when the wallet has several on the venue",
"type": "string",
"format": "uuid",
"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)$"
},
"instrument": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
],
"description": "buy opens or adds to a long (or reduces a short); sell the reverse"
},
"type": {
"type": "string",
"enum": [
"limit",
"market",
"stop_market",
"stop_limit",
"take_profit_market",
"take_profit_limit"
],
"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`"
},
"size": {
"description": "quantity of the base asset. Exactly one of `size` and `notional` is required",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"notional": {
"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",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"price": {
"description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"triggerPrice": {
"description": "price at which a stop or take-profit order is triggered; required by the four trigger types",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"reduceOnly": {
"default": false,
"description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",
"type": "boolean"
},
"tif": {
"default": "gtc",
"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)",
"type": "string",
"enum": [
"gtc",
"ioc",
"alo"
]
},
"slippageBps": {
"description": "market orders: the worst acceptable price, in basis points from the reference price",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"leverage": {
"description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"maxFeeUsd": {
"description": "highest fee accepted, USD; default: 10 bps of the notional",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"clientOrderId": {
"description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,100}$"
}
},
"required": [
"mode",
"instrument",
"side",
"type"
],
"additionalProperties": false
}
# POST /api/v1/trading/orders
Request body (JSON):
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"paper",
"live"
],
"description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."
},
"accountId": {
"description": "paper account or venue account; required when the wallet has several on the venue",
"type": "string",
"format": "uuid",
"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)$"
},
"instrument": {
"type": "string",
"minLength": 1,
"maxLength": 120,
"description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"
},
"side": {
"type": "string",
"enum": [
"buy",
"sell"
],
"description": "buy opens or adds to a long (or reduces a short); sell the reverse"
},
"type": {
"type": "string",
"enum": [
"limit",
"market",
"stop_market",
"stop_limit",
"take_profit_market",
"take_profit_limit"
],
"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`"
},
"size": {
"description": "quantity of the base asset. Exactly one of `size` and `notional` is required",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"notional": {
"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",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"price": {
"description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"triggerPrice": {
"description": "price at which a stop or take-profit order is triggered; required by the four trigger types",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"reduceOnly": {
"default": false,
"description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",
"type": "boolean"
},
"tif": {
"default": "gtc",
"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)",
"type": "string",
"enum": [
"gtc",
"ioc",
"alo"
]
},
"slippageBps": {
"description": "market orders: the worst acceptable price, in basis points from the reference price",
"type": "integer",
"minimum": 1,
"maximum": 500
},
"leverage": {
"description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"maxFeeUsd": {
"description": "highest fee accepted, USD; default: 10 bps of the notional",
"type": "string",
"pattern": "^\\d+(\\.\\d+)?$"
},
"clientOrderId": {
"description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",
"type": "string",
"pattern": "^[A-Za-z0-9._:-]{8,100}$"
}
},
"required": [
"mode",
"instrument",
"side",
"type"
],
"additionalProperties": false
}
# DELETE /api/v1/trading/orders/{id}
| Name |
In |
Required |
Schema |
Description |
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) |
# POST /api/v1/trading/positions/{id}/close
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"slippageBps": {
"description": "worst acceptable price of the closing market order, in basis points from the reference price",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"additionalProperties": false
}
# POST /api/v1/trading/positions/{id}/reduce
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"fraction": {
"type": "string",
"pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",
"description": "share of the position to close, in (0, 1]"
},
"slippageBps": {
"description": "worst acceptable price of the reducing market order, in basis points from the reference price",
"type": "integer",
"minimum": 1,
"maximum": 500
}
},
"required": [
"fraction"
],
"additionalProperties": false
}
# POST /api/v1/trading/commands
Request body (JSON):
{
"type": "object",
"properties": {
"text": {
"type": "string",
"minLength": 1,
"maxLength": 300,
"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 …"
},
"mode": {
"default": "paper",
"type": "string",
"enum": [
"paper",
"live"
],
"description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."
},
"accountId": {
"description": "paper account or venue account; required when the wallet has several on the venue",
"type": "string",
"format": "uuid",
"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)$"
},
"dryRun": {
"default": false,
"description": "true: answer the canonical order (or the control) the command resolves to, and do nothing",
"type": "boolean"
}
},
"required": [
"text"
],
"additionalProperties": false
}
# POST /api/v1/trading/risk/kill-switch
Request body (JSON):
{
"type": "object",
"properties": {
"reason": {
"default": "",
"description": "why, for the audit trail and the `risk.kill_switch` webhook",
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
# POST /api/v1/trading/strategies
Request body (JSON):
{
"type": "object",
"properties": {
"kind": {
"type": "string",
"enum": [
"spot",
"perp"
],
"description": "must be the kind of the agent (409 `wrong_kind` otherwise)"
},
"path": {
"type": "string",
"minLength": 1,
"maxLength": 200,
"description": "library path of the strategy, from GET /strategies (`library[].path`)"
},
"agentId": {
"description": "the agent the version is registered on; required in practice (400 without it)",
"type": "string",
"format": "uuid",
"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)$"
}
},
"required": [
"kind",
"path"
],
"additionalProperties": false
}
# POST /api/v1/trading/strategies/{id}/backtest
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"symbols": {
"description": "default: the agent's universe",
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,15}$"
}
},
"interval": {
"description": "bar interval; default: the agent's",
"type": "string",
"enum": [
"1h",
"1d"
]
}
},
"additionalProperties": false
}
# POST /api/v1/trading/strategies/{id}/start
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"research",
"paper",
"live"
],
"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."
},
"agentId": {
"description": "strategy operations only: the agent, when the version id alone does not name it",
"type": "string",
"format": "uuid",
"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)$"
}
},
"required": [
"mode"
],
"additionalProperties": false
}
# POST /api/v1/trading/strategies/{id}/stop
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"reason": {
"default": "",
"description": "why, for the agent's journal",
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
# GET /api/v1/trading/agents/{id}
| Name |
In |
Required |
Schema |
Description |
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) |
# GET /api/v1/trading/agents/{id}/signals
| Name |
In |
Required |
Schema |
Description |
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) |
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. |
limit |
query |
no |
{"default":100,"type":"integer","minimum":1,"maximum":500} |
rows returned at most |
before |
query |
no |
{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991} |
unix ms: rows strictly before it |
# GET /api/v1/trading/agents/{id}/journal
| Name |
In |
Required |
Schema |
Description |
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) |
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. |
limit |
query |
no |
{"default":100,"type":"integer","minimum":1,"maximum":500} |
rows returned at most |
before |
query |
no |
{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991} |
unix ms: rows strictly before it |
# GET /api/v1/trading/agents/{id}/orders
| Name |
In |
Required |
Schema |
Description |
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) |
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. |
limit |
query |
no |
{"default":100,"type":"integer","minimum":1,"maximum":500} |
rows returned at most |
before |
query |
no |
{"type":"integer","exclusiveMinimum":0,"maximum":9007199254740991} |
unix ms: rows strictly before it |
open |
query |
no |
{"type":"string","enum":["true","false"]} |
true: only the orders that are not final |
| Name |
In |
Required |
Schema |
Description |
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) |
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. |
# GET /api/v1/trading/jobs/{id}
| Name |
In |
Required |
Schema |
Description |
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) |
# POST /api/v1/trading/agents
Request body (JSON):
{
"type": "object",
"properties": {
"kind": {
"description": "without a template: perp (a spot agent needs a vault from the signer: owner only)",
"type": "string",
"enum": [
"spot",
"perp"
]
},
"template": {
"description": "one of GET /agents/templates",
"type": "string",
"maxLength": 40
},
"name": {
"type": "string",
"minLength": 2,
"maxLength": 40,
"description": "shown in the app and in the lists"
},
"mission": {
"default": "",
"description": "free text for people; it changes nothing the agent does",
"type": "string",
"maxLength": 400
},
"universe": {
"description": "asset symbols the agent trades, e.g. [\"BTC\"]; a fixed-universe strategy needs its exact universe (422 `universe_mismatch`); default: the template's",
"minItems": 1,
"maxItems": 12,
"type": "array",
"items": {
"type": "string",
"pattern": "^[A-Z0-9]{2,15}$"
}
},
"venues": {
"description": "venues the agent reads; default: the template's",
"minItems": 1,
"maxItems": 2,
"type": "array",
"items": {
"type": "string",
"enum": [
"hyperliquid",
"edgex",
"dydx",
"gmx"
]
}
},
"strategyPath": {
"description": "bar templates: which of the template's installed strategies to bind, from GET /agents/templates",
"type": "string",
"maxLength": 60
},
"interval": {
"description": "bar agents: bar length; default 1h",
"type": "string",
"enum": [
"1h",
"4h",
"1d"
]
},
"capitalUsdc": {
"description": "simulated capital of the agent, a decimal string; default 1000",
"type": "string",
"pattern": "^\\d{1,7}(\\.\\d{1,6})?$"
},
"risk": {
"description": "overrides of the agent's own risk limits, by name (the limits in force are in GET /agents/{id}: `riskLimits`)",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {
"type": [
"number",
"string",
"boolean"
]
}
},
"config": {
"description": "overrides of the template's parameters, by name",
"type": "object",
"propertyNames": {
"type": "string"
},
"additionalProperties": {}
},
"mode": {
"default": "research",
"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.",
"type": "string",
"enum": [
"research",
"paper"
]
}
},
"required": [
"name"
],
"additionalProperties": false
}
# POST /api/v1/trading/agents/{id}/start
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"research",
"paper",
"live"
],
"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."
},
"agentId": {
"description": "strategy operations only: the agent, when the version id alone does not name it",
"type": "string",
"format": "uuid",
"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)$"
}
},
"required": [
"mode"
],
"additionalProperties": false
}
# POST /api/v1/trading/agents/{id}/pause
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"reason": {
"default": "",
"description": "why, for the agent's journal",
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
# POST /api/v1/trading/agents/{id}/stop
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"reason": {
"default": "",
"description": "why, for the agent's journal",
"type": "string",
"maxLength": 200
}
},
"additionalProperties": false
}
# POST /api/v1/trading/agents/{id}/backtest
| Name |
In |
Required |
Schema |
Description |
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) |
Request body (JSON):
{
"type": "object",
"properties": {
"versionId": {
"description": "bar agents: the strategy version to backtest; default: the agent's current one",
"type": "string",
"format": "uuid",
"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)$"
},
"hours": {
"description": "stream agents: how many hours of recorded snapshots to replay",
"type": "integer",
"minimum": 1,
"maximum": 168
}
},
"additionalProperties": false
}
# Errors
A 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).
Every error is { "error": "<code>", "message": "<sentence>" }; a refusal about an order also carries data (data.order, data.reasons, data.failed, data.checks, data.questions).
A path that is not an operation (or a known path with another method) answers 404 not_found.
The 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.
# GET /api/v1/trading/openapi.json
| Status |
Codes |
| 401 |
unauthenticated |
| 403 |
ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/markets
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_venue |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
markets_unavailable, venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/markets/compare
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_underlying |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/markets/{symbol}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_instrument, unknown_market, unknown_venue |
| 409 |
ambiguous_symbol |
| 422 |
venue_rejected |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/markets/{symbol}/orderbook
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_instrument, unknown_market, unknown_venue |
| 409 |
ambiguous_symbol |
| 422 |
no_orderbook, venue_rejected |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
stale_data, venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/markets/{symbol}/candles
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_instrument, unknown_market, unknown_venue |
| 409 |
ambiguous_symbol |
| 422 |
unsupported_interval, venue_rejected |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/private-markets
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/private-markets/companies/{slug}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 404 |
unknown_company |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/private-markets/{id}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_a_private_market, unknown_private_market |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
venue_rate_limited, venue_timeout, venue_unavailable |
# GET /api/v1/trading/portfolio
| Status |
Codes |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
service_unavailable, signer_unreachable |
# GET /api/v1/trading/balances
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_network |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
service_unavailable, signer_unreachable |
# GET /api/v1/trading/activity
| Status |
Codes |
| 400 |
bad_request, invalid_cursor |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/nfts
| Status |
Codes |
| 400 |
bad_request, invalid_cursor |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_network, unknown_nft |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
nft_disabled, signer_unreachable |
# GET /api/v1/trading/nfts/item
| Status |
Codes |
| 400 |
bad_request, invalid_cursor |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_network, unknown_nft |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
nft_disabled, signer_unreachable |
# GET /api/v1/trading/nfts/activity
| Status |
Codes |
| 400 |
bad_request, invalid_cursor, nft_bad_identifier |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
nft_not_found, unknown_network, unknown_nft |
| 422 |
nft_unsupported_chain, nft_unsupported_standard |
| 429 |
auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited |
| 500 |
internal |
| 502 |
nft_provider_bad_answer, nft_provider_disagreement |
| 503 |
nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable |
# GET /api/v1/trading/nfts/market
| Status |
Codes |
| 400 |
bad_request, nft_bad_identifier |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
nft_not_found, unknown_network |
| 422 |
nft_unsupported_chain, nft_unsupported_standard |
| 429 |
auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited |
| 500 |
internal |
| 502 |
nft_provider_bad_answer, nft_provider_disagreement |
| 503 |
nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable |
# GET /api/v1/trading/nfts/market/events
| Status |
Codes |
| 400 |
bad_request, nft_bad_identifier |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
nft_not_found, unknown_network |
| 422 |
nft_unsupported_chain, nft_unsupported_standard |
| 429 |
auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited |
| 500 |
internal |
| 502 |
nft_provider_bad_answer, nft_provider_disagreement |
| 503 |
nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable |
# GET /api/v1/trading/positions
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
service_unavailable |
# GET /api/v1/trading/orders
| Status |
Codes |
| 400 |
bad_request, invalid_cursor |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/orders/{id}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
unknown_order |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/strategies
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents
| Status |
Codes |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/risk
| Status |
Codes |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/orders/preview
| Status |
Codes |
| 400 |
bad_request, invalid_order |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mandate_required, mixed_credentials, owner_session_required, restricted, spot_execution_requires_agent_vault, venue_restricted |
| 404 |
unknown_account, unknown_instrument, unknown_market, unknown_venue |
| 409 |
account_required, ambiguous_command, ambiguous_order, ambiguous_symbol |
| 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 |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 501 |
execution_not_wired |
| 502 |
swap_flow_failed |
| 503 |
stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable |
# POST /api/v1/trading/orders (open)
| Status |
Codes |
| 400 |
bad_policy, bad_request, idempotency, invalid_order, stale_request |
| 401 |
unauthenticated |
| 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 |
| 404 |
unknown_account, unknown_instrument, unknown_market, unknown_venue |
| 409 |
account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_symbol, bad_state, idempotency_conflict, idempotency_in_progress |
| 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 |
| 423 |
halted, kill_switch_active, read_only_mode |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 501 |
execution_not_wired |
| 502 |
swap_flow_failed |
| 503 |
authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable |
# DELETE /api/v1/trading/orders/{id}
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, mixed_credentials, not_your_order, owner_session_required |
| 404 |
unknown_order |
| 409 |
bad_state, idempotency_conflict, idempotency_in_progress |
| 422 |
cancel_in_app, venue_rejected |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 503 |
signer_unreachable, venue_unavailable |
# POST /api/v1/trading/positions/{id}/close (open)
| Status |
Codes |
| 400 |
bad_policy, bad_request, idempotency, invalid_order, stale_request |
| 401 |
unauthenticated |
| 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 |
| 404 |
unknown_account, unknown_instrument, unknown_position, unknown_venue |
| 409 |
account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_position, bad_state, idempotency_conflict, idempotency_in_progress |
| 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 |
| 423 |
halted, kill_switch_active, read_only_mode |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 501 |
execution_not_wired |
| 502 |
swap_flow_failed |
| 503 |
authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable |
# POST /api/v1/trading/positions/{id}/reduce (open)
| Status |
Codes |
| 400 |
bad_policy, bad_request, idempotency, invalid_order, stale_request |
| 401 |
unauthenticated |
| 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 |
| 404 |
unknown_account, unknown_instrument, unknown_position, unknown_venue |
| 409 |
account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_position, bad_state, idempotency_conflict, idempotency_in_progress |
| 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 |
| 423 |
halted, kill_switch_active, read_only_mode |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 501 |
execution_not_wired |
| 502 |
swap_flow_failed |
| 503 |
authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable |
# POST /api/v1/trading/commands (open)
| Status |
Codes |
| 400 |
bad_policy, bad_request, idempotency, invalid_order, parse_error, stale_request |
| 401 |
unauthenticated |
| 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 |
| 404 |
unknown_account, unknown_instrument, unknown_order, unknown_venue |
| 409 |
account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, bad_state, idempotency_conflict, idempotency_in_progress |
| 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 |
| 423 |
halted, kill_switch_active, read_only_mode |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| 501 |
execution_not_wired |
| 502 |
swap_flow_failed |
| 503 |
authorization_unknown, mandate_unavailable, no_liquidity, service_unavailable, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable |
# POST /api/v1/trading/risk/kill-switch
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/strategies
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
idempotency_conflict, idempotency_in_progress, wrong_kind |
| 422 |
bad_strategy |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/strategies/{id}/backtest
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
idempotency_conflict, idempotency_in_progress |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/strategies/{id}/start
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, owner_required, restricted |
| 404 |
not_found |
| 409 |
bad_report, bad_request, bad_state, halted, idempotency_conflict, idempotency_in_progress, live_unavailable, mandate_required, no_report, no_strategy, other_version |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/strategies/{id}/stop
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
bad_state, idempotency_conflict, idempotency_in_progress |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents/templates
| Status |
Codes |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents/{id}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents/{id}/signals
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents/{id}/journal
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/agents/{id}/orders
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# GET /api/v1/trading/jobs/{id}
| Status |
Codes |
| 400 |
bad_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/agents
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, owner_required |
| 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 |
| 422 |
bad_request, universe_mismatch |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/agents/{id}/start
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, owner_required, restricted |
| 404 |
not_found |
| 409 |
bad_report, bad_state, halted, idempotency_conflict, idempotency_in_progress, live_unavailable, mandate_required, no_report, no_strategy |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/agents/{id}/pause
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
bad_state, idempotency_conflict, idempotency_in_progress |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/agents/{id}/stop
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
bad_state, idempotency_conflict, idempotency_in_progress |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# POST /api/v1/trading/agents/{id}/backtest
| Status |
Codes |
| 400 |
bad_request, idempotency, stale_request |
| 401 |
unauthenticated |
| 403 |
insufficient_scope, ip_not_allowed, mixed_credentials, restricted |
| 404 |
not_found |
| 409 |
idempotency_conflict, idempotency_in_progress, no_strategy, wrong_kind |
| 429 |
auth_throttled, rate_limited |
| 500 |
internal |
# Order states
status |
final |
CREATED |
no |
VALIDATED |
no |
AWAITING_APPROVAL |
no |
APPROVED |
no |
SUBMITTING |
no |
SUBMITTED |
no |
PARTIALLY_FILLED |
no |
FILLED |
yes |
CANCELLED |
yes |
REJECTED |
yes |
FAILED |
yes |
UNKNOWN |
no |
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.
# Refusal detail
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.
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.
# Webhook events
| Event |
Emitted in this version |
Payload (data) |
Description |
key.revoked |
yes |
{ keyId, name, reason } |
an API key was revoked (or replaced by a rotation) |
risk.kill_switch |
yes |
`{ source: "signer", halted: true } |
{ source: "risk_engine", engaged, by, reason }` |
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) |
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) |
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 |