SP Trading API — Python SDK (sp-wallet-python, import sp_wallet)
Official client of the SP Trading API (/api/v1/trading, contract: docs/openapi/trading-v1.json,
reference: docs/TRADING-API-OPENAPI.md). Source: sdk/python/.
- Python ≥ 3.10.
httpx(a synchronous clientSPWalletand an asynchronous clientAsyncSPWallet) andpydanticv2.py.typedis shipped. - Every answer is a typed pydantic model, generated from the OpenAPI document (
scripts/gen_models.py). A test fails when the committed models are not what the document gives, and a second test walks every schema of the document against the model classes. - Money, prices and sizes are decimal strings end to end (
str), exactly as the API sends them;to_decimal()anddecimal_str()convert from and todecimal.Decimal. Afloatis never produced and never accepted: a JSON number that is not money (an age in milliseconds, a count) is parsed asintorDecimal. - The API key is never logged, never part of an error or a traceback, never in
repr(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 models. 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 PyPI. Install it from its path:
pip install /path/to/sp-wallet/sdk/python # or: uv add /path/to/sp-wallet/sdk/pythonQuick start
from sp_wallet import SPWallet
client = SPWallet(api_key="spw_live_…") # or SPWallet() with the environment variable SP_WALLET_API_KEY
client.get_balances()
client.get_positions()
preview = client.preview_order(exchange="hyperliquid", symbol="BTC", side="buy", order_type="market", notional_usdc=100)
if preview.would_execute:
placed = client.create_order(exchange="hyperliquid", symbol="BTC", side="buy", order_type="market", notional_usdc=100) # mode="paper" by default
done = client.wait_for_order(placed.order.id) # FILLED, CANCELLED, REJECTED or FAILEDAsynchronous — the same methods, awaited:
from sp_wallet import AsyncSPWallet
async with AsyncSPWallet() as client:
balances = await client.get_balances()| Argument | Default | |
|---|---|---|
api_key |
env SP_WALLET_API_KEY |
spw_live_…, created by the owner in the Developer screen |
base_url |
env SP_WALLET_BASE_URL, else https://wallet.spboucher.ai |
http:// is accepted for localhost only (or with allow_insecure_http=True) |
timeout |
30.0 |
seconds, per attempt |
max_retries |
2 |
retries after the first attempt |
user_agent |
— | appended to sp-wallet-python/<version> |
send_timestamp |
False |
send X-SPW-Timestamp with mutating calls (the server refuses a call more than 300 s from its clock) |
max_retry_delay |
30.0 |
longest wait accepted before a retry; a 429 asking for more is raised at once |
http_client |
— | your own httpx.Client / httpx.AsyncClient (proxy, TLS); not closed by the SDK |
client.with_options(timeout=…, max_retries=…) returns the same client with other settings for one call, e.g.
client.with_options(max_retries=0).create_order(…). Use the client as a context manager, or call close() /
await aclose().
Methods
The same methods on SPWallet and, awaited, on AsyncSPWallet.
| Method | Operation | Scope |
|---|---|---|
list_markets(venue=, kind=, q=, limit=) |
GET /markets |
markets:read |
compare_markets(underlying=, side=, notional=, leverage=, horizon_hours=, liquidity=, min_net_edge_bps=) |
GET /markets/compare |
markets:read |
get_market(symbol) |
GET /markets/{symbol} |
markets:read |
get_orderbook(symbol, depth=) |
GET /markets/{symbol}/orderbook |
markets:read |
get_candles(symbol, interval=, limit=) |
GET /markets/{symbol}/candles |
markets:read |
list_private_markets(delisted=, size=, side=) |
GET /private-markets |
markets:read |
get_private_market(market_id, size=, side=, interval=, limit=) |
GET /private-markets/{id} |
markets:read |
get_private_market_company(slug, …) |
GET /private-markets/companies/{slug} |
markets:read |
get_portfolio() |
GET /portfolio |
wallet:read |
get_balances(network=) |
GET /balances |
wallet:read |
get_activity(limit=, cursor=), iter_activity(limit=, max_items=) |
GET /activity |
wallet:read |
list_nfts(network=, collection=, status=, q=, sort=, spam=, limit=, cursor=) |
GET /nfts |
wallet:read |
get_nft(key) |
GET /nfts/item |
wallet:read |
get_nft_activity(key, limit=, cursor=, type=) |
GET /nfts/activity |
wallet:read |
get_nft_market(network=, address=, token_id=) |
GET /nfts/market |
markets:read |
get_nft_market_events(network=, address=, token_id=, provider=, type=, after=, before=, cursor=, limit=) |
GET /nfts/market/events |
markets:read |
get_positions(mode=, venue=) |
GET /positions |
positions:read |
get_risk() |
GET /risk |
positions:read |
engage_kill_switch(reason) |
POST /risk/kill-switch |
positions:manage (no mandate) |
list_orders(mode=, venue=, open=, limit=, cursor=), iter_orders(…, max_items=) |
GET /orders |
orders:read |
get_order(order_id) |
GET /orders/{id} |
orders:read |
wait_for_order(order_id, timeout=, poll_interval=, until=) |
polls GET /orders/{id} |
orders:read |
preview_order(…) → models.OrderPreview |
POST /orders/preview |
orders:prepare (a key needs a mandate bound to it) |
create_order(…) → models.PlacedOrder |
POST /orders |
orders:execute + mandate |
cancel_order(order_id) → models.CancelledOrder |
DELETE /orders/{id} |
orders:cancel (its own orders; no mandate) |
close_position(position_id, slippage_bps=) → models.PlacedOrder |
POST /positions/{id}/close |
positions:manage + mandate |
reduce_position(position_id, fraction=, slippage_bps=) → models.PlacedOrder |
POST /positions/{id}/reduce |
positions:manage + mandate |
run_command(text, mode=, account_id=, dry_run=) → models.CommandResult |
POST /commands |
the scope of what the command resolves to |
list_strategies(kind=) |
GET /strategies |
strategies:read |
create_strategy(kind=, path=, agent_id=) → StrategyResult · backtest_strategy(id) → JobResult · start_strategy(id, mode=), stop_strategy(id) → AgentResult |
POST /strategies… |
strategies:manage |
list_agents() |
GET /agents |
agents:read |
list_agent_templates(), get_agent(agent_id) |
GET /agents/templates, /agents/{id} |
agents:read |
list_agent_signals(agent_id, mode=, limit=, before=), list_agent_journal(…), list_agent_orders(…, open=), get_agent_performance(agent_id, mode=) |
GET /agents/{id}/signals, journal, orders, performance — one mode per call |
agents:read |
get_job(job_id), wait_for_job(job_id, timeout=, poll_interval=) |
GET /jobs/{id} |
agents:read |
create_agent(name=, template=, …), start_agent(id, mode=), pause_agent(id), stop_agent(id) → AgentResult · backtest_agent(id, hours=) → JobResult |
POST /agents… |
agents:manage |
openapi() |
GET /openapi.json |
any valid key |
Results are pydantic models with snake_case attributes (portfolio.totals.paper_equity, placed.order.avg_fill_price,
position.entry_price); result.to_dict() gives the answer with the API's own names. Members the contract does not
name are kept (model_extra, also reachable as attributes). result.meta gives the facts of the HTTP exchange:
status, request_id, idempotency_key, idempotent_replay, rate_limit (limit, remaining, reset_seconds),
attempts. An answer that does not match the contract — a status outside the twelve states, a number where a decimal
string is declared — raises ServerError (code == "invalid_response") instead of returning a half-typed object; on a
write the message says that the operation ran.
The private markets are display only: none of these contracts is tradable (tradable is False on every row).
Pagination
GET /orders and GET /activity are paginated by cursor: a page carries next_cursor, which is the cursor of the
next (older) page; None 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 order in client.iter_orders(open=True, limit=100):
print(order.id, order.status)
for item in client.iter_activity(max_items=500):
print(item.kind, item.at)
async for order in async_client.iter_orders(open=True): # AsyncSPWallet: an asynchronous iterator
...
page = client.list_orders(limit=50) # one page by hand
older = client.list_orders(limit=50, cursor=page.next_cursor) if page.next_cursor else Nonelist_markets is not paginated: it answers total and truncated so a list cut by limit is visible.
Decimals
from decimal import Decimal
from sp_wallet import to_decimal, decimal_str
book = client.get_orderbook("hyperliquid:BTC", depth=1)
bid, ask = to_decimal(book.bids[0][0]), to_decimal(book.asks[0][0]) # str → Decimal, exact
client.preview_order(instrument="hyperliquid:BTC", side="buy", order_type="limit",
size=Decimal("0.01"), price=int((bid + ask) / 2)) # Decimal, int or str — never float
decimal_str(Decimal("1E-7")) # "0.0000001": what goes on the wirePassing a float anywhere an amount is expected raises ConfigurationError before any request.
Orders
order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="limit", price="60000", size="0.01")
preview = client.preview_order(**order) # nothing is created; preview.refusals says what would refuse it
placed = client.create_order(**order) # placed.order.status: "SUBMITTED" while it rests
client.cancel_order(placed.order.id) # → order.status "CANCELLED", changed Trueinstrumentisvenue:symbolas returned bylist_markets;exchange+symbolis the same thing in two parts.- The API's
typeis the argumentorder_type.modedefaults to"paper". - Size the order with exactly one of
size(base units) andnotional(quote currency). 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).notional_usdcis the same field under the name of the quick start: the SDK sends it asnotionaland computes nothing.client.get_market(instrument).instrumentgives what an order must respect:lot_size,tick_size,min_order_size,min_notional,max_leverage.- A preview says "no" in its answer, not with an exception:
would_executeis False andrefusalslists each refusal with itsstage(key,lock,mandate,risk,engine) andcode.preview.account.equityandfree_collateralare 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,preview_orderraisesMandateRequired. preview_orderandengage_kill_switchtake 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 get_positions(); both are strictly reduce-only market orders:
positions = client.get_positions(mode="paper").positions
if positions:
client.reduce_position(positions[0].id, fraction=Decimal("0.5"))
client.close_position(positions[0].id)Commands and the kill switch
from sp_wallet import AmbiguousCommand, models
try:
r = client.run_command("LONG BTC-PERP 500 x2", dry_run=True)
# the answer is one of four models: narrow with isinstance
if isinstance(r, models.CommandDryRun): # a dry run: `order` is the CANONICAL order; nothing was created
print(r.order.instrument, r.order.notional, r.hash)
elif isinstance(r, models.CommandExecuted): # executed: `order` is the placed order, `canonical` its canonical form
print(r.order.id, r.order.status, r.canonical.instrument)
elif isinstance(r, models.CommandQuery): # SHOW …
print(r.query, r.data)
elif isinstance(r, models.CommandControl): # CANCEL, KILL, STOP ALL AGENTS
print(r.control.type, r.executed)
except AmbiguousCommand as e:
print([f"{q['field']}: {' | '.join(q['options'])}" for q in e.questions]) # nothing was executed
client.engage_kill_switch("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
templates = client.list_agent_templates().templates # family, engine, the modes each can run in
agent = client.create_agent(template="market-making", name="MM BTC", venues=["hyperliquid"], universe=["BTC"]).agent
client.start_agent(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)
signals = client.list_agent_signals(agent.id, mode="paper", limit=50)
journal = client.list_agent_journal(agent.id, mode="paper")
orders = client.list_agent_orders(agent.id, mode="paper", open=True)
performance = client.get_agent_performance(agent.id, mode="paper") # computed from paper records only; never a backtest
job = client.backtest_agent(agent.id, hours=24).job # asynchronous
done = client.wait_for_job(job.id, timeout=120) # done | failed | cancelled; WaitTimeout is not a failure
client.pause_agent(agent.id)
client.stop_agent(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 keyword, so that code never reads paper figures believing they are live ones;openexists onlist_agent_ordersonly.create_agent(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, thenstart_agent."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.
start_agent(agent_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:
engage_kill_switch(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). An agent'srisklimits are ints, bools,Decimals or decimal strings — never a float.
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", order_type="market", notional="100", mode="live").
Order states and wait_for_order
order.status is one of the twelve ORDER_STATES — a closed enum in the contract and a Literal in the model:
CREATED, VALIDATED, AWAITING_APPROVAL, APPROVED, SUBMITTING, SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED, FAILED, UNKNOWN. Final states (TERMINAL_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.engine_status is the executing engine's own word for the same moment (open, filled, a swap
state…): it is informative — decide on status.
done = client.wait_for_order(order_id, timeout=60, poll_interval=1)
print(done.order.status, done.order.filled, len(done.fills))wait_for_order returns when the status is final (or when until(order) is true) and raises 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, request_id
(X-Request-Id: the owner finds the call in the usage log with it), body, data (the refusal's machine-readable
detail) and, for mutating calls, idempotency_key.
| 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.kill_switch |
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.retry_after (seconds) |
sp_wallet.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…; invalid_response |
NetworkError ↳ sp_wallet.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 as a models.Order — state REJECTED or FAILED — so you know its id. It
is None 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[operation_id].
from sp_wallet import ExecutionDisabled, MandateDenied, MandateRequired, OutcomeUnknown, RateLimited, RiskDenied, ScopeDenied
try:
client.create_order(instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100", mode="paper")
except OutcomeUnknown:
... # see "OutcomeUnknown"
except MandateRequired:
... # the owner must bind an approved mandate to this key
except MandateDenied as e:
print(e.reasons, e.order.id if e.order else None) # ['ORDER_NOTIONAL_EXCEEDED'] …
except RiskDenied as e:
print("kill switch" if e.kill_switch else e.failed, [(c.id, c.observed, c.limit) for c in e.checks])
except ExecutionDisabled:
... # live orders are closed on this server; paper is not affected
except ScopeDenied:
... # the key lacks orders:execute
except RateLimited as e:
... # wait e.retry_after secondsRetries 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 — byte for byte the server's canonical form), 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 (result.meta.idempotent_replay), with a different request409 idempotency_conflict. - The key is exposed three ways so that you can resume after a crash: pass your own (
idempotency_key=, generate it withnew_idempotency_key()and persist it before sending), read it fromresult.meta.idempotency_key, or fromerror.idempotency_key. preview_orderandengage_kill_switcharePOSTs 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 — raises OutcomeUnknown. It is not a failure: the operation
may or may not have been executed.
key = new_idempotency_key() # persist it
try:
client.create_order(**order, idempotency_key=key)
except OutcomeUnknown as e:
# 1. re-send the SAME call with the SAME key: the server returns the stored answer if it ran, or runs it once
result = client.create_order(**order, idempotency_key=e.idempotency_key)
# 2. or read the object: client.get_order(order_id) / client.list_orders(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, create_order, close_position and
reduce_position raise MandateRequired (and preview_order 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:
client.create_order(**order)
except MandateRequired:
... # after a rotation: ask the owner for a mandate for THIS key id, then retry — nothing was createdThe 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). The client is asynchronous and needs the optional dependency websockets:
pip install "sp-wallet-python[stream]" # in the repository: uv sync --extra streamSPWalletStream, OrderBook, StreamError, book_checksum and channel_key are exported by sp_wallet and loaded on
first use: import sp_wallet works on a base install, and websockets is imported only when a stream connects.
import asyncio
from sp_wallet import SPWalletStream
from sp_wallet.stream import Quote
async def main() -> None:
async with SPWalletStream(base_url="https://wallet.example") as stream: # the key: SP_WALLET_API_KEY, in the Authorization header
stream.on("close", lambda c: print("closed;", "reconnecting" if c["will_reconnect"] else "stopped"))
stream.on("error", lambda e: print("stream error:", e.code))
await stream.subscribe([{"type": "quote", "id": "hyperliquid:BTC"}, {"type": "status", "id": "hyperliquid"}])
async for m in stream: # or stream.on("quote", …)
if isinstance(m, Quote):
print(m.id, m.bid, m.ask, m.mark, m.stale) # decimal strings; `stale` is the server's verdict
asyncio.run(main())- Channels:
quote,book(depth),trades,candles(interval),status(id: a venue or"*"). Ids are<venue>:<instrument>(hyperliquid:BTC,dydx:BTC-USD,spot:BTC). Messages are models:Quote,Book,Trades,Candle,VenueStatus(snake_case attributes:recv_ts,venue_ts,bid_size). - Reconnection is on by default (
reconnect=Falseto turn it off): exponential backoff with jitter betweenbackoff_minandbackoff_max; after a reconnection the client subscribes again to everything and the server sends fresh snapshots.closeevents carrywill_reconnect. 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
Bookto anOrderBook;apply()returnsFalseon a sequence hole or a checksum mismatch —await stream.resync(channel)and the server restarts the book from a snapshot. - Slow consumers: quotes are conflated and a
droppedevent says what was skipped; the iterator's buffer is bounded bybuffer_size. - A stream connection writes no row in the key's usage log (the ticket request does).
Browsers and proxies: the ticket flow
A browser cannot set a header on a websocket, and the key must never reach it. A backend asks for a single-use ticket (30 s)
with the key — POST /api/v1/trading/stream/ticket, answer { ticket, expiresAt, ttlMs, url, protocol } — and hands only
the ticket to the page, which connects to /api/v1/trading/stream?ticket=… (in the TypeScript SDK:
new SPWalletStream({ baseUrl, ticket: () => … }), see docs/sdk/typescript.md). A Python backend:
import httpx, os
def stream_ticket() -> str: # behind YOUR authentication; a new ticket for every (re)connection
r = httpx.post(f"{WALLET}/api/v1/trading/stream/ticket", headers={"authorization": f"Bearer {os.environ['SP_WALLET_API_KEY']}"}, json={})
r.raise_for_status()
return r.json()["ticket"]The ticket carries the key's scope and restrictions, works once, and is refused when mixed with another credential. The
Python client can connect that way too: SPWalletStream(auth="ticket") asks for the ticket itself with its key (useful
behind a proxy that strips headers on upgrade), and SPWalletStream(ticket=my_async_function) uses yours.
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:
from sp_wallet import construct_webhook_event, WebhookVerificationError
event = construct_webhook_event(
secret=os.environ["SP_WALLET_WEBHOOK_SECRET"],
timestamp=request.headers.get("x-spw-timestamp"), signature=request.headers.get("x-spw-signature"),
body=raw_body, # bytes or str, exactly as received
) # raises WebhookVerificationError; tolerance 300 s; hmac.compare_digestverify_webhook(…) 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: sdk/python/examples/webhook_receiver.py.
Examples
cd sdk/python && uv sync
SP_WALLET_API_KEY=spw_live_… uv run python examples/read_only.py # read-only tour
SP_WALLET_API_KEY=spw_live_… uv run python examples/async_read.py # the asynchronous client
SP_WALLET_API_KEY=spw_live_… uv run python examples/preview_order.py # a preview with every outcome handled
SP_WALLET_API_KEY=spw_live_… uv run python examples/paper_order.py # PAPER: preview → place → wait → position → close
SP_WALLET_API_KEY=spw_live_… uv run --extra stream python examples/stream_quotes.py # live quotes over the websocket, with reconnectionThe five are executed against the real API by the integration tests.
Development
cd sdk/python
uv sync
uv run python scripts/gen_models.py [--check] # src/sp_wallet/models.py from the OpenAPI document
uv run python scripts/gen_sync.py [--check] # src/sp_wallet/_client.py (sync) from _async_client.py
uv run ruff check
uv run pytest # unit tests + integration test
SPW_SDK_INTEGRATION=off uv run pytest # unit tests onlyThe synchronous client is generated from the asynchronous one: one implementation, the same behaviour by construction.
The integration test starts the real API and the real signer on an own database
(packages/trading-sdk/scripts/test-stack.mts; it needs the repository's node_modules and PostgreSQL), creates
keys, a paper account and paper mandates through the owner flow, calls every method with both clients 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); every answer is validated against the OpenAPI document, closed objects included.
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). list_nfts / get_nft / get_nft_activity read the wallet's own inventory. get_nft_market and get_nft_market_events 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.unlocked_by; nothing is filled in. Amounts are exact base-unit strings in a currency identified by network + mint / contract; a token_id 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). There is no iter_nfts helper yet: page with cursor=next_cursor.