SPB Git

Repository Public

TRADING-API-REFERENCE.md 383.6 KB

# SP Trading API — reference

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: a test compares this file with what the code generates. The same content is served by the wallet at GET /api/v1/trading/docs (HTML) and GET /api/v1/trading/docs.md (this Markdown).

Version 1.0.0 · 46 operations · OpenAPI 3.1: docs/openapi/trading-v1.json, served at GET /api/v1/trading/openapi.json.

# Contents

# Overview

The 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.

Base URL https://wallet.spboucher.ai/api/v1/trading
Format JSON in, JSON out, UTF-8. Request bodies are strict: an unknown field is refused (400 bad_request)
Authentication Authorization: Bearer spw_live_…
Contract OpenAPI 3.1 at /api/v1/trading/openapi.json, generated from the same table the server registers its routes from
This reference /api/v1/trading/docs (HTML), /api/v1/trading/docs.md (Markdown) — both need a key or the owner session, like every path of the API
SDKs TypeScript @sp-wallet/trading-sdk (packages/trading-sdk), Python sp-wallet-python (sdk/python)
Live market data websocket /api/v1/trading/stream

Three rules run through everything:

  • Money is a string. Prices, sizes, amounts and rates are decimal strings; send strings, parse with a decimal type.
  • Paper and live are never mixed. Every row that could be either carries mode; no figure adds the two.
  • 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.

# Getting started in five minutes

Five minutes from nothing to a simulated order. Everything below was run against a real server; the answers shown are recorded.

# 1. Create a key

In the wallet app: Settings → Developer / API → Keys → New key.

  • Name — anything (my bot).
  • Expiry — required, at most 365 days.
  • 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.
  • Approve with your passkey. The secret (spw_live_spk_…) is shown once: the server keeps only a hash of it.

A key opens /api/v1/trading/ and nothing else — never the recovery phrase, the signer, the security settings or the keys themselves.

# 2. First call

bash
export SP_WALLET_BASE_URL=https://wallet.spboucher.ai
export SP_WALLET_API_KEY=spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0   # yours, shown once

curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
import { SPWallet } from '@sp-wallet/trading-sdk';

const client = new SPWallet();   // reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL
const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });
console.log(markets[0].id, markets[0].mark);
python
from sp_wallet import SPWallet

client = SPWallet()   # reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL
markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets
print(markets[0].id, markets[0].mark)
json
{
  "markets": [
    {
      "id": "hyperliquid:BTC",
      "venue": "hyperliquid",
      "kind": "perpetual",
      "symbol": "BTC",
      "base": "BTC",
      "quote": "USD",
      "status": "active",
      "mark": "64432",
      "index": "64460.7",
      "funding": "0.0000089721",
      "fundingIntervalSec": 3600,
      "volume24h": "3621656019.2002997398",
      "openInterest": "37680.57528",
      "maxLeverage": "40",
      "tickSize": "0.1",
      "lotSize": "0.00001",
      "collateral": "USDC",
      "restriction": null,
      "ts": 1794953721101,
      "stale": false,
      "source": "venue"
    }
  ],
  "total": 1,
  "truncated": false,
  "errors": [],
  "ts": 1794953721103
}

Prices are strings ("mark": "64432"): never parse them as floats. ts is milliseconds since the epoch.

The SDKs are in the repository and are not published:

bash
# TypeScript (not on npm: built from the repository)
node packages/trading-sdk/scripts/build.mts
npm install /path/to/sp-wallet/packages/trading-sdk

# Python (not on PyPI)
pip install /path/to/sp-wallet/sdk/python

# 3. First paper order

An order placed with a key needs three things, which only the owner can set up:

  1. a paper account on Hyperliquid — app: Futures → Accounts;
  2. 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;
  3. the mandate bound to the key. Without it, orders:execute is inert and the API answers:
json
{
  "error": "mandate_required",
  "message": "the scope orders:execute is inert on this key: no trading mandate is bound to it"
}

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.

Then:

bash
# 1. what would happen — creates nothing
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Content-Type: application/json" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'

# 2. place it — one Idempotency-Key per logical order
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -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"}'

# 3. read it, then close the position
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" -H "Authorization: Bearer $SP_WALLET_API_KEY"
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
import { SPWallet } from '@sp-wallet/trading-sdk';

const client = new SPWallet();
const order = { mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' } as const;

const preview = await client.previewOrder(order);              // creates nothing
if (!preview.wouldExecute) throw new Error(JSON.stringify(preview.refusals));

const placed = await client.createOrder(order, { idempotencyKey: 'bot-2026-11-17-0001' });
const done = await client.waitForOrder(placed.order.id);       // FILLED, CANCELLED, REJECTED or FAILED
console.log(done.order.status, done.order.filled, done.order.avgFillPrice);

const { positions } = await client.getPositions({ mode: 'paper' });
await client.closePosition(positions[0].id);                   // strictly reduce-only
python
from sp_wallet import SPWallet

client = SPWallet()
order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")

preview = client.preview_order(**order)                        # creates nothing
if not preview.would_execute:
    raise SystemExit(preview.refusals)

placed = client.create_order(**order, idempotency_key="bot-2026-11-17-0001")
done = client.wait_for_order(placed.order.id)                  # FILLED, CANCELLED, REJECTED or FAILED
print(done.order.status, done.order.filled, done.order.avg_fill_price)

positions = client.get_positions(mode="paper").positions
client.close_position(positions[0].id)                         # strictly reduce-only

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

json
{
  "order": {
    "id": "0xff18683e8e2aa319d3812cf8a47fc261",
    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "venueOrderId": "paper-o-1",
    "instrument": "hyperliquid:BTC",
    "side": "buy",
    "type": "market",
    "size": "0.00155",
    "price": "64754",
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "ioc",
    "status": "FILLED",
    "final": true,
    "reasonCode": "VENUE_FILLED",
    "reason": null,
    "rejectCode": null,
    "engineStatus": "filled",
    "filled": "0.00155",
    "avgFillPrice": "64432",
    "acknowledged": true,
    "cancelRequested": false,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",
    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",
    "notionalUsd": "100.3687",
    "projectionError": null,
    "version": 4,
    "createdAt": 1794953729578,
    "updatedAt": 1794953729602
  },
  "idempotent": false,
  "approval": null
}

The same call with the same Idempotency-Key returns the same order (header Idempotent-Replay: true): a retry can never place it twice.

If 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).

# 4. Where to go next

# Démarrage rapide (français)

Cinq 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.

# 1. Créer une clé

Dans l'application : Réglages → Développeur / API → Clés → Nouvelle clé.

  • Nom — libre (mon robot).
  • Expiration — obligatoire, au plus 365 jours.
  • 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.
  • 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.

Une 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.

# 2. Premier appel

bash
export SP_WALLET_BASE_URL=https://wallet.spboucher.ai
export SP_WALLET_API_KEY=spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0   # yours, shown once

curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
import { SPWallet } from '@sp-wallet/trading-sdk';

const client = new SPWallet();   // reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL
const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });
console.log(markets[0].id, markets[0].mark);
python
from sp_wallet import SPWallet

client = SPWallet()   # reads SP_WALLET_API_KEY and SP_WALLET_BASE_URL
markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets
print(markets[0].id, markets[0].mark)

Les prix sont des chaînes ("mark": "64432") : ne les lisez jamais comme des flottants. ts est en millisecondes depuis l'époque Unix.

# 3. Premier ordre simulé (paper)

Un ordre passé avec une clé exige trois choses, que seul le propriétaire peut mettre en place :

  1. un compte simulé sur Hyperliquid — application : Contrats à terme → Comptes ;
  2. 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 ;
  3. le mandat lié à la clé. Sans lui, orders:execute est inerte et l'API répond 403 mandate_required.

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.

Ensuite :

bash
# 1. what would happen — creates nothing
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Content-Type: application/json" -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'

# 2. place it — one Idempotency-Key per logical order
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -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"}'

# 3. read it, then close the position
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" -H "Authorization: Bearer $SP_WALLET_API_KEY"
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
import { SPWallet } from '@sp-wallet/trading-sdk';

const client = new SPWallet();
const order = { mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' } as const;

const preview = await client.previewOrder(order);              // creates nothing
if (!preview.wouldExecute) throw new Error(JSON.stringify(preview.refusals));

const placed = await client.createOrder(order, { idempotencyKey: 'bot-2026-11-17-0001' });
const done = await client.waitForOrder(placed.order.id);       // FILLED, CANCELLED, REJECTED or FAILED
console.log(done.order.status, done.order.filled, done.order.avgFillPrice);

const { positions } = await client.getPositions({ mode: 'paper' });
await client.closePosition(positions[0].id);                   // strictly reduce-only
python
from sp_wallet import SPWallet

client = SPWallet()
order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")

preview = client.preview_order(**order)                        # creates nothing
if not preview.would_execute:
    raise SystemExit(preview.refusals)

placed = client.create_order(**order, idempotency_key="bot-2026-11-17-0001")
done = client.wait_for_order(placed.order.id)                  # FILLED, CANCELLED, REJECTED or FAILED
print(done.order.status, done.order.filled, done.order.avg_fill_price)

positions = client.get_positions(mode="paper").positions
client.close_position(positions[0].id)                         # strictly reduce-only

Un 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.

# 4. Ordres réels

Un 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 et Why an order is refused.

# Authentication and permissions

Every request carries the key in one header. No cookie, no CSRF header, no query parameter — a key in a URL opens nothing.

http
GET /api/v1/trading/markets HTTP/1.1
Host: wallet.spboucher.ai
Authorization: Bearer spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0

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

json
{
  "error": "unauthenticated",
  "message": "authentication required"
}

10 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).

A 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).

# Permissions (scopes)

Scope Opens Execution scope
wallet:read Balances, the portfolio, activity, the wallet's NFTs. —
markets:read Markets, order books, candles, the venue comparator, private markets, NFT market data, and the websocket stream. —
orders:read Orders and their fills. —
orders:prepare Preview an order; dry-run a command. Creates nothing. —
orders:execute Place an order. Execution scope: inert without a mandate bound to the key. yes
orders:cancel Cancel the key's own orders. Needs no mandate: a cancel only removes risk. yes
positions:read Positions and the risk state. —
positions:manage Close or reduce a position (needs a mandate); engage the kill switch (needs none). yes
strategies:read The strategy library and the versions pinned to agents. —
strategies:manage Register, backtest, start and stop strategy versions. Research and paper sign nothing. —
agents:read Agents, their signals, journal, orders, performance, jobs. —
agents:manage Create, start, pause, stop and backtest agents. Going live needs the agent's own owner-approved mandate. —

Every operation names the one scope it needs. A key without it gets:

json
{
  "error": "insufficient_scope",
  "message": "this key lacks the scope wallet:read"
}

The 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.

# What else a key carries

  • Expiry — required, at most 365 days. At most 50 keys.
  • Rate limit — 120 calls a minute by default, at most 600.
  • Restrictions — optional allow-lists of venues, instruments, networks and source IP addresses / CIDR blocks. Outside them: 403 restricted or ip_not_allowed.
  • Limits — optional notional per order and per day, in USD (403 key_limit_exceeded).
  • Mandate — the id of the trading mandate bound to it, or none.

Narrowing 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.

# Decimals, timestamps, identifiers

# Decimals

Anything 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.

Counts and settings are JSON numbers (limit, slippageBps, fundingIntervalSec, decimals).

# Timestamps

Two forms, by family — the field name tells which:

  • milliseconds since the Unix epoch, a JSON integer: ts, createdAt, updatedAt, expiresAt, at of a switch — markets, orders, positions, agents, risk;
  • ISO 8601 UTC strings: asOf (portfolio, balances, NFTs), at of an activity item, priceAt, fetchedAt, the ts of a webhook envelope.

The optional request header X-SPW-Timestamp is Unix seconds.

# Freshness

Market 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.

# Identifiers

Thing Form Example
Instrument / market venue:symbol hyperliquid:BTC, gmx:BTC/USD [BTC-USDC], dydx:BTC-USD, spot:ETH
Order opaque string 0xff18683e8e2aa319d3812cf8a47fc261
Position mode:venue:account:instrument — URL-encode it in a path paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC
Key spk_ + 12 hex spk_0123456789ab
Agent, job, strategy version, mandate, account UUID b9180e9d-3977-403c-a072-9af105bfd59b

A bare symbol (BTC) is accepted where a market is named, when it is not ambiguous; otherwise:

json
{
  "error": "ambiguous_symbol",
  "message": "'BTC' exists on several venues: name one of the candidates as venue:symbol",
  "candidates": [
    "dydx:BTC-USD",
    "edgex:BTCUSDC"
  ]
}

# Instruments and venues

What can be read and what can be traded are different lists.

Venue Market data Paper orders (API) Live orders (API key)
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, …
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)
dydx yes no no — market data only (403 venue_restricted)
edgex yes no no — market data only (403 venue_restricted)
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

GET /markets?venue=hyperliquid lists the instruments with what an order must respect:

json
{
  "id": "hyperliquid:BTC",
  "venue": "hyperliquid",
  "kind": "perpetual",
  "symbol": "BTC",
  "base": "BTC",
  "quote": "USD",
  "status": "active",
  "mark": "64432",
  "index": "64460.7",
  "funding": "0.0000089721",
  "fundingIntervalSec": 3600,
  "volume24h": "3621656019.2002997398",
  "openInterest": "37680.57528",
  "maxLeverage": "40",
  "tickSize": "0.1",
  "lotSize": "0.00001",
  "collateral": "USDC",
  "restriction": null,
  "ts": 1794953721101,
  "stale": false,
  "source": "venue"
}

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.

Candle intervals: 1m, 5m, 15m, 1h, 4h, 1d (spot market data stores fewer: 422 unsupported_interval).

# Paper and live, the execution lock

Every order names its mode.

paper live
What executes the wallet's paper engine, against the venue's real public order book the venue (Hyperliquid)
Money simulated collateral of a paper account the collateral of an authorized venue account
Signature none the isolated signer signs under the mandate it stores
Mandate (key) a paper mandate; approving it signs nothing a live mandate the owner approves with the passkey, compiled into the signer
Server locks none SPW_TRADING_API_EXECUTION, and the mainnet locks

# The execution lock

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:

json
{
  "error": "execution_disabled",
  "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."
}

Paper 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.

# Before the first live order with a key

  1. An authorized Hyperliquid venue account (app: Futures → Accounts, passkey).
  2. A live trading mandate for the key, approved with the passkey, and bound to the key.
  3. 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.
  4. The server locks open.

Preview first: POST /orders/preview runs every gate on the market as it is now and says what would refuse the order, without creating anything.

# Mandates

A 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.

What 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.

  • 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.
  • 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.
  • A revoked or expired mandate winds down: for 24 hours only cancels and strictly reducing orders pass (422 mandate_wind_down).
  • 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.
  • A key or an agent closes only what its own fills opened (403 position_not_attributable).

An order outside the mandate is refused with every reason at once, and the refused order is recorded:

json
{
  "error": "mandate_denied",
  "message": "the order is outside the mandate: ORDER_NOTIONAL_EXCEEDED",
  "data": {
    "reasons": [
      "ORDER_NOTIONAL_EXCEEDED"
    ],
    "order": {
      "id": "0xd51cebbed3c7d5e595f90d368ea832ad",
      "orderId": "0xd51cebbed3c7d5e595f90d368ea832ad",
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "clientId": "0xd51cebbed3c7d5e595f90d368ea832ad",
      "clientOrderId": "0xd51cebbed3c7d5e595f90d368ea832ad",
      "venueOrderId": null,
      "instrument": "hyperliquid:BTC",
      "side": "buy",
      "type": "market",
      "size": "0.01396",
      "price": "64749",
      "triggerPrice": null,
      "reduceOnly": false,
      "tif": "ioc",
      "status": "REJECTED",
      "final": true,
      "reasonCode": "MANDATE_DENIED",
      "reason": "the order is outside the mandate: ORDER_NOTIONAL_EXCEEDED",
      "rejectCode": "mandate_denied",
      "engineStatus": null,
      "filled": "0",
      "avgFillPrice": null,
      "acknowledged": false,
      "cancelRequested": false,
      "origin": "trading_api",
      "principal": {
        "kind": "api_key",
        "id": "spk_0123456789ab"
      },
      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
      "engine": "paper",
      "engineRef": null,
      "hash": "1aee5a4cdfc23da98dd02b104acef0677437ba9d866a24cf53c509e00b6d6a40",
      "notionalUsd": "903.89604",
      "projectionError": null,
      "version": 1,
      "createdAt": 1794953731495,
      "updatedAt": 1794953731502
    }
  }
}

# data.reasons of mandate_denied

Reason Meaning
INVALID_INPUT the order or the usage figures could not be evaluated
MANDATE_NOT_YET_VALID the mandate's validity window has not started
MANDATE_ENDED the mandate has ended (past its end date and its wind-down)
MANDATE_REVOKED the mandate was revoked
WIND_DOWN_REDUCING_ONLY the mandate is winding down: only strictly reducing orders pass
PRINCIPAL_MISMATCH the mandate was approved for another key or agent
MANDATE_ID_MISMATCH the order names another mandate
MODE_MISMATCH a paper mandate cannot place a live order, nor the reverse
ACCOUNT_NOT_ALLOWED the account is not one of the mandate's
VENUE_NOT_ALLOWED the venue is not one of the mandate's
NETWORK_NOT_ALLOWED the network is not one of the mandate's
INSTRUMENT_NOT_ALLOWED the instrument is not in the mandate's list
MARKET_KIND_NOT_ALLOWED spot or perp is not allowed by the mandate
ORDER_TYPE_NOT_ALLOWED the order type (market, limit, stop, take-profit) is not in the mandate's list
NOTIONAL_UNKNOWN the order cannot be valued (no reference price), so the limits cannot be checked
ORDER_NOTIONAL_EXCEEDED the order is above maxOrderNotionalUsd
POSITION_NOTIONAL_EXCEEDED the resulting position is above maxPositionNotionalUsd
CAPITAL_EXCEEDED the capital in use after the order is above maxCapitalUsd
LEVERAGE_EXCEEDED the leverage is above maxLeverage
LEVERAGE_UNKNOWN the leverage the order would run under is not known
DAILY_LOSS_REACHED today's realised loss under the mandate reached maxDailyLossUsd
BELOW_FLOOR_EQUITY the equity of the mandated accounts is below floorEquityUsd
RATE_PER_MINUTE the mandate's orders-per-minute limit is reached
RATE_PER_HOUR the mandate's orders-per-hour limit is reached
RATE_PER_DAY the mandate's orders-per-day limit is reached
SLIPPAGE_ABOVE_MANDATE the order's slippage bound is above the mandate's maxSlippageBps
FEE_ABOVE_MANDATE the order's fee cap is above the mandate's maxFeeUsd
ORDER_OUTLIVES_MANDATE the order would stay valid after the mandate ends
STOP_LOSS_GTE stop condition: the total loss under the mandate reached its threshold
STOP_DRAWDOWN_GTE stop condition: the drawdown from the peak equity reached its threshold
STOP_CONSECUTIVE_REJECTS_GTE stop condition: too many consecutive rejected orders
STOP_DATA_STALE_GTE stop condition: the market data is too old
STOP_SIGNER_UNREACHABLE_GTE stop condition: the signer has been unreachable for too long

# Why an order is refused

An order goes through gates, in this order. The first that refuses answers; the error code tells which gate it was.

# Gate Refuses with Fix
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
2 The key — scope, restrictions, a mandate bound to it 403 insufficient_scope, restricted, mandate_required another key, or the owner widens it
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
4 The mandate 403 mandate_denied + data.reasons; mandate_not_approved, mandate_integrity; 422 mandate_wind_down fit the mandate, or a new mandate
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
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
7 The venue 422 venue_rejected; 503 venue_unavailable read message

Up 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.

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.

# The risk engine

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

json
{
  "error": "kill_switch_active",
  "message": "kill_switch: the kill switch is on: no new risk",
  "data": {
    "failed": [
      "kill_switch"
    ],
    "checks": [
      {
        "id": "kill_switch",
        "ok": false,
        "observed": "true",
        "limit": "false",
        "detail": "the kill switch is on: no new risk",
        "exempt": false
      }
    ],
    "decisionId": 21,
    "order": {
      "id": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",
      "orderId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "clientId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",
      "clientOrderId": "0x6f3d33c8d9a43c3e0bf5a17784a5c1a7",
      "venueOrderId": null,
      "instrument": "hyperliquid:BTC",
      "side": "buy",
      "type": "market",
      "size": "0.00155",
      "price": "64754",
      "triggerPrice": null,
      "reduceOnly": false,
      "tif": "ioc",
      "status": "REJECTED",
      "final": true,
      "reasonCode": "KILL_SWITCH_ACTIVE",
      "reason": "kill_switch: the kill switch is on: no new risk",
      "rejectCode": "kill_switch_active",
      "engineStatus": null,
      "filled": "0",
      "avgFillPrice": null,
      "acknowledged": false,
      "cancelRequested": false,
      "origin": "trading_api",
      "principal": {
        "kind": "api_key",
        "id": "spk_0123456789ab"
      },
      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
      "engine": "paper",
      "engineRef": null,
      "hash": "ea251eb6fc7f290e903f8c8a23dc307c80181d4d35ee320e9d7aa65622218b3f",
      "notionalUsd": "100.3687",
      "projectionError": null,
      "version": 1,
      "createdAt": 1794953766532,
      "updatedAt": 1794953766906
    }
  }
}

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.

Check Limit Rule Applies to a strictly reducing order
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
read_only context.readOnly read-only mode denies every order, reducing or not; only a cancel passes yes
kill_switch context.killSwitch the kill switch denies every order that is not strictly reducing no (exempt)
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
venue_allowed allowedVenues the venue is in the allow-list no (exempt)
instrument_allowed allowedInstruments the instrument is in the allow-list no (exempt)
instrument_status — the instrument is active on the venue (a halted or reduce-only instrument takes no new risk) no (exempt)
signer_status — live orders: the signer is reachable and not halted no (exempt)
venue_connection — live orders: the venue connection is up no (exempt)
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
price_consistency maxSourceDeviationBps (highest − lowest) / lowest over the fresh sources is within the limit; inconsistent data denies only without a limit price
order_notional maxOrderNotional notional of the order (its own notional, or size × the highest of reference, limit and trigger price) no (exempt)
daily_notional maxDailyNotional today's accepted notional plus this order no (exempt)
order_rate_minute maxOrdersPerMinute orders already accepted in the last minute are below the limit no (exempt)
order_rate_hour maxOrdersPerHour orders already accepted in the last hour are below the limit no (exempt)
order_rate_day maxOrdersPerDay orders already accepted today are below the limit no (exempt)
position_size maxPositionNotional resulting position on the instrument, at the reference price no (exempt)
order_leverage maxOrderLeverage perp: the leverage setting the order runs under is known, within the limit and within the venue's maximum no (exempt)
account_leverage maxAccountLeverage gross exposure after the order / total equity (margin.effectiveLeverage); equity ≤ 0 denies no (exempt)
gross_exposure maxGrossExposure Σ |size| · mark over all venues (margin.grossExposure) no (exempt)
net_exposure maxNetExposure |Σ long − Σ short| over all venues (margin.netExposure) no (exempt)
asset_exposure maxAssetExposure |net| exposure of the order's asset over all venues (margin.exposureByAsset) no (exempt)
venue_exposure maxVenueExposure gross exposure on the order's venue no (exempt)
collateral_concentration maxVenueCollateralShareBps share of the total equity held on the order's venue no (exempt)
daily_loss maxDailyLoss today's loss has not reached the limit no (exempt)
total_loss maxTotalLoss the loss since inception has not reached the limit no (exempt)
drawdown maxDrawdownBps (peak − current) / peak has not reached the limit no (exempt)
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)
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)
min_liquidity minLiquidity depth on the taking side within withinBps of the mid ≥ multiple × order size no (exempt)
context_complete — every account of the book could be read; when one cannot, exposure is not known and new risk is denied no (exempt)

Three things worth knowing:

  • 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.
  • 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.
  • 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.

# The venue engine

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

