SPB Git

Repository Public

python.md 34.3 KB 524 lines markdown

1# SP Trading API — Python SDK (`sp-wallet-python`, import `sp_wallet`)23Official client of the SP Trading API (`/api/v1/trading`, contract: [`docs/openapi/trading-v1.json`](../openapi/trading-v1.json),4reference: [`docs/TRADING-API-OPENAPI.md`](../TRADING-API-OPENAPI.md)). Source: `sdk/python/`.56- Python ≥ 3.10. `httpx` (a synchronous client `SPWallet` and an asynchronous client `AsyncSPWallet`) and `pydantic` v2.7  `py.typed` is shipped.8- Every answer is a typed pydantic model, **generated** from the OpenAPI document (`scripts/gen_models.py`). A test fails9  when the committed models are not what the document gives, and a second test walks every schema of the document10  against the model classes.11- Money, prices and sizes are decimal **strings** end to end (`str`), exactly as the API sends them; `to_decimal()` and12  `decimal_str()` convert from and to `decimal.Decimal`. **A `float` is never produced and never accepted**: a JSON number13  that is not money (an age in milliseconds, a count) is parsed as `int` or `Decimal`.14- The API key is never logged, never part of an error or a traceback, never in `repr(client)`.1516> **Execution requires an owner-approved mandate.** Placing an order and closing or reducing a position need — besides17> the scope — an API key **bound to a trading mandate approved by the wallet's owner**. Without one the API refuses the18> call (`403 mandate_required` → `MandateRequired`); an order outside the mandate is `MandateDenied`. A scope alone never19> lets a key execute. Managing agents and strategies needs **no** mandate on the key (research and paper sign nothing):20> an agent goes live only under its *own* mandate, approved by the owner.21>22> **State of the API in this version.** All 46 operations of the contract are implemented and answer typed models.23> **Paper** orders are simulated by the wallet's paper engine against the venue's real order book. **Live** orders24> additionally need `SPW_TRADING_API_EXECUTION=on` on the server (default off → `403 execution_disabled` →25> `ExecutionDisabled`) and the wallet's mainnet locks. Spot orders and live GMX orders are the owner's (passkey): a key is26> refused them.2728## Install (from the repository)2930The package is not published to PyPI. Install it from its path:3132```bash33pip install /path/to/sp-wallet/sdk/python          # or: uv add /path/to/sp-wallet/sdk/python34```3536## Quick start3738```python39from sp_wallet import SPWallet4041client = SPWallet(api_key="spw_live_…")          # or SPWallet() with the environment variable SP_WALLET_API_KEY4243client.get_balances()44client.get_positions()45preview = client.preview_order(exchange="hyperliquid", symbol="BTC", side="buy", order_type="market", notional_usdc=100)46if preview.would_execute:47    placed = client.create_order(exchange="hyperliquid", symbol="BTC", side="buy", order_type="market", notional_usdc=100)  # mode="paper" by default48    done = client.wait_for_order(placed.order.id)        # FILLED, CANCELLED, REJECTED or FAILED49```5051Asynchronous — the same methods, awaited:5253```python54from sp_wallet import AsyncSPWallet5556async with AsyncSPWallet() as client:57    balances = await client.get_balances()58```5960| Argument | Default | |61|---|---|---|62| `api_key` | env `SP_WALLET_API_KEY` | `spw_live_…`, created by the owner in the Developer screen |63| `base_url` | env `SP_WALLET_BASE_URL`, else `https://wallet.spboucher.ai` | `http://` is accepted for `localhost` only (or with `allow_insecure_http=True`) |64| `timeout` | `30.0` | seconds, per attempt |65| `max_retries` | `2` | retries after the first attempt |66| `user_agent` | — | appended to `sp-wallet-python/<version>` |67| `send_timestamp` | `False` | send `X-SPW-Timestamp` with mutating calls (the server refuses a call more than 300 s from its clock) |68| `max_retry_delay` | `30.0` | longest wait accepted before a retry; a 429 asking for more is raised at once |69| `http_client` | — | your own `httpx.Client` / `httpx.AsyncClient` (proxy, TLS); not closed by the SDK |7071`client.with_options(timeout=…, max_retries=…)` returns the same client with other settings for one call, e.g.72`client.with_options(max_retries=0).create_order(…)`. Use the client as a context manager, or call `close()` /73`await aclose()`.7475## Methods7677The same methods on `SPWallet` and, awaited, on `AsyncSPWallet`.7879| Method | Operation | Scope |80|---|---|---|81| `list_markets(venue=, kind=, q=, limit=)` | `GET /markets` | `markets:read` |82| `compare_markets(underlying=, side=, notional=, leverage=, horizon_hours=, liquidity=, min_net_edge_bps=)` | `GET /markets/compare` | `markets:read` |83| `get_market(symbol)` | `GET /markets/{symbol}` | `markets:read` |84| `get_orderbook(symbol, depth=)` | `GET /markets/{symbol}/orderbook` | `markets:read` |85| `get_candles(symbol, interval=, limit=)` | `GET /markets/{symbol}/candles` | `markets:read` |86| `list_private_markets(delisted=, size=, side=)` | `GET /private-markets` | `markets:read` |87| `get_private_market(market_id, size=, side=, interval=, limit=)` | `GET /private-markets/{id}` | `markets:read` |88| `get_private_market_company(slug, …)` | `GET /private-markets/companies/{slug}` | `markets:read` |89| `get_portfolio()` | `GET /portfolio` | `wallet:read` |90| `get_balances(network=)` | `GET /balances` | `wallet:read` |91| `get_activity(limit=, cursor=)`, `iter_activity(limit=, max_items=)` | `GET /activity` | `wallet:read` |92| `list_nfts(network=, collection=, status=, q=, sort=, spam=, limit=, cursor=)` | `GET /nfts` | `wallet:read` |93| `get_nft(key)` | `GET /nfts/item` | `wallet:read` |94| `get_nft_activity(key, limit=, cursor=, type=)` | `GET /nfts/activity` | `wallet:read` |95| `get_nft_market(network=, address=, token_id=)` | `GET /nfts/market` | `markets:read` |96| `get_nft_market_events(network=, address=, token_id=, provider=, type=, after=, before=, cursor=, limit=)` | `GET /nfts/market/events` | `markets:read` |97| `get_positions(mode=, venue=)` | `GET /positions` | `positions:read` |98| `get_risk()` | `GET /risk` | `positions:read` |99| `engage_kill_switch(reason)` | `POST /risk/kill-switch` | `positions:manage` (no mandate) |100| `list_orders(mode=, venue=, open=, limit=, cursor=)`, `iter_orders(…, max_items=)` | `GET /orders` | `orders:read` |101| `get_order(order_id)` | `GET /orders/{id}` | `orders:read` |102| `wait_for_order(order_id, timeout=, poll_interval=, until=)` | polls `GET /orders/{id}` | `orders:read` |103| `preview_order(…)` → `models.OrderPreview` | `POST /orders/preview` | `orders:prepare` (a key needs a mandate bound to it) |104| `create_order(…)` → `models.PlacedOrder` | `POST /orders` | `orders:execute` + mandate |105| `cancel_order(order_id)` → `models.CancelledOrder` | `DELETE /orders/{id}` | `orders:cancel` (its own orders; no mandate) |106| `close_position(position_id, slippage_bps=)` → `models.PlacedOrder` | `POST /positions/{id}/close` | `positions:manage` + mandate |107| `reduce_position(position_id, fraction=, slippage_bps=)` → `models.PlacedOrder` | `POST /positions/{id}/reduce` | `positions:manage` + mandate |108| `run_command(text, mode=, account_id=, dry_run=)` → `models.CommandResult` | `POST /commands` | the scope of what the command resolves to |109| `list_strategies(kind=)` | `GET /strategies` | `strategies:read` |110| `create_strategy(kind=, path=, agent_id=)` → `StrategyResult` · `backtest_strategy(id)` → `JobResult` · `start_strategy(id, mode=)`, `stop_strategy(id)` → `AgentResult` | `POST /strategies…` | `strategies:manage` |111| `list_agents()` | `GET /agents` | `agents:read` |112| `list_agent_templates()`, `get_agent(agent_id)` | `GET /agents/templates`, `/agents/{id}` | `agents:read` |113| `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` |114| `get_job(job_id)`, `wait_for_job(job_id, timeout=, poll_interval=)` | `GET /jobs/{id}` | `agents:read` |115| `create_agent(name=, template=, …)`, `start_agent(id, mode=)`, `pause_agent(id)`, `stop_agent(id)` → `AgentResult` · `backtest_agent(id, hours=)` → `JobResult` | `POST /agents…` | `agents:manage` |116| `openapi()` | `GET /openapi.json` | any valid key |117118Results are pydantic models with snake_case attributes (`portfolio.totals.paper_equity`, `placed.order.avg_fill_price`,119`position.entry_price`); `result.to_dict()` gives the answer with the API's own names. Members the contract does not120name are kept (`model_extra`, also reachable as attributes). `result.meta` gives the facts of the HTTP exchange:121`status`, `request_id`, `idempotency_key`, `idempotent_replay`, `rate_limit` (`limit`, `remaining`, `reset_seconds`),122`attempts`. An answer that does not match the contract — a status outside the twelve states, a number where a decimal123string is declared — raises `ServerError` (`code == "invalid_response"`) instead of returning a half-typed object; on a124write the message says that the operation ran.125126The private markets are display only: none of these contracts is tradable (`tradable` is False on every row).127128### Pagination129130`GET /orders` and `GET /activity` are paginated by cursor: a page carries `next_cursor`, which is the `cursor` of the131next (older) page; `None` at the end. The order is stable (time, then id): no row is repeated or skipped across pages.132The iterators follow the cursor for you; `limit` is the page size.133134```python135for order in client.iter_orders(open=True, limit=100):136    print(order.id, order.status)137for item in client.iter_activity(max_items=500):138    print(item.kind, item.at)139140async for order in async_client.iter_orders(open=True):      # AsyncSPWallet: an asynchronous iterator141    ...142143page = client.list_orders(limit=50)                            # one page by hand144older = client.list_orders(limit=50, cursor=page.next_cursor) if page.next_cursor else None145```146147`list_markets` is not paginated: it answers `total` and `truncated` so a list cut by `limit` is visible.148149### Decimals150151```python152from decimal import Decimal153from sp_wallet import to_decimal, decimal_str154155book = client.get_orderbook("hyperliquid:BTC", depth=1)156bid, ask = to_decimal(book.bids[0][0]), to_decimal(book.asks[0][0])     # str → Decimal, exact157client.preview_order(instrument="hyperliquid:BTC", side="buy", order_type="limit",158                     size=Decimal("0.01"), price=int((bid + ask) / 2))   # Decimal, int or str — never float159decimal_str(Decimal("1E-7"))                                             # "0.0000001": what goes on the wire160```161162Passing a `float` anywhere an amount is expected raises `ConfigurationError` before any request.163164### Orders165166```python167order = dict(mode="paper", instrument="hyperliquid:BTC", side="buy", order_type="limit", price="60000", size="0.01")168preview = client.preview_order(**order)        # nothing is created; preview.refusals says what would refuse it169placed = client.create_order(**order)          # placed.order.status: "SUBMITTED" while it rests170client.cancel_order(placed.order.id)           # → order.status "CANCELLED", changed True171```172173- `instrument` is `venue:symbol` as returned by `list_markets`; `exchange` + `symbol` is the same thing in two parts.174- The API's `type` is the argument `order_type`. `mode` defaults to `"paper"`.175- Size the order with exactly one of `size` (base units) and `notional` (quote currency).176- **`notional` is sized by the server**: it divides by the order's own price (limit, else trigger), else by the mark177  price it reads at that moment, and rounds **down** to the lot size. A stale mark is refused (`503 stale_data`); less178  than one lot is `422 below_min_size`. The answer carries the size that was used (`preview.resolved.size`,179  `placed.order.size`). `notional_usdc` is the same field under the name of the quick start: the SDK sends it as180  `notional` and computes nothing.181- `client.get_market(instrument).instrument` gives what an order must respect: `lot_size`, `tick_size`,182  `min_order_size`, `min_notional`, `max_leverage`.183- A preview says "no" in its answer, not with an exception: `would_execute` is False and `refusals` lists each refusal184  with its `stage` (`key`, `lock`, `mandate`, `risk`, `engine`) and `code`. `preview.account.equity` and185  `free_collateral` are answered only to a key that also holds `wallet:read` or `positions:read`186  (`preview.account.withheld` is True otherwise). A key previews the order it could place: without a mandate bound to187  it, `preview_order` raises `MandateRequired`.188- `preview_order` and `engage_kill_switch` take no `Idempotency-Key` (the contract declares none): they are safe to189  repeat and are retried like a read.190191A position is closed or reduced by its `id` from `get_positions()`; both are strictly reduce-only market orders:192193```python194positions = client.get_positions(mode="paper").positions195if positions:196    client.reduce_position(positions[0].id, fraction=Decimal("0.5"))197    client.close_position(positions[0].id)198```199200### Commands and the kill switch201202```python203from sp_wallet import AmbiguousCommand, models204205try:206    r = client.run_command("LONG BTC-PERP 500 x2", dry_run=True)207    # the answer is one of four models: narrow with isinstance208    if isinstance(r, models.CommandDryRun):        # a dry run: `order` is the CANONICAL order; nothing was created209        print(r.order.instrument, r.order.notional, r.hash)210    elif isinstance(r, models.CommandExecuted):    # executed: `order` is the placed order, `canonical` its canonical form211        print(r.order.id, r.order.status, r.canonical.instrument)212    elif isinstance(r, models.CommandQuery):       # SHOW …213        print(r.query, r.data)214    elif isinstance(r, models.CommandControl):     # CANCEL, KILL, STOP ALL AGENTS215        print(r.control.type, r.executed)216except AmbiguousCommand as e:217    print([f"{q['field']}: {' | '.join(q['options'])}" for q in e.questions])   # nothing was executed218219client.engage_kill_switch("manual stop")   # blocks every NEW risk; cancels and exits still pass; only the owner releases it220```221222The grammar is deterministic (no model). What a command leaves open (venue, leverage, …) comes from the owner's stored223defaults and from nothing else; when they do not settle it, the API answers `409 ambiguous_command` with the questions.224225### Agents226227```python228templates = client.list_agent_templates().templates                      # family, engine, the modes each can run in229agent = client.create_agent(template="market-making", name="MM BTC", venues=["hyperliquid"], universe=["BTC"]).agent230client.start_agent(agent.id, mode="paper")                               # research and paper sign nothing231232# every per-agent read is ONE mode per call: `mode` is required, and an answer never mixes two ("all" is refused)233signals = client.list_agent_signals(agent.id, mode="paper", limit=50)234journal = client.list_agent_journal(agent.id, mode="paper")235orders = client.list_agent_orders(agent.id, mode="paper", open=True)236performance = client.get_agent_performance(agent.id, mode="paper")       # computed from paper records only; never a backtest237238job = client.backtest_agent(agent.id, hours=24).job                      # asynchronous239done = client.wait_for_job(job.id, timeout=120)                          # done | failed | cancelled; WaitTimeout is not a failure240client.pause_agent(agent.id)241client.stop_agent(agent.id)                                              # stop is always allowed242```243244- **`mode` on the reads.** On the wire `mode` is optional: the server answers the mode the agent is in now (for a stopped245  agent, the one it last ran in) and says which in `mode`. The SDK makes it a **required** keyword, so that code never reads246  paper figures believing they are live ones; `open` exists on `list_agent_orders` only.247- **`create_agent(mode=)`** is `"research"` (default: created, not running) or `"paper"`: an agent from a stream or248  supervisor template starts on paper at once; a bar agent (or `kind="perp"`) is created and not started — register and249  backtest a strategy version, then `start_agent`. `"live"` is refused (`400 bad_request`).250- **Paper.** Starting a perp agent on paper creates its *paper trading mandate* (nothing is signed): its orders go through251  the same order service, risk engine and kill switch as every other order. The key needs `agents:manage`, and a key252  restricted to other venues or instruments gets `403 restricted`; a halted paper account answers `409 halted`.253- **Live.** `start_agent(agent_id, mode="live")` succeeds only when a mandate the **owner** approved for that agent with the254  passkey is in force — for a perp agent a trading mandate, which only the owner activates. Otherwise `409 mandate_required`.255  A key can never approve one. Families that cannot go live answer `409 live_unavailable`.256- **Errors.** Every 409 of the agent operations is a `Conflict`; read `e.code` (`mandate_required`, `halted`, `bad_state`,257  `live_unavailable`, `no_strategy`, `no_report`, `bad_report`). `MandateRequired` (403) is about the *key's* mandate on the258  order operations, not about an agent's.259- **One kill switch.** There is no agents-side switch: `engage_kill_switch(reason)` engages the risk engine's, which stops every260  agent's new risk too. Releasing it is the owner's act, in the app. A spot agent is created in the owner's app261  (`403 owner_required`). An agent's `risk` limits are ints, bools, `Decimal`s or decimal strings — never a float.262263### Spot orders (owner session only)264265A key is refused spot execution (`403`). For the owner, a spot order is a swap proposal approved with the passkey:266a SELL names `size` (the quantity sold), a BUY names `notional` — the amount of the quote asset to spend, because a swap267is exact-input (`instrument="spot:ETH-USDC", side="buy", order_type="market", notional="100", mode="live"`).268269### Order states and `wait_for_order`270271`order.status` is one of the twelve `ORDER_STATES` — a closed enum in the contract and a `Literal` in the model:272`CREATED, VALIDATED, AWAITING_APPROVAL, APPROVED, SUBMITTING, SUBMITTED, PARTIALLY_FILLED, FILLED, CANCELLED, REJECTED,273FAILED, UNKNOWN`. Final states (`TERMINAL_ORDER_STATES`): `FILLED, CANCELLED, REJECTED, FAILED`; `order.final` is True274exactly for those. **`UNKNOWN` is not final and is not a failure**: the venue's answer is not known yet; keep reading275the order. `order.engine_status` is the executing engine's own word for the same moment (`open`, `filled`, a swap276state…): it is informative — decide on `status`.277278```python279done = client.wait_for_order(order_id, timeout=60, poll_interval=1)280print(done.order.status, done.order.filled, len(done.fills))281```282283`wait_for_order` returns when the status is final (or when `until(order)` is true) and raises `WaitTimeout` when the284time elapses first — that is not an order failure either; `error.last` is the last answer.285286## Errors287288Every error extends `SPWalletError` and carries `code` (the API's `error` member), `message`, `status`, `request_id`289(`X-Request-Id`: the owner finds the call in the usage log with it), `body`, `data` (the refusal's machine-readable290detail) and, for mutating calls, `idempotency_key`.291292| Class | When |293|---|---|294| `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 |295| `AuthenticationError` | 401 `unauthenticated` — missing, malformed, unknown, expired or revoked key (one answer for all) |296| `PermissionDenied` | 403 — `restricted`, `ip_not_allowed`, `key_limit_exceeded`, `not_your_order`… |297| ↳ `ScopeDenied` | 403 `insufficient_scope` — the key does not hold the operation's scope |298| ↳ `MandateRequired` | 403 `mandate_required` — no trading mandate is bound to the key |299| ↳ `MandateDenied` | 403 `mandate_denied` — the order is outside the mandate; `error.reasons` (`MANDATE_DENY_REASONS`: `ORDER_NOTIONAL_EXCEEDED`, `INSTRUMENT_NOT_ALLOWED`…) |300| ↳ `ExecutionDisabled` | 403 `execution_disabled` — live execution through the API is closed on this server; nothing was created |301| `RiskDenied` | 422 `risk_denied`, 423 `kill_switch_active` / `read_only_mode` — `error.failed` (ids of `RISK_CHECK_IDS`), `error.checks`, `error.kill_switch` |302| `NotFound` | 404 `unknown_order`, `unknown_instrument`, `unknown_venue`, `unknown_market`, `unknown_position`, `not_found` (a path that is not an operation)… |303| `Conflict` | 409 |304| ↳ `IdempotencyConflict` | 409 `idempotency_conflict` — the key was used with a different request |305| ↳ `AmbiguousSymbol` | 409 `ambiguous_symbol` — `error.candidates` lists the `venue:symbol` ids |306| ↳ `AmbiguousCommand` | 409 `ambiguous_command` — `error.questions`; nothing was executed |307| `RateLimited` | 429 `rate_limited`, `auth_throttled` — `error.retry_after` (seconds) |308| `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 |309| `ServerError` ↳ `ServiceUnavailable` | 5xx; 503 `signer_unreachable`, `venue_unavailable`, `markets_unavailable`, `stale_data`…; `invalid_response` |310| `NetworkError` ↳ `sp_wallet.TimeoutError` | no answer (reads, previews) |311| `OutcomeUnknown` | a mutating call without a trustworthy answer — **not a failure**, see below |312| `WaitTimeout`, `WebhookVerificationError`, `ConfigurationError` | SDK-side |313314**`error.order`**: when the server created the order before it refused it (a mandate or risk refusal, a refusal of the315venue engine), the error carries that order as a `models.Order` — state `REJECTED` or `FAILED` — so you know its id. It316is `None` when the call was refused before any order existed (nothing was created). The codes each operation can answer317are in the contract (`x-spw-errors`) and in the SDK as `OPERATION_ERRORS[operation_id]`.318319```python320from sp_wallet import ExecutionDisabled, MandateDenied, MandateRequired, OutcomeUnknown, RateLimited, RiskDenied, ScopeDenied321322try:323    client.create_order(instrument="hyperliquid:BTC", side="buy", order_type="market", notional="100", mode="paper")324except OutcomeUnknown:325    ...                                    # see "OutcomeUnknown"326except MandateRequired:327    ...                                    # the owner must bind an approved mandate to this key328except MandateDenied as e:329    print(e.reasons, e.order.id if e.order else None)          # ['ORDER_NOTIONAL_EXCEEDED'] …330except RiskDenied as e:331    print("kill switch" if e.kill_switch else e.failed, [(c.id, c.observed, c.limit) for c in e.checks])332except ExecutionDisabled:333    ...                                    # live orders are closed on this server; paper is not affected334except ScopeDenied:335    ...                                    # the key lacks orders:execute336except RateLimited as e:337    ...                                    # wait e.retry_after seconds338```339340## Retries and idempotency341342- **Reads (`GET`)** are retried on a network error, a timeout, `429` (after `Retry-After`, else `RateLimit-Reset`) and343  `502 / 503 / 504`, with exponential backoff (0.5 s × 2ⁿ, capped at 8 s) and jitter (50–100 % of the step).344- **Mutating calls (`POST`, `DELETE`)** are retried **only because they carry an `Idempotency-Key`**. The SDK creates one345  UUIDv4 per logical call when you give none, serializes the body **once** in canonical form (sorted keys — byte for346  byte the server's canonical form), and sends the **same key and the same bytes** on every retry. The server then runs347  the operation at most once: the same key with the same request returns the first answer348  (`result.meta.idempotent_replay`), with a different request `409 idempotency_conflict`.349- The key is exposed three ways so that you can resume after a crash: pass your own (`idempotency_key=`, generate it350  with `new_idempotency_key()` and **persist it before sending**), read it from `result.meta.idempotency_key`, or from351  `error.idempotency_key`.352- `preview_order` and `engage_kill_switch` are `POST`s without an `Idempotency-Key` in the contract (repeating them353  changes nothing): they are retried like a read and fail with the ordinary errors, never `OutcomeUnknown`.354- Not retried: 400, 401, 403, 404, 409 (except `idempotency_in_progress`), 422, 423, 500, 501.355356### `OutcomeUnknown`357358A mutating call that ends without a trustworthy answer — timeout, connection lost, `500/502/504`, a `503` that does not359come from the API, the first request with this key still running, or an answer decided before the server looked at the360key (401, 403, 429) after an attempt without an answer — raises `OutcomeUnknown`. **It is not a failure**: the operation361may or may not have been executed.362363```python364key = new_idempotency_key()           # persist it365try:366    client.create_order(**order, idempotency_key=key)367except OutcomeUnknown as e:368    # 1. re-send the SAME call with the SAME key: the server returns the stored answer if it ran, or runs it once369    result = client.create_order(**order, idempotency_key=e.idempotency_key)370    # 2. or read the object: client.get_order(order_id) / client.list_orders(open=True)371    # Never re-send with a NEW key: that could execute the operation twice.372```373374## Key rotation and the trading mandate375376A trading mandate names **one principal — the key id it was approved for** — and a rotation gives the key a new id. The377rotation therefore does **not** carry the mandate: the new key keeps the scopes, limits, restrictions and expiry, and is378**unbound**. Until the owner approves a mandate for the new id and binds it, `create_order`, `close_position` and379`reduce_position` raise `MandateRequired` (and `preview_order` too); reads, cancels of its own orders, the kill switch and380agent management keep working. The answer of the rotation says so:381`{"key": {"mandateId": null, "inertScopes": […]}, "secret": …, "revoked": …, "mandate": {"carried": false, "mandateId": "<old mandate>", "code": "mandate_principal_mismatch", "note": …}}`.382383```python384try:385    client.create_order(**order)386except MandateRequired:387    ...   # after a rotation: ask the owner for a mandate for THIS key id, then retry — nothing was created388```389390The owner's side of it (owner session and passkey — nothing a key can do):391392```bash393# 1. a mandate for the NEW key id: created, then approved (a live mandate is approved with the passkey at the signer)394POST /api/v1/mandates                         { "principal": { "kind": "api_key", "id": "<new key id>" }, "mode": "paper", "accountIds": ["…"], … }395POST /api/v1/mandates/<mandate id>/approve    { }                      # live: /approve/prepare first, then the passkey assertion396# 2. bind it to the key (binding gives the key authority: passkey)397POST /api/v1/developer/keys/<new key id>/update/prepare   { "changes": { "mandateId": "<mandate id>" } }398POST /api/v1/developer/keys/<new key id>/update           { "intentId": "…", "assertion": { … } }399```400401In the app: Developer → the key → *Trading mandate* → *New mandate*.402403## Streaming404405Live market data over one websocket: quotes, order books, trades, candles and venue statuses. Read-only (scope406`markets:read`), same key, same restrictions (a channel of a venue or instrument outside the key's restrictions is refused,407per subscription). The client is asynchronous and needs the optional dependency `websockets`:408409```bash410pip install "sp-wallet-python[stream]"      # in the repository: uv sync --extra stream411```412413`SPWalletStream`, `OrderBook`, `StreamError`, `book_checksum` and `channel_key` are exported by `sp_wallet` and loaded on414first use: `import sp_wallet` works on a base install, and `websockets` is imported only when a stream connects.415416```python417import asyncio418from sp_wallet import SPWalletStream419from sp_wallet.stream import Quote420421async def main() -> None:422    async with SPWalletStream(base_url="https://wallet.example") as stream:     # the key: SP_WALLET_API_KEY, in the Authorization header423        stream.on("close", lambda c: print("closed;", "reconnecting" if c["will_reconnect"] else "stopped"))424        stream.on("error", lambda e: print("stream error:", e.code))425        await stream.subscribe([{"type": "quote", "id": "hyperliquid:BTC"}, {"type": "status", "id": "hyperliquid"}])426        async for m in stream:                                                  # or stream.on("quote", …)427            if isinstance(m, Quote):428                print(m.id, m.bid, m.ask, m.mark, m.stale)                      # decimal strings; `stale` is the server's verdict429430asyncio.run(main())431```432433- **Channels**: `quote`, `book` (`depth`), `trades`, `candles` (`interval`), `status` (`id`: a venue or `"*"`). Ids are434  `<venue>:<instrument>` (`hyperliquid:BTC`, `dydx:BTC-USD`, `spot:BTC`). Messages are models: `Quote`, `Book`, `Trades`,435  `Candle`, `VenueStatus` (snake_case attributes: `recv_ts`, `venue_ts`, `bid_size`).436- **Reconnection** is on by default (`reconnect=False` to turn it off): exponential backoff with jitter between `backoff_min`437  and `backoff_max`; after a reconnection the client subscribes again to everything and the server sends fresh snapshots.438  `close` events carry `will_reconnect`. A refusal that a retry cannot fix (no `markets:read`, revoked key, unknown439  instrument) is a `StreamError` with the server's `code`, and is not retried.440- **Order books**: feed every `Book` to an `OrderBook`; `apply()` returns `False` on a sequence hole or a checksum mismatch —441  `await stream.resync(channel)` and the server restarts the book from a snapshot.442- **Slow consumers**: quotes are conflated and a `dropped` event says what was skipped; the iterator's buffer is bounded by443  `buffer_size`.444- A stream connection writes **no row in the key's usage log** (the ticket request does).445446### Browsers and proxies: the ticket flow447448A 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)449with the key — `POST /api/v1/trading/stream/ticket`, answer `{ ticket, expiresAt, ttlMs, url, protocol }` — and hands only450the ticket to the page, which connects to `/api/v1/trading/stream?ticket=…` (in the TypeScript SDK:451`new SPWalletStream({ baseUrl, ticket: () => … })`, see `docs/sdk/typescript.md`). A Python backend:452453```python454import httpx, os455456def stream_ticket() -> str:                    # behind YOUR authentication; a new ticket for every (re)connection457    r = httpx.post(f"{WALLET}/api/v1/trading/stream/ticket", headers={"authorization": f"Bearer {os.environ['SP_WALLET_API_KEY']}"}, json={})458    r.raise_for_status()459    return r.json()["ticket"]460```461462The ticket carries the key's scope and restrictions, works once, and is refused when mixed with another credential. The463Python client can connect that way too: `SPWalletStream(auth="ticket")` asks for the ticket itself with its key (useful464behind a proxy that strips headers on upgrade), and `SPWalletStream(ticket=my_async_function)` uses yours.465466## Webhooks467468The wallet signs every delivery: `X-SPW-Timestamp: <unix seconds>` and469`X-SPW-Signature: v1=<hex HMAC-SHA256(secret, "<timestamp>.<raw body>")>`. Verify over the **raw** body, before parsing:470471```python472from sp_wallet import construct_webhook_event, WebhookVerificationError473474event = construct_webhook_event(475    secret=os.environ["SP_WALLET_WEBHOOK_SECRET"],476    timestamp=request.headers.get("x-spw-timestamp"), signature=request.headers.get("x-spw-signature"),477    body=raw_body,                    # bytes or str, exactly as received478)                                     # raises WebhookVerificationError; tolerance 300 s; hmac.compare_digest479```480481`verify_webhook(…)` returns a boolean instead. Delivery is at-least-once: deduplicate on `event["id"]`. Events:482`key.revoked`, `risk.kill_switch`, `agent.updated`, `order.updated` (one event per transition of an order),483`risk.proposal`.484A complete receiver: `sdk/python/examples/webhook_receiver.py`.485486## Examples487488```bash489cd sdk/python && uv sync490SP_WALLET_API_KEY=spw_live_… uv run python examples/read_only.py       # read-only tour491SP_WALLET_API_KEY=spw_live_… uv run python examples/async_read.py      # the asynchronous client492SP_WALLET_API_KEY=spw_live_… uv run python examples/preview_order.py   # a preview with every outcome handled493SP_WALLET_API_KEY=spw_live_… uv run python examples/paper_order.py     # PAPER: preview → place → wait → position → close494SP_WALLET_API_KEY=spw_live_… uv run --extra stream python examples/stream_quotes.py   # live quotes over the websocket, with reconnection495```496497The five are executed against the real API by the integration tests.498499## Development500501```bash502cd sdk/python503uv sync504uv run python scripts/gen_models.py [--check]    # src/sp_wallet/models.py from the OpenAPI document505uv run python scripts/gen_sync.py [--check]      # src/sp_wallet/_client.py (sync) from _async_client.py506uv run ruff check507uv run pytest                                    # unit tests + integration test508SPW_SDK_INTEGRATION=off uv run pytest            # unit tests only509```510511The synchronous client is generated from the asynchronous one: one implementation, the same behaviour by construction.512The integration test starts the real API and the real signer on an own database513(`packages/trading-sdk/scripts/test-stack.mts`; it needs the repository's `node_modules` and PostgreSQL), creates514keys, a paper account and paper mandates through the owner flow, calls every method with both clients and runs the515whole **paper** write path (preview → order → fill → reduce → close → resting order → cancel, replay and conflict, the516refusals, the kill switch, commands) and an agent on paper (create from a template → start → signals, journal, orders,517performance → pause → backtest job → stop); every answer is validated against the OpenAPI document, closed objects included.518No live order is sent: the live case stops at `execution_disabled`. It is **skipped** (reported as skipped) when519PostgreSQL is not reachable; a test whose venue cannot be read is skipped with that reason.520521## NFT reads522523Five 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`.524
Files main
Menu

Theme