SP Trading API — TypeScript SDK (@sp-wallet/trading-sdk)
Official client of the SP Trading API (/api/v1/trading, contract: docs/openapi/trading-v1.json,
reference: docs/TRADING-API-OPENAPI.md). Source: packages/trading-sdk/.
- Zero runtime dependency: global
fetchand WebCrypto. Node ≥ 20 and browsers. ESM + type declarations. - Every answer is typed; the types are generated from the OpenAPI document (
scripts/gen-types.mts), and a test fails when the committed types are not what the document gives. - Money, prices and sizes are decimal strings end to end. The SDK never converts them to a
number. - The API key is never logged, never part of an error, never shown by
console.log(client).
Execution requires an owner-approved mandate. Placing an order and closing or reducing a position need — besides the scope — an API key bound to a trading mandate approved by the wallet's owner. Without one the API refuses the call (
403 mandate_required→MandateRequired); an order outside the mandate isMandateDenied. A scope alone never lets a key execute. Managing agents and strategies needs no mandate on the key (research and paper sign nothing): an agent goes live only under its own mandate, approved by the owner.State of the API in this version. All 46 operations of the contract are implemented and answer typed results. Paper orders are simulated by the wallet's paper engine against the venue's real order book. Live orders additionally need
SPW_TRADING_API_EXECUTION=onon the server (default off →403 execution_disabled→ExecutionDisabled) and the wallet's mainnet locks. Spot orders and live GMX orders are the owner's (passkey): a key is refused them.
Install (from the repository)
The package is not published to npm. Build it, then install it from its path:
node packages/trading-sdk/scripts/build.mts # → packages/trading-sdk/dist (index.js + *.d.ts)
npm install /path/to/sp-wallet/packages/trading-sdk # in your projectInside this monorepo, import the sources directly: import { SPWallet } from '@sp-wallet/trading-sdk/src'
(or a relative path, as the examples do).
Quick start
import { SPWallet } from '@sp-wallet/trading-sdk';
const client = new SPWallet({ apiKey: process.env.SP_WALLET_API_KEY }); // or just `new SPWallet()`
const balances = await client.getBalances();
const positions = await client.getPositions();
const preview = await client.previewOrder({ exchange: 'hyperliquid', symbol: 'BTC', side: 'buy', type: 'market', notionalUsdc: 100 });
if (preview.wouldExecute) {
const placed = await client.createOrder({ exchange: 'hyperliquid', symbol: 'BTC', side: 'buy', type: 'market', notionalUsdc: 100 }); // mode: 'paper' by default
const { order } = await client.waitForOrder(placed.order.id); // FILLED, CANCELLED, REJECTED or FAILED
}| Option | Default | |
|---|---|---|
apiKey |
env SP_WALLET_API_KEY |
spw_live_…, created by the owner in the Developer screen |
baseUrl |
env SP_WALLET_BASE_URL, else https://wallet.spboucher.ai |
http:// is accepted for localhost only (or with allowInsecureHttp) |
timeoutMs |
30000 |
per attempt |
maxRetries |
2 |
retries after the first attempt |
userAgent |
— | appended to sp-wallet-typescript/<version> |
sendTimestamp |
false |
send X-SPW-Timestamp with mutating calls (the server refuses a call more than 300 s from its clock) |
maxRetryDelayMs |
30000 |
longest wait accepted before a retry; a 429 asking for more is thrown at once |
fetch |
globalThis.fetch |
Each method takes a last argument { timeoutMs, maxRetries, signal } (and idempotencyKey for the mutating ones).
Methods
| Method | Operation | Scope |
|---|---|---|
listMarkets({ venue, kind, q, limit }) |
GET /markets |
markets:read |
compareMarkets({ underlying, side, notional, leverage, horizonHours, liquidity, minNetEdgeBps }) |
GET /markets/compare |
markets:read |
getMarket(symbol) |
GET /markets/{symbol} |
markets:read |
getOrderbook(symbol, { depth }) |
GET /markets/{symbol}/orderbook |
markets:read |
getCandles(symbol, { interval, limit }) |
GET /markets/{symbol}/candles |
markets:read |
listPrivateMarkets({ delisted, size, side }) |
GET /private-markets |
markets:read |
getPrivateMarket(id, { size, side, interval, limit }) |
GET /private-markets/{id} |
markets:read |
getPrivateMarketCompany(slug, { … }) |
GET /private-markets/companies/{slug} |
markets:read |
getPortfolio() |
GET /portfolio |
wallet:read |
getBalances({ network }) |
GET /balances |
wallet:read |
getActivity({ limit, cursor }), iterateActivity({ limit }, { maxItems }) |
GET /activity |
wallet:read |
listNfts({ network, collection, status, q, sort, spam, limit, cursor }), iterateNfts({ … }, { maxItems }) |
GET /nfts |
wallet:read |
getNft(key) |
GET /nfts/item |
wallet:read |
getNftActivity({ key, limit, cursor, type }) |
GET /nfts/activity |
wallet:read |
getNftMarket({ network, address, tokenId }) |
GET /nfts/market |
markets:read |
getNftMarketEvents({ network, address, tokenId, provider, type, after, before, cursor, limit }) |
GET /nfts/market/events |
markets:read |
getPositions({ mode, venue }) |
GET /positions |
positions:read |
getRisk() |
GET /risk |
positions:read |
engageKillSwitch(reason) |
POST /risk/kill-switch |
positions:manage (no mandate) |
listOrders({ mode, venue, open, limit, cursor }), iterateOrders({ … }, { maxItems }) |
GET /orders |
orders:read |
getOrder(id) |
GET /orders/{id} |
orders:read |
waitForOrder(id, { waitTimeoutMs, pollIntervalMs, until }) |
polls GET /orders/{id} |
orders:read |
previewOrder(order) → OrderPreview |
POST /orders/preview |
orders:prepare (a key needs a mandate bound to it) |
createOrder(order) → PlacedOrder |
POST /orders |
orders:execute + mandate |
cancelOrder(id) → CancelledOrder |
DELETE /orders/{id} |
orders:cancel (its own orders; no mandate) |
closePosition(id, { slippageBps }) → PlacedOrder |
POST /positions/{id}/close |
positions:manage + mandate |
reducePosition(id, { fraction, slippageBps }) → PlacedOrder |
POST /positions/{id}/reduce |
positions:manage + mandate |
runCommand(text, { mode, accountId, dryRun }) → CommandResult |
POST /commands |
the scope of what the command resolves to |
listStrategies({ kind }) |
GET /strategies |
strategies:read |
createStrategy({ kind, path, agentId }) → strategy · backtestStrategy(id) → job · startStrategy(id, { mode }), stopStrategy(id) → agent |
POST /strategies… |
strategies:manage |
listAgents() |
GET /agents |
agents:read |
listAgentTemplates(), getAgent(id) |
GET /agents/templates, /agents/{id} |
agents:read |
listAgentSignals(id, { mode, limit, before }), listAgentJournal(id, { mode, … }), listAgentOrders(id, { mode, open, … }), getAgentPerformance(id, { mode }) |
GET /agents/{id}/signals, journal, orders, performance — one mode per call |
agents:read |
getJob(id), waitForJob(id, { waitTimeoutMs, pollIntervalMs }) |
GET /jobs/{id} |
agents:read |
createAgent({ template, name, … }), startAgent(id, { mode }), pauseAgent(id), stopAgent(id) → agent · backtestAgent(id, { hours }) → job |
POST /agents… |
agents:manage |
openapi() |
GET /openapi.json |
any valid key |
responseMeta(result) gives the facts of the HTTP exchange behind any result: status, requestId, idempotencyKey,
idempotentReplay, rateLimit { limit, remaining, resetSeconds }, attempts.
The private markets are display only: none of these contracts is tradable (tradable: false on every row).
Pagination
GET /orders and GET /activity are paginated by cursor: a page carries nextCursor, which is the cursor of the
next (older) page; null at the end. The order is stable (time, then id): no row is repeated or skipped across pages.
The iterators follow the cursor for you; limit is the page size.
for await (const order of client.iterateOrders({ open: true, limit: 100 })) console.log(order.id, order.status);
for await (const item of client.iterateActivity({}, { maxItems: 500 })) console.log(item.kind, item.at);
const page = await client.listOrders({ limit: 50 }); // one page by hand
const next = page.nextCursor ? await client.listOrders({ limit: 50, cursor: page.nextCursor }) : null;listMarkets is not paginated: it answers total and truncated so a list cut by limit is visible.
Orders
const order = { mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'limit', price: '60000', size: '0.01' } as const;
const preview = await client.previewOrder(order); // nothing is created; preview.refusals says what would refuse it
const placed = await client.createOrder(order); // placed.order.status: 'SUBMITTED' while it rests
await client.cancelOrder(placed.order.id); // → { order: { status: 'CANCELLED', … }, changed: true }instrumentisvenue:symbolas returned bylistMarkets;exchange+symbolis the same thing in two parts.mode('paper'|'live') is required by the API; the SDK sends'paper'when you give none.- Size the order with exactly one of
size(base units) andnotional(quote currency). Both are decimal strings; a JavaScript float is refused before any request (ConfigurationError). notionalis sized by the server: it divides by the order's own price (limit, else trigger), else by the mark price it reads at that moment, and rounds down to the lot size. A stale mark is refused (503 stale_data); less than one lot is422 below_min_size. The answer carries the size that was used (preview.resolved.size,placed.order.size).notionalUsdcis the same field under the name of the quick start: the SDK sends it asnotionaland computes nothing.getMarket(instrument).instrumentgives what an order must respect:lotSize,tickSize,minOrderSize,minNotional,maxLeverage.- A preview says "no" in its answer, not with an exception:
wouldExecuteis false andrefusalslists each refusal with itsstage(key,lock,mandate,risk,engine) andcode.preview.account.equityandfreeCollateralare answered only to a key that also holdswallet:readorpositions:read(preview.account.withheldis true otherwise). A key previews the order it could place: without a mandate bound to it,previewOrderthrowsMandateRequired. previewOrderandengageKillSwitchtake noIdempotency-Key(the contract declares none): they are safe to repeat and are retried like a read.
A position is closed or reduced by its id from getPositions(); both are strictly reduce-only market orders:
const position = (await client.getPositions({ mode: 'paper' })).positions[0];
if (position) {
await client.reducePosition(position.id, { fraction: '0.5' });
await client.closePosition(position.id);
}Commands and the kill switch
import { AmbiguousCommand } from '@sp-wallet/trading-sdk';
try {
const r = await client.runCommand('LONG BTC-PERP 500 x2', { dryRun: true });
// the answer is a discriminated union: narrow on `kind`, and for an order on `executed`
if (r.kind === 'order' && !r.executed) console.log(r.order.instrument, r.order.notional, r.hash); // dry run: the CANONICAL order
if (r.kind === 'order' && r.executed) console.log(r.order.id, r.order.status, r.canonical.instrument); // executed: the placed order
if (r.kind === 'query') console.log(r.query, r.data); // SHOW …
if (r.kind === 'control') console.log(r.control.type, r.executed); // CANCEL, KILL, STOP ALL AGENTS
} catch (e) {
if (e instanceof AmbiguousCommand) console.log(e.questions.map((q) => `${q.field}: ${q.options.join(' | ')}`)); // nothing was executed
else throw e;
}
await client.engageKillSwitch('manual stop'); // blocks every NEW risk; cancels and exits still pass; only the owner releases itThe grammar is deterministic (no model). What a command leaves open (venue, leverage, …) comes from the owner's stored
defaults and from nothing else; when they do not settle it, the API answers 409 ambiguous_command with the questions.
Agents
const { templates } = await client.listAgentTemplates(); // family, engine, the modes each can run in
const { agent } = await client.createAgent({ template: 'market-making', name: 'MM BTC', venues: ['hyperliquid'], universe: ['BTC'] });
await client.startAgent(agent.id, { mode: 'paper' }); // research and paper sign nothing
// every per-agent read is ONE mode per call: `mode` is required, and an answer never mixes two (`all` is refused)
const signals = await client.listAgentSignals(agent.id, { mode: 'paper', limit: 50 });
const journal = await client.listAgentJournal(agent.id, { mode: 'paper' });
const orders = await client.listAgentOrders(agent.id, { mode: 'paper', open: true });
const performance = await client.getAgentPerformance(agent.id, { mode: 'paper' }); // computed from paper records only; never a backtest
const { job } = await client.backtestAgent(agent.id, { hours: 24 }); // asynchronous
const done = await client.waitForJob(job.id, { waitTimeoutMs: 120_000 }); // done | failed | cancelled; WaitTimeout is not a failure
await client.pauseAgent(agent.id); await client.stopAgent(agent.id); // stop is always allowedmodeon the reads. On the wiremodeis optional: the server answers the mode the agent is in now (for a stopped agent, the one it last ran in) and says which inmode. The SDK makes it a required argument, so that code never reads paper figures believing they are live ones;openexists onlistAgentOrdersonly.createAgent({ mode })is'research'(default: created, not running) or'paper': an agent from a stream or supervisor template starts on paper at once; a bar agent (orkind: 'perp') is created and not started — register and backtest a strategy version, thenstartAgent.'live'is refused (400 bad_request).- Paper. Starting a perp agent on paper creates its paper trading mandate (nothing is signed): its orders go through
the same order service, risk engine and kill switch as every other order. The key needs
agents:manage, and a key restricted to other venues or instruments gets403 restricted; a halted paper account answers409 halted. - Live.
startAgent(id, { mode: 'live' })succeeds only when a mandate the owner approved for that agent with the passkey is in force — for a perp agent a trading mandate, which only the owner activates. Otherwise409 mandate_required. A key can never approve one. Families that cannot go live answer409 live_unavailable. - Errors. Every 409 of the agent operations is a
Conflict; reade.code(mandate_required,halted,bad_state,live_unavailable,no_strategy,no_report,bad_report).MandateRequired(403) is about the key's mandate on the order operations, not about an agent's. - One kill switch. There is no agents-side switch:
engageKillSwitch(reason)engages the risk engine's, which stops every agent's new risk too. Releasing it is the owner's act, in the app. A spot agent is created in the owner's app (403 owner_required).
Spot orders (owner session only)
A key is refused spot execution (403). For the owner, a spot order is a swap proposal approved with the passkey:
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: { instrument: 'spot:ETH-USDC', side: 'buy', type: 'market', notional: '100', mode: 'live' }.
Order states and waitForOrder
order.status is one of the twelve ORDER_STATES — a closed enum in the contract: CREATED, VALIDATED, AWAITING_APPROVAL, APPROVED, SUBMITTING, SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, FAILED, UNKNOWN.
Final states (FINAL_ORDER_STATES): FILLED, CANCELLED, REJECTED, FAILED; order.final is true exactly for those.
UNKNOWN is not final and is not a failure: the venue's answer is not known yet; keep reading the order.
order.engineStatus is the executing engine's own word for the same moment (open, filled, a swap state…): it is
informative — decide on status.
const { order, fills } = await client.waitForOrder(id, { waitTimeoutMs: 60_000, pollIntervalMs: 1_000 });waitForOrder returns when the status is final (or when until(order) is true) and throws WaitTimeout when the time
elapses first — that is not an order failure either; error.last is the last answer.
Errors
Every error extends SPWalletError and carries code (the API's error member), message, status, requestId
(X-Request-Id: the owner finds the call in the usage log with it) and, for mutating calls, idempotencyKey.
| Class | When |
|---|---|
ValidationError |
400 bad_request, invalid_order, invalid_cursor, parse_error, idempotency, stale_request; 422 no_orderbook, venue_rejected, below_min_size, no_position, a refusal of the venue engine's own rules |
AuthenticationError |
401 unauthenticated — missing, malformed, unknown, expired or revoked key (one answer for all) |
PermissionDenied |
403 — restricted, ip_not_allowed, key_limit_exceeded, not_your_order… |
↳ ScopeDenied |
403 insufficient_scope — the key does not hold the operation's scope |
↳ MandateRequired |
403 mandate_required — no trading mandate is bound to the key |
↳ MandateDenied |
403 mandate_denied — the order is outside the mandate; error.reasons (MANDATE_DENY_REASONS: ORDER_NOTIONAL_EXCEEDED, INSTRUMENT_NOT_ALLOWED…) |
↳ ExecutionDisabled |
403 execution_disabled — live execution through the API is closed on this server; nothing was created |
RiskDenied |
422 risk_denied, 423 kill_switch_active / read_only_mode — error.failed (ids of RISK_CHECK_IDS), error.checks, error.killSwitch |
NotFound |
404 unknown_order, unknown_instrument, unknown_venue, unknown_market, unknown_position, not_found (a path that is not an operation)… |
Conflict |
409 |
↳ IdempotencyConflict |
409 idempotency_conflict — the key was used with a different request |
↳ AmbiguousSymbol |
409 ambiguous_symbol — error.candidates lists the venue:symbol ids |
↳ AmbiguousCommand |
409 ambiguous_command — error.questions; nothing was executed |
RateLimited |
429 rate_limited, auth_throttled — error.retryAfterSeconds |
NotImplementedError ↳ ExecutionNotWired |
501 execution_not_wired — an operation this server has not connected (an owner's spot order without the swap flow); nothing was done |
ServerError ↳ ServiceUnavailable |
5xx; 503 signer_unreachable, venue_unavailable, markets_unavailable, stale_data… |
NetworkError ↳ TimeoutError |
no answer (reads, previews) |
OutcomeUnknown |
a mutating call without a trustworthy answer — not a failure, see below |
WaitTimeout, WebhookVerificationError, ConfigurationError |
SDK-side |
error.order: when the server created the order before it refused it (a mandate or risk refusal, a refusal of the
venue engine), the error carries that order — state REJECTED or FAILED — so you know its id. It is null when the
call was refused before any order existed (nothing was created). The codes each operation can answer are in the
contract (x-spw-errors) and in the SDK as OPERATION_ERRORS[operationId].
import { ExecutionDisabled, MandateDenied, MandateRequired, OutcomeUnknown, RateLimited, RiskDenied, ScopeDenied } from '@sp-wallet/trading-sdk';
try {
await client.createOrder({ instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100', mode: 'paper' });
} catch (e) {
if (e instanceof OutcomeUnknown) { /* see "OutcomeUnknown" */ }
else if (e instanceof MandateRequired) { /* the owner must bind an approved mandate to this key */ }
else if (e instanceof MandateDenied) console.log(e.reasons, e.order?.id, e.order?.status); // ['ORDER_NOTIONAL_EXCEEDED'] … 'REJECTED'
else if (e instanceof RiskDenied) console.log(e.killSwitch ? 'kill switch' : e.failed, e.checks.map((c) => `${c.id}: ${c.observed} / ${c.limit}`));
else if (e instanceof ExecutionDisabled) { /* live orders are closed on this server; paper is not affected */ }
else if (e instanceof ScopeDenied) { /* the key lacks orders:execute */ }
else if (e instanceof RateLimited) { /* wait e.retryAfterSeconds */ }
else throw e;
}Retries and idempotency
- Reads (
GET) are retried on a network error, a timeout,429(afterRetry-After, elseRateLimit-Reset) and502 / 503 / 504, with exponential backoff (0.5 s × 2ⁿ, capped at 8 s) and jitter (50–100 % of the step). - Mutating calls (
POST,DELETE) are retried only because they carry anIdempotency-Key. The SDK creates one UUIDv4 per logical call when you give none, serializes the body once in canonical form (sorted keys — the same rule as the server's request hash), and sends the same key and the same bytes on every retry. The server then runs the operation at most once: the same key with the same request returns the first answer (responseMeta(r).idempotentReplay), with a different request409 idempotency_conflict. - The key is exposed three ways so that you can resume after a crash: pass your own (
{ idempotencyKey }, generate it withnewIdempotencyKey()and persist it before sending), read it fromresponseMeta(result).idempotencyKey, or fromerror.idempotencyKey. previewOrderandengageKillSwitcharePOSTs without anIdempotency-Keyin the contract (repeating them changes nothing): they are retried like a read and fail with the ordinary errors, neverOutcomeUnknown.- Not retried: 400, 401, 403, 404, 409 (except
idempotency_in_progress), 422, 423, 500, 501.
OutcomeUnknown
A mutating call that ends without a trustworthy answer — timeout, connection lost, 500/502/504, a 503 that does not
come from the API, the first request with this key still running, or an answer decided before the server looked at the
key (401, 403, 429) after an attempt without an answer — throws OutcomeUnknown. It is not a failure: the operation
may or may not have been executed.
try {
await client.createOrder(order, { idempotencyKey });
} catch (e) {
if (!(e instanceof OutcomeUnknown)) throw e;
// 1. re-send the SAME call with the SAME key: the server returns the stored answer if it ran, or runs it once
const result = await client.createOrder(order, { idempotencyKey: e.idempotencyKey! });
// 2. or read the object: client.getOrder(id) / client.listOrders({ open: true })
// Never re-send with a NEW key: that could execute the operation twice.
}Key rotation and the trading mandate
A trading mandate names one principal — the key id it was approved for — and a rotation gives the key a new id. The
rotation therefore does not carry the mandate: the new key keeps the scopes, limits, restrictions and expiry, and is
unbound. Until the owner approves a mandate for the new id and binds it, createOrder, closePosition and
reducePosition throw MandateRequired (and previewOrder too); reads, cancels of its own orders, the kill switch and
agent management keep working. The answer of the rotation says so:
{ key: { mandateId: null, inertScopes: […] }, secret, revoked, mandate: { carried: false, mandateId: '<old mandate>', code: 'mandate_principal_mismatch', note } }.
try { await client.createOrder(order); }
catch (e) {
if (e instanceof MandateRequired) { /* after a rotation: ask the owner for a mandate for THIS key id, then retry — nothing was created */ }
else throw e;
}The owner's side of it (owner session and passkey — nothing a key can do):
# 1. a mandate for the NEW key id: created, then approved (a live mandate is approved with the passkey at the signer)
POST /api/v1/mandates { "principal": { "kind": "api_key", "id": "<new key id>" }, "mode": "paper", "accountIds": ["…"], … }
POST /api/v1/mandates/<mandate id>/approve { } # live: /approve/prepare first, then the passkey assertion
# 2. bind it to the key (binding gives the key authority: passkey)
POST /api/v1/developer/keys/<new key id>/update/prepare { "changes": { "mandateId": "<mandate id>" } }
POST /api/v1/developer/keys/<new key id>/update { "intentId": "…", "assertion": { … } }In the app: Developer → the key → Trading mandate → New mandate.
Streaming
Live market data over one websocket: quotes, order books, trades, candles and venue statuses. Read-only (scope
markets:read), same key, same restrictions (a channel of a venue or instrument outside the key's restrictions is refused,
per subscription). SPWalletStream is exported by the package next to SPWallet; it needs a global WebSocket (Node >= 22,
browsers) or the WebSocket option (the ws package).
import { SPWalletStream, OrderBook, StreamError } from '@sp-wallet/trading-sdk';
const stream = new SPWalletStream({ baseUrl: 'https://wallet.example' }); // the key: SP_WALLET_API_KEY, in the Authorization header
stream.on('close', (c) => console.log(`closed (${c.code}); ${c.willReconnect ? 'reconnecting' : 'stopped'}`));
stream.on('error', (e) => console.log(`stream error: ${e.code}`));
await stream.subscribe([{ type: 'quote', id: 'hyperliquid:BTC' }, { type: 'status', id: 'hyperliquid' }]);
for await (const m of stream) { // or stream.on('quote', …)
if (m.type === 'quote') console.log(m.id, m.bid, m.ask, m.mark, m.stale); // decimal strings; `stale` is the server's verdict
}- Channels:
quote,book(depth),trades,candles(interval),status(id: '<venue>'or'*'). Ids are<venue>:<instrument>(hyperliquid:BTC,dydx:BTC-USD,spot:BTC). - Reconnection is on by default (
reconnect: falseto turn it off): exponential backoff with jitter betweenbackoffMinMs(500) andbackoffMaxMs(30 000); after a reconnection the client subscribes again to everything and the server sends fresh snapshots — a handler never has to do it.closeevents carrywillReconnect. A refusal that a retry cannot fix (nomarkets:read, revoked key, unknown instrument) is aStreamErrorwith the server'scode, and is not retried. - Order books: feed every
bookmessage to anOrderBook;apply()returnsfalseon a sequence hole or a checksum mismatch — callstream.resync(channel)and the server restarts the book from a snapshot. - Slow consumers: quotes are conflated and a
droppedmessage says what was skipped; the iterator's own buffer is bounded bybufferSize. - A stream connection writes no row in the key's usage log (the ticket request does).
Browsers: the ticket flow
A browser cannot set a header on a websocket, and the key must never reach it. Your backend asks for a single-use ticket (30 s) with the key; the browser connects with the ticket only:
// backend (holds the key) — a route of YOUR server, behind YOUR authentication
app.post('/stream-ticket', async () => {
const r = await fetch(`${WALLET}/api/v1/trading/stream/ticket`, { method: 'POST', headers: { authorization: `Bearer ${process.env.SP_WALLET_API_KEY}`, 'content-type': 'application/json' }, body: '{}' });
if (!r.ok) throw new Error(`ticket refused: ${r.status}`);
return { ticket: (await r.json()).ticket }; // { ticket, expiresAt, ttlMs, url, protocol }
});
// browser — no key anywhere; a new ticket is asked at every (re)connection
const stream = new SPWalletStream({
baseUrl: 'https://wallet.example',
ticket: async () => (await (await fetch('/stream-ticket', { method: 'POST' })).json()).ticket,
});
await stream.subscribe({ type: 'quote', id: 'hyperliquid:BTC' });The ticket carries the key's scope and restrictions, works once, and is refused when mixed with another credential. In Node,
auth: 'ticket' makes the client ask for the ticket itself with its key (useful behind a proxy that strips headers on upgrade).
Webhooks
The wallet signs every delivery: X-SPW-Timestamp: <unix seconds> and
X-SPW-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>. Verify over the raw body, before parsing:
import { constructWebhookEvent } from '@sp-wallet/trading-sdk';
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, // string or Uint8Array, exactly as received
}); // throws WebhookVerificationError; tolerance 300 s; constant-time comparisonverifyWebhook(…) returns a boolean instead. Delivery is at-least-once: deduplicate on event.id. Events:
key.revoked, risk.kill_switch, agent.updated, order.updated (one event per transition of an order),
risk.proposal. A complete receiver: packages/trading-sdk/examples/webhook-receiver.ts.
Examples
SP_WALLET_API_KEY=spw_live_… node packages/trading-sdk/examples/read-only.ts # read-only tour
SP_WALLET_API_KEY=spw_live_… node packages/trading-sdk/examples/preview-order.ts # a preview with every outcome handled
SP_WALLET_API_KEY=spw_live_… node packages/trading-sdk/examples/paper-order.ts # PAPER: preview → place → wait → position → close
SP_WALLET_API_KEY=spw_live_… node packages/trading-sdk/examples/stream-quotes.ts # live quotes over the websocket, with reconnectionThe four are executed against the real API by the integration tests.
Development
node packages/trading-sdk/scripts/gen-types.mts [--check] # src/generated/openapi.ts from the OpenAPI document
node_modules/.bin/vitest run packages/trading-sdk # unit tests + integration test
SPW_SDK_INTEGRATION=off node_modules/.bin/vitest run packages/trading-sdk # unit tests onlyThe integration test starts the real API and the real signer on an own database (scripts/test-stack.mts), creates
keys, a paper account and paper mandates through the owner flow, calls every method and runs the whole paper write
path (preview → order → fill → reduce → close → resting order → cancel, replay and conflict, the refusals, the kill
switch, commands) and an agent on paper (create from a template → start → signals, journal, orders, performance → pause → backtest job → stop). No live order is sent: the live case stops at execution_disabled. It is skipped (reported as
skipped) when PostgreSQL is not reachable; a test whose venue cannot be read is skipped with that reason.
NFT reads
Five read operations; no NFT write exists in the API (transfers are the owner's, with the passkey; no marketplace action is built). listNfts / getNft / getNftActivity read the wallet's own inventory. getNftMarket and getNftMarketEvents read market data of ANY item named by its chain identifiers and answer one row per source — a source without its key answers status.state: 'needs_key' with status.unlockedBy; nothing is filled in. Amounts are exact base-unit strings in a currency identified by network + mint / contract (price.amount, price.currency); a tokenId is a string (it can be as large as 2^256 − 1). NFTs carry no value: valuation.state / value.state is 'unavailable'. A fiat rates entry can be withheld for a key (licence of the price source).