json
{
  "error": "price_deviation",
  "message": "price 51000 is more than 200 bps away from the mark 64433",
  "data": {
    "order": "{ … the order, status REJECTED … }"
  }
}

An 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.

# Order states

An order's status is one of twelve states; final is true for four of them.

text
CREATED → VALIDATED → AWAITING_APPROVAL → APPROVED → SUBMITTING → SUBMITTED → PARTIALLY_FILLED → FILLED
                                                          └→ UNKNOWN → (the server asks the venue) → any of the above, or CANCELLED / REJECTED / FAILED
final: FILLED, CANCELLED, REJECTED, FAILED
status Final Meaning
CREATED — recorded; nothing checked yet
VALIDATED — passed the mandate and the risk engine
AWAITING_APPROVAL — an owner order waits for the passkey in the app (never the case for a key)
APPROVED — approved; about to be handed to its engine
SUBMITTING — being sent to the venue (or the paper engine)
SUBMITTED — accepted by the venue and resting; nothing filled yet
PARTIALLY_FILLED — partly filled; the rest is still working
FILLED yes completely filled. Final
CANCELLED yes withdrawn, expired or cancelled. Final
REJECTED yes refused by a rule: validation, mandate, risk, signer policy or the venue. Final; reasonCode and rejectCode say which
FAILED yes a technical failure after which it is PROVEN that no order exists at the venue. Final
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
  • Decide on status and final. engineStatus is the executing engine's own word for the same moment, for information.
  • 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.
  • Nothing becomes FILLED without an event that comes from the venue (or the paper engine).
  • reasonCode is the closed reason of the current state; rejectCode is the API error code of the refusal; reason is a sentence for people.
  • 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.

# Idempotency

Every mutating call needs an Idempotency-Key header: 8 to 100 characters among letters, digits, . _ : -. It makes a retry safe.

You send The server
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)
the same key, the same request returns the stored answer with Idempotent-Replay: true; nothing runs again
the same key, a different request 409 idempotency_conflict
the same key while the first call is still running 409 idempotency_in_progress — wait and resend
no key 400 idempotency
json
{
  "error": "idempotency_conflict",
  "message": "this Idempotency-Key was used with a different request"
}
  • The namespace is the principal: two keys can use the same string.
  • 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.
  • Stored answers are kept 24 hours.
  • 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".
  • 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.

Operations that take no Idempotency-Key, because they change nothing or are naturally idempotent: POST /orders/preview and POST /risk/kill-switch.

A 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.

# Pagination

Three conventions, by list:

Lists How End
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
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
GET /markets and the other lists not paginated; limit cuts, and total + truncated say so —

Cursor 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.

json
{
  "items": [
    {
      "kind": "fill",
      "mode": "paper",
      "at": "2026-11-17T22:15:31.480Z",
      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-6",
      "venue": "hyperliquid",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "instrument": "hyperliquid:BTC",
      "side": "sell",
      "price": "64426",
      "size": "0.00078",
      "fee": "0.022613526",
      "closedPnl": "-0.00468"
    },
    {
      "kind": "fill",
      "mode": "paper",
      "at": "2026-11-17T22:15:31.456Z",
      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-4",
      "venue": "hyperliquid",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "instrument": "hyperliquid:BTC",
      "side": "sell",
      "price": "64426",
      "size": "0.00077",
      "fee": "0.022323609",
      "closedPnl": "-0.00462"
    }
  ],
  "nextCursor": "WyIxNzk0OTUzNzMxNDU2MDAwIiwiZiIsIjZhMmM4MzUxLWNkNzktNDRlMi1iNzVhLWYzOTI4MGQwZWJjMjpwYXBlci1mLTQiXQ"
}

Both SDKs follow the cursor for you: iterateOrders / iterateActivity (TypeScript), iter_orders / iter_activity (Python).

# Rate limits

Per key, in fixed one-minute windows: 120 calls a minute by default, set per key up to 600. Every answer to a key carries:

Header Meaning
RateLimit-Limit the key's calls per minute
RateLimit-Remaining calls left in the current window
RateLimit-Reset seconds until the window resets
Retry-After on a 429 only: seconds to wait
http
HTTP/1.1 429 Too Many Requests
RateLimit-Limit: 3
RateLimit-Remaining: 0
RateLimit-Reset: 60
Retry-After: 60

{"error":"rate_limited","message":"too many requests for this key"}
  • Every call counts, a refused one and a 404 included.
  • The window is in the memory of the API process: a restart resets it.
  • Failed authentications are counted per source address, apart: 10 a minute, then 429 auth_throttled with Retry-After: 60.
  • The owner's session is limited per address instead (240 a minute) and carries no RateLimit-* header.
  • Venues have their own limits: a venue that throttles the wallet answers 503 venue_rate_limited, which is not about your key.

Both SDKs wait and retry on 429 (reads, and writes because they carry an Idempotency-Key). For live prices do not poll: use the stream.

# Errors

Every error has the same body, whatever the status:

json
{
  "error": "<stable machine code>",
  "message": "<sentence for people, English>",
  "data": {
    "…": "machine-readable detail, on refusals that have some"
  }
}

Branch 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.

Status Class Retry?
400 the request is not valid no — fix it
401 no usable credential no
403 authenticated, and refused: scope, restriction, mandate, server lock no
404 the object does not exist; or the path is not an operation (not_found) no
409 a conflict with the state of the object, or a choice is needed after resolving it
422 a valid request that cannot be carried out now after changing the order
423 blocked by the kill switch, read-only mode or a halt when the owner releases it
429 too many requests yes, after Retry-After
500 server error; a mutating call may or may not have run yes, with the same Idempotency-Key
501 declared but not connected; nothing was done no
502, 503 a backing service (venue, signer, provider) failed; nothing was done yes, with backoff

A path that is not an operation, or a known path with another method, answers in the same model:

json
{
  "error": "not_found",
  "message": "no such operation in the trading API: see GET /api/v1/trading/openapi.json"
}

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

json
{
  "error": "bad_request",
  "message": "invalid request"
}

Both 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.

The full list, code by code, is the error catalogue at the end; each operation lists the codes it can answer.

# Commands

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.

text
LONG|SHORT <asset>-PERP <notional> [x<lev>] [LIMIT <px>] [SL <px>] [TP <px>] [ON <venue>]
CLOSE <asset>-PERP [pct%] [ON <venue>]
BUY <asset> <amount> <quote> [ON <venue>]          (spot — the owner only)
SELL <asset> <amount|pct%> [FOR <quote>] [ON <venue>]   (spot — the owner only)
CANCEL ORDER <id>          CANCEL ALL [ON <venue>]
SHOW POSITIONS | BALANCES | ORDERS | RISK
STOP ALL AGENTS            KILL

French spellings are accepted for the keywords (ACHETER, VENDRE, FERMER, ANNULER, AFFICHER, SUR, URGENCE, …); numbers are plain decimals.

  • 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.
  • dryRun: true answers what the line resolves to and does nothing.
  • 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:
json
{
  "error": "ambiguous_command",
  "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.",
  "data": {
    "questions": [
      {
        "field": "network",
        "options": [
          "mainnet"
        ],
        "message": "on which network? The defaults name none for BTC-PERP"
      },
      {
        "field": "orderTtlMs",
        "options": [],
        "message": "no order validity is pre-approved: how long may the order wait before it is sent?"
      }
    ]
  }
}

The 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".

A line that is not a sentence of the grammar:

json
{
  "error": "parse_error",
  "message": "unknown command",
  "data": {
    "code": "unknown_command",
    "token": 0
  }
}

# Webhooks

Webhooks 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.

Event Payload (data) When
key.revoked { keyId, name, reason } an API key was revoked (or replaced by a rotation)
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")
agent.updated { agentId, kind, state, mode } an agent was started, paused or stopped (by the owner, an API key or the risk-management agent)
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)
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

Payloads carry identifiers and states only — no secret, no key material, no amount. On order.updated, read the order with GET /orders/{id}.

# What you receive

http
POST /your/endpoint HTTP/1.1
Content-Type: application/json
X-SPW-Timestamp: 1794953687
X-SPW-Signature: v1=df38f5cf8ef5b56e0c43c3b4fca7755bfcde2892199e8bfe8dc974fee3863b7b
X-SPW-Event: key.revoked
X-SPW-Delivery: 42

{"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"}}

# Verifying the signature

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.

The 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.

ts
import { constructWebhookEvent, WebhookVerificationError } from '@sp-wallet/trading-sdk';

// rawBody: the bytes exactly as received (Buffer / Uint8Array / string)
try {
  const event = await constructWebhookEvent({
    secret: process.env.SP_WALLET_WEBHOOK_SECRET!,
    timestamp: req.headers['x-spw-timestamp'],
    signature: req.headers['x-spw-signature'],
    body: rawBody,
  });
  if (!seen.has(event.id)) { seen.add(event.id); handle(event.event, event.data); }
  res.writeHead(200).end('ok');
} catch (e) {
  res.writeHead(e instanceof WebhookVerificationError ? 400 : 500).end();
}
python
from sp_wallet import WebhookVerificationError, construct_webhook_event

# raw: the bytes exactly as received
try:
    event = construct_webhook_event(secret=SECRET, timestamp=headers.get("x-spw-timestamp"),
                                    signature=headers.get("x-spw-signature"), body=raw)
except WebhookVerificationError:
    return 400
if event["id"] not in seen:
    seen.add(event["id"])
    handle(event["event"], event["data"])
return 200
python
# without the SDK
import hashlib, hmac, time

def verify(secret: str, timestamp: str, signature: str, raw: bytes) -> bool:
    if abs(time.time() - int(timestamp)) > 300:
        return False
    want = "v1=" + hmac.new(secret.encode(), timestamp.encode() + b"." + raw, hashlib.sha256).hexdigest()
    return hmac.compare_digest(want, signature)

# Delivery

  • At least once. Deduplicate on the envelope's id (the same for every attempt of one event; X-SPW-Delivery is the delivery row).
  • 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.
  • HTTPS only, no credentials in the URL, no redirect followed, 8 seconds to answer.
  • Order is not guaranteed: use data.seq of order.updated (it grows with each transition of one order).

# Streaming (websocket)

Live 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.

text
wss://wallet.spboucher.ai/api/v1/trading/stream
  • Scope: markets:read. The key goes in the Authorization header of the handshake — never in the URL.
  • 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.
  • A key's venue and instrument restrictions apply per subscription (error restricted).
  • At most 4 connections per key and 300 subscriptions per connection.
  • A stream connection is not in the key's usage log; the ticket request is.
ts
import { SPWalletStream } from '@sp-wallet/trading-sdk';

const stream = new SPWalletStream();   // SP_WALLET_API_KEY, SP_WALLET_BASE_URL
await stream.subscribe([{ type: 'quote', id: 'hyperliquid:BTC' }, { type: 'status', id: 'hyperliquid' }]);
for await (const m of stream) {
  if (m.type === 'quote') console.log(m.id, m.bid, m.ask, m.mark, m.stale ? '(stale)' : '');
}
python
# pip install "sp-wallet-python[stream]"
import asyncio
from sp_wallet import SPWalletStream
from sp_wallet.stream import Quote

async def main() -> None:
    stream = SPWalletStream()   # SP_WALLET_API_KEY, SP_WALLET_BASE_URL
    await stream.subscribe([{"type": "quote", "id": "hyperliquid:BTC"}, {"type": "status", "id": "hyperliquid"}])
    async for m in stream:
        if isinstance(m, Quote):
            print(m.id, m.bid, m.ask, m.mark, "(stale)" if m.stale else "")

asyncio.run(main())

# Protocol (version 1), in short

JSON text frames; every server frame has "v": 1 and a type. Prices, sizes and rates are decimal strings; times are milliseconds.

json
// client → server
{ "op": "subscribe", "reqId": 7, "channels": [ { "type": "quote",  "id": "hyperliquid:BTC" },
                                               { "type": "book",   "id": "hyperliquid:BTC", "depth": 10 },
                                               { "type": "trades", "id": "hyperliquid:BTC" },
                                               { "type": "candle", "id": "hyperliquid:BTC", "interval": "1m" },
                                               { "type": "status", "id": "*" } ] }
{ "op": "unsubscribe", "channels": [ { "type": "quote", "id": "hyperliquid:BTC" } ] }
{ "op": "ping", "t": 42 }
Server frame Carries
hello first frame: connId, heartbeatMs, the limits
subscribed one per channel, with the last known value at once (snapshot, snapshotAgeMs) and staleAfterMs
quote bid, ask, mid, mark, index, funding, open interest, seq, stale — a full state each time
book a snapshot, then deltas (prevSeq must equal the last seq applied; size "0" removes a price; checksum is a CRC-32 of the top ten levels)
trade a batch, oldest first; the first after a subscription is recent history (snapshot: true)
candle the bar in progress or a new bar
status per venue: connected, reconnecting, stale, down, idle
heartbeat, pong, dropped, unsubscribed, error housekeeping; an error never closes the connection

Close 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).

Order and position updates are not on the stream: use the order.updated webhook, or poll GET /orders/{id} (waitForOrder / wait_for_order).

# Operations

Method Path Operation Permission Idempotency-Key
GET /api/v1/trading/openapi.json getOpenApi — This document any valid key —
GET /api/v1/trading/markets listMarkets — Instruments across venues (perpetuals) and the spot market-data symbols markets:read —
GET /api/v1/trading/markets/compare compareMarkets — Compare the estimated cost of one position across venues markets:read —
GET /api/v1/trading/markets/{symbol} getMarket — One market: instrument, ticker and data quality markets:read —
GET /api/v1/trading/markets/{symbol}/orderbook getOrderbook — Order book of one market markets:read —
GET /api/v1/trading/markets/{symbol}/candles getCandles — Closed bars of one market markets:read —
GET /api/v1/trading/private-markets listPrivateMarkets — Synthetic contracts on private companies, venue by venue, with sourced valuations markets:read —
GET /api/v1/trading/private-markets/companies/{slug} getPrivateMarketCompany — Every contract on one private company, side by side (never merged) markets:read —
GET /api/v1/trading/private-markets/{id} getPrivateMarket — One private-company contract: definition, valuation breakdown, candles, top of book markets:read —
GET /api/v1/trading/portfolio getPortfolio — Wallet value and derivative accounts, per mode wallet:read —
GET /api/v1/trading/balances getBalances — On-chain balances of the wallet wallet:read —
GET /api/v1/trading/activity getActivity — Wallet activity and fills, newest first wallet:read —
GET /api/v1/trading/nfts listNfts — NFTs of the wallet (what the chain confirmed as held) wallet:read —
GET /api/v1/trading/nfts/item getNft — One NFT of the wallet: identity, ownership, creator metadata, sources wallet:read —
GET /api/v1/trading/nfts/activity getNftActivity — On-chain events of one NFT of the wallet wallet:read —
GET /api/v1/trading/nfts/market getNftMarket — Market data of any NFT, one row per source markets:read —
GET /api/v1/trading/nfts/market/events getNftMarketEvents — Market events of any NFT (sales, listings, offers), per source markets:read —
GET /api/v1/trading/positions listPositions — Open positions, paper and live separated by mode positions:read —
GET /api/v1/trading/orders listOrders — Orders, newest first orders:read —
POST /api/v1/trading/orders placeOrder — Place an order orders:execute + mandate required
GET /api/v1/trading/orders/{id} getOrder — One order and its fills orders:read —
DELETE /api/v1/trading/orders/{id} cancelOrder — Cancel an order orders:cancel required
GET /api/v1/trading/strategies listStrategies — Strategy library and the versions pinned to agents strategies:read —
POST /api/v1/trading/strategies createStrategy — Register a library strategy version on an agent strategies:manage required
GET /api/v1/trading/agents listAgents — Trading agents agents:read —
POST /api/v1/trading/agents createAgent — Create an agent (from a template, or a perp agent) agents:manage required
GET /api/v1/trading/risk getRisk — Risk state: kill switch, signer limits, capability locks, account policies positions:read —
POST /api/v1/trading/orders/preview previewOrder — Preview an order: every check it would meet, and an estimate orders:prepare —
POST /api/v1/trading/positions/{id}/close closePosition — Close a position positions:manage + mandate required
POST /api/v1/trading/positions/{id}/reduce reducePosition — Reduce a position positions:manage + mandate required
POST /api/v1/trading/commands runCommand — Run one line of the trading command grammar orders:prepare required
POST /api/v1/trading/risk/kill-switch engageKillSwitch — Engage the global kill switch positions:manage —
POST /api/v1/trading/strategies/{id}/backtest backtestStrategy — Run the backtest of a strategy version (asynchronous job) strategies:manage required
POST /api/v1/trading/strategies/{id}/start startStrategy — Start the agent a strategy version is pinned to strategies:manage required
POST /api/v1/trading/strategies/{id}/stop stopStrategy — Stop the agent a strategy version is pinned to strategies:manage required
GET /api/v1/trading/agents/templates listAgentTemplates — The seven built-in agents: family, engine, modes, installed strategies agents:read —
GET /api/v1/trading/agents/{id} getAgent — One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state agents:read —
GET /api/v1/trading/agents/{id}/signals listAgentSignals — Signal history of one agent, ONE mode agents:read —
GET /api/v1/trading/agents/{id}/journal listAgentJournal — Activity journal of one agent, ONE mode agents:read —
GET /api/v1/trading/agents/{id}/orders listAgentOrders — Order history of one agent, ONE mode, in the unified order states agents:read —
GET /api/v1/trading/agents/{id}/performance getAgentPerformance — Computed performance of one agent, ONE mode agents:read —
GET /api/v1/trading/jobs/{id} getJob — One agent job (backtest, wind-down): status and result agents:read —
POST /api/v1/trading/agents/{id}/start startAgent — Start an agent in research, paper or live mode agents:manage required
POST /api/v1/trading/agents/{id}/pause pauseAgent — Pause an agent agents:manage required
POST /api/v1/trading/agents/{id}/stop stopAgent — Stop an agent (always allowed) agents:manage required
POST /api/v1/trading/agents/{id}/backtest backtestAgent — Run a backtest for an agent (asynchronous job) agents:manage required

# Meta

The contract itself.

# GET /api/v1/trading/openapi.json

This document. Operation id getOpenApi.

  • Permission: any valid key
  • Idempotency-Key: not used
  • Side effects: none (a read)

OpenAPI 3.1 document generated from the route schemas. Any valid key or the owner session.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/openapi.json" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const doc = await client.openapi();
python
doc = client.openapi()

Example response — 200, written from the schema (not recorded). Cut: the real document describes every operation, schema and error code.

json
{
  "openapi": "3.1.0",
  "info": {
    "title": "SP Trading API",
    "version": "1.0.0"
  },
  "paths": {
    "/api/v1/trading/markets": {
      "get": {
        "operationId": "listMarkets"
      }
    }
  }
}
Response fields
Field Type Required Description
openapi string yes

Errors

Status Codes
401 unauthenticated
403 ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# Markets

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

# GET /api/v1/trading/markets

Instruments across venues (perpetuals) and the spot market-data symbols. Operation id listMarkets.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Each 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.

Parameters

Name In Type Required Description
venue query string — venue id: hyperliquid, gmx, dydx, spot — 0–40 characters
kind query "perpetual" | "spot" — perpetual = a venue instrument; spot = a market-data symbol
q query string — case-insensitive match on id, symbol or base — 0–40 characters
limit query integer 1…5000 — rows returned at most; total and truncated say when it cut the list — default 2000

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });
python
markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).markets

Example response — 200, recorded from a real server

json
{
  "markets": [
    {
      "id": "hyperliquid:BTC",
      "venue": "hyperliquid",
      "kind": "perpetual",
      "symbol": "BTC",
      "base": "BTC",
      "quote": "USD",
      "status": "active",
      "mark": "64432",
      "index": "64460.7",
      "funding": "0.0000089721",
      "fundingIntervalSec": 3600,
      "volume24h": "3621656019.2002997398",
      "openInterest": "37680.57528",
      "maxLeverage": "40",
      "tickSize": "0.1",
      "lotSize": "0.00001",
      "collateral": "USDC",
      "restriction": null,
      "ts": 1794953721101,
      "stale": false,
      "source": "venue"
    }
  ],
  "total": 1,
  "truncated": false,
  "errors": [],
  "ts": 1794953721103
}
Response fields
Field Type Required Description
markets array of object yes
markets[].id string yes
markets[].venue string yes
markets[].kind "perpetual" | "spot" yes
markets[].symbol string yes
markets[].base string yes
markets[].quote string yes
markets[].status string yes
markets[].mark string | null yes
markets[].ts integer -9007199254740991…9007199254740991 | null yes time the source produced this row (venue read time, or the last consolidated bar for spot)
markets[].stale boolean yes true when the row is older than its freshness bound or the source could not be refreshed
total integer -9007199254740991…9007199254740991 yes rows matching the filters, before limit
truncated boolean yes
errors array of object yes
errors[].source string yes
errors[].message string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_venue
429 auth_throttled, rate_limited
500 internal
503 markets_unavailable, venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/markets/compare

Compare the estimated cost of one position across venues. Operation id compareMarkets.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

One 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.

Parameters

Name In Type Required Description
underlying query string — common underlying, e.g. BTC (see GET /markets-hub/underlyings) — default "BTC" · pattern [1]{1,15}$
side query "long" | "short" — direction of the position compared — default "long"
notional query string — position notional in USD (not the collateral) — default "1000" · pattern ^(0|[1-9]\d{0,11})(.\d{1,8})?$
leverage query string — leverage of the position: collateral = notional / leverage — default "1" · pattern ^(0|[1-9]\d{0,11})(.\d{1,8})?$
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})?$
liquidity query "taker" | "maker" — how the entry and the exit are executed, for the fee — default "taker"
minNetEdgeBps query string — a discrepancy estimate above this is flagged — default "0" · pattern ^(0|[1-9]\d{0,4})(.\d{1,4})?$

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/compare?underlying=BTC&side=long&notional=1000&leverage=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const cmp = await client.compareMarkets({ underlying: 'BTC', side: 'long', notional: '1000', leverage: '2' });
python
cmp = client.compare_markets(underlying="BTC", side="long", notional="1000", leverage="2")

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.

