SP Trading API — reference
Generated by
npx tsx scripts/gen-openapi.mtsfromservices/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 atGET /api/v1/trading/docs(HTML) andGET /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
- Getting started in five minutes
- Démarrage rapide (français)
- Authentication and permissions
- Decimals, timestamps, identifiers
- Instruments and venues
- Paper and live, the execution lock
- Mandates
- Why an order is refused
- Order states
- Idempotency
- Pagination
- Rate limits
- Errors
- Commands
- Webhooks
- Streaming (websocket)
- Operations
- Meta —
getOpenApi - Markets —
listMarkets,compareMarkets,getMarket,getOrderbook,getCandles,listPrivateMarkets,getPrivateMarketCompany,getPrivateMarket - Portfolio —
getPortfolio,getBalances,getActivity - Nfts —
listNfts,getNft,getNftActivity,getNftMarket,getNftMarketEvents - Positions —
listPositions,closePosition,reducePosition - Orders —
listOrders,placeOrder,getOrder,cancelOrder,previewOrder,runCommand - Strategies —
listStrategies,createStrategy,backtestStrategy,startStrategy,stopStrategy - Agents —
listAgents,createAgent,listAgentTemplates,getAgent,listAgentSignals,listAgentJournal,listAgentOrders,getAgentPerformance,getJob,startAgent,pauseAgent,stopAgent,backtestAgent - Risk —
getRisk,engageKillSwitch
- Meta —
- Objects
- Error catalogue
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 addorders:prepare,orders:execute,orders:cancelandpositions: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
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"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);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){
"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:
# 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/python3. First paper order
An order placed with a key needs three things, which only the owner can set up:
- a paper account on Hyperliquid — app: Futures → Accounts;
- 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; - the mandate bound to the key. Without it,
orders:executeis inert and the API answers:
{
"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": "…" } }thenPOST /api/v1/developer/keys/{id}/update{ intentId, assertion }(a passkey assertion; binding widens the key). No screen calls it yet.
Then:
# 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"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-onlyfrom 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-onlyThe 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:
{
"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
- Why an order is refused — the three gates and every code.
- Idempotency before you write a retry loop.
- Paper and live before the first real order.
- The machine-readable contract:
openapi.json; this page as Markdown:docs.md.
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, ajoutezorders:prepare,orders:execute,orders:canceletpositions: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
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"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);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 :
- un compte simulé sur Hyperliquid — application : Contrats à terme → Comptes ;
- 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 ; - le mandat lié à la clé. Sans lui,
orders:executeest inerte et l'API répond403 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/preparepuisPOST /api/v1/developer/keys/{id}/update(assertion de la clé d'accès). Aucun écran ne les appelle pour l'instant.
Ensuite :
# 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"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-onlyfrom 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-onlyUn 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.
GET /api/v1/trading/markets HTTP/1.1
Host: wallet.spboucher.ai
Authorization: Bearer spw_live_spk_0123456789ab_EXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLEEXAMPLE0The 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:
{
"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:
{
"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
restrictedorip_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,atof a switch — markets, orders, positions, agents, risk; - ISO 8601 UTC strings:
asOf(portfolio, balances, NFTs),atof an activity item,priceAt,fetchedAt, thetsof 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:
{
"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:
{
"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:
{
"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
- An authorized Hyperliquid venue account (app: Futures → Accounts, passkey).
- A live trading mandate for the key, approved with the passkey, and bound to the key.
- 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.
- 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:
{
"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:
{
"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:managecan engage it (POST /risk/kill-switch) and cannot release it. Read-only mode lets only cancels pass. Neither is the signer's emergency halt (423halted), 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:
{
"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.
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, FAILEDstatus |
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
statusandfinal.engineStatusis the executing engine's own word for the same moment, for information. UNKNOWNis 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
FILLEDwithout an event that comes from the venue (or the paper engine). reasonCodeis the closed reason of the current state;rejectCodeis the API error code of the refusal;reasonis 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 byslippageBps(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 |
{
"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:
clientOrderIdin the body (default: the Idempotency-Key). The order id is derived from it and from the principal, so the sameclientOrderIdis the same order for ever —idempotent: truein 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 (400stale_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.
{
"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/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_throttledwithRetry-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:
{
"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:
{
"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):
{
"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.
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 KILLFrench 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:preparewithdryRun), CLOSEpositions:manage, CANCELorders:cancel, SHOW the matching read scope, KILLpositions:manage. dryRun: trueanswers 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:
{
"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:
{
"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
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.
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();
}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# 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-Deliveryis 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.seqoforder.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.
wss://wallet.spboucher.ai/api/v1/trading/stream- Scope:
markets:read. The key goes in theAuthorizationheader 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.
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)' : '');
}# 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.
// 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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/openapi.json" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const doc = await client.openapi();doc = client.openapi()Example response — 200, written from the schema (not recorded). Cut: the real document describes every operation, schema and error code.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });markets = client.list_markets(venue="hyperliquid", q="BTC", limit=3).marketsExample response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/compare?underlying=BTC&side=long¬ional=1000&leverage=2" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const cmp = await client.compareMarkets({ underlying: 'BTC', side: 'long', notional: '1000', leverage: '2' });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.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { instrument, ticker } = await client.getMarket('hyperliquid:BTC');market = client.get_market("hyperliquid:BTC")Example response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/orderbook?depth=3" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const book = await client.getOrderbook('hyperliquid:BTC', { depth: 3 });book = client.get_orderbook("hyperliquid:BTC", depth=3)Example response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/candles?interval=1h&limit=3" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { candles } = await client.getCandles('hyperliquid:BTC', { interval: '1h', limit: 3 });candles = client.get_candles("hyperliquid:BTC", interval="1h", limit=3).candlesExample response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { markets, companies } = await client.listPrivateMarkets();private = client.list_private_markets()Example response — 200, recorded from a real server. Cut to one market. Display only: tradable is always false.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/private-markets/companies/anthropic" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const company = await client.getPrivateMarketCompany('anthropic');company = client.get_private_market_company("anthropic")Example response — 200, recorded from a real server. Cut to one contract.
{
"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
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"const pm = await client.getPrivateMarket('hyperliquid:io:ANTH', { interval: '1d', limit: 3 });pm = client.get_private_market("hyperliquid:io:ANTH", interval="1d", limit=3)Example response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/portfolio" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const portfolio = await client.getPortfolio();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.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/balances?network=base" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { balances } = await client.getBalances({ network: 'base' });balances = client.get_balances(network="base").balancesExample response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/activity?limit=2" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const page = await client.getActivity({ limit: 2 });
for await (const item of client.iterateActivity()) console.log(item.kind, item.at); // every pagepage = 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
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts?limit=2" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { items, nextCursor } = await client.listNfts({ limit: 2 });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.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/item?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { nft } = await client.getNft('evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1');nft = client.get_nft("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1").nftExample response — 200, written from the schema (not recorded)
{
"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
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"const { events } = await client.getNftActivity({ key: 'evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1', limit: 2 });events = client.get_nft_activity("evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1", limit=2).eventsExample 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.
{
"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
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/nfts/market?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const market = await client.getNftMarket({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1' });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.
{
"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
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
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"const { sources } = await client.getNftMarketEvents({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1', type: 'sale', limit: 2 });sources = client.get_nft_market_events(network="ethereum", address="0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D", token_id="1", type="sale", limit=2).sourcesExample 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.
{
"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
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { positions } = await client.getPositions({ mode: 'paper' });positions = client.get_positions(mode="paper").positionsExample response — 200, recorded from a real server. A position id contains colons: URL-encode it in a path (both SDKs do).
{
"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 (403mandate_requiredotherwise) - 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
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 '{}'const closed = await client.closePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC');closed = client.close_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC")Example response — 200, recorded from a real server
{
"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)
POST /api/v1/trading/positions/{id}/reduce
Reduce a position. Operation id reducePosition.
- Permission:
positions:manage— and a trading mandate bound to the key (403mandate_requiredotherwise) - 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
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"}'const reduced = await client.reducePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC', { fraction: '0.5' });reduced = client.reduce_position("paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC", fraction="0.5")Example response — 200, recorded from a real server
{
"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)
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders?open=true&limit=5" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"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 pagepage = 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
{
"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 (403mandate_requiredotherwise) - 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
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"}'const placed = await client.createOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' }, { idempotencyKey: 'bot-2026-11-17-0001' });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.
{
"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)
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { order, fills } = await client.getOrder('0xff18683e8e2aa319d3812cf8a47fc261');
const done = await client.waitForOrder('0xff18683e8e2aa319d3812cf8a47fc261'); // polls until final; UNKNOWN keeps waitingdetail = client.get_order("0xff18683e8e2aa319d3812cf8a47fc261")
done = client.wait_for_order("0xff18683e8e2aa319d3812cf8a47fc261") # polls until final; UNKNOWN keeps waitingExample response — 200, recorded from a real server. Fills and history cut to two entries.
{
"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
curl -s -X DELETE "$SP_WALLET_BASE_URL/api/v1/trading/orders/0x0276bab16d117c8323ee375b61b01d1d" \
-H "Authorization: Bearer $SP_WALLET_API_KEY" \
-H "Idempotency-Key: $(uuidgen)"const { order, changed } = await client.cancelOrder('0x0276bab16d117c8323ee375b61b01d1d');cancelled = client.cancel_order("0x0276bab16d117c8323ee375b61b01d1d")Example response — 200, recorded from a real server. Cancelling again answers 200 with changed: false.
{
"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
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"}'const preview = await client.previewOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' });
if (!preview.wouldExecute) console.log(preview.refusals);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.
{
"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
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
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}'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);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).
{
"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:
- 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 |
- 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 |
— |
- 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 |
- 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)
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/strategies?kind=perp" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { library, versions } = await client.listStrategies({ kind: 'perp' });strategies = client.list_strategies(kind="perp")Example response — 200, recorded from a real server. Cut to one library entry and one version.
{
"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
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"}'const { strategy } = await client.createStrategy({ kind: 'perp', path: 'strategies/momentum_xs_perp/2', agentId: 'fa9c1fd9-a005-4825-bd67-ea180a2eb83d' });strategy = client.create_strategy(kind="perp", path="strategies/momentum_xs_perp/2", agent_id="fa9c1fd9-a005-4825-bd67-ea180a2eb83d").strategyExample response — 200, recorded from a real server
{
"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
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 '{}'const { job } = await client.backtestStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e');
const done = await client.waitForJob(job.id);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
{
"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
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"}'await client.startStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { mode: 'paper' });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).
{
"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
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"}'await client.stopStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { reason: 'documentation example' });client.stop_strategy("450bc266-e1a9-4807-9113-7da6773ddb4e", reason="documentation example")Example response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { agents } = await client.listAgents();agents = client.list_agents().agentsExample response — 200, recorded from a real server
{
"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
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"}'const { agent } = await client.createAgent({ template: 'funding-arb', name: 'Docs funding', mode: 'research' });agent = client.create_agent(template="funding-arb", name="Docs funding", mode="research").agentExample response — 200, recorded from a real server
{
"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
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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/templates" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { templates } = await client.listAgentTemplates();templates = client.list_agent_templates().templatesExample response — 200, recorded from a real server. Cut to one of the seven templates.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { agent } = await client.getAgent('b9180e9d-3977-403c-a072-9af105bfd59b');agent = client.get_agent("b9180e9d-3977-403c-a072-9af105bfd59b").agentExample response — 200, recorded from a real server
{
"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
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"const { signals } = await client.listAgentSignals('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });signals = client.list_agent_signals("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).signalsExample response — 200, recorded from a real server
{
"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
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"const { entries } = await client.listAgentJournal('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 3 });entries = client.list_agent_journal("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=3).entriesExample response — 200, recorded from a real server
{
"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
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"const { orders } = await client.listAgentOrders('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });orders = client.list_agent_orders("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper", limit=2).ordersExample response — 200, recorded from a real server. The recorded agent had placed no order yet.
{
"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
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"const perf = await client.getAgentPerformance('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });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.
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/jobs/72526d3e-9b2a-4f86-977b-07b6531868a8" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const { job } = await client.getJob('72526d3e-9b2a-4f86-977b-07b6531868a8');job = client.get_job("72526d3e-9b2a-4f86-977b-07b6531868a8").jobExample response — 200, recorded from a real server
{
"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
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"}'await client.startAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });client.start_agent("b9180e9d-3977-403c-a072-9af105bfd59b", mode="paper")Example response — 200, recorded from a real server
{
"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
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"}'await client.pauseAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });client.pause_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")Example response — 200, recorded from a real server
{
"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
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"}'await client.stopAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });client.stop_agent("b9180e9d-3977-403c-a072-9af105bfd59b", reason="documentation example")Example response — 200, recorded from a real server
{
"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
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}'const { job } = await client.backtestAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { hours: 1 });job = client.backtest_agent("b9180e9d-3977-403c-a072-9af105bfd59b", hours=1).jobExample response — 200, recorded from a real server
{
"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
curl -s "$SP_WALLET_BASE_URL/api/v1/trading/risk" \
-H "Authorization: Bearer $SP_WALLET_API_KEY"const risk = await client.getRisk();
if (risk.engine.killSwitch.on) console.log('no new risk until the owner releases it');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.
{
"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
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"}'await client.engageKillSwitch('bot detected a runaway loop');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.
{
"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.