SPB Git

Repository Public

TRADING-API-OPENAPI.md 74.6 KB

# 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):

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):

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):

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):

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):

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):

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):

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):

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):

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):

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

# GET /api/v1/trading/agents/{id}/performance

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):

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):

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):

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):

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):

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

# GET /api/v1/trading/agents/{id}/performance

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
Files main
Menu

Theme