json
{
  "underlying": "BTC",
  "category": "crypto",
  "request": {
    "underlying": "BTC",
    "side": "long",
    "notionalUsd": "1000",
    "leverage": "2",
    "horizonHours": "24",
    "liquidity": "taker",
    "minNetEdgeBps": "0",
    "depthBps": [
      "10"
    ]
  },
  "rows": [
    {
      "venue": "hyperliquid",
      "venueName": "Hyperliquid",
      "instrument": "hyperliquid:BTC",
      "symbol": "BTC",
      "underlying": "BTC",
      "multiplier": "1",
      "alternatives": [],
      "tradable": true,
      "tradableReason": null,
      "restriction": null,
      "priceOutlier": false,
      "staleAfterMs": 15000,
      "price": {
        "mark": "64432",
        "index": "64460.7",
        "mid": "64432.5"
      },
      "depth": [
        {
          "bps": "10",
          "bidUsd": "6193729.75994",
          "askUsd": "9895537.37818",
          "bidComplete": false,
          "askComplete": false
        }
      ],
      "depthReason": null,
      "fees": {
        "takerRate": "0.00045",
        "makerRate": "0.00015",
        "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…",
        "asOf": "2026-11-10"
      },
      "funding": {
        "rate": "0.0000089721",
        "intervalSec": 3600,
        "perHour": "0.0000089721",
        "annualised": "0.0785956",
        "assumption": "the venue's current rate held constant over the horizon; funding rates change every interval"
      },
      "maintenance": {
        "fraction": "0.0125",
        "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…"
      },
      "cost": {
        "venue": "hyperliquid",
        "instrument": "hyperliquid:BTC",
        "executionModel": "order_book",
        "midPrice": {
          "value": "64432.5",
          "reason": null,
          "basis": "(best bid + best ask) / 2"
        },
        "spreadBps": {
          "value": "0.1552",
          "reason": null,
          "basis": "(best ask − best bid) / mid"
        },
        "depthBidUsd": {
          "value": "6193729.75994",
          "reason": null,
          "basis": "Σ price × size of the bids within 10 bps of the mid, in the supplied book"
        },
        "depthAskUsd": {
          "value": "9895537.37818",
          "reason": null,
          "basis": "Σ price × size of the asks within 10 bps of the mid, in the supplied book"
        },
        "sizeBase": {
          "value": "0.01552",
          "reason": null,
          "basis": "notional / mid, rounded down to the lot"
        },
        "entryAvgPrice": {
          "value": "64433",
          "reason": null,
          "basis": "average price of walking the book for the whole size"
        },
        "entrySlippageBps": {
          "value": "0.0776",
          "reason": null,
          "basis": "|average entry price − mid| / mid"
        },
        "entrySlippageUsd": {
          "value": "0.00776",
          "reason": null,
          "basis": "entry: average price of walking the book for the whole size vs the mid, half the spread included (router.walkBook)"
        },
        "exitSlippageUsd": {
          "value": "0.00776",
          "reason": null,
          "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)"
        },
        "entryFeeUsd": {
          "value": "0.449997",
          "reason": null,
          "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…"
        },
        "exitFeeUsd": {
          "value": "0.449997",
          "reason": null,
          "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…"
        },
        "fundingUsd": {
          "value": "0.215329",
          "reason": null,
          "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"
        },
        "fundingRatePerHour": {
          "value": "0.0000089721",
          "reason": null,
          "basis": "rate per 3600 s × 3600 / 3600"
        },
        "collateralRequiredUsd": {
          "value": "499.9962",
          "reason": null,
          "basis": "notional / leverage, rounded up (margin.initialMargin)"
        },
        "liquidationPrice": {
          "value": "32624.3037974684",
          "reason": null,
          "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"
        },
        "liquidationDistanceBps": {
          "value": "4936.7089",
          "reason": null,
          "basis": "|entry − liquidation price| / entry"
        },
        "maxLeverage": {
          "value": "40",
          "reason": null,
          "basis": "the venue's maximum for the instrument"
        },
        "totalCostUsd": {
          "value": "1.130843",
          "reason": null,
          "basis": "sum of entrySlippageUsd + exitSlippageUsd + entryFeeUsd + exitFeeUsd + fundingUsd"
        },
        "totalCostBps": {
          "value": "11.3085",
          "reason": null,
          "basis": "total cost / position notional"
        },
        "missing": [],
        "assumptions": [
          "the position is opened and closed in full, each in one order"
        ]
      },
      "sourceTs": {
        "ticker": 1794953721101,
        "book": 1794953722689,
        "pool": null
      },
      "ageMs": 1936,
      "stale": false,
      "error": null
    }
  ],
  "discrepancies": [
    {
      "longVenue": "edgex",
      "shortVenue": "hyperliquid",
      "longInstrument": "edgex:BTCUSDC",
      "shortInstrument": "hyperliquid:BTC",
      "grossGapBps": "8.6212",
      "netEdgeEstimateBps": "-10.379",
      "costsUsd": {
        "feesUsd": "1.738914",
        "exitSlippageUsd": "0.01425",
        "fundingUsd": "0.081578"
      },
      "flagged": false,
      "reason": null,
      "actionableFromWallet": false,
      "assumptions": [
        {
          "code": "disc_assume_1",
          "text": "both legs are opened at the same time, in full, at the average prices of walking the two CURRENT books"
        }
      ],
      "risks": [
        {
          "code": "disc_risk_1",
          "text": "execution risk: one leg can fill and the other not, or at a worse price; the books move between the two orders"
        }
      ]
    }
  ],
  "texts": {
    "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).",
    "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 …",
    "assumptions": [
      {
        "code": "cost_1",
        "text": "the position is opened and closed in full, each in one order"
      }
    ]
  },
  "warnings": [],
  "errors": [],
  "locks": [
    {
      "id": "deriv_live_mainnet",
      "on": false
    }
  ],
  "ts": 1794953723037,
  "source": "estimate"
}
Response fields
Field Type Required Description
underlying string yes
category string | null yes
request object yes
rows array of object yes
rows[].venue string yes
rows[].instrument string yes
rows[].tradable boolean yes false: the wallet cannot trade this venue or instrument; the row is shown for information
rows[].tradableReason string | null yes
rows[].cost object | null yes itemised estimate: every component is { value, reason, basis } — value null WITH the reason when an input is missing
rows[].priceOutlier boolean yes
rows[].ageMs number | null yes
rows[].stale boolean yes
discrepancies array of object yes
discrepancies[].longVenue string yes
discrepancies[].shortVenue string yes
discrepancies[].netEdgeEstimateBps string | null yes an ESTIMATE under assumptions, with risks
discrepancies[].flagged boolean yes
discrepancies[].actionableFromWallet boolean yes
discrepancies[].assumptions array of object yes
discrepancies[].risks array of object yes
texts object yes
texts.disclaimer string yes
warnings array of string yes
errors array of object yes
errors[].source string yes
errors[].message string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
source string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_underlying
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/markets/{symbol}

One market: instrument, ticker and data quality. Operation id getMarket.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

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

Parameters

Name In Type Required Description
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

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { instrument, ticker } = await client.getMarket('hyperliquid:BTC');
python
market = client.get_market("hyperliquid:BTC")

Example response — 200, recorded from a real server

json
{
  "market": {
    "id": "hyperliquid:BTC",
    "venue": "hyperliquid",
    "kind": "perpetual",
    "symbol": "BTC",
    "base": "BTC",
    "quote": "USD",
    "status": "active",
    "mark": "64419",
    "ts": 1794953786018,
    "stale": false,
    "source": "venue"
  },
  "instrument": {
    "venue": "hyperliquid",
    "symbol": "BTC",
    "id": "hyperliquid:BTC",
    "base": "BTC",
    "quote": "USD",
    "kind": "perpetual",
    "collateral": "USDC",
    "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",
    "tickSize": "0.1",
    "lotSize": "0.00001",
    "minOrderSize": null,
    "minNotional": "10",
    "maxLeverage": "40",
    "marginModes": [
      "cross",
      "isolated"
    ],
    "fundingIntervalSec": 3600,
    "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…",
    "status": "active"
  },
  "ticker": {
    "instrument": "hyperliquid:BTC",
    "mark": "64419",
    "index": "64449.4",
    "mid": "64418.5",
    "funding": "0.0000087881",
    "openInterest": "37684.5631",
    "volume24h": "3622010181.9303812981",
    "change24h": "-0.015692",
    "ts": 1794953786018,
    "source": "venue"
  },
  "quality": null,
  "liquidity": null,
  "hasOrderBook": true,
  "errors": {},
  "ts": 1794953786422,
  "source": "venue"
}
Response fields
Field Type Required Description
market object yes
market.id string yes
market.venue string yes
market.kind "perpetual" | "spot" yes
market.symbol string yes
market.base string yes
market.quote string yes
market.status string yes
market.mark string | null yes
market.ts integer -9007199254740991…9007199254740991 | null yes time the source produced this row (venue read time, or the last consolidated bar for spot)
market.stale boolean yes true when the row is older than its freshness bound or the source could not be refreshed
instrument object | null yes null for a spot market-data symbol
instrument.id string yes venue:symbol
instrument.venue string yes
instrument.symbol string yes
instrument.base string yes
instrument.quote string yes
instrument.kind "perpetual" yes
instrument.collateral string yes
instrument.settlement string yes
instrument.tickSize string yes price increment: a limit or trigger price is a multiple of it
instrument.lotSize string yes size increment: an order size is a multiple of it
instrument.minOrderSize string | null yes smallest order size, base units; null when the venue states none
instrument.minNotional string | null yes smallest order value, quote currency; null when the venue states none
instrument.maxLeverage string yes decimal number as a string (never a float)
instrument.marginModes array of "cross" | "isolated" yes
instrument.fundingIntervalSec integer -9007199254740991…9007199254740991 yes
instrument.markPriceMethod string yes
instrument.status "active" | "reduce_only" | "halted" yes
instrument.category "crypto" | "equity" | "pre_ipo" | "commodity" | "fx" — what the underlying is, when the venue's own metadata says it
ticker object | null yes
ticker.instrument string yes
ticker.mark string yes decimal number as a string (never a float)
ticker.index string | null yes
ticker.mid string | null yes
ticker.funding string | null yes per funding interval
ticker.openInterest string | null yes
ticker.volume24h string | null yes
ticker.change24h string | null yes
ticker.ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
quality object | null yes spot only: data quality per interval
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
source string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_instrument, unknown_market, unknown_venue
409 ambiguous_symbol
422 venue_rejected
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/markets/{symbol}/orderbook

Order book of one market. Operation id getOrderbook.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Venues without an order book (GMX, spot data) answer 422 no_orderbook.

Parameters

Name In Type Required Description
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
depth query integer 1…50 — price levels per side — default 20

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/orderbook?depth=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const book = await client.getOrderbook('hyperliquid:BTC', { depth: 3 });
python
book = client.get_orderbook("hyperliquid:BTC", depth=3)

Example response — 200, recorded from a real server

json
{
  "id": "hyperliquid:BTC",
  "bids": [
    [
      "64432",
      "0.43796"
    ],
    [
      "64431",
      "0.00036"
    ],
    [
      "64426",
      "0.0015"
    ]
  ],
  "asks": [
    [
      "64433",
      "27.19556"
    ],
    [
      "64434",
      "2.14586"
    ],
    [
      "64435",
      "10.15654"
    ]
  ],
  "ts": 1794953722689,
  "stale": false,
  "source": "venue"
}
Response fields
Field Type Required Description
id string yes
bids array of [string, string] yes
asks array of [string, string] yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
stale boolean yes
source string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_instrument, unknown_market, unknown_venue
409 ambiguous_symbol
422 no_orderbook, venue_rejected
429 auth_throttled, rate_limited
500 internal
503 stale_data, venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/markets/{symbol}/candles

Closed bars of one market. Operation id getCandles.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Spot market data has fewer intervals than the venues: an interval it does not store answers 422 unsupported_interval.

Parameters

Name In Type Required Description
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
interval query "1m" | "5m" | "15m" | "1h" | "4h" | "1d" — bar length — default "1h"
limit query integer 1…1000 — most recent closed bars, oldest first in the answer — default 200

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/candles?interval=1h&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { candles } = await client.getCandles('hyperliquid:BTC', { interval: '1h', limit: 3 });
python
candles = client.get_candles("hyperliquid:BTC", interval="1h", limit=3).candles

Example response — 200, recorded from a real server

json
{
  "id": "hyperliquid:BTC",
  "interval": "1h",
  "candles": [
    {
      "ts": 1794945600000,
      "open": "63727",
      "high": "64075",
      "low": "63666",
      "close": "63964",
      "volume": "1914.97454"
    },
    {
      "ts": 1794949200000,
      "open": "63964",
      "high": "64645",
      "low": "63925",
      "close": "64331",
      "volume": "3580.64025"
    }
  ],
  "ts": 1794953723670,
  "stale": false,
  "source": "venue"
}
Response fields
Field Type Required Description
id string yes
interval string yes
candles array of object yes
candles[].ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
candles[].open string yes decimal number as a string (never a float)
candles[].high string yes decimal number as a string (never a float)
candles[].low string yes decimal number as a string (never a float)
candles[].close string yes decimal number as a string (never a float)
candles[].volume string yes decimal number as a string (never a float)
ts integer -9007199254740991…9007199254740991 | null yes
stale boolean yes
source string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_instrument, unknown_market, unknown_venue
409 ambiguous_symbol
422 unsupported_interval, venue_rejected
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/private-markets

Synthetic contracts on private companies, venue by venue, with sourced valuations. Operation id listPrivateMarkets.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Live 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.

Parameters

Name In Type Required Description
delisted query "true" | "false" — true: only delisted markets (frozen prices)
size query string — hypothetical position size, contracts (default 1) — pattern ^(0|[1-9]\d{0,11})(.\d{1,8})?$
side query "long" | "short" — side of the hypothetical position (default long)

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { markets, companies } = await client.listPrivateMarkets();
python
private = client.list_private_markets()

Example response — 200, recorded from a real server. Cut to one market. Display only: tradable is always false.

json
{
  "markets": [
    {
      "id": "hyperliquid:io:ANTH",
      "venue": "hyperliquid",
      "platform": "Hyperliquid · EntropyIO (dex io)",
      "operator": "EntropyIO",
      "symbol": "io:ANTH",
      "company": {
        "slug": "anthropic",
        "name": "Anthropic, PBC"
      },
      "status": "live",
      "review": {
        "state": "reviewed",
        "reasons": [],
        "reviewedAt": "2026-11-15",
        "validUntil": "2026-11-18T00:00:00Z",
        "fingerprintChecked": true
      },
      "contract": {
        "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",
        "unit": {
          "kind": "valuation_usd_billions",
          "label": "USD billions of fully diluted company valuation (1.00 = $1B)"
        },
        "quoteCurrency": "USD",
        "collateral": "USDC",
        "underlying": "Anthropic, PBC",
        "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",
        "multiplier": {
          "value": "1",
          "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)"
        },
        "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.",
        "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…",
        "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…",
        "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); …",
        "maxLeverage": "15",
        "margin": "cross_allowed",
        "lotSize": "0.001",
        "szDecimals": 3,
        "fundingIntervalSec": 3600,
        "assetId": 200001,
        "dex": "io",
        "oiCapUsd": "275000000",
        "fundingMultiplier": "0.125",
        "onChainDescription": "",
        "unconfirmedConvention": null,
        "sources": [
          "https://docs.entropy.io/market-types/pre-ipo-perpetuals"
        ]
      },
      "market": {
        "price": {
          "value": "1683.9",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
          "ts": 1794953724740,
          "stale": false
        },
        "oracle": {
          "value": "1684",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",
          "ts": 1794953724740,
          "stale": false
        },
        "mid": {
          "value": "1680.6",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",
          "ts": 1794953724740,
          "stale": false
        },
        "funding": {
          "value": "-0.0000113686",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",
          "ts": 1794953724740,
          "stale": false,
          "intervalSec": 3600
        },
        "openInterest": {
          "value": "117475.832",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",
          "ts": 1794953724740,
          "stale": false
        },
        "openInterestUsd": {
          "value": "197817553.5048",
          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",
          "ts": 1794953724740,
          "stale": false
        },
        "volume24h": {
          "value": "34445966.2849999964",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",
          "ts": 1794953724740,
          "stale": false
        },
        "volumeBase24h": {
          "value": "20388.063",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",
          "ts": 1794953724740,
          "stale": false
        },
        "frozen": false
      },
      "valuation": {
        "syntheticPrice": {
          "value": "1683.9",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
          "ts": 1794953724740,
          "stale": false,
          "unit": "valuation_usd_billions",
          "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",
          "priceKind": "mark"
        },
        "contractMarketValue": {
          "value": "1683.9",
          "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…",
          "reason": null,
          "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)",
          "ts": 1794953724740
        },
        "notionalExposure": {
          "value": "1683.9",
          "formula": "size × contract value, negative for a short",
          "reason": null,
          "position": {
            "side": "long",
            "size": "1"
          },
          "hypothetical": true,
          "ts": 1794953724740
        },
        "impliedValuation": {
          "value": "1683900000000",
          "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",
          "formulaId": "price_x_1e9",
          "formulaSource": {
            "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",
            "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",
            "readAt": "2026-11-15"
          },
          "asOf": 1794953724740,
          "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",
          "reason": null,
          "reasonCode": null
        },
        "lastPrivateValuation": {
          "value": "965000000000",
          "kind": "primary_round",
          "detail": "Series H, $65B raised, post-money",
          "date": "2026-05-28",
          "sourceUrl": "https://www.anthropic.com/news/series-h",
          "confidence": "high"
        },
        "lastPrivateValuationReason": null,
        "premiumDiscount": {
          "premiumBps": "7449.7409",
          "reason": null,
          "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"
        },
        "caveats": [
          {
            "code": "synthetic",
            "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"
          }
        ]
      },
      "tradable": false,
      "notTradable": {
        "code": "builder_dex_read_only",
        "reasons": [
          "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),…"
        ]
      },
      "error": null
    }
  ],
  "companies": [
    {
      "slug": "anthropic",
      "name": "Anthropic, PBC",
      "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.",
      "contracts": [
        "hyperliquid:io:ANTH"
      ],
      "lastPrivateValuation": {
        "value": "965000000000",
        "kind": "primary_round",
        "detail": "Series H, $65B raised, post-money",
        "date": "2026-05-28",
        "sourceUrl": "https://www.anthropic.com/news/series-h",
        "confidence": "high"
      },
      "divergence": [
        {
          "unit": "usd_per_share",
          "unitLabel": "USD per 1 share (share class not specified by the operator)",
          "contracts": [
            {
              "id": "hyperliquid:para:ANTH",
              "price": "96.26",
              "ts": 1794953724843
            }
          ],
          "spreadBps": "7.58",
          "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"
        }
      ]
    }
  ],
  "excluded": [
    {
      "id": "hyperliquid:xyz:SPCX",
      "company": "SpaceX",
      "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.",
      "liveCategory": "stocks",
      "delisted": false
    }
  ],
  "venues": [
    {
      "venue": "hyperliquid",
      "name": "Hyperliquid (builder-deployed dexes)",
      "status": "ok",
      "error": null,
      "ts": 1794953723863,
      "instruments": 5
    }
  ],
  "venuesWithoutAdapter": [
    {
      "venue": "Aster",
      "note": "ANTHROPICUSDT, OPENAIUSDT, POLYMARKETUSD1, OURAUSD1, MOONSHOTUSD1 — per share against a notional reference count of 1 billion shares"
    }
  ],
  "notice": {
    "tradable": false,
    "code": "private_markets_display_only",
    "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…"
  },
  "filter": {
    "delisted": false
  },
  "position": {
    "side": "long",
    "size": "1"
  },
  "cache": {
    "discovery": {
      "ttl": 60000,
      "maxAge": 900000
    },
    "markets": {
      "ttl": 20000,
      "maxAge": 120000
    },
    "delisted": {
      "ttl": 600000,
      "maxAge": 3600000
    },
    "annotation": {
      "ttl": 600000,
      "maxAge": 3600000
    },
    "book": {
      "ttl": 5000,
      "maxAge": 30000
    },
    "candles": {
      "ttl": 60000,
      "maxAge": 600000
    },
    "edgexTickers": {
      "ttl": 3000,
      "maxAge": 15000
    },
    "edgexInstruments": {
      "ttl": 600000,
      "maxAge": 3600000
    },
    "staleAfter": {
      "hyperliquid": 60000,
      "edgex": 15000
    }
  },
  "reviewedTable": {
    "entries": 10,
    "reviewedAt": "2026-11-15"
  },
  "ts": 1794953725186,
  "source": "venue"
}
Response fields
Field Type Required Description
markets array of object yes
markets[].id string yes
markets[].venue string yes
markets[].platform string yes
markets[].symbol string yes
markets[].company object | null yes
markets[].status "live" | "delisted" | "halted" | "reduce_only" yes
markets[].review object yes
markets[].contract object yes
markets[].market object yes
markets[].valuation object yes
markets[].tradable false yes
markets[].notTradable object yes
markets[].error string | null yes
companies array of object yes
companies[].slug string yes
companies[].name string yes
companies[].contracts array of string yes
excluded array of object yes
excluded[].id string yes
excluded[].reason string yes
venues array of object yes
venues[].venue string yes
venues[].status "ok" | "stale" | "error" yes
venues[].error string | null yes
notice object yes
notice.tradable false yes
notice.code string yes
notice.text string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/private-markets/companies/{slug}

Every contract on one private company, side by side (never merged). Operation id getPrivateMarketCompany.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

The 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.

Parameters

Name In Type Required Description
slug path string yes company slug, from GET /private-markets (companies[].slug), e.g. anthropic — pattern [2]{1,40}$
size query string — hypothetical position size, contracts (default 1) — pattern ^(0|[1-9]\d{0,11})(.\d{1,8})?$
side query "long" | "short" — side of the hypothetical position (default long)
interval query "1h" | "1d" — candle length
limit query integer 1…500 — candles returned at most

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets/companies/anthropic" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const company = await client.getPrivateMarketCompany('anthropic');
python
company = client.get_private_market_company("anthropic")

Example response — 200, recorded from a real server. Cut to one contract.

