SPB Git

Repository Public

TRADING-API-REFERENCE.md 383.6 KB 8,403 lines markdown

1# SP Trading API — reference23> Generated by `npx tsx scripts/gen-openapi.mts` from `services/api/src/trading-api/` (`spec.ts`, `examples.ts`, `guide.ts`, `error-catalog.ts`). Do not edit by hand:4> a test compares this file with what the code generates. The same content is served by the wallet at5> `GET /api/v1/trading/docs` (HTML) and `GET /api/v1/trading/docs.md` (this Markdown).67Version 1.0.0 · 46 operations · OpenAPI 3.1: [`docs/openapi/trading-v1.json`](openapi/trading-v1.json), served at `GET /api/v1/trading/openapi.json`.89## Contents1011- [Overview](#overview)12- [Getting started in five minutes](#getting-started)13- [Démarrage rapide (français)](#demarrage-rapide)14- [Authentication and permissions](#authentication)15- [Decimals, timestamps, identifiers](#formats)16- [Instruments and venues](#instruments)17- [Paper and live, the execution lock](#paper-live)18- [Mandates](#mandates)19- [Why an order is refused](#refusals)20- [Order states](#order-states)21- [Idempotency](#idempotency)22- [Pagination](#pagination)23- [Rate limits](#rate-limits)24- [Errors](#errors)25- [Commands](#commands)26- [Webhooks](#webhooks)27- [Streaming (websocket)](#stream)28- [Operations](#operations)29  - [Meta](#tag-meta) — [`getOpenApi`](#op-getOpenApi)30  - [Markets](#tag-markets) — [`listMarkets`](#op-listMarkets), [`compareMarkets`](#op-compareMarkets), [`getMarket`](#op-getMarket), [`getOrderbook`](#op-getOrderbook), [`getCandles`](#op-getCandles), [`listPrivateMarkets`](#op-listPrivateMarkets), [`getPrivateMarketCompany`](#op-getPrivateMarketCompany), [`getPrivateMarket`](#op-getPrivateMarket)31  - [Portfolio](#tag-portfolio) — [`getPortfolio`](#op-getPortfolio), [`getBalances`](#op-getBalances), [`getActivity`](#op-getActivity)32  - [Nfts](#tag-nfts) — [`listNfts`](#op-listNfts), [`getNft`](#op-getNft), [`getNftActivity`](#op-getNftActivity), [`getNftMarket`](#op-getNftMarket), [`getNftMarketEvents`](#op-getNftMarketEvents)33  - [Positions](#tag-positions) — [`listPositions`](#op-listPositions), [`closePosition`](#op-closePosition), [`reducePosition`](#op-reducePosition)34  - [Orders](#tag-orders) — [`listOrders`](#op-listOrders), [`placeOrder`](#op-placeOrder), [`getOrder`](#op-getOrder), [`cancelOrder`](#op-cancelOrder), [`previewOrder`](#op-previewOrder), [`runCommand`](#op-runCommand)35  - [Strategies](#tag-strategies) — [`listStrategies`](#op-listStrategies), [`createStrategy`](#op-createStrategy), [`backtestStrategy`](#op-backtestStrategy), [`startStrategy`](#op-startStrategy), [`stopStrategy`](#op-stopStrategy)36  - [Agents](#tag-agents) — [`listAgents`](#op-listAgents), [`createAgent`](#op-createAgent), [`listAgentTemplates`](#op-listAgentTemplates), [`getAgent`](#op-getAgent), [`listAgentSignals`](#op-listAgentSignals), [`listAgentJournal`](#op-listAgentJournal), [`listAgentOrders`](#op-listAgentOrders), [`getAgentPerformance`](#op-getAgentPerformance), [`getJob`](#op-getJob), [`startAgent`](#op-startAgent), [`pauseAgent`](#op-pauseAgent), [`stopAgent`](#op-stopAgent), [`backtestAgent`](#op-backtestAgent)37  - [Risk](#tag-risk) — [`getRisk`](#op-getRisk), [`engageKillSwitch`](#op-engageKillSwitch)38- [Objects](#objects)39- [Error catalogue](#error-catalogue)4041<a id="overview"></a>4243## Overview4445The SP Trading API is the machine interface of SP Wallet: market data, the portfolio, positions, orders, strategies and agents — 46 operations under `/api/v1/trading`, one owner, keys he creates with his passkey.4647| | |48|---|---|49| Base URL | `https://wallet.spboucher.ai/api/v1/trading` |50| Format | JSON in, JSON out, UTF-8. Request bodies are strict: an unknown field is refused (400 `bad_request`) |51| Authentication | `Authorization: Bearer spw_live_…` |52| Contract | OpenAPI 3.1 at [`/api/v1/trading/openapi.json`](/api/v1/trading/openapi.json), generated from the same table the server registers its routes from |53| This reference | [`/api/v1/trading/docs`](/api/v1/trading/docs) (HTML), [`/api/v1/trading/docs.md`](/api/v1/trading/docs.md) (Markdown) — both need a key or the owner session, like every path of the API |54| SDKs | TypeScript `@sp-wallet/trading-sdk` (`packages/trading-sdk`), Python `sp-wallet-python` (`sdk/python`) |55| Live market data | websocket `/api/v1/trading/stream` |5657Three rules run through everything:5859- **Money is a string.** Prices, sizes, amounts and rates are decimal strings; send strings, parse with a decimal type.60- **Paper and live are never mixed.** Every row that could be either carries `mode`; no figure adds the two.61- **A permission is not an authorization to trade.** A scope lets a key *call* an operation. What bounds an order is a trading mandate the owner approved, checked on every order — and, for live orders, enforced by the isolated signer.6263<a id="getting-started"></a>6465## Getting started in five minutes6667Five minutes from nothing to a simulated order. Everything below was run against a real server; the answers shown are recorded.6869### 1. Create a key7071In the wallet app: **Settings → Developer / API → Keys → New key**.7273- **Name** — anything (`my bot`).74- **Expiry** — required, at most 365 days.75- **Permissions** — for reading: `wallet:read`, `markets:read`, `orders:read`, `positions:read`. For the paper order of step 3 add `orders:prepare`, `orders:execute`, `orders:cancel` and `positions:manage`.76- Approve with your passkey. The secret (`spw_live_spk_…`) is shown **once**: the server keeps only a hash of it.7778A key opens `/api/v1/trading/` and nothing else — never the recovery phrase, the signer, the security settings or the keys themselves.7980### 2. First call8182```bash83export SP_WALLET_BASE_URL=https://wallet.spboucher.ai84export SP_WALLET_API_KEY=spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0   # yours, shown once8586curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \87  -H "Authorization: Bearer $SP_WALLET_API_KEY"88```8990```ts91import { SPWallet } from '@sp-wallet/trading-sdk';9293const client = new SPWallet();   // reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL94const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });95console.log(markets[0].id, markets[0].mark);96```9798```python99from sp_wallet import SPWallet100101client = SPWallet()   # reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL102markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets103print(markets[0].id, markets[0].mark)104```105106```json107{108  "markets": [109    {110      "id": "hyperliquid:BTC",111      "venue": "hyperliquid",112      "kind": "perpetual",113      "symbol": "BTC",114      "base": "BTC",115      "quote": "USD",116      "status": "active",117      "mark": "64432",118      "index": "64460.7",119      "funding": "0.0000089721",120      "fundingIntervalSec": 3600,121      "volume24h": "3621656019.2002997398",122      "openInterest": "37680.57528",123      "maxLeverage": "40",124      "tickSize": "0.1",125      "lotSize": "0.00001",126      "collateral": "USDC",127      "restriction": null,128      "ts": 1794953721101,129      "stale": false,130      "source": "venue"131    }132  ],133  "total": 1,134  "truncated": false,135  "errors": [],136  "ts": 1794953721103137}138```139140Prices are **strings** (`"mark": "64432"`): never parse them as floats. `ts` is milliseconds since the epoch.141142The SDKs are in the repository and are not published:143144```bash145# TypeScript (not on npm: built from the repository)146node packages/trading-sdk/scripts/build.mts147npm install /path/to/sp-wallet/packages/trading-sdk148149# Python (not on PyPI)150pip install /path/to/sp-wallet/sdk/python151```152153### 3. First paper order154155An order placed with a key needs three things, which only the owner can set up:1561571. a **paper account** on Hyperliquid — app: **Futures → Accounts**;1582. a **paper trading mandate** for the key — app: **Settings → Risk → Trading mandates → New** (principal: your API key; mode: paper; the account; the instruments, e.g. `hyperliquid:BTC`; the limits). A paper mandate signs nothing;1593. the mandate **bound to the key**. Without it, `orders:execute` is inert and the API answers:160161```json162{163  "error": "mandate_required",164  "message": "the scope orders:execute is inert on this key: no trading mandate is bound to it"165}166```167168> **Gap in the app.** The Developer screen has a "Mandate id" field only when a key is *created*, and a mandate can only be created for a key that already exists. Binding a mandate to an existing key is the owner route pair `POST /api/v1/developer/keys/{id}/update/prepare` `{ "changes": { "mandateId": "…" } }` then `POST /api/v1/developer/keys/{id}/update` `{ intentId, assertion }` (a passkey assertion; binding widens the key). No screen calls it yet.169170Then:171172```bash173# 1. what would happen — creates nothing174curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" -H "Authorization: Bearer $SP_WALLET_API_KEY" \175  -H "Content-Type: application/json" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'176177# 2. place it — one Idempotency-Key per logical order178curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" -H "Authorization: Bearer $SP_WALLET_API_KEY" \179  -H "Content-Type: application/json" -H "Idempotency-Key: bot-2026-11-17-0001" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'180181# 3. read it, then close the position182curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" -H "Authorization: Bearer $SP_WALLET_API_KEY"183curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" -H "Authorization: Bearer $SP_WALLET_API_KEY"184```185186```ts187import { SPWallet } from '@sp-wallet/trading-sdk';188189const client = new SPWallet();190const order = { mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' } as const;191192const preview = await client.previewOrder(order);              // creates nothing193if (!preview.wouldExecute) throw new Error(JSON.stringify(preview.refusals));194195const placed = await client.createOrder(order, { idempotencyKey: 'bot-2026-11-17-0001' });196const done = await client.waitForOrder(placed.order.id);       // FILLED, CANCELLED, REJECTED or FAILED197console.log(done.order.status, done.order.filled, done.order.avgFillPrice);198199const { positions } = await client.getPositions({ mode: 'paper' });200await client.closePosition(positions[0].id);                   // strictly reduce-only201```202203```python204from sp_wallet import SPWallet205206client = SPWallet()207order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")208209preview = client.preview_order(**order)                        # creates nothing210if not preview.would_execute:211    raise SystemExit(preview.refusals)212213placed = client.create_order(**order, idempotency_key="bot-2026-11-17-0001")214done = client.wait_for_order(placed.order.id)                  # FILLED, CANCELLED, REJECTED or FAILED215print(done.order.status, done.order.filled, done.order.avg_fill_price)216217positions = client.get_positions(mode="paper").positions218client.close_position(positions[0].id)                         # strictly reduce-only219```220221The answer of step 2 — a paper market order is filled at once, against the real Hyperliquid order book, by the wallet's paper engine. Nothing is signed and nothing reaches a venue:222223```json224{225  "order": {226    "id": "0xff18683e8e2aa319d3812cf8a47fc261",227    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",228    "mode": "paper",229    "venue": "hyperliquid",230    "network": "mainnet",231    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",232    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",233    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",234    "venueOrderId": "paper-o-1",235    "instrument": "hyperliquid:BTC",236    "side": "buy",237    "type": "market",238    "size": "0.00155",239    "price": "64754",240    "triggerPrice": null,241    "reduceOnly": false,242    "tif": "ioc",243    "status": "FILLED",244    "final": true,245    "reasonCode": "VENUE_FILLED",246    "reason": null,247    "rejectCode": null,248    "engineStatus": "filled",249    "filled": "0.00155",250    "avgFillPrice": "64432",251    "acknowledged": true,252    "cancelRequested": false,253    "origin": "trading_api",254    "principal": {255      "kind": "api_key",256      "id": "spk_0123456789ab"257    },258    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",259    "engine": "paper",260    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",261    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",262    "notionalUsd": "100.3687",263    "projectionError": null,264    "version": 4,265    "createdAt": 1794953729578,266    "updatedAt": 1794953729602267  },268  "idempotent": false,269  "approval": null270}271```272273The same call with the same `Idempotency-Key` returns the same order (header `Idempotent-Replay: true`): a retry can never place it twice.274275If the wallet has several paper accounts on the venue (a perp agent gets its own when it is created), the API asks which: 409 `account_required`. Add `"accountId"` to the order — the ids are in `GET /portfolio` (`accounts`).276277### 4. Where to go next278279- [Why an order is refused](#refusals) — the three gates and every code.280- [Idempotency](#idempotency) before you write a retry loop.281- [Paper and live](#paper-live) before the first real order.282- The machine-readable contract: [`openapi.json`](/api/v1/trading/openapi.json); this page as Markdown: [`docs.md`](/api/v1/trading/docs.md).283284<a id="demarrage-rapide"></a>285286## Démarrage rapide (français)287288Cinq minutes pour passer de rien à un ordre simulé. Les exemples sont ceux de la section anglaise : les routes, les champs et les réponses sont les mêmes.289290### 1. Créer une clé291292Dans l'application : **Réglages → Développeur / API → Clés → Nouvelle clé**.293294- **Nom** — libre (`mon robot`).295- **Expiration** — obligatoire, au plus 365 jours.296- **Permissions** — pour lire : `wallet:read`, `markets:read`, `orders:read`, `positions:read`. Pour l'ordre simulé de l'étape 3, ajoutez `orders:prepare`, `orders:execute`, `orders:cancel` et `positions:manage`.297- Approuvez avec votre clé d'accès. Le secret (`spw_live_spk_…`) n'est affiché **qu'une fois** : le serveur n'en garde qu'une empreinte.298299Une clé n'ouvre que `/api/v1/trading/` — jamais la phrase de récupération, le signataire, la sécurité ni les clés elles-mêmes.300301### 2. Premier appel302303```bash304export SP_WALLET_BASE_URL=https://wallet.spboucher.ai305export SP_WALLET_API_KEY=spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0   # yours, shown once306307curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \308  -H "Authorization: Bearer $SP_WALLET_API_KEY"309```310311```ts312import { SPWallet } from '@sp-wallet/trading-sdk';313314const client = new SPWallet();   // reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL315const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });316console.log(markets[0].id, markets[0].mark);317```318319```python320from sp_wallet import SPWallet321322client = SPWallet()   # reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL323markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets324print(markets[0].id, markets[0].mark)325```326327Les prix sont des **chaînes** (`"mark": "64432"`) : ne les lisez jamais comme des flottants. `ts` est en millisecondes depuis l'époque Unix.328329### 3. Premier ordre simulé (paper)330331Un ordre passé avec une clé exige trois choses, que seul le propriétaire peut mettre en place :3323331. un **compte simulé** sur Hyperliquid — application : **Contrats à terme → Comptes** ;3342. un **mandat de négociation simulé** pour la clé — application : **Réglages → Risque → Mandats de négociation → Nouveau** (mandant : votre clé d'API ; mode : simulé ; le compte ; les instruments, par exemple `hyperliquid:BTC` ; les limites). Un mandat simulé ne signe rien ;3353. le mandat **lié à la clé**. Sans lui, `orders:execute` est inerte et l'API répond `403 mandate_required`.336337> **Lacune de l'application.** L'écran Développeur n'offre le champ « Identifiant du mandat » qu'à la *création* d'une clé, et un mandat ne peut être créé que pour une clé qui existe déjà. Lier un mandat à une clé existante passe par les deux routes du propriétaire `POST /api/v1/developer/keys/{id}/update/prepare` puis `POST /api/v1/developer/keys/{id}/update` (assertion de la clé d'accès). Aucun écran ne les appelle pour l'instant.338339Ensuite :340341```bash342# 1. what would happen — creates nothing343curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" -H "Authorization: Bearer $SP_WALLET_API_KEY" \344  -H "Content-Type: application/json" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'345346# 2. place it — one Idempotency-Key per logical order347curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" -H "Authorization: Bearer $SP_WALLET_API_KEY" \348  -H "Content-Type: application/json" -H "Idempotency-Key: bot-2026-11-17-0001" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'349350# 3. read it, then close the position351curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" -H "Authorization: Bearer $SP_WALLET_API_KEY"352curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" -H "Authorization: Bearer $SP_WALLET_API_KEY"353```354355```ts356import { SPWallet } from '@sp-wallet/trading-sdk';357358const client = new SPWallet();359const order = { mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' } as const;360361const preview = await client.previewOrder(order);              // creates nothing362if (!preview.wouldExecute) throw new Error(JSON.stringify(preview.refusals));363364const placed = await client.createOrder(order, { idempotencyKey: 'bot-2026-11-17-0001' });365const done = await client.waitForOrder(placed.order.id);       // FILLED, CANCELLED, REJECTED or FAILED366console.log(done.order.status, done.order.filled, done.order.avgFillPrice);367368const { positions } = await client.getPositions({ mode: 'paper' });369await client.closePosition(positions[0].id);                   // strictly reduce-only370```371372```python373from sp_wallet import SPWallet374375client = SPWallet()376order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")377378preview = client.preview_order(**order)                        # creates nothing379if not preview.would_execute:380    raise SystemExit(preview.refusals)381382placed = client.create_order(**order, idempotency_key="bot-2026-11-17-0001")383done = client.wait_for_order(placed.order.id)                  # FILLED, CANCELLED, REJECTED or FAILED384print(done.order.status, done.order.filled, done.order.avg_fill_price)385386positions = client.get_positions(mode="paper").positions387client.close_position(positions[0].id)                         # strictly reduce-only388```389390Un ordre au marché simulé est exécuté tout de suite par le moteur de simulation du portefeuille, contre le vrai carnet d'ordres d'Hyperliquid. Rien n'est signé, rien ne part vers une plateforme. Le même appel avec le même `Idempotency-Key` renvoie le même ordre : une relance ne peut pas le passer deux fois.391392### 4. Ordres réels393394Un ordre réel (`"mode": "live"`) passe par Hyperliquid seulement, sous un mandat réel approuvé avec la clé d'accès et appliqué par le signataire isolé, et seulement si le serveur a `SPW_TRADING_API_EXECUTION=on`. Voir [Paper and live](#paper-live) et [Why an order is refused](#refusals).395396<a id="authentication"></a>397398## Authentication and permissions399400Every request carries the key in one header. No cookie, no CSRF header, no query parameter — a key in a URL opens nothing.401402```http403GET /api/v1/trading/markets HTTP/1.1404Host: wallet.spboucher.ai405Authorization: Bearer spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0406```407408The token is `spw_live_<key id>_<secret>`. The key id (`spk_` + 12 hex) is public and appears in lists, logs and webhooks; the secret is 32 random bytes shown once. A missing, malformed, unknown, expired or revoked key gets one answer:409410```json411{412  "error": "unauthenticated",413  "message": "authentication required"414}415```41641710 failed authentications in a minute from one address lock that address out for the rest of the minute (429 `auth_throttled`). A request that carries a key **and** the session cookie is refused (403 `mixed_credentials`). Outside `/api/v1/trading/` a key is refused before it is even looked up (403 `key_path_forbidden`).418419A key answer carries `X-Request-Id`: quote it when something needs investigating; it is in the usage log (Developer → Usage, kept 90 days by default).420421### Permissions (scopes)422423| Scope | Opens | Execution scope |424|---|---|---|425| `wallet:read` | Balances, the portfolio, activity, the wallet's NFTs. | — |426| `markets:read` | Markets, order books, candles, the venue comparator, private markets, NFT market data, and the websocket stream. | — |427| `orders:read` | Orders and their fills. | — |428| `orders:prepare` | Preview an order; dry-run a command. Creates nothing. | — |429| `orders:execute` | Place an order. Execution scope: inert without a mandate bound to the key. | yes |430| `orders:cancel` | Cancel the key's own orders. Needs no mandate: a cancel only removes risk. | yes |431| `positions:read` | Positions and the risk state. | — |432| `positions:manage` | Close or reduce a position (needs a mandate); engage the kill switch (needs none). | yes |433| `strategies:read` | The strategy library and the versions pinned to agents. | — |434| `strategies:manage` | Register, backtest, start and stop strategy versions. Research and paper sign nothing. | — |435| `agents:read` | Agents, their signals, journal, orders, performance, jobs. | — |436| `agents:manage` | Create, start, pause, stop and backtest agents. Going live needs the agent's own owner-approved mandate. | — |437438Every operation names the one scope it needs. A key without it gets:439440```json441{442  "error": "insufficient_scope",443  "message": "this key lacks the scope wallet:read"444}445```446447The three **execution scopes** are inert until a trading mandate is bound to the key (403 `mandate_required`), with two exceptions that can only remove risk: cancelling the key's own order, and engaging the kill switch.448449### What else a key carries450451- **Expiry** — required, at most 365 days. At most 50 keys.452- **Rate limit** — 120 calls a minute by default, at most 600.453- **Restrictions** — optional allow-lists of venues, instruments, networks and source IP addresses / CIDR blocks. Outside them: 403 `restricted` or `ip_not_allowed`.454- **Limits** — optional notional per order and per day, in USD (403 `key_limit_exceeded`).455- **Mandate** — the id of the trading mandate bound to it, or none.456457Narrowing a key needs the owner's session; anything that widens it — a scope, a later expiry, a looser restriction, a mandate — needs the passkey. **Rotating** a key creates a new id with the same settings and revokes the old one at once; the mandate named the old id, so the new key has no mandate until one is approved and bound again.458459<a id="formats"></a>460461## Decimals, timestamps, identifiers462463### Decimals464465Anything that carries money or a quantity is a decimal **string**: `"64432"`, `"0.00155"`, `"0.0000089721"`. In a request the form is `^\d+(\.\d+)?$` — no sign, no exponent, no thousands separator. A size must be a multiple of the instrument's `lotSize` and a price a multiple of its `tickSize` (both in `GET /markets/{symbol}`); the simplest way to respect the lot is to send `notional` and let the server compute the size.466467Counts and settings are JSON numbers (`limit`, `slippageBps`, `fundingIntervalSec`, `decimals`).468469### Timestamps470471Two forms, by family — the field name tells which:472473- **milliseconds since the Unix epoch**, a JSON integer: `ts`, `createdAt`, `updatedAt`, `expiresAt`, `at` of a switch — markets, orders, positions, agents, risk;474- **ISO 8601 UTC strings**: `asOf` (portfolio, balances, NFTs), `at` of an activity item, `priceAt`, `fetchedAt`, the `ts` of a webhook envelope.475476The optional request header `X-SPW-Timestamp` is Unix **seconds**.477478### Freshness479480Market rows carry `ts` (when the source produced the value) and `stale` (older than its freshness bound, or the source could not be refreshed). A stale row is shown, never hidden: decide on `stale`. Lists that read several sources carry `errors: [{ source, message }]` for the ones that failed, and answer 503 only when none answered.481482### Identifiers483484| Thing | Form | Example |485|---|---|---|486| Instrument / market | `venue:symbol` | `hyperliquid:BTC`, `gmx:BTC/USD [BTC-USDC]`, `dydx:BTC-USD`, `spot:ETH` |487| Order | opaque string | `0xff18683e8e2aa319d3812cf8a47fc261` |488| Position | `mode:venue:account:instrument` — URL-encode it in a path | `paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC` |489| Key | `spk_` + 12 hex | `spk_0123456789ab` |490| Agent, job, strategy version, mandate, account | UUID | `b9180e9d-3977-403c-a072-9af105bfd59b` |491492A bare symbol (`BTC`) is accepted where a market is named, when it is not ambiguous; otherwise:493494```json495{496  "error": "ambiguous_symbol",497  "message": "'BTC' exists on several venues: name one of the candidates as venue:symbol",498  "candidates": [499    "dydx:BTC-USD",500    "edgex:BTCUSDC"501  ]502}503```504505<a id="instruments"></a>506507## Instruments and venues508509What can be read and what can be traded are different lists.510511| Venue | Market data | Paper orders (API) | Live orders (API key) |512|---|---|---|---|513| `hyperliquid` | yes | yes | **yes** — the perpetuals of Hyperliquid's own dex (179 active out of 235 listed when this page was recorded, 2026-11-17), ids `hyperliquid:BTC`, `hyperliquid:ETH`, … |514| `gmx` | yes (pool figures, no order book) | no — the paper engine needs a book (422 `paper_unsupported`) | no — every GMX order is a wallet transaction the owner approves in the app (403 `gmx_requires_owner_passkey`) |515| `dydx` | yes | no | no — market data only (403 `venue_restricted`) |516| `edgex` | yes | no | no — market data only (403 `venue_restricted`) |517| `spot` | yes (bars, no order book) | no | no — a key cannot place a spot order (403 `spot_execution_requires_agent_vault`); an owner's spot order is a swap approved with the passkey |518519`GET /markets?venue=hyperliquid` lists the instruments with what an order must respect:520521```json522{523  "id": "hyperliquid:BTC",524  "venue": "hyperliquid",525  "kind": "perpetual",526  "symbol": "BTC",527  "base": "BTC",528  "quote": "USD",529  "status": "active",530  "mark": "64432",531  "index": "64460.7",532  "funding": "0.0000089721",533  "fundingIntervalSec": 3600,534  "volume24h": "3621656019.2002997398",535  "openInterest": "37680.57528",536  "maxLeverage": "40",537  "tickSize": "0.1",538  "lotSize": "0.00001",539  "collateral": "USDC",540  "restriction": null,541  "ts": 1794953721101,542  "stale": false,543  "source": "venue"544}545```546547**Private markets** (`GET /private-markets`: synthetic contracts on private companies, on Hyperliquid builder dexes and edgeX) are display only — `tradable` is always `false`. Ids have three parts there: `hyperliquid:io:ANTH`.548549Candle intervals: `1m`, `5m`, `15m`, `1h`, `4h`, `1d` (spot market data stores fewer: 422 `unsupported_interval`).550551<a id="paper-live"></a>552553## Paper and live, the execution lock554555Every order names its `mode`.556557| | `paper` | `live` |558|---|---|---|559| What executes | the wallet's paper engine, against the venue's real public order book | the venue (Hyperliquid) |560| Money | simulated collateral of a paper account | the collateral of an authorized venue account |561| Signature | none | the isolated signer signs under the mandate it stores |562| Mandate (key) | a paper mandate; approving it signs nothing | a live mandate the owner approves with the passkey, compiled into the signer |563| Server locks | none | `SPW_TRADING_API_EXECUTION`, and the mainnet locks |564565### The execution lock566567`SPW_TRADING_API_EXECUTION` is a setting of the **server**, not of a key. Unless it is `on`, an order that adds live risk through this API is refused before anything is created:568569```json570{571  "error": "execution_disabled",572  "message": "live execution through the trading API is disabled on this server (SPW_TRADING_API_EXECUTION is not \"on\"); nothing was created. Cancels and strictly reducing orders still pass."573}574```575576Paper is never affected; cancels and strictly reducing orders pass even when the lock is closed. The production server (wallet.spboucher.ai) was reported running with the lock **on** when this page was written (2026-11-17) — the page cannot check it. Two ways to know: the owner's **Developer → Status** screen (service "execution"), or a `POST /orders/preview` of a live order, whose `refusals` would carry `{ "stage": "lock", "code": "execution_disabled" }`. `GET /risk` lists the other server locks under `capabilityLocks` (`deriv_live_mainnet`, `deriv_mandate_mainnet`, `deriv_gmx_live`, `broadcast`), each with `on` and `why`; the execution lock itself is not in that list.577578### Before the first live order with a key5795801. An authorized Hyperliquid venue account (app: Futures → Accounts, passkey).5812. A **live** trading mandate for the key, approved with the passkey, and bound to the key.5823. The risk limits of the live book set by the owner (Settings → Risk → Limits → Live): on a live book an absent limit **denies**, and a key never benefits from limits carried over from earlier versions.5834. The server locks open.584585Preview first: `POST /orders/preview` runs every gate on the market as it is now and says what would refuse the order, without creating anything.586587<a id="mandates"></a>588589## Mandates590591A **trading mandate** is the owner's written authorization for one principal (an API key or an agent): which accounts, which instruments, which order types, how much, how fast, until when. It is immutable — a change is a new mandate and the revocation of the old one — and it is checked on **every** order.592593What a mandate fixes: mode (`paper` or `live`), accounts, instruments, order types, `maxCapitalUsd`, `maxOrderNotionalUsd`, `maxPositionNotionalUsd`, `maxLeverage`, `maxDailyLossUsd`, `floorEquityUsd`, order frequency (per minute, hour, day), `maxSlippageBps`, `maxFeeUsd`, a duration in days, and stop conditions.594595- **Only the owner** creates, approves or revokes one (Settings → Risk → Trading mandates). The routes are outside this API: a key can do nothing to a mandate, its own included.596- A **paper** mandate signs nothing. A **live** mandate is compiled into the shape the isolated signer enforces and approved with the passkey: the signer then refuses, by itself, an order outside it.597- A revoked or expired mandate **winds down**: for 24 hours only cancels and strictly reducing orders pass (422 `mandate_wind_down`).598- A strictly reducing order is exempt from the limits that would stop an exit (capital, position, daily loss, frequency, stop conditions). It stays bound to the mandate's account, venue and instrument.599- A key or an agent closes only what its own fills opened (403 `position_not_attributable`).600601An order outside the mandate is refused with **every** reason at once, and the refused order is recorded:602603```json604{605  "error": "mandate_denied",606  "message": "the order is outside the mandate: ORDER_NOTIONAL_EXCEEDED",607  "data": {608    "reasons": [609      "ORDER_NOTIONAL_EXCEEDED"610    ],611    "order": {612      "id": "0xd51cebbed3c7d5e595f90d368ea832ad",613      "orderId": "0xd51cebbed3c7d5e595f90d368ea832ad",614      "mode": "paper",615      "venue": "hyperliquid",616      "network": "mainnet",617      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",618      "clientId": "0xd51cebbed3c7d5e595f90d368ea832ad",619      "clientOrderId": "0xd51cebbed3c7d5e595f90d368ea832ad",620      "venueOrderId": null,621      "instrument": "hyperliquid:BTC",622      "side": "buy",623      "type": "market",624      "size": "0.01396",625      "price": "64749",626      "triggerPrice": null,627      "reduceOnly": false,628      "tif": "ioc",629      "status": "REJECTED",630      "final": true,631      "reasonCode": "MANDATE_DENIED",632      "reason": "the order is outside the mandate: ORDER_NOTIONAL_EXCEEDED",633      "rejectCode": "mandate_denied",634      "engineStatus": null,635      "filled": "0",636      "avgFillPrice": null,637      "acknowledged": false,638      "cancelRequested": false,639      "origin": "trading_api",640      "principal": {641        "kind": "api_key",642        "id": "spk_0123456789ab"643      },644      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",645      "engine": "paper",646      "engineRef": null,647      "hash": "1aee5a4cdfc23da98dd02b104acef0677437ba9d866a24cf53c509e00b6d6a40",648      "notionalUsd": "903.89604",649      "projectionError": null,650      "version": 1,651      "createdAt": 1794953731495,652      "updatedAt": 1794953731502653    }654  }655}656```657658### `data.reasons` of `mandate_denied`659660| Reason | Meaning |661|---|---|662| `INVALID_INPUT` | the order or the usage figures could not be evaluated |663| `MANDATE_NOT_YET_VALID` | the mandate's validity window has not started |664| `MANDATE_ENDED` | the mandate has ended (past its end date and its wind-down) |665| `MANDATE_REVOKED` | the mandate was revoked |666| `WIND_DOWN_REDUCING_ONLY` | the mandate is winding down: only strictly reducing orders pass |667| `PRINCIPAL_MISMATCH` | the mandate was approved for another key or agent |668| `MANDATE_ID_MISMATCH` | the order names another mandate |669| `MODE_MISMATCH` | a paper mandate cannot place a live order, nor the reverse |670| `ACCOUNT_NOT_ALLOWED` | the account is not one of the mandate's |671| `VENUE_NOT_ALLOWED` | the venue is not one of the mandate's |672| `NETWORK_NOT_ALLOWED` | the network is not one of the mandate's |673| `INSTRUMENT_NOT_ALLOWED` | the instrument is not in the mandate's list |674| `MARKET_KIND_NOT_ALLOWED` | spot or perp is not allowed by the mandate |675| `ORDER_TYPE_NOT_ALLOWED` | the order type (market, limit, stop, take-profit) is not in the mandate's list |676| `NOTIONAL_UNKNOWN` | the order cannot be valued (no reference price), so the limits cannot be checked |677| `ORDER_NOTIONAL_EXCEEDED` | the order is above `maxOrderNotionalUsd` |678| `POSITION_NOTIONAL_EXCEEDED` | the resulting position is above `maxPositionNotionalUsd` |679| `CAPITAL_EXCEEDED` | the capital in use after the order is above `maxCapitalUsd` |680| `LEVERAGE_EXCEEDED` | the leverage is above `maxLeverage` |681| `LEVERAGE_UNKNOWN` | the leverage the order would run under is not known |682| `DAILY_LOSS_REACHED` | today's realised loss under the mandate reached `maxDailyLossUsd` |683| `BELOW_FLOOR_EQUITY` | the equity of the mandated accounts is below `floorEquityUsd` |684| `RATE_PER_MINUTE` | the mandate's orders-per-minute limit is reached |685| `RATE_PER_HOUR` | the mandate's orders-per-hour limit is reached |686| `RATE_PER_DAY` | the mandate's orders-per-day limit is reached |687| `SLIPPAGE_ABOVE_MANDATE` | the order's slippage bound is above the mandate's `maxSlippageBps` |688| `FEE_ABOVE_MANDATE` | the order's fee cap is above the mandate's `maxFeeUsd` |689| `ORDER_OUTLIVES_MANDATE` | the order would stay valid after the mandate ends |690| `STOP_LOSS_GTE` | stop condition: the total loss under the mandate reached its threshold |691| `STOP_DRAWDOWN_GTE` | stop condition: the drawdown from the peak equity reached its threshold |692| `STOP_CONSECUTIVE_REJECTS_GTE` | stop condition: too many consecutive rejected orders |693| `STOP_DATA_STALE_GTE` | stop condition: the market data is too old |694| `STOP_SIGNER_UNREACHABLE_GTE` | stop condition: the signer has been unreachable for too long |695696<a id="refusals"></a>697698## Why an order is refused699700An order goes through gates, in this order. The first that refuses answers; the error code tells which gate it was.701702| # | Gate | Refuses with | Fix |703|---|---|---|---|704| 1 | **The request** — schema, instrument, account | 400 `bad_request`, `invalid_order`; 404 `unknown_instrument`; 409 `ambiguous_symbol`, `account_required`; 422 `below_min_size`, `no_account` | the request |705| 2 | **The key** — scope, restrictions, a mandate bound to it | 403 `insufficient_scope`, `restricted`, `mandate_required` | another key, or the owner widens it |706| 3 | **The execution lock** (live only), then the key's own notional limits, then whose position it is | 403 `execution_disabled`; `key_limit_exceeded`; `position_not_attributable` | the operator; a smaller order |707| 4 | **The mandate** | 403 `mandate_denied` + `data.reasons`; `mandate_not_approved`, `mandate_integrity`; 422 `mandate_wind_down` | fit the mandate, or a new mandate |708| 5 | **The risk engine** — one engine for every principal, venue and mode | 422 `risk_denied` + `data.failed`, `data.checks`; 423 `kill_switch_active`, `read_only_mode` | read `data.checks` |709| 6 | **The venue engine's own rules** — tick, lot, price bands, collateral, the account policy; for live orders, the mainnet locks | 422 `price_not_on_tick`, `size_not_on_lot`, `price_deviation`, `insufficient_collateral`, …; 403 `mainnet_disabled` | the order; the operator |710| 7 | **The venue** | 422 `venue_rejected`; 503 `venue_unavailable` | read `message` |711712Up to gate 3 nothing is created. From gate 4 on, the order **exists**: the refusal carries it in `data.order` with `status: "REJECTED"`, and it appears in `GET /orders`. A refusal is a 4xx; an outcome that is not known is **not** an error — the order is `UNKNOWN` and the server resolves it.713714**Ask before you send.** `POST /orders/preview` runs the same gates and answers 200 with `wouldExecute` and `refusals: [{ stage, code, message }]` (`stage` is `key`, `lock`, `mandate`, `risk` or `engine`), every risk check with what was observed and its limit, and an estimate of fees and slippage.715716### The risk engine717718One engine judges every order — the owner's, an agent's, a key's; paper or live — before any signature. A refusal says which checks failed (`kill_switch` here), what was observed and what the limit was:719720```json721{722  "error": "kill_switch_active",723  "message": "kill_switch: the kill switch is on: no new risk",724  "data": {725    "failed": [726      "kill_switch"727    ],728    "checks": [729      {730        "id": "kill_switch",731        "ok": false,732        "observed": "true",733        "limit": "false",734        "detail": "the kill switch is on: no new risk",735        "exempt": false736      }737    ],738    "decisionId": 21,739    "order": {740      "id": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",741      "orderId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",742      "mode": "paper",743      "venue": "hyperliquid",744      "network": "mainnet",745      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",746      "clientId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",747      "clientOrderId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",748      "venueOrderId": null,749      "instrument": "hyperliquid:BTC",750      "side": "buy",751      "type": "market",752      "size": "0.00155",753      "price": "64754",754      "triggerPrice": null,755      "reduceOnly": false,756      "tif": "ioc",757      "status": "REJECTED",758      "final": true,759      "reasonCode": "KILL_SWITCH_ACTIVE",760      "reason": "kill_switch: the kill switch is on: no new risk",761      "rejectCode": "kill_switch_active",762      "engineStatus": null,763      "filled": "0",764      "avgFillPrice": null,765      "acknowledged": false,766      "cancelRequested": false,767      "origin": "trading_api",768      "principal": {769        "kind": "api_key",770        "id": "spk_0123456789ab"771      },772      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",773      "engine": "paper",774      "engineRef": null,775      "hash": "ea251eb6fc7f290e903f8c8a23dc307c80181d4d35ee320e9d7aa65622218b3f",776      "notionalUsd": "100.3687",777      "projectionError": null,778      "version": 1,779      "createdAt": 1794953766532,780      "updatedAt": 1794953766906781    }782  }783}784```785786`data.checks[].observed` and `.detail` are withheld (null / a neutral sentence) for the checks that reveal account figures when the key holds neither `wallet:read` nor `positions:read`.787788| Check | Limit | Rule | Applies to a strictly reducing order |789|---|---|---|---|790| `input_valid` | — | the three inputs parse; the order's instrument is the context's; at most one position per venue and instrument; a spot sell does not exceed the holding supplied | yes |791| `read_only` | `context.readOnly` | read-only mode denies every order, reducing or not; only a cancel passes | yes |792| `kill_switch` | `context.killSwitch` | the kill switch denies every order that is not strictly reducing | no (exempt) |793| `reduce_only_valid` | — | an order flagged reduce-only must be opposite to an existing position and no larger than it (it can neither increase nor flip) | yes |794| `venue_allowed` | `allowedVenues` | the venue is in the allow-list | no (exempt) |795| `instrument_allowed` | `allowedInstruments` | the instrument is in the allow-list | no (exempt) |796| `instrument_status` | — | the instrument is active on the venue (a halted or reduce-only instrument takes no new risk) | no (exempt) |797| `signer_status` | — | live orders: the signer is reachable and not halted | no (exempt) |798| `venue_connection` | — | live orders: the venue connection is up | no (exempt) |799| `price_freshness` | `maxPriceAgeMs, minPriceSources` | at least minPriceSources sources of the instrument are no older (and no further in the future) than their maximum age | only without a limit price |800| `price_consistency` | `maxSourceDeviationBps` | (highest − lowest) / lowest over the fresh sources is within the limit; inconsistent data denies | only without a limit price |801| `order_notional` | `maxOrderNotional` | notional of the order (its own notional, or size × the highest of reference, limit and trigger price) | no (exempt) |802| `daily_notional` | `maxDailyNotional` | today's accepted notional plus this order | no (exempt) |803| `order_rate_minute` | `maxOrdersPerMinute` | orders already accepted in the last minute are below the limit | no (exempt) |804| `order_rate_hour` | `maxOrdersPerHour` | orders already accepted in the last hour are below the limit | no (exempt) |805| `order_rate_day` | `maxOrdersPerDay` | orders already accepted today are below the limit | no (exempt) |806| `position_size` | `maxPositionNotional` | resulting position on the instrument, at the reference price | no (exempt) |807| `order_leverage` | `maxOrderLeverage` | perp: the leverage setting the order runs under is known, within the limit and within the venue's maximum | no (exempt) |808| `account_leverage` | `maxAccountLeverage` | gross exposure after the order / total equity (margin.effectiveLeverage); equity ≤ 0 denies | no (exempt) |809| `gross_exposure` | `maxGrossExposure` | Σ \|size\| · mark over all venues (margin.grossExposure) | no (exempt) |810| `net_exposure` | `maxNetExposure` | \|Σ long − Σ short\| over all venues (margin.netExposure) | no (exempt) |811| `asset_exposure` | `maxAssetExposure` | \|net\| exposure of the order's asset over all venues (margin.exposureByAsset) | no (exempt) |812| `venue_exposure` | `maxVenueExposure` | gross exposure on the order's venue | no (exempt) |813| `collateral_concentration` | `maxVenueCollateralShareBps` | share of the total equity held on the order's venue | no (exempt) |814| `daily_loss` | `maxDailyLoss` | today's loss has not reached the limit | no (exempt) |815| `total_loss` | `maxTotalLoss` | the loss since inception has not reached the limit | no (exempt) |816| `drawdown` | `maxDrawdownBps` | (peak − current) / peak has not reached the limit | no (exempt) |817| `liquidation_distance` | `minLiquidationDistanceBps` | perp: estimated liquidation price after the order (margin.liquidationPriceCross / liquidationPriceAtLeverage) is at least the limit away from the reference price | no (exempt) |818| `slippage` | `maxSlippageBps (and the order's own maxSlippageBps when lower)` | average price of walking the book (router.walkBook) vs the mid; a book that cannot fill a market order denies | no (exempt) |819| `min_liquidity` | `minLiquidity` | depth on the taking side within withinBps of the mid ≥ multiple × order size | no (exempt) |820| `context_complete` | — | every account of the book could be read; when one cannot, exposure is not known and new risk is denied | no (exempt) |821822Three things worth knowing:823824- On a **live** book, a limit that was never set **denies** (the detail says "no limit is configured"). The owner sets them in Settings → Risk.825- With stale prices, the way out of a position is a reduce-only **limit** order: it names its own price and is exempt from the price checks.826- The **kill switch** blocks every new risk for everybody; cancels and strictly reducing orders pass. A key with `positions:manage` can engage it (`POST /risk/kill-switch`) and **cannot** release it. **Read-only mode** lets only cancels pass. Neither is the signer's emergency halt (423 `halted`), which is lifted on the signer machine.827828### The venue engine829830The last local gate is the engine that would execute the order, with the account's own policy. Its codes are the ones a trading program meets most — a limit price too far from the mark, for instance:831832```json833{834  "error": "price_deviation",835  "message": "price 51000 is more than 200 bps away from the mark 64433",836  "data": {837    "order": "{ … the order, status REJECTED … }"838  }839}840```841842An operation whose engine can add a code of its own is marked **open** in its error list (`x-spw-errors-open` in the OpenAPI document): treat an unknown 4xx code by its HTTP status.843844<a id="order-states"></a>845846## Order states847848An order's `status` is one of twelve states; `final` is true for four of them.849850```text851CREATED → VALIDATED → AWAITING_APPROVAL → APPROVED → SUBMITTING → SUBMITTED → PARTIALLY_FILLED → FILLED852                                                          └→ UNKNOWN → (the server asks the venue) → any of the above, or CANCELLED / REJECTED / FAILED853final: FILLED, CANCELLED, REJECTED, FAILED854```855856| `status` | Final | Meaning |857|---|---|---|858| `CREATED` | — | recorded; nothing checked yet |859| `VALIDATED` | — | passed the mandate and the risk engine |860| `AWAITING_APPROVAL` | — | an owner order waits for the passkey in the app (never the case for a key) |861| `APPROVED` | — | approved; about to be handed to its engine |862| `SUBMITTING` | — | being sent to the venue (or the paper engine) |863| `SUBMITTED` | — | accepted by the venue and resting; nothing filled yet |864| `PARTIALLY_FILLED` | — | partly filled; the rest is still working |865| `FILLED` | yes | completely filled. Final |866| `CANCELLED` | yes | withdrawn, expired or cancelled. Final |867| `REJECTED` | yes | refused by a rule: validation, mandate, risk, signer policy or the venue. Final; `reasonCode` and `rejectCode` say which |868| `FAILED` | yes | a technical failure after which it is PROVEN that no order exists at the venue. Final |869| `UNKNOWN` | — | the outcome at the venue is not known yet. NOT final and NOT a failure: the server resolves it by asking the venue — keep reading the order, do not send it again under a new key |870871- Decide on `status` and `final`. `engineStatus` is the executing engine's own word for the same moment, for information.872- **`UNKNOWN` is not a failure.** A network error after the request may have left makes the outcome unknown; the server reconciles with the venue. Wait — do not place the order again under another key.873- Nothing becomes `FILLED` without an event that comes from the venue (or the paper engine).874- `reasonCode` is the closed reason of the current state; `rejectCode` is the API error code of the refusal; `reason` is a sentence for people.875- Order types: `market`, `limit`, `stop_market`, `stop_limit`, `take_profit_market`, `take_profit_limit`. Time in force: `gtc`, `ioc`, `alo` (add-liquidity-only). A market order is bounded by `slippageBps` (1 to 500), not by a price.876877<a id="idempotency"></a>878879## Idempotency880881Every mutating call needs an `Idempotency-Key` header: 8 to 100 characters among letters, digits, `.` `_` `:` `-`. It makes a retry safe.882883| You send | The server |884|---|---|885| a new key | runs the operation, stores the answer (a 200 **or** a 4xx refusal) with a hash of the request (method, path, canonical body) |886| the same key, the same request | returns the stored answer with `Idempotent-Replay: true`; **nothing runs again** |887| the same key, a different request | 409 `idempotency_conflict` |888| the same key while the first call is still running | 409 `idempotency_in_progress` — wait and resend |889| no key | 400 `idempotency` |890891```json892{893  "error": "idempotency_conflict",894  "message": "this Idempotency-Key was used with a different request"895}896```897898- The namespace is the **principal**: two keys can use the same string.899- An answer ≥ 500 is **not** stored: nothing is assumed to have happened, the same key can be sent again — and should be. After a timeout or a 5xx, resend with the **same** key; never mint a new one for a retry.900- Stored answers are kept 24 hours.901- **An order has a second, permanent identity**: `clientOrderId` in the body (default: the Idempotency-Key). The order id is derived from it and from the principal, so the same `clientOrderId` is the same order for ever — `idempotent: true` in the answer says "this already existed, nothing was sent again".902- `X-SPW-Timestamp` (optional, Unix seconds): when present, a call more than 300 s from the server clock is refused (400 `stale_request`) — a guard against a delayed replay by a proxy.903904Operations that take **no** Idempotency-Key, because they change nothing or are naturally idempotent: `POST /orders/preview` and `POST /risk/kill-switch`.905906A good key is the name of the intent, not a random value made at send time: `rebalance-2026-11-17-btc`. Persist it before sending if the process can crash.907908<a id="pagination"></a>909910## Pagination911912Three conventions, by list:913914| Lists | How | End |915|---|---|---|916| `GET /orders`, `GET /activity`, `GET /nfts`, `GET /nfts/activity` | `limit` + opaque `cursor`: pass `nextCursor` of a page as `cursor` of the next, **with the same filters** | `nextCursor: null` |917| `GET /agents/{id}/signals`, `/journal`, `/orders` | `limit` + `before` (Unix ms: rows strictly before it) — pass the `ts` of the last row | fewer rows than `limit` |918| `GET /markets` and the other lists | not paginated; `limit` cuts, and `total` + `truncated` say so | — |919920Cursor pages are newest first, in one stable order (time, then id): a row created after the first page was read is not inserted into the pages that follow. A cursor that did not come from this list answers 400 `invalid_cursor`. `GET /nfts/market/events` has one cursor **per source**: send it with `provider`.921922```json923{924  "items": [925    {926      "kind": "fill",927      "mode": "paper",928      "at": "2026-11-17T22:15:31.480Z",929      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-6",930      "venue": "hyperliquid",931      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",932      "instrument": "hyperliquid:BTC",933      "side": "sell",934      "price": "64426",935      "size": "0.00078",936      "fee": "0.022613526",937      "closedPnl": "-0.00468"938    },939    {940      "kind": "fill",941      "mode": "paper",942      "at": "2026-11-17T22:15:31.456Z",943      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-4",944      "venue": "hyperliquid",945      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",946      "instrument": "hyperliquid:BTC",947      "side": "sell",948      "price": "64426",949      "size": "0.00077",950      "fee": "0.022323609",951      "closedPnl": "-0.00462"952    }953  ],954  "nextCursor": "WyIxNzk0OTUzNzMxNDU2MDAwIiwiZiIsIjZhMmM4MzUxLWNkNzktNDRlMi1iNzVhLWYzOTI4MGQwZWJjMjpwYXBlci1mLTQiXQ"955}956```957958Both SDKs follow the cursor for you: `iterateOrders` / `iterateActivity` (TypeScript), `iter_orders` / `iter_activity` (Python).959960<a id="rate-limits"></a>961962## Rate limits963964Per key, in fixed one-minute windows: 120 calls a minute by default, set per key up to 600. Every answer to a key carries:965966| Header | Meaning |967|---|---|968| `RateLimit-Limit` | the key's calls per minute |969| `RateLimit-Remaining` | calls left in the current window |970| `RateLimit-Reset` | seconds until the window resets |971| `Retry-After` | on a 429 only: seconds to wait |972973```http974HTTP/1.1 429 Too Many Requests975RateLimit-Limit: 3976RateLimit-Remaining: 0977RateLimit-Reset: 60978Retry-After: 60979980{"error":"rate_limited","message":"too many requests for this key"}981```982983- Every call counts, a refused one and a 404 included.984- The window is in the memory of the API process: a restart resets it.985- Failed authentications are counted per source address, apart: 10 a minute, then 429 `auth_throttled` with `Retry-After: 60`.986- The owner's session is limited per address instead (240 a minute) and carries no `RateLimit-*` header.987- Venues have their own limits: a venue that throttles the wallet answers 503 `venue_rate_limited`, which is not about your key.988989Both SDKs wait and retry on 429 (reads, and writes because they carry an Idempotency-Key). For live prices do not poll: use the [stream](#stream).990991<a id="errors"></a>992993## Errors994995Every error has the same body, whatever the status:996997```json998{999  "error": "<stable machine code>",1000  "message": "<sentence for people, English>",1001  "data": {1002    "…": "machine-readable detail, on refusals that have some"1003  }1004}1005```10061007Branch on `error`, never on `message`. `data` may carry: `order` (the order a refusal is about), `reasons` (mandate), `failed` and `checks` (risk), `questions` (an ambiguous command), `code` and `token` (a parse error). `ambiguous_symbol` carries `candidates` at the top level.10081009| Status | Class | Retry? |1010|---|---|---|1011| 400 | the request is not valid | no — fix it |1012| 401 | no usable credential | no |1013| 403 | authenticated, and refused: scope, restriction, mandate, server lock | no |1014| 404 | the object does not exist; or the path is not an operation (`not_found`) | no |1015| 409 | a conflict with the state of the object, or a choice is needed | after resolving it |1016| 422 | a valid request that cannot be carried out now | after changing the order |1017| 423 | blocked by the kill switch, read-only mode or a halt | when the owner releases it |1018| 429 | too many requests | yes, after `Retry-After` |1019| 500 | server error; a mutating call may or may not have run | yes, with the **same** Idempotency-Key |1020| 501 | declared but not connected; nothing was done | no |1021| 502, 503 | a backing service (venue, signer, provider) failed; nothing was done | yes, with backoff |10221023A path that is not an operation, or a known path with another method, answers in the same model:10241025```json1026{1027  "error": "not_found",1028  "message": "no such operation in the trading API: see GET /api/v1/trading/openapi.json"1029}1030```10311032A body that does not match the schema says only that — the server does not echo which field (check the request against the operation's schema):10331034```json1035{1036  "error": "bad_request",1037  "message": "invalid request"1038}1039```10401041Both SDKs turn these into typed exceptions (`AuthenticationError`, `ScopeDenied`, `MandateRequired`, `MandateDenied`, `RiskDenied`, `ExecutionDisabled`, `AmbiguousCommand`, `RateLimited`, `ValidationError`, …) with `code`, `status`, `requestId` and `order`. A mutating call that got no trustworthy answer raises `OutcomeUnknown` — not a failure — with the Idempotency-Key to resume with.10421043The full list, code by code, is the [error catalogue](#error-catalogue) at the end; each operation lists the codes it can answer.10441045<a id="commands"></a>10461047## Commands10481049`POST /commands` takes one line of a small deterministic grammar — no model, no guess — in English or French. It is the same machinery as the order operations, behind a sentence.10501051```text1052LONG|SHORT <asset>-PERP <notional> [x<lev>] [LIMIT <px>] [SL <px>] [TP <px>] [ON <venue>]1053CLOSE <asset>-PERP [pct%] [ON <venue>]1054BUY <asset> <amount> <quote> [ON <venue>]          (spot — the owner only)1055SELL <asset> <amount|pct%> [FOR <quote>] [ON <venue>]   (spot — the owner only)1056CANCEL ORDER <id>          CANCEL ALL [ON <venue>]1057SHOW POSITIONS | BALANCES | ORDERS | RISK1058STOP ALL AGENTS            KILL1059```10601061French spellings are accepted for the keywords (`ACHETER`, `VENDRE`, `FERMER`, `ANNULER`, `AFFICHER`, `SUR`, `URGENCE`, …); numbers are plain decimals.10621063- The **scope** checked is the one of the operation the line resolves to: an order needs `orders:execute` (`orders:prepare` with `dryRun`), CLOSE `positions:manage`, CANCEL `orders:cancel`, SHOW the matching read scope, KILL `positions:manage`.1064- `dryRun: true` answers what the line resolves to and does nothing.1065- **Nothing is assumed.** Venue, network, leverage, margin mode, fee cap, slippage bound and order validity come from the line or from the owner's stored defaults (he saves them from the command line of the app's Trade screen; owner routes `GET`/`PUT /api/v1/developer/command-defaults`). What neither says is asked back, and nothing executes:10661067```json1068{1069  "error": "ambiguous_command",1070  "message": "the command and the owner's defaults do not settle everything: answer the questions (or set the defaults) and send it again. Nothing was executed.",1071  "data": {1072    "questions": [1073      {1074        "field": "network",1075        "options": [1076          "mainnet"1077        ],1078        "message": "on which network? The defaults name none for BTC-PERP"1079      },1080      {1081        "field": "orderTtlMs",1082        "options": [],1083        "message": "no order validity is pre-approved: how long may the order wait before it is sent?"1084      }1085    ]1086  }1087}1088```10891090The answer has a `kind`: `query` (the read answer is in `data`), `control` (a cancel, the kill switch) or `order` — with `executed: false` for a dry run (`order` is then the canonical order) and `executed: true` otherwise (`order` is the placed order, `canonical` its canonical form). Recorded, `LONG BTC-PERP 100` executed on paper answered `kind: "order"`, `command: "perp_open"`, `order.status: "FILLED"`.10911092A line that is not a sentence of the grammar:10931094```json1095{1096  "error": "parse_error",1097  "message": "unknown command",1098  "data": {1099    "code": "unknown_command",1100    "token": 01101  }1102}1103```11041105<a id="webhooks"></a>11061107## Webhooks11081109Webhooks push events to an HTTPS endpoint of yours. The owner manages them in **Settings → Developer / API → Webhooks** (at most 10 endpoints); the signing secret (`whsec_…`) is shown once.11101111| Event | Payload (`data`) | When |1112|---|---|---|1113| `key.revoked` | `{ keyId, name, reason }` | an API key was revoked (or replaced by a rotation) |1114| `risk.kill_switch` | `{ source: "signer", halted: true } \| { source: "risk_engine", engaged, by, reason }` | the emergency halt of the signer was triggered (source "signer"), or the global kill switch of the risk engine was engaged or released (source "risk_engine") |1115| `agent.updated` | `{ agentId, kind, state, mode }` | an agent was started, paused or stopped (by the owner, an API key or the risk-management agent) |1116| `risk.proposal` | `{ 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) |1117| `order.updated` | `{ 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 |11181119Payloads carry identifiers and states only — no secret, no key material, no amount. On `order.updated`, read the order with `GET /orders/{id}`.11201121### What you receive11221123```http1124POST /your/endpoint HTTP/1.11125Content-Type: application/json1126X-SPW-Timestamp: 17949536871127X-SPW-Signature: v1=df38f5cf8ef5b56e0c43c3b4fca7755bfcde2892199e8bfe8dc974fee3863b7b1128X-SPW-Event: key.revoked1129X-SPW-Delivery: 4211301131{"app":"sp-wallet","id":"ed1fb6d3-1b5c-4bf6-b8cd-2237d8b2b38c","event":"key.revoked","ts":"2026-11-17T22:14:47.655Z","data":{"keyId":"spk_0123456789ab","name":"old bot","reason":"rotated to spk_ba9876543210"}}1132```11331134### Verifying the signature11351136`X-SPW-Signature` is `v1=` + the hex HMAC-SHA-256 of `"<X-SPW-Timestamp>.<raw body>"` with the endpoint's secret. Verify over the **raw bytes** received (not a re-serialised object), compare in constant time, and refuse a timestamp more than 300 s from your clock.11371138The example above is real arithmetic: with the secret `whsec_EXAMPLE_ONLY_0123456789abcdefghijklmnopqrstuv`, the string signed is `1794953687.` followed by the body, and the HMAC is the value shown. Check your implementation against it.11391140```ts1141import { constructWebhookEvent, WebhookVerificationError } from '@sp-wallet/trading-sdk';11421143// rawBody: the bytes exactly as received (Buffer / Uint8Array / string)1144try {1145  const event = await constructWebhookEvent({1146    secret: process.env.SP_WALLET_WEBHOOK_SECRET!,1147    timestamp: req.headers['x-spw-timestamp'],1148    signature: req.headers['x-spw-signature'],1149    body: rawBody,1150  });1151  if (!seen.has(event.id)) { seen.add(event.id); handle(event.event, event.data); }1152  res.writeHead(200).end('ok');1153} catch (e) {1154  res.writeHead(e instanceof WebhookVerificationError ? 400 : 500).end();1155}1156```11571158```python1159from sp_wallet import WebhookVerificationError, construct_webhook_event11601161# raw: the bytes exactly as received1162try:1163    event = construct_webhook_event(secret=SECRET, timestamp=headers.get("x-spw-timestamp"),1164                                    signature=headers.get("x-spw-signature"), body=raw)1165except WebhookVerificationError:1166    return 4001167if event["id"] not in seen:1168    seen.add(event["id"])1169    handle(event["event"], event["data"])1170return 2001171```11721173```python1174# without the SDK1175import hashlib, hmac, time11761177def verify(secret: str, timestamp: str, signature: str, raw: bytes) -> bool:1178    if abs(time.time() - int(timestamp)) > 300:1179        return False1180    want = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()1181    return hmac.compare_digest(want, signature)1182```11831184### Delivery11851186- **At least once.** Deduplicate on the envelope's `id` (the same for every attempt of one event; `X-SPW-Delivery` is the delivery row).1187- A delivery succeeds on any 2xx. Otherwise it is retried after 30 s, 2 min, 10 min, 1 h, 6 h; after 6 attempts it is `failed`. The Webhooks screen shows every delivery with its last status.1188- HTTPS only, no credentials in the URL, no redirect followed, 8 seconds to answer.1189- Order is not guaranteed: use `data.seq` of `order.updated` (it grows with each transition of one order).11901191<a id="stream"></a>11921193## Streaming (websocket)11941195Live market data — quotes, order books, trades, candles, venue status — is a websocket, which OpenAPI cannot describe. It is read-only: nothing is placed or cancelled over it.11961197```text1198wss://wallet.spboucher.ai/api/v1/trading/stream1199```12001201- **Scope**: `markets:read`. The key goes in the `Authorization` header of the handshake — never in the URL.1202- A client that cannot set a header (a browser) asks for a single-use ticket: `POST /api/v1/trading/stream/ticket` (same key, same scope) answers `{ ticket, expiresAt, ttlMs, url, protocol }`; connect to `…/stream?ticket=…` within 30 s.1203- A key's venue and instrument restrictions apply per subscription (`error restricted`).1204- At most 4 connections per key and 300 subscriptions per connection.1205- A stream connection is not in the key's usage log; the ticket request is.12061207```ts1208import { SPWalletStream } from '@sp-wallet/trading-sdk';12091210const stream = new SPWalletStream();   // SP_WALLET_API_KEY, SP_WALLET_BASE_URL1211await stream.subscribe([{ type: 'quote', id: 'hyperliquid:BTC' }, { type: 'status', id: 'hyperliquid' }]);1212for await (const m of stream) {1213  if (m.type === 'quote') console.log(m.id, m.bid, m.ask, m.mark, m.stale ? '(stale)' : '');1214}1215```12161217```python1218# pip install "sp-wallet-python[stream]"1219import asyncio1220from sp_wallet import SPWalletStream1221from sp_wallet.stream import Quote12221223async def main() -> None:1224    stream = SPWalletStream()   # SP_WALLET_API_KEY, SP_WALLET_BASE_URL1225    await stream.subscribe([{"type": "quote", "id": "hyperliquid:BTC"}, {"type": "status", "id": "hyperliquid"}])1226    async for m in stream:1227        if isinstance(m, Quote):1228            print(m.id, m.bid, m.ask, m.mark, "(stale)" if m.stale else "")12291230asyncio.run(main())1231```12321233### Protocol (version 1), in short12341235JSON text frames; every server frame has `"v": 1` and a `type`. Prices, sizes and rates are decimal strings; times are milliseconds.12361237```json1238// client → server1239{ "op": "subscribe", "reqId": 7, "channels": [ { "type": "quote",  "id": "hyperliquid:BTC" },1240                                               { "type": "book",   "id": "hyperliquid:BTC", "depth": 10 },1241                                               { "type": "trades", "id": "hyperliquid:BTC" },1242                                               { "type": "candle", "id": "hyperliquid:BTC", "interval": "1m" },1243                                               { "type": "status", "id": "*" } ] }1244{ "op": "unsubscribe", "channels": [ { "type": "quote", "id": "hyperliquid:BTC" } ] }1245{ "op": "ping", "t": 42 }1246```12471248| Server frame | Carries |1249|---|---|1250| `hello` | first frame: `connId`, `heartbeatMs`, the limits |1251| `subscribed` | one per channel, with the last known value at once (`snapshot`, `snapshotAgeMs`) and `staleAfterMs` |1252| `quote` | bid, ask, mid, mark, index, funding, open interest, `seq`, `stale` — a full state each time |1253| `book` | a `snapshot`, then `delta`s (`prevSeq` must equal the last `seq` applied; size `"0"` removes a price; `checksum` is a CRC-32 of the top ten levels) |1254| `trade` | a batch, oldest first; the first after a subscription is recent history (`snapshot: true`) |1255| `candle` | the bar in progress or a new bar |1256| `status` | per venue: `connected`, `reconnecting`, `stale`, `down`, `idle` |1257| `heartbeat`, `pong`, `dropped`, `unsubscribed`, `error` | housekeeping; an `error` never closes the connection |12581259Close code **4001** means the key is no longer active: do not reconnect with it. `1001` (server restart) — reconnect. The full protocol, the limits and the staleness rules are in `docs/V11-QUOTE-ENGINE.md`; both SDKs implement reconnection, resubscription and the order-book checks (`OrderBook`).12601261Order and position updates are **not** on the stream: use the `order.updated` webhook, or poll `GET /orders/{id}` (`waitForOrder` / `wait_for_order`).12621263<a id="operations"></a>12641265## Operations12661267| Method | Path | Operation | Permission | Idempotency-Key |1268|---|---|---|---|---|1269| GET | `/api/v1/trading/openapi.json` | [`getOpenApi`](#op-getOpenApi) — This document | any valid key | — |1270| GET | `/api/v1/trading/markets` | [`listMarkets`](#op-listMarkets) — Instruments across venues (perpetuals) and the spot market-data symbols | `markets:read` | — |1271| GET | `/api/v1/trading/markets/compare` | [`compareMarkets`](#op-compareMarkets) — Compare the estimated cost of one position across venues | `markets:read` | — |1272| GET | `/api/v1/trading/markets/{symbol}` | [`getMarket`](#op-getMarket) — One market: instrument, ticker and data quality | `markets:read` | — |1273| GET | `/api/v1/trading/markets/{symbol}/orderbook` | [`getOrderbook`](#op-getOrderbook) — Order book of one market | `markets:read` | — |1274| GET | `/api/v1/trading/markets/{symbol}/candles` | [`getCandles`](#op-getCandles) — Closed bars of one market | `markets:read` | — |1275| GET | `/api/v1/trading/private-markets` | [`listPrivateMarkets`](#op-listPrivateMarkets) — Synthetic contracts on private companies, venue by venue, with sourced valuations | `markets:read` | — |1276| GET | `/api/v1/trading/private-markets/companies/{slug}` | [`getPrivateMarketCompany`](#op-getPrivateMarketCompany) — Every contract on one private company, side by side (never merged) | `markets:read` | — |1277| GET | `/api/v1/trading/private-markets/{id}` | [`getPrivateMarket`](#op-getPrivateMarket) — One private-company contract: definition, valuation breakdown, candles, top of book | `markets:read` | — |1278| GET | `/api/v1/trading/portfolio` | [`getPortfolio`](#op-getPortfolio) — Wallet value and derivative accounts, per mode | `wallet:read` | — |1279| GET | `/api/v1/trading/balances` | [`getBalances`](#op-getBalances) — On-chain balances of the wallet | `wallet:read` | — |1280| GET | `/api/v1/trading/activity` | [`getActivity`](#op-getActivity) — Wallet activity and fills, newest first | `wallet:read` | — |1281| GET | `/api/v1/trading/nfts` | [`listNfts`](#op-listNfts) — NFTs of the wallet (what the chain confirmed as held) | `wallet:read` | — |1282| GET | `/api/v1/trading/nfts/item` | [`getNft`](#op-getNft) — One NFT of the wallet: identity, ownership, creator metadata, sources | `wallet:read` | — |1283| GET | `/api/v1/trading/nfts/activity` | [`getNftActivity`](#op-getNftActivity) — On-chain events of one NFT of the wallet | `wallet:read` | — |1284| GET | `/api/v1/trading/nfts/market` | [`getNftMarket`](#op-getNftMarket) — Market data of any NFT, one row per source | `markets:read` | — |1285| GET | `/api/v1/trading/nfts/market/events` | [`getNftMarketEvents`](#op-getNftMarketEvents) — Market events of any NFT (sales, listings, offers), per source | `markets:read` | — |1286| GET | `/api/v1/trading/positions` | [`listPositions`](#op-listPositions) — Open positions, paper and live separated by `mode` | `positions:read` | — |1287| GET | `/api/v1/trading/orders` | [`listOrders`](#op-listOrders) — Orders, newest first | `orders:read` | — |1288| POST | `/api/v1/trading/orders` | [`placeOrder`](#op-placeOrder) — Place an order | `orders:execute` + mandate | required |1289| GET | `/api/v1/trading/orders/{id}` | [`getOrder`](#op-getOrder) — One order and its fills | `orders:read` | — |1290| DELETE | `/api/v1/trading/orders/{id}` | [`cancelOrder`](#op-cancelOrder) — Cancel an order | `orders:cancel` | required |1291| GET | `/api/v1/trading/strategies` | [`listStrategies`](#op-listStrategies) — Strategy library and the versions pinned to agents | `strategies:read` | — |1292| POST | `/api/v1/trading/strategies` | [`createStrategy`](#op-createStrategy) — Register a library strategy version on an agent | `strategies:manage` | required |1293| GET | `/api/v1/trading/agents` | [`listAgents`](#op-listAgents) — Trading agents | `agents:read` | — |1294| POST | `/api/v1/trading/agents` | [`createAgent`](#op-createAgent) — Create an agent (from a template, or a perp agent) | `agents:manage` | required |1295| GET | `/api/v1/trading/risk` | [`getRisk`](#op-getRisk) — Risk state: kill switch, signer limits, capability locks, account policies | `positions:read` | — |1296| POST | `/api/v1/trading/orders/preview` | [`previewOrder`](#op-previewOrder) — Preview an order: every check it would meet, and an estimate | `orders:prepare` | — |1297| POST | `/api/v1/trading/positions/{id}/close` | [`closePosition`](#op-closePosition) — Close a position | `positions:manage` + mandate | required |1298| POST | `/api/v1/trading/positions/{id}/reduce` | [`reducePosition`](#op-reducePosition) — Reduce a position | `positions:manage` + mandate | required |1299| POST | `/api/v1/trading/commands` | [`runCommand`](#op-runCommand) — Run one line of the trading command grammar | `orders:prepare` | required |1300| POST | `/api/v1/trading/risk/kill-switch` | [`engageKillSwitch`](#op-engageKillSwitch) — Engage the global kill switch | `positions:manage` | — |1301| POST | `/api/v1/trading/strategies/{id}/backtest` | [`backtestStrategy`](#op-backtestStrategy) — Run the backtest of a strategy version (asynchronous job) | `strategies:manage` | required |1302| POST | `/api/v1/trading/strategies/{id}/start` | [`startStrategy`](#op-startStrategy) — Start the agent a strategy version is pinned to | `strategies:manage` | required |1303| POST | `/api/v1/trading/strategies/{id}/stop` | [`stopStrategy`](#op-stopStrategy) — Stop the agent a strategy version is pinned to | `strategies:manage` | required |1304| GET | `/api/v1/trading/agents/templates` | [`listAgentTemplates`](#op-listAgentTemplates) — The seven built-in agents: family, engine, modes, installed strategies | `agents:read` | — |1305| GET | `/api/v1/trading/agents/{id}` | [`getAgent`](#op-getAgent) — One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state | `agents:read` | — |1306| GET | `/api/v1/trading/agents/{id}/signals` | [`listAgentSignals`](#op-listAgentSignals) — Signal history of one agent, ONE mode | `agents:read` | — |1307| GET | `/api/v1/trading/agents/{id}/journal` | [`listAgentJournal`](#op-listAgentJournal) — Activity journal of one agent, ONE mode | `agents:read` | — |1308| GET | `/api/v1/trading/agents/{id}/orders` | [`listAgentOrders`](#op-listAgentOrders) — Order history of one agent, ONE mode, in the unified order states | `agents:read` | — |1309| GET | `/api/v1/trading/agents/{id}/performance` | [`getAgentPerformance`](#op-getAgentPerformance) — Computed performance of one agent, ONE mode | `agents:read` | — |1310| GET | `/api/v1/trading/jobs/{id}` | [`getJob`](#op-getJob) — One agent job (backtest, wind-down): status and result | `agents:read` | — |1311| POST | `/api/v1/trading/agents/{id}/start` | [`startAgent`](#op-startAgent) — Start an agent in research, paper or live mode | `agents:manage` | required |1312| POST | `/api/v1/trading/agents/{id}/pause` | [`pauseAgent`](#op-pauseAgent) — Pause an agent | `agents:manage` | required |1313| POST | `/api/v1/trading/agents/{id}/stop` | [`stopAgent`](#op-stopAgent) — Stop an agent (always allowed) | `agents:manage` | required |1314| POST | `/api/v1/trading/agents/{id}/backtest` | [`backtestAgent`](#op-backtestAgent) — Run a backtest for an agent (asynchronous job) | `agents:manage` | required |13151316<a id="tag-meta"></a>13171318### Meta13191320The contract itself.13211322<a id="op-getOpenApi"></a>13231324#### GET `/api/v1/trading/openapi.json`13251326**This document.** Operation id `getOpenApi`.13271328- **Permission:** any valid key1329- **Idempotency-Key:** not used1330- **Side effects:** none (a read)13311332OpenAPI 3.1 document generated from the route schemas. Any valid key or the owner session.13331334**Example request**13351336```bash1337curl -s "$SP_WALLET_BASE_URL/api/v1/trading/openapi.json" \1338  -H "Authorization: Bearer $SP_WALLET_API_KEY"1339```13401341```ts1342const doc = await client.openapi();1343```13441345```python1346doc = client.openapi()1347```13481349**Example response** — 200, written from the schema (not recorded). Cut: the real document describes every operation, schema and error code.13501351```json1352{1353  "openapi": "3.1.0",1354  "info": {1355    "title": "SP Trading API",1356    "version": "1.0.0"1357  },1358  "paths": {1359    "/api/v1/trading/markets": {1360      "get": {1361        "operationId": "listMarkets"1362      }1363    }1364  }1365}1366```13671368<details><summary><b>Response fields</b></summary>13691370| Field | Type | Required | Description |1371|---|---|---|---|1372| `openapi` | `string` | yes |  |13731374</details>13751376**Errors**13771378| Status | Codes |1379|---|---|1380| 401 | [`unauthenticated`](#err-unauthenticated) |1381| 403 | [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |1382| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |1383| 500 | [`internal`](#err-internal) |13841385<a id="tag-markets"></a>13861387### Markets13881389Public market data: instruments across venues, tickers, order books, candles, the venue comparator, and the synthetic contracts on private companies. Scope `markets:read`. Reading a venue does not mean it can be traded: live orders with a key exist on Hyperliquid only.13901391<a id="op-listMarkets"></a>13921393#### GET `/api/v1/trading/markets`13941395**Instruments across venues (perpetuals) and the spot market-data symbols.** Operation id `listMarkets`.13961397- **Permission:** `markets:read`1398- **Idempotency-Key:** not used1399- **Side effects:** none (a read)14001401Each row carries the time its source produced it (`ts`) and a `stale` flag. A venue that cannot be read is listed in `errors`; when no source answers the call fails with 503. An unknown `venue` answers 404 `unknown_venue`. Not paginated: `total` and `truncated` tell when `limit` cut the list.14021403**Parameters**14041405| Name | In | Type | Required | Description |1406|---|---|---|---|---|1407| `venue` | query | `string` | — | venue id: hyperliquid, gmx, dydx, spot — 0–40 characters |1408| `kind` | query | `"perpetual" \| "spot"` | — | perpetual = a venue instrument; spot = a market-data symbol |1409| `q` | query | `string` | — | case-insensitive match on id, symbol or base — 0–40 characters |1410| `limit` | query | `integer 1…5000` | — | rows returned at most; `total` and `truncated` say when it cut the list — default 2000 |14111412**Example request**14131414```bash1415curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \1416  -H "Authorization: Bearer $SP_WALLET_API_KEY"1417```14181419```ts1420const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });1421```14221423```python1424markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets1425```14261427**Example response** — 200, recorded from a real server14281429```json1430{1431  "markets": [1432    {1433      "id": "hyperliquid:BTC",1434      "venue": "hyperliquid",1435      "kind": "perpetual",1436      "symbol": "BTC",1437      "base": "BTC",1438      "quote": "USD",1439      "status": "active",1440      "mark": "64432",1441      "index": "64460.7",1442      "funding": "0.0000089721",1443      "fundingIntervalSec": 3600,1444      "volume24h": "3621656019.2002997398",1445      "openInterest": "37680.57528",1446      "maxLeverage": "40",1447      "tickSize": "0.1",1448      "lotSize": "0.00001",1449      "collateral": "USDC",1450      "restriction": null,1451      "ts": 1794953721101,1452      "stale": false,1453      "source": "venue"1454    }1455  ],1456  "total": 1,1457  "truncated": false,1458  "errors": [],1459  "ts": 17949537211031460}1461```14621463<details><summary><b>Response fields</b></summary>14641465| Field | Type | Required | Description |1466|---|---|---|---|1467| `markets` | `array of object` | yes |  |1468| `markets[].id` | `string` | yes |  |1469| `markets[].venue` | `string` | yes |  |1470| `markets[].kind` | `"perpetual" \| "spot"` | yes |  |1471| `markets[].symbol` | `string` | yes |  |1472| `markets[].base` | `string` | yes |  |1473| `markets[].quote` | `string` | yes |  |1474| `markets[].status` | `string` | yes |  |1475| `markets[].mark` | `string \| null` | yes |  |1476| `markets[].ts` | `integer -9007199254740991…9007199254740991 \| null` | yes | time the source produced this row (venue read time, or the last consolidated bar for spot) |1477| `markets[].stale` | `boolean` | yes | true when the row is older than its freshness bound or the source could not be refreshed |1478| `total` | `integer -9007199254740991…9007199254740991` | yes | rows matching the filters, before `limit` |1479| `truncated` | `boolean` | yes |  |1480| `errors` | `array of object` | yes |  |1481| `errors[].source` | `string` | yes |  |1482| `errors[].message` | `string` | yes |  |1483| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |14841485</details>14861487**Errors**14881489| Status | Codes |1490|---|---|1491| 400 | [`bad_request`](#err-bad_request) |1492| 401 | [`unauthenticated`](#err-unauthenticated) |1493| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |1494| 404 | [`unknown_venue`](#err-unknown_venue) |1495| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |1496| 500 | [`internal`](#err-internal) |1497| 503 | [`markets_unavailable`](#err-markets_unavailable), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |14981499<a id="op-compareMarkets"></a>15001501#### GET `/api/v1/trading/markets/compare`15021503**Compare the estimated cost of one position across venues.** Operation id `compareMarkets`.15041505- **Permission:** `markets:read`1506- **Idempotency-Key:** not used1507- **Side effects:** none (a read)15081509One row per venue for a common underlying, from the real instrument, order book (GMX: pool figures), ticker, fee schedule and funding rate read now: spread, depth within 10/25/50 bps, slippage for the notional, fees, funding expected over the horizon (current rate held constant), collateral, liquidation estimate and the itemised total. Every figure is an estimate; a missing input gives null with its reason. Venues the wallet cannot trade on are shown and flagged. `discrepancies` are estimates with their assumptions and risks, never a recommendation.15101511**Parameters**15121513| Name | In | Type | Required | Description |1514|---|---|---|---|---|1515| `underlying` | query | `string` | — | common underlying, e.g. BTC (see GET /markets-hub/underlyings) — default "BTC" · pattern ^[A-Za-z0-9]{1,15}$ |1516| `side` | query | `"long" \| "short"` | — | direction of the position compared — default "long" |1517| `notional` | query | `string` | — | position notional in USD (not the collateral) — default "1000" · pattern ^(0\|[1-9]\d{0,11})(\.\d{1,8})?$ |1518| `leverage` | query | `string` | — | leverage of the position: collateral = notional / leverage — default "1" · pattern ^(0\|[1-9]\d{0,11})(\.\d{1,8})?$ |1519| `horizonHours` | query | `string` | — | expected holding period; funding is the current rate held constant over it — default "24" · pattern ^(0\|[1-9]\d{0,3})(\.\d{1,4})?$ |1520| `liquidity` | query | `"taker" \| "maker"` | — | how the entry and the exit are executed, for the fee — default "taker" |1521| `minNetEdgeBps` | query | `string` | — | a discrepancy estimate above this is flagged — default "0" · pattern ^(0\|[1-9]\d{0,4})(\.\d{1,4})?$ |15221523**Example request**15241525```bash1526curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/compare?underlying=BTC&side=long&notional=1000&leverage=2" \1527  -H "Authorization: Bearer $SP_WALLET_API_KEY"1528```15291530```ts1531const cmp = await client.compareMarkets({ underlying: 'BTC', side: 'long', notional: '1000', leverage: '2' });1532```15331534```python1535cmp = client.compare_markets(underlying="BTC", side="long", notional="1000", leverage="2")1536```15371538**Example response** — 200, recorded from a real server. Cut to one row and one discrepancy. dYdX and edgeX rows are information: `tradable` is false on them.15391540```json1541{1542  "underlying": "BTC",1543  "category": "crypto",1544  "request": {1545    "underlying": "BTC",1546    "side": "long",1547    "notionalUsd": "1000",1548    "leverage": "2",1549    "horizonHours": "24",1550    "liquidity": "taker",1551    "minNetEdgeBps": "0",1552    "depthBps": [1553      "10"1554    ]1555  },1556  "rows": [1557    {1558      "venue": "hyperliquid",1559      "venueName": "Hyperliquid",1560      "instrument": "hyperliquid:BTC",1561      "symbol": "BTC",1562      "underlying": "BTC",1563      "multiplier": "1",1564      "alternatives": [],1565      "tradable": true,1566      "tradableReason": null,1567      "restriction": null,1568      "priceOutlier": false,1569      "staleAfterMs": 15000,1570      "price": {1571        "mark": "64432",1572        "index": "64460.7",1573        "mid": "64432.5"1574      },1575      "depth": [1576        {1577          "bps": "10",1578          "bidUsd": "6193729.75994",1579          "askUsd": "9895537.37818",1580          "bidComplete": false,1581          "askComplete": false1582        }1583      ],1584      "depthReason": null,1585      "fees": {1586        "takerRate": "0.00045",1587        "makerRate": "0.00015",1588        "source": "base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fee…",1589        "asOf": "2026-11-10"1590      },1591      "funding": {1592        "rate": "0.0000089721",1593        "intervalSec": 3600,1594        "perHour": "0.0000089721",1595        "annualised": "0.0785956",1596        "assumption": "the venue's current rate held constant over the horizon; funding rates change every interval"1597      },1598      "maintenance": {1599        "fraction": "0.0125",1600        "basis": "1 / (2 × maximum leverage 40): half of the initial margin at the maximum leverage (1 / (2 × max leverage) of notional); tiered by position size — https://hyperliquid.gitbook.io/hyp…"1601      },1602      "cost": {1603        "venue": "hyperliquid",1604        "instrument": "hyperliquid:BTC",1605        "executionModel": "order_book",1606        "midPrice": {1607          "value": "64432.5",1608          "reason": null,1609          "basis": "(best bid + best ask) / 2"1610        },1611        "spreadBps": {1612          "value": "0.1552",1613          "reason": null,1614          "basis": "(best ask − best bid) / mid"1615        },1616        "depthBidUsd": {1617          "value": "6193729.75994",1618          "reason": null,1619          "basis": "Σ price × size of the bids within 10 bps of the mid, in the supplied book"1620        },1621        "depthAskUsd": {1622          "value": "9895537.37818",1623          "reason": null,1624          "basis": "Σ price × size of the asks within 10 bps of the mid, in the supplied book"1625        },1626        "sizeBase": {1627          "value": "0.01552",1628          "reason": null,1629          "basis": "notional / mid, rounded down to the lot"1630        },1631        "entryAvgPrice": {1632          "value": "64433",1633          "reason": null,1634          "basis": "average price of walking the book for the whole size"1635        },1636        "entrySlippageBps": {1637          "value": "0.0776",1638          "reason": null,1639          "basis": "|average entry price − mid| / mid"1640        },1641        "entrySlippageUsd": {1642          "value": "0.00776",1643          "reason": null,1644          "basis": "entry: average price of walking the book for the whole size vs the mid, half the spread included (router.walkBook)"1645        },1646        "exitSlippageUsd": {1647          "value": "0.00776",1648          "reason": null,1649          "basis": "exit, on the current book: average price of walking the book for the whole size vs the mid, half the spread included (router.walkBook)"1650        },1651        "entryFeeUsd": {1652          "value": "0.449997",1653          "reason": null,1654          "basis": "taker rate 0.00045 × notional — base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook…"1655        },1656        "exitFeeUsd": {1657          "value": "0.449997",1658          "reason": null,1659          "basis": "taker rate 0.00045 × notional — base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook…"1660        },1661        "fundingUsd": {1662          "value": "0.215329",1663          "reason": null,1664          "basis": "current rate 0.0000089721 per 3600 s (ticker.funding of the venue) held constant for 24 h on the position's notional; longs pay a positive rate"1665        },1666        "fundingRatePerHour": {1667          "value": "0.0000089721",1668          "reason": null,1669          "basis": "rate per 3600 s × 3600 / 3600"1670        },1671        "collateralRequiredUsd": {1672          "value": "499.9962",1673          "reason": null,1674          "basis": "notional / leverage, rounded up (margin.initialMargin)"1675        },1676        "liquidationPrice": {1677          "value": "32624.3037974684",1678          "reason": null,1679          "basis": "isolated, long: equity = maintenance at p; flat maintenance fraction, no fees; no funding accrual; margin = entry notional / leverage; entry at the estimated average entry price"1680        },1681        "liquidationDistanceBps": {1682          "value": "4936.7089",1683          "reason": null,1684          "basis": "|entry − liquidation price| / entry"1685        },1686        "maxLeverage": {1687          "value": "40",1688          "reason": null,1689          "basis": "the venue's maximum for the instrument"1690        },1691        "totalCostUsd": {1692          "value": "1.130843",1693          "reason": null,1694          "basis": "sum of entrySlippageUsd + exitSlippageUsd + entryFeeUsd + exitFeeUsd + fundingUsd"1695        },1696        "totalCostBps": {1697          "value": "11.3085",1698          "reason": null,1699          "basis": "total cost / position notional"1700        },1701        "missing": [],1702        "assumptions": [1703          "the position is opened and closed in full, each in one order"1704        ]1705      },1706      "sourceTs": {1707        "ticker": 1794953721101,1708        "book": 1794953722689,1709        "pool": null1710      },1711      "ageMs": 1936,1712      "stale": false,1713      "error": null1714    }1715  ],1716  "discrepancies": [1717    {1718      "longVenue": "edgex",1719      "shortVenue": "hyperliquid",1720      "longInstrument": "edgex:BTCUSDC",1721      "shortInstrument": "hyperliquid:BTC",1722      "grossGapBps": "8.6212",1723      "netEdgeEstimateBps": "-10.379",1724      "costsUsd": {1725        "feesUsd": "1.738914",1726        "exitSlippageUsd": "0.01425",1727        "fundingUsd": "0.081578"1728      },1729      "flagged": false,1730      "reason": null,1731      "actionableFromWallet": false,1732      "assumptions": [1733        {1734          "code": "disc_assume_1",1735          "text": "both legs are opened at the same time, in full, at the average prices of walking the two CURRENT books"1736        }1737      ],1738      "risks": [1739        {1740          "code": "disc_risk_1",1741          "text": "execution risk: one leg can fill and the other not, or at a worse price; the books move between the two orders"1742        }1743      ]1744    }1745  ],1746  "texts": {1747    "disclaimer": "Estimates computed from one snapshot of public market data. Not a quote and not a recommendation: the contracts differ between venues (collateral, price used for liquidation, funding rule, execution).",1748    "discrepancy": "netEdgeEstimateBps is the price difference between two venues net of fees on four legs, the exit slippage on both and the net funding over the horizon. It is an estimate under the …",1749    "assumptions": [1750      {1751        "code": "cost_1",1752        "text": "the position is opened and closed in full, each in one order"1753      }1754    ]1755  },1756  "warnings": [],1757  "errors": [],1758  "locks": [1759    {1760      "id": "deriv_live_mainnet",1761      "on": false1762    }1763  ],1764  "ts": 1794953723037,1765  "source": "estimate"1766}1767```17681769<details><summary><b>Response fields</b></summary>17701771| Field | Type | Required | Description |1772|---|---|---|---|1773| `underlying` | `string` | yes |  |1774| `category` | `string \| null` | yes |  |1775| `request` | `object` | yes |  |1776| `rows` | `array of object` | yes |  |1777| `rows[].venue` | `string` | yes |  |1778| `rows[].instrument` | `string` | yes |  |1779| `rows[].tradable` | `boolean` | yes | false: the wallet cannot trade this venue or instrument; the row is shown for information |1780| `rows[].tradableReason` | `string \| null` | yes |  |1781| `rows[].cost` | `object \| null` | yes | itemised estimate: every component is { value, reason, basis } — value null WITH the reason when an input is missing |1782| `rows[].priceOutlier` | `boolean` | yes |  |1783| `rows[].ageMs` | `number \| null` | yes |  |1784| `rows[].stale` | `boolean` | yes |  |1785| `discrepancies` | `array of object` | yes |  |1786| `discrepancies[].longVenue` | `string` | yes |  |1787| `discrepancies[].shortVenue` | `string` | yes |  |1788| `discrepancies[].netEdgeEstimateBps` | `string \| null` | yes | an ESTIMATE under `assumptions`, with `risks` |1789| `discrepancies[].flagged` | `boolean` | yes |  |1790| `discrepancies[].actionableFromWallet` | `boolean` | yes |  |1791| `discrepancies[].assumptions` | `array of object` | yes |  |1792| `discrepancies[].risks` | `array of object` | yes |  |1793| `texts` | `object` | yes |  |1794| `texts.disclaimer` | `string` | yes |  |1795| `warnings` | `array of string` | yes |  |1796| `errors` | `array of object` | yes |  |1797| `errors[].source` | `string` | yes |  |1798| `errors[].message` | `string` | yes |  |1799| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |1800| `source` | `string` | yes |  |18011802</details>18031804**Errors**18051806| Status | Codes |1807|---|---|1808| 400 | [`bad_request`](#err-bad_request) |1809| 401 | [`unauthenticated`](#err-unauthenticated) |1810| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |1811| 404 | [`unknown_underlying`](#err-unknown_underlying) |1812| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |1813| 500 | [`internal`](#err-internal) |1814| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |18151816<a id="op-getMarket"></a>18171818#### GET `/api/v1/trading/markets/{symbol}`18191820**One market: instrument, ticker and data quality.** Operation id `getMarket`.18211822- **Permission:** `markets:read`1823- **Idempotency-Key:** not used1824- **Side effects:** none (a read)18251826`instrument` carries what an order must respect: `lotSize`, `tickSize`, `minOrderSize`, `minNotional`, `maxLeverage`. A bare symbol that exists on several venues answers 409 `ambiguous_symbol` with the candidates. 404: `unknown_venue` (the part before the colon), `unknown_instrument` (the venue does not list it), `unknown_market` (a spot symbol without data, or a bare symbol nothing answers to).18271828**Parameters**18291830| Name | In | Type | Required | Description |1831|---|---|---|---|---|1832| `symbol` | path | `string` | yes | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous — 1–120 characters |18331834**Example request**18351836```bash1837curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC" \1838  -H "Authorization: Bearer $SP_WALLET_API_KEY"1839```18401841```ts1842const { instrument, ticker } = await client.getMarket('hyperliquid:BTC');1843```18441845```python1846market = client.get_market("hyperliquid:BTC")1847```18481849**Example response** — 200, recorded from a real server18501851```json1852{1853  "market": {1854    "id": "hyperliquid:BTC",1855    "venue": "hyperliquid",1856    "kind": "perpetual",1857    "symbol": "BTC",1858    "base": "BTC",1859    "quote": "USD",1860    "status": "active",1861    "mark": "64419",1862    "ts": 1794953786018,1863    "stale": false,1864    "source": "venue"1865  },1866  "instrument": {1867    "venue": "hyperliquid",1868    "symbol": "BTC",1869    "id": "hyperliquid:BTC",1870    "base": "BTC",1871    "quote": "USD",1872    "kind": "perpetual",1873    "collateral": "USDC",1874    "settlement": "Linear perpetual margined and settled in USDC; the oracle is USDT-denominated for most assets (quanto: USDT PnL paid in USDC, no conversion); funding every hour, peer to peer",1875    "tickSize": "0.1",1876    "lotSize": "0.00001",1877    "minOrderSize": null,1878    "minNotional": "10",1879    "maxLeverage": "40",1880    "marginModes": [1881      "cross",1882      "isolated"1883    ],1884    "fundingIntervalSec": 3600,1885    "markPriceMethod": "Median of (1) oracle + 150 s EMA of (Hyperliquid mid − oracle), (2) median of best bid, best ask, last trade, (3) weighted median of Binance, OKX, Bybit, Gate IO, MEXC perp mids; u…",1886    "status": "active"1887  },1888  "ticker": {1889    "instrument": "hyperliquid:BTC",1890    "mark": "64419",1891    "index": "64449.4",1892    "mid": "64418.5",1893    "funding": "0.0000087881",1894    "openInterest": "37684.5631",1895    "volume24h": "3622010181.9303812981",1896    "change24h": "-0.015692",1897    "ts": 1794953786018,1898    "source": "venue"1899  },1900  "quality": null,1901  "liquidity": null,1902  "hasOrderBook": true,1903  "errors": {},1904  "ts": 1794953786422,1905  "source": "venue"1906}1907```19081909<details><summary><b>Response fields</b></summary>19101911| Field | Type | Required | Description |1912|---|---|---|---|1913| `market` | `object` | yes |  |1914| `market.id` | `string` | yes |  |1915| `market.venue` | `string` | yes |  |1916| `market.kind` | `"perpetual" \| "spot"` | yes |  |1917| `market.symbol` | `string` | yes |  |1918| `market.base` | `string` | yes |  |1919| `market.quote` | `string` | yes |  |1920| `market.status` | `string` | yes |  |1921| `market.mark` | `string \| null` | yes |  |1922| `market.ts` | `integer -9007199254740991…9007199254740991 \| null` | yes | time the source produced this row (venue read time, or the last consolidated bar for spot) |1923| `market.stale` | `boolean` | yes | true when the row is older than its freshness bound or the source could not be refreshed |1924| `instrument` | `object \| null` | yes | null for a spot market-data symbol |1925| `instrument.id` | `string` | yes | `venue:symbol` |1926| `instrument.venue` | `string` | yes |  |1927| `instrument.symbol` | `string` | yes |  |1928| `instrument.base` | `string` | yes |  |1929| `instrument.quote` | `string` | yes |  |1930| `instrument.kind` | `"perpetual"` | yes |  |1931| `instrument.collateral` | `string` | yes |  |1932| `instrument.settlement` | `string` | yes |  |1933| `instrument.tickSize` | `string` | yes | price increment: a limit or trigger price is a multiple of it |1934| `instrument.lotSize` | `string` | yes | size increment: an order size is a multiple of it |1935| `instrument.minOrderSize` | `string \| null` | yes | smallest order size, base units; null when the venue states none |1936| `instrument.minNotional` | `string \| null` | yes | smallest order value, quote currency; null when the venue states none |1937| `instrument.maxLeverage` | `string` | yes | decimal number as a string (never a float) |1938| `instrument.marginModes` | `array of "cross" \| "isolated"` | yes |  |1939| `instrument.fundingIntervalSec` | `integer -9007199254740991…9007199254740991` | yes |  |1940| `instrument.markPriceMethod` | `string` | yes |  |1941| `instrument.status` | `"active" \| "reduce_only" \| "halted"` | yes |  |1942| `instrument.category` | `"crypto" \| "equity" \| "pre_ipo" \| "commodity" \| "fx"` | — | what the underlying is, when the venue's own metadata says it |1943| `ticker` | `object \| null` | yes |  |1944| `ticker.instrument` | `string` | yes |  |1945| `ticker.mark` | `string` | yes | decimal number as a string (never a float) |1946| `ticker.index` | `string \| null` | yes |  |1947| `ticker.mid` | `string \| null` | yes |  |1948| `ticker.funding` | `string \| null` | yes | per funding interval |1949| `ticker.openInterest` | `string \| null` | yes |  |1950| `ticker.volume24h` | `string \| null` | yes |  |1951| `ticker.change24h` | `string \| null` | yes |  |1952| `ticker.ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |1953| `quality` | `object \| null` | yes | spot only: data quality per interval |1954| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |1955| `source` | `string` | yes |  |19561957</details>19581959**Errors**19601961| Status | Codes |1962|---|---|1963| 400 | [`bad_request`](#err-bad_request) |1964| 401 | [`unauthenticated`](#err-unauthenticated) |1965| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |1966| 404 | [`unknown_instrument`](#err-unknown_instrument), [`unknown_market`](#err-unknown_market), [`unknown_venue`](#err-unknown_venue) |1967| 409 | [`ambiguous_symbol`](#err-ambiguous_symbol) |1968| 422 | [`venue_rejected`](#err-venue_rejected) |1969| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |1970| 500 | [`internal`](#err-internal) |1971| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |19721973<a id="op-getOrderbook"></a>19741975#### GET `/api/v1/trading/markets/{symbol}/orderbook`19761977**Order book of one market.** Operation id `getOrderbook`.19781979- **Permission:** `markets:read`1980- **Idempotency-Key:** not used1981- **Side effects:** none (a read)19821983Venues without an order book (GMX, spot data) answer 422 `no_orderbook`.19841985**Parameters**19861987| Name | In | Type | Required | Description |1988|---|---|---|---|---|1989| `symbol` | path | `string` | yes | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous — 1–120 characters |1990| `depth` | query | `integer 1…50` | — | price levels per side — default 20 |19911992**Example request**19931994```bash1995curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/orderbook?depth=3" \1996  -H "Authorization: Bearer $SP_WALLET_API_KEY"1997```19981999```ts2000const book = await client.getOrderbook('hyperliquid:BTC', { depth: 3 });2001```20022003```python2004book = client.get_orderbook("hyperliquid:BTC", depth=3)2005```20062007**Example response** — 200, recorded from a real server20082009```json2010{2011  "id": "hyperliquid:BTC",2012  "bids": [2013    [2014      "64432",2015      "0.43796"2016    ],2017    [2018      "64431",2019      "0.00036"2020    ],2021    [2022      "64426",2023      "0.0015"2024    ]2025  ],2026  "asks": [2027    [2028      "64433",2029      "27.19556"2030    ],2031    [2032      "64434",2033      "2.14586"2034    ],2035    [2036      "64435",2037      "10.15654"2038    ]2039  ],2040  "ts": 1794953722689,2041  "stale": false,2042  "source": "venue"2043}2044```20452046<details><summary><b>Response fields</b></summary>20472048| Field | Type | Required | Description |2049|---|---|---|---|2050| `id` | `string` | yes |  |2051| `bids` | `array of [string, string]` | yes |  |2052| `asks` | `array of [string, string]` | yes |  |2053| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |2054| `stale` | `boolean` | yes |  |2055| `source` | `string` | yes |  |20562057</details>20582059**Errors**20602061| Status | Codes |2062|---|---|2063| 400 | [`bad_request`](#err-bad_request) |2064| 401 | [`unauthenticated`](#err-unauthenticated) |2065| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |2066| 404 | [`unknown_instrument`](#err-unknown_instrument), [`unknown_market`](#err-unknown_market), [`unknown_venue`](#err-unknown_venue) |2067| 409 | [`ambiguous_symbol`](#err-ambiguous_symbol) |2068| 422 | [`no_orderbook`](#err-no_orderbook), [`venue_rejected`](#err-venue_rejected) |2069| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |2070| 500 | [`internal`](#err-internal) |2071| 503 | [`stale_data`](#err-stale_data), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |20722073<a id="op-getCandles"></a>20742075#### GET `/api/v1/trading/markets/{symbol}/candles`20762077**Closed bars of one market.** Operation id `getCandles`.20782079- **Permission:** `markets:read`2080- **Idempotency-Key:** not used2081- **Side effects:** none (a read)20822083Spot market data has fewer intervals than the venues: an interval it does not store answers 422 `unsupported_interval`.20842085**Parameters**20862087| Name | In | Type | Required | Description |2088|---|---|---|---|---|2089| `symbol` | path | `string` | yes | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous — 1–120 characters |2090| `interval` | query | `"1m" \| "5m" \| "15m" \| "1h" \| "4h" \| "1d"` | — | bar length — default "1h" |2091| `limit` | query | `integer 1…1000` | — | most recent closed bars, oldest first in the answer — default 200 |20922093**Example request**20942095```bash2096curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/candles?interval=1h&limit=3" \2097  -H "Authorization: Bearer $SP_WALLET_API_KEY"2098```20992100```ts2101const { candles } = await client.getCandles('hyperliquid:BTC', { interval: '1h', limit: 3 });2102```21032104```python2105candles = client.get_candles("hyperliquid:BTC", interval="1h", limit=3).candles2106```21072108**Example response** — 200, recorded from a real server21092110```json2111{2112  "id": "hyperliquid:BTC",2113  "interval": "1h",2114  "candles": [2115    {2116      "ts": 1794945600000,2117      "open": "63727",2118      "high": "64075",2119      "low": "63666",2120      "close": "63964",2121      "volume": "1914.97454"2122    },2123    {2124      "ts": 1794949200000,2125      "open": "63964",2126      "high": "64645",2127      "low": "63925",2128      "close": "64331",2129      "volume": "3580.64025"2130    }2131  ],2132  "ts": 1794953723670,2133  "stale": false,2134  "source": "venue"2135}2136```21372138<details><summary><b>Response fields</b></summary>21392140| Field | Type | Required | Description |2141|---|---|---|---|2142| `id` | `string` | yes |  |2143| `interval` | `string` | yes |  |2144| `candles` | `array of object` | yes |  |2145| `candles[].ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |2146| `candles[].open` | `string` | yes | decimal number as a string (never a float) |2147| `candles[].high` | `string` | yes | decimal number as a string (never a float) |2148| `candles[].low` | `string` | yes | decimal number as a string (never a float) |2149| `candles[].close` | `string` | yes | decimal number as a string (never a float) |2150| `candles[].volume` | `string` | yes | decimal number as a string (never a float) |2151| `ts` | `integer -9007199254740991…9007199254740991 \| null` | yes |  |2152| `stale` | `boolean` | yes |  |2153| `source` | `string` | yes |  |21542155</details>21562157**Errors**21582159| Status | Codes |2160|---|---|2161| 400 | [`bad_request`](#err-bad_request) |2162| 401 | [`unauthenticated`](#err-unauthenticated) |2163| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |2164| 404 | [`unknown_instrument`](#err-unknown_instrument), [`unknown_market`](#err-unknown_market), [`unknown_venue`](#err-unknown_venue) |2165| 409 | [`ambiguous_symbol`](#err-ambiguous_symbol) |2166| 422 | [`unsupported_interval`](#err-unsupported_interval), [`venue_rejected`](#err-venue_rejected) |2167| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |2168| 500 | [`internal`](#err-internal) |2169| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |21702171<a id="op-listPrivateMarkets"></a>21722173#### GET `/api/v1/trading/private-markets`21742175**Synthetic contracts on private companies, venue by venue, with sourced valuations.** Operation id `listPrivateMarkets`.21762177- **Permission:** `markets:read`2178- **Idempotency-Key:** not used2179- **Side effects:** none (a read)21802181Live discovery (Hyperliquid builder dexes categorised `preipo`, edgeX `pre_ipo`) joined with a reviewed contract table. Five quantities are separate fields: synthetic price, contract market value, notional exposure, implied valuation estimate (or null + reason), last known private valuation. A venue that cannot be read gives rows with `error`; the others answer. Venues are never averaged.21822183**Parameters**21842185| Name | In | Type | Required | Description |2186|---|---|---|---|---|2187| `delisted` | query | `"true" \| "false"` | — | true: only delisted markets (frozen prices) |2188| `size` | query | `string` | — | hypothetical position size, contracts (default 1) — pattern ^(0\|[1-9]\d{0,11})(\.\d{1,8})?$ |2189| `side` | query | `"long" \| "short"` | — | side of the hypothetical position (default long) |21902191**Example request**21922193```bash2194curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets" \2195  -H "Authorization: Bearer $SP_WALLET_API_KEY"2196```21972198```ts2199const { markets, companies } = await client.listPrivateMarkets();2200```22012202```python2203private = client.list_private_markets()2204```22052206**Example response** — 200, recorded from a real server. Cut to one market. Display only: `tradable` is always false.22072208```json2209{2210  "markets": [2211    {2212      "id": "hyperliquid:io:ANTH",2213      "venue": "hyperliquid",2214      "platform": "Hyperliquid · EntropyIO (dex io)",2215      "operator": "EntropyIO",2216      "symbol": "io:ANTH",2217      "company": {2218        "slug": "anthropic",2219        "name": "Anthropic, PBC"2220      },2221      "status": "live",2222      "review": {2223        "state": "reviewed",2224        "reasons": [],2225        "reviewedAt": "2026-11-15",2226        "validUntil": "2026-11-18T00:00:00Z",2227        "fingerprintChecked": true2228      },2229      "contract": {2230        "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",2231        "unit": {2232          "kind": "valuation_usd_billions",2233          "label": "USD billions of fully diluted company valuation (1.00 = $1B)"2234        },2235        "quoteCurrency": "USD",2236        "collateral": "USDC",2237        "underlying": "Anthropic, PBC",2238        "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",2239        "multiplier": {2240          "value": "1",2241          "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"2242        },2243        "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",2244        "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",2245        "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",2246        "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",2247        "maxLeverage": "15",2248        "margin": "cross_allowed",2249        "lotSize": "0.001",2250        "szDecimals": 3,2251        "fundingIntervalSec": 3600,2252        "assetId": 200001,2253        "dex": "io",2254        "oiCapUsd": "275000000",2255        "fundingMultiplier": "0.125",2256        "onChainDescription": "",2257        "unconfirmedConvention": null,2258        "sources": [2259          "https://docs.entropy.io/market-types/pre-ipo-perpetuals"2260        ]2261      },2262      "market": {2263        "price": {2264          "value": "1683.9",2265          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",2266          "ts": 1794953724740,2267          "stale": false2268        },2269        "oracle": {2270          "value": "1684",2271          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",2272          "ts": 1794953724740,2273          "stale": false2274        },2275        "mid": {2276          "value": "1680.6",2277          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",2278          "ts": 1794953724740,2279          "stale": false2280        },2281        "funding": {2282          "value": "-0.0000113686",2283          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",2284          "ts": 1794953724740,2285          "stale": false,2286          "intervalSec": 36002287        },2288        "openInterest": {2289          "value": "117475.832",2290          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",2291          "ts": 1794953724740,2292          "stale": false2293        },2294        "openInterestUsd": {2295          "value": "197817553.5048",2296          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",2297          "ts": 1794953724740,2298          "stale": false2299        },2300        "volume24h": {2301          "value": "34445966.2849999964",2302          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",2303          "ts": 1794953724740,2304          "stale": false2305        },2306        "volumeBase24h": {2307          "value": "20388.063",2308          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",2309          "ts": 1794953724740,2310          "stale": false2311        },2312        "frozen": false2313      },2314      "valuation": {2315        "syntheticPrice": {2316          "value": "1683.9",2317          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",2318          "ts": 1794953724740,2319          "stale": false,2320          "unit": "valuation_usd_billions",2321          "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",2322          "priceKind": "mark"2323        },2324        "contractMarketValue": {2325          "value": "1683.9",2326          "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",2327          "reason": null,2328          "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",2329          "ts": 17949537247402330        },2331        "notionalExposure": {2332          "value": "1683.9",2333          "formula": "size × contract value, negative for a short",2334          "reason": null,2335          "position": {2336            "side": "long",2337            "size": "1"2338          },2339          "hypothetical": true,2340          "ts": 17949537247402341        },2342        "impliedValuation": {2343          "value": "1683900000000",2344          "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",2345          "formulaId": "price_x_1e9",2346          "formulaSource": {2347            "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",2348            "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",2349            "readAt": "2026-11-15"2350          },2351          "asOf": 1794953724740,2352          "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",2353          "reason": null,2354          "reasonCode": null2355        },2356        "lastPrivateValuation": {2357          "value": "965000000000",2358          "kind": "primary_round",2359          "detail": "Series H, $65B raised, post-money",2360          "date": "2026-05-28",2361          "sourceUrl": "https://www.anthropic.com/news/series-h",2362          "confidence": "high"2363        },2364        "lastPrivateValuationReason": null,2365        "premiumDiscount": {2366          "premiumBps": "7449.7409",2367          "reason": null,2368          "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"2369        },2370        "caveats": [2371          {2372            "code": "synthetic",2373            "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"2374          }2375        ]2376      },2377      "tradable": false,2378      "notTradable": {2379        "code": "builder_dex_read_only",2380        "reasons": [2381          "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"2382        ]2383      },2384      "error": null2385    }2386  ],2387  "companies": [2388    {2389      "slug": "anthropic",2390      "name": "Anthropic, PBC",2391      "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date.",2392      "contracts": [2393        "hyperliquid:io:ANTH"2394      ],2395      "lastPrivateValuation": {2396        "value": "965000000000",2397        "kind": "primary_round",2398        "detail": "Series H, $65B raised, post-money",2399        "date": "2026-05-28",2400        "sourceUrl": "https://www.anthropic.com/news/series-h",2401        "confidence": "high"2402      },2403      "divergence": [2404        {2405          "unit": "usd_per_share",2406          "unitLabel": "USD per 1 share (share class not specified by the operator)",2407          "contracts": [2408            {2409              "id": "hyperliquid:para:ANTH",2410              "price": "96.26",2411              "ts": 17949537248432412            }2413          ],2414          "spreadBps": "7.58",2415          "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"2416        }2417      ]2418    }2419  ],2420  "excluded": [2421    {2422      "id": "hyperliquid:xyz:SPCX",2423      "company": "SpaceX",2424      "reason": "SpaceX is a listed company (Nasdaq: SPCX): the deployer annotates this market as a listed stock and categorises it `stocks`. Not a private market.",2425      "liveCategory": "stocks",2426      "delisted": false2427    }2428  ],2429  "venues": [2430    {2431      "venue": "hyperliquid",2432      "name": "Hyperliquid (builder-deployed dexes)",2433      "status": "ok",2434      "error": null,2435      "ts": 1794953723863,2436      "instruments": 52437    }2438  ],2439  "venuesWithoutAdapter": [2440    {2441      "venue": "Aster",2442      "note": "ANTHROPICUSDT, OPENAIUSDT, POLYMARKETUSD1, OURAUSD1, MOONSHOTUSD1 — per share against a notional reference count of 1 billion shares"2443    }2444  ],2445  "notice": {2446    "tradable": false,2447    "code": "private_markets_display_only",2448    "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"2449  },2450  "filter": {2451    "delisted": false2452  },2453  "position": {2454    "side": "long",2455    "size": "1"2456  },2457  "cache": {2458    "discovery": {2459      "ttl": 60000,2460      "maxAge": 9000002461    },2462    "markets": {2463      "ttl": 20000,2464      "maxAge": 1200002465    },2466    "delisted": {2467      "ttl": 600000,2468      "maxAge": 36000002469    },2470    "annotation": {2471      "ttl": 600000,2472      "maxAge": 36000002473    },2474    "book": {2475      "ttl": 5000,2476      "maxAge": 300002477    },2478    "candles": {2479      "ttl": 60000,2480      "maxAge": 6000002481    },2482    "edgexTickers": {2483      "ttl": 3000,2484      "maxAge": 150002485    },2486    "edgexInstruments": {2487      "ttl": 600000,2488      "maxAge": 36000002489    },2490    "staleAfter": {2491      "hyperliquid": 60000,2492      "edgex": 150002493    }2494  },2495  "reviewedTable": {2496    "entries": 10,2497    "reviewedAt": "2026-11-15"2498  },2499  "ts": 1794953725186,2500  "source": "venue"2501}2502```25032504<details><summary><b>Response fields</b></summary>25052506| Field | Type | Required | Description |2507|---|---|---|---|2508| `markets` | `array of object` | yes |  |2509| `markets[].id` | `string` | yes |  |2510| `markets[].venue` | `string` | yes |  |2511| `markets[].platform` | `string` | yes |  |2512| `markets[].symbol` | `string` | yes |  |2513| `markets[].company` | `object \| null` | yes |  |2514| `markets[].status` | `"live" \| "delisted" \| "halted" \| "reduce_only"` | yes |  |2515| `markets[].review` | `object` | yes |  |2516| `markets[].contract` | `object` | yes |  |2517| `markets[].market` | `object` | yes |  |2518| `markets[].valuation` | `object` | yes |  |2519| `markets[].tradable` | `false` | yes |  |2520| `markets[].notTradable` | `object` | yes |  |2521| `markets[].error` | `string \| null` | yes |  |2522| `companies` | `array of object` | yes |  |2523| `companies[].slug` | `string` | yes |  |2524| `companies[].name` | `string` | yes |  |2525| `companies[].contracts` | `array of string` | yes |  |2526| `excluded` | `array of object` | yes |  |2527| `excluded[].id` | `string` | yes |  |2528| `excluded[].reason` | `string` | yes |  |2529| `venues` | `array of object` | yes |  |2530| `venues[].venue` | `string` | yes |  |2531| `venues[].status` | `"ok" \| "stale" \| "error"` | yes |  |2532| `venues[].error` | `string \| null` | yes |  |2533| `notice` | `object` | yes |  |2534| `notice.tradable` | `false` | yes |  |2535| `notice.code` | `string` | yes |  |2536| `notice.text` | `string` | yes |  |2537| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |25382539</details>25402541**Errors**25422543| Status | Codes |2544|---|---|2545| 400 | [`bad_request`](#err-bad_request) |2546| 401 | [`unauthenticated`](#err-unauthenticated) |2547| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |2548| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |2549| 500 | [`internal`](#err-internal) |2550| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |25512552<a id="op-getPrivateMarketCompany"></a>25532554#### GET `/api/v1/trading/private-markets/companies/{slug}`25552556**Every contract on one private company, side by side (never merged).** Operation id `getPrivateMarketCompany`.25572558- **Permission:** `markets:read`2559- **Idempotency-Key:** not used2560- **Side effects:** none (a read)25612562The contracts that reference one company (`slug` from GET /private-markets, `companies`), each on its own row with its own unit and valuation breakdown, plus the delisted ones and the sourced private-valuation references. `merged` is always null: a figure of one venue is never combined with another's. Display only: none of these contracts is tradable from this wallet.25632564**Parameters**25652566| Name | In | Type | Required | Description |2567|---|---|---|---|---|2568| `slug` | path | `string` | yes | company slug, from GET /private-markets (`companies[].slug`), e.g. `anthropic` — pattern ^[a-z0-9-]{1,40}$ |2569| `size` | query | `string` | — | hypothetical position size, contracts (default 1) — pattern ^(0\|[1-9]\d{0,11})(\.\d{1,8})?$ |2570| `side` | query | `"long" \| "short"` | — | side of the hypothetical position (default long) |2571| `interval` | query | `"1h" \| "1d"` | — | candle length |2572| `limit` | query | `integer 1…500` | — | candles returned at most |25732574**Example request**25752576```bash2577curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets/companies/anthropic" \2578  -H "Authorization: Bearer $SP_WALLET_API_KEY"2579```25802581```ts2582const company = await client.getPrivateMarketCompany('anthropic');2583```25842585```python2586company = client.get_private_market_company("anthropic")2587```25882589**Example response** — 200, recorded from a real server. Cut to one contract.25902591```json2592{2593  "company": {2594    "slug": "anthropic",2595    "name": "Anthropic, PBC",2596    "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date."2597  },2598  "contracts": [2599    {2600      "id": "hyperliquid:io:ANTH",2601      "venue": "hyperliquid",2602      "platform": "Hyperliquid · EntropyIO (dex io)",2603      "operator": "EntropyIO",2604      "symbol": "io:ANTH",2605      "company": {2606        "slug": "anthropic",2607        "name": "Anthropic, PBC"2608      },2609      "status": "live",2610      "review": {2611        "state": "reviewed",2612        "reasons": [],2613        "reviewedAt": "2026-11-15",2614        "validUntil": "2026-11-18T00:00:00Z",2615        "fingerprintChecked": true2616      },2617      "contract": {2618        "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",2619        "unit": {2620          "kind": "valuation_usd_billions",2621          "label": "USD billions of fully diluted company valuation (1.00 = $1B)"2622        },2623        "quoteCurrency": "USD",2624        "collateral": "USDC",2625        "underlying": "Anthropic, PBC",2626        "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",2627        "multiplier": {2628          "value": "1",2629          "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"2630        },2631        "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",2632        "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",2633        "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",2634        "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",2635        "maxLeverage": "15",2636        "margin": "cross_allowed",2637        "lotSize": "0.001",2638        "szDecimals": 3,2639        "fundingIntervalSec": 3600,2640        "assetId": 200001,2641        "dex": "io",2642        "oiCapUsd": "275000000",2643        "fundingMultiplier": "0.125",2644        "onChainDescription": "",2645        "unconfirmedConvention": null,2646        "sources": [2647          "https://docs.entropy.io/market-types/pre-ipo-perpetuals"2648        ]2649      },2650      "market": {2651        "price": {2652          "value": "1683.9",2653          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",2654          "ts": 1794953724740,2655          "stale": false2656        },2657        "oracle": {2658          "value": "1684",2659          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",2660          "ts": 1794953724740,2661          "stale": false2662        },2663        "mid": {2664          "value": "1680.6",2665          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",2666          "ts": 1794953724740,2667          "stale": false2668        },2669        "funding": {2670          "value": "-0.0000113686",2671          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",2672          "ts": 1794953724740,2673          "stale": false,2674          "intervalSec": 36002675        },2676        "openInterest": {2677          "value": "117475.832",2678          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",2679          "ts": 1794953724740,2680          "stale": false2681        },2682        "openInterestUsd": {2683          "value": "197817553.5048",2684          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",2685          "ts": 1794953724740,2686          "stale": false2687        },2688        "volume24h": {2689          "value": "34445966.2849999964",2690          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",2691          "ts": 1794953724740,2692          "stale": false2693        },2694        "volumeBase24h": {2695          "value": "20388.063",2696          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",2697          "ts": 1794953724740,2698          "stale": false2699        },2700        "frozen": false2701      },2702      "valuation": {2703        "syntheticPrice": {2704          "value": "1683.9",2705          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",2706          "ts": 1794953724740,2707          "stale": false,2708          "unit": "valuation_usd_billions",2709          "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",2710          "priceKind": "mark"2711        },2712        "contractMarketValue": {2713          "value": "1683.9",2714          "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",2715          "reason": null,2716          "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",2717          "ts": 17949537247402718        },2719        "notionalExposure": {2720          "value": "1683.9",2721          "formula": "size × contract value, negative for a short",2722          "reason": null,2723          "position": {2724            "side": "long",2725            "size": "1"2726          },2727          "hypothetical": true,2728          "ts": 17949537247402729        },2730        "impliedValuation": {2731          "value": "1683900000000",2732          "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",2733          "formulaId": "price_x_1e9",2734          "formulaSource": {2735            "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",2736            "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",2737            "readAt": "2026-11-15"2738          },2739          "asOf": 1794953724740,2740          "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",2741          "reason": null,2742          "reasonCode": null2743        },2744        "lastPrivateValuation": {2745          "value": "965000000000",2746          "kind": "primary_round",2747          "detail": "Series H, $65B raised, post-money",2748          "date": "2026-05-28",2749          "sourceUrl": "https://www.anthropic.com/news/series-h",2750          "confidence": "high"2751        },2752        "lastPrivateValuationReason": null,2753        "premiumDiscount": {2754          "premiumBps": "7449.7409",2755          "reason": null,2756          "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"2757        },2758        "caveats": [2759          {2760            "code": "synthetic",2761            "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"2762          }2763        ]2764      },2765      "tradable": false,2766      "notTradable": {2767        "code": "builder_dex_read_only",2768        "reasons": [2769          "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"2770        ]2771      },2772      "error": null2773    }2774  ],2775  "delisted": [2776    {2777      "id": "hyperliquid:vntl:ANTHROPIC",2778      "venue": "hyperliquid",2779      "platform": "Hyperliquid · Ventuals (dex vntl) — shut down",2780      "operator": "Ventuals",2781      "symbol": "vntl:ANTHROPIC",2782      "company": {2783        "slug": "anthropic",2784        "name": "Anthropic, PBC"2785      },2786      "status": "delisted",2787      "review": {2788        "state": "reviewed",2789        "reasons": [],2790        "reviewedAt": "2026-11-15",2791        "validUntil": null,2792        "fingerprintChecked": true2793      },2794      "contract": {2795        "nature": "cash-settled perpetual, pure synthetic — DELISTED: Ventuals shut down on 15 Jun 2026 and its markets were settled",2796        "unit": {2797          "kind": "valuation_usd_billions",2798          "label": "USD billions of company valuation (historical)"2799        },2800        "quoteCurrency": "USD",2801        "collateral": "USDH",2802        "underlying": "Anthropic, PBC",2803        "contractSize": "1 contract = 1 unit of ANTHROPIC; smallest size 0.001",2804        "multiplier": {2805          "value": "1",2806          "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"2807        },2808        "settlement": "Settled at the 24 h mark TWAP 1618.90 on 15 Jun 2026 (Ventuals sunset guide).",2809        "ipoConversion": "not applicable (settled)",2810        "oracle": "Was 1/3 Notice price + 2/3 two-hour EMA of the mark (Ventuals documentation).",2811        "liquidation": "not applicable (no open position can exist)",2812        "maxLeverage": "3",2813        "margin": "strict_isolated",2814        "lotSize": "0.001",2815        "szDecimals": 3,2816        "fundingIntervalSec": 3600,2817        "assetId": 130002,2818        "dex": "vntl",2819        "oiCapUsd": "10000000",2820        "fundingMultiplier": "0",2821        "onChainDescription": "ANTHROPIC tracks the total valuation of Anthropic, in billions. E.g. if 1 ANTHROPIC = $500, then the implied total valuation of the company is $500B.",2822        "unconfirmedConvention": null,2823        "sources": [2824          "https://docs.ventuals.com/perp-specifications/private-companies"2825        ]2826      },2827      "market": {2828        "price": {2829          "value": "1619.3",2830          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",2831          "ts": 1794953725593,2832          "stale": false2833        },2834        "oracle": {2835          "value": "1618.9",2836          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — oracle price",2837          "ts": 1794953725593,2838          "stale": false2839        },2840        "mid": {2841          "value": null,2842          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — book mid",2843          "ts": null,2844          "stale": false2845        },2846        "funding": {2847          "value": "0",2848          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — funding rate per interval",2849          "ts": 1794953725593,2850          "stale": false,2851          "intervalSec": 36002852        },2853        "openInterest": {2854          "value": "0",2855          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — open interest, contracts",2856          "ts": 1794953725593,2857          "stale": false2858        },2859        "openInterestUsd": {2860          "value": "0",2861          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",2862          "ts": 1794953725593,2863          "stale": false2864        },2865        "volume24h": {2866          "value": "0",2867          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h notional volume, USD",2868          "ts": 1794953725593,2869          "stale": false2870        },2871        "volumeBase24h": {2872          "value": "0",2873          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h volume, contracts",2874          "ts": 1794953725593,2875          "stale": false2876        },2877        "frozen": true2878      },2879      "valuation": {2880        "syntheticPrice": {2881          "value": "1619.3",2882          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",2883          "ts": 1794953725593,2884          "stale": false,2885          "unit": "valuation_usd_billions",2886          "unitLabel": "USD billions of company valuation (historical)",2887          "priceKind": "frozen mark"2888        },2889        "contractMarketValue": {2890          "value": null,2891          "formula": null,2892          "reason": "delisted market: the frozen price is not the value of a contract that can be held",2893          "source": null,2894          "ts": null2895        },2896        "notionalExposure": {2897          "value": null,2898          "formula": null,2899          "reason": "delisted market: the frozen price is not the value of a contract that can be held",2900          "position": {2901            "side": "long",2902            "size": "1"2903          },2904          "hypothetical": true,2905          "ts": null2906        },2907        "impliedValuation": {2908          "value": null,2909          "formula": null,2910          "formulaId": null,2911          "formulaSource": {2912            "url": "https://docs.ventuals.com/perp-specifications/private-companies",2913            "quote": "The price of the perp contract is the company valuation divided by 1 billion.",2914            "readAt": "2026-11-15"2915          },2916          "asOf": null,2917          "label": null,2918          "reason": "delisted market: the price is frozen at its last value of June 2026 and is not a current price — no valuation is derived from it",2919          "reasonCode": "delisted_frozen"2920        },2921        "lastPrivateValuation": {2922          "value": "965000000000",2923          "kind": "primary_round",2924          "detail": "Series H, $65B raised, post-money",2925          "date": "2026-05-28",2926          "sourceUrl": "https://www.anthropic.com/news/series-h",2927          "confidence": "high"2928        },2929        "lastPrivateValuationReason": null,2930        "premiumDiscount": {2931          "premiumBps": null,2932          "reason": "delisted market: the price is frozen at its last value of June 2026 and is not a current price — no valuation is derived from it",2933          "caveat": null2934        },2935        "caveats": [2936          {2937            "code": "synthetic",2938            "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"2939          }2940        ]2941      },2942      "tradable": false,2943      "notTradable": {2944        "code": "builder_dex_read_only",2945        "reasons": [2946          "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"2947        ]2948      },2949      "error": null2950    }2951  ],2952  "references": [2953    {2954      "company": "anthropic",2955      "valueUsd": "965000000000",2956      "kind": "primary_round",2957      "detail": "Series H, $65B raised, post-money",2958      "date": "2026-05-28",2959      "sourceUrl": "https://www.anthropic.com/news/series-h",2960      "confidence": "high",2961      "postMoney": true2962    }2963  ],2964  "lastPrivateValuation": {2965    "value": "965000000000",2966    "kind": "primary_round",2967    "detail": "Series H, $65B raised, post-money",2968    "date": "2026-05-28",2969    "sourceUrl": "https://www.anthropic.com/news/series-h",2970    "confidence": "high"2971  },2972  "divergence": [2973    {2974      "unit": "usd_per_share",2975      "unitLabel": "USD per 1 share (share class not specified by the operator)",2976      "contracts": [2977        {2978          "id": "hyperliquid:para:ANTH",2979          "price": "96.26",2980          "ts": 17949537248432981        }2982      ],2983      "spreadBps": "7.58",2984      "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"2985    }2986  ],2987  "merged": null,2988  "mergedReason": "contracts of different venues are different instruments: no average, no blended price, no cross-fill",2989  "venues": [2990    {2991      "venue": "hyperliquid",2992      "name": "Hyperliquid (builder-deployed dexes)",2993      "status": "ok",2994      "error": null,2995      "ts": 1794953723863,2996      "instruments": 52997    }2998  ],2999  "notice": {3000    "tradable": false,3001    "code": "private_markets_display_only",3002    "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"3003  },3004  "position": {3005    "side": "long",3006    "size": "1"3007  },3008  "ts": 1794953725812,3009  "source": "venue"3010}3011```30123013<details><summary><b>Response fields</b></summary>30143015| Field | Type | Required | Description |3016|---|---|---|---|3017| `company` | `object` | yes |  |3018| `company.slug` | `string` | yes |  |3019| `company.name` | `string` | yes |  |3020| `contracts` | `array of object` | yes |  |3021| `contracts[].id` | `string` | yes |  |3022| `contracts[].venue` | `string` | yes |  |3023| `contracts[].platform` | `string` | yes |  |3024| `contracts[].symbol` | `string` | yes |  |3025| `contracts[].company` | `object \| null` | yes |  |3026| `contracts[].status` | `"live" \| "delisted" \| "halted" \| "reduce_only"` | yes |  |3027| `contracts[].review` | `object` | yes |  |3028| `contracts[].contract` | `object` | yes |  |3029| `contracts[].market` | `object` | yes |  |3030| `contracts[].valuation` | `object` | yes |  |3031| `contracts[].tradable` | `false` | yes |  |3032| `contracts[].notTradable` | `object` | yes |  |3033| `contracts[].error` | `string \| null` | yes |  |3034| `delisted` | `array of object` | yes |  |3035| `delisted[].id` | `string` | yes |  |3036| `delisted[].venue` | `string` | yes |  |3037| `delisted[].platform` | `string` | yes |  |3038| `delisted[].symbol` | `string` | yes |  |3039| `delisted[].company` | `object \| null` | yes |  |3040| `delisted[].status` | `"live" \| "delisted" \| "halted" \| "reduce_only"` | yes |  |3041| `delisted[].review` | `object` | yes |  |3042| `delisted[].contract` | `object` | yes |  |3043| `delisted[].market` | `object` | yes |  |3044| `delisted[].valuation` | `object` | yes |  |3045| `delisted[].tradable` | `false` | yes |  |3046| `delisted[].notTradable` | `object` | yes |  |3047| `delisted[].error` | `string \| null` | yes |  |3048| `references` | `array of object` | yes |  |3049| `merged` | `null` | yes | always null: venues are never merged |3050| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |30513052</details>30533054**Errors**30553056| Status | Codes |3057|---|---|3058| 400 | [`bad_request`](#err-bad_request) |3059| 401 | [`unauthenticated`](#err-unauthenticated) |3060| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |3061| 404 | [`unknown_company`](#err-unknown_company) |3062| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3063| 500 | [`internal`](#err-internal) |3064| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |30653066<a id="op-getPrivateMarket"></a>30673068#### GET `/api/v1/trading/private-markets/{id}`30693070**One private-company contract: definition, valuation breakdown, candles, top of book.** Operation id `getPrivateMarket`.30713072- **Permission:** `markets:read`3073- **Idempotency-Key:** not used3074- **Side effects:** none (a read)30753076One contract (`id` from GET /private-markets): what it is (nature, unit, settlement, oracle), its market figures each with source, time and `stale`, the valuation breakdown for a hypothetical position (`size`, `side`), the top of the book and candles (`interval`, `limit`). An instrument that exists and is not a private-company contract answers 404 `not_a_private_market`. Display only.30773078**Parameters**30793080| Name | In | Type | Required | Description |3081|---|---|---|---|---|3082| `id` | path | `string` | yes | `venue:symbol`, e.g. `hyperliquid:io:ANTH`, `edgex:ANTHROPICUSDC` — 3–120 characters · pattern ^[a-z]+:[A-Za-z0-9:._-]+$ |3083| `size` | query | `string` | — | hypothetical position size, contracts (default 1) — pattern ^(0\|[1-9]\d{0,11})(\.\d{1,8})?$ |3084| `side` | query | `"long" \| "short"` | — | side of the hypothetical position (default long) |3085| `interval` | query | `"1h" \| "1d"` | — | candle length |3086| `limit` | query | `integer 1…500` | — | candles returned at most |30873088**Example request**30893090```bash3091curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets/hyperliquid:io:ANTH?interval=1d&limit=3" \3092  -H "Authorization: Bearer $SP_WALLET_API_KEY"3093```30943095```ts3096const pm = await client.getPrivateMarket('hyperliquid:io:ANTH', { interval: '1d', limit: 3 });3097```30983099```python3100pm = client.get_private_market("hyperliquid:io:ANTH", interval="1d", limit=3)3101```31023103**Example response** — 200, recorded from a real server31043105```json3106{3107  "market": {3108    "id": "hyperliquid:io:ANTH",3109    "venue": "hyperliquid",3110    "platform": "Hyperliquid · EntropyIO (dex io)",3111    "operator": "EntropyIO",3112    "symbol": "io:ANTH",3113    "company": {3114      "slug": "anthropic",3115      "name": "Anthropic, PBC"3116    },3117    "status": "live",3118    "review": {3119      "state": "reviewed",3120      "reasons": [],3121      "reviewedAt": "2026-11-15",3122      "validUntil": "2026-11-18T00:00:00Z",3123      "fingerprintChecked": true3124    },3125    "contract": {3126      "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",3127      "unit": {3128        "kind": "valuation_usd_billions",3129        "label": "USD billions of fully diluted company valuation (1.00 = $1B)"3130      },3131      "quoteCurrency": "USD",3132      "collateral": "USDC",3133      "underlying": "Anthropic, PBC",3134      "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",3135      "multiplier": {3136        "value": "1",3137        "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"3138      },3139      "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",3140      "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",3141      "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",3142      "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",3143      "maxLeverage": "15",3144      "margin": "cross_allowed",3145      "lotSize": "0.001",3146      "szDecimals": 3,3147      "fundingIntervalSec": 3600,3148      "assetId": 200001,3149      "dex": "io",3150      "oiCapUsd": "275000000",3151      "fundingMultiplier": "0.125",3152      "onChainDescription": "",3153      "unconfirmedConvention": null,3154      "sources": [3155        "https://docs.entropy.io/market-types/pre-ipo-perpetuals"3156      ]3157    },3158    "market": {3159      "price": {3160        "value": "1683.9",3161        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",3162        "ts": 1794953724740,3163        "stale": false3164      },3165      "oracle": {3166        "value": "1684",3167        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",3168        "ts": 1794953724740,3169        "stale": false3170      },3171      "mid": {3172        "value": "1680.6",3173        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",3174        "ts": 1794953724740,3175        "stale": false3176      },3177      "funding": {3178        "value": "-0.0000113686",3179        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",3180        "ts": 1794953724740,3181        "stale": false,3182        "intervalSec": 36003183      },3184      "openInterest": {3185        "value": "117475.832",3186        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",3187        "ts": 1794953724740,3188        "stale": false3189      },3190      "openInterestUsd": {3191        "value": "197817553.5048",3192        "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",3193        "ts": 1794953724740,3194        "stale": false3195      },3196      "volume24h": {3197        "value": "34445966.2849999964",3198        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",3199        "ts": 1794953724740,3200        "stale": false3201      },3202      "volumeBase24h": {3203        "value": "20388.063",3204        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",3205        "ts": 1794953724740,3206        "stale": false3207      },3208      "frozen": false3209    },3210    "valuation": {3211      "syntheticPrice": {3212        "value": "1683.9",3213        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",3214        "ts": 1794953724740,3215        "stale": false,3216        "unit": "valuation_usd_billions",3217        "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",3218        "priceKind": "mark"3219      },3220      "contractMarketValue": {3221        "value": "1683.9",3222        "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",3223        "reason": null,3224        "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",3225        "ts": 17949537247403226      },3227      "notionalExposure": {3228        "value": "1683.9",3229        "formula": "size × contract value, negative for a short",3230        "reason": null,3231        "position": {3232          "side": "long",3233          "size": "1"3234        },3235        "hypothetical": true,3236        "ts": 17949537247403237      },3238      "impliedValuation": {3239        "value": "1683900000000",3240        "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",3241        "formulaId": "price_x_1e9",3242        "formulaSource": {3243          "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",3244          "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",3245          "readAt": "2026-11-15"3246        },3247        "asOf": 1794953724740,3248        "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",3249        "reason": null,3250        "reasonCode": null3251      },3252      "lastPrivateValuation": {3253        "value": "965000000000",3254        "kind": "primary_round",3255        "detail": "Series H, $65B raised, post-money",3256        "date": "2026-05-28",3257        "sourceUrl": "https://www.anthropic.com/news/series-h",3258        "confidence": "high"3259      },3260      "lastPrivateValuationReason": null,3261      "premiumDiscount": {3262        "premiumBps": "7449.7409",3263        "reason": null,3264        "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"3265      },3266      "caveats": [3267        {3268          "code": "synthetic",3269          "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"3270        }3271      ]3272    },3273    "tradable": false,3274    "notTradable": {3275      "code": "builder_dex_read_only",3276      "reasons": [3277        "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"3278      ]3279    },3280    "error": null3281  },3282  "book": {3283    "bids": [3284      [3285        "1680.4"3286      ],3287      [3288        "1680.2"3289      ],3290      [3291        "1680.1"3292      ]3293    ],3294    "asks": [3295      [3296        "1680.8"3297      ],3298      [3299        "1681"3300      ],3301      [3302        "1681.1"3303      ]3304    ],3305    "ts": 1794953724827,3306    "stale": false,3307    "source": "Hyperliquid info l2Book"3308  },3309  "candles": {3310    "interval": "1d",3311    "candles": [3312      {3313        "ts": 1794700800000,3314        "open": "1779.8",3315        "high": "1785.7",3316        "low": "1752.3",3317        "close": "1777.2",3318        "volume": "4532.974"3319      }3320    ],3321    "ts": 1794953725389,3322    "stale": false,3323    "source": "Hyperliquid info candleSnapshot"3324  },3325  "references": [3326    {3327      "company": "anthropic",3328      "valueUsd": "965000000000",3329      "kind": "primary_round",3330      "detail": "Series H, $65B raised, post-money",3331      "date": "2026-05-28",3332      "sourceUrl": "https://www.anthropic.com/news/series-h",3333      "confidence": "high",3334      "postMoney": true3335    }3336  ],3337  "company": {3338    "slug": "anthropic",3339    "name": "Anthropic, PBC",3340    "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date.",3341    "contracts": [3342      "hyperliquid:io:ANTH"3343    ],3344    "lastPrivateValuation": {3345      "value": "965000000000",3346      "kind": "primary_round",3347      "detail": "Series H, $65B raised, post-money",3348      "date": "2026-05-28",3349      "sourceUrl": "https://www.anthropic.com/news/series-h",3350      "confidence": "high"3351    },3352    "divergence": [3353      {3354        "unit": "usd_per_share",3355        "unitLabel": "USD per 1 share (share class not specified by the operator)",3356        "contracts": [3357          {3358            "id": "hyperliquid:para:ANTH",3359            "price": "96.26",3360            "ts": 17949537248433361          }3362        ],3363        "spreadBps": "7.58",3364        "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"3365      }3366    ]3367  },3368  "sameCompany": [3369    {3370      "id": "hyperliquid:para:ANTH",3371      "platform": "Hyperliquid · Paragon (dex para)",3372      "price": {3373        "value": "96.26",3374        "source": "Hyperliquid info metaAndAssetCtxs (dex para) — mark price",3375        "ts": 1794953724843,3376        "stale": false3377      },3378      "unit": {3379        "kind": "usd_per_share",3380        "label": "USD per 1 share (share class not specified by the operator)"3381      },3382      "review": "reviewed"3383    }3384  ],3385  "notice": {3386    "tradable": false,3387    "code": "private_markets_display_only",3388    "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"3389  },3390  "position": {3391    "side": "long",3392    "size": "1"3393  },3394  "ts": 1794953725389,3395  "source": "venue"3396}3397```33983399<details><summary><b>Response fields</b></summary>34003401| Field | Type | Required | Description |3402|---|---|---|---|3403| `market` | `object` | yes |  |3404| `market.id` | `string` | yes |  |3405| `market.venue` | `string` | yes |  |3406| `market.platform` | `string` | yes |  |3407| `market.symbol` | `string` | yes |  |3408| `market.company` | `object \| null` | yes |  |3409| `market.status` | `"live" \| "delisted" \| "halted" \| "reduce_only"` | yes |  |3410| `market.review` | `object` | yes |  |3411| `market.contract` | `object` | yes |  |3412| `market.market` | `object` | yes |  |3413| `market.valuation` | `object` | yes |  |3414| `market.tradable` | `false` | yes |  |3415| `market.notTradable` | `object` | yes |  |3416| `market.error` | `string \| null` | yes |  |3417| `book` | `object` | yes |  |3418| `candles` | `object` | yes |  |3419| `references` | `array of object` | yes |  |3420| `references[].kind` | `string` | yes |  |3421| `references[].date` | `string` | yes |  |3422| `references[].sourceUrl` | `string` | yes |  |3423| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |34243425</details>34263427**Errors**34283429| Status | Codes |3430|---|---|3431| 400 | [`bad_request`](#err-bad_request) |3432| 401 | [`unauthenticated`](#err-unauthenticated) |3433| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |3434| 404 | [`not_a_private_market`](#err-not_a_private_market), [`unknown_private_market`](#err-unknown_private_market) |3435| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3436| 500 | [`internal`](#err-internal) |3437| 503 | [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |34383439<a id="tag-portfolio"></a>34403441### Portfolio34423443What the wallet holds: on-chain balances, the valued portfolio with every derivatives account, and the activity feed. Scope `wallet:read`. Paper and live are separate figures, never summed.34443445<a id="op-getPortfolio"></a>34463447#### GET `/api/v1/trading/portfolio`34483449**Wallet value and derivative accounts, per mode.** Operation id `getPortfolio`.34503451- **Permission:** `wallet:read`3452- **Idempotency-Key:** not used3453- **Side effects:** none (a read)34543455Wallet balances valued in USD, then every derivatives account with its `mode`. Every amount is a decimal string. Paper and live are never added together.34563457**Example request**34583459```bash3460curl -s "$SP_WALLET_BASE_URL/api/v1/trading/portfolio" \3461  -H "Authorization: Bearer $SP_WALLET_API_KEY"3462```34633464```ts3465const portfolio = await client.getPortfolio();3466```34673468```python3469portfolio = client.get_portfolio()3470```34713472**Example response** — 200, recorded from a real server. Cut to one balance. The test wallet is empty; `totals` are three separate figures, never summed.34733474```json3475{3476  "asOf": "2026-11-17T22:15:27.274Z",3477  "wallet": {3478    "valueUsd": "0",3479    "priced": 0,3480    "unpriced": 0,3481    "pricesAsOf": "2026-11-17T22:15:27.274Z",3482    "balances": [3483      {3484        "network": "ethereum",3485        "networkName": "Ethereum",3486        "asset": "native",3487        "symbol": "ETH",3488        "name": "Ether",3489        "decimals": 18,3490        "amount": "0",3491        "display": "0",3492        "error": null,3493        "valueUsd": "0",3494        "priceSource": "coingecko",3495        "priceAt": "2026-11-17T22:14:49.000Z",3496        "priceDivergent": false,3497        "priceDivergenceBps": null3498      }3499    ]3500  },3501  "accounts": [3502    {3503      "mode": "paper",3504      "venue": "hyperliquid",3505      "network": "mainnet",3506      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",3507      "label": "SDK paper",3508      "equity": "10000",3509      "collateral": "10000",3510      "error": null,3511      "source": "paper"3512    }3513  ],3514  "totals": {3515    "walletUsd": "0",3516    "liveVenueEquity": "0",3517    "paperEquity": "10000",3518    "note": "three separate figures: the wallet (on-chain, USD), venue accounts on mainnet (live), paper accounts (simulated). They are never added together; testnet accounts are listed but not summed."3519  },3520  "halted": false,3521  "errors": []3522}3523```35243525<details><summary><b>Response fields</b></summary>35263527| Field | Type | Required | Description |3528|---|---|---|---|3529| `asOf` | `string` | yes |  |3530| `wallet` | `object` | yes |  |3531| `wallet.valueUsd` | `string \| null` | yes | USD, a decimal string; null when the price feed is unavailable |3532| `wallet.priced` | `integer -9007199254740991…9007199254740991` | yes |  |3533| `wallet.unpriced` | `integer -9007199254740991…9007199254740991` | yes |  |3534| `wallet.pricesAsOf` | `string \| null` | yes |  |3535| `wallet.balances` | `array of object` | yes |  |3536| `accounts` | `array of object` | yes |  |3537| `accounts[].mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |3538| `accounts[].venue` | `string` | yes |  |3539| `accounts[].accountId` | `string` | yes |  |3540| `accounts[].equity` | `string \| null` | yes |  |3541| `accounts[].error` | `string \| null` | yes |  |3542| `totals` | `object` | yes | three separate figures; there is no sum across modes |3543| `totals.walletUsd` | `string \| null` | yes |  |3544| `totals.liveVenueEquity` | `string \| null` | yes |  |3545| `totals.paperEquity` | `string \| null` | yes |  |3546| `totals.note` | `string` | yes | what the three figures are, in a sentence |3547| `halted` | `boolean \| null` | yes | emergency halt of the signer; null when the signer does not say |3548| `errors` | `array of object` | yes |  |3549| `errors[].source` | `string` | yes |  |3550| `errors[].message` | `string` | yes |  |35513552</details>35533554**Errors**35553556| Status | Codes |3557|---|---|3558| 401 | [`unauthenticated`](#err-unauthenticated) |3559| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |3560| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3561| 500 | [`internal`](#err-internal) |3562| 503 | [`service_unavailable`](#err-service_unavailable), [`signer_unreachable`](#err-signer_unreachable) |35633564<a id="op-getBalances"></a>35653566#### GET `/api/v1/trading/balances`35673568**On-chain balances of the wallet.** Operation id `getBalances`.35693570- **Permission:** `wallet:read`3571- **Idempotency-Key:** not used3572- **Side effects:** none (a read)35733574One row per asset of the wallet registry, read from the chains now: `amount` is the exact integer of base units as a string, `display` the same in the asset's decimals. A network that cannot be read gives rows with `error` (and an entry in `errors`), never a zero; 503 only when no network answered. Not valued: GET /portfolio adds prices.35753576**Parameters**35773578| Name | In | Type | Required | Description |3579|---|---|---|---|---|3580| `network` | query | `string` | — | one network id (e.g. `base`, `arbitrum`, `solana`); default: every network of the wallet — 0–24 characters |35813582**Example request**35833584```bash3585curl -s "$SP_WALLET_BASE_URL/api/v1/trading/balances?network=base" \3586  -H "Authorization: Bearer $SP_WALLET_API_KEY"3587```35883589```ts3590const { balances } = await client.getBalances({ network: 'base' });3591```35923593```python3594balances = client.get_balances(network="base").balances3595```35963597**Example response** — 200, recorded from a real server35983599```json3600{3601  "asOf": "2026-11-17T22:15:28.199Z",3602  "balances": [3603    {3604      "network": "base",3605      "networkName": "Base",3606      "asset": "native",3607      "symbol": "ETH",3608      "name": "Ether",3609      "decimals": 18,3610      "amount": "0",3611      "display": "0",3612      "error": null3613    },3614    {3615      "network": "base",3616      "networkName": "Base",3617      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",3618      "symbol": "USDC",3619      "name": "USD Coin",3620      "decimals": 6,3621      "amount": "0",3622      "display": "0",3623      "error": null3624    }3625  ],3626  "errors": [],3627  "halted": false3628}3629```36303631<details><summary><b>Response fields</b></summary>36323633| Field | Type | Required | Description |3634|---|---|---|---|3635| `asOf` | `string` | yes |  |3636| `balances` | `array of object` | yes |  |3637| `balances[].network` | `string` | yes |  |3638| `balances[].asset` | `string` | yes |  |3639| `balances[].symbol` | `string` | yes |  |3640| `balances[].decimals` | `integer -9007199254740991…9007199254740991` | yes |  |3641| `balances[].amount` | `string \| null` | yes |  |3642| `balances[].display` | `string \| null` | yes |  |3643| `balances[].error` | `string \| null` | yes |  |3644| `errors` | `array of object` | yes |  |3645| `errors[].source` | `string` | yes |  |3646| `errors[].message` | `string` | yes |  |3647| `halted` | `boolean \| null` | yes | emergency halt of the signer; null when the signer does not say |36483649</details>36503651**Errors**36523653| Status | Codes |3654|---|---|3655| 400 | [`bad_request`](#err-bad_request) |3656| 401 | [`unauthenticated`](#err-unauthenticated) |3657| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |3658| 404 | [`unknown_network`](#err-unknown_network) |3659| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3660| 500 | [`internal`](#err-internal) |3661| 503 | [`service_unavailable`](#err-service_unavailable), [`signer_unreachable`](#err-signer_unreachable) |36623663<a id="op-getActivity"></a>36643665#### GET `/api/v1/trading/activity`36663667**Wallet activity and fills, newest first.** Operation id `getActivity`.36683669- **Permission:** `wallet:read`3670- **Idempotency-Key:** not used3671- **Side effects:** none (a read)36723673Sends, swaps, bridges, receipts and derivative fills, newest first, in one stable order (time, then id). Paginated: `nextCursor` of a page is the `cursor` of the next; null at the end. An item that appears after the first page was read is not inserted into the pages that follow.36743675**Parameters**36763677| Name | In | Type | Required | Description |3678|---|---|---|---|---|3679| `limit` | query | `integer 1…500` | — | rows returned at most — default 100 |3680| `cursor` | query | `string` | — | opaque position returned as `nextCursor` by the previous page; send it with the same filters — 1–400 characters · pattern ^[A-Za-z0-9_-]+$ |36813682**Example request**36833684```bash3685curl -s "$SP_WALLET_BASE_URL/api/v1/trading/activity?limit=2" \3686  -H "Authorization: Bearer $SP_WALLET_API_KEY"3687```36883689```ts3690const page = await client.getActivity({ limit: 2 });3691for await (const item of client.iterateActivity()) console.log(item.kind, item.at);   // every page3692```36933694```python3695page = client.get_activity(limit=2)3696for item in client.iter_activity():   # every page3697    print(item.kind, item.at)3698```36993700**Example response** — 200, recorded from a real server37013702```json3703{3704  "items": [3705    {3706      "kind": "fill",3707      "mode": "paper",3708      "at": "2026-11-17T22:15:31.480Z",3709      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-6",3710      "venue": "hyperliquid",3711      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",3712      "instrument": "hyperliquid:BTC",3713      "side": "sell",3714      "price": "64426",3715      "size": "0.00078",3716      "fee": "0.022613526",3717      "closedPnl": "-0.00468"3718    },3719    {3720      "kind": "fill",3721      "mode": "paper",3722      "at": "2026-11-17T22:15:31.456Z",3723      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-4",3724      "venue": "hyperliquid",3725      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",3726      "instrument": "hyperliquid:BTC",3727      "side": "sell",3728      "price": "64426",3729      "size": "0.00077",3730      "fee": "0.022323609",3731      "closedPnl": "-0.00462"3732    }3733  ],3734  "nextCursor": "WyIxNzk0OTUzNzMxNDU2MDAwIiwiZiIsIjZhMmM4MzUxLWNkNzktNDRlMi1iNzVhLWYzOTI4MGQwZWJjMjpwYXBlci1mLTQiXQ"3735}3736```37373738<details><summary><b>Response fields</b></summary>37393740| Field | Type | Required | Description |3741|---|---|---|---|3742| `items` | `array of object` | yes |  |3743| `items[].kind` | `string` | yes |  |3744| `items[].at` | `string` | yes |  |3745| `items[].mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |3746| `nextCursor` | `string \| null` | yes | pass it as `cursor` to read the next (older) page; null when there is none |37473748</details>37493750**Errors**37513752| Status | Codes |3753|---|---|3754| 400 | [`bad_request`](#err-bad_request), [`invalid_cursor`](#err-invalid_cursor) |3755| 401 | [`unauthenticated`](#err-unauthenticated) |3756| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |3757| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3758| 500 | [`internal`](#err-internal) |37593760<a id="tag-nfts"></a>37613762### Nfts37633764Read-only NFT data: the wallet's inventory (`wallet:read`) and market data of any item (`markets:read`). No transfer and no market write exists in this API. An NFT never has a value here.37653766<a id="op-listNfts"></a>37673768#### GET `/api/v1/trading/nfts`37693770**NFTs of the wallet (what the chain confirmed as held).** Operation id `listNfts`.37713772- **Permission:** `wallet:read`3773- **Idempotency-Key:** not used3774- **Side effects:** none (a read)37753776The inventory as last synchronised: Solana (Token Metadata, programmable, Token-2022, Core, compressed through an index) and the EVM networks (ERC-721, ERC-1155). Every row names the source and confidence of its ownership. NFTs carry NO value: `valuation.state` is `unavailable` (never zero, never a floor) and they are not part of GET /portfolio. Paginated: `nextCursor` of a page is the `cursor` of the next.37773778**Parameters**37793780| Name | In | Type | Required | Description |3781|---|---|---|---|---|3782| `network` | query | `string` | — | one network id; default: all — 0–24 characters |3783| `collection` | query | `string` | — | collection key — 0–260 characters |3784| `status` | query | `"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 |3785| `q` | query | `string` | — | case-insensitive text matched on the name, the key or the collection name — 0–80 characters |3786| `sort` | query | `"recent" \| "name"` | — | order of the list — default "recent" |3787| `spam` | query | `"hide" \| "show" \| "only"` | — | items an indexer flags as spam are hidden by default, never deleted — default "hide" |3788| `limit` | query | `integer 1…100` | — | rows returned at most — default 48 |3789| `cursor` | query | `string` | — | opaque position returned as `nextCursor` by the previous page; send it with the same filters — 1–400 characters · pattern ^[A-Za-z0-9_-]+$ |37903791**Example request**37923793```bash3794curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts?limit=2" \3795  -H "Authorization: Bearer $SP_WALLET_API_KEY"3796```37973798```ts3799const { items, nextCursor } = await client.listNfts({ limit: 2 });3800```38013802```python3803nfts = client.list_nfts(limit=2)3804```38053806**Example response** — 200, recorded from a real server. The test wallet holds no NFT: the list is empty, and `valuation` is always `unavailable`.38073808```json3809{3810  "items": [],3811  "total": 0,3812  "hiddenSpam": 0,3813  "nextCursor": null,3814  "valuation": {3815    "state": "unavailable",3816    "reason": "no_reliable_valuation",3817    "note": "an NFT has no value this wallet can establish: it is not counted as zero and not valued at a collection floor; it is not part of GET /portfolio"3818  },3819  "asOf": "2026-11-17T22:15:28.204Z"3820}3821```38223823<details><summary><b>Response fields</b></summary>38243825| Field | Type | Required | Description |3826|---|---|---|---|3827| `items` | `array of object` | yes |  |3828| `items[].key` | `string` | yes | `family:network:asset-id` — the id every NFT operation takes |3829| `items[].network` | `string` | yes |  |3830| `items[].family` | `string` | yes |  |3831| `items[].standard` | `string` | yes |  |3832| `items[].assetId` | `string` | yes |  |3833| `items[].contractAddress` | `string \| null` | yes |  |3834| `items[].tokenId` | `string \| null` | yes | decimal string (up to 2^256 − 1), never a number |3835| `items[].mintAddress` | `string \| null` | yes |  |3836| `items[].quantity` | `string` | yes | exact integer of base units, as a string — pattern ^(0\|[1-9][0-9]{0,77})$ |3837| `items[].name` | `string \| null` | yes | declared by the creator — not chain truth |3838| `items[].onchainName` | `string \| null` | yes |  |3839| `items[].collection` | `object \| null` | yes |  |3840| `items[].state` | `string` | yes |  |3841| `items[].inWallet` | `boolean` | yes |  |3842| `items[].transferable` | `boolean` | yes |  |3843| `items[].transferBlockedBy` | `array of string` | yes |  |3844| `items[].spam` | `object \| null` | yes | an indexer's signal, named — never a verdict of this wallet |3845| `items[].ownershipSource` | `object` | yes |  |3846| `total` | `integer -9007199254740991…9007199254740991` | yes |  |3847| `hiddenSpam` | `integer -9007199254740991…9007199254740991` | yes |  |3848| `nextCursor` | `string \| null` | yes | pass it as `cursor` to read the next (older) page; null when there is none |3849| `valuation` | `object` | yes | NFTs have no value in this API: never zero, never a floor |3850| `valuation.state` | `"unavailable"` | yes |  |3851| `valuation.reason` | `string` | yes |  |3852| `valuation.note` | `string` | yes |  |3853| `asOf` | `string` | yes |  |38543855</details>38563857**Errors**38583859| Status | Codes |3860|---|---|3861| 400 | [`bad_request`](#err-bad_request), [`invalid_cursor`](#err-invalid_cursor) |3862| 401 | [`unauthenticated`](#err-unauthenticated) |3863| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |3864| 404 | [`unknown_network`](#err-unknown_network), [`unknown_nft`](#err-unknown_nft) |3865| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |3866| 500 | [`internal`](#err-internal) |3867| 503 | [`nft_disabled`](#err-nft_disabled), [`signer_unreachable`](#err-signer_unreachable) |38683869<a id="op-getNft"></a>38703871#### GET `/api/v1/trading/nfts/item`38723873**One NFT of the wallet: identity, ownership, creator metadata, sources.** Operation id `getNft`.38743875- **Permission:** `wallet:read`3876- **Idempotency-Key:** not used3877- **Side effects:** none (a read)38783879Only an NFT of the inventory (404 `unknown_nft` otherwise — a looked-up item is not the wallet's). On-chain facts, creator-declared metadata and indexed data are separate fields, each with its source. `marketActions` lists the market actions: none exists in this version.38803881**Parameters**38823883| Name | In | Type | Required | Description |3884|---|---|---|---|---|3885| `key` | query | `string` | yes | `family:network:asset-id`, as returned by GET /nfts — 5–260 characters |38863887**Example request**38883889```bash3890curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/item?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1" \3891  -H "Authorization: Bearer $SP_WALLET_API_KEY"3892```38933894```ts3895const { nft } = await client.getNft('evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1');3896```38973898```python3899nft = client.get_nft("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1").nft3900```39013902**Example response** — 200, written from the schema (not recorded)39033904```json3905{3906  "nft": {3907    "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",3908    "network": "ethereum",3909    "family": "evm",3910    "standard": "erc721",3911    "assetId": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",3912    "contractAddress": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",3913    "tokenId": "1",3914    "mintAddress": null,3915    "quantity": "1",3916    "name": "Example #1",3917    "onchainName": null,3918    "collection": {3919      "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",3920      "id": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",3921      "name": "Example Collection",3922      "verifiedOnChain": {3923        "state": "unsupported"3924      }3925    },3926    "state": "held",3927    "inWallet": true,3928    "transferable": true,3929    "transferBlockedBy": [],3930    "spam": null,3931    "ownershipSource": {3932      "category": "onchain",3933      "source": "rpc:ownerOf",3934      "confidence": "confirmed",3935      "fetchedAt": "2026-11-17T22:15:29.000Z",3936      "stale": false3937    },3938    "ownership": {3939      "state": "held",3940      "owner": {3941        "state": "known",3942        "value": "0x00000000000000000000000000000000000000aa"3943      },3944      "heldByWallet": true3945    },3946    "metadata": {3947      "status": "ok",3948      "name": "Example #1",3949      "description": "Declared by the creator.",3950      "attributes": [3951        {3952          "traitType": "Background",3953          "value": "Blue"3954        }3955      ]3956    },3957    "sources": [3958      {3959        "category": "onchain",3960        "source": "rpc:ownerOf",3961        "stale": false3962      },3963      {3964        "category": "creator_metadata",3965        "source": "tokenURI",3966        "stale": false3967      }3968    ]3969  },3970  "marketActions": [3971    {3972      "id": "sell",3973      "available": false,3974      "reason": "market_writes_not_built"3975    }3976  ]3977}3978```39793980<details><summary><b>Response fields</b></summary>39813982| Field | Type | Required | Description |3983|---|---|---|---|3984| `nft` | `object` | yes |  |3985| `nft.key` | `string` | yes | `family:network:asset-id` — the id every NFT operation takes |3986| `nft.network` | `string` | yes |  |3987| `nft.family` | `string` | yes |  |3988| `nft.standard` | `string` | yes |  |3989| `nft.assetId` | `string` | yes |  |3990| `nft.contractAddress` | `string \| null` | yes |  |3991| `nft.tokenId` | `string \| null` | yes | decimal string (up to 2^256 − 1), never a number |3992| `nft.mintAddress` | `string \| null` | yes |  |3993| `nft.quantity` | `string` | yes | exact integer of base units, as a string — pattern ^(0\|[1-9][0-9]{0,77})$ |3994| `nft.name` | `string \| null` | yes | declared by the creator — not chain truth |3995| `nft.onchainName` | `string \| null` | yes |  |3996| `nft.collection` | `object \| null` | yes |  |3997| `nft.state` | `string` | yes |  |3998| `nft.inWallet` | `boolean` | yes |  |3999| `nft.transferable` | `boolean` | yes |  |4000| `nft.transferBlockedBy` | `array of string` | yes |  |4001| `nft.spam` | `object \| null` | yes | an indexer's signal, named — never a verdict of this wallet |4002| `nft.ownershipSource` | `object` | yes |  |4003| `nft.ownership` | `object` | yes |  |4004| `nft.metadata` | `object` | yes | declared by the creator: text, never chain truth |4005| `nft.sources` | `array of object` | yes |  |4006| `marketActions` | `array of object` | yes | the market actions, none of which exists in this version: every one is `available: false` with its reason |4007| `marketActions[].id` | `string` | yes |  |4008| `marketActions[].available` | `false` | yes |  |4009| `marketActions[].reason` | `string` | yes |  |40104011</details>40124013**Errors**40144015| Status | Codes |4016|---|---|4017| 400 | [`bad_request`](#err-bad_request), [`invalid_cursor`](#err-invalid_cursor) |4018| 401 | [`unauthenticated`](#err-unauthenticated) |4019| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4020| 404 | [`unknown_network`](#err-unknown_network), [`unknown_nft`](#err-unknown_nft) |4021| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4022| 500 | [`internal`](#err-internal) |4023| 503 | [`nft_disabled`](#err-nft_disabled), [`signer_unreachable`](#err-signer_unreachable) |40244025<a id="op-getNftActivity"></a>40264027#### GET `/api/v1/trading/nfts/activity`40284029**On-chain events of one NFT of the wallet.** Operation id `getNftActivity`.40304031- **Permission:** `wallet:read`4032- **Idempotency-Key:** not used4033- **Side effects:** none (a read)40344035Mints, transfers and burns read from the chain. A transfer is never a sale: `price` is null unless SP Wallet linked a payment of the SAME transaction through a decoded marketplace event (Seaport `OrderFulfilled`), in which case the event is a `sale` and `interpretedBy` names the decoder. `completeness` says how much history the sources gave.40364037**Parameters**40384039| Name | In | Type | Required | Description |4040|---|---|---|---|---|4041| `key` | query | `string` | yes | `family:network:asset-id`, as returned by GET /nfts — 5–260 characters |4042| `limit` | query | `integer 1…50` | — | rows returned at most — default 20 |4043| `cursor` | query | `string` | — | `nextCursor` of the previous page — 0–400 characters |4044| `type` | query | `"mint" \| "transfer" \| "transfer-in" \| "transfer-out" \| "burn" \| "sale" \| "unknown"` | — | only events of this type |40454046**Example request**40474048```bash4049curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/activity?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1&limit=2" \4050  -H "Authorization: Bearer $SP_WALLET_API_KEY"4051```40524053```ts4054const { events } = await client.getNftActivity({ key: 'evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1', limit: 2 });4055```40564057```python4058events = client.get_nft_activity("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1", limit=2).events4059```40604061**Example response** — 200, written from the schema (not recorded). A transfer has no price: `price` is set only when a decoded marketplace event of the same transaction links a payment.40624063```json4064{4065  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",4066  "events": [4067    {4068      "id": "0x5c1f…e2a9:14",4069      "type": "transfer-in",4070      "tx": "0x5c1f0d2b7a9e4c3f8b6a1d0e9f7c5b3a2d1e0f9c8b7a6d5e4f3c2b1a0f9ee2a9",4071      "at": "2026-10-02T14:11:23.000Z",4072      "from": "0x00000000000000000000000000000000000000bb",4073      "to": "0x00000000000000000000000000000000000000aa",4074      "quantity": "1",4075      "finality": "final",4076      "price": null,4077      "interpretedBy": "chain"4078    }4079  ],4080  "nextCursor": null,4081  "completeness": "partial",4082  "note": null,4083  "error": null4084}4085```40864087<details><summary><b>Response fields</b></summary>40884089| Field | Type | Required | Description |4090|---|---|---|---|4091| `key` | `string` | yes |  |4092| `events` | `array of object` | yes |  |4093| `events[].id` | `string` | yes |  |4094| `events[].type` | `string` | yes |  |4095| `events[].tx` | `string` | yes |  |4096| `events[].at` | `string \| null` | yes |  |4097| `events[].from` | `string \| null` | yes |  |4098| `events[].to` | `string \| null` | yes |  |4099| `events[].quantity` | `string` | yes |  |4100| `events[].finality` | `string` | yes |  |4101| `events[].price` | `object \| null` | yes | set ONLY when a payment of the same transaction was linked by a decoded marketplace event; a transfer alone never has one |4102| `events[].interpretedBy` | `string` | yes |  |4103| `nextCursor` | `string \| null` | yes | pass it as `cursor` to read the next (older) page; null when there is none |4104| `completeness` | `string` | yes |  |4105| `note` | `string \| null` | yes |  |4106| `error` | `string \| null` | yes |  |41074108</details>41094110**Errors**41114112| Status | Codes |4113|---|---|4114| 400 | [`bad_request`](#err-bad_request), [`invalid_cursor`](#err-invalid_cursor), [`nft_bad_identifier`](#err-nft_bad_identifier) |4115| 401 | [`unauthenticated`](#err-unauthenticated) |4116| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4117| 404 | [`nft_not_found`](#err-nft_not_found), [`unknown_network`](#err-unknown_network), [`unknown_nft`](#err-unknown_nft) |4118| 422 | [`nft_unsupported_chain`](#err-nft_unsupported_chain), [`nft_unsupported_standard`](#err-nft_unsupported_standard) |4119| 429 | [`auth_throttled`](#err-auth_throttled), [`nft_budget_exhausted`](#err-nft_budget_exhausted), [`nft_provider_rate_limited`](#err-nft_provider_rate_limited), [`rate_limited`](#err-rate_limited) |4120| 500 | [`internal`](#err-internal) |4121| 502 | [`nft_provider_bad_answer`](#err-nft_provider_bad_answer), [`nft_provider_disagreement`](#err-nft_provider_disagreement) |4122| 503 | [`nft_disabled`](#err-nft_disabled), [`nft_provider_method_unsupported`](#err-nft_provider_method_unsupported), [`nft_provider_not_configured`](#err-nft_provider_not_configured), [`nft_provider_unavailable`](#err-nft_provider_unavailable), [`signer_unreachable`](#err-signer_unreachable) |41234124<a id="op-getNftMarket"></a>41254126#### GET `/api/v1/trading/nfts/market`41274128**Market data of any NFT, one row per source.** Operation id `getNftMarket`.41294130- **Permission:** `markets:read`4131- **Idempotency-Key:** not used4132- **Side effects:** none (a read)41334134The item is named by its chain identifiers and read on-chain first. Then every configured market source answers on its own row: asking price, best offer, last sale, collection floor — five different notions, each in its own currency (network + exact mint / contract + decimals), with the source, its date and `stale`. A source without its key answers `needs_key` with the variable name; nothing is ever filled in. Sources are never merged: disagreements are listed in `contradictions`. Says nothing about the wallet. `rates` are secondary; a rate from a price source licensed for internal use is withheld from an API key.41354136**Parameters**41374138| Name | In | Type | Required | Description |4139|---|---|---|---|---|4140| `network` | query | `string` | yes | network id, e.g. `ethereum`, `base`, `solana` — 0–24 characters |4141| `address` | query | `string` | yes | EVM: the contract; Solana: the mint / asset address — 26–64 characters |4142| `tokenId` | query | `string` | — | EVM: required, decimal or 0x-hex — 0–80 characters |41434144**Example request**41454146```bash4147curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/market?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1" \4148  -H "Authorization: Bearer $SP_WALLET_API_KEY"4149```41504151```ts4152const market = await client.getNftMarket({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1' });4153```41544155```python4156market = client.get_nft_market(network="ethereum", address="0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", token_id="1")4157```41584159**Example response** — 200, recorded from a real server. Recorded on a server without a marketplace key: the source answers `needs_key` and names the variable. Nothing is filled in.41604161```json4162{4163  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",4164  "network": "ethereum",4165  "standard": "erc721",4166  "sources": [4167    {4168      "url": null,4169      "listed": {4170        "state": "unknown"4171      },4172      "ask": {4173        "state": "unknown"4174      },4175      "bestOffer": {4176        "state": "unknown"4177      },4178      "lastSale": {4179        "state": "unknown"4180      },4181      "collection": null,4182      "collectionFloor": {4183        "state": "unknown"4184      },4185      "verification": null,4186      "flags": {4187        "suspicious": {4188          "state": "unknown"4189        },4190        "disabled": {4191          "state": "unknown"4192        },4193        "nsfw": {4194          "state": "unknown"4195        }4196      },4197      "rarity": {4198        "state": "unknown"4199      },4200      "status": {4201        "provider": "opensea",4202        "name": "OpenSea",4203        "state": "needs_key",4204        "code": "no_api_key",4205        "unlockedBy": "OPENSEA_API_KEY",4206        "stale": false,4207        "stamp": null,4208        "attribution": null4209      }4210    }4211  ],4212  "contradictions": [],4213  "rates": {},4214  "value": {4215    "state": "unavailable",4216    "reason": "no_valuation_from_floor_or_single_quote"4217  },4218  "marketActions": [4219    {4220      "id": "buy",4221      "available": false,4222      "reason": "market_writes_not_built"4223    },4224    {4225      "id": "sell",4226      "available": false,4227      "reason": "market_writes_not_built"4228    }4229  ],4230  "asOf": "2026-11-17T22:15:29.113Z"4231}4232```42334234<details><summary><b>Response fields</b></summary>42354236| Field | Type | Required | Description |4237|---|---|---|---|4238| `key` | `string` | yes |  |4239| `network` | `string` | yes |  |4240| `standard` | `string` | yes |  |4241| `sources` | `array of object` | yes | ONE ROW PER SOURCE: never merged, never averaged |4242| `sources[].status` | `object` | yes |  |4243| `sources[].url` | `string \| null` | yes |  |4244| `sources[].listed` | `object` | yes | `known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value |4245| `sources[].ask` | `object` | yes | asking price of a live listing |4246| `sources[].bestOffer` | `object` | yes | `known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value |4247| `sources[].lastSale` | `object` | yes | last sale the source reports |4248| `sources[].collectionFloor` | `object` | yes | a statistic of the COLLECTION — never the value of this item |4249| `sources[].verification` | `object \| null` | yes | the marketplace's own badge, named — not an on-chain verification |4250| `sources[].rarity` | `object` | yes | `known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value |4251| `contradictions` | `array of object` | yes |  |4252| `contradictions[].field` | `string` | yes |  |4253| `contradictions[].providers` | `array of string` | yes |  |4254| `contradictions[].note` | `string` | yes |  |4255| `rates` | `map of object` | yes | fiat rates of the currencies quoted, keyed `network:asset` — secondary information with its own source and date |4256| `value` | `object` | yes |  |4257| `value.state` | `"unavailable"` | yes |  |4258| `value.reason` | `string` | yes |  |4259| `marketActions` | `array of object` | yes | the market actions, none of which exists in this version: every one is `available: false` with its reason |4260| `marketActions[].id` | `string` | yes |  |4261| `marketActions[].available` | `false` | yes |  |4262| `marketActions[].reason` | `string` | yes |  |4263| `asOf` | `string` | yes |  |42644265</details>42664267**Errors**42684269| Status | Codes |4270|---|---|4271| 400 | [`bad_request`](#err-bad_request), [`nft_bad_identifier`](#err-nft_bad_identifier) |4272| 401 | [`unauthenticated`](#err-unauthenticated) |4273| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4274| 404 | [`nft_not_found`](#err-nft_not_found), [`unknown_network`](#err-unknown_network) |4275| 422 | [`nft_unsupported_chain`](#err-nft_unsupported_chain), [`nft_unsupported_standard`](#err-nft_unsupported_standard) |4276| 429 | [`auth_throttled`](#err-auth_throttled), [`nft_budget_exhausted`](#err-nft_budget_exhausted), [`nft_provider_rate_limited`](#err-nft_provider_rate_limited), [`rate_limited`](#err-rate_limited) |4277| 500 | [`internal`](#err-internal) |4278| 502 | [`nft_provider_bad_answer`](#err-nft_provider_bad_answer), [`nft_provider_disagreement`](#err-nft_provider_disagreement) |4279| 503 | [`nft_disabled`](#err-nft_disabled), [`nft_provider_method_unsupported`](#err-nft_provider_method_unsupported), [`nft_provider_not_configured`](#err-nft_provider_not_configured), [`nft_provider_unavailable`](#err-nft_provider_unavailable), [`signer_unreachable`](#err-signer_unreachable) |42804281<a id="op-getNftMarketEvents"></a>42824283#### GET `/api/v1/trading/nfts/market/events`42844285**Market events of any NFT (sales, listings, offers), per source.** Operation id `getNftMarketEvents`.42864287- **Permission:** `markets:read`4288- **Idempotency-Key:** not used4289- **Side effects:** none (a read)42904291What each market source reports, newest first, with the payment token and quantity when the source gives them. Filter by `type`, `after`, `before`. One list per source: a `nextCursor` is passed back as `cursor` together with `provider`. A wash-trade flag is passed through when a source has one (`unknown` otherwise). These are market statements, listed apart from the chain's transfers (GET /nfts/activity).42924293**Parameters**42944295| Name | In | Type | Required | Description |4296|---|---|---|---|---|4297| `network` | query | `string` | yes | network id, e.g. `ethereum`, `base`, `solana` — 0–24 characters |4298| `address` | query | `string` | yes | EVM: the contract; Solana: the mint / asset address — 26–64 characters |4299| `tokenId` | query | `string` | — | EVM: required, decimal or 0x-hex — 0–80 characters |4300| `provider` | query | `string` | — | only this source (its id is `sources[].status.provider`); required with `cursor` — pattern ^[a-z][a-z0-9-]{1,30}$ |4301| `type` | query | `string` | — | comma-separated: sale, list, delist, offer, cancel-offer, transfer, mint — 0–120 characters · pattern ^[a-z,-]+$ |4302| `after` | query | `string` | — | only events after this instant (ISO 8601) — ISO 8601 date-time |4303| `before` | query | `string` | — | only events before this instant (ISO 8601) — ISO 8601 date-time |4304| `cursor` | query | `string` | — | a position in ONE source's list: send it with `provider` — 0–600 characters |4305| `limit` | query | `integer 1…50` | — | rows returned at most — default 20 |43064307**Example request**43084309```bash4310curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/market/events?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1&type=sale&limit=2" \4311  -H "Authorization: Bearer $SP_WALLET_API_KEY"4312```43134314```ts4315const { sources } = await client.getNftMarketEvents({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1', type: 'sale', limit: 2 });4316```43174318```python4319sources = client.get_nft_market_events(network="ethereum", address="0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", token_id="1", type="sale", limit=2).sources4320```43214322**Example response** — 200, recorded from a real server. Recorded on a server without a marketplace key: the source answers `needs_key` and lists no event. With a key, each event carries `type`, `at`, `tx`, `from`, `to`, `quantity`, `price` (amount in base units + currency) and `flags.washTrade`.43234324```json4325{4326  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",4327  "sources": [4328    {4329      "status": {4330        "provider": "opensea",4331        "name": "OpenSea",4332        "state": "needs_key",4333        "code": "no_api_key",4334        "unlockedBy": "OPENSEA_API_KEY",4335        "stale": false,4336        "stamp": null,4337        "attribution": null4338      },4339      "events": [],4340      "nextCursor": null4341    }4342  ],4343  "rates": {},4344  "asOf": "2026-11-17T22:37:24.187Z"4345}4346```43474348<details><summary><b>Response fields</b></summary>43494350| Field | Type | Required | Description |4351|---|---|---|---|4352| `key` | `string` | yes |  |4353| `sources` | `array of object` | yes |  |4354| `sources[].status` | `object` | yes |  |4355| `sources[].events` | `array of object` | yes |  |4356| `sources[].nextCursor` | `string \| null` | yes | pass it as `cursor` to read the next (older) page; null when there is none |4357| `rates` | `map of object` | yes |  |4358| `asOf` | `string` | yes |  |43594360</details>43614362**Errors**43634364| Status | Codes |4365|---|---|4366| 400 | [`bad_request`](#err-bad_request), [`nft_bad_identifier`](#err-nft_bad_identifier) |4367| 401 | [`unauthenticated`](#err-unauthenticated) |4368| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4369| 404 | [`nft_not_found`](#err-nft_not_found), [`unknown_network`](#err-unknown_network) |4370| 422 | [`nft_unsupported_chain`](#err-nft_unsupported_chain), [`nft_unsupported_standard`](#err-nft_unsupported_standard) |4371| 429 | [`auth_throttled`](#err-auth_throttled), [`nft_budget_exhausted`](#err-nft_budget_exhausted), [`nft_provider_rate_limited`](#err-nft_provider_rate_limited), [`rate_limited`](#err-rate_limited) |4372| 500 | [`internal`](#err-internal) |4373| 502 | [`nft_provider_bad_answer`](#err-nft_provider_bad_answer), [`nft_provider_disagreement`](#err-nft_provider_disagreement) |4374| 503 | [`nft_disabled`](#err-nft_disabled), [`nft_provider_method_unsupported`](#err-nft_provider_method_unsupported), [`nft_provider_not_configured`](#err-nft_provider_not_configured), [`nft_provider_unavailable`](#err-nft_provider_unavailable), [`signer_unreachable`](#err-signer_unreachable) |43754376<a id="tag-positions"></a>43774378### Positions43794380Open positions, and the two ways out of one: close and reduce — strictly reduce-only market orders. Closing passes the kill switch.43814382<a id="op-listPositions"></a>43834384#### GET `/api/v1/trading/positions`43854386**Open positions, paper and live separated by `mode`.** Operation id `listPositions`.43874388- **Permission:** `positions:read`4389- **Idempotency-Key:** not used4390- **Side effects:** none (a read)43914392Every open derivatives position of the wallet — paper accounts, Hyperliquid venue accounts, GMX (read on-chain) — each with its `mode`. `id` is what POST /positions/{id}/close and /reduce take; it contains colons: URL-encode it. A source that cannot be read is listed in `errors`; 503 only when none answered. Sizes and prices are decimal strings.43934394**Parameters**43954396| Name | In | Type | Required | Description |4397|---|---|---|---|---|4398| `mode` | query | `"paper" \| "live"` | — | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |4399| `venue` | query | `string` | — | venue id: hyperliquid, gmx, dydx, spot — 0–40 characters |44004401**Example request**44024403```bash4404curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" \4405  -H "Authorization: Bearer $SP_WALLET_API_KEY"4406```44074408```ts4409const { positions } = await client.getPositions({ mode: 'paper' });4410```44114412```python4413positions = client.get_positions(mode="paper").positions4414```44154416**Example response** — 200, recorded from a real server. A position `id` contains colons: URL-encode it in a path (both SDKs do).44174418```json4419{4420  "positions": [4421    {4422      "id": "paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC",4423      "mode": "paper",4424      "venue": "hyperliquid",4425      "network": "mainnet",4426      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",4427      "instrument": "hyperliquid:BTC",4428      "side": "long",4429      "size": "0.00155",4430      "entryPrice": "64432",4431      "markPrice": "64430.7",4432      "liquidationPrice": null,4433      "leverage": "3",4434      "margin": "33.289195",4435      "unrealizedPnl": "-0.002015",4436      "source": "paper"4437    }4438  ],4439  "errors": [],4440  "ts": 17949537314364441}4442```44434444<details><summary><b>Response fields</b></summary>44454446| Field | Type | Required | Description |4447|---|---|---|---|4448| `positions` | `array of object` | yes |  |4449| `positions[].id` | `string` | yes |  |4450| `positions[].mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |4451| `positions[].venue` | `string` | yes |  |4452| `positions[].accountId` | `string` | yes |  |4453| `positions[].instrument` | `string \| null` | yes |  |4454| `positions[].side` | `"long" \| "short"` | yes |  |4455| `positions[].size` | `string` | yes | decimal number as a string (never a float) |4456| `positions[].entryPrice` | `string` | yes | decimal number as a string (never a float) |4457| `positions[].markPrice` | `string \| null` | yes |  |4458| `positions[].unrealizedPnl` | `string \| null` | yes |  |4459| `positions[].source` | `string` | yes |  |4460| `errors` | `array of object` | yes |  |4461| `errors[].source` | `string` | yes |  |4462| `errors[].message` | `string` | yes |  |4463| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |44644465</details>44664467**Errors**44684469| Status | Codes |4470|---|---|4471| 400 | [`bad_request`](#err-bad_request) |4472| 401 | [`unauthenticated`](#err-unauthenticated) |4473| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4474| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4475| 500 | [`internal`](#err-internal) |4476| 503 | [`service_unavailable`](#err-service_unavailable) |44774478<a id="op-closePosition"></a>44794480#### POST `/api/v1/trading/positions/{id}/close`44814482**Close a position.** Operation id `closePosition`.44834484- **Permission:** `positions:manage` — and a trading mandate bound to the key (403 `mandate_required` otherwise)4485- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice4486- **Side effects:** yes — see the description44874488A strictly reduce-only market order on the whole position (`id` from GET /positions). Refused (422 `not_reducing`) if it would not strictly reduce. A key: the position must be on an account and an instrument of its mandate. Passes the kill switch; not read-only mode. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.44894490**Parameters**44914492| Name | In | Type | Required | Description |4493|---|---|---|---|---|4494| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |44954496**Request body** (JSON; unknown fields are refused)44974498| Field | Type | Required | Description |4499|---|---|---|---|4500| `slippageBps` | `integer 1…500` | — | worst acceptable price of the closing market order, in basis points from the reference price |45014502**Example request**45034504```bash4505curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/close" \4506  -H "Authorization: Bearer $SP_WALLET_API_KEY" \4507  -H "Idempotency-Key: $(uuidgen)" \4508  -H "Content-Type: application/json" \4509  -d '{}'4510```45114512```ts4513const closed = await client.closePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC');4514```45154516```python4517closed = client.close_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC")4518```45194520**Example response** — 200, recorded from a real server45214522```json4523{4524  "order": {4525    "id": "0xfa8f57b697470c1ec4327676f56a9868",4526    "orderId": "0xfa8f57b697470c1ec4327676f56a9868",4527    "mode": "paper",4528    "venue": "hyperliquid",4529    "network": "mainnet",4530    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",4531    "clientId": "0xfa8f57b697470c1ec4327676f56a9868",4532    "clientOrderId": "0xfa8f57b697470c1ec4327676f56a9868",4533    "venueOrderId": "paper-o-5",4534    "instrument": "hyperliquid:BTC",4535    "side": "sell",4536    "type": "market",4537    "size": "0.00078",4538    "price": "64104",4539    "triggerPrice": null,4540    "reduceOnly": true,4541    "tif": "ioc",4542    "status": "FILLED",4543    "final": true,4544    "reasonCode": "VENUE_FILLED",4545    "reason": null,4546    "rejectCode": null,4547    "engineStatus": "filled",4548    "filled": "0.00078",4549    "avgFillPrice": "64426",4550    "acknowledged": true,4551    "cancelRequested": false,4552    "origin": "trading_api",4553    "principal": {4554      "kind": "api_key",4555      "id": "spk_0123456789ab"4556    },4557    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",4558    "engine": "paper",4559    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xfa8f57b697470c1ec4327676f56a9868",4560    "hash": "73c1d9ea9e8be9bc4f6be7ed0febf7f3947552ec479c497b256798e8d217f7cd",4561    "notionalUsd": "50.00112",4562    "projectionError": null,4563    "version": 4,4564    "createdAt": 1794953731468,4565    "updatedAt": 17949537314874566  },4567  "idempotent": false,4568  "approval": null4569}4570```45714572<details><summary><b>Response fields</b></summary>45734574| Field | Type | Required | Description |4575|---|---|---|---|4576| `order` | `Order` | yes |  |4577| `idempotent` | `boolean` | yes | true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again |4578| `approval` | `object \| null` | yes | set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key |4579| `approval.by` | `string` | yes |  |4580| `approval.engine` | `string` | yes |  |4581| `approval.accountId` | `string` | yes |  |4582| `approval.clientId` | `string` | yes |  |4583| `approval.hash` | `string \| null` | yes |  |4584| `approval.expiresAt` | `integer -9007199254740991…9007199254740991 \| null` | yes |  |4585| `approval.approve` | `object` | yes |  |45864587</details>45884589**Errors** (open: the executing venue engine can add a code of its own rules)45904591| Status | Codes |4592|---|---|4593| 400 | [`bad_policy`](#err-bad_policy), [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`invalid_order`](#err-invalid_order), [`stale_request`](#err-stale_request) |4594| 401 | [`unauthenticated`](#err-unauthenticated) |4595| 403 | [`execution_disabled`](#err-execution_disabled), [`gmx_disabled`](#err-gmx_disabled), [`gmx_requires_owner_passkey`](#err-gmx_requires_owner_passkey), [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`key_limit_exceeded`](#err-key_limit_exceeded), [`mainnet_disabled`](#err-mainnet_disabled), [`mandate_denied`](#err-mandate_denied), [`mandate_integrity`](#err-mandate_integrity), [`mandate_mainnet_disabled`](#err-mandate_mainnet_disabled), [`mandate_not_approved`](#err-mandate_not_approved), [`mandate_required`](#err-mandate_required), [`mixed_credentials`](#err-mixed_credentials), [`owner_session_required`](#err-owner_session_required), [`position_not_attributable`](#err-position_not_attributable), [`restricted`](#err-restricted), [`spot_execution_requires_agent_vault`](#err-spot_execution_requires_agent_vault), [`venue_restricted`](#err-venue_restricted) |4596| 404 | [`unknown_account`](#err-unknown_account), [`unknown_instrument`](#err-unknown_instrument), [`unknown_position`](#err-unknown_position), [`unknown_venue`](#err-unknown_venue) |4597| 409 | [`account_has_active_mandate`](#err-account_has_active_mandate), [`account_required`](#err-account_required), [`ambiguous_command`](#err-ambiguous_command), [`ambiguous_order`](#err-ambiguous_order), [`ambiguous_position`](#err-ambiguous_position), [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |4598| 422 | [`authorization_expired`](#err-authorization_expired), [`bad_input`](#err-bad_input), [`bad_mark`](#err-bad_mark), [`bad_order`](#err-bad_order), [`bad_policy`](#err-bad_policy), [`below_min_notional`](#err-below_min_notional), [`below_min_size`](#err-below_min_size), [`close_in_app`](#err-close_in_app), [`daily_loss_exceeded`](#err-daily_loss_exceeded), [`data_mismatch`](#err-data_mismatch), [`duplicate_client_id`](#err-duplicate_client_id), [`fee_cap_not_expressible`](#err-fee_cap_not_expressible), [`gmx_leverage_required`](#err-gmx_leverage_required), [`gross_exposure_exceeded`](#err-gross_exposure_exceeded), [`halted`](#err-halted), [`inconsistent_prices`](#err-inconsistent_prices), [`instrument_halted`](#err-instrument_halted), [`instrument_mismatch`](#err-instrument_mismatch), [`instrument_not_allowed`](#err-instrument_not_allowed), [`instrument_reduce_only`](#err-instrument_reduce_only), [`insufficient_collateral`](#err-insufficient_collateral), [`invalid_order`](#err-invalid_order), [`leverage_exceeded`](#err-leverage_exceeded), [`leverage_mismatch`](#err-leverage_mismatch), [`liquidation_too_close`](#err-liquidation_too_close), [`live_not_available`](#err-live_not_available), [`mandate_mismatch`](#err-mandate_mismatch), [`mandate_none`](#err-mandate_none), [`mandate_wind_down`](#err-mandate_wind_down), [`mark_index_divergence`](#err-mark_index_divergence), [`missing_balance`](#err-missing_balance), [`missing_reference_price`](#err-missing_reference_price), [`mode_read_only`](#err-mode_read_only), [`no_account`](#err-no_account), [`no_client_id_format`](#err-no_client_id_format), [`no_instrument`](#err-no_instrument), [`no_position`](#err-no_position), [`not_reducing`](#err-not_reducing), [`order_notional_exceeded`](#err-order_notional_exceeded), [`order_rate_day`](#err-order_rate_day), [`order_rate_minute`](#err-order_rate_minute), [`paper_unsupported`](#err-paper_unsupported), [`position_notional_exceeded`](#err-position_notional_exceeded), [`price_deviation`](#err-price_deviation), [`price_not_on_tick`](#err-price_not_on_tick), [`price_required`](#err-price_required), [`reduce_only_would_flip`](#err-reduce_only_would_flip), [`reduce_only_would_increase`](#err-reduce_only_would_increase), [`risk_denied`](#err-risk_denied), [`size_not_on_lot`](#err-size_not_on_lot), [`spot_buy_needs_quote_amount`](#err-spot_buy_needs_quote_amount), [`spot_market_only`](#err-spot_market_only), [`spot_paper_not_available`](#err-spot_paper_not_available), [`spot_via_swap_screen`](#err-spot_via_swap_screen), [`stale_book`](#err-stale_book), [`stale_ticker`](#err-stale_ticker), [`swap_not_enabled`](#err-swap_not_enabled), [`total_loss_exceeded`](#err-total_loss_exceeded), [`trigger_required`](#err-trigger_required), [`unknown_instrument`](#err-unknown_instrument), [`unsupported_asset`](#err-unsupported_asset), [`venue_not_wired`](#err-venue_not_wired), [`venue_rejected`](#err-venue_rejected), [`zero_size`](#err-zero_size) |4599| 423 | [`halted`](#err-halted), [`kill_switch_active`](#err-kill_switch_active), [`read_only_mode`](#err-read_only_mode) |4600| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4601| 500 | [`internal`](#err-internal) |4602| 501 | [`execution_not_wired`](#err-execution_not_wired) |4603| 502 | [`swap_flow_failed`](#err-swap_flow_failed) |4604| 503 | [`authorization_unknown`](#err-authorization_unknown), [`mandate_unavailable`](#err-mandate_unavailable), [`no_liquidity`](#err-no_liquidity), [`signer_unreachable`](#err-signer_unreachable), [`stale_data`](#err-stale_data), [`unknown_instrument`](#err-unknown_instrument), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |46054606<a id="op-reducePosition"></a>46074608#### POST `/api/v1/trading/positions/{id}/reduce`46094610**Reduce a position.** Operation id `reducePosition`.46114612- **Permission:** `positions:manage` — and a trading mandate bound to the key (403 `mandate_required` otherwise)4613- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice4614- **Side effects:** yes — see the description46154616As close, on a fraction of the position (rounded down to the lot). The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.46174618**Parameters**46194620| Name | In | Type | Required | Description |4621|---|---|---|---|---|4622| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |46234624**Request body** (JSON; unknown fields are refused)46254626| Field | Type | Required | Description |4627|---|---|---|---|4628| `fraction` | `string` | yes | share of the position to close, in (0, 1] — pattern ^(0(\.\d+)?\|1(\.0+)?)$ |4629| `slippageBps` | `integer 1…500` | — | worst acceptable price of the reducing market order, in basis points from the reference price |46304631**Example request**46324633```bash4634curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/reduce" \4635  -H "Authorization: Bearer $SP_WALLET_API_KEY" \4636  -H "Idempotency-Key: $(uuidgen)" \4637  -H "Content-Type: application/json" \4638  -d '{"fraction":"0.5"}'4639```46404641```ts4642const reduced = await client.reducePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC', { fraction: '0.5' });4643```46444645```python4646reduced = client.reduce_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC", fraction="0.5")4647```46484649**Example response** — 200, recorded from a real server46504651```json4652{4653  "order": {4654    "id": "0xae8c2f844447aa3dc5604837d7a7d78f",4655    "orderId": "0xae8c2f844447aa3dc5604837d7a7d78f",4656    "mode": "paper",4657    "venue": "hyperliquid",4658    "network": "mainnet",4659    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",4660    "clientId": "0xae8c2f844447aa3dc5604837d7a7d78f",4661    "clientOrderId": "0xae8c2f844447aa3dc5604837d7a7d78f",4662    "venueOrderId": "paper-o-3",4663    "instrument": "hyperliquid:BTC",4664    "side": "sell",4665    "type": "market",4666    "size": "0.00077",4667    "price": "64104",4668    "triggerPrice": null,4669    "reduceOnly": true,4670    "tif": "ioc",4671    "status": "FILLED",4672    "final": true,4673    "reasonCode": "VENUE_FILLED",4674    "reason": null,4675    "rejectCode": null,4676    "engineStatus": "filled",4677    "filled": "0.00077",4678    "avgFillPrice": "64426",4679    "acknowledged": true,4680    "cancelRequested": false,4681    "origin": "trading_api",4682    "principal": {4683      "kind": "api_key",4684      "id": "spk_0123456789ab"4685    },4686    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",4687    "engine": "paper",4688    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xae8c2f844447aa3dc5604837d7a7d78f",4689    "hash": "1528b646d4c9541d3faddcf092cccca76aa9710a7956c811adb5a5128c1a25ad",4690    "notionalUsd": "49.36008",4691    "projectionError": null,4692    "version": 4,4693    "createdAt": 1794953731442,4694    "updatedAt": 17949537314614695  },4696  "idempotent": false,4697  "approval": null4698}4699```47004701<details><summary><b>Response fields</b></summary>47024703| Field | Type | Required | Description |4704|---|---|---|---|4705| `order` | `Order` | yes |  |4706| `idempotent` | `boolean` | yes | true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again |4707| `approval` | `object \| null` | yes | set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key |4708| `approval.by` | `string` | yes |  |4709| `approval.engine` | `string` | yes |  |4710| `approval.accountId` | `string` | yes |  |4711| `approval.clientId` | `string` | yes |  |4712| `approval.hash` | `string \| null` | yes |  |4713| `approval.expiresAt` | `integer -9007199254740991…9007199254740991 \| null` | yes |  |4714| `approval.approve` | `object` | yes |  |47154716</details>47174718**Errors** (open: the executing venue engine can add a code of its own rules)47194720| Status | Codes |4721|---|---|4722| 400 | [`bad_policy`](#err-bad_policy), [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`invalid_order`](#err-invalid_order), [`stale_request`](#err-stale_request) |4723| 401 | [`unauthenticated`](#err-unauthenticated) |4724| 403 | [`execution_disabled`](#err-execution_disabled), [`gmx_disabled`](#err-gmx_disabled), [`gmx_requires_owner_passkey`](#err-gmx_requires_owner_passkey), [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`key_limit_exceeded`](#err-key_limit_exceeded), [`mainnet_disabled`](#err-mainnet_disabled), [`mandate_denied`](#err-mandate_denied), [`mandate_integrity`](#err-mandate_integrity), [`mandate_mainnet_disabled`](#err-mandate_mainnet_disabled), [`mandate_not_approved`](#err-mandate_not_approved), [`mandate_required`](#err-mandate_required), [`mixed_credentials`](#err-mixed_credentials), [`owner_session_required`](#err-owner_session_required), [`position_not_attributable`](#err-position_not_attributable), [`restricted`](#err-restricted), [`spot_execution_requires_agent_vault`](#err-spot_execution_requires_agent_vault), [`venue_restricted`](#err-venue_restricted) |4725| 404 | [`unknown_account`](#err-unknown_account), [`unknown_instrument`](#err-unknown_instrument), [`unknown_position`](#err-unknown_position), [`unknown_venue`](#err-unknown_venue) |4726| 409 | [`account_has_active_mandate`](#err-account_has_active_mandate), [`account_required`](#err-account_required), [`ambiguous_command`](#err-ambiguous_command), [`ambiguous_order`](#err-ambiguous_order), [`ambiguous_position`](#err-ambiguous_position), [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |4727| 422 | [`authorization_expired`](#err-authorization_expired), [`bad_input`](#err-bad_input), [`bad_mark`](#err-bad_mark), [`bad_order`](#err-bad_order), [`bad_policy`](#err-bad_policy), [`below_min_notional`](#err-below_min_notional), [`below_min_size`](#err-below_min_size), [`close_in_app`](#err-close_in_app), [`daily_loss_exceeded`](#err-daily_loss_exceeded), [`data_mismatch`](#err-data_mismatch), [`duplicate_client_id`](#err-duplicate_client_id), [`fee_cap_not_expressible`](#err-fee_cap_not_expressible), [`gmx_leverage_required`](#err-gmx_leverage_required), [`gross_exposure_exceeded`](#err-gross_exposure_exceeded), [`halted`](#err-halted), [`inconsistent_prices`](#err-inconsistent_prices), [`instrument_halted`](#err-instrument_halted), [`instrument_mismatch`](#err-instrument_mismatch), [`instrument_not_allowed`](#err-instrument_not_allowed), [`instrument_reduce_only`](#err-instrument_reduce_only), [`insufficient_collateral`](#err-insufficient_collateral), [`invalid_order`](#err-invalid_order), [`leverage_exceeded`](#err-leverage_exceeded), [`leverage_mismatch`](#err-leverage_mismatch), [`liquidation_too_close`](#err-liquidation_too_close), [`live_not_available`](#err-live_not_available), [`mandate_mismatch`](#err-mandate_mismatch), [`mandate_none`](#err-mandate_none), [`mandate_wind_down`](#err-mandate_wind_down), [`mark_index_divergence`](#err-mark_index_divergence), [`missing_balance`](#err-missing_balance), [`missing_reference_price`](#err-missing_reference_price), [`mode_read_only`](#err-mode_read_only), [`no_account`](#err-no_account), [`no_client_id_format`](#err-no_client_id_format), [`no_instrument`](#err-no_instrument), [`no_position`](#err-no_position), [`not_reducing`](#err-not_reducing), [`order_notional_exceeded`](#err-order_notional_exceeded), [`order_rate_day`](#err-order_rate_day), [`order_rate_minute`](#err-order_rate_minute), [`paper_unsupported`](#err-paper_unsupported), [`position_notional_exceeded`](#err-position_notional_exceeded), [`price_deviation`](#err-price_deviation), [`price_not_on_tick`](#err-price_not_on_tick), [`price_required`](#err-price_required), [`reduce_only_would_flip`](#err-reduce_only_would_flip), [`reduce_only_would_increase`](#err-reduce_only_would_increase), [`risk_denied`](#err-risk_denied), [`size_not_on_lot`](#err-size_not_on_lot), [`spot_buy_needs_quote_amount`](#err-spot_buy_needs_quote_amount), [`spot_market_only`](#err-spot_market_only), [`spot_paper_not_available`](#err-spot_paper_not_available), [`spot_via_swap_screen`](#err-spot_via_swap_screen), [`stale_book`](#err-stale_book), [`stale_ticker`](#err-stale_ticker), [`swap_not_enabled`](#err-swap_not_enabled), [`total_loss_exceeded`](#err-total_loss_exceeded), [`trigger_required`](#err-trigger_required), [`unknown_instrument`](#err-unknown_instrument), [`unsupported_asset`](#err-unsupported_asset), [`venue_not_wired`](#err-venue_not_wired), [`venue_rejected`](#err-venue_rejected), [`zero_size`](#err-zero_size) |4728| 423 | [`halted`](#err-halted), [`kill_switch_active`](#err-kill_switch_active), [`read_only_mode`](#err-read_only_mode) |4729| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4730| 500 | [`internal`](#err-internal) |4731| 501 | [`execution_not_wired`](#err-execution_not_wired) |4732| 502 | [`swap_flow_failed`](#err-swap_flow_failed) |4733| 503 | [`authorization_unknown`](#err-authorization_unknown), [`mandate_unavailable`](#err-mandate_unavailable), [`no_liquidity`](#err-no_liquidity), [`signer_unreachable`](#err-signer_unreachable), [`stale_data`](#err-stale_data), [`unknown_instrument`](#err-unknown_instrument), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |47344735<a id="tag-orders"></a>47364737### Orders47384739Preview, place, read and cancel orders, and the one-line command grammar. Every order passes the key, the mandate, the risk engine and the venue engine, in that order; a refusal names its gate.47404741<a id="op-listOrders"></a>47424743#### GET `/api/v1/trading/orders`47444745**Orders, newest first.** Operation id `listOrders`.47464747- **Permission:** `orders:read`4748- **Idempotency-Key:** not used4749- **Side effects:** none (a read)47504751Every order of the wallet — placed through this API, in the app or by an agent — in one stable order (creation time, then id), newest first. `status` is the unified state; `engineStatus` is the executing engine's own word. Paginated: `nextCursor` of a page is the `cursor` of the next; null at the end. An order created after the first page was read is not inserted into the pages that follow.47524753**Parameters**47544755| Name | In | Type | Required | Description |4756|---|---|---|---|---|4757| `mode` | query | `"paper" \| "live"` | — | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |4758| `venue` | query | `string` | — | venue id: hyperliquid, gmx, dydx, spot — 0–40 characters |4759| `open` | query | `"true" \| "false"` | — | true: only orders that are not final; false: only final orders |4760| `limit` | query | `integer 1…500` | — | rows returned at most — default 100 |4761| `cursor` | query | `string` | — | opaque position returned as `nextCursor` by the previous page; send it with the same filters — 1–400 characters · pattern ^[A-Za-z0-9_-]+$ |47624763**Example request**47644765```bash4766curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders?open=true&limit=5" \4767  -H "Authorization: Bearer $SP_WALLET_API_KEY"4768```47694770```ts4771const { orders, nextCursor } = await client.listOrders({ open: true, limit: 5 });4772for await (const order of client.iterateOrders({ open: true })) console.log(order.id, order.status);   // every page4773```47744775```python4776page = client.list_orders(open=True, limit=5)4777for order in client.iter_orders(open=True):   # every page4778    print(order.id, order.status)4779```47804781**Example response** — 200, recorded from a real server47824783```json4784{4785  "orders": [4786    {4787      "id": "0x0276bab16d117c8323ee375b61b01d1d",4788      "orderId": "0x0276bab16d117c8323ee375b61b01d1d",4789      "mode": "paper",4790      "venue": "hyperliquid",4791      "network": "mainnet",4792      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",4793      "clientId": "0x0276bab16d117c8323ee375b61b01d1d",4794      "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",4795      "venueOrderId": "paper-o-11",4796      "instrument": "hyperliquid:BTC",4797      "side": "buy",4798      "type": "limit",4799      "size": "0.001",4800      "price": "63775",4801      "triggerPrice": null,4802      "reduceOnly": false,4803      "tif": "gtc",4804      "status": "SUBMITTED",4805      "final": false,4806      "reasonCode": "VENUE_ACCEPTED",4807      "reason": null,4808      "rejectCode": null,4809      "engineStatus": "open",4810      "filled": "0",4811      "avgFillPrice": null,4812      "acknowledged": true,4813      "cancelRequested": false,4814      "origin": "trading_api",4815      "principal": {4816        "kind": "api_key",4817        "id": "spk_0123456789ab"4818      },4819      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",4820      "engine": "paper",4821      "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",4822      "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",4823      "notionalUsd": "63.775",4824      "projectionError": null,4825      "version": 4,4826      "createdAt": 1794953786427,4827      "updatedAt": 17949537864454828    }4829  ],4830  "nextCursor": null,4831  "ts": 17949537864524832}4833```48344835<details><summary><b>Response fields</b></summary>48364837| Field | Type | Required | Description |4838|---|---|---|---|4839| `orders` | `array of Order` | yes |  |4840| `nextCursor` | `string \| null` | yes | pass it as `cursor` to read the next (older) page; null when there is none |4841| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |48424843</details>48444845**Errors**48464847| Status | Codes |4848|---|---|4849| 400 | [`bad_request`](#err-bad_request), [`invalid_cursor`](#err-invalid_cursor) |4850| 401 | [`unauthenticated`](#err-unauthenticated) |4851| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |4852| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4853| 500 | [`internal`](#err-internal) |48544855<a id="op-placeOrder"></a>48564857#### POST `/api/v1/trading/orders`48584859**Place an order.** Operation id `placeOrder`.48604861- **Permission:** `orders:execute` — and a trading mandate bound to the key (403 `mandate_required` otherwise)4862- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice4863- **Side effects:** yes — see the description48644865Idempotent on (principal, Idempotency-Key): a replay answers the same order and never sends a second request to a venue; the same key with a different order answers 409 `idempotency_conflict`.48664867Owner session: the order is checked and waits `AWAITING_APPROVAL` until the owner approves it with the passkey in the app (paper: executed at once, nothing is signed).48684869API key: needs a trading mandate bound to the key that covers the order exactly (403 `mandate_denied` with the reasons otherwise), then the risk engine, then the venue engine's mandate path — the isolated signer applies the derivative mandate it stores.48704871LIVE needs `SPW_TRADING_API_EXECUTION=on` on the server (403 `execution_disabled` otherwise) and the existing mainnet locks. Live orders with a key exist on Hyperliquid only.48724873A refusal after the order exists answers 4xx with the order in `data.order` (state `REJECTED` or `FAILED`). An outcome that is not known is `UNKNOWN`, never a failure.48744875Spot orders: 403 `spot_execution_requires_agent_vault` for a key; 422 `spot_via_swap_screen` for the owner. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.48764877**Request body** (JSON; unknown fields are refused)48784879| Field | Type | Required | Description |4880|---|---|---|---|4881| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |4882| `accountId` | `string` | — | paper account or venue account; required when the wallet has several on the venue — a UUID |4883| `instrument` | `string` | yes | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous — 1–120 characters |4884| `side` | `"buy" \| "sell"` | yes | buy opens or adds to a long (or reduces a short); sell the reverse |4885| `type` | `"limit" \| "market" \| "stop_market" \| "stop_limit" \| "take_profit_market" \| "take_profit_limit"` | yes | 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` |4886| `size` | `string` | — | quantity of the base asset. Exactly one of `size` and `notional` is required — pattern ^\d+(\.\d+)?$ |4887| `notional` | `string` | — | 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 — pattern ^\d+(\.\d+)?$ |4888| `price` | `string` | — | limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order — pattern ^\d+(\.\d+)?$ |4889| `triggerPrice` | `string` | — | price at which a stop or take-profit order is triggered; required by the four trigger types — pattern ^\d+(\.\d+)?$ |4890| `reduceOnly` | `boolean` | — | true: the order may only reduce an existing position — it can neither open, increase nor flip one — default false |4891| `tif` | `"gtc" \| "ioc" \| "alo"` | — | 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) — default "gtc" |4892| `slippageBps` | `integer 1…500` | — | market orders: the worst acceptable price, in basis points from the reference price |4893| `leverage` | `string` | — | paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting — pattern ^\d+(\.\d+)?$ |4894| `maxFeeUsd` | `string` | — | highest fee accepted, USD; default: 10 bps of the notional — pattern ^\d+(\.\d+)?$ |4895| `clientOrderId` | `string` | — | idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal — pattern ^[A-Za-z0-9._:-]{8,100}$ |48964897**Example request**48984899```bash4900curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" \4901  -H "Authorization: Bearer $SP_WALLET_API_KEY" \4902  -H "Idempotency-Key: $(uuidgen)" \4903  -H "Content-Type: application/json" \4904  -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'4905```49064907```ts4908const placed = await client.createOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' }, { idempotencyKey: 'bot-2026-11-17-0001' });4909```49104911```python4912placed = client.create_order(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100", idempotency_key="bot-2026-11-17-0001")4913```49144915**Example response** — 200, recorded from a real server. A paper market order is filled at once by the paper engine against the real Hyperliquid book: `status` is already `FILLED`.49164917```json4918{4919  "order": {4920    "id": "0xff18683e8e2aa319d3812cf8a47fc261",4921    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",4922    "mode": "paper",4923    "venue": "hyperliquid",4924    "network": "mainnet",4925    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",4926    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",4927    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",4928    "venueOrderId": "paper-o-1",4929    "instrument": "hyperliquid:BTC",4930    "side": "buy",4931    "type": "market",4932    "size": "0.00155",4933    "price": "64754",4934    "triggerPrice": null,4935    "reduceOnly": false,4936    "tif": "ioc",4937    "status": "FILLED",4938    "final": true,4939    "reasonCode": "VENUE_FILLED",4940    "reason": null,4941    "rejectCode": null,4942    "engineStatus": "filled",4943    "filled": "0.00155",4944    "avgFillPrice": "64432",4945    "acknowledged": true,4946    "cancelRequested": false,4947    "origin": "trading_api",4948    "principal": {4949      "kind": "api_key",4950      "id": "spk_0123456789ab"4951    },4952    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",4953    "engine": "paper",4954    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",4955    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",4956    "notionalUsd": "100.3687",4957    "projectionError": null,4958    "version": 4,4959    "createdAt": 1794953729578,4960    "updatedAt": 17949537296024961  },4962  "idempotent": false,4963  "approval": null4964}4965```49664967<details><summary><b>Response fields</b></summary>49684969| Field | Type | Required | Description |4970|---|---|---|---|4971| `order` | `Order` | yes |  |4972| `idempotent` | `boolean` | yes | true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again |4973| `approval` | `object \| null` | yes | set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key |4974| `approval.by` | `string` | yes |  |4975| `approval.engine` | `string` | yes |  |4976| `approval.accountId` | `string` | yes |  |4977| `approval.clientId` | `string` | yes |  |4978| `approval.hash` | `string \| null` | yes |  |4979| `approval.expiresAt` | `integer -9007199254740991…9007199254740991 \| null` | yes |  |4980| `approval.approve` | `object` | yes |  |49814982</details>49834984**Errors** (open: the executing venue engine can add a code of its own rules)49854986| Status | Codes |4987|---|---|4988| 400 | [`bad_policy`](#err-bad_policy), [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`invalid_order`](#err-invalid_order), [`stale_request`](#err-stale_request) |4989| 401 | [`unauthenticated`](#err-unauthenticated) |4990| 403 | [`execution_disabled`](#err-execution_disabled), [`gmx_disabled`](#err-gmx_disabled), [`gmx_requires_owner_passkey`](#err-gmx_requires_owner_passkey), [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`key_limit_exceeded`](#err-key_limit_exceeded), [`mainnet_disabled`](#err-mainnet_disabled), [`mandate_denied`](#err-mandate_denied), [`mandate_integrity`](#err-mandate_integrity), [`mandate_mainnet_disabled`](#err-mandate_mainnet_disabled), [`mandate_not_approved`](#err-mandate_not_approved), [`mandate_required`](#err-mandate_required), [`mixed_credentials`](#err-mixed_credentials), [`owner_session_required`](#err-owner_session_required), [`position_not_attributable`](#err-position_not_attributable), [`restricted`](#err-restricted), [`spot_execution_requires_agent_vault`](#err-spot_execution_requires_agent_vault), [`venue_restricted`](#err-venue_restricted) |4991| 404 | [`unknown_account`](#err-unknown_account), [`unknown_instrument`](#err-unknown_instrument), [`unknown_market`](#err-unknown_market), [`unknown_venue`](#err-unknown_venue) |4992| 409 | [`account_has_active_mandate`](#err-account_has_active_mandate), [`account_required`](#err-account_required), [`ambiguous_command`](#err-ambiguous_command), [`ambiguous_order`](#err-ambiguous_order), [`ambiguous_symbol`](#err-ambiguous_symbol), [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |4993| 422 | [`authorization_expired`](#err-authorization_expired), [`bad_input`](#err-bad_input), [`bad_mark`](#err-bad_mark), [`bad_order`](#err-bad_order), [`bad_policy`](#err-bad_policy), [`below_min_notional`](#err-below_min_notional), [`below_min_size`](#err-below_min_size), [`daily_loss_exceeded`](#err-daily_loss_exceeded), [`data_mismatch`](#err-data_mismatch), [`duplicate_client_id`](#err-duplicate_client_id), [`fee_cap_not_expressible`](#err-fee_cap_not_expressible), [`gmx_leverage_required`](#err-gmx_leverage_required), [`gross_exposure_exceeded`](#err-gross_exposure_exceeded), [`halted`](#err-halted), [`inconsistent_prices`](#err-inconsistent_prices), [`instrument_halted`](#err-instrument_halted), [`instrument_mismatch`](#err-instrument_mismatch), [`instrument_not_allowed`](#err-instrument_not_allowed), [`instrument_reduce_only`](#err-instrument_reduce_only), [`insufficient_collateral`](#err-insufficient_collateral), [`invalid_order`](#err-invalid_order), [`leverage_exceeded`](#err-leverage_exceeded), [`leverage_mismatch`](#err-leverage_mismatch), [`liquidation_too_close`](#err-liquidation_too_close), [`live_not_available`](#err-live_not_available), [`mandate_mismatch`](#err-mandate_mismatch), [`mandate_none`](#err-mandate_none), [`mandate_wind_down`](#err-mandate_wind_down), [`mark_index_divergence`](#err-mark_index_divergence), [`missing_balance`](#err-missing_balance), [`missing_reference_price`](#err-missing_reference_price), [`mode_read_only`](#err-mode_read_only), [`no_account`](#err-no_account), [`no_client_id_format`](#err-no_client_id_format), [`no_instrument`](#err-no_instrument), [`no_position`](#err-no_position), [`order_notional_exceeded`](#err-order_notional_exceeded), [`order_rate_day`](#err-order_rate_day), [`order_rate_minute`](#err-order_rate_minute), [`paper_unsupported`](#err-paper_unsupported), [`position_notional_exceeded`](#err-position_notional_exceeded), [`price_deviation`](#err-price_deviation), [`price_not_on_tick`](#err-price_not_on_tick), [`price_required`](#err-price_required), [`reduce_only_would_flip`](#err-reduce_only_would_flip), [`reduce_only_would_increase`](#err-reduce_only_would_increase), [`risk_denied`](#err-risk_denied), [`size_not_on_lot`](#err-size_not_on_lot), [`spot_buy_needs_quote_amount`](#err-spot_buy_needs_quote_amount), [`spot_market_only`](#err-spot_market_only), [`spot_paper_not_available`](#err-spot_paper_not_available), [`spot_via_swap_screen`](#err-spot_via_swap_screen), [`stale_book`](#err-stale_book), [`stale_ticker`](#err-stale_ticker), [`swap_not_enabled`](#err-swap_not_enabled), [`total_loss_exceeded`](#err-total_loss_exceeded), [`trigger_required`](#err-trigger_required), [`unknown_instrument`](#err-unknown_instrument), [`unsupported_asset`](#err-unsupported_asset), [`venue_not_wired`](#err-venue_not_wired), [`venue_rejected`](#err-venue_rejected), [`zero_size`](#err-zero_size) |4994| 423 | [`halted`](#err-halted), [`kill_switch_active`](#err-kill_switch_active), [`read_only_mode`](#err-read_only_mode) |4995| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |4996| 500 | [`internal`](#err-internal) |4997| 501 | [`execution_not_wired`](#err-execution_not_wired) |4998| 502 | [`swap_flow_failed`](#err-swap_flow_failed) |4999| 503 | [`authorization_unknown`](#err-authorization_unknown), [`mandate_unavailable`](#err-mandate_unavailable), [`no_liquidity`](#err-no_liquidity), [`signer_unreachable`](#err-signer_unreachable), [`stale_data`](#err-stale_data), [`unknown_instrument`](#err-unknown_instrument), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |50005001<a id="op-getOrder"></a>50025003#### GET `/api/v1/trading/orders/{id}`50045005**One order and its fills.** Operation id `getOrder`.50065007- **Permission:** `orders:read`5008- **Idempotency-Key:** not used5009- **Side effects:** none (a read)50105011The order in its unified state, its fills, and `history`: every transition it went through, oldest first, with the event and the reason code. Poll this to follow an order until `final` is true (both SDKs: `waitForOrder` / `wait_for_order`); `UNKNOWN` is not final — keep reading.50125013**Parameters**50145015| Name | In | Type | Required | Description |5016|---|---|---|---|---|5017| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |50185019**Example request**50205021```bash5022curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" \5023  -H "Authorization: Bearer $SP_WALLET_API_KEY"5024```50255026```ts5027const { order, fills } = await client.getOrder('0xff18683e8e2aa319d3812cf8a47fc261');5028const done = await client.waitForOrder('0xff18683e8e2aa319d3812cf8a47fc261');   // polls until final; UNKNOWN keeps waiting5029```50305031```python5032detail = client.get_order("0xff18683e8e2aa319d3812cf8a47fc261")5033done = client.wait_for_order("0xff18683e8e2aa319d3812cf8a47fc261")   # polls until final; UNKNOWN keeps waiting5034```50355036**Example response** — 200, recorded from a real server. Fills and history cut to two entries.50375038```json5039{5040  "order": {5041    "id": "0xff18683e8e2aa319d3812cf8a47fc261",5042    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",5043    "mode": "paper",5044    "venue": "hyperliquid",5045    "network": "mainnet",5046    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",5047    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",5048    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",5049    "venueOrderId": "paper-o-1",5050    "instrument": "hyperliquid:BTC",5051    "side": "buy",5052    "type": "market",5053    "size": "0.00155",5054    "price": "64754",5055    "triggerPrice": null,5056    "reduceOnly": false,5057    "tif": "ioc",5058    "status": "FILLED",5059    "final": true,5060    "reasonCode": "VENUE_FILLED",5061    "reason": null,5062    "rejectCode": null,5063    "engineStatus": "filled",5064    "filled": "0.00155",5065    "avgFillPrice": "64432",5066    "acknowledged": true,5067    "cancelRequested": false,5068    "origin": "trading_api",5069    "principal": {5070      "kind": "api_key",5071      "id": "spk_0123456789ab"5072    },5073    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",5074    "engine": "paper",5075    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",5076    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",5077    "notionalUsd": "100.3687",5078    "projectionError": null,5079    "version": 4,5080    "createdAt": 1794953729578,5081    "updatedAt": 1794953729602,5082    "canonical": {5083      "v": 1,5084      "tif": "ioc",5085      "mode": "paper",5086      "side": "buy",5087      "size": "0.00155",5088      "type": "market",5089      "venue": "hyperliquid",5090      "network": "mainnet",5091      "leverage": null,5092      "notional": null,5093      "createdAt": 1794953729578,5094      "expiresAt": 1794953849578,5095      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",5096      "maxFeeUsd": "0.099869",5097      "principal": {5098        "id": "spk_0123456789ab",5099        "kind": "api_key"5100      },5101      "instrument": "hyperliquid:BTC",5102      "limitPrice": null,5103      "marginMode": null,5104      "marketKind": "perp",5105      "reduceOnly": false,5106      "triggerPrice": null,5107      "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",5108      "maxSlippageBps": 505109    }5110  },5111  "fills": [5112    {5113      "id": "paper-f-2",5114      "instrument": "hyperliquid:BTC",5115      "side": "buy",5116      "price": "64432",5117      "size": "0.00155",5118      "fee": "0.04494132",5119      "feeAsset": "USDC",5120      "closedPnl": null,5121      "liquidation": false,5122      "ts": 17949537295955123    }5124  ],5125  "history": [5126    {5127      "seq": 1,5128      "from": "CREATED",5129      "to": "VALIDATED",5130      "event": "validated",5131      "reason": "VALIDATION_PASSED",5132      "detail": null,5133      "at": 17949537295905134    },5135    {5136      "seq": 2,5137      "from": "VALIDATED",5138      "to": "APPROVED",5139      "event": "approved",5140      "reason": "APPROVED_BY_MANDATE",5141      "detail": null,5142      "at": 17949537295935143    }5144  ]5145}5146```51475148<details><summary><b>Response fields</b></summary>51495150| Field | Type | Required | Description |5151|---|---|---|---|5152| `order` | `Order` | yes |  |5153| `fills` | `array of object` | yes |  |5154| `fills[].id` | `string` | yes |  |5155| `fills[].instrument` | `string` | yes |  |5156| `fills[].side` | `string` | yes |  |5157| `fills[].price` | `string` | yes | decimal number as a string (never a float) |5158| `fills[].size` | `string` | yes | decimal number as a string (never a float) |5159| `fills[].fee` | `string` | yes | decimal number as a string (never a float) |5160| `fills[].feeAsset` | `string` | yes |  |5161| `fills[].closedPnl` | `string \| null` | yes |  |5162| `fills[].liquidation` | `boolean` | yes |  |5163| `fills[].ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |5164| `history` | `array of object` | — | the transitions of the order, oldest first (absent for `agent:` rows) |51655166</details>51675168**Errors**51695170| Status | Codes |5171|---|---|5172| 400 | [`bad_request`](#err-bad_request) |5173| 401 | [`unauthenticated`](#err-unauthenticated) |5174| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |5175| 404 | [`unknown_order`](#err-unknown_order) |5176| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5177| 500 | [`internal`](#err-internal) |51785179<a id="op-cancelOrder"></a>51805181#### DELETE `/api/v1/trading/orders/{id}`51825183**Cancel an order.** Operation id `cancelOrder`.51845185- **Permission:** `orders:cancel`5186- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice5187- **Side effects:** yes — see the description51885189A key cancels its OWN orders only (403 `not_your_order`); no trading mandate is required, and the kill switch and read-only mode never stop a cancel: it can only remove what could still execute. At the venue the order is `CANCELLED` when the venue says so. An order that is already final answers 200 with `changed: false`.51905191**Parameters**51925193| Name | In | Type | Required | Description |5194|---|---|---|---|---|5195| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |51965197**Example request**51985199```bash5200curl -s -X DELETE "$SP_WALLET_BASE_URL/api/v1/trading/orders/0x0276bab16d117c8323ee375b61b01d1d" \5201  -H "Authorization: Bearer $SP_WALLET_API_KEY" \5202  -H "Idempotency-Key: $(uuidgen)"5203```52045205```ts5206const { order, changed } = await client.cancelOrder('0x0276bab16d117c8323ee375b61b01d1d');5207```52085209```python5210cancelled = client.cancel_order("0x0276bab16d117c8323ee375b61b01d1d")5211```52125213**Example response** — 200, recorded from a real server. Cancelling again answers 200 with `changed: false`.52145215```json5216{5217  "order": {5218    "id": "0x0276bab16d117c8323ee375b61b01d1d",5219    "orderId": "0x0276bab16d117c8323ee375b61b01d1d",5220    "mode": "paper",5221    "venue": "hyperliquid",5222    "network": "mainnet",5223    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",5224    "clientId": "0x0276bab16d117c8323ee375b61b01d1d",5225    "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",5226    "venueOrderId": "paper-o-11",5227    "instrument": "hyperliquid:BTC",5228    "side": "buy",5229    "type": "limit",5230    "size": "0.001",5231    "price": "63775",5232    "triggerPrice": null,5233    "reduceOnly": false,5234    "tif": "gtc",5235    "status": "CANCELLED",5236    "final": true,5237    "reasonCode": "CANCELLED_BY_REQUEST",5238    "reason": "cancelled by the user",5239    "rejectCode": null,5240    "engineStatus": "cancelled",5241    "filled": "0",5242    "avgFillPrice": null,5243    "acknowledged": true,5244    "cancelRequested": true,5245    "origin": "trading_api",5246    "principal": {5247      "kind": "api_key",5248      "id": "spk_0123456789ab"5249    },5250    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",5251    "engine": "paper",5252    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",5253    "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",5254    "notionalUsd": "63.775",5255    "projectionError": null,5256    "version": 6,5257    "createdAt": 1794953786427,5258    "updatedAt": 17949537864595259  },5260  "sent": false,5261  "changed": true,5262  "venue": null5263}5264```52655266<details><summary><b>Response fields</b></summary>52675268| Field | Type | Required | Description |5269|---|---|---|---|5270| `order` | `Order` | yes |  |5271| `sent` | `boolean` | yes | true: a cancel request went to a venue |5272| `changed` | `boolean` | yes | false: the order was already final |5273| `venue` | `any` | — |  |52745275</details>52765277**Errors**52785279| Status | Codes |5280|---|---|5281| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |5282| 401 | [`unauthenticated`](#err-unauthenticated) |5283| 403 | [`gmx_requires_owner_passkey`](#err-gmx_requires_owner_passkey), [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`not_your_order`](#err-not_your_order), [`owner_session_required`](#err-owner_session_required) |5284| 404 | [`unknown_order`](#err-unknown_order) |5285| 409 | [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |5286| 422 | [`cancel_in_app`](#err-cancel_in_app), [`venue_rejected`](#err-venue_rejected) |5287| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5288| 500 | [`internal`](#err-internal) |5289| 503 | [`signer_unreachable`](#err-signer_unreachable), [`venue_unavailable`](#err-venue_unavailable) |52905291<a id="op-previewOrder"></a>52925293#### POST `/api/v1/trading/orders/preview`52945295**Preview an order: every check it would meet, and an estimate.** Operation id `previewOrder`.52965297- **Permission:** `orders:prepare`5298- **Idempotency-Key:** not used5299- **Side effects:** none: creates, signs and sends nothing53005301Resolves the instrument and the account, then runs the key limits, the server locks, the trading mandate (keys and agents), the independent risk engine and the venue engine's own checks on the market as it is now.53025303Answers the canonical order and its hash, every check with what was observed and its limit, an estimate (fees, slippage against the real book, liquidation price) and whether an owner passkey approval would be required. Never creates, signs or sends anything; takes no Idempotency-Key.53045305What WOULD refuse the order is in `refusals` (HTTP 200), not an error answer.53065307A key previews the order it could place: a key with no trading mandate bound to it answers 403 `mandate_required` (the scope itself needs no mandate; the previewed order does). Account figures (equity, free collateral, positions) are answered only to a key that also holds `wallet:read` or `positions:read` (`account.withheld`).53085309**Request body** (JSON; unknown fields are refused)53105311| Field | Type | Required | Description |5312|---|---|---|---|5313| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |5314| `accountId` | `string` | — | paper account or venue account; required when the wallet has several on the venue — a UUID |5315| `instrument` | `string` | yes | `venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous — 1–120 characters |5316| `side` | `"buy" \| "sell"` | yes | buy opens or adds to a long (or reduces a short); sell the reverse |5317| `type` | `"limit" \| "market" \| "stop_market" \| "stop_limit" \| "take_profit_market" \| "take_profit_limit"` | yes | 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` |5318| `size` | `string` | — | quantity of the base asset. Exactly one of `size` and `notional` is required — pattern ^\d+(\.\d+)?$ |5319| `notional` | `string` | — | 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 — pattern ^\d+(\.\d+)?$ |5320| `price` | `string` | — | limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order — pattern ^\d+(\.\d+)?$ |5321| `triggerPrice` | `string` | — | price at which a stop or take-profit order is triggered; required by the four trigger types — pattern ^\d+(\.\d+)?$ |5322| `reduceOnly` | `boolean` | — | true: the order may only reduce an existing position — it can neither open, increase nor flip one — default false |5323| `tif` | `"gtc" \| "ioc" \| "alo"` | — | 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) — default "gtc" |5324| `slippageBps` | `integer 1…500` | — | market orders: the worst acceptable price, in basis points from the reference price |5325| `leverage` | `string` | — | paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting — pattern ^\d+(\.\d+)?$ |5326| `maxFeeUsd` | `string` | — | highest fee accepted, USD; default: 10 bps of the notional — pattern ^\d+(\.\d+)?$ |5327| `clientOrderId` | `string` | — | idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal — pattern ^[A-Za-z0-9._:-]{8,100}$ |53285329**Example request**53305331```bash5332curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" \5333  -H "Authorization: Bearer $SP_WALLET_API_KEY" \5334  -H "Content-Type: application/json" \5335  -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'5336```53375338```ts5339const preview = await client.previewOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' });5340if (!preview.wouldExecute) console.log(preview.refusals);5341```53425343```python5344preview = client.preview_order(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")5345if not preview.would_execute:5346    print(preview.refusals)5347```53485349**Example response** — 200, recorded from a real server. Risk checks cut to two. `wouldExecute` is true exactly when `refusals` is empty.53505351```json5352{5353  "order": {5354    "v": 1,5355    "venue": "hyperliquid",5356    "network": "mainnet",5357    "instrument": "hyperliquid:BTC",5358    "marketKind": "perp",5359    "side": "buy",5360    "type": "market",5361    "size": "0.00155",5362    "notional": null,5363    "limitPrice": null,5364    "triggerPrice": null,5365    "reduceOnly": false,5366    "tif": "ioc",5367    "maxSlippageBps": 50,5368    "maxFeeUsd": "0.099869",5369    "leverage": null,5370    "marginMode": null,5371    "clientOrderId": "0xc7f8200619c1018d8757a6318aab7a51",5372    "mode": "paper",5373    "principal": {5374      "kind": "api_key",5375      "id": "spk_0123456789ab"5376    },5377    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",5378    "createdAt": 1794953729364,5379    "expiresAt": 17949538493645380  },5381  "hash": "a780accd8e5abce90b3975329e8386b8117bbd470727ae3b442bbaf852163506",5382  "resolved": {5383    "size": "0.00155",5384    "worstPrice": "64754",5385    "notionalUsd": "100.3687"5386  },5387  "wouldExecute": true,5388  "refusals": [],5389  "approval": {5390    "required": false,5391    "by": "mandate",5392    "note": "paper: nothing is signed"5393  },5394  "risk": {5395    "decision": "allow",5396    "reducing": false,5397    "checks": [5398      {5399        "id": "input_valid",5400        "ok": true,5401        "observed": null,5402        "limit": null,5403        "detail": "request, context and limits are well formed",5404        "exempt": false5405      },5406      {5407        "id": "read_only",5408        "ok": true,5409        "observed": "false",5410        "limit": "false",5411        "detail": "not in read-only mode",5412        "exempt": false5413      }5414    ],5415    "derived": {5416      "size": "0.00155",5417      "notional": "99.91207",5418      "referencePrice": "64459.4",5419      "positionBefore": "0",5420      "positionAfter": "0.00155"5421    },5422    "decisionId": 15423  },5424  "mandate": {5425    "id": "84f954ea-0c25-4985-bc19-901d510964d7",5426    "decision": "allow",5427    "reasons": [],5428    "phase": "active"5429  },5430  "engine": {5431    "name": "paper",5432    "risk": {5433      "ok": true5434    },5435    "estimate": {5436      "leverage": "3",5437      "price": "64754",5438      "source": "estimate",5439      "notional": "99.8696",5440      "initialMargin": "33.289866666666666667",5441      "fee": "0.04494132",5442      "avgFillPrice": "64432",5443      "slippageBps": "-0.0776",5444      "liquidationPrice": {5445        "value": null,5446        "source": "estimate",5447        "method": "cross, single-position approximation at a flat maintenance fraction of 0.02; position after the immediate fills; no funding, no fees"5448      },5449      "freeCollateralAfter": "9966.66415868",5450      "filledSize": "0.00155",5451      "restingSize": "0",5452      "status": "filled",5453      "rejectReason": null5454    }5455  },5456  "account": {5457    "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",5458    "venue": "hyperliquid",5459    "network": "mainnet",5460    "equity": "10000",5461    "freeCollateral": "10000",5462    "withheld": false5463  },5464  "ts": 17949537293645465}5466```54675468<details><summary><b>Response fields</b></summary>54695470| Field | Type | Required | Description |5471|---|---|---|---|5472| `order` | `CanonicalOrder` | yes |  |5473| `hash` | `string` | yes | SHA-256 of the canonical bytes, hex |5474| `resolved` | `object \| null` | yes | what the canonical order leaves open; null when it could not be resolved (see `refusals`) |5475| `resolved.size` | `string \| null` | yes | base units; null when the order is sized by a quote amount the venue converts (a GMX increase) |5476| `resolved.worstPrice` | `string \| null` | yes |  |5477| `resolved.notionalUsd` | `string \| null` | yes |  |5478| `wouldExecute` | `boolean` | yes | true exactly when `refusals` is empty |5479| `refusals` | `array of object` | yes |  |5480| `refusals[].stage` | `"key" \| "lock" \| "mandate" \| "risk" \| "engine"` | yes |  |5481| `refusals[].code` | `string` | yes |  |5482| `refusals[].message` | `string` | yes |  |5483| `refusals[].reasons` | `array of string` | — |  |5484| `approval` | `object` | yes |  |5485| `approval.required` | `boolean` | yes |  |5486| `approval.by` | `"owner_passkey" \| "mandate" \| "none"` | yes |  |5487| `risk` | `object` | yes |  |5488| `risk.decision` | `"allow" \| "deny"` | yes |  |5489| `risk.reducing` | `boolean` | yes |  |5490| `risk.checks` | `array of RiskCheck` | yes |  |5491| `risk.derived` | `object \| null` | yes | null for a spot order: of the risk engine only the kill switch and read-only mode apply to it |5492| `mandate` | `object \| null` | yes | null for the owner session, and when the key's mandate cannot be used (a `mandate` refusal then says why) |5493| `mandate.id` | `string` | yes |  |5494| `mandate.decision` | `"allow" \| "deny"` | yes |  |5495| `mandate.reasons` | `array of string` | yes |  |5496| `engine` | `object` | yes |  |5497| `engine.name` | `string` | yes |  |5498| `engine.risk` | `object \| null` | yes |  |5499| `engine.estimate` | `object \| null` | yes | fees, slippage against the real book, liquidation price: an estimate |5500| `account` | `object` | yes |  |5501| `account.id` | `string \| null` | yes | null for a spot order (the wallet itself) |5502| `account.venue` | `string` | yes |  |5503| `account.network` | `string` | yes |  |5504| `account.equity` | `string \| null` | — |  |5505| `account.freeCollateral` | `string \| null` | — |  |5506| `account.withheld` | `boolean` | yes | true: the key holds neither `wallet:read` nor `positions:read`, so `equity`, `freeCollateral`, the position figures of `risk.derived`, and the account figures of the risk checks, of the refusal sentences and of the estimate are omitted |5507| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |55085509</details>55105511**Errors**55125513| Status | Codes |5514|---|---|5515| 400 | [`bad_request`](#err-bad_request), [`invalid_order`](#err-invalid_order) |5516| 401 | [`unauthenticated`](#err-unauthenticated) |5517| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mandate_required`](#err-mandate_required), [`mixed_credentials`](#err-mixed_credentials), [`owner_session_required`](#err-owner_session_required), [`restricted`](#err-restricted), [`spot_execution_requires_agent_vault`](#err-spot_execution_requires_agent_vault), [`venue_restricted`](#err-venue_restricted) |5518| 404 | [`unknown_account`](#err-unknown_account), [`unknown_instrument`](#err-unknown_instrument), [`unknown_market`](#err-unknown_market), [`unknown_venue`](#err-unknown_venue) |5519| 409 | [`account_required`](#err-account_required), [`ambiguous_command`](#err-ambiguous_command), [`ambiguous_order`](#err-ambiguous_order), [`ambiguous_symbol`](#err-ambiguous_symbol) |5520| 422 | [`below_min_size`](#err-below_min_size), [`fee_cap_not_expressible`](#err-fee_cap_not_expressible), [`gmx_leverage_required`](#err-gmx_leverage_required), [`inconsistent_prices`](#err-inconsistent_prices), [`invalid_order`](#err-invalid_order), [`missing_balance`](#err-missing_balance), [`missing_reference_price`](#err-missing_reference_price), [`no_account`](#err-no_account), [`no_client_id_format`](#err-no_client_id_format), [`no_instrument`](#err-no_instrument), [`no_position`](#err-no_position), [`spot_buy_needs_quote_amount`](#err-spot_buy_needs_quote_amount), [`spot_market_only`](#err-spot_market_only), [`spot_paper_not_available`](#err-spot_paper_not_available), [`spot_via_swap_screen`](#err-spot_via_swap_screen), [`swap_not_enabled`](#err-swap_not_enabled), [`unknown_instrument`](#err-unknown_instrument), [`unsupported_asset`](#err-unsupported_asset), [`venue_not_wired`](#err-venue_not_wired), [`venue_rejected`](#err-venue_rejected), [`zero_size`](#err-zero_size) |5521| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5522| 500 | [`internal`](#err-internal) |5523| 501 | [`execution_not_wired`](#err-execution_not_wired) |5524| 502 | [`swap_flow_failed`](#err-swap_flow_failed) |5525| 503 | [`stale_data`](#err-stale_data), [`unknown_instrument`](#err-unknown_instrument), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |55265527<a id="op-runCommand"></a>55285529#### POST `/api/v1/trading/commands`55305531**Run one line of the trading command grammar.** Operation id `runCommand`.55325533- **Permission:** `orders:prepare`5534- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice5535- **Side effects:** yes — see the description55365537Deterministic grammar (no model): LONG|SHORT <asset>-PERP <notional> [x<lev>] [LIMIT <px>] [SL <px>] [TP <px>] [ON <venue>], CLOSE <asset>-PERP [pct%], CANCEL ORDER <id>, CANCEL ALL, SHOW POSITIONS|BALANCES|ORDERS|RISK, STOP ALL AGENTS, KILL, and for the owner BUY/SELL (spot).55385539The scope checked is the one of the operation the command resolves to: an order needs `orders:execute` (`orders:prepare` with `dryRun`), CLOSE `positions:manage`, CANCEL `orders:cancel`, SHOW the matching read scope, KILL `positions:manage`.55405541Resolution uses the owner's stored defaults (GET/PUT /api/v1/developer/command-defaults) and nothing else: a command the defaults do not settle answers 409 `ambiguous_command` with the questions in `data.questions` and executes nothing.55425543`kind` says what the command resolved to: `query` (the read answer is in `data`), `control` (a cancel or the kill switch) or `order`. A spot order (BUY ETH 100 USDC, SELL ETH 0.5) is the owner's: it becomes a swap proposal approved with the passkey. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.55445545**Request body** (JSON; unknown fields are refused)55465547| Field | Type | Required | Description |5548|---|---|---|---|5549| `text` | `string` | yes | 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 … — 1–300 characters |5550| `mode` | `"paper" \| "live"` | — | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. — default "paper" |5551| `accountId` | `string` | — | paper account or venue account; required when the wallet has several on the venue — a UUID |5552| `dryRun` | `boolean` | — | true: answer the canonical order (or the control) the command resolves to, and do nothing — default false |55535554**Example request**55555556```bash5557curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/commands" \5558  -H "Authorization: Bearer $SP_WALLET_API_KEY" \5559  -H "Idempotency-Key: $(uuidgen)" \5560  -H "Content-Type: application/json" \5561  -d '{"text":"LONG BTC-PERP 100","mode":"paper","dryRun":true}'5562```55635564```ts5565const r = await client.runCommand('LONG BTC-PERP 100', { mode: 'paper', dryRun: true });5566if (r.kind === 'order' && !r.executed) console.log(r.order, r.hash);5567```55685569```python5570r = client.run_command("LONG BTC-PERP 100", mode="paper", dry_run=True)5571```55725573**Example response** — 200, recorded from a real server. A dry run: the canonical order the line resolves to, and nothing created. Needs the owner's command defaults (see Commands).55745575```json5576{5577  "command": "perp_open",5578  "mode": "paper",5579  "dryRun": true,5580  "kind": "order",5581  "order": {5582    "v": 1,5583    "venue": "hyperliquid",5584    "network": "mainnet",5585    "instrument": "hyperliquid:BTC",5586    "marketKind": "perp",5587    "side": "buy",5588    "type": "market",5589    "size": null,5590    "notional": "100",5591    "limitPrice": null,5592    "triggerPrice": null,5593    "reduceOnly": false,5594    "tif": "ioc",5595    "maxSlippageBps": 50,5596    "maxFeeUsd": "0.1",5597    "leverage": "2",5598    "marginMode": "cross",5599    "clientOrderId": "0x58617397cbaee774b5a74ada6581a070",5600    "mode": "paper",5601    "principal": {5602      "kind": "api_key",5603      "id": "spk_0123456789ab"5604    },5605    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",5606    "createdAt": 1794953783632,5607    "expiresAt": 17949538436325608  },5609  "hash": "5a6980aa9a3668f4618c2186974428ca40b83bc68ce2be2194f5a02732c57db5",5610  "attached": [],5611  "executed": false5612}5613```56145615**Response** — one of:561656171. SHOW …56185619| Field | Type | Required | Description |5620|---|---|---|---|5621| `kind` | `"query"` | yes |  |5622| `command` | `string` | yes | the parsed command type |5623| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |5624| `dryRun` | `boolean` | yes |  |5625| `query` | `string` | yes |  |5626| `data` | `object` | yes | the answer of the matching read operation |562756282. CANCEL, KILL, STOP ALL AGENTS56295630| Field | Type | Required | Description |5631|---|---|---|---|5632| `kind` | `"control"` | yes |  |5633| `command` | `string` | yes | the parsed command type |5634| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |5635| `dryRun` | `boolean` | yes |  |5636| `executed` | `boolean` | yes |  |5637| `control` | `object` | yes |  |5638| `result` | `object` | — | CANCEL ORDER, executed: the answer of the cancel |5639| `results` | `array of object` | — | CANCEL ALL, executed: one row per order |5640| `orders` | `array of string` | — | CANCEL ALL, dry run: the ids that would be cancelled |5641| `killSwitch` | `Switch` | — |  |564256433. an order command with `dryRun`56445645| Field | Type | Required | Description |5646|---|---|---|---|5647| `kind` | `"order"` | yes |  |5648| `command` | `string` | yes | the parsed command type |5649| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |5650| `dryRun` | `boolean` | yes |  |5651| `executed` | `false` | yes |  |5652| `order` | `CanonicalOrder` | yes | the canonical order the command resolves to; nothing was created |5653| `hash` | `string` | yes |  |5654| `attached` | `array of object` | yes |  |5655| `preview` | `object` | — | spot: the preview of the swap the order would become |565656574. an order command, executed56585659| Field | Type | Required | Description |5660|---|---|---|---|5661| `kind` | `"order"` | yes |  |5662| `command` | `string` | yes | the parsed command type |5663| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |5664| `dryRun` | `boolean` | yes |  |5665| `executed` | `true` | yes |  |5666| `order` | `Order` | yes | the order that was placed, as POST /orders answers it |5667| `canonical` | `CanonicalOrder` | yes | the canonical order that was placed |5668| `hash` | `string` | yes |  |5669| `idempotent` | `boolean` | yes |  |5670| `approval` | `object \| null` | yes |  |5671| `attached` | `array of object` | yes |  |56725673**Errors** (open: the executing venue engine can add a code of its own rules)56745675| Status | Codes |5676|---|---|5677| 400 | [`bad_policy`](#err-bad_policy), [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`invalid_order`](#err-invalid_order), [`parse_error`](#err-parse_error), [`stale_request`](#err-stale_request) |5678| 401 | [`unauthenticated`](#err-unauthenticated) |5679| 403 | [`execution_disabled`](#err-execution_disabled), [`gmx_disabled`](#err-gmx_disabled), [`gmx_requires_owner_passkey`](#err-gmx_requires_owner_passkey), [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`key_limit_exceeded`](#err-key_limit_exceeded), [`mainnet_disabled`](#err-mainnet_disabled), [`mandate_denied`](#err-mandate_denied), [`mandate_integrity`](#err-mandate_integrity), [`mandate_mainnet_disabled`](#err-mandate_mainnet_disabled), [`mandate_not_approved`](#err-mandate_not_approved), [`mandate_required`](#err-mandate_required), [`mixed_credentials`](#err-mixed_credentials), [`not_your_order`](#err-not_your_order), [`owner_session_required`](#err-owner_session_required), [`position_not_attributable`](#err-position_not_attributable), [`restricted`](#err-restricted), [`spot_execution_requires_agent_vault`](#err-spot_execution_requires_agent_vault), [`venue_restricted`](#err-venue_restricted) |5680| 404 | [`unknown_account`](#err-unknown_account), [`unknown_instrument`](#err-unknown_instrument), [`unknown_order`](#err-unknown_order), [`unknown_venue`](#err-unknown_venue) |5681| 409 | [`account_has_active_mandate`](#err-account_has_active_mandate), [`account_required`](#err-account_required), [`ambiguous_command`](#err-ambiguous_command), [`ambiguous_order`](#err-ambiguous_order), [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |5682| 422 | [`authorization_expired`](#err-authorization_expired), [`bad_input`](#err-bad_input), [`bad_mark`](#err-bad_mark), [`bad_order`](#err-bad_order), [`bad_policy`](#err-bad_policy), [`below_min_notional`](#err-below_min_notional), [`below_min_size`](#err-below_min_size), [`cancel_in_app`](#err-cancel_in_app), [`daily_loss_exceeded`](#err-daily_loss_exceeded), [`data_mismatch`](#err-data_mismatch), [`duplicate_client_id`](#err-duplicate_client_id), [`fee_cap_not_expressible`](#err-fee_cap_not_expressible), [`gmx_leverage_required`](#err-gmx_leverage_required), [`gross_exposure_exceeded`](#err-gross_exposure_exceeded), [`halted`](#err-halted), [`inconsistent_prices`](#err-inconsistent_prices), [`instrument_halted`](#err-instrument_halted), [`instrument_mismatch`](#err-instrument_mismatch), [`instrument_not_allowed`](#err-instrument_not_allowed), [`instrument_reduce_only`](#err-instrument_reduce_only), [`insufficient_collateral`](#err-insufficient_collateral), [`invalid_order`](#err-invalid_order), [`leverage_exceeded`](#err-leverage_exceeded), [`leverage_mismatch`](#err-leverage_mismatch), [`liquidation_too_close`](#err-liquidation_too_close), [`live_not_available`](#err-live_not_available), [`mandate_mismatch`](#err-mandate_mismatch), [`mandate_none`](#err-mandate_none), [`mandate_wind_down`](#err-mandate_wind_down), [`mark_index_divergence`](#err-mark_index_divergence), [`missing_balance`](#err-missing_balance), [`missing_reference_price`](#err-missing_reference_price), [`mode_read_only`](#err-mode_read_only), [`no_account`](#err-no_account), [`no_client_id_format`](#err-no_client_id_format), [`no_instrument`](#err-no_instrument), [`no_position`](#err-no_position), [`not_reducing`](#err-not_reducing), [`order_notional_exceeded`](#err-order_notional_exceeded), [`order_rate_day`](#err-order_rate_day), [`order_rate_minute`](#err-order_rate_minute), [`paper_unsupported`](#err-paper_unsupported), [`position_notional_exceeded`](#err-position_notional_exceeded), [`price_deviation`](#err-price_deviation), [`price_not_on_tick`](#err-price_not_on_tick), [`price_required`](#err-price_required), [`reduce_only_would_flip`](#err-reduce_only_would_flip), [`reduce_only_would_increase`](#err-reduce_only_would_increase), [`risk_denied`](#err-risk_denied), [`size_not_on_lot`](#err-size_not_on_lot), [`spot_buy_needs_quote_amount`](#err-spot_buy_needs_quote_amount), [`spot_market_only`](#err-spot_market_only), [`spot_paper_not_available`](#err-spot_paper_not_available), [`spot_via_swap_screen`](#err-spot_via_swap_screen), [`stale_book`](#err-stale_book), [`stale_ticker`](#err-stale_ticker), [`swap_not_enabled`](#err-swap_not_enabled), [`total_loss_exceeded`](#err-total_loss_exceeded), [`trigger_required`](#err-trigger_required), [`unknown_instrument`](#err-unknown_instrument), [`unsupported_asset`](#err-unsupported_asset), [`venue_not_wired`](#err-venue_not_wired), [`venue_rejected`](#err-venue_rejected), [`zero_size`](#err-zero_size) |5683| 423 | [`halted`](#err-halted), [`kill_switch_active`](#err-kill_switch_active), [`read_only_mode`](#err-read_only_mode) |5684| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5685| 500 | [`internal`](#err-internal) |5686| 501 | [`execution_not_wired`](#err-execution_not_wired) |5687| 502 | [`swap_flow_failed`](#err-swap_flow_failed) |5688| 503 | [`authorization_unknown`](#err-authorization_unknown), [`mandate_unavailable`](#err-mandate_unavailable), [`no_liquidity`](#err-no_liquidity), [`service_unavailable`](#err-service_unavailable), [`signer_unreachable`](#err-signer_unreachable), [`stale_data`](#err-stale_data), [`unknown_instrument`](#err-unknown_instrument), [`venue_rate_limited`](#err-venue_rate_limited), [`venue_timeout`](#err-venue_timeout), [`venue_unavailable`](#err-venue_unavailable) |56895690<a id="tag-strategies"></a>56915692### Strategies56935694The strategy library and the versions pinned to agents: register, backtest, start, stop. Research and paper sign nothing.56955696<a id="op-listStrategies"></a>56975698#### GET `/api/v1/trading/strategies`56995700**Strategy library and the versions pinned to agents.** Operation id `listStrategies`.57015702- **Permission:** `strategies:read`5703- **Idempotency-Key:** not used5704- **Side effects:** none (a read)57055706`library`: the strategy files installed in the laboratory, each with its `path` (what POST /strategies takes) and the SHA-256 of the file. `versions`: the versions registered on agents, with their status. A source that cannot be read is listed in `errors`.57075708**Parameters**57095710| Name | In | Type | Required | Description |5711|---|---|---|---|---|5712| `kind` | query | `"spot" \| "perp"` | — | only spot or only perp strategies |57135714**Example request**57155716```bash5717curl -s "$SP_WALLET_BASE_URL/api/v1/trading/strategies?kind=perp" \5718  -H "Authorization: Bearer $SP_WALLET_API_KEY"5719```57205721```ts5722const { library, versions } = await client.listStrategies({ kind: 'perp' });5723```57245725```python5726strategies = client.list_strategies(kind="perp")5727```57285729**Example response** — 200, recorded from a real server. Cut to one library entry and one version.57305731```json5732{5733  "library": [5734    {5735      "kind": "perp",5736      "path": "strategies/basis_cash_carry/1",5737      "sha256": "344831f2ea276d1b3935164287a3e81e5dcc2940841622a88fb3ca218a0a790b",5738      "meta": {5739        "name": "basis_cash_carry",5740        "version": "1",5741        "kind": "perp",5742        "universe": [5743          "BTC"5744        ],5745        "interval": "1h",5746        "lookback": 720,5747        "max_leverage": 1,5748        "max_gross_exposure": 1,5749        "params": {5750          "window": 168,5751          "enter_net_apr": 0.05,5752          "exit_apr": 0.02,5753          "round_trip_cost_bps": 60,5754          "holding_days": 30,5755          "max_adverse_basis_bps": 15,5756          "state_bars": 336,5757          "gross": 0.95758        }5759      }5760    }5761  ],5762  "versions": [5763    {5764      "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",5765      "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",5766      "kind": "perp",5767      "name": "momentum_xs_perp",5768      "version": "2",5769      "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",5770      "status": "backtesting",5771      "hasReport": false,5772      "createdAt": 1794953786690,5773      "approvedAt": null5774    }5775  ],5776  "errors": []5777}5778```57795780<details><summary><b>Response fields</b></summary>57815782| Field | Type | Required | Description |5783|---|---|---|---|5784| `library` | `array of object` | yes |  |5785| `library[].kind` | `"spot" \| "perp"` | yes |  |5786| `library[].path` | `string` | yes |  |5787| `library[].sha256` | `string` | yes |  |5788| `versions` | `array of object` | yes |  |5789| `versions[].id` | `string` | yes |  |5790| `versions[].agentId` | `string` | yes |  |5791| `versions[].name` | `string` | yes |  |5792| `versions[].version` | `string` | yes |  |5793| `versions[].sha256` | `string` | yes |  |5794| `versions[].status` | `string` | yes |  |5795| `errors` | `array of object` | yes |  |5796| `errors[].source` | `string` | yes |  |5797| `errors[].message` | `string` | yes |  |57985799</details>58005801**Errors**58025803| Status | Codes |5804|---|---|5805| 400 | [`bad_request`](#err-bad_request) |5806| 401 | [`unauthenticated`](#err-unauthenticated) |5807| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |5808| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5809| 500 | [`internal`](#err-internal) |58105811<a id="op-createStrategy"></a>58125813#### POST `/api/v1/trading/strategies`58145815**Register a library strategy version on an agent.** Operation id `createStrategy`.58165817- **Permission:** `strategies:manage`5818- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice5819- **Side effects:** yes — see the description58205821Pins the version by the SHA-256 of its file and queues its backtest. Registers nothing new in the library and approves nothing. `agentId` is required.58225823**Request body** (JSON; unknown fields are refused)58245825| Field | Type | Required | Description |5826|---|---|---|---|5827| `kind` | `"spot" \| "perp"` | yes | must be the kind of the agent (409 `wrong_kind` otherwise) |5828| `path` | `string` | yes | library path of the strategy, from GET /strategies (`library[].path`) — 1–200 characters |5829| `agentId` | `string` | — | the agent the version is registered on; required in practice (400 without it) — a UUID |58305831**Example request**58325833```bash5834curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies" \5835  -H "Authorization: Bearer $SP_WALLET_API_KEY" \5836  -H "Idempotency-Key: $(uuidgen)" \5837  -H "Content-Type: application/json" \5838  -d '{"kind":"perp","path":"strategies/momentum_xs_perp/2","agentId":"fa9c1fd9-a005-4825-bd67-ea180a2eb83d"}'5839```58405841```ts5842const { strategy } = await client.createStrategy({ kind: 'perp', path: 'strategies/momentum_xs_perp/2', agentId: 'fa9c1fd9-a005-4825-bd67-ea180a2eb83d' });5843```58445845```python5846strategy = client.create_strategy(kind="perp", path="strategies/momentum_xs_perp/2", agent_id="fa9c1fd9-a005-4825-bd67-ea180a2eb83d").strategy5847```58485849**Example response** — 200, recorded from a real server58505851```json5852{5853  "strategy": {5854    "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",5855    "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",5856    "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",5857    "status": "backtesting"5858  },5859  "note": "registered and queued for its backtest; approval for LIVE stays the owner's"5860}5861```58625863<details><summary><b>Response fields</b></summary>58645865| Field | Type | Required | Description |5866|---|---|---|---|5867| `strategy` | `object` | yes |  |5868| `strategy.id` | `string` | yes |  |5869| `strategy.agentId` | `string` | yes |  |5870| `strategy.sha256` | `string` | yes |  |5871| `strategy.status` | `string` | yes |  |58725873</details>58745875**Errors**58765877| Status | Codes |5878|---|---|5879| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |5880| 401 | [`unauthenticated`](#err-unauthenticated) |5881| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |5882| 404 | [`not_found`](#err-not_found) |5883| 409 | [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress), [`wrong_kind`](#err-wrong_kind) |5884| 422 | [`bad_strategy`](#err-bad_strategy) |5885| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5886| 500 | [`internal`](#err-internal) |58875888<a id="op-backtestStrategy"></a>58895890#### POST `/api/v1/trading/strategies/{id}/backtest`58915892**Run the backtest of a strategy version (asynchronous job).** Operation id `backtestStrategy`.58935894- **Permission:** `strategies:manage`5895- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice5896- **Side effects:** yes — see the description58975898Answers a job id; read it with GET /jobs/{id}. The result is a BACKTEST report on the version — never a performance figure.58995900**Parameters**59015902| Name | In | Type | Required | Description |5903|---|---|---|---|---|5904| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |59055906**Request body** (JSON; unknown fields are refused)59075908| Field | Type | Required | Description |5909|---|---|---|---|5910| `symbols` | `array of string` | — | default: the agent's universe — 1–12 items |5911| `interval` | `"1h" \| "1d"` | — | bar interval; default: the agent's |59125913**Example request**59145915```bash5916curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/backtest" \5917  -H "Authorization: Bearer $SP_WALLET_API_KEY" \5918  -H "Idempotency-Key: $(uuidgen)" \5919  -H "Content-Type: application/json" \5920  -d '{}'5921```59225923```ts5924const { job } = await client.backtestStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e');5925const done = await client.waitForJob(job.id);5926```59275928```python5929job = client.backtest_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e").job5930done = client.wait_for_job(job.id)5931```59325933**Example response** — 200, recorded from a real server59345935```json5936{5937  "job": {5938    "id": "43823b3b-af8c-4c78-8527-638ea5fde77b",5939    "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",5940    "kind": "backtest",5941    "status": "queued",5942    "deadLettered": false,5943    "attempts": 0,5944    "maxAttempts": 2,5945    "runAt": 1794953786889,5946    "error": null,5947    "result": null,5948    "createdAt": 1794953786889,5949    "updatedAt": 1794953786889,5950    "finishedAt": null5951  },5952  "label": "backtest"5953}5954```59555956<details><summary><b>Response fields</b></summary>59575958| Field | Type | Required | Description |5959|---|---|---|---|5960| `job` | `object` | yes |  |5961| `job.id` | `string` | yes |  |5962| `job.kind` | `string` | yes |  |5963| `job.status` | `"queued" \| "running" \| "done" \| "failed" \| "cancelled"` | yes |  |5964| `job.attempts` | `integer -9007199254740991…9007199254740991` | yes |  |5965| `label` | `string` | — |  |59665967</details>59685969**Errors**59705971| Status | Codes |5972|---|---|5973| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |5974| 401 | [`unauthenticated`](#err-unauthenticated) |5975| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |5976| 404 | [`not_found`](#err-not_found) |5977| 409 | [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |5978| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |5979| 500 | [`internal`](#err-internal) |59805981<a id="op-startStrategy"></a>59825983#### POST `/api/v1/trading/strategies/{id}/start`59845985**Start the agent a strategy version is pinned to.** Operation id `startStrategy`.59865987- **Permission:** `strategies:manage`5988- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice5989- **Side effects:** yes — see the description59905991research and paper sign nothing. Starting a perp agent on `paper` creates its PAPER trading mandate (nothing is signed; its orders go through the unified order service, the risk engine and that mandate): the key needs `agents:manage` and may not be restricted away from the agent's venue or instruments (403 `insufficient_scope` / `restricted`), and a halted paper account answers 409 `halted`. `live` is accepted ONLY when a mandate approved by the owner with the passkey is in force for this agent — for a perp agent a TRADING mandate, which only the owner activates: a key answers 409 `mandate_required` (a key, an agent or this API can never approve a mandate). Families that cannot go live answer 409 `live_unavailable` with the reason.59925993**Parameters**59945995| Name | In | Type | Required | Description |5996|---|---|---|---|---|5997| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |59985999**Request body** (JSON; unknown fields are refused)60006001| Field | Type | Required | Description |6002|---|---|---|---|6003| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |6004| `agentId` | `string` | — | strategy operations only: the agent, when the version id alone does not name it — a UUID |60056006**Example request**60076008```bash6009curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/start" \6010  -H "Authorization: Bearer $SP_WALLET_API_KEY" \6011  -H "Idempotency-Key: $(uuidgen)" \6012  -H "Content-Type: application/json" \6013  -d '{"mode":"paper"}'6014```60156016```ts6017await client.startStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { mode: 'paper' });6018```60196020```python6021client.start_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e", mode="paper")6022```60236024**Example response** — 200, recorded from a real server. Only the most recent version of an agent starts, and only once its backtest is done (409 `other_version`, `no_report` otherwise).60256026```json6027{6028  "agent": {6029    "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",6030    "name": "Docs momentum",6031    "mission": "",6032    "kind": "perp",6033    "family": "momentum",6034    "template": "momentum",6035    "engine": "bar",6036    "state": "active",6037    "phase": "PAPER_TRADING",6038    "mode": "paper",6039    "venue": "hyperliquid",6040    "network": "hyperliquid",6041    "universe": [6042      "BTC",6043      "ETH"6044    ],6045    "interval": "1h",6046    "capitalUsd": "1000",6047    "riskLimits": {6048      "maxLeverage": 2,6049      "minTradePct": 2,6050      "slippageBps": 30,6051      "maxPositionX": 1,6052      "maxDailyLossPct": 3,6053      "maxTotalLossPct": 10,6054      "maxGrossExposureX": 1.56055    },6056    "configVersion": 3,6057    "strategy": {6058      "name": "momentum_xs_perp",6059      "version": "2",6060      "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",6061      "path": "strategies/momentum_xs_perp/2",6062      "status": "approved",6063      "kind": "python"6064    },6065    "mandate": null,6066    "pausedFrom": null,6067    "live": {6068      "capable": true,6069      "code": null,6070      "reason": null6071    },6072    "stopReason": null,6073    "lastBar": null,6074    "createdAt": 1794953786472,6075    "updatedAt": 17949550431806076  },6077  "strategyVersionId": "450bc266-e1a9-4807-9113-7da6773ddb4e"6078}6079```60806081<details><summary><b>Response fields</b></summary>60826083| Field | Type | Required | Description |6084|---|---|---|---|6085| `agent` | `object` | yes |  |6086| `agent.id` | `string` | yes |  |6087| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |6088| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |60896090</details>60916092**Errors**60936094| Status | Codes |6095|---|---|6096| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |6097| 401 | [`unauthenticated`](#err-unauthenticated) |6098| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`owner_required`](#err-owner_required), [`restricted`](#err-restricted) |6099| 404 | [`not_found`](#err-not_found) |6100| 409 | [`bad_report`](#err-bad_report), [`bad_request`](#err-bad_request), [`bad_state`](#err-bad_state), [`halted`](#err-halted), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress), [`live_unavailable`](#err-live_unavailable), [`mandate_required`](#err-mandate_required), [`no_report`](#err-no_report), [`no_strategy`](#err-no_strategy), [`other_version`](#err-other_version) |6101| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6102| 500 | [`internal`](#err-internal) |61036104<a id="op-stopStrategy"></a>61056106#### POST `/api/v1/trading/strategies/{id}/stop`61076108**Stop the agent a strategy version is pinned to.** Operation id `stopStrategy`.61096110- **Permission:** `strategies:manage`6111- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice6112- **Side effects:** yes — see the description61136114Always allowed. The safe wind-down: a live perp agent's mandate is revoked and its positions are closed with reduce-only orders; a live spot agent's mandate is revoked at the signer; simulated quotes are withdrawn.61156116**Parameters**61176118| Name | In | Type | Required | Description |6119|---|---|---|---|---|6120| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |61216122**Request body** (JSON; unknown fields are refused)61236124| Field | Type | Required | Description |6125|---|---|---|---|6126| `reason` | `string` | — | why, for the agent's journal — default "" · 0–200 characters |61276128**Example request**61296130```bash6131curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/stop" \6132  -H "Authorization: Bearer $SP_WALLET_API_KEY" \6133  -H "Idempotency-Key: $(uuidgen)" \6134  -H "Content-Type: application/json" \6135  -d '{"reason":"documentation example"}'6136```61376138```ts6139await client.stopStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { reason: 'documentation example' });6140```61416142```python6143client.stop_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e", reason="documentation example")6144```61456146**Example response** — 200, recorded from a real server61476148```json6149{6150  "agent": {6151    "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",6152    "name": "Docs momentum",6153    "mission": "",6154    "kind": "perp",6155    "family": "momentum",6156    "template": "momentum",6157    "engine": "bar",6158    "state": "stopped",6159    "phase": "STOPPED",6160    "mode": "paper",6161    "venue": "hyperliquid",6162    "network": "hyperliquid",6163    "universe": [6164      "BTC",6165      "ETH"6166    ],6167    "interval": "1h",6168    "capitalUsd": "1000",6169    "riskLimits": {6170      "maxLeverage": 2,6171      "minTradePct": 2,6172      "slippageBps": 30,6173      "maxPositionX": 1,6174      "maxDailyLossPct": 3,6175      "maxTotalLossPct": 10,6176      "maxGrossExposureX": 1.56177    },6178    "configVersion": 2,6179    "strategy": null,6180    "mandate": null,6181    "pausedFrom": null,6182    "live": {6183      "capable": true,6184      "code": null,6185      "reason": null6186    },6187    "stopReason": "stopped by the key:spk_0123456789ab",6188    "lastBar": null,6189    "createdAt": 1794953786472,6190    "updatedAt": 17949537868946191  },6192  "windDown": null6193}6194```61956196<details><summary><b>Response fields</b></summary>61976198| Field | Type | Required | Description |6199|---|---|---|---|6200| `agent` | `object` | yes |  |6201| `agent.id` | `string` | yes |  |6202| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |6203| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |62046205</details>62066207**Errors**62086209| Status | Codes |6210|---|---|6211| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |6212| 401 | [`unauthenticated`](#err-unauthenticated) |6213| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |6214| 404 | [`not_found`](#err-not_found) |6215| 409 | [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |6216| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6217| 500 | [`internal`](#err-internal) |62186219<a id="tag-agents"></a>62206221### Agents62226223Trading agents: templates, lifecycle (create, start, pause, stop), and their history read ONE mode per call (research, paper or live). An agent goes live only under its own owner-approved mandate.62246225<a id="op-listAgents"></a>62266227#### GET `/api/v1/trading/agents`62286229**Trading agents.** Operation id `listAgents`.62306231- **Permission:** `agents:read`6232- **Idempotency-Key:** not used6233- **Side effects:** none (a read)62346235Every agent of the wallet. Decide on `lifecycle` (active, paused, stopped) and `tradingMode` (research, paper, live); `state` and `mode` are the historical raw words, kept for compatibility. A key restricted to venues sees only the agents that trade there.62366237**Example request**62386239```bash6240curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents" \6241  -H "Authorization: Bearer $SP_WALLET_API_KEY"6242```62436244```ts6245const { agents } = await client.listAgents();6246```62476248```python6249agents = client.list_agents().agents6250```62516252**Example response** — 200, recorded from a real server62536254```json6255{6256  "agents": [6257    {6258      "id": "b9180e9d-3977-403c-a072-9af105bfd59b",6259      "name": "Docs funding",6260      "mission": "",6261      "kind": "stream",6262      "family": "funding_arb",6263      "template": "funding-arb",6264      "engine": "stream",6265      "state": "CREATED",6266      "phase": "CREATED",6267      "mode": "RESEARCH",6268      "venue": "hyperliquid+dydx",6269      "network": "hyperliquid+dydx",6270      "universe": [6271        "BTC"6272      ],6273      "interval": "stream",6274      "capitalUsd": "1000",6275      "riskLimits": {6276        "maxGrossUsd": 1000,6277        "maxDataAgeMs": 5000,6278        "maxPositionUsd": 500,6279        "maxDailyLossPct": 2,6280        "maxTotalLossPct": 56281      },6282      "configVersion": 1,6283      "strategy": {6284        "name": "funding_differential",6285        "version": "1",6286        "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",6287        "path": null,6288        "status": "built_in",6289        "kind": "rule"6290      },6291      "mandate": null,6292      "pausedFrom": null,6293      "live": {6294        "capable": false,6295        "code": "family_not_live",6296        "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"6297      },6298      "stopReason": null,6299      "lastBar": null,6300      "createdAt": 1794953757211,6301      "updatedAt": 1794953757211,6302      "lifecycle": "stopped",6303      "tradingMode": "research",6304      "strategyVersionId": null,6305      "mandateId": null,6306      "accountId": null6307    }6308  ]6309}6310```63116312<details><summary><b>Response fields</b></summary>63136314| Field | Type | Required | Description |6315|---|---|---|---|6316| `agents` | `array of object` | yes |  |6317| `agents[].id` | `string` | yes |  |6318| `agents[].kind` | `"spot" \| "perp" \| "stream" \| "supervisor"` | yes |  |6319| `agents[].name` | `string` | yes |  |6320| `agents[].family` | `string` | yes |  |6321| `agents[].state` | `string` | yes | historical raw state |6322| `agents[].mode` | `string` | yes | historical raw mode |6323| `agents[].lifecycle` | `"active" \| "paused" \| "stopped"` | yes |  |6324| `agents[].tradingMode` | `"research" \| "paper" \| "live" \| null` | yes |  |6325| `agents[].venue` | `string` | yes |  |6326| `agents[].universe` | `array of string` | yes |  |6327| `agents[].interval` | `string` | yes |  |6328| `agents[].configVersion` | `integer -9007199254740991…9007199254740991` | yes |  |63296330</details>63316332**Errors**63336334| Status | Codes |6335|---|---|6336| 401 | [`unauthenticated`](#err-unauthenticated) |6337| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |6338| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6339| 500 | [`internal`](#err-internal) |63406341<a id="op-createAgent"></a>63426343#### POST `/api/v1/trading/agents`63446345**Create an agent (from a template, or a perp agent).** Operation id `createAgent`.63466347- **Permission:** `agents:manage`6348- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice6349- **Side effects:** yes — see the description63506351Nothing is signed and no vault is derived. A spot agent is created in the owner's app (403 `owner_required`). A template whose strategy is not installed answers 409 `strategy_not_installed`.63526353**Request body** (JSON; unknown fields are refused)63546355| Field | Type | Required | Description |6356|---|---|---|---|6357| `kind` | `"spot" \| "perp"` | — | without a template: perp (a spot agent needs a vault from the signer: owner only) |6358| `template` | `string` | — | one of GET /agents/templates — 0–40 characters |6359| `name` | `string` | yes | shown in the app and in the lists — 2–40 characters |6360| `mission` | `string` | — | free text for people; it changes nothing the agent does — default "" · 0–400 characters |6361| `universe` | `array of string` | — | asset symbols the agent trades, e.g. ["BTC"]; a fixed-universe strategy needs its exact universe (422 `universe_mismatch`); default: the template's — 1–12 items |6362| `venues` | `array of "hyperliquid" \| "edgex" \| "dydx" \| "gmx"` | — | venues the agent reads; default: the template's — 1–2 items |6363| `strategyPath` | `string` | — | bar templates: which of the template's installed strategies to bind, from GET /agents/templates — 0–60 characters |6364| `interval` | `"1h" \| "4h" \| "1d"` | — | bar agents: bar length; default 1h |6365| `capitalUsdc` | `string` | — | simulated capital of the agent, a decimal string; default 1000 — pattern ^\d{1,7}(\.\d{1,6})?$ |6366| `risk` | `map of number \| string \| boolean` | — | overrides of the agent's own risk limits, by name (the limits in force are in GET /agents/{id}: `riskLimits`) |6367| `config` | `map of any` | — | overrides of the template's parameters, by name |6368| `mode` | `"research" \| "paper"` | — | 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. — default "research" |63696370**Example request**63716372```bash6373curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents" \6374  -H "Authorization: Bearer $SP_WALLET_API_KEY" \6375  -H "Idempotency-Key: $(uuidgen)" \6376  -H "Content-Type: application/json" \6377  -d '{"template":"funding-arb","name":"Docs funding","mode":"research"}'6378```63796380```ts6381const { agent } = await client.createAgent({ template: 'funding-arb', name: 'Docs funding', mode: 'research' });6382```63836384```python6385agent = client.create_agent(template="funding-arb", name="Docs funding", mode="research").agent6386```63876388**Example response** — 200, recorded from a real server63896390```json6391{6392  "agent": {6393    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",6394    "name": "Docs funding",6395    "mission": "",6396    "kind": "stream",6397    "family": "funding_arb",6398    "template": "funding-arb",6399    "engine": "stream",6400    "state": "stopped",6401    "phase": "CREATED",6402    "mode": "research",6403    "venue": "hyperliquid+dydx",6404    "network": "hyperliquid+dydx",6405    "universe": [6406      "BTC"6407    ],6408    "interval": "stream",6409    "capitalUsd": "1000",6410    "riskLimits": {6411      "maxGrossUsd": 1000,6412      "maxDataAgeMs": 5000,6413      "maxPositionUsd": 500,6414      "maxDailyLossPct": 2,6415      "maxTotalLossPct": 56416    },6417    "configVersion": 1,6418    "strategy": {6419      "name": "funding_differential",6420      "version": "1",6421      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",6422      "path": null,6423      "status": "built_in",6424      "kind": "rule"6425    },6426    "mandate": null,6427    "pausedFrom": null,6428    "live": {6429      "capable": false,6430      "code": "family_not_live",6431      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"6432    },6433    "stopReason": null,6434    "lastBar": null,6435    "createdAt": 1794953757211,6436    "updatedAt": 17949537572116437  },6438  "strategy": null,6439  "warnings": [6440    {6441      "code": "no_live",6442      "message": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"6443    }6444  ]6445}6446```64476448<details><summary><b>Response fields</b></summary>64496450| Field | Type | Required | Description |6451|---|---|---|---|6452| `agent` | `object` | yes |  |6453| `agent.id` | `string` | yes |  |6454| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |6455| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |64566457</details>64586459**Errors**64606461| Status | Codes |6462|---|---|6463| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |6464| 401 | [`unauthenticated`](#err-unauthenticated) |6465| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`owner_required`](#err-owner_required) |6466| 409 | [`bad_report`](#err-bad_report), [`bad_state`](#err-bad_state), [`exists`](#err-exists), [`halted`](#err-halted), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress), [`live_unavailable`](#err-live_unavailable), [`mandate_required`](#err-mandate_required), [`no_report`](#err-no_report), [`no_strategy`](#err-no_strategy), [`strategy_not_installed`](#err-strategy_not_installed), [`wrong_kind`](#err-wrong_kind) |6467| 422 | [`bad_request`](#err-bad_request), [`universe_mismatch`](#err-universe_mismatch) |6468| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6469| 500 | [`internal`](#err-internal) |64706471<a id="op-listAgentTemplates"></a>64726473#### GET `/api/v1/trading/agents/templates`64746475**The seven built-in agents: family, engine, modes, installed strategies.** Operation id `listAgentTemplates`.64766477- **Permission:** `agents:read`6478- **Idempotency-Key:** not used6479- **Side effects:** none (a read)64806481A bar template is bound BY NAME to laboratory strategies; `strategyInstalled: false` means none of them is installed (no placeholder is ever substituted). `liveReason` says why a family cannot go live.64826483**Example request**64846485```bash6486curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/templates" \6487  -H "Authorization: Bearer $SP_WALLET_API_KEY"6488```64896490```ts6491const { templates } = await client.listAgentTemplates();6492```64936494```python6495templates = client.list_agent_templates().templates6496```64976498**Example response** — 200, recorded from a real server. Cut to one of the seven templates.64996500```json6501{6502  "templates": [6503    {6504      "id": "stat-arb",6505      "family": "stat_arb",6506      "engine": "bar",6507      "kind": "perp",6508      "name": {6509        "fr": "Arbitrage statistique",6510        "en": "Statistical Arbitrage"6511      },6512      "summary": {6513        "fr": "Paire ou panier co-intégré de contrats perpétuels Hyperliquid : achète l'écart quand il s'éloigne de sa moyenne, le revend quand il y revient.",6514        "en": "A co-integrated pair or basket of Hyperliquid perpetuals: buys the spread when it is far from its mean, sells it back when it returns."6515      },6516      "modes": [6517        "research"6518      ],6519      "liveReason": null,6520      "strategyNames": [6521        "statarb_basket_perp"6522      ],6523      "installed": [6524        {6525          "path": "statarb_basket_perp/1",6526          "name": "statarb_basket_perp",6527          "version": "1",6528          "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",6529          "universe": [6530            "BTC"6531          ],6532          "interval": "1h",6533          "spotLegs": false,6534          "generic": false,6535          "minSymbols": 6,6536          "maxSymbols": 6,6537          "defaultUniverse": null,6538          "liveCapable": false,6539          "liveReason": "its universe includes LINK, AAVE, HYPE, outside the signer's pinned instruments (BTC, ETH, SOL); an agent runs a fixed-universe strategy only on its exact universe, so it stays on paper",6540          "liveCondition": null6541        }6542      ],6543      "strategyInstalled": true,6544      "rule": null,6545      "labBacktest": {6546        "wanted": [],6547        "installed": [],6548        "agentRunnable": false6549      },6550      "labStudies": [],6551      "labVerdicts": [6552        {6553          "available": true,6554          "kind": "strategy",6555          "backtest": true,6556          "name": "statarb_basket_perp",6557          "version": "1",6558          "strategy": "statarb_basket_perp/1",6559          "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",6560          "symbols": [6561            "BTC"6562          ],6563          "where": "strategies",6564          "installedHashMatches": true,6565          "scope": "agent",6566          "liveCapable": false,6567          "deflatedSharpe": 0.000002855202061682034,6568          "deflatedSharpeThreshold": 0.95,6569          "significant": false,6570          "trialsTested": 31,6571          "ownTrials": 5,6572          "testSharpeCi": [6573            -18.4767707257599386574          ],6575          "splits": {6576            "train": {6577              "netReturn": -0.10170708254821714,6578              "netSharpe": -7.182497476407538,6579              "grossSharpe": -2.942848775728168,6580              "maxDrawdown": 0.10170708254821714,6581              "trades": 384,6582              "stop": {6583                "code": "total_loss",6584                "reason": "total loss limit reached (10 % of the capital)",6585                "ts": "2026-06-29T18:00:00+00:00"6586              },6587              "grossToNet": {6588                "pricePnl": -42.47637,6589                "funding": 0.286722681079791,6590                "fees": 17.985133225783834,6591                "liquidationPenalties": 0,6592                "slippage": 4.3453824145459,6593                "latency": 37.186919588967264,6594                "netPnl": -101.707082548217166595              }6596            },6597            "validation": {6598              "netReturn": -0.10328278271158842,6599              "netSharpe": -10.506726964730408,6600              "grossSharpe": 0.2656999138474378,6601              "maxDrawdown": 0.10328278271158842,6602              "trades": 870,6603              "stop": {6604                "code": "total_loss",6605                "reason": "total loss limit reached (10 % of the capital)",6606                "ts": "2026-09-25T08:00:00+00:00"6607              },6608              "grossToNet": {6609                "pricePnl": 2.05459,6610                "funding": 0.294203640074876,6611                "fees": 34.364870451549976,6612                "liquidationPenalties": 0,6613                "slippage": 8.0428194421408,6614                "latency": 63.22388645797256,6615                "netPnl": -103.282782711588426616              }6617            },6618            "test": {6619              "netReturn": -0.10165090743737748,6620              "netSharpe": -11.067904972523419,6621              "grossSharpe": 0.7338473369539557,6622              "maxDrawdown": 0.1024842740501597,6623              "trades": 851,6624              "stop": {6625                "code": "total_loss",6626                "reason": "total loss limit reached (10 % of the capital)",6627                "ts": "2026-11-04T16:00:00+00:00"6628              },6629              "grossToNet": {6630                "pricePnl": 6.1472,6631                "funding": -0.381330817681965,6632                "fees": 37.63228249889594,6633                "liquidationPenalties": 0,6634                "slippage": 8.9354844276773,6635                "latency": 60.84900969312219,6636                "netPnl": -101.650907437377446637              }6638            }6639          },6640          "stoppedSplits": [6641            "train"6642          ],6643          "checks": {6644            "lookahead": "pass",6645            "data_quality": "pass",6646            "ledger": "pass",6647            "funding_alignment": "pass"6648          },6649          "window": {6650            "start": "2026-05-19T00:00:00+00:00",6651            "end": "2026-11-14T23:00:00+00:00",6652            "interval": "1h",6653            "bars": 43206654          },6655          "splitDates": {6656            "train": [6657              "2026-05-19T00:00:00+00:00"6658            ],6659            "validation": [6660              "2026-09-04T00:00:00+00:00"6661            ],6662            "test": [6663              "2026-10-10T00:00:00+00:00"6664            ]6665          },6666          "dataSha256": "060687f0fc9f948d28ce5c5fd39c32798b3c924c35e0a5bb879dceec408c00f5",6667          "codeSha256": "6ea1cf4df5ceb8b33c0a763ca1c8724c76de60b861714597b73295ec89507356",6668          "engineParityApplied": true,6669          "results": {6670            "dir": "research/results/2026-11-15-v11",6671            "file": "statarb_basket_perp-1.json",6672            "fileSha256": "745a629f00d35b8b76d0e0ea681a7dbe22501b74b86351e80fd23ab3ebe71f14",6673            "matchesManifest": true6674          }6675        }6676      ],6677      "defaults": {6678        "universe": [6679          "BTC"6680        ],6681        "venues": [6682          "hyperliquid"6683        ],6684        "interval": "1h",6685        "capitalUsdc": "1000",6686        "config": {},6687        "risk": {6688          "maxLeverage": 2,6689          "maxGrossExposureX": 1.5,6690          "maxPositionX": 1,6691          "maxDailyLossPct": 3,6692          "maxTotalLossPct": 10,6693          "slippageBps": 30,6694          "minTradePct": 26695        }6696      }6697    }6698  ]6699}6700```67016702<details><summary><b>Response fields</b></summary>67036704| Field | Type | Required | Description |6705|---|---|---|---|6706| `templates` | `array of object` | yes |  |6707| `templates[].id` | `string` | yes |  |6708| `templates[].family` | `string` | yes |  |6709| `templates[].engine` | `string` | yes |  |6710| `templates[].modes` | `array of "research" \| "paper" \| "live"` | yes |  |6711| `templates[].liveReason` | `string \| null` | yes |  |6712| `templates[].strategyInstalled` | `boolean` | yes |  |67136714</details>67156716**Errors**67176718| Status | Codes |6719|---|---|6720| 401 | [`unauthenticated`](#err-unauthenticated) |6721| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |6722| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6723| 500 | [`internal`](#err-internal) |67246725<a id="op-getAgent"></a>67266727#### GET `/api/v1/trading/agents/{id}`67286729**One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state.** Operation id `getAgent`.67306731- **Permission:** `agents:read`6732- **Idempotency-Key:** not used6733- **Side effects:** none (a read)67346735`agent.state` is active, paused or stopped and `agent.mode` research, paper or live. `mandateDraft` is the mandate the owner would have to approve for this agent to go live (null when none can be drafted). An unknown id, or an agent a restricted key may not see, answers 404 `not_found`.67366737**Parameters**67386739| Name | In | Type | Required | Description |6740|---|---|---|---|---|6741| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |67426743**Example request**67446745```bash6746curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b" \6747  -H "Authorization: Bearer $SP_WALLET_API_KEY"6748```67496750```ts6751const { agent } = await client.getAgent('b9180e9d-3977-403c-a072-9af105bfd59b');6752```67536754```python6755agent = client.get_agent("b9180e9d-3977-403c-a072-9af105bfd59b").agent6756```67576758**Example response** — 200, recorded from a real server67596760```json6761{6762  "agent": {6763    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",6764    "name": "Docs funding",6765    "mission": "",6766    "kind": "stream",6767    "family": "funding_arb",6768    "template": "funding-arb",6769    "engine": "stream",6770    "state": "stopped",6771    "phase": "CREATED",6772    "mode": "research",6773    "venue": "hyperliquid+dydx",6774    "network": "hyperliquid+dydx",6775    "universe": [6776      "BTC"6777    ],6778    "interval": "stream",6779    "capitalUsd": "1000",6780    "riskLimits": {6781      "maxGrossUsd": 1000,6782      "maxDataAgeMs": 5000,6783      "maxPositionUsd": 500,6784      "maxDailyLossPct": 2,6785      "maxTotalLossPct": 56786    },6787    "configVersion": 1,6788    "strategy": {6789      "name": "funding_differential",6790      "version": "1",6791      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",6792      "path": null,6793      "status": "built_in",6794      "kind": "rule"6795    },6796    "mandate": null,6797    "pausedFrom": null,6798    "live": {6799      "capable": false,6800      "code": "family_not_live",6801      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"6802    },6803    "stopReason": null,6804    "lastBar": null,6805    "createdAt": 1794953757211,6806    "updatedAt": 1794953757211,6807    "familyModes": {6808      "engine": "stream",6809      "modes": [6810        "research",6811        "paper"6812      ],6813      "liveReason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"6814    },6815    "backtests": {6816      "label": "backtest",6817      "note": "A backtest is a simulation on historical data under stated assumptions. It is not a track record and is never shown as performance.",6818      "versions": [],6819      "recorded": null6820    },6821    "runtime": {6822      "venues": [6823        "hyperliquid",6824        "dydx"6825      ],6826      "rule": "funding_differential",6827      "config": {6828        "notionalUsd": "250",6829        "horizonHours": "24",6830        "minNetCarryBps": "5",6831        "decisionEveryMs": 60000,6832        "exitNetCarryBps": "0"6833      },6834      "counters": null,6835      "hold": null,6836      "lastPass": null,6837      "book": null6838    },6839    "worker": {6840      "lease": null,6841      "tick": null6842    },6843    "jobs": [],6844    "killSwitch": {6845      "engaged": false,6846      "reason": null,6847      "at": null,6848      "by": null,6849      "readOnly": false,6850      "readOnlyReason": null,6851      "release": {6852        "route": "/risk",6853        "passkey": true6854      }6855    }6856  },6857  "mandateDraft": {6858    "draft": "agent:b9180e9d-3977-403c-a072-9af105bfd59b",6859    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",6860    "family": "funding_arb",6861    "approval": {6862      "route": "/risk?mandate=agent:b9180e9d-3977-403c-a072-9af105bfd59b",6863      "note": "the mandate is approved by the owner with the passkey; the signer judges the approval and enforces the mandate on every order"6864    },6865    "available": false,6866    "code": "family_not_live",6867    "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat",6868    "fields": null6869  }6870}6871```68726873<details><summary><b>Response fields</b></summary>68746875| Field | Type | Required | Description |6876|---|---|---|---|6877| `agent` | `object` | yes |  |6878| `agent.id` | `string` | yes |  |6879| `agent.family` | `string` | yes |  |6880| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |6881| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |6882| `mandateDraft` | `object \| null` | yes |  |68836884</details>68856886**Errors**68876888| Status | Codes |6889|---|---|6890| 400 | [`bad_request`](#err-bad_request) |6891| 401 | [`unauthenticated`](#err-unauthenticated) |6892| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |6893| 404 | [`not_found`](#err-not_found) |6894| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |6895| 500 | [`internal`](#err-internal) |68966897<a id="op-listAgentSignals"></a>68986899#### GET `/api/v1/trading/agents/{id}/signals`69006901**Signal history of one agent, ONE mode.** Operation id `listAgentSignals`.69026903- **Permission:** `agents:read`6904- **Idempotency-Key:** not used6905- **Side effects:** none (a read)69066907Each signal carries the mode, the configuration version, the strategy hash, a digest of its inputs, its output and the decision: `acted`, or `skipped` with a reason code.69086909**Parameters**69106911| Name | In | Type | Required | Description |6912|---|---|---|---|---|6913| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |6914| `mode` | query | `"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. |6915| `limit` | query | `integer 1…500` | — | rows returned at most — default 100 |6916| `before` | query | `integer 0…9007199254740991` | — | unix ms: rows strictly before it |69176918**Example request**69196920```bash6921curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/signals?mode=paper&limit=2" \6922  -H "Authorization: Bearer $SP_WALLET_API_KEY"6923```69246925```ts6926const { signals } = await client.listAgentSignals('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });6927```69286929```python6930signals = client.list_agent_signals("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).signals6931```69326933**Example response** — 200, recorded from a real server69346935```json6936{6937  "mode": "paper",6938  "signals": [6939    {6940      "id": "2",6941      "ts": 1794953758433,6942      "mode": "paper",6943      "kind": "stream",6944      "configVersion": 1,6945      "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",6946      "inputsDigest": "ce04a27eb7d4a2a54c55ea9a63340283bc5ffb6cc7ff9aba8f86947ac273a1a4",6947      "status": "done",6948      "decision": "skipped",6949      "reasonCode": "edge_below_threshold",6950      "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",6951      "output": {6952        "a": {6953          "id": "hyperliquid:BTC",6954          "rate": "0.0000088903",6955          "venue": "hyperliquid",6956          "hourlyBps": 0.088903,6957          "takerRate": 0.00045,6958          "intervalSec": 36006959        },6960        "b": {6961          "id": "dydx:BTC-USD",6962          "rate": "0.00000153333333333333",6963          "venue": "dydx",6964          "hourlyBps": 0.015333333333,6965          "takerRate": 0.0005,6966          "intervalSec": 36006967        },6968        "legs": [],6969        "action": "hold",6970        "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",6971        "feesBps": 19,6972        "longVenue": "dydx",6973        "reasonCode": "edge_below_threshold",6974        "shortVenue": "hyperliquid",6975        "netCarryBps": -17.234327999992,6976        "grossCarryBps": 1.7656720000079997,6977        "diffBpsPerHour": 0.073569666666999996978      },6979      "scaled": null,6980      "scale": null,6981      "equity": "1000",6982      "targets": null,6983      "orders": null,6984      "createdAt": 1794953758435,6985      "updatedAt": 17949537584356986    },6987    {6988      "id": "1",6989      "ts": 1794953757448,6990      "mode": "paper",6991      "kind": "stream",6992      "configVersion": 1,6993      "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",6994      "inputsDigest": null,6995      "status": "hold",6996      "decision": "skipped",6997      "reasonCode": "data_gap",6998      "reason": "hyperliquid:BTC: the stream is reconnecting",6999      "output": null,7000      "scaled": null,7001      "scale": null,7002      "equity": null,7003      "targets": null,7004      "orders": null,7005      "createdAt": 1794953757449,7006      "updatedAt": 17949537574497007    }7008  ]7009}7010```70117012<details><summary><b>Response fields</b></summary>70137014| Field | Type | Required | Description |7015|---|---|---|---|7016| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |7017| `signals` | `array of object` | yes |  |7018| `signals[].id` | `string` | yes |  |7019| `signals[].ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |7020| `signals[].mode` | `"research" \| "paper" \| "live"` | yes | 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. |7021| `signals[].configVersion` | `integer -9007199254740991…9007199254740991` | yes |  |7022| `signals[].strategySha256` | `string` | yes |  |7023| `signals[].decision` | `"pending" \| "acted" \| "skipped"` | yes |  |7024| `signals[].reasonCode` | `string \| null` | yes |  |70257026</details>70277028**Errors**70297030| Status | Codes |7031|---|---|7032| 400 | [`bad_request`](#err-bad_request) |7033| 401 | [`unauthenticated`](#err-unauthenticated) |7034| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7035| 404 | [`not_found`](#err-not_found) |7036| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7037| 500 | [`internal`](#err-internal) |70387039<a id="op-listAgentJournal"></a>70407041#### GET `/api/v1/trading/agents/{id}/journal`70427043**Activity journal of one agent, ONE mode.** Operation id `listAgentJournal`.70447045- **Permission:** `agents:read`7046- **Idempotency-Key:** not used7047- **Side effects:** none (a read)70487049Decisions, orders, fills, errors, risk denials, mandate events and state changes, newest first.70507051**Parameters**70527053| Name | In | Type | Required | Description |7054|---|---|---|---|---|7055| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |7056| `mode` | query | `"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. |7057| `limit` | query | `integer 1…500` | — | rows returned at most — default 100 |7058| `before` | query | `integer 0…9007199254740991` | — | unix ms: rows strictly before it |70597060**Example request**70617062```bash7063curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/journal?mode=paper&limit=3" \7064  -H "Authorization: Bearer $SP_WALLET_API_KEY"7065```70667067```ts7068const { entries } = await client.listAgentJournal('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 3 });7069```70707071```python7072entries = client.list_agent_journal("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=3).entries7073```70747075**Example response** — 200, recorded from a real server70767077```json7078{7079  "mode": "paper",7080  "entries": [7081    {7082      "id": "3",7083      "ts": 1794953758433,7084      "mode": "paper",7085      "kind": "state",7086      "severity": "info",7087      "code": "data_ok",7088      "title": "Data is fresh again: decisions resume",7089      "body": "after 1 s (data_gap)",7090      "data": null,7091      "ref": null,7092      "configVersion": 17093    },7094    {7095      "id": "2",7096      "ts": 1794953757448,7097      "mode": "paper",7098      "kind": "hold",7099      "severity": "warning",7100      "code": "data_gap",7101      "title": "Data gap: quoting and decisions paused",7102      "body": "hyperliquid:BTC: the stream is reconnecting",7103      "data": null,7104      "ref": null,7105      "configVersion": 17106    }7107  ]7108}7109```71107111<details><summary><b>Response fields</b></summary>71127113| Field | Type | Required | Description |7114|---|---|---|---|7115| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |7116| `entries` | `array of object` | yes |  |7117| `entries[].id` | `string` | yes |  |7118| `entries[].ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |7119| `entries[].mode` | `"research" \| "paper" \| "live"` | yes | 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. |7120| `entries[].kind` | `string` | yes |  |7121| `entries[].severity` | `string` | yes |  |7122| `entries[].title` | `string` | yes |  |71237124</details>71257126**Errors**71277128| Status | Codes |7129|---|---|7130| 400 | [`bad_request`](#err-bad_request) |7131| 401 | [`unauthenticated`](#err-unauthenticated) |7132| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7133| 404 | [`not_found`](#err-not_found) |7134| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7135| 500 | [`internal`](#err-internal) |71367137<a id="op-listAgentOrders"></a>71387139#### GET `/api/v1/trading/agents/{id}/orders`71407141**Order history of one agent, ONE mode, in the unified order states.** Operation id `listAgentOrders`.71427143- **Permission:** `agents:read`7144- **Idempotency-Key:** not used7145- **Side effects:** none (a read)71467147The agent's orders in one mode, newest first, with `state` in the twelve unified order states. Page with `before` (the `ts` of the last row) and `limit`. Research places no order: its list is empty.71487149**Parameters**71507151| Name | In | Type | Required | Description |7152|---|---|---|---|---|7153| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |7154| `mode` | query | `"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. |7155| `limit` | query | `integer 1…500` | — | rows returned at most — default 100 |7156| `before` | query | `integer 0…9007199254740991` | — | unix ms: rows strictly before it |7157| `open` | query | `"true" \| "false"` | — | true: only the orders that are not final |71587159**Example request**71607161```bash7162curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/orders?mode=paper&limit=2" \7163  -H "Authorization: Bearer $SP_WALLET_API_KEY"7164```71657166```ts7167const { orders } = await client.listAgentOrders('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });7168```71697170```python7171orders = client.list_agent_orders("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).orders7172```71737174**Example response** — 200, recorded from a real server. The recorded agent had placed no order yet.71757176```json7177{7178  "mode": "paper",7179  "orders": []7180}7181```71827183<details><summary><b>Response fields</b></summary>71847185| Field | Type | Required | Description |7186|---|---|---|---|7187| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |7188| `orders` | `array of object` | yes |  |7189| `orders[].id` | `string` | yes |  |7190| `orders[].mode` | `"paper" \| "live"` | yes |  |7191| `orders[].instrument` | `string` | yes |  |7192| `orders[].side` | `string` | yes |  |7193| `orders[].state` | `string` | yes | unified order state (CREATED … FILLED, CANCELLED, REJECTED, FAILED, UNKNOWN) |71947195</details>71967197**Errors**71987199| Status | Codes |7200|---|---|7201| 400 | [`bad_request`](#err-bad_request) |7202| 401 | [`unauthenticated`](#err-unauthenticated) |7203| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7204| 404 | [`not_found`](#err-not_found) |7205| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7206| 500 | [`internal`](#err-internal) |72077208<a id="op-getAgentPerformance"></a>72097210#### GET `/api/v1/trading/agents/{id}/performance`72117212**Computed performance of one agent, ONE mode.** Operation id `getAgentPerformance`.72137214- **Permission:** `agents:read`7215- **Idempotency-Key:** not used7216- **Side effects:** none (a read)72177218Equity curve, returns, volatility, Sharpe, Sortino, max drawdown, win rate, profit factor, turnover, fees, funding, slippage, net PnL — computed from the records of that mode only, with small-sample warnings. Paper and live are never added. Backtests are not here.72197220**Parameters**72217222| Name | In | Type | Required | Description |7223|---|---|---|---|---|7224| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |7225| `mode` | query | `"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. |72267227**Example request**72287229```bash7230curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/performance?mode=paper" \7231  -H "Authorization: Bearer $SP_WALLET_API_KEY"7232```72337234```ts7235const perf = await client.getAgentPerformance('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });7236```72377238```python7239perf = client.get_agent_performance("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper")7240```72417242**Example response** — 200, recorded from a real server. A figure that cannot be computed is `{ value: null, reason }`, never zero.72437244```json7245{7246  "points": 1,7247  "from": 1794953700000,7248  "to": 1794953700000,7249  "periodsPerYear": null,7250  "totalReturn": {7251    "value": null,7252    "reason": "fewer than two equity points"7253  },7254  "volatility": {7255    "value": null,7256    "reason": "fewer than two returns"7257  },7258  "sharpe": {7259    "value": null,7260    "reason": "fewer than two returns"7261  },7262  "sortino": {7263    "value": null,7264    "reason": "fewer than two returns"7265  },7266  "maxDrawdown": {7267    "value": 0,7268    "reason": null7269  },7270  "winRate": {7271    "value": null,7272    "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"7273  },7274  "profitFactor": {7275    "value": null,7276    "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"7277  },7278  "turnover": {7279    "value": 0,7280    "reason": null7281  },7282  "feesUsd": {7283    "value": 0,7284    "reason": null7285  },7286  "fundingUsd": {7287    "value": 0,7288    "reason": null7289  },7290  "slippageUsd": {7291    "value": null,7292    "reason": "simulated fills are at the quote or at the book price read by the decision"7293  },7294  "netPnlUsd": {7295    "value": null,7296    "reason": "fewer than two equity points"7297  },7298  "closedTrades": 0,7299  "orders": 0,7300  "warnings": [7301    {7302      "code": "small_sample",7303      "message": "1 equity point(s): volatility, Sharpe and Sortino on fewer than 30 points say almost nothing"7304    }7305  ],7306  "mode": "paper",7307  "label": "PAPER — simulated orders and fills; no money moved",7308  "equityCurve": [7309    {7310      "ts": 1794953700000,7311      "equity": 10007312    }7313  ]7314}7315```73167317<details><summary><b>Response fields</b></summary>73187319| Field | Type | Required | Description |7320|---|---|---|---|7321| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |7322| `label` | `string` | yes | says which mode the figures are for; a backtest is never in this answer |7323| `points` | `integer -9007199254740991…9007199254740991` | yes |  |7324| `warnings` | `array of object` | yes |  |7325| `warnings[].code` | `string` | yes |  |7326| `warnings[].message` | `string` | yes |  |73277328</details>73297330**Errors**73317332| Status | Codes |7333|---|---|7334| 400 | [`bad_request`](#err-bad_request) |7335| 401 | [`unauthenticated`](#err-unauthenticated) |7336| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7337| 404 | [`not_found`](#err-not_found) |7338| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7339| 500 | [`internal`](#err-internal) |73407341<a id="op-getJob"></a>73427343#### GET `/api/v1/trading/jobs/{id}`73447345**One agent job (backtest, wind-down): status and result.** Operation id `getJob`.73467347- **Permission:** `agents:read`7348- **Idempotency-Key:** not used7349- **Side effects:** none (a read)73507351Poll until `job.status` is `done`, `failed` or `cancelled` (both SDKs: `waitForJob` / `wait_for_job`). A backtest's `result` is labelled as a backtest and carries its own warnings (too few data points, missing snapshots).73527353**Parameters**73547355| Name | In | Type | Required | Description |7356|---|---|---|---|---|7357| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |73587359**Example request**73607361```bash7362curl -s "$SP_WALLET_BASE_URL/api/v1/trading/jobs/72526d3e-9b2a-4f86-977b-07b6531868a8" \7363  -H "Authorization: Bearer $SP_WALLET_API_KEY"7364```73657366```ts7367const { job } = await client.getJob('72526d3e-9b2a-4f86-977b-07b6531868a8');7368```73697370```python7371job = client.get_job("72526d3e-9b2a-4f86-977b-07b6531868a8").job7372```73737374**Example response** — 200, recorded from a real server73757376```json7377{7378  "job": {7379    "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",7380    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",7381    "kind": "backtest",7382    "status": "done",7383    "deadLettered": false,7384    "attempts": 1,7385    "maxAttempts": 2,7386    "runAt": 1794953761249,7387    "error": null,7388    "result": {7389      "kind": "recorded_replay",7390      "label": "backtest",7391      "missing": 360,7392      "warnings": [7393        "0 recorded instant(s): far too few to conclude anything",7394        "360 of 360 expected snapshots are missing in this window: the replay skipped them"7395      ],7396      "snapshots": 07397    },7398    "createdAt": 1794953761249,7399    "updatedAt": 1794953762380,7400    "finishedAt": 17949537623807401  }7402}7403```74047405<details><summary><b>Response fields</b></summary>74067407| Field | Type | Required | Description |7408|---|---|---|---|7409| `job` | `object` | yes |  |7410| `job.id` | `string` | yes |  |7411| `job.kind` | `string` | yes |  |7412| `job.status` | `"queued" \| "running" \| "done" \| "failed" \| "cancelled"` | yes |  |7413| `job.attempts` | `integer -9007199254740991…9007199254740991` | yes |  |7414| `label` | `string` | — |  |74157416</details>74177418**Errors**74197420| Status | Codes |7421|---|---|7422| 400 | [`bad_request`](#err-bad_request) |7423| 401 | [`unauthenticated`](#err-unauthenticated) |7424| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7425| 404 | [`not_found`](#err-not_found) |7426| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7427| 500 | [`internal`](#err-internal) |74287429<a id="op-startAgent"></a>74307431#### POST `/api/v1/trading/agents/{id}/start`74327433**Start an agent in research, paper or live mode.** Operation id `startAgent`.74347435- **Permission:** `agents:manage`7436- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice7437- **Side effects:** yes — see the description74387439research and paper sign nothing. Starting a perp agent on `paper` creates its PAPER trading mandate (nothing is signed; its orders go through the unified order service, the risk engine and that mandate): the key needs `agents:manage` and may not be restricted away from the agent's venue or instruments (403 `insufficient_scope` / `restricted`), and a halted paper account answers 409 `halted`. `live` is accepted ONLY when a mandate approved by the owner with the passkey is in force for this agent — for a perp agent a TRADING mandate, which only the owner activates: a key answers 409 `mandate_required` (a key, an agent or this API can never approve a mandate). Families that cannot go live answer 409 `live_unavailable` with the reason.74407441**Parameters**74427443| Name | In | Type | Required | Description |7444|---|---|---|---|---|7445| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |74467447**Request body** (JSON; unknown fields are refused)74487449| Field | Type | Required | Description |7450|---|---|---|---|7451| `mode` | `"research" \| "paper" \| "live"` | yes | 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. |7452| `agentId` | `string` | — | strategy operations only: the agent, when the version id alone does not name it — a UUID |74537454**Example request**74557456```bash7457curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/start" \7458  -H "Authorization: Bearer $SP_WALLET_API_KEY" \7459  -H "Idempotency-Key: $(uuidgen)" \7460  -H "Content-Type: application/json" \7461  -d '{"mode":"paper"}'7462```74637464```ts7465await client.startAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });7466```74677468```python7469client.start_agent("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper")7470```74717472**Example response** — 200, recorded from a real server74737474```json7475{7476  "agent": {7477    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",7478    "name": "Docs funding",7479    "mission": "",7480    "kind": "stream",7481    "family": "funding_arb",7482    "template": "funding-arb",7483    "engine": "stream",7484    "state": "active",7485    "phase": "PAPER_TRADING",7486    "mode": "paper",7487    "venue": "hyperliquid+dydx",7488    "network": "hyperliquid+dydx",7489    "universe": [7490      "BTC"7491    ],7492    "interval": "stream",7493    "capitalUsd": "1000",7494    "riskLimits": {7495      "maxGrossUsd": 1000,7496      "maxDataAgeMs": 5000,7497      "maxPositionUsd": 500,7498      "maxDailyLossPct": 2,7499      "maxTotalLossPct": 57500    },7501    "configVersion": 1,7502    "strategy": {7503      "name": "funding_differential",7504      "version": "1",7505      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",7506      "path": null,7507      "status": "built_in",7508      "kind": "rule"7509    },7510    "mandate": null,7511    "pausedFrom": null,7512    "live": {7513      "capable": false,7514      "code": "family_not_live",7515      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"7516    },7517    "stopReason": null,7518    "lastBar": null,7519    "createdAt": 1794953757211,7520    "updatedAt": 17949537572307521  }7522}7523```75247525<details><summary><b>Response fields</b></summary>75267527| Field | Type | Required | Description |7528|---|---|---|---|7529| `agent` | `object` | yes |  |7530| `agent.id` | `string` | yes |  |7531| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |7532| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |75337534</details>75357536**Errors**75377538| Status | Codes |7539|---|---|7540| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |7541| 401 | [`unauthenticated`](#err-unauthenticated) |7542| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`owner_required`](#err-owner_required), [`restricted`](#err-restricted) |7543| 404 | [`not_found`](#err-not_found) |7544| 409 | [`bad_report`](#err-bad_report), [`bad_state`](#err-bad_state), [`halted`](#err-halted), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress), [`live_unavailable`](#err-live_unavailable), [`mandate_required`](#err-mandate_required), [`no_report`](#err-no_report), [`no_strategy`](#err-no_strategy) |7545| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7546| 500 | [`internal`](#err-internal) |75477548<a id="op-pauseAgent"></a>75497550#### POST `/api/v1/trading/agents/{id}/pause`75517552**Pause an agent.** Operation id `pauseAgent`.75537554- **Permission:** `agents:manage`7555- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice7556- **Side effects:** yes — see the description75577558No new exposure. A live perp agent keeps its positions and its mandate; a live spot agent's mandate is revoked at the signer (resuming it needs a new owner approval).75597560**Parameters**75617562| Name | In | Type | Required | Description |7563|---|---|---|---|---|7564| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |75657566**Request body** (JSON; unknown fields are refused)75677568| Field | Type | Required | Description |7569|---|---|---|---|7570| `reason` | `string` | — | why, for the agent's journal — default "" · 0–200 characters |75717572**Example request**75737574```bash7575curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/pause" \7576  -H "Authorization: Bearer $SP_WALLET_API_KEY" \7577  -H "Idempotency-Key: $(uuidgen)" \7578  -H "Content-Type: application/json" \7579  -d '{"reason":"documentation example"}'7580```75817582```ts7583await client.pauseAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });7584```75857586```python7587client.pause_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")7588```75897590**Example response** — 200, recorded from a real server75917592```json7593{7594  "agent": {7595    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",7596    "name": "Docs funding",7597    "mission": "",7598    "kind": "stream",7599    "family": "funding_arb",7600    "template": "funding-arb",7601    "engine": "stream",7602    "state": "paused",7603    "phase": "PAUSED",7604    "mode": "paper",7605    "venue": "hyperliquid+dydx",7606    "network": "hyperliquid+dydx",7607    "universe": [7608      "BTC"7609    ],7610    "interval": "stream",7611    "capitalUsd": "1000",7612    "riskLimits": {7613      "maxGrossUsd": 1000,7614      "maxDataAgeMs": 5000,7615      "maxPositionUsd": 500,7616      "maxDailyLossPct": 2,7617      "maxTotalLossPct": 57618    },7619    "configVersion": 1,7620    "strategy": {7621      "name": "funding_differential",7622      "version": "1",7623      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",7624      "path": null,7625      "status": "built_in",7626      "kind": "rule"7627    },7628    "mandate": null,7629    "pausedFrom": "PAPER",7630    "live": {7631      "capable": false,7632      "code": "family_not_live",7633      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"7634    },7635    "stopReason": null,7636    "lastBar": null,7637    "createdAt": 1794953757211,7638    "updatedAt": 17949537637607639  }7640}7641```76427643<details><summary><b>Response fields</b></summary>76447645| Field | Type | Required | Description |7646|---|---|---|---|7647| `agent` | `object` | yes |  |7648| `agent.id` | `string` | yes |  |7649| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |7650| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |76517652</details>76537654**Errors**76557656| Status | Codes |7657|---|---|7658| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |7659| 401 | [`unauthenticated`](#err-unauthenticated) |7660| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7661| 404 | [`not_found`](#err-not_found) |7662| 409 | [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |7663| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7664| 500 | [`internal`](#err-internal) |76657666<a id="op-stopAgent"></a>76677668#### POST `/api/v1/trading/agents/{id}/stop`76697670**Stop an agent (always allowed).** Operation id `stopAgent`.76717672- **Permission:** `agents:manage`7673- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice7674- **Side effects:** yes — see the description76757676Always allowed. The safe wind-down: a live perp agent's mandate is revoked and its positions are closed with reduce-only orders; a live spot agent's mandate is revoked at the signer; simulated quotes are withdrawn.76777678**Parameters**76797680| Name | In | Type | Required | Description |7681|---|---|---|---|---|7682| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |76837684**Request body** (JSON; unknown fields are refused)76857686| Field | Type | Required | Description |7687|---|---|---|---|7688| `reason` | `string` | — | why, for the agent's journal — default "" · 0–200 characters |76897690**Example request**76917692```bash7693curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/stop" \7694  -H "Authorization: Bearer $SP_WALLET_API_KEY" \7695  -H "Idempotency-Key: $(uuidgen)" \7696  -H "Content-Type: application/json" \7697  -d '{"reason":"documentation example"}'7698```76997700```ts7701await client.stopAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });7702```77037704```python7705client.stop_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")7706```77077708**Example response** — 200, recorded from a real server77097710```json7711{7712  "agent": {7713    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",7714    "name": "Docs funding",7715    "mission": "",7716    "kind": "stream",7717    "family": "funding_arb",7718    "template": "funding-arb",7719    "engine": "stream",7720    "state": "stopped",7721    "phase": "STOPPED",7722    "mode": "paper",7723    "venue": "hyperliquid+dydx",7724    "network": "hyperliquid+dydx",7725    "universe": [7726      "BTC"7727    ],7728    "interval": "stream",7729    "capitalUsd": "1000",7730    "riskLimits": {7731      "maxGrossUsd": 1000,7732      "maxDataAgeMs": 5000,7733      "maxPositionUsd": 500,7734      "maxDailyLossPct": 2,7735      "maxTotalLossPct": 57736    },7737    "configVersion": 1,7738    "strategy": {7739      "name": "funding_differential",7740      "version": "1",7741      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",7742      "path": null,7743      "status": "built_in",7744      "kind": "rule"7745    },7746    "mandate": null,7747    "pausedFrom": "PAPER",7748    "live": {7749      "capable": false,7750      "code": "family_not_live",7751      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"7752    },7753    "stopReason": "stopped by key:spk_0123456789ab: documentation example",7754    "lastBar": null,7755    "createdAt": 1794953757211,7756    "updatedAt": 17949537637677757  },7758  "windDown": null7759}7760```77617762<details><summary><b>Response fields</b></summary>77637764| Field | Type | Required | Description |7765|---|---|---|---|7766| `agent` | `object` | yes |  |7767| `agent.id` | `string` | yes |  |7768| `agent.state` | `"active" \| "paused" \| "stopped"` | yes |  |7769| `agent.mode` | `"research" \| "paper" \| "live"` | yes | 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. |77707771</details>77727773**Errors**77747775| Status | Codes |7776|---|---|7777| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |7778| 401 | [`unauthenticated`](#err-unauthenticated) |7779| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7780| 404 | [`not_found`](#err-not_found) |7781| 409 | [`bad_state`](#err-bad_state), [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress) |7782| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7783| 500 | [`internal`](#err-internal) |77847785<a id="op-backtestAgent"></a>77867787#### POST `/api/v1/trading/agents/{id}/backtest`77887789**Run a backtest for an agent (asynchronous job).** Operation id `backtestAgent`.77907791- **Permission:** `agents:manage`7792- **Idempotency-Key:** required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice7793- **Side effects:** yes — see the description77947795Bar agents: the laboratory backtest of the strategy version. Stream agents: the rule replayed on the top-of-book snapshots the stream engine recorded. Always a BACKTEST, labelled as such.77967797**Parameters**77987799| Name | In | Type | Required | Description |7800|---|---|---|---|---|7801| `id` | path | `string` | yes | the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons) — 1–200 characters |78027803**Request body** (JSON; unknown fields are refused)78047805| Field | Type | Required | Description |7806|---|---|---|---|7807| `versionId` | `string` | — | bar agents: the strategy version to backtest; default: the agent's current one — a UUID |7808| `hours` | `integer 1…168` | — | stream agents: how many hours of recorded snapshots to replay |78097810**Example request**78117812```bash7813curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/backtest" \7814  -H "Authorization: Bearer $SP_WALLET_API_KEY" \7815  -H "Idempotency-Key: $(uuidgen)" \7816  -H "Content-Type: application/json" \7817  -d '{"hours":1}'7818```78197820```ts7821const { job } = await client.backtestAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { hours: 1 });7822```78237824```python7825job = client.backtest_agent("b9180e9d-3977-403c-a072-9af105bfd59b", hours=1).job7826```78277828**Example response** — 200, recorded from a real server78297830```json7831{7832  "job": {7833    "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",7834    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",7835    "kind": "backtest",7836    "status": "queued",7837    "deadLettered": false,7838    "attempts": 0,7839    "maxAttempts": 2,7840    "runAt": 1794953761249,7841    "error": null,7842    "result": null,7843    "createdAt": 1794953761249,7844    "updatedAt": 1794953761249,7845    "finishedAt": null7846  },7847  "label": "backtest"7848}7849```78507851<details><summary><b>Response fields</b></summary>78527853| Field | Type | Required | Description |7854|---|---|---|---|7855| `job` | `object` | yes |  |7856| `job.id` | `string` | yes |  |7857| `job.kind` | `string` | yes |  |7858| `job.status` | `"queued" \| "running" \| "done" \| "failed" \| "cancelled"` | yes |  |7859| `job.attempts` | `integer -9007199254740991…9007199254740991` | yes |  |7860| `label` | `string` | — |  |78617862</details>78637864**Errors**78657866| Status | Codes |7867|---|---|7868| 400 | [`bad_request`](#err-bad_request), [`idempotency`](#err-idempotency), [`stale_request`](#err-stale_request) |7869| 401 | [`unauthenticated`](#err-unauthenticated) |7870| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials), [`restricted`](#err-restricted) |7871| 404 | [`not_found`](#err-not_found) |7872| 409 | [`idempotency_conflict`](#err-idempotency_conflict), [`idempotency_in_progress`](#err-idempotency_in_progress), [`no_strategy`](#err-no_strategy), [`wrong_kind`](#err-wrong_kind) |7873| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |7874| 500 | [`internal`](#err-internal) |78757876<a id="tag-risk"></a>78777878### Risk78797880The state of the risk engine and of the server locks, and the one control a key has: engaging the global kill switch (never releasing it).78817882<a id="op-getRisk"></a>78837884#### GET `/api/v1/trading/risk`78857886**Risk state: kill switch, signer limits, capability locks, account policies.** Operation id `getRisk`.78877888- **Permission:** `positions:read`7889- **Idempotency-Key:** not used7890- **Side effects:** none (a read)78917892What can stop an order, in one read. `engine.killSwitch` and `engine.readOnly`: the global switches of the risk engine. `killSwitch`: the signer's emergency halt (a different thing). `capabilityLocks`: the server locks, each with `on` and `why` — the lock of live execution through this API (`SPW_TRADING_API_EXECUTION`) is NOT in this list: a preview of a live order shows it as a `lock` refusal. `accounts`: the policy of every derivatives account. `signerPolicy`: the signer's per-transaction and daily limits.78937894**Example request**78957896```bash7897curl -s "$SP_WALLET_BASE_URL/api/v1/trading/risk" \7898  -H "Authorization: Bearer $SP_WALLET_API_KEY"7899```79007901```ts7902const risk = await client.getRisk();7903if (risk.engine.killSwitch.on) console.log('no new risk until the owner releases it');7904```79057906```python7907risk = client.get_risk()7908if risk.engine.kill_switch.on:7909    print("no new risk until the owner releases it")7910```79117912**Example response** — 200, recorded from a real server. Cut to one lock and one account; the per-asset maps of the signer policy are cut to four entries.79137914```json7915{7916  "killSwitch": {7917    "signerReachable": true,7918    "signerHalted": false,7919    "note": "the signer halt stops signing (reduce-only exits and cancels are still signed since V11) and is lifted on the signer machine only. The global kill switch of the risk engine (`engin…"7920  },7921  "signerPolicy": {7922    "perTx": {7923      "ethereum:ETH": "25000000000000000",7924      "ethereum:USDC": "50000000",7925      "ethereum:USDT": "50000000",7926      "ethereum:PYUSD": "50000000"7927    },7928    "daily": {7929      "ethereum:ETH": "50000000000000000",7930      "ethereum:USDC": "100000000",7931      "ethereum:USDT": "100000000",7932      "ethereum:PYUSD": "100000000"7933    },7934    "maxFee": {7935      "ethereum": "5000000000000000",7936      "base": "300000000000000",7937      "arbitrum": "300000000000000",7938      "optimism": "300000000000000"7939    },7940    "spentToday": {}7941  },7942  "capabilityLocks": [7943    {7944      "id": "deriv_live_mainnet",7945      "on": false,7946      "why": "SPW_DERIV_LIVE_MAINNET is not \"on\": NEW mainnet risk answers mainnet_disabled (orders that open or add, leverage changes, authorizations, collateral moves); cancels and reduce-only…"7947    }7948  ],7949  "accounts": [7950    {7951      "mode": "paper",7952      "venue": "hyperliquid",7953      "network": "mainnet",7954      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",7955      "policy": {7956        "mode": "PAPER",7957        "allowedInstruments": [7958          "hyperliquid:BTC"7959        ],7960        "halt": null,7961        "maxDataAgeMs": 10000,7962        "maxDeviationBps": "200",7963        "maxMarkIndexBps": "100",7964        "maxLeverage": "3",7965        "maxOrderNotional": "10000",7966        "maxGrossExposure": "30000",7967        "maxPositionNotional": "20000",7968        "minFreeCollateral": "1000",7969        "minLiquidationDistanceBps": "1000",7970        "maxDailyLoss": "500",7971        "maxTotalLoss": "2000",7972        "maxOrdersPerMinute": 60,7973        "maxOrdersPerDay": 2007974      },7975      "halted": null,7976      "halt": null7977    }7978  ],7979  "key": {7980    "limits": {7981      "maxOrderNotionalUsd": null,7982      "maxDailyNotionalUsd": null7983    },7984    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",7985    "limitsEnforced": true,7986    "note": "the key's notional limits and its venue / instrument / network restrictions are applied to every order it places, before the mandate and the risk engine"7987  },7988  "errors": [],7989  "ts": 1794953728201,7990  "engine": {7991    "killSwitch": {7992      "on": false,7993      "at": null,7994      "by": null,7995      "reason": null7996    },7997    "readOnly": {7998      "on": false,7999      "at": null,8000      "by": null,8001      "reason": null8002    },8003    "note": "the global kill switch blocks every new risk (cancels and strictly reducing orders pass); read-only mode lets only cancels pass. Releasing either needs the owner's passkey."8004  }8005}8006```80078008<details><summary><b>Response fields</b></summary>80098010| Field | Type | Required | Description |8011|---|---|---|---|8012| `killSwitch` | `object` | yes |  |8013| `killSwitch.signerReachable` | `boolean` | yes |  |8014| `killSwitch.signerHalted` | `boolean \| null` | yes |  |8015| `killSwitch.note` | `string` | yes |  |8016| `signerPolicy` | `object \| null` | yes |  |8017| `capabilityLocks` | `array of object` | yes |  |8018| `capabilityLocks[].id` | `string` | yes |  |8019| `capabilityLocks[].on` | `boolean` | yes |  |8020| `capabilityLocks[].why` | `string` | yes |  |8021| `accounts` | `array of object` | yes |  |8022| `accounts[].mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |8023| `accounts[].venue` | `string` | yes |  |8024| `accounts[].accountId` | `string` | yes |  |8025| `accounts[].policy` | `object \| null` | yes |  |8026| `accounts[].halted` | `boolean \| null` | yes |  |8027| `errors` | `array of object` | yes |  |8028| `errors[].source` | `string` | yes |  |8029| `errors[].message` | `string` | yes |  |8030| `ts` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |8031| `engine` | `object` | yes | the global switches of the risk engine: `killSwitch.on` blocks every new risk; `readOnly.on` lets only cancels pass |8032| `engine.killSwitch` | `Switch` | yes |  |8033| `engine.readOnly` | `Switch` | yes |  |8034| `engine.note` | `string` | yes |  |80358036</details>80378038**Errors**80398040| Status | Codes |8041|---|---|8042| 401 | [`unauthenticated`](#err-unauthenticated) |8043| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |8044| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |8045| 500 | [`internal`](#err-internal) |80468047<a id="op-engageKillSwitch"></a>80488049#### POST `/api/v1/trading/risk/kill-switch`80508051**Engage the global kill switch.** Operation id `engageKillSwitch`.80528053- **Permission:** `positions:manage`8054- **Idempotency-Key:** not used8055- **Side effects:** yes — see the description80568057Blocks every NEW risk for every principal on every venue and in every mode; cancels and strictly reducing orders still pass. Engaging needs no mandate (it only removes risk) and takes no Idempotency-Key: engaging a switch that is on changes nothing. Releasing it is NOT possible with a key: owner session and passkey only.80588059**Request body** (JSON; unknown fields are refused)80608061| Field | Type | Required | Description |8062|---|---|---|---|8063| `reason` | `string` | — | why, for the audit trail and the `risk.kill_switch` webhook — default "" · 0–200 characters |80648065**Example request**80668067```bash8068curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/risk/kill-switch" \8069  -H "Authorization: Bearer $SP_WALLET_API_KEY" \8070  -H "Content-Type: application/json" \8071  -d '{"reason":"documentation example"}'8072```80738074```ts8075await client.engageKillSwitch('bot detected a runaway loop');8076```80778078```python8079client.engage_kill_switch("bot detected a runaway loop")8080```80818082**Example response** — 200, recorded from a real server. A key can engage it and can never release it.80838084```json8085{8086  "killSwitch": {8087    "on": true,8088    "at": 1794953765956,8089    "by": {8090      "kind": "api_key",8091      "id": "spk_0123456789ab"8092    },8093    "reason": "documentation example"8094  },8095  "readOnly": {8096    "on": false,8097    "at": null,8098    "by": null,8099    "reason": null8100  }8101}8102```81038104<details><summary><b>Response fields</b></summary>81058106| Field | Type | Required | Description |8107|---|---|---|---|8108| `killSwitch` | `Switch` | yes |  |8109| `readOnly` | `Switch` | yes |  |81108111</details>81128113**Errors**81148115| Status | Codes |8116|---|---|8117| 400 | [`bad_request`](#err-bad_request) |8118| 401 | [`unauthenticated`](#err-unauthenticated) |8119| 403 | [`insufficient_scope`](#err-insufficient_scope), [`ip_not_allowed`](#err-ip_not_allowed), [`mixed_credentials`](#err-mixed_credentials) |8120| 429 | [`auth_throttled`](#err-auth_throttled), [`rate_limited`](#err-rate_limited) |8121| 500 | [`internal`](#err-internal) |81228123<a id="objects"></a>81248125## Objects81268127Shapes the answers share (`#/components/schemas/<name>` in the OpenAPI document).81288129<a id="schema-Error"></a>81308131### Error81328133| Field | Type | Required | Description |8134|---|---|---|---|8135| `error` | `string` | yes | stable machine code: one of the operation's `x-spw-errors` |8136| `message` | `string` | yes | human-readable sentence (English) |8137| `candidates` | `array of string` | — | `ambiguous_symbol`: the `venue:symbol` ids the bare symbol could mean |8138| `data` | `object` | — | machine-readable detail of a refusal |8139| `data.order` | `Order` | — | the order the refusal is about, when one exists (state REJECTED or FAILED) |8140| `data.reasons` | `array of string` | — | `mandate_denied`: codes of `x-spw-mandate-deny-reasons`; a mandate that cannot be used: the error code in upper case |8141| `data.failed` | `array of string` | — | `risk_denied`, `kill_switch_active`, `read_only_mode`: ids of the failed risk checks |8142| `data.checks` | `array of RiskCheck` | — | the failed risk checks, each with what was observed and its limit |8143| `data.decisionId` | `integer -9007199254740991…9007199254740991` | — |  |8144| `data.questions` | `array of object` | — | `ambiguous_command`: what the command and the owner's defaults leave open |8145| `data.code` | `string` | — | `parse_error`: the grammar's own code |8146| `data.token` | `integer -9007199254740991…9007199254740991` | — | `parse_error`: index of the offending token |81478148<a id="schema-Order"></a>81498150### Order81518152| Field | Type | Required | Description |8153|---|---|---|---|8154| `id` | `string` | yes | the id every order operation takes |8155| `mode` | `"paper" \| "live"` | yes | paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. |8156| `venue` | `string` | yes |  |8157| `network` | `string` | yes |  |8158| `accountId` | `string \| null` | yes |  |8159| `instrument` | `string \| null` | yes |  |8160| `side` | `string \| null` | yes |  |8161| `type` | `string` | yes |  |8162| `status` | `"CREATED" \| "VALIDATED" \| "AWAITING_APPROVAL" \| "APPROVED" \| "SUBMITTING" \| "SUBMITTED" \| "PARTIALLY_FILLED" \| "FILLED" \| "CANCELLED" \| "REJECTED" \| "FAILED" \| "UNKNOWN"` | yes | unified order state. Final: FILLED, CANCELLED, REJECTED, FAILED. UNKNOWN means the outcome at the venue is not known yet: it is not final and it is not a failure |8163| `engineStatus` | `string \| null` | yes | the word of the engine that executes the order (paper engine, Hyperliquid engine, GMX operation, agent swap) for the same moment; null before an engine holds it. Informative: decide on `status` |8164| `final` | `boolean` | yes | true exactly when `status` is FILLED, CANCELLED, REJECTED or FAILED |8165| `size` | `string \| null` | — |  |8166| `price` | `string \| null` | — |  |8167| `triggerPrice` | `string \| null` | — |  |8168| `reduceOnly` | `boolean` | — |  |8169| `tif` | `string` | — |  |8170| `filled` | `string` | — | cumulative filled size, base units |8171| `avgFillPrice` | `string \| null` | — |  |8172| `reasonCode` | `string \| null` | — | closed reason code of the current state (state machine) |8173| `reason` | `string \| null` | — | sentence for people |8174| `rejectCode` | `string \| null` | — | API error code of the refusal, when the order was refused |8175| `clientOrderId` | `string \| null` | — |  |8176| `orderId` | `string` | — |  |8177| `origin` | `string` | — |  |8178| `mandateId` | `string \| null` | — |  |8179| `notionalUsd` | `string \| null` | — |  |8180| `createdAt` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |8181| `updatedAt` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |81828183<a id="schema-CanonicalOrder"></a>81848185### CanonicalOrder81868187the canonical order SPW-ORDER-INTENT-v1: what is hashed, checked by the mandate and the risk engine, and handed to the engine81888189| Field | Type | Required | Description |8190|---|---|---|---|8191| `v` | `1` | yes |  |8192| `venue` | `string` | yes |  |8193| `network` | `string` | yes |  |8194| `instrument` | `string` | yes |  |8195| `marketKind` | `"spot" \| "perp"` | yes |  |8196| `side` | `"buy" \| "sell"` | yes |  |8197| `type` | `"market" \| "limit" \| "stop" \| "take_profit"` | yes |  |8198| `size` | `string \| null` | yes |  |8199| `notional` | `string \| null` | yes |  |8200| `limitPrice` | `string \| null` | yes |  |8201| `triggerPrice` | `string \| null` | yes |  |8202| `reduceOnly` | `boolean` | yes |  |8203| `tif` | `string` | yes |  |8204| `maxSlippageBps` | `integer -9007199254740991…9007199254740991` | yes |  |8205| `maxFeeUsd` | `string` | yes | decimal number as a string (never a float) |8206| `leverage` | `string \| null` | yes |  |8207| `clientOrderId` | `string` | yes |  |8208| `mode` | `"research" \| "paper" \| "live"` | yes |  |8209| `principal` | `object` | yes |  |8210| `principal.kind` | `"owner" \| "agent" \| "api_key"` | yes |  |8211| `principal.id` | `string` | yes |  |8212| `mandateId` | `string \| null` | yes |  |8213| `createdAt` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |8214| `expiresAt` | `integer -9007199254740991…9007199254740991` | yes | milliseconds since the Unix epoch |82158216<a id="schema-RiskCheck"></a>82178218### RiskCheck82198220| Field | Type | Required | Description |8221|---|---|---|---|8222| `id` | `string` | yes | one of `x-spw-risk-checks` |8223| `ok` | `boolean` | yes |  |8224| `observed` | `string \| null` | yes |  |8225| `limit` | `string \| null` | yes |  |8226| `detail` | `string` | yes |  |8227| `exempt` | `boolean` | yes |  |82288229<a id="schema-Switch"></a>82308231### Switch82328233| Field | Type | Required | Description |8234|---|---|---|---|8235| `on` | `boolean` | yes |  |8236| `at` | `integer -9007199254740991…9007199254740991 \| null` | yes |  |8237| `by` | `object \| null` | yes |  |8238| `by.kind` | `string` | yes |  |8239| `by.id` | `string` | yes |  |8240| `reason` | `string \| null` | yes |  |82418242<a id="error-catalogue"></a>82438244## Error catalogue82458246Every code an operation of this API can answer (153), with what it means and what to do. The `message` of a real answer carries the figures of the case.82478248| Code | Status | Meaning | What to do |8249|---|---|---|---|8250| <a id="err-account_has_active_mandate"></a>`account_has_active_mandate` | 409 | This venue account already carries the mandate of another principal: one venue account serves one principal at a time. | Use another account, or the owner revokes the other mandate. |8251| <a id="err-account_required"></a>`account_required` | 409 | The wallet has several accounts on this venue in this mode. | Name one with `accountId` (GET /portfolio lists them). |8252| <a id="err-ambiguous_command"></a>`ambiguous_command` | 409 | The command line and the owner's stored defaults leave something open (venue, network, leverage, margin mode, fee cap, order validity). Nothing was executed. | Read `data.questions` (each has a `field` and its `options`). Say it in the command (`x2`, `ON hyperliquid`) or have the owner set the defaults once. |8253| <a id="err-ambiguous_order"></a>`ambiguous_order` | 409 | The order and the owner's defaults do not settle everything (spot). | Read `data.questions`; name what is missing, or the owner sets the command defaults. |8254| <a id="err-ambiguous_position"></a>`ambiguous_position` | 409 | The wallet holds a long and a short on this GMX market. | Name the position by its key. |8255| <a id="err-ambiguous_symbol"></a>`ambiguous_symbol` | 409 | A bare symbol (`BTC`) exists on several venues. | Name one of `candidates` as `venue:symbol` (e.g. `hyperliquid:BTC`). |8256| <a id="err-auth_throttled"></a>`auth_throttled` | 429 | Ten failed authentications in a minute from this address: every key request from it is refused for the rest of the window, valid keys included. | Stop sending a bad key. Wait 60 seconds (`Retry-After`). |8257| <a id="err-authorization_expired"></a>`authorization_expired` | 422 | The venue authorization of the account has expired. | The owner approves a new one with the passkey. |8258| <a id="err-authorization_unknown"></a>`authorization_unknown` | 503 | The signer gave no usable answer: it may or may not have stored the authorization. | The owner uses "recover" on the venue account. |8259| <a id="err-bad_input"></a>`bad_input` | 422 | The engine's risk context could not be evaluated. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8260| <a id="err-bad_mark"></a>`bad_mark` | 422 | The mark price is not positive. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8261| <a id="err-bad_order"></a>`bad_order` | 422 | The engine cannot express the order (e.g. too many decimals for the asset). | Fix the request; sending it again unchanged gives the same answer. |8262| <a id="err-bad_policy"></a>`bad_policy` | 400, 422 | The risk policy of the account is invalid, or names an instrument that is not in the pinned asset table. | Only the owner can change this, in the app, with the passkey. |8263| <a id="err-bad_report"></a>`bad_report` | 409 | The backtest report disqualifies this version: it cannot run, even on paper. | Register another version. |8264| <a id="err-bad_request"></a>`bad_request` | 400, 409, 422 | The path parameters, the query or the JSON body do not match the operation's schema (an unknown field is refused: bodies are strict), or a value is out of its range. | Fix the request; sending it again unchanged gives the same answer. The schema of each operation is in this reference and in the OpenAPI document. |8265| <a id="err-bad_state"></a>`bad_state` | 409 | The object is not in a state that allows this: an order being handed to its engine right now, a swap already approved, an agent or job already in that state. | Read the object again; for an order, ask again in a moment. |8266| <a id="err-bad_strategy"></a>`bad_strategy` | 422 | The laboratory refused the strategy file. | Read `message`; pick a path from GET /strategies (`library`). |8267| <a id="err-below_min_notional"></a>`below_min_notional` | 422 | The order is worth less than the venue's minimum. | Raise it above `minNotional`. |8268| <a id="err-below_min_size"></a>`below_min_size` | 422 | The size is under one lot, or the `notional` buys less than one lot at the reference price, or the fraction of a position is less than one lot. | Raise the size/notional. `lotSize`, `minOrderSize` and `minNotional` are in GET /markets/{symbol}. |8269| <a id="err-cancel_in_app"></a>`cancel_in_app` | 422 | This order is cancelled in the app (a spot agent's swap, a GMX order). | Do it in the app. |8270| <a id="err-close_in_app"></a>`close_in_app` | 422 | A GMX position is closed by a wallet transaction approved with the passkey. | Do it in the app. |8271| <a id="err-daily_loss_exceeded"></a>`daily_loss_exceeded` | 422 | The account's daily loss limit is reached. | No new risk today; reductions pass. |8272| <a id="err-data_mismatch"></a>`data_mismatch` | 422 | The ticker or book the engine holds is for another instrument. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8273| <a id="err-duplicate_client_id"></a>`duplicate_client_id` | 422 | This client order id was already used on the account. | Use a new `clientOrderId` / Idempotency-Key for a new order. |8274| <a id="err-execution_disabled"></a>`execution_disabled` | 403 | Live execution through the trading API is closed on this server (`SPW_TRADING_API_EXECUTION` is not `on`). Nothing was created. | Paper is not affected; cancels and strictly reducing orders still pass. The server operator opens the lock. |8275| <a id="err-execution_not_wired"></a>`execution_not_wired` | 501 | The operation exists in the contract and is not connected on this server (or, for STOP ALL AGENTS, could stop nothing from here). Never a success: nothing was done. | Do not retry. Use the operation the message points to. |8276| <a id="err-exists"></a>`exists` | 409 | A risk-management (supervisor) agent already exists. | Stop it before creating another. |8277| <a id="err-fee_cap_not_expressible"></a>`fee_cap_not_expressible` | 422 | The quote asset is not one the owner's defaults count as USD, so the fee cap cannot be expressed. | Use a USD quote, or the owner adds it to the defaults (`usdQuotes`). |8278| <a id="err-gmx_disabled"></a>`gmx_disabled` | 403 | GMX live trading is switched off (server lock or owner setting). | Only the owner can change this, in the app, with the passkey. |8279| <a id="err-gmx_leverage_required"></a>`gmx_leverage_required` | 422 | A GMX increase must name its `leverage` (GMX has no leverage setting to fall back on). | Owner orders only: add `leverage`. |8280| <a id="err-gmx_requires_owner_passkey"></a>`gmx_requires_owner_passkey` | 403 | Every GMX order is a wallet transaction the owner approves with the passkey: a key or an agent cannot place, close or cancel one. | Do it in the app. |8281| <a id="err-gross_exposure_exceeded"></a>`gross_exposure_exceeded` | 422 | The resulting gross exposure exceeds the account policy. | Reduce first, or send a smaller order. |8282| <a id="err-halted"></a>`halted` | 409, 422, 423 | 423/422: the signer's emergency halt is active, or the account is halted. 409 (agents): the agent's paper account is halted. | Cancels and reduce-only exits are still signed. The halt is lifted on the signer machine only. |8283| <a id="err-idempotency"></a>`idempotency` | 400 | A mutating call without a valid `Idempotency-Key` header (8 to 100 characters: letters, digits, `.` `_` `:` `-`). | Send the header. One key per logical action; keep it for retries. |8284| <a id="err-idempotency_conflict"></a>`idempotency_conflict` | 409 | This Idempotency-Key (or `clientOrderId`) was already used with a DIFFERENT request, or belongs to another principal. | A new action needs a new key. To retry the first action, send the first request again, byte for byte. |8285| <a id="err-idempotency_in_progress"></a>`idempotency_in_progress` | 409 | The first call with this Idempotency-Key is still running, or just ended without an answer. | Wait a second and send the same call again. |8286| <a id="err-inconsistent_prices"></a>`inconsistent_prices` | 422 | The stop-loss / take-profit are on the wrong side of the entry or of each other. | A long: SL below entry, TP above. A short: the reverse. |8287| <a id="err-instrument_halted"></a>`instrument_halted` | 422 | The venue has halted this instrument. | Nothing to do until the venue reopens it. |8288| <a id="err-instrument_mismatch"></a>`instrument_mismatch` | 422 | The account is on one venue and the instrument on another. | Name the account of the instrument's venue. |8289| <a id="err-instrument_not_allowed"></a>`instrument_not_allowed` | 422 | The instrument is not allowed by the account's authorization or policy. | Trade an allowed instrument, or the owner widens the policy. |8290| <a id="err-instrument_reduce_only"></a>`instrument_reduce_only` | 422 | The venue only accepts orders that reduce a position on this instrument. | Send reduce-only orders. |8291| <a id="err-insufficient_collateral"></a>`insufficient_collateral` | 422 | Not enough free collateral on the account for this order. | Send a smaller order, or the owner adds collateral to the account. |8292| <a id="err-insufficient_scope"></a>`insufficient_scope` | 403 | The key does not hold the permission (scope) this operation needs. For POST /commands: the scope of the operation the command resolves to. | Use a key that holds the scope named in `message`. Adding a scope to a key needs the owner's passkey. |8293| <a id="err-internal"></a>`internal` | 500 | The server failed. A mutating call may or may not have run. | Send the same call again with the SAME Idempotency-Key: it either returns the stored answer or runs once. Do not create a new key for a retry. |8294| <a id="err-invalid_cursor"></a>`invalid_cursor` | 400 | The `cursor` is not one a previous page of this list returned. | Start again without a cursor; send a cursor with the same filters it came with. |8295| <a id="err-invalid_order"></a>`invalid_order` | 400, 422 | The order is not well-formed for its type: a limit without `price`, a stop without `triggerPrice`, `reduceOnly` on spot, a research-mode order, a mandate or principal that is not the caller's. | Fix the request; sending it again unchanged gives the same answer. |8296| <a id="err-ip_not_allowed"></a>`ip_not_allowed` | 403 | The key has an IP allow-list and the request came from another address. | Call from an allowed address, or have the owner change the key's restrictions. |8297| <a id="err-key_limit_exceeded"></a>`key_limit_exceeded` | 403 | The order is above the key's own notional limit (per order or per day), or cannot be valued so the limit cannot be checked. | Send a smaller order; the limits are on the key (Developer → Keys). |8298| <a id="err-kill_switch_active"></a>`kill_switch_active` | 423 | The global kill switch is on: no new risk for anybody, on any venue, in any mode. | Cancels and strictly reducing orders still pass. Only the owner releases it, with the passkey. |8299| <a id="err-leverage_exceeded"></a>`leverage_exceeded` | 422 | The leverage is above the authorized maximum (policy, mandate or venue). | Lower it. |8300| <a id="err-leverage_mismatch"></a>`leverage_mismatch` | 422 | A live order names a leverage that is not the venue's current setting for the instrument. | Send the order without `leverage`, or the owner changes the setting in the app. |8301| <a id="err-liquidation_too_close"></a>`liquidation_too_close` | 422 | The estimated liquidation price after the order is closer to the mark than the policy allows. | Smaller size or lower leverage. |8302| <a id="err-live_not_available"></a>`live_not_available` | 422 | A paper account can only be PAPER or READ_ONLY. | Use a venue account for live. |8303| <a id="err-live_unavailable"></a>`live_unavailable` | 409 | This agent family cannot go live (the message says why). | Run it on paper. |8304| <a id="err-mainnet_disabled"></a>`mainnet_disabled` | 403 | The server lock for new mainnet risk is closed (`SPW_DERIV_LIVE_MAINNET`). | Paper works; cancels and reductions pass. Only the owner can change this, in the app, with the passkey. |8305| <a id="err-mandate_denied"></a>`mandate_denied` | 403 | The order is outside the mandate. `data.reasons` lists EVERY reason (codes of the mandate table, e.g. `ORDER_NOTIONAL_EXCEEDED`, `INSTRUMENT_NOT_ALLOWED`); `data.order` is the order, state REJECTED. | Change the order to fit the mandate; a wider mandate is a new mandate approved by the owner. |8306| <a id="err-mandate_integrity"></a>`mandate_integrity` | 403 | The stored mandate no longer hashes to what the owner's passkey approved. It is unusable and gets revoked. | The owner approves a new mandate. |8307| <a id="err-mandate_mainnet_disabled"></a>`mandate_mainnet_disabled` | 403 | The server lock for mandates on mainnet is closed (`SPW_DERIV_MANDATE_MAINNET`). | Paper works; cancels and reductions pass. Only the owner can change this, in the app, with the passkey. |8308| <a id="err-mandate_mismatch"></a>`mandate_mismatch` | 422 | The mandate was approved for another strategy version or another agent. | The owner approves a mandate for this one. |8309| <a id="err-mandate_none"></a>`mandate_none` | 422 | Live: no derivative mandate is in force at the signer for this venue account. | The owner approves a live mandate with the passkey. |8310| <a id="err-mandate_not_approved"></a>`mandate_not_approved` | 403 | The mandate bound to this principal was never approved, or is no longer active. | The owner approves a mandate and binds it. |8311| <a id="err-mandate_required"></a>`mandate_required` | 403, 409 | 403: an execution scope is inert on this key because no trading mandate is bound to it. 409 (agents): going live needs a mandate the owner approved for that agent. | The owner creates and approves a mandate for the key (Settings → Risk → Trading mandates), then binds it to the key. See Mandates. |8312| <a id="err-mandate_unavailable"></a>`mandate_unavailable` | 503 | Live mandates are not available on this server (a server lock). | Paper works. Only the owner can change this, in the app, with the passkey. |8313| <a id="err-mandate_wind_down"></a>`mandate_wind_down` | 422 | The mandate was revoked or has expired: for 24 h only cancels and reduce-only orders are placed. | Reduce or close; new risk needs a new mandate. |8314| <a id="err-mark_index_divergence"></a>`mark_index_divergence` | 422 | Mark and index prices are further apart than the policy allows. | Retry later. |8315| <a id="err-markets_unavailable"></a>`markets_unavailable` | 503 | No market source at all could be read. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8316| <a id="err-missing_balance"></a>`missing_balance` | 422 | A percentage of a balance was asked and the balance could not be read. | Retry, or name an absolute quantity. |8317| <a id="err-missing_reference_price"></a>`missing_reference_price` | 422 | No USD reference price is available to express the fee cap. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8318| <a id="err-mixed_credentials"></a>`mixed_credentials` | 403 | The request carried an API key and a session cookie (or a stream ticket) together. | Send exactly one credential. A script never sends the cookie. |8319| <a id="err-mode_read_only"></a>`mode_read_only` | 422 | The venue account is read-only: live trading was never authorized with the owner's passkey, or the authorization was revoked. | The owner authorizes the account in Futures → Accounts. |8320| <a id="err-nft_bad_identifier"></a>`nft_bad_identifier` | 400 | The address or token id is not well-formed for the network. | Fix the request; sending it again unchanged gives the same answer. |8321| <a id="err-nft_budget_exhausted"></a>`nft_budget_exhausted` | 429 | The wallet's own request budget for a metered provider is spent for now. | Retry later; do not poll. |8322| <a id="err-nft_disabled"></a>`nft_disabled` | 503 | The NFT module is switched off on this server. | The server operator enables it. |8323| <a id="err-nft_not_found"></a>`nft_not_found` | 404 | The chain does not know this item. | Check network, address and token id. |8324| <a id="err-nft_provider_bad_answer"></a>`nft_provider_bad_answer` | 502 | A provider answered something that could not be interpreted. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8325| <a id="err-nft_provider_disagreement"></a>`nft_provider_disagreement` | 502 | Sources disagree on a fact the answer needs. | Read GET /nfts/market: each source is on its own row. |8326| <a id="err-nft_provider_method_unsupported"></a>`nft_provider_method_unsupported` | 503 | The provider cannot answer this kind of question for this network. | Nothing to do. |8327| <a id="err-nft_provider_not_configured"></a>`nft_provider_not_configured` | 503 | The provider this call needs has no key on the server. | The answer names the server variable; the operator sets it. |8328| <a id="err-nft_provider_rate_limited"></a>`nft_provider_rate_limited` | 429 | A market-data provider is rate-limiting this wallet. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8329| <a id="err-nft_provider_unavailable"></a>`nft_provider_unavailable` | 503 | A provider is down. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8330| <a id="err-nft_unsupported_chain"></a>`nft_unsupported_chain` | 422 | No NFT adapter for this network. | Use Solana or one of the EVM networks. |8331| <a id="err-nft_unsupported_standard"></a>`nft_unsupported_standard` | 422 | The contract is not an NFT standard this wallet reads. | Nothing to do. |8332| <a id="err-no_account"></a>`no_account` | 422 | No paper account (mode `paper`) or no authorized venue account (mode `live`) on this venue. | The owner creates a paper account, or authorizes a venue account with the passkey, in Futures → Accounts. |8333| <a id="err-no_client_id_format"></a>`no_client_id_format` | 422 | The venue has no client-order-id format this wallet can derive. | Use a venue the wallet trades. |8334| <a id="err-no_instrument"></a>`no_instrument` | 422 | The command names an asset no instrument of the catalogue matches (on that venue/network). | Check the asset and the venue. |8335| <a id="err-no_liquidity"></a>`no_liquidity` | 503 | The book has no bid/ask from which to derive a price for a market order. | Retry later, or send a limit order. |8336| <a id="err-no_orderbook"></a>`no_orderbook` | 422 | The venue has no order book (GMX is a liquidity pool; spot market data stores bars). | Use GET /markets/{symbol} for the price. |8337| <a id="err-no_position"></a>`no_position` | 422 | There is no open position to close or reduce on that instrument and account. | Read GET /positions first. |8338| <a id="err-no_report"></a>`no_report` | 409 | The strategy version has no backtest report. | Run POST /strategies/{id}/backtest and wait for the job. |8339| <a id="err-no_strategy"></a>`no_strategy` | 409 | The agent has no approved strategy version. | Register one with POST /strategies and let its backtest finish. |8340| <a id="err-not_a_private_market"></a>`not_a_private_market` | 404 | The instrument exists and is not a private-company contract. | Read it with GET /markets/{symbol}. |8341| <a id="err-not_found"></a>`not_found` | 404 | Agents: no such agent, strategy version or job (or the key is restricted away from it). Any other path: not an operation of this API. | Check the id; list with GET /agents or GET /strategies. For a path, see the operation list. |8342| <a id="err-not_reducing"></a>`not_reducing` | 422 | The order would not strictly reduce an existing position: nothing was placed. | Read GET /positions; the position may already be closed. |8343| <a id="err-not_your_order"></a>`not_your_order` | 403 | A key cancels its own orders only. | The owner cancels anything, in the app. |8344| <a id="err-order_notional_exceeded"></a>`order_notional_exceeded` | 422 | The order is above the account policy's notional per order. | Send a smaller order. |8345| <a id="err-order_rate_day"></a>`order_rate_day` | 422 | Too many orders on this account today (account policy). | Wait for the next day; Only the owner can change this, in the app, with the passkey. |8346| <a id="err-order_rate_minute"></a>`order_rate_minute` | 422 | Too many orders on this account in the last minute (account policy). | Slow down. |8347| <a id="err-other_version"></a>`other_version` | 409 | Only the most recent version of an agent can be started (or: the agent runs another approved version). | Register the version again, or start the current one. |8348| <a id="err-owner_required"></a>`owner_required` | 403 | Only the owner can do this: create a spot agent (its vault is derived by the signer), let the supervisor act on live agents. | Do it in the app. |8349| <a id="err-owner_session_required"></a>`owner_session_required` | 403 | A spot order (a swap proposal) is prepared and withdrawn in the owner's session, not with a key. | Do it in the app. |8350| <a id="err-paper_unsupported"></a>`paper_unsupported` | 422 | The venue has no order book, so the paper engine cannot fill against it (GMX). | Paper-trade on Hyperliquid. |8351| <a id="err-parse_error"></a>`parse_error` | 400 | The text is not a sentence of the command grammar. `data.code` is the grammar's own code and `data.token` the index of the offending token. | Fix the line; the grammar is in the Commands section. |8352| <a id="err-position_not_attributable"></a>`position_not_attributable` | 403 | A key or an agent closes only the part of a position its own fills opened; this position (or that share of it) was opened by the owner or another principal. | Close only what the key opened; the owner closes anything. |8353| <a id="err-position_notional_exceeded"></a>`position_notional_exceeded` | 422 | The resulting position exceeds the account policy for the instrument. | Send a smaller order. |8354| <a id="err-price_deviation"></a>`price_deviation` | 422 | The price is further from the mark (or the trigger) than the account policy allows (`maxDeviationBps`; GET /risk shows the policy of each account). | Price the order closer to the mark. The mark is in GET /markets/{symbol}. |8355| <a id="err-price_not_on_tick"></a>`price_not_on_tick` | 422 | The price is not a multiple of the instrument's `tickSize` (or has too many decimals for the venue). | Round the price to `tickSize` — as a decimal STRING, not a float. |8356| <a id="err-price_required"></a>`price_required` | 422 | A limit order needs `price` (a market order needs a worst acceptable price, which the server derives). | Add `price`. |8357| <a id="err-rate_limited"></a>`rate_limited` | 429 | More calls than the key's per-minute limit in the current one-minute window. | Wait `Retry-After` seconds (also `RateLimit-Reset`), then go on. Both SDKs do this for you. |8358| <a id="err-read_only_mode"></a>`read_only_mode` | 423 | Read-only mode is on: only cancels pass (or: an agent in research mode places no order). | Cancel if needed; the owner releases it with the passkey. |8359| <a id="err-reduce_only_would_flip"></a>`reduce_only_would_flip` | 422 | A reduce-only order is larger than the position. | Size it at most to the position; POST /positions/{id}/close does it for you. |8360| <a id="err-reduce_only_would_increase"></a>`reduce_only_would_increase` | 422 | A reduce-only order would open or increase a position. | Check the side and the position. |8361| <a id="err-restricted"></a>`restricted` | 403 | The key's restrictions (venues, instruments, networks) exclude what the call names. | Use a venue, instrument or network the key is allowed on, or have the owner widen the key (passkey). |8362| <a id="err-risk_denied"></a>`risk_denied` | 422 | The independent risk engine refused the order. `data.failed` lists the failed check ids and `data.checks` gives, for each, what was observed and the limit; `data.order` is the order, state REJECTED. | Read `data.checks`. Frequent: a limit never configured on the live book, stale prices, an order too large for the collateral. See the risk checks table. |8363| <a id="err-service_unavailable"></a>`service_unavailable` | 503 | No network / no position source could be read. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8364| <a id="err-signer_unreachable"></a>`signer_unreachable` | 503 | The isolated signer cannot be reached: balances, the portfolio and anything that needs a signature are unavailable. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. If it lasts, the owner checks the signer machine. |8365| <a id="err-size_not_on_lot"></a>`size_not_on_lot` | 422 | The size is not a multiple of `lotSize`. | Round the size down to `lotSize`, or send `notional` and let the server size it. |8366| <a id="err-spot_buy_needs_quote_amount"></a>`spot_buy_needs_quote_amount` | 422 | A swap is exact-input: a spot BUY names the amount of the quote asset to spend. | Send `notional` (not `size`) for a spot buy, or the command `BUY ETH 100 USDC`. |8367| <a id="err-spot_execution_requires_agent_vault"></a>`spot_execution_requires_agent_vault` | 403 | An API key cannot place a spot order: spot execution for keys and agents exists only through an agent vault under a spot mandate. | Trade perpetuals with the key, or let a spot agent do it. |8368| <a id="err-spot_market_only"></a>`spot_market_only` | 422 | A spot order here is an immediate swap bounded by `slippageBps`: resting and trigger orders do not exist for spot. | Send `type: "market"`. |8369| <a id="err-spot_paper_not_available"></a>`spot_paper_not_available` | 422 | There is no paper spot engine for the owner. | Use mode `live` (a real swap, approved with the passkey); paper spot exists for agents only. |8370| <a id="err-spot_via_swap_screen"></a>`spot_via_swap_screen` | 422 | An owner's spot order is a swap proposal approved with the passkey. | Prepare it in the Swap screen. |8371| <a id="err-stale_book"></a>`stale_book` | 422 | The order book is older than the account policy allows. | Retry in a few seconds. |8372| <a id="err-stale_data"></a>`stale_data` | 503 | The price or book needed is older than its freshness bound (e.g. a notional cannot be turned into a size at a stale mark). | Retry in a few seconds. A limit order sized with `size` names its own price and does not depend on the mark. |8373| <a id="err-stale_request"></a>`stale_request` | 400 | `X-SPW-Timestamp` was sent and is more than 300 s from the server clock (or is not Unix seconds). | Fix the client clock, or do not send the header: it is optional. |8374| <a id="err-stale_ticker"></a>`stale_ticker` | 422 | The venue ticker is older than the account policy allows (`maxDataAgeMs`). | Retry in a few seconds. |8375| <a id="err-strategy_not_installed"></a>`strategy_not_installed` | 409 | No strategy of this template is installed in the laboratory. Nothing was created (no placeholder is substituted). | See `strategyInstalled` in GET /agents/templates. |8376| <a id="err-swap_flow_failed"></a>`swap_flow_failed` | 502 | The swap flow returned no proposal. | Retry; if it lasts, prepare the swap in the app to see the reason. |8377| <a id="err-swap_not_enabled"></a>`swap_not_enabled` | 422 | The wallet does not execute swaps on this network. | Use a network where swaps are enabled. |8378| <a id="err-total_loss_exceeded"></a>`total_loss_exceeded` | 422 | The account's total loss limit is reached. | Reductions pass; Only the owner can change this, in the app, with the passkey. |8379| <a id="err-trigger_required"></a>`trigger_required` | 422 | A stop or take-profit order needs `triggerPrice`. | Add `triggerPrice`. |8380| <a id="err-unauthenticated"></a>`unauthenticated` | 401 | No credential, or a key that is malformed, unknown, wrong, expired or revoked. One answer for all of them, on purpose. | Check the `Authorization: Bearer spw_live_…` header and the key's status and expiry in Developer → Keys. Ten failures a minute from one address lead to `auth_throttled`. |8381| <a id="err-universe_mismatch"></a>`universe_mismatch` | 422 | A fixed-universe strategy runs on its exact universe; the agent's differs. | Create the agent with the universe the message lists. |8382| <a id="err-unknown_account"></a>`unknown_account` | 404 | No paper account / authorized venue account with this `accountId` on the venue. | Omit `accountId` when the wallet has one account on the venue; else take it from GET /portfolio (`accounts`). |8383| <a id="err-unknown_company"></a>`unknown_company` | 404 | No reviewed private-company contract under this slug. | Take slugs from GET /private-markets (`companies`). |8384| <a id="err-unknown_instrument"></a>`unknown_instrument` | 404, 422, 503 | 404: the venue does not list this instrument. 422: an instrument the order path cannot use (not in the pinned table of the venue). 503: the venue could not be read to find out. | Take ids from GET /markets (`venue:symbol`). On 503 retry later. |8385| <a id="err-unknown_market"></a>`unknown_market` | 404 | A spot symbol without data, or a bare symbol nothing answers to. | Take the id from GET /markets. |8386| <a id="err-unknown_network"></a>`unknown_network` | 404 | The network id is not one of the wallet's. | Take network ids from GET /balances. |8387| <a id="err-unknown_nft"></a>`unknown_nft` | 404 | This NFT is not in the wallet's inventory. | Take `key` from GET /nfts. For any other item use GET /nfts/market. |8388| <a id="err-unknown_order"></a>`unknown_order` | 404 | No order with this id (or none this key may see). | Take ids from GET /orders or from the answer of POST /orders. |8389| <a id="err-unknown_position"></a>`unknown_position` | 404 | The position id is not of the form GET /positions returns, or names nothing. | Take `id` from GET /positions and URL-encode it. |8390| <a id="err-unknown_private_market"></a>`unknown_private_market` | 404 | This id is not a private-company market known to the venues the wallet reads. | Take ids from GET /private-markets. |8391| <a id="err-unknown_underlying"></a>`unknown_underlying` | 404 | No perpetual is mapped to this underlying in the comparator. | Use an underlying that GET /markets lists as a `base`. |8392| <a id="err-unknown_venue"></a>`unknown_venue` | 404 | The venue id is not one this wallet knows (`hyperliquid`, `gmx`, `dydx`, `edgex`, `spot`). | List the ids with GET /markets. |8393| <a id="err-unsupported_asset"></a>`unsupported_asset` | 422 | The base or quote asset is not exactly one asset of the wallet registry on that network. | Name assets the wallet lists in GET /balances. |8394| <a id="err-unsupported_interval"></a>`unsupported_interval` | 422 | Spot market data does not store this candle interval. | Use one of the intervals the message lists. |8395| <a id="err-venue_not_wired"></a>`venue_not_wired` | 422 | Live orders on this venue are not placed through this endpoint (GMX: prepared in the app, one passkey per order). This endpoint places live orders on Hyperliquid only. | Use `hyperliquid:*` for live orders through the API. |8396| <a id="err-venue_rate_limited"></a>`venue_rate_limited` | 503 | The venue is rate-limiting this wallet. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8397| <a id="err-venue_rejected"></a>`venue_rejected` | 422 | The venue itself refused (the message quotes it): the order, a cancel, a margin mode it does not offer. | Read `message`; fix the order. |8398| <a id="err-venue_restricted"></a>`venue_restricted` | 403 | The venue is never tradable from this wallet (dYdX and edgeX: market data only, a jurisdiction restriction). | Read its data; trade on Hyperliquid. |8399| <a id="err-venue_timeout"></a>`venue_timeout` | 503 | The venue did not answer in time and no earlier value can stand in. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8400| <a id="err-venue_unavailable"></a>`venue_unavailable` | 503 | The venue (or the signer, for the wallet address) could not be read, so no honest answer exists. | Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. |8401| <a id="err-wrong_kind"></a>`wrong_kind` | 409 | The strategy and the agent are of different kinds (spot / perp), or the operation does not apply to this kind of agent. | Match the kinds. |8402| <a id="err-zero_size"></a>`zero_size` | 422 | The quantity resolves to zero. | Raise the amount. |8403
Files main
Menu

Theme