json
{
  "company": {
    "slug": "anthropic",
    "name": "Anthropic, PBC",
    "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."
  },
  "contracts": [
    {
      "id": "hyperliquid:io:ANTH",
      "venue": "hyperliquid",
      "platform": "Hyperliquid · EntropyIO (dex io)",
      "operator": "EntropyIO",
      "symbol": "io:ANTH",
      "company": {
        "slug": "anthropic",
        "name": "Anthropic, PBC"
      },
      "status": "live",
      "review": {
        "state": "reviewed",
        "reasons": [],
        "reviewedAt": "2026-11-15",
        "validUntil": "2026-11-18T00:00:00Z",
        "fingerprintChecked": true
      },
      "contract": {
        "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",
        "unit": {
          "kind": "valuation_usd_billions",
          "label": "USD billions of fully diluted company valuation (1.00 = $1B)"
        },
        "quoteCurrency": "USD",
        "collateral": "USDC",
        "underlying": "Anthropic, PBC",
        "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",
        "multiplier": {
          "value": "1",
          "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)"
        },
        "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.",
        "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…",
        "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…",
        "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); …",
        "maxLeverage": "15",
        "margin": "cross_allowed",
        "lotSize": "0.001",
        "szDecimals": 3,
        "fundingIntervalSec": 3600,
        "assetId": 200001,
        "dex": "io",
        "oiCapUsd": "275000000",
        "fundingMultiplier": "0.125",
        "onChainDescription": "",
        "unconfirmedConvention": null,
        "sources": [
          "https://docs.entropy.io/market-types/pre-ipo-perpetuals"
        ]
      },
      "market": {
        "price": {
          "value": "1683.9",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
          "ts": 1794953724740,
          "stale": false
        },
        "oracle": {
          "value": "1684",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",
          "ts": 1794953724740,
          "stale": false
        },
        "mid": {
          "value": "1680.6",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",
          "ts": 1794953724740,
          "stale": false
        },
        "funding": {
          "value": "-0.0000113686",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",
          "ts": 1794953724740,
          "stale": false,
          "intervalSec": 3600
        },
        "openInterest": {
          "value": "117475.832",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",
          "ts": 1794953724740,
          "stale": false
        },
        "openInterestUsd": {
          "value": "197817553.5048",
          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",
          "ts": 1794953724740,
          "stale": false
        },
        "volume24h": {
          "value": "34445966.2849999964",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",
          "ts": 1794953724740,
          "stale": false
        },
        "volumeBase24h": {
          "value": "20388.063",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",
          "ts": 1794953724740,
          "stale": false
        },
        "frozen": false
      },
      "valuation": {
        "syntheticPrice": {
          "value": "1683.9",
          "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
          "ts": 1794953724740,
          "stale": false,
          "unit": "valuation_usd_billions",
          "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",
          "priceKind": "mark"
        },
        "contractMarketValue": {
          "value": "1683.9",
          "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…",
          "reason": null,
          "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)",
          "ts": 1794953724740
        },
        "notionalExposure": {
          "value": "1683.9",
          "formula": "size × contract value, negative for a short",
          "reason": null,
          "position": {
            "side": "long",
            "size": "1"
          },
          "hypothetical": true,
          "ts": 1794953724740
        },
        "impliedValuation": {
          "value": "1683900000000",
          "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",
          "formulaId": "price_x_1e9",
          "formulaSource": {
            "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",
            "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",
            "readAt": "2026-11-15"
          },
          "asOf": 1794953724740,
          "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",
          "reason": null,
          "reasonCode": null
        },
        "lastPrivateValuation": {
          "value": "965000000000",
          "kind": "primary_round",
          "detail": "Series H, $65B raised, post-money",
          "date": "2026-05-28",
          "sourceUrl": "https://www.anthropic.com/news/series-h",
          "confidence": "high"
        },
        "lastPrivateValuationReason": null,
        "premiumDiscount": {
          "premiumBps": "7449.7409",
          "reason": null,
          "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"
        },
        "caveats": [
          {
            "code": "synthetic",
            "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"
          }
        ]
      },
      "tradable": false,
      "notTradable": {
        "code": "builder_dex_read_only",
        "reasons": [
          "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),…"
        ]
      },
      "error": null
    }
  ],
  "delisted": [
    {
      "id": "hyperliquid:vntl:ANTHROPIC",
      "venue": "hyperliquid",
      "platform": "Hyperliquid · Ventuals (dex vntl) — shut down",
      "operator": "Ventuals",
      "symbol": "vntl:ANTHROPIC",
      "company": {
        "slug": "anthropic",
        "name": "Anthropic, PBC"
      },
      "status": "delisted",
      "review": {
        "state": "reviewed",
        "reasons": [],
        "reviewedAt": "2026-11-15",
        "validUntil": null,
        "fingerprintChecked": true
      },
      "contract": {
        "nature": "cash-settled perpetual, pure synthetic — DELISTED: Ventuals shut down on 15 Jun 2026 and its markets were settled",
        "unit": {
          "kind": "valuation_usd_billions",
          "label": "USD billions of company valuation (historical)"
        },
        "quoteCurrency": "USD",
        "collateral": "USDH",
        "underlying": "Anthropic, PBC",
        "contractSize": "1 contract = 1 unit of ANTHROPIC; smallest size 0.001",
        "multiplier": {
          "value": "1",
          "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)"
        },
        "settlement": "Settled at the 24 h mark TWAP 1618.90 on 15 Jun 2026 (Ventuals sunset guide).",
        "ipoConversion": "not applicable (settled)",
        "oracle": "Was 1/3 Notice price + 2/3 two-hour EMA of the mark (Ventuals documentation).",
        "liquidation": "not applicable (no open position can exist)",
        "maxLeverage": "3",
        "margin": "strict_isolated",
        "lotSize": "0.001",
        "szDecimals": 3,
        "fundingIntervalSec": 3600,
        "assetId": 130002,
        "dex": "vntl",
        "oiCapUsd": "10000000",
        "fundingMultiplier": "0",
        "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.",
        "unconfirmedConvention": null,
        "sources": [
          "https://docs.ventuals.com/perp-specifications/private-companies"
        ]
      },
      "market": {
        "price": {
          "value": "1619.3",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",
          "ts": 1794953725593,
          "stale": false
        },
        "oracle": {
          "value": "1618.9",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — oracle price",
          "ts": 1794953725593,
          "stale": false
        },
        "mid": {
          "value": null,
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — book mid",
          "ts": null,
          "stale": false
        },
        "funding": {
          "value": "0",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — funding rate per interval",
          "ts": 1794953725593,
          "stale": false,
          "intervalSec": 3600
        },
        "openInterest": {
          "value": "0",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — open interest, contracts",
          "ts": 1794953725593,
          "stale": false
        },
        "openInterestUsd": {
          "value": "0",
          "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",
          "ts": 1794953725593,
          "stale": false
        },
        "volume24h": {
          "value": "0",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h notional volume, USD",
          "ts": 1794953725593,
          "stale": false
        },
        "volumeBase24h": {
          "value": "0",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h volume, contracts",
          "ts": 1794953725593,
          "stale": false
        },
        "frozen": true
      },
      "valuation": {
        "syntheticPrice": {
          "value": "1619.3",
          "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",
          "ts": 1794953725593,
          "stale": false,
          "unit": "valuation_usd_billions",
          "unitLabel": "USD billions of company valuation (historical)",
          "priceKind": "frozen mark"
        },
        "contractMarketValue": {
          "value": null,
          "formula": null,
          "reason": "delisted market: the frozen price is not the value of a contract that can be held",
          "source": null,
          "ts": null
        },
        "notionalExposure": {
          "value": null,
          "formula": null,
          "reason": "delisted market: the frozen price is not the value of a contract that can be held",
          "position": {
            "side": "long",
            "size": "1"
          },
          "hypothetical": true,
          "ts": null
        },
        "impliedValuation": {
          "value": null,
          "formula": null,
          "formulaId": null,
          "formulaSource": {
            "url": "https://docs.ventuals.com/perp-specifications/private-companies",
            "quote": "The price of the perp contract is the company valuation divided by 1 billion.",
            "readAt": "2026-11-15"
          },
          "asOf": null,
          "label": null,
          "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",
          "reasonCode": "delisted_frozen"
        },
        "lastPrivateValuation": {
          "value": "965000000000",
          "kind": "primary_round",
          "detail": "Series H, $65B raised, post-money",
          "date": "2026-05-28",
          "sourceUrl": "https://www.anthropic.com/news/series-h",
          "confidence": "high"
        },
        "lastPrivateValuationReason": null,
        "premiumDiscount": {
          "premiumBps": null,
          "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",
          "caveat": null
        },
        "caveats": [
          {
            "code": "synthetic",
            "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"
          }
        ]
      },
      "tradable": false,
      "notTradable": {
        "code": "builder_dex_read_only",
        "reasons": [
          "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),…"
        ]
      },
      "error": null
    }
  ],
  "references": [
    {
      "company": "anthropic",
      "valueUsd": "965000000000",
      "kind": "primary_round",
      "detail": "Series H, $65B raised, post-money",
      "date": "2026-05-28",
      "sourceUrl": "https://www.anthropic.com/news/series-h",
      "confidence": "high",
      "postMoney": true
    }
  ],
  "lastPrivateValuation": {
    "value": "965000000000",
    "kind": "primary_round",
    "detail": "Series H, $65B raised, post-money",
    "date": "2026-05-28",
    "sourceUrl": "https://www.anthropic.com/news/series-h",
    "confidence": "high"
  },
  "divergence": [
    {
      "unit": "usd_per_share",
      "unitLabel": "USD per 1 share (share class not specified by the operator)",
      "contracts": [
        {
          "id": "hyperliquid:para:ANTH",
          "price": "96.26",
          "ts": 1794953724843
        }
      ],
      "spreadBps": "7.58",
      "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"
    }
  ],
  "merged": null,
  "mergedReason": "contracts of different venues are different instruments: no average, no blended price, no cross-fill",
  "venues": [
    {
      "venue": "hyperliquid",
      "name": "Hyperliquid (builder-deployed dexes)",
      "status": "ok",
      "error": null,
      "ts": 1794953723863,
      "instruments": 5
    }
  ],
  "notice": {
    "tradable": false,
    "code": "private_markets_display_only",
    "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…"
  },
  "position": {
    "side": "long",
    "size": "1"
  },
  "ts": 1794953725812,
  "source": "venue"
}
Response fields
Field Type Required Description
company object yes
company.slug string yes
company.name string yes
contracts array of object yes
contracts[].id string yes
contracts[].venue string yes
contracts[].platform string yes
contracts[].symbol string yes
contracts[].company object | null yes
contracts[].status "live" | "delisted" | "halted" | "reduce_only" yes
contracts[].review object yes
contracts[].contract object yes
contracts[].market object yes
contracts[].valuation object yes
contracts[].tradable false yes
contracts[].notTradable object yes
contracts[].error string | null yes
delisted array of object yes
delisted[].id string yes
delisted[].venue string yes
delisted[].platform string yes
delisted[].symbol string yes
delisted[].company object | null yes
delisted[].status "live" | "delisted" | "halted" | "reduce_only" yes
delisted[].review object yes
delisted[].contract object yes
delisted[].market object yes
delisted[].valuation object yes
delisted[].tradable false yes
delisted[].notTradable object yes
delisted[].error string | null yes
references array of object yes
merged null yes always null: venues are never merged
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
404 unknown_company
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/private-markets/{id}

One private-company contract: definition, valuation breakdown, candles, top of book. Operation id getPrivateMarket.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

One 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.

Parameters

Name In Type Required Description
id path string yes venue:symbol, e.g. hyperliquid:io:ANTH, edgex:ANTHROPICUSDC — 3–120 characters · pattern [3]+:[A-Za-z0-9:._-]+$
size query string — hypothetical position size, contracts (default 1) — pattern ^(0|[1-9]\d{0,11})(.\d{1,8})?$
side query "long" | "short" — side of the hypothetical position (default long)
interval query "1h" | "1d" — candle length
limit query integer 1…500 — candles returned at most

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets/hyperliquid:io:ANTH?interval=1d&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const pm = await client.getPrivateMarket('hyperliquid:io:ANTH', { interval: '1d', limit: 3 });
python
pm = client.get_private_market("hyperliquid:io:ANTH", interval="1d", limit=3)

Example response — 200, recorded from a real server

json
{
  "market": {
    "id": "hyperliquid:io:ANTH",
    "venue": "hyperliquid",
    "platform": "Hyperliquid · EntropyIO (dex io)",
    "operator": "EntropyIO",
    "symbol": "io:ANTH",
    "company": {
      "slug": "anthropic",
      "name": "Anthropic, PBC"
    },
    "status": "live",
    "review": {
      "state": "reviewed",
      "reasons": [],
      "reviewedAt": "2026-11-15",
      "validUntil": "2026-11-18T00:00:00Z",
      "fingerprintChecked": true
    },
    "contract": {
      "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",
      "unit": {
        "kind": "valuation_usd_billions",
        "label": "USD billions of fully diluted company valuation (1.00 = $1B)"
      },
      "quoteCurrency": "USD",
      "collateral": "USDC",
      "underlying": "Anthropic, PBC",
      "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",
      "multiplier": {
        "value": "1",
        "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)"
      },
      "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.",
      "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…",
      "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…",
      "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); …",
      "maxLeverage": "15",
      "margin": "cross_allowed",
      "lotSize": "0.001",
      "szDecimals": 3,
      "fundingIntervalSec": 3600,
      "assetId": 200001,
      "dex": "io",
      "oiCapUsd": "275000000",
      "fundingMultiplier": "0.125",
      "onChainDescription": "",
      "unconfirmedConvention": null,
      "sources": [
        "https://docs.entropy.io/market-types/pre-ipo-perpetuals"
      ]
    },
    "market": {
      "price": {
        "value": "1683.9",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
        "ts": 1794953724740,
        "stale": false
      },
      "oracle": {
        "value": "1684",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",
        "ts": 1794953724740,
        "stale": false
      },
      "mid": {
        "value": "1680.6",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",
        "ts": 1794953724740,
        "stale": false
      },
      "funding": {
        "value": "-0.0000113686",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",
        "ts": 1794953724740,
        "stale": false,
        "intervalSec": 3600
      },
      "openInterest": {
        "value": "117475.832",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",
        "ts": 1794953724740,
        "stale": false
      },
      "openInterestUsd": {
        "value": "197817553.5048",
        "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",
        "ts": 1794953724740,
        "stale": false
      },
      "volume24h": {
        "value": "34445966.2849999964",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",
        "ts": 1794953724740,
        "stale": false
      },
      "volumeBase24h": {
        "value": "20388.063",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",
        "ts": 1794953724740,
        "stale": false
      },
      "frozen": false
    },
    "valuation": {
      "syntheticPrice": {
        "value": "1683.9",
        "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",
        "ts": 1794953724740,
        "stale": false,
        "unit": "valuation_usd_billions",
        "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",
        "priceKind": "mark"
      },
      "contractMarketValue": {
        "value": "1683.9",
        "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…",
        "reason": null,
        "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)",
        "ts": 1794953724740
      },
      "notionalExposure": {
        "value": "1683.9",
        "formula": "size × contract value, negative for a short",
        "reason": null,
        "position": {
          "side": "long",
          "size": "1"
        },
        "hypothetical": true,
        "ts": 1794953724740
      },
      "impliedValuation": {
        "value": "1683900000000",
        "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",
        "formulaId": "price_x_1e9",
        "formulaSource": {
          "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",
          "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",
          "readAt": "2026-11-15"
        },
        "asOf": 1794953724740,
        "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",
        "reason": null,
        "reasonCode": null
      },
      "lastPrivateValuation": {
        "value": "965000000000",
        "kind": "primary_round",
        "detail": "Series H, $65B raised, post-money",
        "date": "2026-05-28",
        "sourceUrl": "https://www.anthropic.com/news/series-h",
        "confidence": "high"
      },
      "lastPrivateValuationReason": null,
      "premiumDiscount": {
        "premiumBps": "7449.7409",
        "reason": null,
        "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"
      },
      "caveats": [
        {
          "code": "synthetic",
          "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"
        }
      ]
    },
    "tradable": false,
    "notTradable": {
      "code": "builder_dex_read_only",
      "reasons": [
        "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),…"
      ]
    },
    "error": null
  },
  "book": {
    "bids": [
      [
        "1680.4"
      ],
      [
        "1680.2"
      ],
      [
        "1680.1"
      ]
    ],
    "asks": [
      [
        "1680.8"
      ],
      [
        "1681"
      ],
      [
        "1681.1"
      ]
    ],
    "ts": 1794953724827,
    "stale": false,
    "source": "Hyperliquid info l2Book"
  },
  "candles": {
    "interval": "1d",
    "candles": [
      {
        "ts": 1794700800000,
        "open": "1779.8",
        "high": "1785.7",
        "low": "1752.3",
        "close": "1777.2",
        "volume": "4532.974"
      }
    ],
    "ts": 1794953725389,
    "stale": false,
    "source": "Hyperliquid info candleSnapshot"
  },
  "references": [
    {
      "company": "anthropic",
      "valueUsd": "965000000000",
      "kind": "primary_round",
      "detail": "Series H, $65B raised, post-money",
      "date": "2026-05-28",
      "sourceUrl": "https://www.anthropic.com/news/series-h",
      "confidence": "high",
      "postMoney": true
    }
  ],
  "company": {
    "slug": "anthropic",
    "name": "Anthropic, PBC",
    "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.",
    "contracts": [
      "hyperliquid:io:ANTH"
    ],
    "lastPrivateValuation": {
      "value": "965000000000",
      "kind": "primary_round",
      "detail": "Series H, $65B raised, post-money",
      "date": "2026-05-28",
      "sourceUrl": "https://www.anthropic.com/news/series-h",
      "confidence": "high"
    },
    "divergence": [
      {
        "unit": "usd_per_share",
        "unitLabel": "USD per 1 share (share class not specified by the operator)",
        "contracts": [
          {
            "id": "hyperliquid:para:ANTH",
            "price": "96.26",
            "ts": 1794953724843
          }
        ],
        "spreadBps": "7.58",
        "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"
      }
    ]
  },
  "sameCompany": [
    {
      "id": "hyperliquid:para:ANTH",
      "platform": "Hyperliquid · Paragon (dex para)",
      "price": {
        "value": "96.26",
        "source": "Hyperliquid info metaAndAssetCtxs (dex para) — mark price",
        "ts": 1794953724843,
        "stale": false
      },
      "unit": {
        "kind": "usd_per_share",
        "label": "USD per 1 share (share class not specified by the operator)"
      },
      "review": "reviewed"
    }
  ],
  "notice": {
    "tradable": false,
    "code": "private_markets_display_only",
    "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…"
  },
  "position": {
    "side": "long",
    "size": "1"
  },
  "ts": 1794953725389,
  "source": "venue"
}
Response fields
Field Type Required Description
market object yes
market.id string yes
market.venue string yes
market.platform string yes
market.symbol string yes
market.company object | null yes
market.status "live" | "delisted" | "halted" | "reduce_only" yes
market.review object yes
market.contract object yes
market.market object yes
market.valuation object yes
market.tradable false yes
market.notTradable object yes
market.error string | null yes
book object yes
candles object yes
references array of object yes
references[].kind string yes
references[].date string yes
references[].sourceUrl string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_a_private_market, unknown_private_market
429 auth_throttled, rate_limited
500 internal
503 venue_rate_limited, venue_timeout, venue_unavailable

# Portfolio

What 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.

# GET /api/v1/trading/portfolio

Wallet value and derivative accounts, per mode. Operation id getPortfolio.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Wallet balances valued in USD, then every derivatives account with its mode. Every amount is a decimal string. Paper and live are never added together.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/portfolio" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const portfolio = await client.getPortfolio();
python
portfolio = client.get_portfolio()

Example response — 200, recorded from a real server. Cut to one balance. The test wallet is empty; totals are three separate figures, never summed.

json
{
  "asOf": "2026-11-17T22:15:27.274Z",
  "wallet": {
    "valueUsd": "0",
    "priced": 0,
    "unpriced": 0,
    "pricesAsOf": "2026-11-17T22:15:27.274Z",
    "balances": [
      {
        "network": "ethereum",
        "networkName": "Ethereum",
        "asset": "native",
        "symbol": "ETH",
        "name": "Ether",
        "decimals": 18,
        "amount": "0",
        "display": "0",
        "error": null,
        "valueUsd": "0",
        "priceSource": "coingecko",
        "priceAt": "2026-11-17T22:14:49.000Z",
        "priceDivergent": false,
        "priceDivergenceBps": null
      }
    ]
  },
  "accounts": [
    {
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "label": "SDK paper",
      "equity": "10000",
      "collateral": "10000",
      "error": null,
      "source": "paper"
    }
  ],
  "totals": {
    "walletUsd": "0",
    "liveVenueEquity": "0",
    "paperEquity": "10000",
    "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."
  },
  "halted": false,
  "errors": []
}
Response fields
Field Type Required Description
asOf string yes
wallet object yes
wallet.valueUsd string | null yes USD, a decimal string; null when the price feed is unavailable
wallet.priced integer -9007199254740991…9007199254740991 yes
wallet.unpriced integer -9007199254740991…9007199254740991 yes
wallet.pricesAsOf string | null yes
wallet.balances array of object yes
accounts array of object yes
accounts[].mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
accounts[].venue string yes
accounts[].accountId string yes
accounts[].equity string | null yes
accounts[].error string | null yes
totals object yes three separate figures; there is no sum across modes
totals.walletUsd string | null yes
totals.liveVenueEquity string | null yes
totals.paperEquity string | null yes
totals.note string yes what the three figures are, in a sentence
halted boolean | null yes emergency halt of the signer; null when the signer does not say
errors array of object yes
errors[].source string yes
errors[].message string yes

Errors

Status Codes
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal
503 service_unavailable, signer_unreachable

# GET /api/v1/trading/balances

On-chain balances of the wallet. Operation id getBalances.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

One 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.

Parameters

Name In Type Required Description
network query string — one network id (e.g. base, arbitrum, solana); default: every network of the wallet — 0–24 characters

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/balances?network=base" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { balances } = await client.getBalances({ network: 'base' });
python
balances = client.get_balances(network="base").balances

Example response — 200, recorded from a real server

json
{
  "asOf": "2026-11-17T22:15:28.199Z",
  "balances": [
    {
      "network": "base",
      "networkName": "Base",
      "asset": "native",
      "symbol": "ETH",
      "name": "Ether",
      "decimals": 18,
      "amount": "0",
      "display": "0",
      "error": null
    },
    {
      "network": "base",
      "networkName": "Base",
      "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
      "symbol": "USDC",
      "name": "USD Coin",
      "decimals": 6,
      "amount": "0",
      "display": "0",
      "error": null
    }
  ],
  "errors": [],
  "halted": false
}
Response fields
Field Type Required Description
asOf string yes
balances array of object yes
balances[].network string yes
balances[].asset string yes
balances[].symbol string yes
balances[].decimals integer -9007199254740991…9007199254740991 yes
balances[].amount string | null yes
balances[].display string | null yes
balances[].error string | null yes
errors array of object yes
errors[].source string yes
errors[].message string yes
halted boolean | null yes emergency halt of the signer; null when the signer does not say

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_network
429 auth_throttled, rate_limited
500 internal
503 service_unavailable, signer_unreachable

# GET /api/v1/trading/activity

Wallet activity and fills, newest first. Operation id getActivity.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Sends, 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.

Parameters

Name In Type Required Description
limit query integer 1…500 — rows returned at most — default 100
cursor query string — opaque position returned as nextCursor by the previous page; send it with the same filters — 1–400 characters · pattern [4]+$

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/activity?limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const page = await client.getActivity({ limit: 2 });
for await (const item of client.iterateActivity()) console.log(item.kind, item.at);   // every page
python
page = client.get_activity(limit=2)
for item in client.iter_activity():   # every page
    print(item.kind, item.at)

Example response — 200, recorded from a real server

json
{
  "items": [
    {
      "kind": "fill",
      "mode": "paper",
      "at": "2026-11-17T22:15:31.480Z",
      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-6",
      "venue": "hyperliquid",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "instrument": "hyperliquid:BTC",
      "side": "sell",
      "price": "64426",
      "size": "0.00078",
      "fee": "0.022613526",
      "closedPnl": "-0.00468"
    },
    {
      "kind": "fill",
      "mode": "paper",
      "at": "2026-11-17T22:15:31.456Z",
      "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-4",
      "venue": "hyperliquid",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "instrument": "hyperliquid:BTC",
      "side": "sell",
      "price": "64426",
      "size": "0.00077",
      "fee": "0.022323609",
      "closedPnl": "-0.00462"
    }
  ],
  "nextCursor": "WyIxNzk0OTUzNzMxNDU2MDAwIiwiZiIsIjZhMmM4MzUxLWNkNzktNDRlMi1iNzVhLWYzOTI4MGQwZWJjMjpwYXBlci1mLTQiXQ"
}
Response fields
Field Type Required Description
items array of object yes
items[].kind string yes
items[].at string yes
items[].mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
nextCursor string | null yes pass it as cursor to read the next (older) page; null when there is none

Errors

Status Codes
400 bad_request, invalid_cursor
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# Nfts

Read-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.

# GET /api/v1/trading/nfts

NFTs of the wallet (what the chain confirmed as held). Operation id listNfts.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

The 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.

Parameters

Name In Type Required Description
network query string — one network id; default: all — 0–24 characters
collection query string — collection key — 0–260 characters
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
q query string — case-insensitive text matched on the name, the key or the collection name — 0–80 characters
sort query "recent" | "name" — order of the list — default "recent"
spam query "hide" | "show" | "only" — items an indexer flags as spam are hidden by default, never deleted — default "hide"
limit query integer 1…100 — rows returned at most — default 48
cursor query string — opaque position returned as nextCursor by the previous page; send it with the same filters — 1–400 characters · pattern [5]+$

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts?limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { items, nextCursor } = await client.listNfts({ limit: 2 });
python
nfts = client.list_nfts(limit=2)

Example response — 200, recorded from a real server. The test wallet holds no NFT: the list is empty, and valuation is always unavailable.

json
{
  "items": [],
  "total": 0,
  "hiddenSpam": 0,
  "nextCursor": null,
  "valuation": {
    "state": "unavailable",
    "reason": "no_reliable_valuation",
    "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"
  },
  "asOf": "2026-11-17T22:15:28.204Z"
}
Response fields
Field Type Required Description
items array of object yes
items[].key string yes family:network:asset-id — the id every NFT operation takes
items[].network string yes
items[].family string yes
items[].standard string yes
items[].assetId string yes
items[].contractAddress string | null yes
items[].tokenId string | null yes decimal string (up to 2^256 − 1), never a number
items[].mintAddress string | null yes
items[].quantity string yes exact integer of base units, as a string — pattern ^(0|[1-9][0-9]{0,77})$
items[].name string | null yes declared by the creator — not chain truth
items[].onchainName string | null yes
items[].collection object | null yes
items[].state string yes
items[].inWallet boolean yes
items[].transferable boolean yes
items[].transferBlockedBy array of string yes
items[].spam object | null yes an indexer's signal, named — never a verdict of this wallet
items[].ownershipSource object yes
total integer -9007199254740991…9007199254740991 yes
hiddenSpam integer -9007199254740991…9007199254740991 yes
nextCursor string | null yes pass it as cursor to read the next (older) page; null when there is none
valuation object yes NFTs have no value in this API: never zero, never a floor
valuation.state "unavailable" yes
valuation.reason string yes
valuation.note string yes
asOf string yes

Errors

Status Codes
400 bad_request, invalid_cursor
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_network, unknown_nft
429 auth_throttled, rate_limited
500 internal
503 nft_disabled, signer_unreachable

# GET /api/v1/trading/nfts/item

One NFT of the wallet: identity, ownership, creator metadata, sources. Operation id getNft.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Only 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.

Parameters

Name In Type Required Description
key query string yes family:network:asset-id, as returned by GET /nfts — 5–260 characters

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/item?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { nft } = await client.getNft('evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1');
python
nft = client.get_nft("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1").nft

Example response — 200, written from the schema (not recorded)

json
{
  "nft": {
    "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",
    "network": "ethereum",
    "family": "evm",
    "standard": "erc721",
    "assetId": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",
    "contractAddress": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
    "tokenId": "1",
    "mintAddress": null,
    "quantity": "1",
    "name": "Example #1",
    "onchainName": null,
    "collection": {
      "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
      "id": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",
      "name": "Example Collection",
      "verifiedOnChain": {
        "state": "unsupported"
      }
    },
    "state": "held",
    "inWallet": true,
    "transferable": true,
    "transferBlockedBy": [],
    "spam": null,
    "ownershipSource": {
      "category": "onchain",
      "source": "rpc:ownerOf",
      "confidence": "confirmed",
      "fetchedAt": "2026-11-17T22:15:29.000Z",
      "stale": false
    },
    "ownership": {
      "state": "held",
      "owner": {
        "state": "known",
        "value": "0x00000000000000000000000000000000000000aa"
      },
      "heldByWallet": true
    },
    "metadata": {
      "status": "ok",
      "name": "Example #1",
      "description": "Declared by the creator.",
      "attributes": [
        {
          "traitType": "Background",
          "value": "Blue"
        }
      ]
    },
    "sources": [
      {
        "category": "onchain",
        "source": "rpc:ownerOf",
        "stale": false
      },
      {
        "category": "creator_metadata",
        "source": "tokenURI",
        "stale": false
      }
    ]
  },
  "marketActions": [
    {
      "id": "sell",
      "available": false,
      "reason": "market_writes_not_built"
    }
  ]
}
Response fields
Field Type Required Description
nft object yes
nft.key string yes family:network:asset-id — the id every NFT operation takes
nft.network string yes
nft.family string yes
nft.standard string yes
nft.assetId string yes
nft.contractAddress string | null yes
nft.tokenId string | null yes decimal string (up to 2^256 − 1), never a number
nft.mintAddress string | null yes
nft.quantity string yes exact integer of base units, as a string — pattern ^(0|[1-9][0-9]{0,77})$
nft.name string | null yes declared by the creator — not chain truth
nft.onchainName string | null yes
nft.collection object | null yes
nft.state string yes
nft.inWallet boolean yes
nft.transferable boolean yes
nft.transferBlockedBy array of string yes
nft.spam object | null yes an indexer's signal, named — never a verdict of this wallet
nft.ownershipSource object yes
nft.ownership object yes
nft.metadata object yes declared by the creator: text, never chain truth
nft.sources array of object yes
marketActions array of object yes the market actions, none of which exists in this version: every one is available: false with its reason
marketActions[].id string yes
marketActions[].available false yes
marketActions[].reason string yes

Errors

Status Codes
400 bad_request, invalid_cursor
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_network, unknown_nft
429 auth_throttled, rate_limited
500 internal
503 nft_disabled, signer_unreachable

# GET /api/v1/trading/nfts/activity

On-chain events of one NFT of the wallet. Operation id getNftActivity.

  • Permission: wallet:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Mints, 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.

Parameters

Name In Type Required Description
key query string yes family:network:asset-id, as returned by GET /nfts — 5–260 characters
limit query integer 1…50 — rows returned at most — default 20
cursor query string — nextCursor of the previous page — 0–400 characters
type query "mint" | "transfer" | "transfer-in" | "transfer-out" | "burn" | "sale" | "unknown" — only events of this type

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/activity?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1&limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { events } = await client.getNftActivity({ key: 'evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1', limit: 2 });
python
events = client.get_nft_activity("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1", limit=2).events

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.

json
{
  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",
  "events": [
    {
      "id": "0x5c1f…e2a9:14",
      "type": "transfer-in",
      "tx": "0x5c1f0d2b7a9e4c3f8b6a1d0e9f7c5b3a2d1e0f9c8b7a6d5e4f3c2b1a0f9ee2a9",
      "at": "2026-10-02T14:11:23.000Z",
      "from": "0x00000000000000000000000000000000000000bb",
      "to": "0x00000000000000000000000000000000000000aa",
      "quantity": "1",
      "finality": "final",
      "price": null,
      "interpretedBy": "chain"
    }
  ],
  "nextCursor": null,
  "completeness": "partial",
  "note": null,
  "error": null
}
Response fields
Field Type Required Description
key string yes
events array of object yes
events[].id string yes
events[].type string yes
events[].tx string yes
events[].at string | null yes
events[].from string | null yes
events[].to string | null yes
events[].quantity string yes
events[].finality string yes
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
events[].interpretedBy string yes
nextCursor string | null yes pass it as cursor to read the next (older) page; null when there is none
completeness string yes
note string | null yes
error string | null yes

Errors

Status Codes
400 bad_request, invalid_cursor, nft_bad_identifier
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 nft_not_found, unknown_network, unknown_nft
422 nft_unsupported_chain, nft_unsupported_standard
429 auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited
500 internal
502 nft_provider_bad_answer, nft_provider_disagreement
503 nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable

# GET /api/v1/trading/nfts/market

Market data of any NFT, one row per source. Operation id getNftMarket.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

The 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.

Parameters

Name In Type Required Description
network query string yes network id, e.g. ethereum, base, solana — 0–24 characters
address query string yes EVM: the contract; Solana: the mint / asset address — 26–64 characters
tokenId query string — EVM: required, decimal or 0x-hex — 0–80 characters

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/market?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const market = await client.getNftMarket({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1' });
python
market = client.get_nft_market(network="ethereum", address="0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", token_id="1")

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.

json
{
  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",
  "network": "ethereum",
  "standard": "erc721",
  "sources": [
    {
      "url": null,
      "listed": {
        "state": "unknown"
      },
      "ask": {
        "state": "unknown"
      },
      "bestOffer": {
        "state": "unknown"
      },
      "lastSale": {
        "state": "unknown"
      },
      "collection": null,
      "collectionFloor": {
        "state": "unknown"
      },
      "verification": null,
      "flags": {
        "suspicious": {
          "state": "unknown"
        },
        "disabled": {
          "state": "unknown"
        },
        "nsfw": {
          "state": "unknown"
        }
      },
      "rarity": {
        "state": "unknown"
      },
      "status": {
        "provider": "opensea",
        "name": "OpenSea",
        "state": "needs_key",
        "code": "no_api_key",
        "unlockedBy": "OPENSEA_API_KEY",
        "stale": false,
        "stamp": null,
        "attribution": null
      }
    }
  ],
  "contradictions": [],
  "rates": {},
  "value": {
    "state": "unavailable",
    "reason": "no_valuation_from_floor_or_single_quote"
  },
  "marketActions": [
    {
      "id": "buy",
      "available": false,
      "reason": "market_writes_not_built"
    },
    {
      "id": "sell",
      "available": false,
      "reason": "market_writes_not_built"
    }
  ],
  "asOf": "2026-11-17T22:15:29.113Z"
}
Response fields
Field Type Required Description
key string yes
network string yes
standard string yes
sources array of object yes ONE ROW PER SOURCE: never merged, never averaged
sources[].status object yes
sources[].url string | null yes
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
sources[].ask object yes asking price of a live listing
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
sources[].lastSale object yes last sale the source reports
sources[].collectionFloor object yes a statistic of the COLLECTION — never the value of this item
sources[].verification object | null yes the marketplace's own badge, named — not an on-chain verification
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
contradictions array of object yes
contradictions[].field string yes
contradictions[].providers array of string yes
contradictions[].note string yes
rates map of object yes fiat rates of the currencies quoted, keyed network:asset — secondary information with its own source and date
value object yes
value.state "unavailable" yes
value.reason string yes
marketActions array of object yes the market actions, none of which exists in this version: every one is available: false with its reason
marketActions[].id string yes
marketActions[].available false yes
marketActions[].reason string yes
asOf string yes

Errors

Status Codes
400 bad_request, nft_bad_identifier
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 nft_not_found, unknown_network
422 nft_unsupported_chain, nft_unsupported_standard
429 auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited
500 internal
502 nft_provider_bad_answer, nft_provider_disagreement
503 nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable

# GET /api/v1/trading/nfts/market/events

Market events of any NFT (sales, listings, offers), per source. Operation id getNftMarketEvents.

  • Permission: markets:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

What 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).

Parameters

Name In Type Required Description
network query string yes network id, e.g. ethereum, base, solana — 0–24 characters
address query string yes EVM: the contract; Solana: the mint / asset address — 26–64 characters
tokenId query string — EVM: required, decimal or 0x-hex — 0–80 characters
provider query string — only this source (its id is sources[].status.provider); required with cursor — pattern [6][a-z0-9-]{1,30}$
type query string — comma-separated: sale, list, delist, offer, cancel-offer, transfer, mint — 0–120 characters · pattern [7]+$
after query string — only events after this instant (ISO 8601) — ISO 8601 date-time
before query string — only events before this instant (ISO 8601) — ISO 8601 date-time
cursor query string — a position in ONE source's list: send it with provider — 0–600 characters
limit query integer 1…50 — rows returned at most — default 20

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/market/events?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1&type=sale&limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { sources } = await client.getNftMarketEvents({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1', type: 'sale', limit: 2 });
python
sources = client.get_nft_market_events(network="ethereum", address="0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", token_id="1", type="sale", limit=2).sources

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.

json
{
  "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",
  "sources": [
    {
      "status": {
        "provider": "opensea",
        "name": "OpenSea",
        "state": "needs_key",
        "code": "no_api_key",
        "unlockedBy": "OPENSEA_API_KEY",
        "stale": false,
        "stamp": null,
        "attribution": null
      },
      "events": [],
      "nextCursor": null
    }
  ],
  "rates": {},
  "asOf": "2026-11-17T22:37:24.187Z"
}
Response fields
Field Type Required Description
key string yes
sources array of object yes
sources[].status object yes
sources[].events array of object yes
sources[].nextCursor string | null yes pass it as cursor to read the next (older) page; null when there is none
rates map of object yes
asOf string yes

Errors

Status Codes
400 bad_request, nft_bad_identifier
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 nft_not_found, unknown_network
422 nft_unsupported_chain, nft_unsupported_standard
429 auth_throttled, nft_budget_exhausted, nft_provider_rate_limited, rate_limited
500 internal
502 nft_provider_bad_answer, nft_provider_disagreement
503 nft_disabled, nft_provider_method_unsupported, nft_provider_not_configured, nft_provider_unavailable, signer_unreachable

# Positions

Open positions, and the two ways out of one: close and reduce — strictly reduce-only market orders. Closing passes the kill switch.

# GET /api/v1/trading/positions

Open positions, paper and live separated by mode. Operation id listPositions.

  • Permission: positions:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Every 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.

Parameters

Name In Type Required Description
mode query "paper" | "live" — paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
venue query string — venue id: hyperliquid, gmx, dydx, spot — 0–40 characters

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { positions } = await client.getPositions({ mode: 'paper' });
python
positions = client.get_positions(mode="paper").positions

Example response — 200, recorded from a real server. A position id contains colons: URL-encode it in a path (both SDKs do).

json
{
  "positions": [
    {
      "id": "paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC",
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "instrument": "hyperliquid:BTC",
      "side": "long",
      "size": "0.00155",
      "entryPrice": "64432",
      "markPrice": "64430.7",
      "liquidationPrice": null,
      "leverage": "3",
      "margin": "33.289195",
      "unrealizedPnl": "-0.002015",
      "source": "paper"
    }
  ],
  "errors": [],
  "ts": 1794953731436
}
Response fields
Field Type Required Description
positions array of object yes
positions[].id string yes
positions[].mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
positions[].venue string yes
positions[].accountId string yes
positions[].instrument string | null yes
positions[].side "long" | "short" yes
positions[].size string yes decimal number as a string (never a float)
positions[].entryPrice string yes decimal number as a string (never a float)
positions[].markPrice string | null yes
positions[].unrealizedPnl string | null yes
positions[].source string yes
errors array of object yes
errors[].source string yes
errors[].message string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
429 auth_throttled, rate_limited
500 internal
503 service_unavailable

# POST /api/v1/trading/positions/{id}/close

Close a position. Operation id closePosition.

  • Permission: positions:manage — and a trading mandate bound to the key (403 mandate_required otherwise)
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

A 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
slippageBps integer 1…500 — worst acceptable price of the closing market order, in basis points from the reference price

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/close" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
ts
const closed = await client.closePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC');
python
closed = client.close_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC")

Example response — 200, recorded from a real server

json
{
  "order": {
    "id": "0xfa8f57b697470c1ec4327676f56a9868",
    "orderId": "0xfa8f57b697470c1ec4327676f56a9868",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0xfa8f57b697470c1ec4327676f56a9868",
    "clientOrderId": "0xfa8f57b697470c1ec4327676f56a9868",
    "venueOrderId": "paper-o-5",
    "instrument": "hyperliquid:BTC",
    "side": "sell",
    "type": "market",
    "size": "0.00078",
    "price": "64104",
    "triggerPrice": null,
    "reduceOnly": true,
    "tif": "ioc",
    "status": "FILLED",
    "final": true,
    "reasonCode": "VENUE_FILLED",
    "reason": null,
    "rejectCode": null,
    "engineStatus": "filled",
    "filled": "0.00078",
    "avgFillPrice": "64426",
    "acknowledged": true,
    "cancelRequested": false,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xfa8f57b697470c1ec4327676f56a9868",
    "hash": "73c1d9ea9e8be9bc4f6be7ed0febf7f3947552ec479c497b256798e8d217f7cd",
    "notionalUsd": "50.00112",
    "projectionError": null,
    "version": 4,
    "createdAt": 1794953731468,
    "updatedAt": 1794953731487
  },
  "idempotent": false,
  "approval": null
}
Response fields
Field Type Required Description
order Order yes
idempotent boolean yes true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again
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
approval.by string yes
approval.engine string yes
approval.accountId string yes
approval.clientId string yes
approval.hash string | null yes
approval.expiresAt integer -9007199254740991…9007199254740991 | null yes
approval.approve object yes

Errors (open: the executing venue engine can add a code of its own rules)

Status Codes
400 bad_policy, bad_request, idempotency, invalid_order, stale_request
401 unauthenticated
403 execution_disabled, gmx_disabled, gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, key_limit_exceeded, mainnet_disabled, mandate_denied, mandate_integrity, mandate_mainnet_disabled, mandate_not_approved, mandate_required, mixed_credentials, owner_session_required, position_not_attributable, restricted, spot_execution_requires_agent_vault, venue_restricted
404 unknown_account, unknown_instrument, unknown_position, unknown_venue
409 account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_position, bad_state, idempotency_conflict, idempotency_in_progress
422 authorization_expired, bad_input, bad_mark, bad_order, bad_policy, below_min_notional, below_min_size, close_in_app, daily_loss_exceeded, data_mismatch, duplicate_client_id, fee_cap_not_expressible, gmx_leverage_required, gross_exposure_exceeded, halted, inconsistent_prices, instrument_halted, instrument_mismatch, instrument_not_allowed, instrument_reduce_only, insufficient_collateral, invalid_order, leverage_exceeded, leverage_mismatch, liquidation_too_close, live_not_available, mandate_mismatch, mandate_none, mandate_wind_down, mark_index_divergence, missing_balance, missing_reference_price, mode_read_only, no_account, no_client_id_format, no_instrument, no_position, not_reducing, order_notional_exceeded, order_rate_day, order_rate_minute, paper_unsupported, position_notional_exceeded, price_deviation, price_not_on_tick, price_required, reduce_only_would_flip, reduce_only_would_increase, risk_denied, size_not_on_lot, spot_buy_needs_quote_amount, spot_market_only, spot_paper_not_available, spot_via_swap_screen, stale_book, stale_ticker, swap_not_enabled, total_loss_exceeded, trigger_required, unknown_instrument, unsupported_asset, venue_not_wired, venue_rejected, zero_size
423 halted, kill_switch_active, read_only_mode
429 auth_throttled, rate_limited
500 internal
501 execution_not_wired
502 swap_flow_failed
503 authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable

# POST /api/v1/trading/positions/{id}/reduce

Reduce a position. Operation id reducePosition.

  • Permission: positions:manage — and a trading mandate bound to the key (403 mandate_required otherwise)
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

As 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
fraction string yes share of the position to close, in (0, 1] — pattern ^(0(.\d+)?|1(.0+)?)$
slippageBps integer 1…500 — worst acceptable price of the reducing market order, in basis points from the reference price

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/reduce" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"fraction":"0.5"}'
ts
const reduced = await client.reducePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC', { fraction: '0.5' });
python
reduced = client.reduce_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC", fraction="0.5")

Example response — 200, recorded from a real server

json
{
  "order": {
    "id": "0xae8c2f844447aa3dc5604837d7a7d78f",
    "orderId": "0xae8c2f844447aa3dc5604837d7a7d78f",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0xae8c2f844447aa3dc5604837d7a7d78f",
    "clientOrderId": "0xae8c2f844447aa3dc5604837d7a7d78f",
    "venueOrderId": "paper-o-3",
    "instrument": "hyperliquid:BTC",
    "side": "sell",
    "type": "market",
    "size": "0.00077",
    "price": "64104",
    "triggerPrice": null,
    "reduceOnly": true,
    "tif": "ioc",
    "status": "FILLED",
    "final": true,
    "reasonCode": "VENUE_FILLED",
    "reason": null,
    "rejectCode": null,
    "engineStatus": "filled",
    "filled": "0.00077",
    "avgFillPrice": "64426",
    "acknowledged": true,
    "cancelRequested": false,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xae8c2f844447aa3dc5604837d7a7d78f",
    "hash": "1528b646d4c9541d3faddcf092cccca76aa9710a7956c811adb5a5128c1a25ad",
    "notionalUsd": "49.36008",
    "projectionError": null,
    "version": 4,
    "createdAt": 1794953731442,
    "updatedAt": 1794953731461
  },
  "idempotent": false,
  "approval": null
}
Response fields
Field Type Required Description
order Order yes
idempotent boolean yes true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again
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
approval.by string yes
approval.engine string yes
approval.accountId string yes
approval.clientId string yes
approval.hash string | null yes
approval.expiresAt integer -9007199254740991…9007199254740991 | null yes
approval.approve object yes

Errors (open: the executing venue engine can add a code of its own rules)

Status Codes
400 bad_policy, bad_request, idempotency, invalid_order, stale_request
401 unauthenticated
403 execution_disabled, gmx_disabled, gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, key_limit_exceeded, mainnet_disabled, mandate_denied, mandate_integrity, mandate_mainnet_disabled, mandate_not_approved, mandate_required, mixed_credentials, owner_session_required, position_not_attributable, restricted, spot_execution_requires_agent_vault, venue_restricted
404 unknown_account, unknown_instrument, unknown_position, unknown_venue
409 account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_position, bad_state, idempotency_conflict, idempotency_in_progress
422 authorization_expired, bad_input, bad_mark, bad_order, bad_policy, below_min_notional, below_min_size, close_in_app, daily_loss_exceeded, data_mismatch, duplicate_client_id, fee_cap_not_expressible, gmx_leverage_required, gross_exposure_exceeded, halted, inconsistent_prices, instrument_halted, instrument_mismatch, instrument_not_allowed, instrument_reduce_only, insufficient_collateral, invalid_order, leverage_exceeded, leverage_mismatch, liquidation_too_close, live_not_available, mandate_mismatch, mandate_none, mandate_wind_down, mark_index_divergence, missing_balance, missing_reference_price, mode_read_only, no_account, no_client_id_format, no_instrument, no_position, not_reducing, order_notional_exceeded, order_rate_day, order_rate_minute, paper_unsupported, position_notional_exceeded, price_deviation, price_not_on_tick, price_required, reduce_only_would_flip, reduce_only_would_increase, risk_denied, size_not_on_lot, spot_buy_needs_quote_amount, spot_market_only, spot_paper_not_available, spot_via_swap_screen, stale_book, stale_ticker, swap_not_enabled, total_loss_exceeded, trigger_required, unknown_instrument, unsupported_asset, venue_not_wired, venue_rejected, zero_size
423 halted, kill_switch_active, read_only_mode
429 auth_throttled, rate_limited
500 internal
501 execution_not_wired
502 swap_flow_failed
503 authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable

# Orders

Preview, 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.

# GET /api/v1/trading/orders

Orders, newest first. Operation id listOrders.

  • Permission: orders:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Every 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.

Parameters

Name In Type Required Description
mode query "paper" | "live" — paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
venue query string — venue id: hyperliquid, gmx, dydx, spot — 0–40 characters
open query "true" | "false" — true: only orders that are not final; false: only final orders
limit query integer 1…500 — rows returned at most — default 100
cursor query string — opaque position returned as nextCursor by the previous page; send it with the same filters — 1–400 characters · pattern [8]+$

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders?open=true&limit=5" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { orders, nextCursor } = await client.listOrders({ open: true, limit: 5 });
for await (const order of client.iterateOrders({ open: true })) console.log(order.id, order.status);   // every page
python
page = client.list_orders(open=True, limit=5)
for order in client.iter_orders(open=True):   # every page
    print(order.id, order.status)

Example response — 200, recorded from a real server

json
{
  "orders": [
    {
      "id": "0x0276bab16d117c8323ee375b61b01d1d",
      "orderId": "0x0276bab16d117c8323ee375b61b01d1d",
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "clientId": "0x0276bab16d117c8323ee375b61b01d1d",
      "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",
      "venueOrderId": "paper-o-11",
      "instrument": "hyperliquid:BTC",
      "side": "buy",
      "type": "limit",
      "size": "0.001",
      "price": "63775",
      "triggerPrice": null,
      "reduceOnly": false,
      "tif": "gtc",
      "status": "SUBMITTED",
      "final": false,
      "reasonCode": "VENUE_ACCEPTED",
      "reason": null,
      "rejectCode": null,
      "engineStatus": "open",
      "filled": "0",
      "avgFillPrice": null,
      "acknowledged": true,
      "cancelRequested": false,
      "origin": "trading_api",
      "principal": {
        "kind": "api_key",
        "id": "spk_0123456789ab"
      },
      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
      "engine": "paper",
      "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",
      "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",
      "notionalUsd": "63.775",
      "projectionError": null,
      "version": 4,
      "createdAt": 1794953786427,
      "updatedAt": 1794953786445
    }
  ],
  "nextCursor": null,
  "ts": 1794953786452
}
Response fields
Field Type Required Description
orders array of Order yes
nextCursor string | null yes pass it as cursor to read the next (older) page; null when there is none
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request, invalid_cursor
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/orders

Place an order. Operation id placeOrder.

  • Permission: orders:execute — and a trading mandate bound to the key (403 mandate_required otherwise)
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Idempotent 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.

Owner 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).

API 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.

LIVE 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.

A 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.

Spot 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.

Request body (JSON; unknown fields are refused)

Field Type Required Description
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
accountId string — paper account or venue account; required when the wallet has several on the venue — a UUID
instrument string yes venue:symbol (e.g. hyperliquid:BTC, spot:ETH); a bare symbol is accepted when it is not ambiguous — 1–120 characters
side "buy" | "sell" yes buy opens or adds to a long (or reduces a short); sell the reverse
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
size string — quantity of the base asset. Exactly one of size and notional is required — pattern ^\d+(.\d+)?$
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+)?$
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+)?$
triggerPrice string — price at which a stop or take-profit order is triggered; required by the four trigger types — pattern ^\d+(.\d+)?$
reduceOnly boolean — true: the order may only reduce an existing position — it can neither open, increase nor flip one — default false
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"
slippageBps integer 1…500 — market orders: the worst acceptable price, in basis points from the reference price
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+)?$
maxFeeUsd string — highest fee accepted, USD; default: 10 bps of the notional — pattern ^\d+(.\d+)?$
clientOrderId string — idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal — pattern [9]{8,100}$

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'
ts
const placed = await client.createOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' }, { idempotencyKey: 'bot-2026-11-17-0001' });
python
placed = client.create_order(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100", idempotency_key="bot-2026-11-17-0001")

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.

json
{
  "order": {
    "id": "0xff18683e8e2aa319d3812cf8a47fc261",
    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "venueOrderId": "paper-o-1",
    "instrument": "hyperliquid:BTC",
    "side": "buy",
    "type": "market",
    "size": "0.00155",
    "price": "64754",
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "ioc",
    "status": "FILLED",
    "final": true,
    "reasonCode": "VENUE_FILLED",
    "reason": null,
    "rejectCode": null,
    "engineStatus": "filled",
    "filled": "0.00155",
    "avgFillPrice": "64432",
    "acknowledged": true,
    "cancelRequested": false,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",
    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",
    "notionalUsd": "100.3687",
    "projectionError": null,
    "version": 4,
    "createdAt": 1794953729578,
    "updatedAt": 1794953729602
  },
  "idempotent": false,
  "approval": null
}
Response fields
Field Type Required Description
order Order yes
idempotent boolean yes true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again
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
approval.by string yes
approval.engine string yes
approval.accountId string yes
approval.clientId string yes
approval.hash string | null yes
approval.expiresAt integer -9007199254740991…9007199254740991 | null yes
approval.approve object yes

Errors (open: the executing venue engine can add a code of its own rules)

Status Codes
400 bad_policy, bad_request, idempotency, invalid_order, stale_request
401 unauthenticated
403 execution_disabled, gmx_disabled, gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, key_limit_exceeded, mainnet_disabled, mandate_denied, mandate_integrity, mandate_mainnet_disabled, mandate_not_approved, mandate_required, mixed_credentials, owner_session_required, position_not_attributable, restricted, spot_execution_requires_agent_vault, venue_restricted
404 unknown_account, unknown_instrument, unknown_market, unknown_venue
409 account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, ambiguous_symbol, bad_state, idempotency_conflict, idempotency_in_progress
422 authorization_expired, bad_input, bad_mark, bad_order, bad_policy, below_min_notional, below_min_size, daily_loss_exceeded, data_mismatch, duplicate_client_id, fee_cap_not_expressible, gmx_leverage_required, gross_exposure_exceeded, halted, inconsistent_prices, instrument_halted, instrument_mismatch, instrument_not_allowed, instrument_reduce_only, insufficient_collateral, invalid_order, leverage_exceeded, leverage_mismatch, liquidation_too_close, live_not_available, mandate_mismatch, mandate_none, mandate_wind_down, mark_index_divergence, missing_balance, missing_reference_price, mode_read_only, no_account, no_client_id_format, no_instrument, no_position, order_notional_exceeded, order_rate_day, order_rate_minute, paper_unsupported, position_notional_exceeded, price_deviation, price_not_on_tick, price_required, reduce_only_would_flip, reduce_only_would_increase, risk_denied, size_not_on_lot, spot_buy_needs_quote_amount, spot_market_only, spot_paper_not_available, spot_via_swap_screen, stale_book, stale_ticker, swap_not_enabled, total_loss_exceeded, trigger_required, unknown_instrument, unsupported_asset, venue_not_wired, venue_rejected, zero_size
423 halted, kill_switch_active, read_only_mode
429 auth_throttled, rate_limited
500 internal
501 execution_not_wired
502 swap_flow_failed
503 authorization_unknown, mandate_unavailable, no_liquidity, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable

# GET /api/v1/trading/orders/{id}

One order and its fills. Operation id getOrder.

  • Permission: orders:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

The 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.

Parameters

Name In Type Required Description
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

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { order, fills } = await client.getOrder('0xff18683e8e2aa319d3812cf8a47fc261');
const done = await client.waitForOrder('0xff18683e8e2aa319d3812cf8a47fc261');   // polls until final; UNKNOWN keeps waiting
python
detail = client.get_order("0xff18683e8e2aa319d3812cf8a47fc261")
done = client.wait_for_order("0xff18683e8e2aa319d3812cf8a47fc261")   # polls until final; UNKNOWN keeps waiting

Example response — 200, recorded from a real server. Fills and history cut to two entries.

json
{
  "order": {
    "id": "0xff18683e8e2aa319d3812cf8a47fc261",
    "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",
    "venueOrderId": "paper-o-1",
    "instrument": "hyperliquid:BTC",
    "side": "buy",
    "type": "market",
    "size": "0.00155",
    "price": "64754",
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "ioc",
    "status": "FILLED",
    "final": true,
    "reasonCode": "VENUE_FILLED",
    "reason": null,
    "rejectCode": null,
    "engineStatus": "filled",
    "filled": "0.00155",
    "avgFillPrice": "64432",
    "acknowledged": true,
    "cancelRequested": false,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",
    "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",
    "notionalUsd": "100.3687",
    "projectionError": null,
    "version": 4,
    "createdAt": 1794953729578,
    "updatedAt": 1794953729602,
    "canonical": {
      "v": 1,
      "tif": "ioc",
      "mode": "paper",
      "side": "buy",
      "size": "0.00155",
      "type": "market",
      "venue": "hyperliquid",
      "network": "mainnet",
      "leverage": null,
      "notional": null,
      "createdAt": 1794953729578,
      "expiresAt": 1794953849578,
      "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
      "maxFeeUsd": "0.099869",
      "principal": {
        "id": "spk_0123456789ab",
        "kind": "api_key"
      },
      "instrument": "hyperliquid:BTC",
      "limitPrice": null,
      "marginMode": null,
      "marketKind": "perp",
      "reduceOnly": false,
      "triggerPrice": null,
      "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",
      "maxSlippageBps": 50
    }
  },
  "fills": [
    {
      "id": "paper-f-2",
      "instrument": "hyperliquid:BTC",
      "side": "buy",
      "price": "64432",
      "size": "0.00155",
      "fee": "0.04494132",
      "feeAsset": "USDC",
      "closedPnl": null,
      "liquidation": false,
      "ts": 1794953729595
    }
  ],
  "history": [
    {
      "seq": 1,
      "from": "CREATED",
      "to": "VALIDATED",
      "event": "validated",
      "reason": "VALIDATION_PASSED",
      "detail": null,
      "at": 1794953729590
    },
    {
      "seq": 2,
      "from": "VALIDATED",
      "to": "APPROVED",
      "event": "approved",
      "reason": "APPROVED_BY_MANDATE",
      "detail": null,
      "at": 1794953729593
    }
  ]
}
Response fields
Field Type Required Description
order Order yes
fills array of object yes
fills[].id string yes
fills[].instrument string yes
fills[].side string yes
fills[].price string yes decimal number as a string (never a float)
fills[].size string yes decimal number as a string (never a float)
fills[].fee string yes decimal number as a string (never a float)
fills[].feeAsset string yes
fills[].closedPnl string | null yes
fills[].liquidation boolean yes
fills[].ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
history array of object — the transitions of the order, oldest first (absent for agent: rows)

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 unknown_order
429 auth_throttled, rate_limited
500 internal

# DELETE /api/v1/trading/orders/{id}

Cancel an order. Operation id cancelOrder.

  • Permission: orders:cancel
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

A 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.

Parameters

Name In Type Required Description
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

Example request

bash
curl -s -X DELETE "$SP_WALLET_BASE_URL/api/v1/trading/orders/0x0276bab16d117c8323ee375b61b01d1d" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)"
ts
const { order, changed } = await client.cancelOrder('0x0276bab16d117c8323ee375b61b01d1d');
python
cancelled = client.cancel_order("0x0276bab16d117c8323ee375b61b01d1d")

Example response — 200, recorded from a real server. Cancelling again answers 200 with changed: false.

json
{
  "order": {
    "id": "0x0276bab16d117c8323ee375b61b01d1d",
    "orderId": "0x0276bab16d117c8323ee375b61b01d1d",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "mainnet",
    "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "clientId": "0x0276bab16d117c8323ee375b61b01d1d",
    "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",
    "venueOrderId": "paper-o-11",
    "instrument": "hyperliquid:BTC",
    "side": "buy",
    "type": "limit",
    "size": "0.001",
    "price": "63775",
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "gtc",
    "status": "CANCELLED",
    "final": true,
    "reasonCode": "CANCELLED_BY_REQUEST",
    "reason": "cancelled by the user",
    "rejectCode": null,
    "engineStatus": "cancelled",
    "filled": "0",
    "avgFillPrice": null,
    "acknowledged": true,
    "cancelRequested": true,
    "origin": "trading_api",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "engine": "paper",
    "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",
    "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",
    "notionalUsd": "63.775",
    "projectionError": null,
    "version": 6,
    "createdAt": 1794953786427,
    "updatedAt": 1794953786459
  },
  "sent": false,
  "changed": true,
  "venue": null
}
Response fields
Field Type Required Description
order Order yes
sent boolean yes true: a cancel request went to a venue
changed boolean yes false: the order was already final
venue any —

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, mixed_credentials, not_your_order, owner_session_required
404 unknown_order
409 bad_state, idempotency_conflict, idempotency_in_progress
422 cancel_in_app, venue_rejected
429 auth_throttled, rate_limited
500 internal
503 signer_unreachable, venue_unavailable

# POST /api/v1/trading/orders/preview

Preview an order: every check it would meet, and an estimate. Operation id previewOrder.

  • Permission: orders:prepare
  • Idempotency-Key: not used
  • Side effects: none: creates, signs and sends nothing

Resolves 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.

Answers 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.

What WOULD refuse the order is in refusals (HTTP 200), not an error answer.

A 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).

Request body (JSON; unknown fields are refused)

Field Type Required Description
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
accountId string — paper account or venue account; required when the wallet has several on the venue — a UUID
instrument string yes venue:symbol (e.g. hyperliquid:BTC, spot:ETH); a bare symbol is accepted when it is not ambiguous — 1–120 characters
side "buy" | "sell" yes buy opens or adds to a long (or reduces a short); sell the reverse
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
size string — quantity of the base asset. Exactly one of size and notional is required — pattern ^\d+(.\d+)?$
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+)?$
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+)?$
triggerPrice string — price at which a stop or take-profit order is triggered; required by the four trigger types — pattern ^\d+(.\d+)?$
reduceOnly boolean — true: the order may only reduce an existing position — it can neither open, increase nor flip one — default false
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"
slippageBps integer 1…500 — market orders: the worst acceptable price, in basis points from the reference price
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+)?$
maxFeeUsd string — highest fee accepted, USD; default: 10 bps of the notional — pattern ^\d+(.\d+)?$
clientOrderId string — idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal — pattern [10]{8,100}$

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/orders/preview" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"mode":"paper","instrument":"hyperliquid:BTC","side":"buy","type":"market","notional":"100"}'
ts
const preview = await client.previewOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' });
if (!preview.wouldExecute) console.log(preview.refusals);
python
preview = client.preview_order(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100")
if not preview.would_execute:
    print(preview.refusals)

Example response — 200, recorded from a real server. Risk checks cut to two. wouldExecute is true exactly when refusals is empty.

json
{
  "order": {
    "v": 1,
    "venue": "hyperliquid",
    "network": "mainnet",
    "instrument": "hyperliquid:BTC",
    "marketKind": "perp",
    "side": "buy",
    "type": "market",
    "size": "0.00155",
    "notional": null,
    "limitPrice": null,
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "ioc",
    "maxSlippageBps": 50,
    "maxFeeUsd": "0.099869",
    "leverage": null,
    "marginMode": null,
    "clientOrderId": "0xc7f8200619c1018d8757a6318aab7a51",
    "mode": "paper",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "createdAt": 1794953729364,
    "expiresAt": 1794953849364
  },
  "hash": "a780accd8e5abce90b3975329e8386b8117bbd470727ae3b442bbaf852163506",
  "resolved": {
    "size": "0.00155",
    "worstPrice": "64754",
    "notionalUsd": "100.3687"
  },
  "wouldExecute": true,
  "refusals": [],
  "approval": {
    "required": false,
    "by": "mandate",
    "note": "paper: nothing is signed"
  },
  "risk": {
    "decision": "allow",
    "reducing": false,
    "checks": [
      {
        "id": "input_valid",
        "ok": true,
        "observed": null,
        "limit": null,
        "detail": "request, context and limits are well formed",
        "exempt": false
      },
      {
        "id": "read_only",
        "ok": true,
        "observed": "false",
        "limit": "false",
        "detail": "not in read-only mode",
        "exempt": false
      }
    ],
    "derived": {
      "size": "0.00155",
      "notional": "99.91207",
      "referencePrice": "64459.4",
      "positionBefore": "0",
      "positionAfter": "0.00155"
    },
    "decisionId": 1
  },
  "mandate": {
    "id": "84f954ea-0c25-4985-bc19-901d510964d7",
    "decision": "allow",
    "reasons": [],
    "phase": "active"
  },
  "engine": {
    "name": "paper",
    "risk": {
      "ok": true
    },
    "estimate": {
      "leverage": "3",
      "price": "64754",
      "source": "estimate",
      "notional": "99.8696",
      "initialMargin": "33.289866666666666667",
      "fee": "0.04494132",
      "avgFillPrice": "64432",
      "slippageBps": "-0.0776",
      "liquidationPrice": {
        "value": null,
        "source": "estimate",
        "method": "cross, single-position approximation at a flat maintenance fraction of 0.02; position after the immediate fills; no funding, no fees"
      },
      "freeCollateralAfter": "9966.66415868",
      "filledSize": "0.00155",
      "restingSize": "0",
      "status": "filled",
      "rejectReason": null
    }
  },
  "account": {
    "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
    "venue": "hyperliquid",
    "network": "mainnet",
    "equity": "10000",
    "freeCollateral": "10000",
    "withheld": false
  },
  "ts": 1794953729364
}
Response fields
Field Type Required Description
order CanonicalOrder yes
hash string yes SHA-256 of the canonical bytes, hex
resolved object | null yes what the canonical order leaves open; null when it could not be resolved (see refusals)
resolved.size string | null yes base units; null when the order is sized by a quote amount the venue converts (a GMX increase)
resolved.worstPrice string | null yes
resolved.notionalUsd string | null yes
wouldExecute boolean yes true exactly when refusals is empty
refusals array of object yes
refusals[].stage "key" | "lock" | "mandate" | "risk" | "engine" yes
refusals[].code string yes
refusals[].message string yes
refusals[].reasons array of string —
approval object yes
approval.required boolean yes
approval.by "owner_passkey" | "mandate" | "none" yes
risk object yes
risk.decision "allow" | "deny" yes
risk.reducing boolean yes
risk.checks array of RiskCheck yes
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
mandate object | null yes null for the owner session, and when the key's mandate cannot be used (a mandate refusal then says why)
mandate.id string yes
mandate.decision "allow" | "deny" yes
mandate.reasons array of string yes
engine object yes
engine.name string yes
engine.risk object | null yes
engine.estimate object | null yes fees, slippage against the real book, liquidation price: an estimate
account object yes
account.id string | null yes null for a spot order (the wallet itself)
account.venue string yes
account.network string yes
account.equity string | null —
account.freeCollateral string | null —
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
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

Errors

Status Codes
400 bad_request, invalid_order
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mandate_required, mixed_credentials, owner_session_required, restricted, spot_execution_requires_agent_vault, venue_restricted
404 unknown_account, unknown_instrument, unknown_market, unknown_venue
409 account_required, ambiguous_command, ambiguous_order, ambiguous_symbol
422 below_min_size, fee_cap_not_expressible, gmx_leverage_required, inconsistent_prices, invalid_order, missing_balance, missing_reference_price, no_account, no_client_id_format, no_instrument, no_position, spot_buy_needs_quote_amount, spot_market_only, spot_paper_not_available, spot_via_swap_screen, swap_not_enabled, unknown_instrument, unsupported_asset, venue_not_wired, venue_rejected, zero_size
429 auth_throttled, rate_limited
500 internal
501 execution_not_wired
502 swap_flow_failed
503 stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable

# POST /api/v1/trading/commands

Run one line of the trading command grammar. Operation id runCommand.

  • Permission: orders:prepare
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Deterministic grammar (no model): LONG|SHORT -PERP [x] [LIMIT ] [SL ] [TP ] [ON ], CLOSE -PERP [pct%], CANCEL ORDER , CANCEL ALL, SHOW POSITIONS|BALANCES|ORDERS|RISK, STOP ALL AGENTS, KILL, and for the owner BUY/SELL (spot).

The 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.

Resolution 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.

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.

Request body (JSON; unknown fields are refused)

Field Type Required Description
text string yes one line of the trading command grammar, English or French: LONG BTC-PERP 500 x2, CLOSE BTC-PERP 50%, CANCEL ORDER , SHOW POSITIONS, KILL … — 1–300 characters
mode "paper" | "live" — paper = simulated, live = a venue or on-chain account. The two are never merged in one figure. — default "paper"
accountId string — paper account or venue account; required when the wallet has several on the venue — a UUID
dryRun boolean — true: answer the canonical order (or the control) the command resolves to, and do nothing — default false

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/commands" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"text":"LONG BTC-PERP 100","mode":"paper","dryRun":true}'
ts
const r = await client.runCommand('LONG BTC-PERP 100', { mode: 'paper', dryRun: true });
if (r.kind === 'order' && !r.executed) console.log(r.order, r.hash);
python
r = client.run_command("LONG BTC-PERP 100", mode="paper", dry_run=True)

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

json
{
  "command": "perp_open",
  "mode": "paper",
  "dryRun": true,
  "kind": "order",
  "order": {
    "v": 1,
    "venue": "hyperliquid",
    "network": "mainnet",
    "instrument": "hyperliquid:BTC",
    "marketKind": "perp",
    "side": "buy",
    "type": "market",
    "size": null,
    "notional": "100",
    "limitPrice": null,
    "triggerPrice": null,
    "reduceOnly": false,
    "tif": "ioc",
    "maxSlippageBps": 50,
    "maxFeeUsd": "0.1",
    "leverage": "2",
    "marginMode": "cross",
    "clientOrderId": "0x58617397cbaee774b5a74ada6581a070",
    "mode": "paper",
    "principal": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "createdAt": 1794953783632,
    "expiresAt": 1794953843632
  },
  "hash": "5a6980aa9a3668f4618c2186974428ca40b83bc68ce2be2194f5a02732c57db5",
  "attached": [],
  "executed": false
}

Response — one of:

  1. SHOW …
Field Type Required Description
kind "query" yes
command string yes the parsed command type
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
dryRun boolean yes
query string yes
data object yes the answer of the matching read operation
  1. CANCEL, KILL, STOP ALL AGENTS
Field Type Required Description
kind "control" yes
command string yes the parsed command type
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
dryRun boolean yes
executed boolean yes
control object yes
result object — CANCEL ORDER, executed: the answer of the cancel
results array of object — CANCEL ALL, executed: one row per order
orders array of string — CANCEL ALL, dry run: the ids that would be cancelled
killSwitch Switch —
  1. an order command with dryRun
Field Type Required Description
kind "order" yes
command string yes the parsed command type
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
dryRun boolean yes
executed false yes
order CanonicalOrder yes the canonical order the command resolves to; nothing was created
hash string yes
attached array of object yes
preview object — spot: the preview of the swap the order would become
  1. an order command, executed
Field Type Required Description
kind "order" yes
command string yes the parsed command type
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
dryRun boolean yes
executed true yes
order Order yes the order that was placed, as POST /orders answers it
canonical CanonicalOrder yes the canonical order that was placed
hash string yes
idempotent boolean yes
approval object | null yes
attached array of object yes

Errors (open: the executing venue engine can add a code of its own rules)

Status Codes
400 bad_policy, bad_request, idempotency, invalid_order, parse_error, stale_request
401 unauthenticated
403 execution_disabled, gmx_disabled, gmx_requires_owner_passkey, insufficient_scope, ip_not_allowed, key_limit_exceeded, mainnet_disabled, mandate_denied, mandate_integrity, mandate_mainnet_disabled, mandate_not_approved, mandate_required, mixed_credentials, not_your_order, owner_session_required, position_not_attributable, restricted, spot_execution_requires_agent_vault, venue_restricted
404 unknown_account, unknown_instrument, unknown_order, unknown_venue
409 account_has_active_mandate, account_required, ambiguous_command, ambiguous_order, bad_state, idempotency_conflict, idempotency_in_progress
422 authorization_expired, bad_input, bad_mark, bad_order, bad_policy, below_min_notional, below_min_size, cancel_in_app, daily_loss_exceeded, data_mismatch, duplicate_client_id, fee_cap_not_expressible, gmx_leverage_required, gross_exposure_exceeded, halted, inconsistent_prices, instrument_halted, instrument_mismatch, instrument_not_allowed, instrument_reduce_only, insufficient_collateral, invalid_order, leverage_exceeded, leverage_mismatch, liquidation_too_close, live_not_available, mandate_mismatch, mandate_none, mandate_wind_down, mark_index_divergence, missing_balance, missing_reference_price, mode_read_only, no_account, no_client_id_format, no_instrument, no_position, not_reducing, order_notional_exceeded, order_rate_day, order_rate_minute, paper_unsupported, position_notional_exceeded, price_deviation, price_not_on_tick, price_required, reduce_only_would_flip, reduce_only_would_increase, risk_denied, size_not_on_lot, spot_buy_needs_quote_amount, spot_market_only, spot_paper_not_available, spot_via_swap_screen, stale_book, stale_ticker, swap_not_enabled, total_loss_exceeded, trigger_required, unknown_instrument, unsupported_asset, venue_not_wired, venue_rejected, zero_size
423 halted, kill_switch_active, read_only_mode
429 auth_throttled, rate_limited
500 internal
501 execution_not_wired
502 swap_flow_failed
503 authorization_unknown, mandate_unavailable, no_liquidity, service_unavailable, signer_unreachable, stale_data, unknown_instrument, venue_rate_limited, venue_timeout, venue_unavailable

# Strategies

The strategy library and the versions pinned to agents: register, backtest, start, stop. Research and paper sign nothing.

# GET /api/v1/trading/strategies

Strategy library and the versions pinned to agents. Operation id listStrategies.

  • Permission: strategies:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

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.

Parameters

Name In Type Required Description
kind query "spot" | "perp" — only spot or only perp strategies

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/strategies?kind=perp" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { library, versions } = await client.listStrategies({ kind: 'perp' });
python
strategies = client.list_strategies(kind="perp")

Example response — 200, recorded from a real server. Cut to one library entry and one version.

json
{
  "library": [
    {
      "kind": "perp",
      "path": "strategies/basis_cash_carry/1",
      "sha256": "344831f2ea276d1b3935164287a3e81e5dcc2940841622a88fb3ca218a0a790b",
      "meta": {
        "name": "basis_cash_carry",
        "version": "1",
        "kind": "perp",
        "universe": [
          "BTC"
        ],
        "interval": "1h",
        "lookback": 720,
        "max_leverage": 1,
        "max_gross_exposure": 1,
        "params": {
          "window": 168,
          "enter_net_apr": 0.05,
          "exit_apr": 0.02,
          "round_trip_cost_bps": 60,
          "holding_days": 30,
          "max_adverse_basis_bps": 15,
          "state_bars": 336,
          "gross": 0.9
        }
      }
    }
  ],
  "versions": [
    {
      "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",
      "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",
      "kind": "perp",
      "name": "momentum_xs_perp",
      "version": "2",
      "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",
      "status": "backtesting",
      "hasReport": false,
      "createdAt": 1794953786690,
      "approvedAt": null
    }
  ],
  "errors": []
}
Response fields
Field Type Required Description
library array of object yes
library[].kind "spot" | "perp" yes
library[].path string yes
library[].sha256 string yes
versions array of object yes
versions[].id string yes
versions[].agentId string yes
versions[].name string yes
versions[].version string yes
versions[].sha256 string yes
versions[].status string yes
errors array of object yes
errors[].source string yes
errors[].message string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/strategies

Register a library strategy version on an agent. Operation id createStrategy.

  • Permission: strategies:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Pins 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.

Request body (JSON; unknown fields are refused)

Field Type Required Description
kind "spot" | "perp" yes must be the kind of the agent (409 wrong_kind otherwise)
path string yes library path of the strategy, from GET /strategies (library[].path) — 1–200 characters
agentId string — the agent the version is registered on; required in practice (400 without it) — a UUID

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"kind":"perp","path":"strategies/momentum_xs_perp/2","agentId":"fa9c1fd9-a005-4825-bd67-ea180a2eb83d"}'
ts
const { strategy } = await client.createStrategy({ kind: 'perp', path: 'strategies/momentum_xs_perp/2', agentId: 'fa9c1fd9-a005-4825-bd67-ea180a2eb83d' });
python
strategy = client.create_strategy(kind="perp", path="strategies/momentum_xs_perp/2", agent_id="fa9c1fd9-a005-4825-bd67-ea180a2eb83d").strategy

Example response — 200, recorded from a real server

json
{
  "strategy": {
    "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",
    "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",
    "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",
    "status": "backtesting"
  },
  "note": "registered and queued for its backtest; approval for LIVE stays the owner's"
}
Response fields
Field Type Required Description
strategy object yes
strategy.id string yes
strategy.agentId string yes
strategy.sha256 string yes
strategy.status string yes

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 idempotency_conflict, idempotency_in_progress, wrong_kind
422 bad_strategy
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/strategies/{id}/backtest

Run the backtest of a strategy version (asynchronous job). Operation id backtestStrategy.

  • Permission: strategies:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Answers a job id; read it with GET /jobs/{id}. The result is a BACKTEST report on the version — never a performance figure.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
symbols array of string — default: the agent's universe — 1–12 items
interval "1h" | "1d" — bar interval; default: the agent's

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/backtest" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{}'
ts
const { job } = await client.backtestStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e');
const done = await client.waitForJob(job.id);
python
job = client.backtest_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e").job
done = client.wait_for_job(job.id)

Example response — 200, recorded from a real server

json
{
  "job": {
    "id": "43823b3b-af8c-4c78-8527-638ea5fde77b",
    "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",
    "kind": "backtest",
    "status": "queued",
    "deadLettered": false,
    "attempts": 0,
    "maxAttempts": 2,
    "runAt": 1794953786889,
    "error": null,
    "result": null,
    "createdAt": 1794953786889,
    "updatedAt": 1794953786889,
    "finishedAt": null
  },
  "label": "backtest"
}
Response fields
Field Type Required Description
job object yes
job.id string yes
job.kind string yes
job.status "queued" | "running" | "done" | "failed" | "cancelled" yes
job.attempts integer -9007199254740991…9007199254740991 yes
label string —

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 idempotency_conflict, idempotency_in_progress
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/strategies/{id}/start

Start the agent a strategy version is pinned to. Operation id startStrategy.

  • Permission: strategies:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

research 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
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.
agentId string — strategy operations only: the agent, when the version id alone does not name it — a UUID

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/start" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode":"paper"}'
ts
await client.startStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { mode: 'paper' });
python
client.start_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e", mode="paper")

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

json
{
  "agent": {
    "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",
    "name": "Docs momentum",
    "mission": "",
    "kind": "perp",
    "family": "momentum",
    "template": "momentum",
    "engine": "bar",
    "state": "active",
    "phase": "PAPER_TRADING",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "hyperliquid",
    "universe": [
      "BTC",
      "ETH"
    ],
    "interval": "1h",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxLeverage": 2,
      "minTradePct": 2,
      "slippageBps": 30,
      "maxPositionX": 1,
      "maxDailyLossPct": 3,
      "maxTotalLossPct": 10,
      "maxGrossExposureX": 1.5
    },
    "configVersion": 3,
    "strategy": {
      "name": "momentum_xs_perp",
      "version": "2",
      "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",
      "path": "strategies/momentum_xs_perp/2",
      "status": "approved",
      "kind": "python"
    },
    "mandate": null,
    "pausedFrom": null,
    "live": {
      "capable": true,
      "code": null,
      "reason": null
    },
    "stopReason": null,
    "lastBar": null,
    "createdAt": 1794953786472,
    "updatedAt": 1794955043180
  },
  "strategyVersionId": "450bc266-e1a9-4807-9113-7da6773ddb4e"
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, owner_required, restricted
404 not_found
409 bad_report, bad_request, bad_state, halted, idempotency_conflict, idempotency_in_progress, live_unavailable, mandate_required, no_report, no_strategy, other_version
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/strategies/{id}/stop

Stop the agent a strategy version is pinned to. Operation id stopStrategy.

  • Permission: strategies:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Always 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
reason string — why, for the agent's journal — default "" · 0–200 characters

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/stop" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"documentation example"}'
ts
await client.stopStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { reason: 'documentation example' });
python
client.stop_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e", reason="documentation example")

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",
    "name": "Docs momentum",
    "mission": "",
    "kind": "perp",
    "family": "momentum",
    "template": "momentum",
    "engine": "bar",
    "state": "stopped",
    "phase": "STOPPED",
    "mode": "paper",
    "venue": "hyperliquid",
    "network": "hyperliquid",
    "universe": [
      "BTC",
      "ETH"
    ],
    "interval": "1h",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxLeverage": 2,
      "minTradePct": 2,
      "slippageBps": 30,
      "maxPositionX": 1,
      "maxDailyLossPct": 3,
      "maxTotalLossPct": 10,
      "maxGrossExposureX": 1.5
    },
    "configVersion": 2,
    "strategy": null,
    "mandate": null,
    "pausedFrom": null,
    "live": {
      "capable": true,
      "code": null,
      "reason": null
    },
    "stopReason": "stopped by the key:spk_0123456789ab",
    "lastBar": null,
    "createdAt": 1794953786472,
    "updatedAt": 1794953786894
  },
  "windDown": null
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 bad_state, idempotency_conflict, idempotency_in_progress
429 auth_throttled, rate_limited
500 internal

# Agents

Trading 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.

# GET /api/v1/trading/agents

Trading agents. Operation id listAgents.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Every 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.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { agents } = await client.listAgents();
python
agents = client.list_agents().agents

Example response — 200, recorded from a real server

json
{
  "agents": [
    {
      "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
      "name": "Docs funding",
      "mission": "",
      "kind": "stream",
      "family": "funding_arb",
      "template": "funding-arb",
      "engine": "stream",
      "state": "CREATED",
      "phase": "CREATED",
      "mode": "RESEARCH",
      "venue": "hyperliquid+dydx",
      "network": "hyperliquid+dydx",
      "universe": [
        "BTC"
      ],
      "interval": "stream",
      "capitalUsd": "1000",
      "riskLimits": {
        "maxGrossUsd": 1000,
        "maxDataAgeMs": 5000,
        "maxPositionUsd": 500,
        "maxDailyLossPct": 2,
        "maxTotalLossPct": 5
      },
      "configVersion": 1,
      "strategy": {
        "name": "funding_differential",
        "version": "1",
        "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
        "path": null,
        "status": "built_in",
        "kind": "rule"
      },
      "mandate": null,
      "pausedFrom": null,
      "live": {
        "capable": false,
        "code": "family_not_live",
        "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
      },
      "stopReason": null,
      "lastBar": null,
      "createdAt": 1794953757211,
      "updatedAt": 1794953757211,
      "lifecycle": "stopped",
      "tradingMode": "research",
      "strategyVersionId": null,
      "mandateId": null,
      "accountId": null
    }
  ]
}
Response fields
Field Type Required Description
agents array of object yes
agents[].id string yes
agents[].kind "spot" | "perp" | "stream" | "supervisor" yes
agents[].name string yes
agents[].family string yes
agents[].state string yes historical raw state
agents[].mode string yes historical raw mode
agents[].lifecycle "active" | "paused" | "stopped" yes
agents[].tradingMode "research" | "paper" | "live" | null yes
agents[].venue string yes
agents[].universe array of string yes
agents[].interval string yes
agents[].configVersion integer -9007199254740991…9007199254740991 yes

Errors

Status Codes
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/agents

Create an agent (from a template, or a perp agent). Operation id createAgent.

  • Permission: agents:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Nothing 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.

Request body (JSON; unknown fields are refused)

Field Type Required Description
kind "spot" | "perp" — without a template: perp (a spot agent needs a vault from the signer: owner only)
template string — one of GET /agents/templates — 0–40 characters
name string yes shown in the app and in the lists — 2–40 characters
mission string — free text for people; it changes nothing the agent does — default "" · 0–400 characters
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
venues array of "hyperliquid" | "edgex" | "dydx" | "gmx" — venues the agent reads; default: the template's — 1–2 items
strategyPath string — bar templates: which of the template's installed strategies to bind, from GET /agents/templates — 0–60 characters
interval "1h" | "4h" | "1d" — bar agents: bar length; default 1h
capitalUsdc string — simulated capital of the agent, a decimal string; default 1000 — pattern ^\d{1,7}(.\d{1,6})?$
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)
config map of any — overrides of the template's parameters, by name
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"

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"template":"funding-arb","name":"Docs funding","mode":"research"}'
ts
const { agent } = await client.createAgent({ template: 'funding-arb', name: 'Docs funding', mode: 'research' });
python
agent = client.create_agent(template="funding-arb", name="Docs funding", mode="research").agent

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "name": "Docs funding",
    "mission": "",
    "kind": "stream",
    "family": "funding_arb",
    "template": "funding-arb",
    "engine": "stream",
    "state": "stopped",
    "phase": "CREATED",
    "mode": "research",
    "venue": "hyperliquid+dydx",
    "network": "hyperliquid+dydx",
    "universe": [
      "BTC"
    ],
    "interval": "stream",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxGrossUsd": 1000,
      "maxDataAgeMs": 5000,
      "maxPositionUsd": 500,
      "maxDailyLossPct": 2,
      "maxTotalLossPct": 5
    },
    "configVersion": 1,
    "strategy": {
      "name": "funding_differential",
      "version": "1",
      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "path": null,
      "status": "built_in",
      "kind": "rule"
    },
    "mandate": null,
    "pausedFrom": null,
    "live": {
      "capable": false,
      "code": "family_not_live",
      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "stopReason": null,
    "lastBar": null,
    "createdAt": 1794953757211,
    "updatedAt": 1794953757211
  },
  "strategy": null,
  "warnings": [
    {
      "code": "no_live",
      "message": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    }
  ]
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, owner_required
409 bad_report, bad_state, exists, halted, idempotency_conflict, idempotency_in_progress, live_unavailable, mandate_required, no_report, no_strategy, strategy_not_installed, wrong_kind
422 bad_request, universe_mismatch
429 auth_throttled, rate_limited
500 internal

# GET /api/v1/trading/agents/templates

The seven built-in agents: family, engine, modes, installed strategies. Operation id listAgentTemplates.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

A 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.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/templates" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { templates } = await client.listAgentTemplates();
python
templates = client.list_agent_templates().templates

Example response — 200, recorded from a real server. Cut to one of the seven templates.

json
{
  "templates": [
    {
      "id": "stat-arb",
      "family": "stat_arb",
      "engine": "bar",
      "kind": "perp",
      "name": {
        "fr": "Arbitrage statistique",
        "en": "Statistical Arbitrage"
      },
      "summary": {
        "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.",
        "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."
      },
      "modes": [
        "research"
      ],
      "liveReason": null,
      "strategyNames": [
        "statarb_basket_perp"
      ],
      "installed": [
        {
          "path": "statarb_basket_perp/1",
          "name": "statarb_basket_perp",
          "version": "1",
          "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",
          "universe": [
            "BTC"
          ],
          "interval": "1h",
          "spotLegs": false,
          "generic": false,
          "minSymbols": 6,
          "maxSymbols": 6,
          "defaultUniverse": null,
          "liveCapable": false,
          "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",
          "liveCondition": null
        }
      ],
      "strategyInstalled": true,
      "rule": null,
      "labBacktest": {
        "wanted": [],
        "installed": [],
        "agentRunnable": false
      },
      "labStudies": [],
      "labVerdicts": [
        {
          "available": true,
          "kind": "strategy",
          "backtest": true,
          "name": "statarb_basket_perp",
          "version": "1",
          "strategy": "statarb_basket_perp/1",
          "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",
          "symbols": [
            "BTC"
          ],
          "where": "strategies",
          "installedHashMatches": true,
          "scope": "agent",
          "liveCapable": false,
          "deflatedSharpe": 0.000002855202061682034,
          "deflatedSharpeThreshold": 0.95,
          "significant": false,
          "trialsTested": 31,
          "ownTrials": 5,
          "testSharpeCi": [
            -18.476770725759938
          ],
          "splits": {
            "train": {
              "netReturn": -0.10170708254821714,
              "netSharpe": -7.182497476407538,
              "grossSharpe": -2.942848775728168,
              "maxDrawdown": 0.10170708254821714,
              "trades": 384,
              "stop": {
                "code": "total_loss",
                "reason": "total loss limit reached (10 % of the capital)",
                "ts": "2026-06-29T18:00:00+00:00"
              },
              "grossToNet": {
                "pricePnl": -42.47637,
                "funding": 0.286722681079791,
                "fees": 17.985133225783834,
                "liquidationPenalties": 0,
                "slippage": 4.3453824145459,
                "latency": 37.186919588967264,
                "netPnl": -101.70708254821716
              }
            },
            "validation": {
              "netReturn": -0.10328278271158842,
              "netSharpe": -10.506726964730408,
              "grossSharpe": 0.2656999138474378,
              "maxDrawdown": 0.10328278271158842,
              "trades": 870,
              "stop": {
                "code": "total_loss",
                "reason": "total loss limit reached (10 % of the capital)",
                "ts": "2026-09-25T08:00:00+00:00"
              },
              "grossToNet": {
                "pricePnl": 2.05459,
                "funding": 0.294203640074876,
                "fees": 34.364870451549976,
                "liquidationPenalties": 0,
                "slippage": 8.0428194421408,
                "latency": 63.22388645797256,
                "netPnl": -103.28278271158842
              }
            },
            "test": {
              "netReturn": -0.10165090743737748,
              "netSharpe": -11.067904972523419,
              "grossSharpe": 0.7338473369539557,
              "maxDrawdown": 0.1024842740501597,
              "trades": 851,
              "stop": {
                "code": "total_loss",
                "reason": "total loss limit reached (10 % of the capital)",
                "ts": "2026-11-04T16:00:00+00:00"
              },
              "grossToNet": {
                "pricePnl": 6.1472,
                "funding": -0.381330817681965,
                "fees": 37.63228249889594,
                "liquidationPenalties": 0,
                "slippage": 8.9354844276773,
                "latency": 60.84900969312219,
                "netPnl": -101.65090743737744
              }
            }
          },
          "stoppedSplits": [
            "train"
          ],
          "checks": {
            "lookahead": "pass",
            "data_quality": "pass",
            "ledger": "pass",
            "funding_alignment": "pass"
          },
          "window": {
            "start": "2026-05-19T00:00:00+00:00",
            "end": "2026-11-14T23:00:00+00:00",
            "interval": "1h",
            "bars": 4320
          },
          "splitDates": {
            "train": [
              "2026-05-19T00:00:00+00:00"
            ],
            "validation": [
              "2026-09-04T00:00:00+00:00"
            ],
            "test": [
              "2026-10-10T00:00:00+00:00"
            ]
          },
          "dataSha256": "060687f0fc9f948d28ce5c5fd39c32798b3c924c35e0a5bb879dceec408c00f5",
          "codeSha256": "6ea1cf4df5ceb8b33c0a763ca1c8724c76de60b861714597b73295ec89507356",
          "engineParityApplied": true,
          "results": {
            "dir": "research/results/2026-11-15-v11",
            "file": "statarb_basket_perp-1.json",
            "fileSha256": "745a629f00d35b8b76d0e0ea681a7dbe22501b74b86351e80fd23ab3ebe71f14",
            "matchesManifest": true
          }
        }
      ],
      "defaults": {
        "universe": [
          "BTC"
        ],
        "venues": [
          "hyperliquid"
        ],
        "interval": "1h",
        "capitalUsdc": "1000",
        "config": {},
        "risk": {
          "maxLeverage": 2,
          "maxGrossExposureX": 1.5,
          "maxPositionX": 1,
          "maxDailyLossPct": 3,
          "maxTotalLossPct": 10,
          "slippageBps": 30,
          "minTradePct": 2
        }
      }
    }
  ]
}
Response fields
Field Type Required Description
templates array of object yes
templates[].id string yes
templates[].family string yes
templates[].engine string yes
templates[].modes array of "research" | "paper" | "live" yes
templates[].liveReason string | null yes
templates[].strategyInstalled boolean yes

Errors

Status Codes
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

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

One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state. Operation id getAgent.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

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.

Parameters

Name In Type Required Description
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

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { agent } = await client.getAgent('b9180e9d-3977-403c-a072-9af105bfd59b');
python
agent = client.get_agent("b9180e9d-3977-403c-a072-9af105bfd59b").agent

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "name": "Docs funding",
    "mission": "",
    "kind": "stream",
    "family": "funding_arb",
    "template": "funding-arb",
    "engine": "stream",
    "state": "stopped",
    "phase": "CREATED",
    "mode": "research",
    "venue": "hyperliquid+dydx",
    "network": "hyperliquid+dydx",
    "universe": [
      "BTC"
    ],
    "interval": "stream",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxGrossUsd": 1000,
      "maxDataAgeMs": 5000,
      "maxPositionUsd": 500,
      "maxDailyLossPct": 2,
      "maxTotalLossPct": 5
    },
    "configVersion": 1,
    "strategy": {
      "name": "funding_differential",
      "version": "1",
      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "path": null,
      "status": "built_in",
      "kind": "rule"
    },
    "mandate": null,
    "pausedFrom": null,
    "live": {
      "capable": false,
      "code": "family_not_live",
      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "stopReason": null,
    "lastBar": null,
    "createdAt": 1794953757211,
    "updatedAt": 1794953757211,
    "familyModes": {
      "engine": "stream",
      "modes": [
        "research",
        "paper"
      ],
      "liveReason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "backtests": {
      "label": "backtest",
      "note": "A backtest is a simulation on historical data under stated assumptions. It is not a track record and is never shown as performance.",
      "versions": [],
      "recorded": null
    },
    "runtime": {
      "venues": [
        "hyperliquid",
        "dydx"
      ],
      "rule": "funding_differential",
      "config": {
        "notionalUsd": "250",
        "horizonHours": "24",
        "minNetCarryBps": "5",
        "decisionEveryMs": 60000,
        "exitNetCarryBps": "0"
      },
      "counters": null,
      "hold": null,
      "lastPass": null,
      "book": null
    },
    "worker": {
      "lease": null,
      "tick": null
    },
    "jobs": [],
    "killSwitch": {
      "engaged": false,
      "reason": null,
      "at": null,
      "by": null,
      "readOnly": false,
      "readOnlyReason": null,
      "release": {
        "route": "/risk",
        "passkey": true
      }
    }
  },
  "mandateDraft": {
    "draft": "agent:b9180e9d-3977-403c-a072-9af105bfd59b",
    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "family": "funding_arb",
    "approval": {
      "route": "/risk?mandate=agent:b9180e9d-3977-403c-a072-9af105bfd59b",
      "note": "the mandate is approved by the owner with the passkey; the signer judges the approval and enforces the mandate on every order"
    },
    "available": false,
    "code": "family_not_live",
    "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat",
    "fields": null
  }
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.family string yes
agent.state "active" | "paused" | "stopped" yes
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.
mandateDraft object | null yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

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

Signal history of one agent, ONE mode. Operation id listAgentSignals.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Each 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.

Parameters

Name In Type Required Description
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
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.
limit query integer 1…500 — rows returned at most — default 100
before query integer 0…9007199254740991 — unix ms: rows strictly before it

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/signals?mode=paper&limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { signals } = await client.listAgentSignals('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });
python
signals = client.list_agent_signals("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).signals

Example response — 200, recorded from a real server

json
{
  "mode": "paper",
  "signals": [
    {
      "id": "2",
      "ts": 1794953758433,
      "mode": "paper",
      "kind": "stream",
      "configVersion": 1,
      "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "inputsDigest": "ce04a27eb7d4a2a54c55ea9a63340283bc5ffb6cc7ff9aba8f86947ac273a1a4",
      "status": "done",
      "decision": "skipped",
      "reasonCode": "edge_below_threshold",
      "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",
      "output": {
        "a": {
          "id": "hyperliquid:BTC",
          "rate": "0.0000088903",
          "venue": "hyperliquid",
          "hourlyBps": 0.088903,
          "takerRate": 0.00045,
          "intervalSec": 3600
        },
        "b": {
          "id": "dydx:BTC-USD",
          "rate": "0.00000153333333333333",
          "venue": "dydx",
          "hourlyBps": 0.015333333333,
          "takerRate": 0.0005,
          "intervalSec": 3600
        },
        "legs": [],
        "action": "hold",
        "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",
        "feesBps": 19,
        "longVenue": "dydx",
        "reasonCode": "edge_below_threshold",
        "shortVenue": "hyperliquid",
        "netCarryBps": -17.234327999992,
        "grossCarryBps": 1.7656720000079997,
        "diffBpsPerHour": 0.07356966666699999
      },
      "scaled": null,
      "scale": null,
      "equity": "1000",
      "targets": null,
      "orders": null,
      "createdAt": 1794953758435,
      "updatedAt": 1794953758435
    },
    {
      "id": "1",
      "ts": 1794953757448,
      "mode": "paper",
      "kind": "stream",
      "configVersion": 1,
      "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "inputsDigest": null,
      "status": "hold",
      "decision": "skipped",
      "reasonCode": "data_gap",
      "reason": "hyperliquid:BTC: the stream is reconnecting",
      "output": null,
      "scaled": null,
      "scale": null,
      "equity": null,
      "targets": null,
      "orders": null,
      "createdAt": 1794953757449,
      "updatedAt": 1794953757449
    }
  ]
}
Response fields
Field Type Required Description
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.
signals array of object yes
signals[].id string yes
signals[].ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
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.
signals[].configVersion integer -9007199254740991…9007199254740991 yes
signals[].strategySha256 string yes
signals[].decision "pending" | "acted" | "skipped" yes
signals[].reasonCode string | null yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

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

Activity journal of one agent, ONE mode. Operation id listAgentJournal.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Decisions, orders, fills, errors, risk denials, mandate events and state changes, newest first.

Parameters

Name In Type Required Description
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
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.
limit query integer 1…500 — rows returned at most — default 100
before query integer 0…9007199254740991 — unix ms: rows strictly before it

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/journal?mode=paper&limit=3" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { entries } = await client.listAgentJournal('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 3 });
python
entries = client.list_agent_journal("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=3).entries

Example response — 200, recorded from a real server

json
{
  "mode": "paper",
  "entries": [
    {
      "id": "3",
      "ts": 1794953758433,
      "mode": "paper",
      "kind": "state",
      "severity": "info",
      "code": "data_ok",
      "title": "Data is fresh again: decisions resume",
      "body": "after 1 s (data_gap)",
      "data": null,
      "ref": null,
      "configVersion": 1
    },
    {
      "id": "2",
      "ts": 1794953757448,
      "mode": "paper",
      "kind": "hold",
      "severity": "warning",
      "code": "data_gap",
      "title": "Data gap: quoting and decisions paused",
      "body": "hyperliquid:BTC: the stream is reconnecting",
      "data": null,
      "ref": null,
      "configVersion": 1
    }
  ]
}
Response fields
Field Type Required Description
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.
entries array of object yes
entries[].id string yes
entries[].ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
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.
entries[].kind string yes
entries[].severity string yes
entries[].title string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

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

Order history of one agent, ONE mode, in the unified order states. Operation id listAgentOrders.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

The 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.

Parameters

Name In Type Required Description
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
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.
limit query integer 1…500 — rows returned at most — default 100
before query integer 0…9007199254740991 — unix ms: rows strictly before it
open query "true" | "false" — true: only the orders that are not final

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/orders?mode=paper&limit=2" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { orders } = await client.listAgentOrders('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });
python
orders = client.list_agent_orders("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).orders

Example response — 200, recorded from a real server. The recorded agent had placed no order yet.

json
{
  "mode": "paper",
  "orders": []
}
Response fields
Field Type Required Description
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.
orders array of object yes
orders[].id string yes
orders[].mode "paper" | "live" yes
orders[].instrument string yes
orders[].side string yes
orders[].state string yes unified order state (CREATED … FILLED, CANCELLED, REJECTED, FAILED, UNKNOWN)

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

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

Computed performance of one agent, ONE mode. Operation id getAgentPerformance.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Equity 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.

Parameters

Name In Type Required Description
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
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.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/performance?mode=paper" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const perf = await client.getAgentPerformance('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });
python
perf = client.get_agent_performance("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper")

Example response — 200, recorded from a real server. A figure that cannot be computed is { value: null, reason }, never zero.

json
{
  "points": 1,
  "from": 1794953700000,
  "to": 1794953700000,
  "periodsPerYear": null,
  "totalReturn": {
    "value": null,
    "reason": "fewer than two equity points"
  },
  "volatility": {
    "value": null,
    "reason": "fewer than two returns"
  },
  "sharpe": {
    "value": null,
    "reason": "fewer than two returns"
  },
  "sortino": {
    "value": null,
    "reason": "fewer than two returns"
  },
  "maxDrawdown": {
    "value": 0,
    "reason": null
  },
  "winRate": {
    "value": null,
    "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"
  },
  "profitFactor": {
    "value": null,
    "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"
  },
  "turnover": {
    "value": 0,
    "reason": null
  },
  "feesUsd": {
    "value": 0,
    "reason": null
  },
  "fundingUsd": {
    "value": 0,
    "reason": null
  },
  "slippageUsd": {
    "value": null,
    "reason": "simulated fills are at the quote or at the book price read by the decision"
  },
  "netPnlUsd": {
    "value": null,
    "reason": "fewer than two equity points"
  },
  "closedTrades": 0,
  "orders": 0,
  "warnings": [
    {
      "code": "small_sample",
      "message": "1 equity point(s): volatility, Sharpe and Sortino on fewer than 30 points say almost nothing"
    }
  ],
  "mode": "paper",
  "label": "PAPER — simulated orders and fills; no money moved",
  "equityCurve": [
    {
      "ts": 1794953700000,
      "equity": 1000
    }
  ]
}
Response fields
Field Type Required Description
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.
label string yes says which mode the figures are for; a backtest is never in this answer
points integer -9007199254740991…9007199254740991 yes
warnings array of object yes
warnings[].code string yes
warnings[].message string yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

# GET /api/v1/trading/jobs/{id}

One agent job (backtest, wind-down): status and result. Operation id getJob.

  • Permission: agents:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

Poll 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).

Parameters

Name In Type Required Description
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

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/jobs/72526d3e-9b2a-4f86-977b-07b6531868a8" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const { job } = await client.getJob('72526d3e-9b2a-4f86-977b-07b6531868a8');
python
job = client.get_job("72526d3e-9b2a-4f86-977b-07b6531868a8").job

Example response — 200, recorded from a real server

json
{
  "job": {
    "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",
    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "kind": "backtest",
    "status": "done",
    "deadLettered": false,
    "attempts": 1,
    "maxAttempts": 2,
    "runAt": 1794953761249,
    "error": null,
    "result": {
      "kind": "recorded_replay",
      "label": "backtest",
      "missing": 360,
      "warnings": [
        "0 recorded instant(s): far too few to conclude anything",
        "360 of 360 expected snapshots are missing in this window: the replay skipped them"
      ],
      "snapshots": 0
    },
    "createdAt": 1794953761249,
    "updatedAt": 1794953762380,
    "finishedAt": 1794953762380
  }
}
Response fields
Field Type Required Description
job object yes
job.id string yes
job.kind string yes
job.status "queued" | "running" | "done" | "failed" | "cancelled" yes
job.attempts integer -9007199254740991…9007199254740991 yes
label string —

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/agents/{id}/start

Start an agent in research, paper or live mode. Operation id startAgent.

  • Permission: agents:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

research 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
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.
agentId string — strategy operations only: the agent, when the version id alone does not name it — a UUID

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/start" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"mode":"paper"}'
ts
await client.startAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });
python
client.start_agent("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper")

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "name": "Docs funding",
    "mission": "",
    "kind": "stream",
    "family": "funding_arb",
    "template": "funding-arb",
    "engine": "stream",
    "state": "active",
    "phase": "PAPER_TRADING",
    "mode": "paper",
    "venue": "hyperliquid+dydx",
    "network": "hyperliquid+dydx",
    "universe": [
      "BTC"
    ],
    "interval": "stream",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxGrossUsd": 1000,
      "maxDataAgeMs": 5000,
      "maxPositionUsd": 500,
      "maxDailyLossPct": 2,
      "maxTotalLossPct": 5
    },
    "configVersion": 1,
    "strategy": {
      "name": "funding_differential",
      "version": "1",
      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "path": null,
      "status": "built_in",
      "kind": "rule"
    },
    "mandate": null,
    "pausedFrom": null,
    "live": {
      "capable": false,
      "code": "family_not_live",
      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "stopReason": null,
    "lastBar": null,
    "createdAt": 1794953757211,
    "updatedAt": 1794953757230
  }
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, owner_required, restricted
404 not_found
409 bad_report, bad_state, halted, idempotency_conflict, idempotency_in_progress, live_unavailable, mandate_required, no_report, no_strategy
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/agents/{id}/pause

Pause an agent. Operation id pauseAgent.

  • Permission: agents:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

No 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).

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
reason string — why, for the agent's journal — default "" · 0–200 characters

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/pause" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"documentation example"}'
ts
await client.pauseAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });
python
client.pause_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "name": "Docs funding",
    "mission": "",
    "kind": "stream",
    "family": "funding_arb",
    "template": "funding-arb",
    "engine": "stream",
    "state": "paused",
    "phase": "PAUSED",
    "mode": "paper",
    "venue": "hyperliquid+dydx",
    "network": "hyperliquid+dydx",
    "universe": [
      "BTC"
    ],
    "interval": "stream",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxGrossUsd": 1000,
      "maxDataAgeMs": 5000,
      "maxPositionUsd": 500,
      "maxDailyLossPct": 2,
      "maxTotalLossPct": 5
    },
    "configVersion": 1,
    "strategy": {
      "name": "funding_differential",
      "version": "1",
      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "path": null,
      "status": "built_in",
      "kind": "rule"
    },
    "mandate": null,
    "pausedFrom": "PAPER",
    "live": {
      "capable": false,
      "code": "family_not_live",
      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "stopReason": null,
    "lastBar": null,
    "createdAt": 1794953757211,
    "updatedAt": 1794953763760
  }
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 bad_state, idempotency_conflict, idempotency_in_progress
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/agents/{id}/stop

Stop an agent (always allowed). Operation id stopAgent.

  • Permission: agents:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Always 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
reason string — why, for the agent's journal — default "" · 0–200 characters

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/stop" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"reason":"documentation example"}'
ts
await client.stopAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });
python
client.stop_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")

Example response — 200, recorded from a real server

json
{
  "agent": {
    "id": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "name": "Docs funding",
    "mission": "",
    "kind": "stream",
    "family": "funding_arb",
    "template": "funding-arb",
    "engine": "stream",
    "state": "stopped",
    "phase": "STOPPED",
    "mode": "paper",
    "venue": "hyperliquid+dydx",
    "network": "hyperliquid+dydx",
    "universe": [
      "BTC"
    ],
    "interval": "stream",
    "capitalUsd": "1000",
    "riskLimits": {
      "maxGrossUsd": 1000,
      "maxDataAgeMs": 5000,
      "maxPositionUsd": 500,
      "maxDailyLossPct": 2,
      "maxTotalLossPct": 5
    },
    "configVersion": 1,
    "strategy": {
      "name": "funding_differential",
      "version": "1",
      "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",
      "path": null,
      "status": "built_in",
      "kind": "rule"
    },
    "mandate": null,
    "pausedFrom": "PAPER",
    "live": {
      "capable": false,
      "code": "family_not_live",
      "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"
    },
    "stopReason": "stopped by key:spk_0123456789ab: documentation example",
    "lastBar": null,
    "createdAt": 1794953757211,
    "updatedAt": 1794953763767
  },
  "windDown": null
}
Response fields
Field Type Required Description
agent object yes
agent.id string yes
agent.state "active" | "paused" | "stopped" yes
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.

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 bad_state, idempotency_conflict, idempotency_in_progress
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/agents/{id}/backtest

Run a backtest for an agent (asynchronous job). Operation id backtestAgent.

  • Permission: agents:manage
  • Idempotency-Key: required (8–100 characters). The same key with the same request returns the first answer; nothing runs twice
  • Side effects: yes — see the description

Bar 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.

Parameters

Name In Type Required Description
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

Request body (JSON; unknown fields are refused)

Field Type Required Description
versionId string — bar agents: the strategy version to backtest; default: the agent's current one — a UUID
hours integer 1…168 — stream agents: how many hours of recorded snapshots to replay

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/backtest" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"hours":1}'
ts
const { job } = await client.backtestAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { hours: 1 });
python
job = client.backtest_agent("b9180e9d-3977-403c-a072-9af105bfd59b", hours=1).job

Example response — 200, recorded from a real server

json
{
  "job": {
    "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",
    "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",
    "kind": "backtest",
    "status": "queued",
    "deadLettered": false,
    "attempts": 0,
    "maxAttempts": 2,
    "runAt": 1794953761249,
    "error": null,
    "result": null,
    "createdAt": 1794953761249,
    "updatedAt": 1794953761249,
    "finishedAt": null
  },
  "label": "backtest"
}
Response fields
Field Type Required Description
job object yes
job.id string yes
job.kind string yes
job.status "queued" | "running" | "done" | "failed" | "cancelled" yes
job.attempts integer -9007199254740991…9007199254740991 yes
label string —

Errors

Status Codes
400 bad_request, idempotency, stale_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials, restricted
404 not_found
409 idempotency_conflict, idempotency_in_progress, no_strategy, wrong_kind
429 auth_throttled, rate_limited
500 internal

# Risk

The 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).

# GET /api/v1/trading/risk

Risk state: kill switch, signer limits, capability locks, account policies. Operation id getRisk.

  • Permission: positions:read
  • Idempotency-Key: not used
  • Side effects: none (a read)

What 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.

Example request

bash
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/risk" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY"
ts
const risk = await client.getRisk();
if (risk.engine.killSwitch.on) console.log('no new risk until the owner releases it');
python
risk = client.get_risk()
if risk.engine.kill_switch.on:
    print("no new risk until the owner releases it")

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.

json
{
  "killSwitch": {
    "signerReachable": true,
    "signerHalted": false,
    "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…"
  },
  "signerPolicy": {
    "perTx": {
      "ethereum:ETH": "25000000000000000",
      "ethereum:USDC": "50000000",
      "ethereum:USDT": "50000000",
      "ethereum:PYUSD": "50000000"
    },
    "daily": {
      "ethereum:ETH": "50000000000000000",
      "ethereum:USDC": "100000000",
      "ethereum:USDT": "100000000",
      "ethereum:PYUSD": "100000000"
    },
    "maxFee": {
      "ethereum": "5000000000000000",
      "base": "300000000000000",
      "arbitrum": "300000000000000",
      "optimism": "300000000000000"
    },
    "spentToday": {}
  },
  "capabilityLocks": [
    {
      "id": "deriv_live_mainnet",
      "on": false,
      "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…"
    }
  ],
  "accounts": [
    {
      "mode": "paper",
      "venue": "hyperliquid",
      "network": "mainnet",
      "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",
      "policy": {
        "mode": "PAPER",
        "allowedInstruments": [
          "hyperliquid:BTC"
        ],
        "halt": null,
        "maxDataAgeMs": 10000,
        "maxDeviationBps": "200",
        "maxMarkIndexBps": "100",
        "maxLeverage": "3",
        "maxOrderNotional": "10000",
        "maxGrossExposure": "30000",
        "maxPositionNotional": "20000",
        "minFreeCollateral": "1000",
        "minLiquidationDistanceBps": "1000",
        "maxDailyLoss": "500",
        "maxTotalLoss": "2000",
        "maxOrdersPerMinute": 60,
        "maxOrdersPerDay": 200
      },
      "halted": null,
      "halt": null
    }
  ],
  "key": {
    "limits": {
      "maxOrderNotionalUsd": null,
      "maxDailyNotionalUsd": null
    },
    "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",
    "limitsEnforced": true,
    "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"
  },
  "errors": [],
  "ts": 1794953728201,
  "engine": {
    "killSwitch": {
      "on": false,
      "at": null,
      "by": null,
      "reason": null
    },
    "readOnly": {
      "on": false,
      "at": null,
      "by": null,
      "reason": null
    },
    "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."
  }
}
Response fields
Field Type Required Description
killSwitch object yes
killSwitch.signerReachable boolean yes
killSwitch.signerHalted boolean | null yes
killSwitch.note string yes
signerPolicy object | null yes
capabilityLocks array of object yes
capabilityLocks[].id string yes
capabilityLocks[].on boolean yes
capabilityLocks[].why string yes
accounts array of object yes
accounts[].mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
accounts[].venue string yes
accounts[].accountId string yes
accounts[].policy object | null yes
accounts[].halted boolean | null yes
errors array of object yes
errors[].source string yes
errors[].message string yes
ts integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
engine object yes the global switches of the risk engine: killSwitch.on blocks every new risk; readOnly.on lets only cancels pass
engine.killSwitch Switch yes
engine.readOnly Switch yes
engine.note string yes

Errors

Status Codes
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# POST /api/v1/trading/risk/kill-switch

Engage the global kill switch. Operation id engageKillSwitch.

  • Permission: positions:manage
  • Idempotency-Key: not used
  • Side effects: yes — see the description

Blocks 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.

Request body (JSON; unknown fields are refused)

Field Type Required Description
reason string — why, for the audit trail and the risk.kill_switch webhook — default "" · 0–200 characters

Example request

bash
curl -s -X POST "$SP_WALLET_BASE_URL/api/v1/trading/risk/kill-switch" \
  -H "Authorization: Bearer $SP_WALLET_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"reason":"documentation example"}'
ts
await client.engageKillSwitch('bot detected a runaway loop');
python
client.engage_kill_switch("bot detected a runaway loop")

Example response — 200, recorded from a real server. A key can engage it and can never release it.

json
{
  "killSwitch": {
    "on": true,
    "at": 1794953765956,
    "by": {
      "kind": "api_key",
      "id": "spk_0123456789ab"
    },
    "reason": "documentation example"
  },
  "readOnly": {
    "on": false,
    "at": null,
    "by": null,
    "reason": null
  }
}
Response fields
Field Type Required Description
killSwitch Switch yes
readOnly Switch yes

Errors

Status Codes
400 bad_request
401 unauthenticated
403 insufficient_scope, ip_not_allowed, mixed_credentials
429 auth_throttled, rate_limited
500 internal

# Objects

Shapes the answers share (#/components/schemas/<name> in the OpenAPI document).

# Error

Field Type Required Description
error string yes stable machine code: one of the operation's x-spw-errors
message string yes human-readable sentence (English)
candidates array of string — ambiguous_symbol: the venue:symbol ids the bare symbol could mean
data object — machine-readable detail of a refusal
data.order Order — the order the refusal is about, when one exists (state REJECTED or FAILED)
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
data.failed array of string — risk_denied, kill_switch_active, read_only_mode: ids of the failed risk checks
data.checks array of RiskCheck — the failed risk checks, each with what was observed and its limit
data.decisionId integer -9007199254740991…9007199254740991 —
data.questions array of object — ambiguous_command: what the command and the owner's defaults leave open
data.code string — parse_error: the grammar's own code
data.token integer -9007199254740991…9007199254740991 — parse_error: index of the offending token

# Order

Field Type Required Description
id string yes the id every order operation takes
mode "paper" | "live" yes paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.
venue string yes
network string yes
accountId string | null yes
instrument string | null yes
side string | null yes
type string yes
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
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
final boolean yes true exactly when status is FILLED, CANCELLED, REJECTED or FAILED
size string | null —
price string | null —
triggerPrice string | null —
reduceOnly boolean —
tif string —
filled string — cumulative filled size, base units
avgFillPrice string | null —
reasonCode string | null — closed reason code of the current state (state machine)
reason string | null — sentence for people
rejectCode string | null — API error code of the refusal, when the order was refused
clientOrderId string | null —
orderId string —
origin string —
mandateId string | null —
notionalUsd string | null —
createdAt integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
updatedAt integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

# CanonicalOrder

the canonical order SPW-ORDER-INTENT-v1: what is hashed, checked by the mandate and the risk engine, and handed to the engine

Field Type Required Description
v 1 yes
venue string yes
network string yes
instrument string yes
marketKind "spot" | "perp" yes
side "buy" | "sell" yes
type "market" | "limit" | "stop" | "take_profit" yes
size string | null yes
notional string | null yes
limitPrice string | null yes
triggerPrice string | null yes
reduceOnly boolean yes
tif string yes
maxSlippageBps integer -9007199254740991…9007199254740991 yes
maxFeeUsd string yes decimal number as a string (never a float)
leverage string | null yes
clientOrderId string yes
mode "research" | "paper" | "live" yes
principal object yes
principal.kind "owner" | "agent" | "api_key" yes
principal.id string yes
mandateId string | null yes
createdAt integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch
expiresAt integer -9007199254740991…9007199254740991 yes milliseconds since the Unix epoch

# RiskCheck

Field Type Required Description
id string yes one of x-spw-risk-checks
ok boolean yes
observed string | null yes
limit string | null yes
detail string yes
exempt boolean yes

# Switch

Field Type Required Description
on boolean yes
at integer -9007199254740991…9007199254740991 | null yes
by object | null yes
by.kind string yes
by.id string yes
reason string | null yes

# Error catalogue

Every 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.

Code Status Meaning What to do
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.
account_required 409 The wallet has several accounts on this venue in this mode. Name one with accountId (GET /portfolio lists them).
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.
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.
ambiguous_position 409 The wallet holds a long and a short on this GMX market. Name the position by its key.
ambiguous_symbol 409 A bare symbol (BTC) exists on several venues. Name one of candidates as venue:symbol (e.g. hyperliquid:BTC).
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).
authorization_expired 422 The venue authorization of the account has expired. The owner approves a new one with the passkey.
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.
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.
bad_mark 422 The mark price is not positive. Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key.
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.
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.
bad_report 409 The backtest report disqualifies this version: it cannot run, even on paper. Register another version.
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.
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.
bad_strategy 422 The laboratory refused the strategy file. Read message; pick a path from GET /strategies (library).
below_min_notional 422 The order is worth less than the venue's minimum. Raise it above minNotional.
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}.
cancel_in_app 422 This order is cancelled in the app (a spot agent's swap, a GMX order). Do it in the app.
close_in_app 422 A GMX position is closed by a wallet transaction approved with the passkey. Do it in the app.
daily_loss_exceeded 422 The account's daily loss limit is reached. No new risk today; reductions pass.
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.
duplicate_client_id 422 This client order id was already used on the account. Use a new clientOrderId / Idempotency-Key for a new order.
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.
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.
exists 409 A risk-management (supervisor) agent already exists. Stop it before creating another.
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).
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.
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.
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.
gross_exposure_exceeded 422 The resulting gross exposure exceeds the account policy. Reduce first, or send a smaller order.
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.
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.
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.
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.
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.
instrument_halted 422 The venue has halted this instrument. Nothing to do until the venue reopens it.
instrument_mismatch 422 The account is on one venue and the instrument on another. Name the account of the instrument's venue.
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.
instrument_reduce_only 422 The venue only accepts orders that reduce a position on this instrument. Send reduce-only orders.
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.
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.
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.
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.
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.
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.
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).
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.
leverage_exceeded 422 The leverage is above the authorized maximum (policy, mandate or venue). Lower it.
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.
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.
live_not_available 422 A paper account can only be PAPER or READ_ONLY. Use a venue account for live.
live_unavailable 409 This agent family cannot go live (the message says why). Run it on paper.
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.
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.
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.
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.
mandate_mismatch 422 The mandate was approved for another strategy version or another agent. The owner approves a mandate for this one.
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.
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.
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.
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.
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.
mark_index_divergence 422 Mark and index prices are further apart than the policy allows. Retry later.
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.
missing_balance 422 A percentage of a balance was asked and the balance could not be read. Retry, or name an absolute quantity.
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.
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.
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.
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.
nft_budget_exhausted 429 The wallet's own request budget for a metered provider is spent for now. Retry later; do not poll.
nft_disabled 503 The NFT module is switched off on this server. The server operator enables it.
nft_not_found 404 The chain does not know this item. Check network, address and token id.
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.
nft_provider_disagreement 502 Sources disagree on a fact the answer needs. Read GET /nfts/market: each source is on its own row.
nft_provider_method_unsupported 503 The provider cannot answer this kind of question for this network. Nothing to do.
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.
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.
nft_provider_unavailable 503 A provider is down. Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key.
nft_unsupported_chain 422 No NFT adapter for this network. Use Solana or one of the EVM networks.
nft_unsupported_standard 422 The contract is not an NFT standard this wallet reads. Nothing to do.
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.
no_client_id_format 422 The venue has no client-order-id format this wallet can derive. Use a venue the wallet trades.
no_instrument 422 The command names an asset no instrument of the catalogue matches (on that venue/network). Check the asset and the venue.
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.
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.
no_position 422 There is no open position to close or reduce on that instrument and account. Read GET /positions first.
no_report 409 The strategy version has no backtest report. Run POST /strategies/{id}/backtest and wait for the job.
no_strategy 409 The agent has no approved strategy version. Register one with POST /strategies and let its backtest finish.
not_a_private_market 404 The instrument exists and is not a private-company contract. Read it with GET /markets/{symbol}.
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.
not_reducing 422 The order would not strictly reduce an existing position: nothing was placed. Read GET /positions; the position may already be closed.
not_your_order 403 A key cancels its own orders only. The owner cancels anything, in the app.
order_notional_exceeded 422 The order is above the account policy's notional per order. Send a smaller order.
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.
order_rate_minute 422 Too many orders on this account in the last minute (account policy). Slow down.
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.
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.
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.
paper_unsupported 422 The venue has no order book, so the paper engine cannot fill against it (GMX). Paper-trade on Hyperliquid.
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.
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.
position_notional_exceeded 422 The resulting position exceeds the account policy for the instrument. Send a smaller order.
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}.
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.
price_required 422 A limit order needs price (a market order needs a worst acceptable price, which the server derives). Add price.
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.
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.
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.
reduce_only_would_increase 422 A reduce-only order would open or increase a position. Check the side and the position.
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).
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.
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.
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.
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.
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.
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.
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".
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.
spot_via_swap_screen 422 An owner's spot order is a swap proposal approved with the passkey. Prepare it in the Swap screen.
stale_book 422 The order book is older than the account policy allows. Retry in a few seconds.
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.
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.
stale_ticker 422 The venue ticker is older than the account policy allows (maxDataAgeMs). Retry in a few seconds.
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.
swap_flow_failed 502 The swap flow returned no proposal. Retry; if it lasts, prepare the swap in the app to see the reason.
swap_not_enabled 422 The wallet does not execute swaps on this network. Use a network where swaps are enabled.
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.
trigger_required 422 A stop or take-profit order needs triggerPrice. Add triggerPrice.
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.
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.
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).
unknown_company 404 No reviewed private-company contract under this slug. Take slugs from GET /private-markets (companies).
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.
unknown_market 404 A spot symbol without data, or a bare symbol nothing answers to. Take the id from GET /markets.
unknown_network 404 The network id is not one of the wallet's. Take network ids from GET /balances.
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.
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.
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.
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.
unknown_underlying 404 No perpetual is mapped to this underlying in the comparator. Use an underlying that GET /markets lists as a base.
unknown_venue 404 The venue id is not one this wallet knows (hyperliquid, gmx, dydx, edgex, spot). List the ids with GET /markets.
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.
unsupported_interval 422 Spot market data does not store this candle interval. Use one of the intervals the message lists.
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.
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.
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.
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.
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.
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.
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.
zero_size 422 The quantity resolves to zero. Raise the amount.

  1. A-Za-z0-9 ↩︎

  2. a-z0-9- ↩︎

  3. a-z ↩︎

  4. A-Za-z0-9_- ↩︎

  5. A-Za-z0-9_- ↩︎

  6. a-z ↩︎

  7. a-z,- ↩︎

  8. A-Za-z0-9_- ↩︎

  9. A-Za-z0-9._:- ↩︎

  10. A-Za-z0-9._:- ↩︎

Files main
Menu

Theme