Repository Public
1{2 "openapi": "3.1.0",3 "info": {4 "title": "SP Trading API",5 "version": "1.0.0",6 "description": "Machine interface of SP Wallet: market data, portfolio, positions, orders, strategies and agents.\n\nHuman-readable reference, generated from this document and served by the same server: `GET /api/v1/trading/docs` (HTML: getting started, concepts, one section per operation, the error catalogue) and `GET /api/v1/trading/docs.md` (the same as Markdown). Those two paths and the websocket below are the only paths under the prefix that are not operations of this document.\n\nEvery operation carries a worked example: the request (`example` on parameters and on the request body), the 200 answer (`example` on the response; `x-spw-example-recorded: true` when it is a real recorded answer), and the same call as curl, TypeScript and Python (`x-codeSamples`; `client` is an `SPWallet` of the SDK, built from the environment variables `SP_WALLET_API_KEY` and `SP_WALLET_BASE_URL`).\n\nWhat each error code means and what to do about it: `x-spw-error-catalog` (every code of every `x-spw-errors`). The reasons of a `mandate_denied`: `x-spw-mandate-deny-reason-docs`. The twelve order states: `x-spw-order-states`, each explained in `x-spw-order-state-docs`; the scopes in `x-spw-scope-docs`.\n\nLive trading with a key exists on Hyperliquid only (the perpetuals of its own dex, ids `hyperliquid:BTC`); GMX orders are the owner's, approved in the app; dYdX and edgeX are market data only. Paper orders are simulated by the wallet against the real Hyperliquid order book.\n\nAuthentication: `Authorization: Bearer spw_live_…` (an API key created by the owner with his passkey). A key opens nothing outside `/api/v1/trading/`.\n\nEvery operation names the scope it needs (`x-spw-scope`). Scopes are access control inside the API; they are not what bounds execution: an order placed with a key is bounded by a trading mandate that the isolated signer enforces, and execution scopes are inert without one.\n\nNumbers that carry money are decimal strings. Paper and live data always carry a `mode` and are never merged.\n\nErrors are `{ \"error\": \"<code>\", \"message\": \"<sentence>\" }`, with `data` when a refusal has machine-readable detail (the order it is about, the mandate's reasons, the failed risk checks, the questions of an ambiguous command). Every operation lists the codes it can answer, with their status, in `x-spw-errors`. A 400 `bad_request` produced by input validation also carries `data.fields`: one `{ path, code, message }` per refused member (what is expected, never the value that was sent). Rate limits are per key: `RateLimit-Limit`, `RateLimit-Remaining`, `RateLimit-Reset` (seconds).\n\nA path that is not an operation of this document (or a known path with another method) answers 404 `not_found` in the same error model.\n\nLive market data (quotes, order books, trades, candles, venue statuses) is also served over a websocket, which this document cannot describe: `GET /api/v1/trading/stream` (scope `markets:read`; the key in the `Authorization` header of the handshake, or `?ticket=` with a single-use ticket from `POST /api/v1/trading/stream/ticket`). See `docs/V11-QUOTE-ENGINE.md`. A stream connection writes no row in the key's usage log — it is counted in the stream's own statistics; the ticket request is an ordinary call and is logged like any other.\n\nAn order's `status` is one of the twelve states of `x-spw-order-states`; `final` is true for the states marked final. `UNKNOWN` is neither final nor a failure. Lists that can grow without bound (`GET /orders`, `GET /activity`) are paginated with `cursor` / `nextCursor`."7 },8 "servers": [9 {10 "url": "/",11 "description": "the wallet's own origin"12 }13 ],14 "externalDocs": {15 "description": "Reference: getting started, concepts, examples, error catalogue (HTML; add `.md` for Markdown)",16 "url": "/api/v1/trading/docs"17 },18 "tags": [19 {20 "name": "Meta",21 "description": "The contract itself."22 },23 {24 "name": "Markets",25 "description": "Public market data: instruments across venues, tickers, order books, candles, the venue comparator, and the synthetic contracts on private companies. Scope `markets:read`. Reading a venue does not mean it can be traded: live orders with a key exist on Hyperliquid only."26 },27 {28 "name": "Portfolio",29 "description": "What the wallet holds: on-chain balances, the valued portfolio with every derivatives account, and the activity feed. Scope `wallet:read`. Paper and live are separate figures, never summed."30 },31 {32 "name": "Nfts",33 "description": "Read-only NFT data: the wallet's inventory (`wallet:read`) and market data of any item (`markets:read`). No transfer and no market write exists in this API. An NFT never has a value here."34 },35 {36 "name": "Positions",37 "description": "Open positions, and the two ways out of one: close and reduce — strictly reduce-only market orders. Closing passes the kill switch."38 },39 {40 "name": "Orders",41 "description": "Preview, place, read and cancel orders, and the one-line command grammar. Every order passes the key, the mandate, the risk engine and the venue engine, in that order; a refusal names its gate."42 },43 {44 "name": "Strategies",45 "description": "The strategy library and the versions pinned to agents: register, backtest, start, stop. Research and paper sign nothing."46 },47 {48 "name": "Agents",49 "description": "Trading agents: templates, lifecycle (create, start, pause, stop), and their history read ONE mode per call (research, paper or live). An agent goes live only under its own owner-approved mandate."50 },51 {52 "name": "Risk",53 "description": "The state of the risk engine and of the server locks, and the one control a key has: engaging the global kill switch (never releasing it)."54 }55 ],56 "paths": {57 "/api/v1/trading/openapi.json": {58 "get": {59 "operationId": "getOpenApi",60 "tags": [61 "Meta"62 ],63 "summary": "This document",64 "description": "OpenAPI 3.1 document generated from the route schemas. Any valid key or the owner session.",65 "security": [66 {67 "bearerKey": []68 }69 ],70 "x-spw-scope": "any valid key",71 "x-spw-implemented": true,72 "x-spw-errors": [73 {74 "status": 401,75 "code": "unauthenticated"76 },77 {78 "status": 403,79 "code": "ip_not_allowed"80 },81 {82 "status": 403,83 "code": "mixed_credentials"84 },85 {86 "status": 429,87 "code": "auth_throttled"88 },89 {90 "status": 429,91 "code": "rate_limited"92 },93 {94 "status": 500,95 "code": "internal"96 }97 ],98 "x-spw-example-recorded": false,99 "x-spw-example-note": "Cut: the real document describes every operation, schema and error code.",100 "x-codeSamples": [101 {102 "lang": "Shell",103 "label": "curl",104 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/openapi.json\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""105 },106 {107 "lang": "TypeScript",108 "label": "TypeScript",109 "source": "const doc = await client.openapi();"110 },111 {112 "lang": "Python",113 "label": "Python",114 "source": "doc = client.openapi()"115 }116 ],117 "parameters": [],118 "responses": {119 "200": {120 "description": "OK",121 "content": {122 "application/json": {123 "schema": {124 "type": "object",125 "properties": {126 "openapi": {127 "type": "string"128 }129 },130 "required": [131 "openapi"132 ],133 "additionalProperties": {}134 },135 "example": {136 "openapi": "3.1.0",137 "info": {138 "title": "SP Trading API",139 "version": "1.0.0"140 },141 "paths": {142 "/api/v1/trading/markets": {143 "get": {144 "operationId": "listMarkets"145 }146 }147 }148 }149 }150 }151 },152 "401": {153 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",154 "content": {155 "application/json": {156 "schema": {157 "$ref": "#/components/schemas/Error"158 }159 }160 }161 },162 "403": {163 "description": "Authenticated, and refused: `ip_not_allowed`, `mixed_credentials`",164 "content": {165 "application/json": {166 "schema": {167 "$ref": "#/components/schemas/Error"168 }169 }170 }171 },172 "429": {173 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",174 "content": {175 "application/json": {176 "schema": {177 "$ref": "#/components/schemas/Error"178 }179 }180 }181 },182 "500": {183 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",184 "content": {185 "application/json": {186 "schema": {187 "$ref": "#/components/schemas/Error"188 }189 }190 }191 }192 }193 }194 },195 "/api/v1/trading/markets": {196 "get": {197 "operationId": "listMarkets",198 "tags": [199 "Markets"200 ],201 "summary": "Instruments across venues (perpetuals) and the spot market-data symbols",202 "description": "Each row carries the time its source produced it (`ts`) and a `stale` flag. A venue that cannot be read is listed in `errors`; when no source answers the call fails with 503. An unknown `venue` answers 404 `unknown_venue`. Not paginated: `total` and `truncated` tell when `limit` cut the list.",203 "security": [204 {205 "bearerKey": [206 "markets:read"207 ]208 }209 ],210 "x-spw-scope": "markets:read",211 "x-spw-implemented": true,212 "x-spw-errors": [213 {214 "status": 400,215 "code": "bad_request"216 },217 {218 "status": 401,219 "code": "unauthenticated"220 },221 {222 "status": 403,223 "code": "insufficient_scope"224 },225 {226 "status": 403,227 "code": "ip_not_allowed"228 },229 {230 "status": 403,231 "code": "mixed_credentials"232 },233 {234 "status": 403,235 "code": "restricted"236 },237 {238 "status": 404,239 "code": "unknown_venue"240 },241 {242 "status": 429,243 "code": "auth_throttled"244 },245 {246 "status": 429,247 "code": "rate_limited"248 },249 {250 "status": 500,251 "code": "internal"252 },253 {254 "status": 503,255 "code": "markets_unavailable"256 },257 {258 "status": 503,259 "code": "venue_rate_limited"260 },261 {262 "status": 503,263 "code": "venue_timeout"264 },265 {266 "status": 503,267 "code": "venue_unavailable"268 }269 ],270 "x-spw-example-recorded": true,271 "x-codeSamples": [272 {273 "lang": "Shell",274 "label": "curl",275 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/markets?venue=hyperliquid&q=BTC&limit=3\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""276 },277 {278 "lang": "TypeScript",279 "label": "TypeScript",280 "source": "const { markets } = await client.listMarkets({ venue: 'hyperliquid', q: 'BTC', limit: 3 });"281 },282 {283 "lang": "Python",284 "label": "Python",285 "source": "markets = client.list_markets(venue=\"hyperliquid\", q=\"BTC\", limit=3).markets"286 }287 ],288 "parameters": [289 {290 "name": "venue",291 "in": "query",292 "required": false,293 "description": "venue id: hyperliquid, gmx, dydx, spot",294 "schema": {295 "type": "string",296 "maxLength": 40297 },298 "example": "hyperliquid"299 },300 {301 "name": "kind",302 "in": "query",303 "required": false,304 "description": "perpetual = a venue instrument; spot = a market-data symbol",305 "schema": {306 "type": "string",307 "enum": [308 "perpetual",309 "spot"310 ]311 }312 },313 {314 "name": "q",315 "in": "query",316 "required": false,317 "description": "case-insensitive match on id, symbol or base",318 "schema": {319 "type": "string",320 "maxLength": 40321 },322 "example": "BTC"323 },324 {325 "name": "limit",326 "in": "query",327 "required": false,328 "description": "rows returned at most; `total` and `truncated` say when it cut the list",329 "schema": {330 "default": 2000,331 "type": "integer",332 "minimum": 1,333 "maximum": 5000334 },335 "example": 3336 }337 ],338 "responses": {339 "200": {340 "description": "OK (the example is a recorded answer)",341 "content": {342 "application/json": {343 "schema": {344 "type": "object",345 "properties": {346 "markets": {347 "type": "array",348 "items": {349 "type": "object",350 "properties": {351 "id": {352 "type": "string"353 },354 "venue": {355 "type": "string"356 },357 "kind": {358 "type": "string",359 "enum": [360 "perpetual",361 "spot"362 ]363 },364 "symbol": {365 "type": "string"366 },367 "base": {368 "type": "string"369 },370 "quote": {371 "type": "string"372 },373 "status": {374 "type": "string"375 },376 "mark": {377 "anyOf": [378 {379 "type": "string",380 "description": "decimal number as a string (never a float)"381 },382 {383 "type": "null"384 }385 ]386 },387 "ts": {388 "anyOf": [389 {390 "type": "integer",391 "minimum": -9007199254740991,392 "maximum": 9007199254740991,393 "description": "milliseconds since the Unix epoch"394 },395 {396 "type": "null"397 }398 ],399 "description": "time the source produced this row (venue read time, or the last consolidated bar for spot)"400 },401 "stale": {402 "type": "boolean",403 "description": "true when the row is older than its freshness bound or the source could not be refreshed"404 }405 },406 "required": [407 "id",408 "venue",409 "kind",410 "symbol",411 "base",412 "quote",413 "status",414 "mark",415 "ts",416 "stale"417 ],418 "additionalProperties": {}419 }420 },421 "total": {422 "type": "integer",423 "minimum": -9007199254740991,424 "maximum": 9007199254740991,425 "description": "rows matching the filters, before `limit`"426 },427 "truncated": {428 "type": "boolean"429 },430 "errors": {431 "type": "array",432 "items": {433 "type": "object",434 "properties": {435 "source": {436 "type": "string"437 },438 "message": {439 "type": "string"440 }441 },442 "required": [443 "source",444 "message"445 ],446 "additionalProperties": false447 }448 },449 "ts": {450 "type": "integer",451 "minimum": -9007199254740991,452 "maximum": 9007199254740991,453 "description": "milliseconds since the Unix epoch"454 }455 },456 "required": [457 "markets",458 "total",459 "truncated",460 "errors",461 "ts"462 ],463 "additionalProperties": false464 },465 "example": {466 "markets": [467 {468 "id": "hyperliquid:BTC",469 "venue": "hyperliquid",470 "kind": "perpetual",471 "symbol": "BTC",472 "base": "BTC",473 "quote": "USD",474 "status": "active",475 "mark": "64432",476 "index": "64460.7",477 "funding": "0.0000089721",478 "fundingIntervalSec": 3600,479 "volume24h": "3621656019.2002997398",480 "openInterest": "37680.57528",481 "maxLeverage": "40",482 "tickSize": "0.1",483 "lotSize": "0.00001",484 "collateral": "USDC",485 "restriction": null,486 "ts": 1794953721101,487 "stale": false,488 "source": "venue"489 }490 ],491 "total": 1,492 "truncated": false,493 "errors": [],494 "ts": 1794953721103495 }496 }497 }498 },499 "400": {500 "description": "The request is not valid: `bad_request`",501 "content": {502 "application/json": {503 "schema": {504 "$ref": "#/components/schemas/Error"505 }506 }507 }508 },509 "401": {510 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",511 "content": {512 "application/json": {513 "schema": {514 "$ref": "#/components/schemas/Error"515 }516 }517 }518 },519 "403": {520 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",521 "content": {522 "application/json": {523 "schema": {524 "$ref": "#/components/schemas/Error"525 }526 }527 }528 },529 "404": {530 "description": "The object named by the request does not exist: `unknown_venue`",531 "content": {532 "application/json": {533 "schema": {534 "$ref": "#/components/schemas/Error"535 }536 }537 }538 },539 "429": {540 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",541 "content": {542 "application/json": {543 "schema": {544 "$ref": "#/components/schemas/Error"545 }546 }547 }548 },549 "500": {550 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",551 "content": {552 "application/json": {553 "schema": {554 "$ref": "#/components/schemas/Error"555 }556 }557 }558 },559 "503": {560 "description": "A backing service is unavailable; nothing was done: `markets_unavailable`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",561 "content": {562 "application/json": {563 "schema": {564 "$ref": "#/components/schemas/Error"565 }566 }567 }568 }569 }570 }571 },572 "/api/v1/trading/markets/compare": {573 "get": {574 "operationId": "compareMarkets",575 "tags": [576 "Markets"577 ],578 "summary": "Compare the estimated cost of one position across venues",579 "description": "One row per venue for a common underlying, from the real instrument, order book (GMX: pool figures), ticker, fee schedule and funding rate read now: spread, depth within 10/25/50 bps, slippage for the notional, fees, funding expected over the horizon (current rate held constant), collateral, liquidation estimate and the itemised total. Every figure is an estimate; a missing input gives null with its reason. Venues the wallet cannot trade on are shown and flagged. `discrepancies` are estimates with their assumptions and risks, never a recommendation.",580 "security": [581 {582 "bearerKey": [583 "markets:read"584 ]585 }586 ],587 "x-spw-scope": "markets:read",588 "x-spw-implemented": true,589 "x-spw-errors": [590 {591 "status": 400,592 "code": "bad_request"593 },594 {595 "status": 401,596 "code": "unauthenticated"597 },598 {599 "status": 403,600 "code": "insufficient_scope"601 },602 {603 "status": 403,604 "code": "ip_not_allowed"605 },606 {607 "status": 403,608 "code": "mixed_credentials"609 },610 {611 "status": 403,612 "code": "restricted"613 },614 {615 "status": 404,616 "code": "unknown_underlying"617 },618 {619 "status": 429,620 "code": "auth_throttled"621 },622 {623 "status": 429,624 "code": "rate_limited"625 },626 {627 "status": 500,628 "code": "internal"629 },630 {631 "status": 503,632 "code": "venue_rate_limited"633 },634 {635 "status": 503,636 "code": "venue_timeout"637 },638 {639 "status": 503,640 "code": "venue_unavailable"641 }642 ],643 "x-spw-example-recorded": true,644 "x-spw-example-note": "Cut to one row and one discrepancy. dYdX and edgeX rows are information: `tradable` is false on them.",645 "x-codeSamples": [646 {647 "lang": "Shell",648 "label": "curl",649 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/markets/compare?underlying=BTC&side=long¬ional=1000&leverage=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""650 },651 {652 "lang": "TypeScript",653 "label": "TypeScript",654 "source": "const cmp = await client.compareMarkets({ underlying: 'BTC', side: 'long', notional: '1000', leverage: '2' });"655 },656 {657 "lang": "Python",658 "label": "Python",659 "source": "cmp = client.compare_markets(underlying=\"BTC\", side=\"long\", notional=\"1000\", leverage=\"2\")"660 }661 ],662 "parameters": [663 {664 "name": "underlying",665 "in": "query",666 "required": false,667 "description": "common underlying, e.g. BTC (see GET /markets-hub/underlyings)",668 "schema": {669 "default": "BTC",670 "type": "string",671 "pattern": "^[A-Za-z0-9]{1,15}$"672 },673 "example": "BTC"674 },675 {676 "name": "side",677 "in": "query",678 "required": false,679 "description": "direction of the position compared",680 "schema": {681 "default": "long",682 "type": "string",683 "enum": [684 "long",685 "short"686 ]687 },688 "example": "long"689 },690 {691 "name": "notional",692 "in": "query",693 "required": false,694 "description": "position notional in USD (not the collateral)",695 "schema": {696 "default": "1000",697 "type": "string",698 "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"699 },700 "example": "1000"701 },702 {703 "name": "leverage",704 "in": "query",705 "required": false,706 "description": "leverage of the position: collateral = notional / leverage",707 "schema": {708 "default": "1",709 "type": "string",710 "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"711 },712 "example": "2"713 },714 {715 "name": "horizonHours",716 "in": "query",717 "required": false,718 "description": "expected holding period; funding is the current rate held constant over it",719 "schema": {720 "default": "24",721 "type": "string",722 "pattern": "^(0|[1-9]\\d{0,3})(\\.\\d{1,4})?$"723 }724 },725 {726 "name": "liquidity",727 "in": "query",728 "required": false,729 "description": "how the entry and the exit are executed, for the fee",730 "schema": {731 "default": "taker",732 "type": "string",733 "enum": [734 "taker",735 "maker"736 ]737 }738 },739 {740 "name": "minNetEdgeBps",741 "in": "query",742 "required": false,743 "description": "a discrepancy estimate above this is flagged",744 "schema": {745 "default": "0",746 "type": "string",747 "pattern": "^(0|[1-9]\\d{0,4})(\\.\\d{1,4})?$"748 }749 }750 ],751 "responses": {752 "200": {753 "description": "OK (the example is a recorded answer)",754 "content": {755 "application/json": {756 "schema": {757 "type": "object",758 "properties": {759 "underlying": {760 "type": "string"761 },762 "category": {763 "type": [764 "string",765 "null"766 ]767 },768 "request": {769 "type": "object",770 "properties": {},771 "additionalProperties": {}772 },773 "rows": {774 "type": "array",775 "items": {776 "type": "object",777 "properties": {778 "venue": {779 "type": "string"780 },781 "instrument": {782 "type": "string"783 },784 "tradable": {785 "type": "boolean",786 "description": "false: the wallet cannot trade this venue or instrument; the row is shown for information"787 },788 "tradableReason": {789 "type": [790 "string",791 "null"792 ]793 },794 "cost": {795 "anyOf": [796 {797 "type": "object",798 "properties": {},799 "additionalProperties": {}800 },801 {802 "type": "null"803 }804 ],805 "description": "itemised estimate: every component is { value, reason, basis } — value null WITH the reason when an input is missing"806 },807 "priceOutlier": {808 "type": "boolean"809 },810 "ageMs": {811 "type": [812 "number",813 "null"814 ]815 },816 "stale": {817 "type": "boolean"818 }819 },820 "required": [821 "venue",822 "instrument",823 "tradable",824 "tradableReason",825 "cost",826 "priceOutlier",827 "ageMs",828 "stale"829 ],830 "additionalProperties": {}831 }832 },833 "discrepancies": {834 "type": "array",835 "items": {836 "type": "object",837 "properties": {838 "longVenue": {839 "type": "string"840 },841 "shortVenue": {842 "type": "string"843 },844 "netEdgeEstimateBps": {845 "anyOf": [846 {847 "type": "string",848 "description": "decimal number as a string (never a float)"849 },850 {851 "type": "null"852 }853 ],854 "description": "an ESTIMATE under `assumptions`, with `risks`"855 },856 "flagged": {857 "type": "boolean"858 },859 "actionableFromWallet": {860 "type": "boolean"861 },862 "assumptions": {863 "type": "array",864 "items": {865 "type": "object",866 "properties": {867 "code": {868 "type": "string"869 },870 "text": {871 "type": "string"872 }873 },874 "required": [875 "code",876 "text"877 ],878 "additionalProperties": false879 }880 },881 "risks": {882 "type": "array",883 "items": {884 "type": "object",885 "properties": {886 "code": {887 "type": "string"888 },889 "text": {890 "type": "string"891 }892 },893 "required": [894 "code",895 "text"896 ],897 "additionalProperties": false898 }899 }900 },901 "required": [902 "longVenue",903 "shortVenue",904 "netEdgeEstimateBps",905 "flagged",906 "actionableFromWallet",907 "assumptions",908 "risks"909 ],910 "additionalProperties": {}911 }912 },913 "texts": {914 "type": "object",915 "properties": {916 "disclaimer": {917 "type": "string"918 }919 },920 "required": [921 "disclaimer"922 ],923 "additionalProperties": {}924 },925 "warnings": {926 "type": "array",927 "items": {928 "type": "string"929 }930 },931 "errors": {932 "type": "array",933 "items": {934 "type": "object",935 "properties": {936 "source": {937 "type": "string"938 },939 "message": {940 "type": "string"941 }942 },943 "required": [944 "source",945 "message"946 ],947 "additionalProperties": false948 }949 },950 "ts": {951 "type": "integer",952 "minimum": -9007199254740991,953 "maximum": 9007199254740991,954 "description": "milliseconds since the Unix epoch"955 },956 "source": {957 "type": "string"958 }959 },960 "required": [961 "underlying",962 "category",963 "request",964 "rows",965 "discrepancies",966 "texts",967 "warnings",968 "errors",969 "ts",970 "source"971 ],972 "additionalProperties": {}973 },974 "example": {975 "underlying": "BTC",976 "category": "crypto",977 "request": {978 "underlying": "BTC",979 "side": "long",980 "notionalUsd": "1000",981 "leverage": "2",982 "horizonHours": "24",983 "liquidity": "taker",984 "minNetEdgeBps": "0",985 "depthBps": [986 "10"987 ]988 },989 "rows": [990 {991 "venue": "hyperliquid",992 "venueName": "Hyperliquid",993 "instrument": "hyperliquid:BTC",994 "symbol": "BTC",995 "underlying": "BTC",996 "multiplier": "1",997 "alternatives": [],998 "tradable": true,999 "tradableReason": null,1000 "restriction": null,1001 "priceOutlier": false,1002 "staleAfterMs": 15000,1003 "price": {1004 "mark": "64432",1005 "index": "64460.7",1006 "mid": "64432.5"1007 },1008 "depth": [1009 {1010 "bps": "10",1011 "bidUsd": "6193729.75994",1012 "askUsd": "9895537.37818",1013 "bidComplete": false,1014 "askComplete": false1015 }1016 ],1017 "depthReason": null,1018 "fees": {1019 "takerRate": "0.00045",1020 "makerRate": "0.00015",1021 "source": "base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook.io/hyperliquid-docs/trading/fee…",1022 "asOf": "2026-11-10"1023 },1024 "funding": {1025 "rate": "0.0000089721",1026 "intervalSec": 3600,1027 "perHour": "0.0000089721",1028 "annualised": "0.0785956",1029 "assumption": "the venue's current rate held constant over the horizon; funding rates change every interval"1030 },1031 "maintenance": {1032 "fraction": "0.0125",1033 "basis": "1 / (2 × maximum leverage 40): half of the initial margin at the maximum leverage (1 / (2 × max leverage) of notional); tiered by position size — https://hyperliquid.gitbook.io/hyp…"1034 },1035 "cost": {1036 "venue": "hyperliquid",1037 "instrument": "hyperliquid:BTC",1038 "executionModel": "order_book",1039 "midPrice": {1040 "value": "64432.5",1041 "reason": null,1042 "basis": "(best bid + best ask) / 2"1043 },1044 "spreadBps": {1045 "value": "0.1552",1046 "reason": null,1047 "basis": "(best ask − best bid) / mid"1048 },1049 "depthBidUsd": {1050 "value": "6193729.75994",1051 "reason": null,1052 "basis": "Σ price × size of the bids within 10 bps of the mid, in the supplied book"1053 },1054 "depthAskUsd": {1055 "value": "9895537.37818",1056 "reason": null,1057 "basis": "Σ price × size of the asks within 10 bps of the mid, in the supplied book"1058 },1059 "sizeBase": {1060 "value": "0.01552",1061 "reason": null,1062 "basis": "notional / mid, rounded down to the lot"1063 },1064 "entryAvgPrice": {1065 "value": "64433",1066 "reason": null,1067 "basis": "average price of walking the book for the whole size"1068 },1069 "entrySlippageBps": {1070 "value": "0.0776",1071 "reason": null,1072 "basis": "|average entry price − mid| / mid"1073 },1074 "entrySlippageUsd": {1075 "value": "0.00776",1076 "reason": null,1077 "basis": "entry: average price of walking the book for the whole size vs the mid, half the spread included (router.walkBook)"1078 },1079 "exitSlippageUsd": {1080 "value": "0.00776",1081 "reason": null,1082 "basis": "exit, on the current book: average price of walking the book for the whole size vs the mid, half the spread included (router.walkBook)"1083 },1084 "entryFeeUsd": {1085 "value": "0.449997",1086 "reason": null,1087 "basis": "taker rate 0.00045 × notional — base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook…"1088 },1089 "exitFeeUsd": {1090 "value": "0.449997",1091 "reason": null,1092 "basis": "taker rate 0.00045 × notional — base tier of the perps fee schedule (taker 0.045 %, maker 0.015 %); 14-day volume tiers and staking discounts lower it — https://hyperliquid.gitbook…"1093 },1094 "fundingUsd": {1095 "value": "0.215329",1096 "reason": null,1097 "basis": "current rate 0.0000089721 per 3600 s (ticker.funding of the venue) held constant for 24 h on the position's notional; longs pay a positive rate"1098 },1099 "fundingRatePerHour": {1100 "value": "0.0000089721",1101 "reason": null,1102 "basis": "rate per 3600 s × 3600 / 3600"1103 },1104 "collateralRequiredUsd": {1105 "value": "499.9962",1106 "reason": null,1107 "basis": "notional / leverage, rounded up (margin.initialMargin)"1108 },1109 "liquidationPrice": {1110 "value": "32624.3037974684",1111 "reason": null,1112 "basis": "isolated, long: equity = maintenance at p; flat maintenance fraction, no fees; no funding accrual; margin = entry notional / leverage; entry at the estimated average entry price"1113 },1114 "liquidationDistanceBps": {1115 "value": "4936.7089",1116 "reason": null,1117 "basis": "|entry − liquidation price| / entry"1118 },1119 "maxLeverage": {1120 "value": "40",1121 "reason": null,1122 "basis": "the venue's maximum for the instrument"1123 },1124 "totalCostUsd": {1125 "value": "1.130843",1126 "reason": null,1127 "basis": "sum of entrySlippageUsd + exitSlippageUsd + entryFeeUsd + exitFeeUsd + fundingUsd"1128 },1129 "totalCostBps": {1130 "value": "11.3085",1131 "reason": null,1132 "basis": "total cost / position notional"1133 },1134 "missing": [],1135 "assumptions": [1136 "the position is opened and closed in full, each in one order"1137 ]1138 },1139 "sourceTs": {1140 "ticker": 1794953721101,1141 "book": 1794953722689,1142 "pool": null1143 },1144 "ageMs": 1936,1145 "stale": false,1146 "error": null1147 }1148 ],1149 "discrepancies": [1150 {1151 "longVenue": "edgex",1152 "shortVenue": "hyperliquid",1153 "longInstrument": "edgex:BTCUSDC",1154 "shortInstrument": "hyperliquid:BTC",1155 "grossGapBps": "8.6212",1156 "netEdgeEstimateBps": "-10.379",1157 "costsUsd": {1158 "feesUsd": "1.738914",1159 "exitSlippageUsd": "0.01425",1160 "fundingUsd": "0.081578"1161 },1162 "flagged": false,1163 "reason": null,1164 "actionableFromWallet": false,1165 "assumptions": [1166 {1167 "code": "disc_assume_1",1168 "text": "both legs are opened at the same time, in full, at the average prices of walking the two CURRENT books"1169 }1170 ],1171 "risks": [1172 {1173 "code": "disc_risk_1",1174 "text": "execution risk: one leg can fill and the other not, or at a worse price; the books move between the two orders"1175 }1176 ]1177 }1178 ],1179 "texts": {1180 "disclaimer": "Estimates computed from one snapshot of public market data. Not a quote and not a recommendation: the contracts differ between venues (collateral, price used for liquidation, funding rule, execution).",1181 "discrepancy": "netEdgeEstimateBps is the price difference between two venues net of fees on four legs, the exit slippage on both and the net funding over the horizon. It is an estimate under the …",1182 "assumptions": [1183 {1184 "code": "cost_1",1185 "text": "the position is opened and closed in full, each in one order"1186 }1187 ]1188 },1189 "warnings": [],1190 "errors": [],1191 "locks": [1192 {1193 "id": "deriv_live_mainnet",1194 "on": false1195 }1196 ],1197 "ts": 1794953723037,1198 "source": "estimate"1199 }1200 }1201 }1202 },1203 "400": {1204 "description": "The request is not valid: `bad_request`",1205 "content": {1206 "application/json": {1207 "schema": {1208 "$ref": "#/components/schemas/Error"1209 }1210 }1211 }1212 },1213 "401": {1214 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",1215 "content": {1216 "application/json": {1217 "schema": {1218 "$ref": "#/components/schemas/Error"1219 }1220 }1221 }1222 },1223 "403": {1224 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",1225 "content": {1226 "application/json": {1227 "schema": {1228 "$ref": "#/components/schemas/Error"1229 }1230 }1231 }1232 },1233 "404": {1234 "description": "The object named by the request does not exist: `unknown_underlying`",1235 "content": {1236 "application/json": {1237 "schema": {1238 "$ref": "#/components/schemas/Error"1239 }1240 }1241 }1242 },1243 "429": {1244 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",1245 "content": {1246 "application/json": {1247 "schema": {1248 "$ref": "#/components/schemas/Error"1249 }1250 }1251 }1252 },1253 "500": {1254 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",1255 "content": {1256 "application/json": {1257 "schema": {1258 "$ref": "#/components/schemas/Error"1259 }1260 }1261 }1262 },1263 "503": {1264 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",1265 "content": {1266 "application/json": {1267 "schema": {1268 "$ref": "#/components/schemas/Error"1269 }1270 }1271 }1272 }1273 }1274 }1275 },1276 "/api/v1/trading/markets/{symbol}": {1277 "get": {1278 "operationId": "getMarket",1279 "tags": [1280 "Markets"1281 ],1282 "summary": "One market: instrument, ticker and data quality",1283 "description": "`instrument` carries what an order must respect: `lotSize`, `tickSize`, `minOrderSize`, `minNotional`, `maxLeverage`. A bare symbol that exists on several venues answers 409 `ambiguous_symbol` with the candidates. 404: `unknown_venue` (the part before the colon), `unknown_instrument` (the venue does not list it), `unknown_market` (a spot symbol without data, or a bare symbol nothing answers to).",1284 "security": [1285 {1286 "bearerKey": [1287 "markets:read"1288 ]1289 }1290 ],1291 "x-spw-scope": "markets:read",1292 "x-spw-implemented": true,1293 "x-spw-errors": [1294 {1295 "status": 400,1296 "code": "bad_request"1297 },1298 {1299 "status": 401,1300 "code": "unauthenticated"1301 },1302 {1303 "status": 403,1304 "code": "insufficient_scope"1305 },1306 {1307 "status": 403,1308 "code": "ip_not_allowed"1309 },1310 {1311 "status": 403,1312 "code": "mixed_credentials"1313 },1314 {1315 "status": 403,1316 "code": "restricted"1317 },1318 {1319 "status": 404,1320 "code": "unknown_instrument"1321 },1322 {1323 "status": 404,1324 "code": "unknown_market"1325 },1326 {1327 "status": 404,1328 "code": "unknown_venue"1329 },1330 {1331 "status": 409,1332 "code": "ambiguous_symbol"1333 },1334 {1335 "status": 422,1336 "code": "venue_rejected"1337 },1338 {1339 "status": 429,1340 "code": "auth_throttled"1341 },1342 {1343 "status": 429,1344 "code": "rate_limited"1345 },1346 {1347 "status": 500,1348 "code": "internal"1349 },1350 {1351 "status": 503,1352 "code": "venue_rate_limited"1353 },1354 {1355 "status": 503,1356 "code": "venue_timeout"1357 },1358 {1359 "status": 503,1360 "code": "venue_unavailable"1361 }1362 ],1363 "x-spw-example-recorded": true,1364 "x-codeSamples": [1365 {1366 "lang": "Shell",1367 "label": "curl",1368 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""1369 },1370 {1371 "lang": "TypeScript",1372 "label": "TypeScript",1373 "source": "const { instrument, ticker } = await client.getMarket('hyperliquid:BTC');"1374 },1375 {1376 "lang": "Python",1377 "label": "Python",1378 "source": "market = client.get_market(\"hyperliquid:BTC\")"1379 }1380 ],1381 "parameters": [1382 {1383 "name": "symbol",1384 "in": "path",1385 "required": true,1386 "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous",1387 "schema": {1388 "type": "string",1389 "minLength": 1,1390 "maxLength": 1201391 },1392 "example": "hyperliquid:BTC"1393 }1394 ],1395 "responses": {1396 "200": {1397 "description": "OK (the example is a recorded answer)",1398 "content": {1399 "application/json": {1400 "schema": {1401 "type": "object",1402 "properties": {1403 "market": {1404 "type": "object",1405 "properties": {1406 "id": {1407 "type": "string"1408 },1409 "venue": {1410 "type": "string"1411 },1412 "kind": {1413 "type": "string",1414 "enum": [1415 "perpetual",1416 "spot"1417 ]1418 },1419 "symbol": {1420 "type": "string"1421 },1422 "base": {1423 "type": "string"1424 },1425 "quote": {1426 "type": "string"1427 },1428 "status": {1429 "type": "string"1430 },1431 "mark": {1432 "anyOf": [1433 {1434 "type": "string",1435 "description": "decimal number as a string (never a float)"1436 },1437 {1438 "type": "null"1439 }1440 ]1441 },1442 "ts": {1443 "anyOf": [1444 {1445 "type": "integer",1446 "minimum": -9007199254740991,1447 "maximum": 9007199254740991,1448 "description": "milliseconds since the Unix epoch"1449 },1450 {1451 "type": "null"1452 }1453 ],1454 "description": "time the source produced this row (venue read time, or the last consolidated bar for spot)"1455 },1456 "stale": {1457 "type": "boolean",1458 "description": "true when the row is older than its freshness bound or the source could not be refreshed"1459 }1460 },1461 "required": [1462 "id",1463 "venue",1464 "kind",1465 "symbol",1466 "base",1467 "quote",1468 "status",1469 "mark",1470 "ts",1471 "stale"1472 ],1473 "additionalProperties": {}1474 },1475 "instrument": {1476 "anyOf": [1477 {1478 "type": "object",1479 "properties": {1480 "id": {1481 "type": "string",1482 "description": "`venue:symbol`"1483 },1484 "venue": {1485 "type": "string"1486 },1487 "symbol": {1488 "type": "string"1489 },1490 "base": {1491 "type": "string"1492 },1493 "quote": {1494 "type": "string"1495 },1496 "kind": {1497 "type": "string",1498 "const": "perpetual"1499 },1500 "collateral": {1501 "type": "string"1502 },1503 "settlement": {1504 "type": "string"1505 },1506 "tickSize": {1507 "type": "string",1508 "description": "price increment: a limit or trigger price is a multiple of it"1509 },1510 "lotSize": {1511 "type": "string",1512 "description": "size increment: an order size is a multiple of it"1513 },1514 "minOrderSize": {1515 "anyOf": [1516 {1517 "type": "string",1518 "description": "decimal number as a string (never a float)"1519 },1520 {1521 "type": "null"1522 }1523 ],1524 "description": "smallest order size, base units; null when the venue states none"1525 },1526 "minNotional": {1527 "anyOf": [1528 {1529 "type": "string",1530 "description": "decimal number as a string (never a float)"1531 },1532 {1533 "type": "null"1534 }1535 ],1536 "description": "smallest order value, quote currency; null when the venue states none"1537 },1538 "maxLeverage": {1539 "type": "string",1540 "description": "decimal number as a string (never a float)"1541 },1542 "marginModes": {1543 "type": "array",1544 "items": {1545 "type": "string",1546 "enum": [1547 "cross",1548 "isolated"1549 ]1550 }1551 },1552 "fundingIntervalSec": {1553 "type": "integer",1554 "minimum": -9007199254740991,1555 "maximum": 90071992547409911556 },1557 "markPriceMethod": {1558 "type": "string"1559 },1560 "status": {1561 "type": "string",1562 "enum": [1563 "active",1564 "reduce_only",1565 "halted"1566 ]1567 },1568 "category": {1569 "description": "what the underlying is, when the venue's own metadata says it",1570 "type": "string",1571 "enum": [1572 "crypto",1573 "equity",1574 "pre_ipo",1575 "commodity",1576 "fx"1577 ]1578 }1579 },1580 "required": [1581 "id",1582 "venue",1583 "symbol",1584 "base",1585 "quote",1586 "kind",1587 "collateral",1588 "settlement",1589 "tickSize",1590 "lotSize",1591 "minOrderSize",1592 "minNotional",1593 "maxLeverage",1594 "marginModes",1595 "fundingIntervalSec",1596 "markPriceMethod",1597 "status"1598 ],1599 "additionalProperties": {}1600 },1601 {1602 "type": "null"1603 }1604 ],1605 "description": "null for a spot market-data symbol"1606 },1607 "ticker": {1608 "anyOf": [1609 {1610 "type": "object",1611 "properties": {1612 "instrument": {1613 "type": "string"1614 },1615 "mark": {1616 "type": "string",1617 "description": "decimal number as a string (never a float)"1618 },1619 "index": {1620 "anyOf": [1621 {1622 "type": "string",1623 "description": "decimal number as a string (never a float)"1624 },1625 {1626 "type": "null"1627 }1628 ]1629 },1630 "mid": {1631 "anyOf": [1632 {1633 "type": "string",1634 "description": "decimal number as a string (never a float)"1635 },1636 {1637 "type": "null"1638 }1639 ]1640 },1641 "funding": {1642 "anyOf": [1643 {1644 "type": "string",1645 "description": "decimal number as a string (never a float)"1646 },1647 {1648 "type": "null"1649 }1650 ],1651 "description": "per funding interval"1652 },1653 "openInterest": {1654 "anyOf": [1655 {1656 "type": "string",1657 "description": "decimal number as a string (never a float)"1658 },1659 {1660 "type": "null"1661 }1662 ]1663 },1664 "volume24h": {1665 "anyOf": [1666 {1667 "type": "string",1668 "description": "decimal number as a string (never a float)"1669 },1670 {1671 "type": "null"1672 }1673 ]1674 },1675 "change24h": {1676 "anyOf": [1677 {1678 "type": "string",1679 "description": "decimal number as a string (never a float)"1680 },1681 {1682 "type": "null"1683 }1684 ]1685 },1686 "ts": {1687 "type": "integer",1688 "minimum": -9007199254740991,1689 "maximum": 9007199254740991,1690 "description": "milliseconds since the Unix epoch"1691 }1692 },1693 "required": [1694 "instrument",1695 "mark",1696 "index",1697 "mid",1698 "funding",1699 "openInterest",1700 "volume24h",1701 "change24h",1702 "ts"1703 ],1704 "additionalProperties": {}1705 },1706 {1707 "type": "null"1708 }1709 ]1710 },1711 "quality": {1712 "anyOf": [1713 {1714 "type": "object",1715 "properties": {},1716 "additionalProperties": {}1717 },1718 {1719 "type": "null"1720 }1721 ],1722 "description": "spot only: data quality per interval"1723 },1724 "ts": {1725 "type": "integer",1726 "minimum": -9007199254740991,1727 "maximum": 9007199254740991,1728 "description": "milliseconds since the Unix epoch"1729 },1730 "source": {1731 "type": "string"1732 }1733 },1734 "required": [1735 "market",1736 "instrument",1737 "ticker",1738 "quality",1739 "ts",1740 "source"1741 ],1742 "additionalProperties": {}1743 },1744 "example": {1745 "market": {1746 "id": "hyperliquid:BTC",1747 "venue": "hyperliquid",1748 "kind": "perpetual",1749 "symbol": "BTC",1750 "base": "BTC",1751 "quote": "USD",1752 "status": "active",1753 "mark": "64419",1754 "ts": 1794953786018,1755 "stale": false,1756 "source": "venue"1757 },1758 "instrument": {1759 "venue": "hyperliquid",1760 "symbol": "BTC",1761 "id": "hyperliquid:BTC",1762 "base": "BTC",1763 "quote": "USD",1764 "kind": "perpetual",1765 "collateral": "USDC",1766 "settlement": "Linear perpetual margined and settled in USDC; the oracle is USDT-denominated for most assets (quanto: USDT PnL paid in USDC, no conversion); funding every hour, peer to peer",1767 "tickSize": "0.1",1768 "lotSize": "0.00001",1769 "minOrderSize": null,1770 "minNotional": "10",1771 "maxLeverage": "40",1772 "marginModes": [1773 "cross",1774 "isolated"1775 ],1776 "fundingIntervalSec": 3600,1777 "markPriceMethod": "Median of (1) oracle + 150 s EMA of (Hyperliquid mid − oracle), (2) median of best bid, best ask, last trade, (3) weighted median of Binance, OKX, Bybit, Gate IO, MEXC perp mids; u…",1778 "status": "active"1779 },1780 "ticker": {1781 "instrument": "hyperliquid:BTC",1782 "mark": "64419",1783 "index": "64449.4",1784 "mid": "64418.5",1785 "funding": "0.0000087881",1786 "openInterest": "37684.5631",1787 "volume24h": "3622010181.9303812981",1788 "change24h": "-0.015692",1789 "ts": 1794953786018,1790 "source": "venue"1791 },1792 "quality": null,1793 "liquidity": null,1794 "hasOrderBook": true,1795 "errors": {},1796 "ts": 1794953786422,1797 "source": "venue"1798 }1799 }1800 }1801 },1802 "400": {1803 "description": "The request is not valid: `bad_request`",1804 "content": {1805 "application/json": {1806 "schema": {1807 "$ref": "#/components/schemas/Error"1808 }1809 }1810 }1811 },1812 "401": {1813 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",1814 "content": {1815 "application/json": {1816 "schema": {1817 "$ref": "#/components/schemas/Error"1818 }1819 }1820 }1821 },1822 "403": {1823 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",1824 "content": {1825 "application/json": {1826 "schema": {1827 "$ref": "#/components/schemas/Error"1828 }1829 }1830 }1831 },1832 "404": {1833 "description": "The object named by the request does not exist: `unknown_instrument`, `unknown_market`, `unknown_venue`",1834 "content": {1835 "application/json": {1836 "schema": {1837 "$ref": "#/components/schemas/Error"1838 }1839 }1840 }1841 },1842 "409": {1843 "description": "The request conflicts with the state of the object, or needs a choice: `ambiguous_symbol`",1844 "content": {1845 "application/json": {1846 "schema": {1847 "$ref": "#/components/schemas/Error"1848 }1849 }1850 }1851 },1852 "422": {1853 "description": "A valid request that cannot be carried out: `venue_rejected`",1854 "content": {1855 "application/json": {1856 "schema": {1857 "$ref": "#/components/schemas/Error"1858 }1859 }1860 }1861 },1862 "429": {1863 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",1864 "content": {1865 "application/json": {1866 "schema": {1867 "$ref": "#/components/schemas/Error"1868 }1869 }1870 }1871 },1872 "500": {1873 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",1874 "content": {1875 "application/json": {1876 "schema": {1877 "$ref": "#/components/schemas/Error"1878 }1879 }1880 }1881 },1882 "503": {1883 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",1884 "content": {1885 "application/json": {1886 "schema": {1887 "$ref": "#/components/schemas/Error"1888 }1889 }1890 }1891 }1892 }1893 }1894 },1895 "/api/v1/trading/markets/{symbol}/orderbook": {1896 "get": {1897 "operationId": "getOrderbook",1898 "tags": [1899 "Markets"1900 ],1901 "summary": "Order book of one market",1902 "description": "Venues without an order book (GMX, spot data) answer 422 `no_orderbook`.",1903 "security": [1904 {1905 "bearerKey": [1906 "markets:read"1907 ]1908 }1909 ],1910 "x-spw-scope": "markets:read",1911 "x-spw-implemented": true,1912 "x-spw-errors": [1913 {1914 "status": 400,1915 "code": "bad_request"1916 },1917 {1918 "status": 401,1919 "code": "unauthenticated"1920 },1921 {1922 "status": 403,1923 "code": "insufficient_scope"1924 },1925 {1926 "status": 403,1927 "code": "ip_not_allowed"1928 },1929 {1930 "status": 403,1931 "code": "mixed_credentials"1932 },1933 {1934 "status": 403,1935 "code": "restricted"1936 },1937 {1938 "status": 404,1939 "code": "unknown_instrument"1940 },1941 {1942 "status": 404,1943 "code": "unknown_market"1944 },1945 {1946 "status": 404,1947 "code": "unknown_venue"1948 },1949 {1950 "status": 409,1951 "code": "ambiguous_symbol"1952 },1953 {1954 "status": 422,1955 "code": "no_orderbook"1956 },1957 {1958 "status": 422,1959 "code": "venue_rejected"1960 },1961 {1962 "status": 429,1963 "code": "auth_throttled"1964 },1965 {1966 "status": 429,1967 "code": "rate_limited"1968 },1969 {1970 "status": 500,1971 "code": "internal"1972 },1973 {1974 "status": 503,1975 "code": "stale_data"1976 },1977 {1978 "status": 503,1979 "code": "venue_rate_limited"1980 },1981 {1982 "status": 503,1983 "code": "venue_timeout"1984 },1985 {1986 "status": 503,1987 "code": "venue_unavailable"1988 }1989 ],1990 "x-spw-example-recorded": true,1991 "x-codeSamples": [1992 {1993 "lang": "Shell",1994 "label": "curl",1995 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/orderbook?depth=3\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""1996 },1997 {1998 "lang": "TypeScript",1999 "label": "TypeScript",2000 "source": "const book = await client.getOrderbook('hyperliquid:BTC', { depth: 3 });"2001 },2002 {2003 "lang": "Python",2004 "label": "Python",2005 "source": "book = client.get_orderbook(\"hyperliquid:BTC\", depth=3)"2006 }2007 ],2008 "parameters": [2009 {2010 "name": "symbol",2011 "in": "path",2012 "required": true,2013 "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous",2014 "schema": {2015 "type": "string",2016 "minLength": 1,2017 "maxLength": 1202018 },2019 "example": "hyperliquid:BTC"2020 },2021 {2022 "name": "depth",2023 "in": "query",2024 "required": false,2025 "description": "price levels per side",2026 "schema": {2027 "default": 20,2028 "type": "integer",2029 "minimum": 1,2030 "maximum": 502031 },2032 "example": 32033 }2034 ],2035 "responses": {2036 "200": {2037 "description": "OK (the example is a recorded answer)",2038 "content": {2039 "application/json": {2040 "schema": {2041 "type": "object",2042 "properties": {2043 "id": {2044 "type": "string"2045 },2046 "bids": {2047 "type": "array",2048 "items": {2049 "type": "array",2050 "prefixItems": [2051 {2052 "type": "string",2053 "description": "decimal number as a string (never a float)"2054 },2055 {2056 "type": "string",2057 "description": "decimal number as a string (never a float)"2058 }2059 ],2060 "items": false,2061 "minItems": 2,2062 "maxItems": 2,2063 "description": "[price, size]"2064 }2065 },2066 "asks": {2067 "type": "array",2068 "items": {2069 "type": "array",2070 "prefixItems": [2071 {2072 "type": "string",2073 "description": "decimal number as a string (never a float)"2074 },2075 {2076 "type": "string",2077 "description": "decimal number as a string (never a float)"2078 }2079 ],2080 "items": false,2081 "minItems": 2,2082 "maxItems": 2,2083 "description": "[price, size]"2084 }2085 },2086 "ts": {2087 "type": "integer",2088 "minimum": -9007199254740991,2089 "maximum": 9007199254740991,2090 "description": "milliseconds since the Unix epoch"2091 },2092 "stale": {2093 "type": "boolean"2094 },2095 "source": {2096 "type": "string"2097 }2098 },2099 "required": [2100 "id",2101 "bids",2102 "asks",2103 "ts",2104 "stale",2105 "source"2106 ],2107 "additionalProperties": false2108 },2109 "example": {2110 "id": "hyperliquid:BTC",2111 "bids": [2112 [2113 "64432",2114 "0.43796"2115 ],2116 [2117 "64431",2118 "0.00036"2119 ],2120 [2121 "64426",2122 "0.0015"2123 ]2124 ],2125 "asks": [2126 [2127 "64433",2128 "27.19556"2129 ],2130 [2131 "64434",2132 "2.14586"2133 ],2134 [2135 "64435",2136 "10.15654"2137 ]2138 ],2139 "ts": 1794953722689,2140 "stale": false,2141 "source": "venue"2142 }2143 }2144 }2145 },2146 "400": {2147 "description": "The request is not valid: `bad_request`",2148 "content": {2149 "application/json": {2150 "schema": {2151 "$ref": "#/components/schemas/Error"2152 }2153 }2154 }2155 },2156 "401": {2157 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",2158 "content": {2159 "application/json": {2160 "schema": {2161 "$ref": "#/components/schemas/Error"2162 }2163 }2164 }2165 },2166 "403": {2167 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",2168 "content": {2169 "application/json": {2170 "schema": {2171 "$ref": "#/components/schemas/Error"2172 }2173 }2174 }2175 },2176 "404": {2177 "description": "The object named by the request does not exist: `unknown_instrument`, `unknown_market`, `unknown_venue`",2178 "content": {2179 "application/json": {2180 "schema": {2181 "$ref": "#/components/schemas/Error"2182 }2183 }2184 }2185 },2186 "409": {2187 "description": "The request conflicts with the state of the object, or needs a choice: `ambiguous_symbol`",2188 "content": {2189 "application/json": {2190 "schema": {2191 "$ref": "#/components/schemas/Error"2192 }2193 }2194 }2195 },2196 "422": {2197 "description": "A valid request that cannot be carried out: `no_orderbook`, `venue_rejected`",2198 "content": {2199 "application/json": {2200 "schema": {2201 "$ref": "#/components/schemas/Error"2202 }2203 }2204 }2205 },2206 "429": {2207 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",2208 "content": {2209 "application/json": {2210 "schema": {2211 "$ref": "#/components/schemas/Error"2212 }2213 }2214 }2215 },2216 "500": {2217 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",2218 "content": {2219 "application/json": {2220 "schema": {2221 "$ref": "#/components/schemas/Error"2222 }2223 }2224 }2225 },2226 "503": {2227 "description": "A backing service is unavailable; nothing was done: `stale_data`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",2228 "content": {2229 "application/json": {2230 "schema": {2231 "$ref": "#/components/schemas/Error"2232 }2233 }2234 }2235 }2236 }2237 }2238 },2239 "/api/v1/trading/markets/{symbol}/candles": {2240 "get": {2241 "operationId": "getCandles",2242 "tags": [2243 "Markets"2244 ],2245 "summary": "Closed bars of one market",2246 "description": "Spot market data has fewer intervals than the venues: an interval it does not store answers 422 `unsupported_interval`.",2247 "security": [2248 {2249 "bearerKey": [2250 "markets:read"2251 ]2252 }2253 ],2254 "x-spw-scope": "markets:read",2255 "x-spw-implemented": true,2256 "x-spw-errors": [2257 {2258 "status": 400,2259 "code": "bad_request"2260 },2261 {2262 "status": 401,2263 "code": "unauthenticated"2264 },2265 {2266 "status": 403,2267 "code": "insufficient_scope"2268 },2269 {2270 "status": 403,2271 "code": "ip_not_allowed"2272 },2273 {2274 "status": 403,2275 "code": "mixed_credentials"2276 },2277 {2278 "status": 403,2279 "code": "restricted"2280 },2281 {2282 "status": 404,2283 "code": "unknown_instrument"2284 },2285 {2286 "status": 404,2287 "code": "unknown_market"2288 },2289 {2290 "status": 404,2291 "code": "unknown_venue"2292 },2293 {2294 "status": 409,2295 "code": "ambiguous_symbol"2296 },2297 {2298 "status": 422,2299 "code": "unsupported_interval"2300 },2301 {2302 "status": 422,2303 "code": "venue_rejected"2304 },2305 {2306 "status": 429,2307 "code": "auth_throttled"2308 },2309 {2310 "status": 429,2311 "code": "rate_limited"2312 },2313 {2314 "status": 500,2315 "code": "internal"2316 },2317 {2318 "status": 503,2319 "code": "venue_rate_limited"2320 },2321 {2322 "status": 503,2323 "code": "venue_timeout"2324 },2325 {2326 "status": 503,2327 "code": "venue_unavailable"2328 }2329 ],2330 "x-spw-example-recorded": true,2331 "x-codeSamples": [2332 {2333 "lang": "Shell",2334 "label": "curl",2335 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/markets/hyperliquid:BTC/candles?interval=1h&limit=3\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""2336 },2337 {2338 "lang": "TypeScript",2339 "label": "TypeScript",2340 "source": "const { candles } = await client.getCandles('hyperliquid:BTC', { interval: '1h', limit: 3 });"2341 },2342 {2343 "lang": "Python",2344 "label": "Python",2345 "source": "candles = client.get_candles(\"hyperliquid:BTC\", interval=\"1h\", limit=3).candles"2346 }2347 ],2348 "parameters": [2349 {2350 "name": "symbol",2351 "in": "path",2352 "required": true,2353 "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous",2354 "schema": {2355 "type": "string",2356 "minLength": 1,2357 "maxLength": 1202358 },2359 "example": "hyperliquid:BTC"2360 },2361 {2362 "name": "interval",2363 "in": "query",2364 "required": false,2365 "description": "bar length",2366 "schema": {2367 "default": "1h",2368 "type": "string",2369 "enum": [2370 "1m",2371 "5m",2372 "15m",2373 "1h",2374 "4h",2375 "1d"2376 ]2377 },2378 "example": "1h"2379 },2380 {2381 "name": "limit",2382 "in": "query",2383 "required": false,2384 "description": "most recent closed bars, oldest first in the answer",2385 "schema": {2386 "default": 200,2387 "type": "integer",2388 "minimum": 1,2389 "maximum": 10002390 },2391 "example": 32392 }2393 ],2394 "responses": {2395 "200": {2396 "description": "OK (the example is a recorded answer)",2397 "content": {2398 "application/json": {2399 "schema": {2400 "type": "object",2401 "properties": {2402 "id": {2403 "type": "string"2404 },2405 "interval": {2406 "type": "string"2407 },2408 "candles": {2409 "type": "array",2410 "items": {2411 "type": "object",2412 "properties": {2413 "ts": {2414 "type": "integer",2415 "minimum": -9007199254740991,2416 "maximum": 9007199254740991,2417 "description": "milliseconds since the Unix epoch"2418 },2419 "open": {2420 "type": "string",2421 "description": "decimal number as a string (never a float)"2422 },2423 "high": {2424 "type": "string",2425 "description": "decimal number as a string (never a float)"2426 },2427 "low": {2428 "type": "string",2429 "description": "decimal number as a string (never a float)"2430 },2431 "close": {2432 "type": "string",2433 "description": "decimal number as a string (never a float)"2434 },2435 "volume": {2436 "type": "string",2437 "description": "decimal number as a string (never a float)"2438 }2439 },2440 "required": [2441 "ts",2442 "open",2443 "high",2444 "low",2445 "close",2446 "volume"2447 ],2448 "additionalProperties": {}2449 }2450 },2451 "ts": {2452 "anyOf": [2453 {2454 "type": "integer",2455 "minimum": -9007199254740991,2456 "maximum": 9007199254740991,2457 "description": "milliseconds since the Unix epoch"2458 },2459 {2460 "type": "null"2461 }2462 ]2463 },2464 "stale": {2465 "type": "boolean"2466 },2467 "source": {2468 "type": "string"2469 }2470 },2471 "required": [2472 "id",2473 "interval",2474 "candles",2475 "ts",2476 "stale",2477 "source"2478 ],2479 "additionalProperties": {}2480 },2481 "example": {2482 "id": "hyperliquid:BTC",2483 "interval": "1h",2484 "candles": [2485 {2486 "ts": 1794945600000,2487 "open": "63727",2488 "high": "64075",2489 "low": "63666",2490 "close": "63964",2491 "volume": "1914.97454"2492 },2493 {2494 "ts": 1794949200000,2495 "open": "63964",2496 "high": "64645",2497 "low": "63925",2498 "close": "64331",2499 "volume": "3580.64025"2500 }2501 ],2502 "ts": 1794953723670,2503 "stale": false,2504 "source": "venue"2505 }2506 }2507 }2508 },2509 "400": {2510 "description": "The request is not valid: `bad_request`",2511 "content": {2512 "application/json": {2513 "schema": {2514 "$ref": "#/components/schemas/Error"2515 }2516 }2517 }2518 },2519 "401": {2520 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",2521 "content": {2522 "application/json": {2523 "schema": {2524 "$ref": "#/components/schemas/Error"2525 }2526 }2527 }2528 },2529 "403": {2530 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",2531 "content": {2532 "application/json": {2533 "schema": {2534 "$ref": "#/components/schemas/Error"2535 }2536 }2537 }2538 },2539 "404": {2540 "description": "The object named by the request does not exist: `unknown_instrument`, `unknown_market`, `unknown_venue`",2541 "content": {2542 "application/json": {2543 "schema": {2544 "$ref": "#/components/schemas/Error"2545 }2546 }2547 }2548 },2549 "409": {2550 "description": "The request conflicts with the state of the object, or needs a choice: `ambiguous_symbol`",2551 "content": {2552 "application/json": {2553 "schema": {2554 "$ref": "#/components/schemas/Error"2555 }2556 }2557 }2558 },2559 "422": {2560 "description": "A valid request that cannot be carried out: `unsupported_interval`, `venue_rejected`",2561 "content": {2562 "application/json": {2563 "schema": {2564 "$ref": "#/components/schemas/Error"2565 }2566 }2567 }2568 },2569 "429": {2570 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",2571 "content": {2572 "application/json": {2573 "schema": {2574 "$ref": "#/components/schemas/Error"2575 }2576 }2577 }2578 },2579 "500": {2580 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",2581 "content": {2582 "application/json": {2583 "schema": {2584 "$ref": "#/components/schemas/Error"2585 }2586 }2587 }2588 },2589 "503": {2590 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",2591 "content": {2592 "application/json": {2593 "schema": {2594 "$ref": "#/components/schemas/Error"2595 }2596 }2597 }2598 }2599 }2600 }2601 },2602 "/api/v1/trading/private-markets": {2603 "get": {2604 "operationId": "listPrivateMarkets",2605 "tags": [2606 "Markets"2607 ],2608 "summary": "Synthetic contracts on private companies, venue by venue, with sourced valuations",2609 "description": "Live discovery (Hyperliquid builder dexes categorised `preipo`, edgeX `pre_ipo`) joined with a reviewed contract table. Five quantities are separate fields: synthetic price, contract market value, notional exposure, implied valuation estimate (or null + reason), last known private valuation. A venue that cannot be read gives rows with `error`; the others answer. Venues are never averaged.",2610 "security": [2611 {2612 "bearerKey": [2613 "markets:read"2614 ]2615 }2616 ],2617 "x-spw-scope": "markets:read",2618 "x-spw-implemented": true,2619 "x-spw-errors": [2620 {2621 "status": 400,2622 "code": "bad_request"2623 },2624 {2625 "status": 401,2626 "code": "unauthenticated"2627 },2628 {2629 "status": 403,2630 "code": "insufficient_scope"2631 },2632 {2633 "status": 403,2634 "code": "ip_not_allowed"2635 },2636 {2637 "status": 403,2638 "code": "mixed_credentials"2639 },2640 {2641 "status": 429,2642 "code": "auth_throttled"2643 },2644 {2645 "status": 429,2646 "code": "rate_limited"2647 },2648 {2649 "status": 500,2650 "code": "internal"2651 },2652 {2653 "status": 503,2654 "code": "venue_rate_limited"2655 },2656 {2657 "status": 503,2658 "code": "venue_timeout"2659 },2660 {2661 "status": 503,2662 "code": "venue_unavailable"2663 }2664 ],2665 "x-spw-example-recorded": true,2666 "x-spw-example-note": "Cut to one market. Display only: `tradable` is always false.",2667 "x-codeSamples": [2668 {2669 "lang": "Shell",2670 "label": "curl",2671 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/private-markets\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""2672 },2673 {2674 "lang": "TypeScript",2675 "label": "TypeScript",2676 "source": "const { markets, companies } = await client.listPrivateMarkets();"2677 },2678 {2679 "lang": "Python",2680 "label": "Python",2681 "source": "private = client.list_private_markets()"2682 }2683 ],2684 "parameters": [2685 {2686 "name": "delisted",2687 "in": "query",2688 "required": false,2689 "description": "true: only delisted markets (frozen prices)",2690 "schema": {2691 "type": "string",2692 "enum": [2693 "true",2694 "false"2695 ]2696 }2697 },2698 {2699 "name": "size",2700 "in": "query",2701 "required": false,2702 "description": "hypothetical position size, contracts (default 1)",2703 "schema": {2704 "type": "string",2705 "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"2706 }2707 },2708 {2709 "name": "side",2710 "in": "query",2711 "required": false,2712 "description": "side of the hypothetical position (default long)",2713 "schema": {2714 "type": "string",2715 "enum": [2716 "long",2717 "short"2718 ]2719 }2720 }2721 ],2722 "responses": {2723 "200": {2724 "description": "OK (the example is a recorded answer)",2725 "content": {2726 "application/json": {2727 "schema": {2728 "type": "object",2729 "properties": {2730 "markets": {2731 "type": "array",2732 "items": {2733 "type": "object",2734 "properties": {2735 "id": {2736 "type": "string"2737 },2738 "venue": {2739 "type": "string"2740 },2741 "platform": {2742 "type": "string"2743 },2744 "symbol": {2745 "type": "string"2746 },2747 "company": {2748 "anyOf": [2749 {2750 "type": "object",2751 "properties": {2752 "slug": {2753 "type": "string"2754 },2755 "name": {2756 "type": "string"2757 }2758 },2759 "required": [2760 "slug",2761 "name"2762 ],2763 "additionalProperties": false2764 },2765 {2766 "type": "null"2767 }2768 ]2769 },2770 "status": {2771 "type": "string",2772 "enum": [2773 "live",2774 "delisted",2775 "halted",2776 "reduce_only"2777 ]2778 },2779 "review": {2780 "type": "object",2781 "properties": {2782 "state": {2783 "type": "string",2784 "enum": [2785 "reviewed",2786 "under_review",2787 "not_reviewed"2788 ]2789 },2790 "reasons": {2791 "type": "array",2792 "items": {2793 "type": "string"2794 }2795 }2796 },2797 "required": [2798 "state",2799 "reasons"2800 ],2801 "additionalProperties": {}2802 },2803 "contract": {2804 "type": "object",2805 "properties": {2806 "nature": {2807 "type": "string"2808 },2809 "unit": {2810 "type": "object",2811 "properties": {2812 "kind": {2813 "type": "string",2814 "enum": [2815 "usd_per_share",2816 "valuation_usd_billions",2817 "unknown"2818 ]2819 },2820 "label": {2821 "type": "string"2822 }2823 },2824 "required": [2825 "kind",2826 "label"2827 ],2828 "additionalProperties": false2829 },2830 "quoteCurrency": {2831 "type": "string"2832 },2833 "settlement": {2834 "type": "string"2835 },2836 "oracle": {2837 "type": "string"2838 },2839 "liquidation": {2840 "type": "string"2841 }2842 },2843 "required": [2844 "nature",2845 "unit",2846 "quoteCurrency",2847 "settlement",2848 "oracle",2849 "liquidation"2850 ],2851 "additionalProperties": {}2852 },2853 "market": {2854 "type": "object",2855 "properties": {2856 "price": {2857 "type": "object",2858 "properties": {2859 "value": {2860 "anyOf": [2861 {2862 "type": "string",2863 "description": "decimal number as a string (never a float)"2864 },2865 {2866 "type": "null"2867 }2868 ]2869 },2870 "source": {2871 "type": "string"2872 },2873 "ts": {2874 "anyOf": [2875 {2876 "type": "integer",2877 "minimum": -9007199254740991,2878 "maximum": 9007199254740991,2879 "description": "milliseconds since the Unix epoch"2880 },2881 {2882 "type": "null"2883 }2884 ]2885 },2886 "stale": {2887 "type": "boolean"2888 }2889 },2890 "required": [2891 "value",2892 "source",2893 "ts",2894 "stale"2895 ],2896 "additionalProperties": false,2897 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"2898 },2899 "funding": {2900 "type": "object",2901 "properties": {2902 "value": {2903 "anyOf": [2904 {2905 "type": "string",2906 "description": "decimal number as a string (never a float)"2907 },2908 {2909 "type": "null"2910 }2911 ]2912 },2913 "source": {2914 "type": "string"2915 },2916 "ts": {2917 "anyOf": [2918 {2919 "type": "integer",2920 "minimum": -9007199254740991,2921 "maximum": 9007199254740991,2922 "description": "milliseconds since the Unix epoch"2923 },2924 {2925 "type": "null"2926 }2927 ]2928 },2929 "stale": {2930 "type": "boolean"2931 },2932 "intervalSec": {2933 "anyOf": [2934 {2935 "type": "integer",2936 "minimum": -9007199254740991,2937 "maximum": 90071992547409912938 },2939 {2940 "type": "null"2941 }2942 ]2943 }2944 },2945 "required": [2946 "value",2947 "source",2948 "ts",2949 "stale",2950 "intervalSec"2951 ],2952 "additionalProperties": false2953 },2954 "openInterest": {2955 "type": "object",2956 "properties": {2957 "value": {2958 "anyOf": [2959 {2960 "type": "string",2961 "description": "decimal number as a string (never a float)"2962 },2963 {2964 "type": "null"2965 }2966 ]2967 },2968 "source": {2969 "type": "string"2970 },2971 "ts": {2972 "anyOf": [2973 {2974 "type": "integer",2975 "minimum": -9007199254740991,2976 "maximum": 9007199254740991,2977 "description": "milliseconds since the Unix epoch"2978 },2979 {2980 "type": "null"2981 }2982 ]2983 },2984 "stale": {2985 "type": "boolean"2986 }2987 },2988 "required": [2989 "value",2990 "source",2991 "ts",2992 "stale"2993 ],2994 "additionalProperties": false,2995 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"2996 },2997 "volume24h": {2998 "type": "object",2999 "properties": {3000 "value": {3001 "anyOf": [3002 {3003 "type": "string",3004 "description": "decimal number as a string (never a float)"3005 },3006 {3007 "type": "null"3008 }3009 ]3010 },3011 "source": {3012 "type": "string"3013 },3014 "ts": {3015 "anyOf": [3016 {3017 "type": "integer",3018 "minimum": -9007199254740991,3019 "maximum": 9007199254740991,3020 "description": "milliseconds since the Unix epoch"3021 },3022 {3023 "type": "null"3024 }3025 ]3026 },3027 "stale": {3028 "type": "boolean"3029 }3030 },3031 "required": [3032 "value",3033 "source",3034 "ts",3035 "stale"3036 ],3037 "additionalProperties": false,3038 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"3039 }3040 },3041 "required": [3042 "price",3043 "funding",3044 "openInterest",3045 "volume24h"3046 ],3047 "additionalProperties": {}3048 },3049 "valuation": {3050 "type": "object",3051 "properties": {3052 "syntheticPrice": {3053 "type": "object",3054 "properties": {3055 "value": {3056 "anyOf": [3057 {3058 "type": "string",3059 "description": "decimal number as a string (never a float)"3060 },3061 {3062 "type": "null"3063 }3064 ]3065 }3066 },3067 "required": [3068 "value"3069 ],3070 "additionalProperties": {}3071 },3072 "contractMarketValue": {3073 "type": "object",3074 "properties": {3075 "value": {3076 "anyOf": [3077 {3078 "type": "string",3079 "description": "decimal number as a string (never a float)"3080 },3081 {3082 "type": "null"3083 }3084 ]3085 },3086 "reason": {3087 "type": [3088 "string",3089 "null"3090 ]3091 }3092 },3093 "required": [3094 "value",3095 "reason"3096 ],3097 "additionalProperties": {}3098 },3099 "notionalExposure": {3100 "type": "object",3101 "properties": {3102 "value": {3103 "anyOf": [3104 {3105 "type": "string",3106 "description": "decimal number as a string (never a float)"3107 },3108 {3109 "type": "null"3110 }3111 ]3112 },3113 "hypothetical": {3114 "type": "boolean",3115 "const": true3116 }3117 },3118 "required": [3119 "value",3120 "hypothetical"3121 ],3122 "additionalProperties": {}3123 },3124 "impliedValuation": {3125 "type": "object",3126 "properties": {3127 "value": {3128 "anyOf": [3129 {3130 "type": "string",3131 "description": "decimal number as a string (never a float)"3132 },3133 {3134 "type": "null"3135 }3136 ]3137 },3138 "formula": {3139 "type": [3140 "string",3141 "null"3142 ]3143 },3144 "reason": {3145 "type": [3146 "string",3147 "null"3148 ]3149 },3150 "reasonCode": {3151 "type": [3152 "string",3153 "null"3154 ]3155 }3156 },3157 "required": [3158 "value",3159 "formula",3160 "reason",3161 "reasonCode"3162 ],3163 "additionalProperties": {},3164 "description": "null + reason unless the reviewed definition gives the formula"3165 },3166 "lastPrivateValuation": {3167 "anyOf": [3168 {3169 "type": "object",3170 "properties": {3171 "value": {3172 "type": "string",3173 "description": "decimal number as a string (never a float)"3174 },3175 "kind": {3176 "type": "string"3177 },3178 "date": {3179 "type": "string"3180 },3181 "sourceUrl": {3182 "type": "string"3183 }3184 },3185 "required": [3186 "value",3187 "kind",3188 "date",3189 "sourceUrl"3190 ],3191 "additionalProperties": {}3192 },3193 {3194 "type": "null"3195 }3196 ]3197 },3198 "premiumDiscount": {3199 "type": "object",3200 "properties": {3201 "premiumBps": {3202 "anyOf": [3203 {3204 "type": "string",3205 "description": "decimal number as a string (never a float)"3206 },3207 {3208 "type": "null"3209 }3210 ]3211 }3212 },3213 "required": [3214 "premiumBps"3215 ],3216 "additionalProperties": {}3217 },3218 "caveats": {3219 "type": "array",3220 "items": {3221 "type": "object",3222 "properties": {3223 "code": {3224 "type": "string"3225 },3226 "text": {3227 "type": "string"3228 }3229 },3230 "required": [3231 "code",3232 "text"3233 ],3234 "additionalProperties": {}3235 }3236 }3237 },3238 "required": [3239 "syntheticPrice",3240 "contractMarketValue",3241 "notionalExposure",3242 "impliedValuation",3243 "lastPrivateValuation",3244 "premiumDiscount",3245 "caveats"3246 ],3247 "additionalProperties": {}3248 },3249 "tradable": {3250 "type": "boolean",3251 "const": false3252 },3253 "notTradable": {3254 "type": "object",3255 "properties": {3256 "code": {3257 "type": "string"3258 },3259 "reasons": {3260 "type": "array",3261 "items": {3262 "type": "string"3263 }3264 }3265 },3266 "required": [3267 "code",3268 "reasons"3269 ],3270 "additionalProperties": false3271 },3272 "error": {3273 "type": [3274 "string",3275 "null"3276 ]3277 }3278 },3279 "required": [3280 "id",3281 "venue",3282 "platform",3283 "symbol",3284 "company",3285 "status",3286 "review",3287 "contract",3288 "market",3289 "valuation",3290 "tradable",3291 "notTradable",3292 "error"3293 ],3294 "additionalProperties": {}3295 }3296 },3297 "companies": {3298 "type": "array",3299 "items": {3300 "type": "object",3301 "properties": {3302 "slug": {3303 "type": "string"3304 },3305 "name": {3306 "type": "string"3307 },3308 "contracts": {3309 "type": "array",3310 "items": {3311 "type": "string"3312 }3313 }3314 },3315 "required": [3316 "slug",3317 "name",3318 "contracts"3319 ],3320 "additionalProperties": {}3321 }3322 },3323 "excluded": {3324 "type": "array",3325 "items": {3326 "type": "object",3327 "properties": {3328 "id": {3329 "type": "string"3330 },3331 "reason": {3332 "type": "string"3333 }3334 },3335 "required": [3336 "id",3337 "reason"3338 ],3339 "additionalProperties": {}3340 }3341 },3342 "venues": {3343 "type": "array",3344 "items": {3345 "type": "object",3346 "properties": {3347 "venue": {3348 "type": "string"3349 },3350 "status": {3351 "type": "string",3352 "enum": [3353 "ok",3354 "stale",3355 "error"3356 ]3357 },3358 "error": {3359 "type": [3360 "string",3361 "null"3362 ]3363 }3364 },3365 "required": [3366 "venue",3367 "status",3368 "error"3369 ],3370 "additionalProperties": {}3371 }3372 },3373 "notice": {3374 "type": "object",3375 "properties": {3376 "tradable": {3377 "type": "boolean",3378 "const": false3379 },3380 "code": {3381 "type": "string"3382 },3383 "text": {3384 "type": "string"3385 }3386 },3387 "required": [3388 "tradable",3389 "code",3390 "text"3391 ],3392 "additionalProperties": false3393 },3394 "ts": {3395 "type": "integer",3396 "minimum": -9007199254740991,3397 "maximum": 9007199254740991,3398 "description": "milliseconds since the Unix epoch"3399 }3400 },3401 "required": [3402 "markets",3403 "companies",3404 "excluded",3405 "venues",3406 "notice",3407 "ts"3408 ],3409 "additionalProperties": {}3410 },3411 "example": {3412 "markets": [3413 {3414 "id": "hyperliquid:io:ANTH",3415 "venue": "hyperliquid",3416 "platform": "Hyperliquid · EntropyIO (dex io)",3417 "operator": "EntropyIO",3418 "symbol": "io:ANTH",3419 "company": {3420 "slug": "anthropic",3421 "name": "Anthropic, PBC"3422 },3423 "status": "live",3424 "review": {3425 "state": "reviewed",3426 "reasons": [],3427 "reviewedAt": "2026-11-15",3428 "validUntil": "2026-11-18T00:00:00Z",3429 "fingerprintChecked": true3430 },3431 "contract": {3432 "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",3433 "unit": {3434 "kind": "valuation_usd_billions",3435 "label": "USD billions of fully diluted company valuation (1.00 = $1B)"3436 },3437 "quoteCurrency": "USD",3438 "collateral": "USDC",3439 "underlying": "Anthropic, PBC",3440 "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",3441 "multiplier": {3442 "value": "1",3443 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"3444 },3445 "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",3446 "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",3447 "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",3448 "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",3449 "maxLeverage": "15",3450 "margin": "cross_allowed",3451 "lotSize": "0.001",3452 "szDecimals": 3,3453 "fundingIntervalSec": 3600,3454 "assetId": 200001,3455 "dex": "io",3456 "oiCapUsd": "275000000",3457 "fundingMultiplier": "0.125",3458 "onChainDescription": "",3459 "unconfirmedConvention": null,3460 "sources": [3461 "https://docs.entropy.io/market-types/pre-ipo-perpetuals"3462 ]3463 },3464 "market": {3465 "price": {3466 "value": "1683.9",3467 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",3468 "ts": 1794953724740,3469 "stale": false3470 },3471 "oracle": {3472 "value": "1684",3473 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",3474 "ts": 1794953724740,3475 "stale": false3476 },3477 "mid": {3478 "value": "1680.6",3479 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",3480 "ts": 1794953724740,3481 "stale": false3482 },3483 "funding": {3484 "value": "-0.0000113686",3485 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",3486 "ts": 1794953724740,3487 "stale": false,3488 "intervalSec": 36003489 },3490 "openInterest": {3491 "value": "117475.832",3492 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",3493 "ts": 1794953724740,3494 "stale": false3495 },3496 "openInterestUsd": {3497 "value": "197817553.5048",3498 "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",3499 "ts": 1794953724740,3500 "stale": false3501 },3502 "volume24h": {3503 "value": "34445966.2849999964",3504 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",3505 "ts": 1794953724740,3506 "stale": false3507 },3508 "volumeBase24h": {3509 "value": "20388.063",3510 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",3511 "ts": 1794953724740,3512 "stale": false3513 },3514 "frozen": false3515 },3516 "valuation": {3517 "syntheticPrice": {3518 "value": "1683.9",3519 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",3520 "ts": 1794953724740,3521 "stale": false,3522 "unit": "valuation_usd_billions",3523 "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",3524 "priceKind": "mark"3525 },3526 "contractMarketValue": {3527 "value": "1683.9",3528 "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",3529 "reason": null,3530 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",3531 "ts": 17949537247403532 },3533 "notionalExposure": {3534 "value": "1683.9",3535 "formula": "size × contract value, negative for a short",3536 "reason": null,3537 "position": {3538 "side": "long",3539 "size": "1"3540 },3541 "hypothetical": true,3542 "ts": 17949537247403543 },3544 "impliedValuation": {3545 "value": "1683900000000",3546 "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",3547 "formulaId": "price_x_1e9",3548 "formulaSource": {3549 "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",3550 "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",3551 "readAt": "2026-11-15"3552 },3553 "asOf": 1794953724740,3554 "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",3555 "reason": null,3556 "reasonCode": null3557 },3558 "lastPrivateValuation": {3559 "value": "965000000000",3560 "kind": "primary_round",3561 "detail": "Series H, $65B raised, post-money",3562 "date": "2026-05-28",3563 "sourceUrl": "https://www.anthropic.com/news/series-h",3564 "confidence": "high"3565 },3566 "lastPrivateValuationReason": null,3567 "premiumDiscount": {3568 "premiumBps": "7449.7409",3569 "reason": null,3570 "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"3571 },3572 "caveats": [3573 {3574 "code": "synthetic",3575 "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"3576 }3577 ]3578 },3579 "tradable": false,3580 "notTradable": {3581 "code": "builder_dex_read_only",3582 "reasons": [3583 "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"3584 ]3585 },3586 "error": null3587 }3588 ],3589 "companies": [3590 {3591 "slug": "anthropic",3592 "name": "Anthropic, PBC",3593 "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date.",3594 "contracts": [3595 "hyperliquid:io:ANTH"3596 ],3597 "lastPrivateValuation": {3598 "value": "965000000000",3599 "kind": "primary_round",3600 "detail": "Series H, $65B raised, post-money",3601 "date": "2026-05-28",3602 "sourceUrl": "https://www.anthropic.com/news/series-h",3603 "confidence": "high"3604 },3605 "divergence": [3606 {3607 "unit": "usd_per_share",3608 "unitLabel": "USD per 1 share (share class not specified by the operator)",3609 "contracts": [3610 {3611 "id": "hyperliquid:para:ANTH",3612 "price": "96.26",3613 "ts": 17949537248433614 }3615 ],3616 "spreadBps": "7.58",3617 "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"3618 }3619 ]3620 }3621 ],3622 "excluded": [3623 {3624 "id": "hyperliquid:xyz:SPCX",3625 "company": "SpaceX",3626 "reason": "SpaceX is a listed company (Nasdaq: SPCX): the deployer annotates this market as a listed stock and categorises it `stocks`. Not a private market.",3627 "liveCategory": "stocks",3628 "delisted": false3629 }3630 ],3631 "venues": [3632 {3633 "venue": "hyperliquid",3634 "name": "Hyperliquid (builder-deployed dexes)",3635 "status": "ok",3636 "error": null,3637 "ts": 1794953723863,3638 "instruments": 53639 }3640 ],3641 "venuesWithoutAdapter": [3642 {3643 "venue": "Aster",3644 "note": "ANTHROPICUSDT, OPENAIUSDT, POLYMARKETUSD1, OURAUSD1, MOONSHOTUSD1 — per share against a notional reference count of 1 billion shares"3645 }3646 ],3647 "notice": {3648 "tradable": false,3649 "code": "private_markets_display_only",3650 "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"3651 },3652 "filter": {3653 "delisted": false3654 },3655 "position": {3656 "side": "long",3657 "size": "1"3658 },3659 "cache": {3660 "discovery": {3661 "ttl": 60000,3662 "maxAge": 9000003663 },3664 "markets": {3665 "ttl": 20000,3666 "maxAge": 1200003667 },3668 "delisted": {3669 "ttl": 600000,3670 "maxAge": 36000003671 },3672 "annotation": {3673 "ttl": 600000,3674 "maxAge": 36000003675 },3676 "book": {3677 "ttl": 5000,3678 "maxAge": 300003679 },3680 "candles": {3681 "ttl": 60000,3682 "maxAge": 6000003683 },3684 "edgexTickers": {3685 "ttl": 3000,3686 "maxAge": 150003687 },3688 "edgexInstruments": {3689 "ttl": 600000,3690 "maxAge": 36000003691 },3692 "staleAfter": {3693 "hyperliquid": 60000,3694 "edgex": 150003695 }3696 },3697 "reviewedTable": {3698 "entries": 10,3699 "reviewedAt": "2026-11-15"3700 },3701 "ts": 1794953725186,3702 "source": "venue"3703 }3704 }3705 }3706 },3707 "400": {3708 "description": "The request is not valid: `bad_request`",3709 "content": {3710 "application/json": {3711 "schema": {3712 "$ref": "#/components/schemas/Error"3713 }3714 }3715 }3716 },3717 "401": {3718 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",3719 "content": {3720 "application/json": {3721 "schema": {3722 "$ref": "#/components/schemas/Error"3723 }3724 }3725 }3726 },3727 "403": {3728 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",3729 "content": {3730 "application/json": {3731 "schema": {3732 "$ref": "#/components/schemas/Error"3733 }3734 }3735 }3736 },3737 "429": {3738 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",3739 "content": {3740 "application/json": {3741 "schema": {3742 "$ref": "#/components/schemas/Error"3743 }3744 }3745 }3746 },3747 "500": {3748 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",3749 "content": {3750 "application/json": {3751 "schema": {3752 "$ref": "#/components/schemas/Error"3753 }3754 }3755 }3756 },3757 "503": {3758 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",3759 "content": {3760 "application/json": {3761 "schema": {3762 "$ref": "#/components/schemas/Error"3763 }3764 }3765 }3766 }3767 }3768 }3769 },3770 "/api/v1/trading/private-markets/companies/{slug}": {3771 "get": {3772 "operationId": "getPrivateMarketCompany",3773 "tags": [3774 "Markets"3775 ],3776 "summary": "Every contract on one private company, side by side (never merged)",3777 "description": "The contracts that reference one company (`slug` from GET /private-markets, `companies`), each on its own row with its own unit and valuation breakdown, plus the delisted ones and the sourced private-valuation references. `merged` is always null: a figure of one venue is never combined with another's. Display only: none of these contracts is tradable from this wallet.",3778 "security": [3779 {3780 "bearerKey": [3781 "markets:read"3782 ]3783 }3784 ],3785 "x-spw-scope": "markets:read",3786 "x-spw-implemented": true,3787 "x-spw-errors": [3788 {3789 "status": 400,3790 "code": "bad_request"3791 },3792 {3793 "status": 401,3794 "code": "unauthenticated"3795 },3796 {3797 "status": 403,3798 "code": "insufficient_scope"3799 },3800 {3801 "status": 403,3802 "code": "ip_not_allowed"3803 },3804 {3805 "status": 403,3806 "code": "mixed_credentials"3807 },3808 {3809 "status": 404,3810 "code": "unknown_company"3811 },3812 {3813 "status": 429,3814 "code": "auth_throttled"3815 },3816 {3817 "status": 429,3818 "code": "rate_limited"3819 },3820 {3821 "status": 500,3822 "code": "internal"3823 },3824 {3825 "status": 503,3826 "code": "venue_rate_limited"3827 },3828 {3829 "status": 503,3830 "code": "venue_timeout"3831 },3832 {3833 "status": 503,3834 "code": "venue_unavailable"3835 }3836 ],3837 "x-spw-example-recorded": true,3838 "x-spw-example-note": "Cut to one contract.",3839 "x-codeSamples": [3840 {3841 "lang": "Shell",3842 "label": "curl",3843 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/private-markets/companies/anthropic\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""3844 },3845 {3846 "lang": "TypeScript",3847 "label": "TypeScript",3848 "source": "const company = await client.getPrivateMarketCompany('anthropic');"3849 },3850 {3851 "lang": "Python",3852 "label": "Python",3853 "source": "company = client.get_private_market_company(\"anthropic\")"3854 }3855 ],3856 "parameters": [3857 {3858 "name": "slug",3859 "in": "path",3860 "required": true,3861 "description": "company slug, from GET /private-markets (`companies[].slug`), e.g. `anthropic`",3862 "schema": {3863 "type": "string",3864 "pattern": "^[a-z0-9-]{1,40}$"3865 },3866 "example": "anthropic"3867 },3868 {3869 "name": "size",3870 "in": "query",3871 "required": false,3872 "description": "hypothetical position size, contracts (default 1)",3873 "schema": {3874 "type": "string",3875 "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"3876 }3877 },3878 {3879 "name": "side",3880 "in": "query",3881 "required": false,3882 "description": "side of the hypothetical position (default long)",3883 "schema": {3884 "type": "string",3885 "enum": [3886 "long",3887 "short"3888 ]3889 }3890 },3891 {3892 "name": "interval",3893 "in": "query",3894 "required": false,3895 "description": "candle length",3896 "schema": {3897 "type": "string",3898 "enum": [3899 "1h",3900 "1d"3901 ]3902 }3903 },3904 {3905 "name": "limit",3906 "in": "query",3907 "required": false,3908 "description": "candles returned at most",3909 "schema": {3910 "type": "integer",3911 "minimum": 1,3912 "maximum": 5003913 }3914 }3915 ],3916 "responses": {3917 "200": {3918 "description": "OK (the example is a recorded answer)",3919 "content": {3920 "application/json": {3921 "schema": {3922 "type": "object",3923 "properties": {3924 "company": {3925 "type": "object",3926 "properties": {3927 "slug": {3928 "type": "string"3929 },3930 "name": {3931 "type": "string"3932 }3933 },3934 "required": [3935 "slug",3936 "name"3937 ],3938 "additionalProperties": {}3939 },3940 "contracts": {3941 "type": "array",3942 "items": {3943 "type": "object",3944 "properties": {3945 "id": {3946 "type": "string"3947 },3948 "venue": {3949 "type": "string"3950 },3951 "platform": {3952 "type": "string"3953 },3954 "symbol": {3955 "type": "string"3956 },3957 "company": {3958 "anyOf": [3959 {3960 "type": "object",3961 "properties": {3962 "slug": {3963 "type": "string"3964 },3965 "name": {3966 "type": "string"3967 }3968 },3969 "required": [3970 "slug",3971 "name"3972 ],3973 "additionalProperties": false3974 },3975 {3976 "type": "null"3977 }3978 ]3979 },3980 "status": {3981 "type": "string",3982 "enum": [3983 "live",3984 "delisted",3985 "halted",3986 "reduce_only"3987 ]3988 },3989 "review": {3990 "type": "object",3991 "properties": {3992 "state": {3993 "type": "string",3994 "enum": [3995 "reviewed",3996 "under_review",3997 "not_reviewed"3998 ]3999 },4000 "reasons": {4001 "type": "array",4002 "items": {4003 "type": "string"4004 }4005 }4006 },4007 "required": [4008 "state",4009 "reasons"4010 ],4011 "additionalProperties": {}4012 },4013 "contract": {4014 "type": "object",4015 "properties": {4016 "nature": {4017 "type": "string"4018 },4019 "unit": {4020 "type": "object",4021 "properties": {4022 "kind": {4023 "type": "string",4024 "enum": [4025 "usd_per_share",4026 "valuation_usd_billions",4027 "unknown"4028 ]4029 },4030 "label": {4031 "type": "string"4032 }4033 },4034 "required": [4035 "kind",4036 "label"4037 ],4038 "additionalProperties": false4039 },4040 "quoteCurrency": {4041 "type": "string"4042 },4043 "settlement": {4044 "type": "string"4045 },4046 "oracle": {4047 "type": "string"4048 },4049 "liquidation": {4050 "type": "string"4051 }4052 },4053 "required": [4054 "nature",4055 "unit",4056 "quoteCurrency",4057 "settlement",4058 "oracle",4059 "liquidation"4060 ],4061 "additionalProperties": {}4062 },4063 "market": {4064 "type": "object",4065 "properties": {4066 "price": {4067 "type": "object",4068 "properties": {4069 "value": {4070 "anyOf": [4071 {4072 "type": "string",4073 "description": "decimal number as a string (never a float)"4074 },4075 {4076 "type": "null"4077 }4078 ]4079 },4080 "source": {4081 "type": "string"4082 },4083 "ts": {4084 "anyOf": [4085 {4086 "type": "integer",4087 "minimum": -9007199254740991,4088 "maximum": 9007199254740991,4089 "description": "milliseconds since the Unix epoch"4090 },4091 {4092 "type": "null"4093 }4094 ]4095 },4096 "stale": {4097 "type": "boolean"4098 }4099 },4100 "required": [4101 "value",4102 "source",4103 "ts",4104 "stale"4105 ],4106 "additionalProperties": false,4107 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4108 },4109 "funding": {4110 "type": "object",4111 "properties": {4112 "value": {4113 "anyOf": [4114 {4115 "type": "string",4116 "description": "decimal number as a string (never a float)"4117 },4118 {4119 "type": "null"4120 }4121 ]4122 },4123 "source": {4124 "type": "string"4125 },4126 "ts": {4127 "anyOf": [4128 {4129 "type": "integer",4130 "minimum": -9007199254740991,4131 "maximum": 9007199254740991,4132 "description": "milliseconds since the Unix epoch"4133 },4134 {4135 "type": "null"4136 }4137 ]4138 },4139 "stale": {4140 "type": "boolean"4141 },4142 "intervalSec": {4143 "anyOf": [4144 {4145 "type": "integer",4146 "minimum": -9007199254740991,4147 "maximum": 90071992547409914148 },4149 {4150 "type": "null"4151 }4152 ]4153 }4154 },4155 "required": [4156 "value",4157 "source",4158 "ts",4159 "stale",4160 "intervalSec"4161 ],4162 "additionalProperties": false4163 },4164 "openInterest": {4165 "type": "object",4166 "properties": {4167 "value": {4168 "anyOf": [4169 {4170 "type": "string",4171 "description": "decimal number as a string (never a float)"4172 },4173 {4174 "type": "null"4175 }4176 ]4177 },4178 "source": {4179 "type": "string"4180 },4181 "ts": {4182 "anyOf": [4183 {4184 "type": "integer",4185 "minimum": -9007199254740991,4186 "maximum": 9007199254740991,4187 "description": "milliseconds since the Unix epoch"4188 },4189 {4190 "type": "null"4191 }4192 ]4193 },4194 "stale": {4195 "type": "boolean"4196 }4197 },4198 "required": [4199 "value",4200 "source",4201 "ts",4202 "stale"4203 ],4204 "additionalProperties": false,4205 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4206 },4207 "volume24h": {4208 "type": "object",4209 "properties": {4210 "value": {4211 "anyOf": [4212 {4213 "type": "string",4214 "description": "decimal number as a string (never a float)"4215 },4216 {4217 "type": "null"4218 }4219 ]4220 },4221 "source": {4222 "type": "string"4223 },4224 "ts": {4225 "anyOf": [4226 {4227 "type": "integer",4228 "minimum": -9007199254740991,4229 "maximum": 9007199254740991,4230 "description": "milliseconds since the Unix epoch"4231 },4232 {4233 "type": "null"4234 }4235 ]4236 },4237 "stale": {4238 "type": "boolean"4239 }4240 },4241 "required": [4242 "value",4243 "source",4244 "ts",4245 "stale"4246 ],4247 "additionalProperties": false,4248 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4249 }4250 },4251 "required": [4252 "price",4253 "funding",4254 "openInterest",4255 "volume24h"4256 ],4257 "additionalProperties": {}4258 },4259 "valuation": {4260 "type": "object",4261 "properties": {4262 "syntheticPrice": {4263 "type": "object",4264 "properties": {4265 "value": {4266 "anyOf": [4267 {4268 "type": "string",4269 "description": "decimal number as a string (never a float)"4270 },4271 {4272 "type": "null"4273 }4274 ]4275 }4276 },4277 "required": [4278 "value"4279 ],4280 "additionalProperties": {}4281 },4282 "contractMarketValue": {4283 "type": "object",4284 "properties": {4285 "value": {4286 "anyOf": [4287 {4288 "type": "string",4289 "description": "decimal number as a string (never a float)"4290 },4291 {4292 "type": "null"4293 }4294 ]4295 },4296 "reason": {4297 "type": [4298 "string",4299 "null"4300 ]4301 }4302 },4303 "required": [4304 "value",4305 "reason"4306 ],4307 "additionalProperties": {}4308 },4309 "notionalExposure": {4310 "type": "object",4311 "properties": {4312 "value": {4313 "anyOf": [4314 {4315 "type": "string",4316 "description": "decimal number as a string (never a float)"4317 },4318 {4319 "type": "null"4320 }4321 ]4322 },4323 "hypothetical": {4324 "type": "boolean",4325 "const": true4326 }4327 },4328 "required": [4329 "value",4330 "hypothetical"4331 ],4332 "additionalProperties": {}4333 },4334 "impliedValuation": {4335 "type": "object",4336 "properties": {4337 "value": {4338 "anyOf": [4339 {4340 "type": "string",4341 "description": "decimal number as a string (never a float)"4342 },4343 {4344 "type": "null"4345 }4346 ]4347 },4348 "formula": {4349 "type": [4350 "string",4351 "null"4352 ]4353 },4354 "reason": {4355 "type": [4356 "string",4357 "null"4358 ]4359 },4360 "reasonCode": {4361 "type": [4362 "string",4363 "null"4364 ]4365 }4366 },4367 "required": [4368 "value",4369 "formula",4370 "reason",4371 "reasonCode"4372 ],4373 "additionalProperties": {},4374 "description": "null + reason unless the reviewed definition gives the formula"4375 },4376 "lastPrivateValuation": {4377 "anyOf": [4378 {4379 "type": "object",4380 "properties": {4381 "value": {4382 "type": "string",4383 "description": "decimal number as a string (never a float)"4384 },4385 "kind": {4386 "type": "string"4387 },4388 "date": {4389 "type": "string"4390 },4391 "sourceUrl": {4392 "type": "string"4393 }4394 },4395 "required": [4396 "value",4397 "kind",4398 "date",4399 "sourceUrl"4400 ],4401 "additionalProperties": {}4402 },4403 {4404 "type": "null"4405 }4406 ]4407 },4408 "premiumDiscount": {4409 "type": "object",4410 "properties": {4411 "premiumBps": {4412 "anyOf": [4413 {4414 "type": "string",4415 "description": "decimal number as a string (never a float)"4416 },4417 {4418 "type": "null"4419 }4420 ]4421 }4422 },4423 "required": [4424 "premiumBps"4425 ],4426 "additionalProperties": {}4427 },4428 "caveats": {4429 "type": "array",4430 "items": {4431 "type": "object",4432 "properties": {4433 "code": {4434 "type": "string"4435 },4436 "text": {4437 "type": "string"4438 }4439 },4440 "required": [4441 "code",4442 "text"4443 ],4444 "additionalProperties": {}4445 }4446 }4447 },4448 "required": [4449 "syntheticPrice",4450 "contractMarketValue",4451 "notionalExposure",4452 "impliedValuation",4453 "lastPrivateValuation",4454 "premiumDiscount",4455 "caveats"4456 ],4457 "additionalProperties": {}4458 },4459 "tradable": {4460 "type": "boolean",4461 "const": false4462 },4463 "notTradable": {4464 "type": "object",4465 "properties": {4466 "code": {4467 "type": "string"4468 },4469 "reasons": {4470 "type": "array",4471 "items": {4472 "type": "string"4473 }4474 }4475 },4476 "required": [4477 "code",4478 "reasons"4479 ],4480 "additionalProperties": false4481 },4482 "error": {4483 "type": [4484 "string",4485 "null"4486 ]4487 }4488 },4489 "required": [4490 "id",4491 "venue",4492 "platform",4493 "symbol",4494 "company",4495 "status",4496 "review",4497 "contract",4498 "market",4499 "valuation",4500 "tradable",4501 "notTradable",4502 "error"4503 ],4504 "additionalProperties": {}4505 }4506 },4507 "delisted": {4508 "type": "array",4509 "items": {4510 "type": "object",4511 "properties": {4512 "id": {4513 "type": "string"4514 },4515 "venue": {4516 "type": "string"4517 },4518 "platform": {4519 "type": "string"4520 },4521 "symbol": {4522 "type": "string"4523 },4524 "company": {4525 "anyOf": [4526 {4527 "type": "object",4528 "properties": {4529 "slug": {4530 "type": "string"4531 },4532 "name": {4533 "type": "string"4534 }4535 },4536 "required": [4537 "slug",4538 "name"4539 ],4540 "additionalProperties": false4541 },4542 {4543 "type": "null"4544 }4545 ]4546 },4547 "status": {4548 "type": "string",4549 "enum": [4550 "live",4551 "delisted",4552 "halted",4553 "reduce_only"4554 ]4555 },4556 "review": {4557 "type": "object",4558 "properties": {4559 "state": {4560 "type": "string",4561 "enum": [4562 "reviewed",4563 "under_review",4564 "not_reviewed"4565 ]4566 },4567 "reasons": {4568 "type": "array",4569 "items": {4570 "type": "string"4571 }4572 }4573 },4574 "required": [4575 "state",4576 "reasons"4577 ],4578 "additionalProperties": {}4579 },4580 "contract": {4581 "type": "object",4582 "properties": {4583 "nature": {4584 "type": "string"4585 },4586 "unit": {4587 "type": "object",4588 "properties": {4589 "kind": {4590 "type": "string",4591 "enum": [4592 "usd_per_share",4593 "valuation_usd_billions",4594 "unknown"4595 ]4596 },4597 "label": {4598 "type": "string"4599 }4600 },4601 "required": [4602 "kind",4603 "label"4604 ],4605 "additionalProperties": false4606 },4607 "quoteCurrency": {4608 "type": "string"4609 },4610 "settlement": {4611 "type": "string"4612 },4613 "oracle": {4614 "type": "string"4615 },4616 "liquidation": {4617 "type": "string"4618 }4619 },4620 "required": [4621 "nature",4622 "unit",4623 "quoteCurrency",4624 "settlement",4625 "oracle",4626 "liquidation"4627 ],4628 "additionalProperties": {}4629 },4630 "market": {4631 "type": "object",4632 "properties": {4633 "price": {4634 "type": "object",4635 "properties": {4636 "value": {4637 "anyOf": [4638 {4639 "type": "string",4640 "description": "decimal number as a string (never a float)"4641 },4642 {4643 "type": "null"4644 }4645 ]4646 },4647 "source": {4648 "type": "string"4649 },4650 "ts": {4651 "anyOf": [4652 {4653 "type": "integer",4654 "minimum": -9007199254740991,4655 "maximum": 9007199254740991,4656 "description": "milliseconds since the Unix epoch"4657 },4658 {4659 "type": "null"4660 }4661 ]4662 },4663 "stale": {4664 "type": "boolean"4665 }4666 },4667 "required": [4668 "value",4669 "source",4670 "ts",4671 "stale"4672 ],4673 "additionalProperties": false,4674 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4675 },4676 "funding": {4677 "type": "object",4678 "properties": {4679 "value": {4680 "anyOf": [4681 {4682 "type": "string",4683 "description": "decimal number as a string (never a float)"4684 },4685 {4686 "type": "null"4687 }4688 ]4689 },4690 "source": {4691 "type": "string"4692 },4693 "ts": {4694 "anyOf": [4695 {4696 "type": "integer",4697 "minimum": -9007199254740991,4698 "maximum": 9007199254740991,4699 "description": "milliseconds since the Unix epoch"4700 },4701 {4702 "type": "null"4703 }4704 ]4705 },4706 "stale": {4707 "type": "boolean"4708 },4709 "intervalSec": {4710 "anyOf": [4711 {4712 "type": "integer",4713 "minimum": -9007199254740991,4714 "maximum": 90071992547409914715 },4716 {4717 "type": "null"4718 }4719 ]4720 }4721 },4722 "required": [4723 "value",4724 "source",4725 "ts",4726 "stale",4727 "intervalSec"4728 ],4729 "additionalProperties": false4730 },4731 "openInterest": {4732 "type": "object",4733 "properties": {4734 "value": {4735 "anyOf": [4736 {4737 "type": "string",4738 "description": "decimal number as a string (never a float)"4739 },4740 {4741 "type": "null"4742 }4743 ]4744 },4745 "source": {4746 "type": "string"4747 },4748 "ts": {4749 "anyOf": [4750 {4751 "type": "integer",4752 "minimum": -9007199254740991,4753 "maximum": 9007199254740991,4754 "description": "milliseconds since the Unix epoch"4755 },4756 {4757 "type": "null"4758 }4759 ]4760 },4761 "stale": {4762 "type": "boolean"4763 }4764 },4765 "required": [4766 "value",4767 "source",4768 "ts",4769 "stale"4770 ],4771 "additionalProperties": false,4772 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4773 },4774 "volume24h": {4775 "type": "object",4776 "properties": {4777 "value": {4778 "anyOf": [4779 {4780 "type": "string",4781 "description": "decimal number as a string (never a float)"4782 },4783 {4784 "type": "null"4785 }4786 ]4787 },4788 "source": {4789 "type": "string"4790 },4791 "ts": {4792 "anyOf": [4793 {4794 "type": "integer",4795 "minimum": -9007199254740991,4796 "maximum": 9007199254740991,4797 "description": "milliseconds since the Unix epoch"4798 },4799 {4800 "type": "null"4801 }4802 ]4803 },4804 "stale": {4805 "type": "boolean"4806 }4807 },4808 "required": [4809 "value",4810 "source",4811 "ts",4812 "stale"4813 ],4814 "additionalProperties": false,4815 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"4816 }4817 },4818 "required": [4819 "price",4820 "funding",4821 "openInterest",4822 "volume24h"4823 ],4824 "additionalProperties": {}4825 },4826 "valuation": {4827 "type": "object",4828 "properties": {4829 "syntheticPrice": {4830 "type": "object",4831 "properties": {4832 "value": {4833 "anyOf": [4834 {4835 "type": "string",4836 "description": "decimal number as a string (never a float)"4837 },4838 {4839 "type": "null"4840 }4841 ]4842 }4843 },4844 "required": [4845 "value"4846 ],4847 "additionalProperties": {}4848 },4849 "contractMarketValue": {4850 "type": "object",4851 "properties": {4852 "value": {4853 "anyOf": [4854 {4855 "type": "string",4856 "description": "decimal number as a string (never a float)"4857 },4858 {4859 "type": "null"4860 }4861 ]4862 },4863 "reason": {4864 "type": [4865 "string",4866 "null"4867 ]4868 }4869 },4870 "required": [4871 "value",4872 "reason"4873 ],4874 "additionalProperties": {}4875 },4876 "notionalExposure": {4877 "type": "object",4878 "properties": {4879 "value": {4880 "anyOf": [4881 {4882 "type": "string",4883 "description": "decimal number as a string (never a float)"4884 },4885 {4886 "type": "null"4887 }4888 ]4889 },4890 "hypothetical": {4891 "type": "boolean",4892 "const": true4893 }4894 },4895 "required": [4896 "value",4897 "hypothetical"4898 ],4899 "additionalProperties": {}4900 },4901 "impliedValuation": {4902 "type": "object",4903 "properties": {4904 "value": {4905 "anyOf": [4906 {4907 "type": "string",4908 "description": "decimal number as a string (never a float)"4909 },4910 {4911 "type": "null"4912 }4913 ]4914 },4915 "formula": {4916 "type": [4917 "string",4918 "null"4919 ]4920 },4921 "reason": {4922 "type": [4923 "string",4924 "null"4925 ]4926 },4927 "reasonCode": {4928 "type": [4929 "string",4930 "null"4931 ]4932 }4933 },4934 "required": [4935 "value",4936 "formula",4937 "reason",4938 "reasonCode"4939 ],4940 "additionalProperties": {},4941 "description": "null + reason unless the reviewed definition gives the formula"4942 },4943 "lastPrivateValuation": {4944 "anyOf": [4945 {4946 "type": "object",4947 "properties": {4948 "value": {4949 "type": "string",4950 "description": "decimal number as a string (never a float)"4951 },4952 "kind": {4953 "type": "string"4954 },4955 "date": {4956 "type": "string"4957 },4958 "sourceUrl": {4959 "type": "string"4960 }4961 },4962 "required": [4963 "value",4964 "kind",4965 "date",4966 "sourceUrl"4967 ],4968 "additionalProperties": {}4969 },4970 {4971 "type": "null"4972 }4973 ]4974 },4975 "premiumDiscount": {4976 "type": "object",4977 "properties": {4978 "premiumBps": {4979 "anyOf": [4980 {4981 "type": "string",4982 "description": "decimal number as a string (never a float)"4983 },4984 {4985 "type": "null"4986 }4987 ]4988 }4989 },4990 "required": [4991 "premiumBps"4992 ],4993 "additionalProperties": {}4994 },4995 "caveats": {4996 "type": "array",4997 "items": {4998 "type": "object",4999 "properties": {5000 "code": {5001 "type": "string"5002 },5003 "text": {5004 "type": "string"5005 }5006 },5007 "required": [5008 "code",5009 "text"5010 ],5011 "additionalProperties": {}5012 }5013 }5014 },5015 "required": [5016 "syntheticPrice",5017 "contractMarketValue",5018 "notionalExposure",5019 "impliedValuation",5020 "lastPrivateValuation",5021 "premiumDiscount",5022 "caveats"5023 ],5024 "additionalProperties": {}5025 },5026 "tradable": {5027 "type": "boolean",5028 "const": false5029 },5030 "notTradable": {5031 "type": "object",5032 "properties": {5033 "code": {5034 "type": "string"5035 },5036 "reasons": {5037 "type": "array",5038 "items": {5039 "type": "string"5040 }5041 }5042 },5043 "required": [5044 "code",5045 "reasons"5046 ],5047 "additionalProperties": false5048 },5049 "error": {5050 "type": [5051 "string",5052 "null"5053 ]5054 }5055 },5056 "required": [5057 "id",5058 "venue",5059 "platform",5060 "symbol",5061 "company",5062 "status",5063 "review",5064 "contract",5065 "market",5066 "valuation",5067 "tradable",5068 "notTradable",5069 "error"5070 ],5071 "additionalProperties": {}5072 }5073 },5074 "references": {5075 "type": "array",5076 "items": {5077 "type": "object",5078 "properties": {},5079 "additionalProperties": {}5080 }5081 },5082 "merged": {5083 "type": "null",5084 "description": "always null: venues are never merged"5085 },5086 "ts": {5087 "type": "integer",5088 "minimum": -9007199254740991,5089 "maximum": 9007199254740991,5090 "description": "milliseconds since the Unix epoch"5091 }5092 },5093 "required": [5094 "company",5095 "contracts",5096 "delisted",5097 "references",5098 "merged",5099 "ts"5100 ],5101 "additionalProperties": {}5102 },5103 "example": {5104 "company": {5105 "slug": "anthropic",5106 "name": "Anthropic, PBC",5107 "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date."5108 },5109 "contracts": [5110 {5111 "id": "hyperliquid:io:ANTH",5112 "venue": "hyperliquid",5113 "platform": "Hyperliquid · EntropyIO (dex io)",5114 "operator": "EntropyIO",5115 "symbol": "io:ANTH",5116 "company": {5117 "slug": "anthropic",5118 "name": "Anthropic, PBC"5119 },5120 "status": "live",5121 "review": {5122 "state": "reviewed",5123 "reasons": [],5124 "reviewedAt": "2026-11-15",5125 "validUntil": "2026-11-18T00:00:00Z",5126 "fingerprintChecked": true5127 },5128 "contract": {5129 "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",5130 "unit": {5131 "kind": "valuation_usd_billions",5132 "label": "USD billions of fully diluted company valuation (1.00 = $1B)"5133 },5134 "quoteCurrency": "USD",5135 "collateral": "USDC",5136 "underlying": "Anthropic, PBC",5137 "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",5138 "multiplier": {5139 "value": "1",5140 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"5141 },5142 "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",5143 "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",5144 "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",5145 "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",5146 "maxLeverage": "15",5147 "margin": "cross_allowed",5148 "lotSize": "0.001",5149 "szDecimals": 3,5150 "fundingIntervalSec": 3600,5151 "assetId": 200001,5152 "dex": "io",5153 "oiCapUsd": "275000000",5154 "fundingMultiplier": "0.125",5155 "onChainDescription": "",5156 "unconfirmedConvention": null,5157 "sources": [5158 "https://docs.entropy.io/market-types/pre-ipo-perpetuals"5159 ]5160 },5161 "market": {5162 "price": {5163 "value": "1683.9",5164 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",5165 "ts": 1794953724740,5166 "stale": false5167 },5168 "oracle": {5169 "value": "1684",5170 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",5171 "ts": 1794953724740,5172 "stale": false5173 },5174 "mid": {5175 "value": "1680.6",5176 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",5177 "ts": 1794953724740,5178 "stale": false5179 },5180 "funding": {5181 "value": "-0.0000113686",5182 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",5183 "ts": 1794953724740,5184 "stale": false,5185 "intervalSec": 36005186 },5187 "openInterest": {5188 "value": "117475.832",5189 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",5190 "ts": 1794953724740,5191 "stale": false5192 },5193 "openInterestUsd": {5194 "value": "197817553.5048",5195 "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",5196 "ts": 1794953724740,5197 "stale": false5198 },5199 "volume24h": {5200 "value": "34445966.2849999964",5201 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",5202 "ts": 1794953724740,5203 "stale": false5204 },5205 "volumeBase24h": {5206 "value": "20388.063",5207 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",5208 "ts": 1794953724740,5209 "stale": false5210 },5211 "frozen": false5212 },5213 "valuation": {5214 "syntheticPrice": {5215 "value": "1683.9",5216 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",5217 "ts": 1794953724740,5218 "stale": false,5219 "unit": "valuation_usd_billions",5220 "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",5221 "priceKind": "mark"5222 },5223 "contractMarketValue": {5224 "value": "1683.9",5225 "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",5226 "reason": null,5227 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",5228 "ts": 17949537247405229 },5230 "notionalExposure": {5231 "value": "1683.9",5232 "formula": "size × contract value, negative for a short",5233 "reason": null,5234 "position": {5235 "side": "long",5236 "size": "1"5237 },5238 "hypothetical": true,5239 "ts": 17949537247405240 },5241 "impliedValuation": {5242 "value": "1683900000000",5243 "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",5244 "formulaId": "price_x_1e9",5245 "formulaSource": {5246 "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",5247 "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",5248 "readAt": "2026-11-15"5249 },5250 "asOf": 1794953724740,5251 "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",5252 "reason": null,5253 "reasonCode": null5254 },5255 "lastPrivateValuation": {5256 "value": "965000000000",5257 "kind": "primary_round",5258 "detail": "Series H, $65B raised, post-money",5259 "date": "2026-05-28",5260 "sourceUrl": "https://www.anthropic.com/news/series-h",5261 "confidence": "high"5262 },5263 "lastPrivateValuationReason": null,5264 "premiumDiscount": {5265 "premiumBps": "7449.7409",5266 "reason": null,5267 "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"5268 },5269 "caveats": [5270 {5271 "code": "synthetic",5272 "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"5273 }5274 ]5275 },5276 "tradable": false,5277 "notTradable": {5278 "code": "builder_dex_read_only",5279 "reasons": [5280 "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"5281 ]5282 },5283 "error": null5284 }5285 ],5286 "delisted": [5287 {5288 "id": "hyperliquid:vntl:ANTHROPIC",5289 "venue": "hyperliquid",5290 "platform": "Hyperliquid · Ventuals (dex vntl) — shut down",5291 "operator": "Ventuals",5292 "symbol": "vntl:ANTHROPIC",5293 "company": {5294 "slug": "anthropic",5295 "name": "Anthropic, PBC"5296 },5297 "status": "delisted",5298 "review": {5299 "state": "reviewed",5300 "reasons": [],5301 "reviewedAt": "2026-11-15",5302 "validUntil": null,5303 "fingerprintChecked": true5304 },5305 "contract": {5306 "nature": "cash-settled perpetual, pure synthetic — DELISTED: Ventuals shut down on 15 Jun 2026 and its markets were settled",5307 "unit": {5308 "kind": "valuation_usd_billions",5309 "label": "USD billions of company valuation (historical)"5310 },5311 "quoteCurrency": "USD",5312 "collateral": "USDH",5313 "underlying": "Anthropic, PBC",5314 "contractSize": "1 contract = 1 unit of ANTHROPIC; smallest size 0.001",5315 "multiplier": {5316 "value": "1",5317 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"5318 },5319 "settlement": "Settled at the 24 h mark TWAP 1618.90 on 15 Jun 2026 (Ventuals sunset guide).",5320 "ipoConversion": "not applicable (settled)",5321 "oracle": "Was 1/3 Notice price + 2/3 two-hour EMA of the mark (Ventuals documentation).",5322 "liquidation": "not applicable (no open position can exist)",5323 "maxLeverage": "3",5324 "margin": "strict_isolated",5325 "lotSize": "0.001",5326 "szDecimals": 3,5327 "fundingIntervalSec": 3600,5328 "assetId": 130002,5329 "dex": "vntl",5330 "oiCapUsd": "10000000",5331 "fundingMultiplier": "0",5332 "onChainDescription": "ANTHROPIC tracks the total valuation of Anthropic, in billions. E.g. if 1 ANTHROPIC = $500, then the implied total valuation of the company is $500B.",5333 "unconfirmedConvention": null,5334 "sources": [5335 "https://docs.ventuals.com/perp-specifications/private-companies"5336 ]5337 },5338 "market": {5339 "price": {5340 "value": "1619.3",5341 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",5342 "ts": 1794953725593,5343 "stale": false5344 },5345 "oracle": {5346 "value": "1618.9",5347 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — oracle price",5348 "ts": 1794953725593,5349 "stale": false5350 },5351 "mid": {5352 "value": null,5353 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — book mid",5354 "ts": null,5355 "stale": false5356 },5357 "funding": {5358 "value": "0",5359 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — funding rate per interval",5360 "ts": 1794953725593,5361 "stale": false,5362 "intervalSec": 36005363 },5364 "openInterest": {5365 "value": "0",5366 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — open interest, contracts",5367 "ts": 1794953725593,5368 "stale": false5369 },5370 "openInterestUsd": {5371 "value": "0",5372 "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",5373 "ts": 1794953725593,5374 "stale": false5375 },5376 "volume24h": {5377 "value": "0",5378 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h notional volume, USD",5379 "ts": 1794953725593,5380 "stale": false5381 },5382 "volumeBase24h": {5383 "value": "0",5384 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — 24 h volume, contracts",5385 "ts": 1794953725593,5386 "stale": false5387 },5388 "frozen": true5389 },5390 "valuation": {5391 "syntheticPrice": {5392 "value": "1619.3",5393 "source": "Hyperliquid info metaAndAssetCtxs (dex vntl) — mark price (frozen: delisted)",5394 "ts": 1794953725593,5395 "stale": false,5396 "unit": "valuation_usd_billions",5397 "unitLabel": "USD billions of company valuation (historical)",5398 "priceKind": "frozen mark"5399 },5400 "contractMarketValue": {5401 "value": null,5402 "formula": null,5403 "reason": "delisted market: the frozen price is not the value of a contract that can be held",5404 "source": null,5405 "ts": null5406 },5407 "notionalExposure": {5408 "value": null,5409 "formula": null,5410 "reason": "delisted market: the frozen price is not the value of a contract that can be held",5411 "position": {5412 "side": "long",5413 "size": "1"5414 },5415 "hypothetical": true,5416 "ts": null5417 },5418 "impliedValuation": {5419 "value": null,5420 "formula": null,5421 "formulaId": null,5422 "formulaSource": {5423 "url": "https://docs.ventuals.com/perp-specifications/private-companies",5424 "quote": "The price of the perp contract is the company valuation divided by 1 billion.",5425 "readAt": "2026-11-15"5426 },5427 "asOf": null,5428 "label": null,5429 "reason": "delisted market: the price is frozen at its last value of June 2026 and is not a current price — no valuation is derived from it",5430 "reasonCode": "delisted_frozen"5431 },5432 "lastPrivateValuation": {5433 "value": "965000000000",5434 "kind": "primary_round",5435 "detail": "Series H, $65B raised, post-money",5436 "date": "2026-05-28",5437 "sourceUrl": "https://www.anthropic.com/news/series-h",5438 "confidence": "high"5439 },5440 "lastPrivateValuationReason": null,5441 "premiumDiscount": {5442 "premiumBps": null,5443 "reason": "delisted market: the price is frozen at its last value of June 2026 and is not a current price — no valuation is derived from it",5444 "caveat": null5445 },5446 "caveats": [5447 {5448 "code": "synthetic",5449 "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"5450 }5451 ]5452 },5453 "tradable": false,5454 "notTradable": {5455 "code": "builder_dex_read_only",5456 "reasons": [5457 "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"5458 ]5459 },5460 "error": null5461 }5462 ],5463 "references": [5464 {5465 "company": "anthropic",5466 "valueUsd": "965000000000",5467 "kind": "primary_round",5468 "detail": "Series H, $65B raised, post-money",5469 "date": "2026-05-28",5470 "sourceUrl": "https://www.anthropic.com/news/series-h",5471 "confidence": "high",5472 "postMoney": true5473 }5474 ],5475 "lastPrivateValuation": {5476 "value": "965000000000",5477 "kind": "primary_round",5478 "detail": "Series H, $65B raised, post-money",5479 "date": "2026-05-28",5480 "sourceUrl": "https://www.anthropic.com/news/series-h",5481 "confidence": "high"5482 },5483 "divergence": [5484 {5485 "unit": "usd_per_share",5486 "unitLabel": "USD per 1 share (share class not specified by the operator)",5487 "contracts": [5488 {5489 "id": "hyperliquid:para:ANTH",5490 "price": "96.26",5491 "ts": 17949537248435492 }5493 ],5494 "spreadBps": "7.58",5495 "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"5496 }5497 ],5498 "merged": null,5499 "mergedReason": "contracts of different venues are different instruments: no average, no blended price, no cross-fill",5500 "venues": [5501 {5502 "venue": "hyperliquid",5503 "name": "Hyperliquid (builder-deployed dexes)",5504 "status": "ok",5505 "error": null,5506 "ts": 1794953723863,5507 "instruments": 55508 }5509 ],5510 "notice": {5511 "tradable": false,5512 "code": "private_markets_display_only",5513 "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"5514 },5515 "position": {5516 "side": "long",5517 "size": "1"5518 },5519 "ts": 1794953725812,5520 "source": "venue"5521 }5522 }5523 }5524 },5525 "400": {5526 "description": "The request is not valid: `bad_request`",5527 "content": {5528 "application/json": {5529 "schema": {5530 "$ref": "#/components/schemas/Error"5531 }5532 }5533 }5534 },5535 "401": {5536 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",5537 "content": {5538 "application/json": {5539 "schema": {5540 "$ref": "#/components/schemas/Error"5541 }5542 }5543 }5544 },5545 "403": {5546 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",5547 "content": {5548 "application/json": {5549 "schema": {5550 "$ref": "#/components/schemas/Error"5551 }5552 }5553 }5554 },5555 "404": {5556 "description": "The object named by the request does not exist: `unknown_company`",5557 "content": {5558 "application/json": {5559 "schema": {5560 "$ref": "#/components/schemas/Error"5561 }5562 }5563 }5564 },5565 "429": {5566 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",5567 "content": {5568 "application/json": {5569 "schema": {5570 "$ref": "#/components/schemas/Error"5571 }5572 }5573 }5574 },5575 "500": {5576 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",5577 "content": {5578 "application/json": {5579 "schema": {5580 "$ref": "#/components/schemas/Error"5581 }5582 }5583 }5584 },5585 "503": {5586 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",5587 "content": {5588 "application/json": {5589 "schema": {5590 "$ref": "#/components/schemas/Error"5591 }5592 }5593 }5594 }5595 }5596 }5597 },5598 "/api/v1/trading/private-markets/{id}": {5599 "get": {5600 "operationId": "getPrivateMarket",5601 "tags": [5602 "Markets"5603 ],5604 "summary": "One private-company contract: definition, valuation breakdown, candles, top of book",5605 "description": "One contract (`id` from GET /private-markets): what it is (nature, unit, settlement, oracle), its market figures each with source, time and `stale`, the valuation breakdown for a hypothetical position (`size`, `side`), the top of the book and candles (`interval`, `limit`). An instrument that exists and is not a private-company contract answers 404 `not_a_private_market`. Display only.",5606 "security": [5607 {5608 "bearerKey": [5609 "markets:read"5610 ]5611 }5612 ],5613 "x-spw-scope": "markets:read",5614 "x-spw-implemented": true,5615 "x-spw-errors": [5616 {5617 "status": 400,5618 "code": "bad_request"5619 },5620 {5621 "status": 401,5622 "code": "unauthenticated"5623 },5624 {5625 "status": 403,5626 "code": "insufficient_scope"5627 },5628 {5629 "status": 403,5630 "code": "ip_not_allowed"5631 },5632 {5633 "status": 403,5634 "code": "mixed_credentials"5635 },5636 {5637 "status": 403,5638 "code": "restricted"5639 },5640 {5641 "status": 404,5642 "code": "not_a_private_market"5643 },5644 {5645 "status": 404,5646 "code": "unknown_private_market"5647 },5648 {5649 "status": 429,5650 "code": "auth_throttled"5651 },5652 {5653 "status": 429,5654 "code": "rate_limited"5655 },5656 {5657 "status": 500,5658 "code": "internal"5659 },5660 {5661 "status": 503,5662 "code": "venue_rate_limited"5663 },5664 {5665 "status": 503,5666 "code": "venue_timeout"5667 },5668 {5669 "status": 503,5670 "code": "venue_unavailable"5671 }5672 ],5673 "x-spw-example-recorded": true,5674 "x-codeSamples": [5675 {5676 "lang": "Shell",5677 "label": "curl",5678 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/private-markets/hyperliquid:io:ANTH?interval=1d&limit=3\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""5679 },5680 {5681 "lang": "TypeScript",5682 "label": "TypeScript",5683 "source": "const pm = await client.getPrivateMarket('hyperliquid:io:ANTH', { interval: '1d', limit: 3 });"5684 },5685 {5686 "lang": "Python",5687 "label": "Python",5688 "source": "pm = client.get_private_market(\"hyperliquid:io:ANTH\", interval=\"1d\", limit=3)"5689 }5690 ],5691 "parameters": [5692 {5693 "name": "id",5694 "in": "path",5695 "required": true,5696 "description": "`venue:symbol`, e.g. `hyperliquid:io:ANTH`, `edgex:ANTHROPICUSDC`",5697 "schema": {5698 "type": "string",5699 "minLength": 3,5700 "maxLength": 120,5701 "pattern": "^[a-z]+:[A-Za-z0-9:._-]+$"5702 },5703 "example": "hyperliquid:io:ANTH"5704 },5705 {5706 "name": "size",5707 "in": "query",5708 "required": false,5709 "description": "hypothetical position size, contracts (default 1)",5710 "schema": {5711 "type": "string",5712 "pattern": "^(0|[1-9]\\d{0,11})(\\.\\d{1,8})?$"5713 }5714 },5715 {5716 "name": "side",5717 "in": "query",5718 "required": false,5719 "description": "side of the hypothetical position (default long)",5720 "schema": {5721 "type": "string",5722 "enum": [5723 "long",5724 "short"5725 ]5726 }5727 },5728 {5729 "name": "interval",5730 "in": "query",5731 "required": false,5732 "description": "candle length",5733 "schema": {5734 "type": "string",5735 "enum": [5736 "1h",5737 "1d"5738 ]5739 },5740 "example": "1d"5741 },5742 {5743 "name": "limit",5744 "in": "query",5745 "required": false,5746 "description": "candles returned at most",5747 "schema": {5748 "type": "integer",5749 "minimum": 1,5750 "maximum": 5005751 },5752 "example": 35753 }5754 ],5755 "responses": {5756 "200": {5757 "description": "OK (the example is a recorded answer)",5758 "content": {5759 "application/json": {5760 "schema": {5761 "type": "object",5762 "properties": {5763 "market": {5764 "type": "object",5765 "properties": {5766 "id": {5767 "type": "string"5768 },5769 "venue": {5770 "type": "string"5771 },5772 "platform": {5773 "type": "string"5774 },5775 "symbol": {5776 "type": "string"5777 },5778 "company": {5779 "anyOf": [5780 {5781 "type": "object",5782 "properties": {5783 "slug": {5784 "type": "string"5785 },5786 "name": {5787 "type": "string"5788 }5789 },5790 "required": [5791 "slug",5792 "name"5793 ],5794 "additionalProperties": false5795 },5796 {5797 "type": "null"5798 }5799 ]5800 },5801 "status": {5802 "type": "string",5803 "enum": [5804 "live",5805 "delisted",5806 "halted",5807 "reduce_only"5808 ]5809 },5810 "review": {5811 "type": "object",5812 "properties": {5813 "state": {5814 "type": "string",5815 "enum": [5816 "reviewed",5817 "under_review",5818 "not_reviewed"5819 ]5820 },5821 "reasons": {5822 "type": "array",5823 "items": {5824 "type": "string"5825 }5826 }5827 },5828 "required": [5829 "state",5830 "reasons"5831 ],5832 "additionalProperties": {}5833 },5834 "contract": {5835 "type": "object",5836 "properties": {5837 "nature": {5838 "type": "string"5839 },5840 "unit": {5841 "type": "object",5842 "properties": {5843 "kind": {5844 "type": "string",5845 "enum": [5846 "usd_per_share",5847 "valuation_usd_billions",5848 "unknown"5849 ]5850 },5851 "label": {5852 "type": "string"5853 }5854 },5855 "required": [5856 "kind",5857 "label"5858 ],5859 "additionalProperties": false5860 },5861 "quoteCurrency": {5862 "type": "string"5863 },5864 "settlement": {5865 "type": "string"5866 },5867 "oracle": {5868 "type": "string"5869 },5870 "liquidation": {5871 "type": "string"5872 }5873 },5874 "required": [5875 "nature",5876 "unit",5877 "quoteCurrency",5878 "settlement",5879 "oracle",5880 "liquidation"5881 ],5882 "additionalProperties": {}5883 },5884 "market": {5885 "type": "object",5886 "properties": {5887 "price": {5888 "type": "object",5889 "properties": {5890 "value": {5891 "anyOf": [5892 {5893 "type": "string",5894 "description": "decimal number as a string (never a float)"5895 },5896 {5897 "type": "null"5898 }5899 ]5900 },5901 "source": {5902 "type": "string"5903 },5904 "ts": {5905 "anyOf": [5906 {5907 "type": "integer",5908 "minimum": -9007199254740991,5909 "maximum": 9007199254740991,5910 "description": "milliseconds since the Unix epoch"5911 },5912 {5913 "type": "null"5914 }5915 ]5916 },5917 "stale": {5918 "type": "boolean"5919 }5920 },5921 "required": [5922 "value",5923 "source",5924 "ts",5925 "stale"5926 ],5927 "additionalProperties": false,5928 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"5929 },5930 "funding": {5931 "type": "object",5932 "properties": {5933 "value": {5934 "anyOf": [5935 {5936 "type": "string",5937 "description": "decimal number as a string (never a float)"5938 },5939 {5940 "type": "null"5941 }5942 ]5943 },5944 "source": {5945 "type": "string"5946 },5947 "ts": {5948 "anyOf": [5949 {5950 "type": "integer",5951 "minimum": -9007199254740991,5952 "maximum": 9007199254740991,5953 "description": "milliseconds since the Unix epoch"5954 },5955 {5956 "type": "null"5957 }5958 ]5959 },5960 "stale": {5961 "type": "boolean"5962 },5963 "intervalSec": {5964 "anyOf": [5965 {5966 "type": "integer",5967 "minimum": -9007199254740991,5968 "maximum": 90071992547409915969 },5970 {5971 "type": "null"5972 }5973 ]5974 }5975 },5976 "required": [5977 "value",5978 "source",5979 "ts",5980 "stale",5981 "intervalSec"5982 ],5983 "additionalProperties": false5984 },5985 "openInterest": {5986 "type": "object",5987 "properties": {5988 "value": {5989 "anyOf": [5990 {5991 "type": "string",5992 "description": "decimal number as a string (never a float)"5993 },5994 {5995 "type": "null"5996 }5997 ]5998 },5999 "source": {6000 "type": "string"6001 },6002 "ts": {6003 "anyOf": [6004 {6005 "type": "integer",6006 "minimum": -9007199254740991,6007 "maximum": 9007199254740991,6008 "description": "milliseconds since the Unix epoch"6009 },6010 {6011 "type": "null"6012 }6013 ]6014 },6015 "stale": {6016 "type": "boolean"6017 }6018 },6019 "required": [6020 "value",6021 "source",6022 "ts",6023 "stale"6024 ],6025 "additionalProperties": false,6026 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"6027 },6028 "volume24h": {6029 "type": "object",6030 "properties": {6031 "value": {6032 "anyOf": [6033 {6034 "type": "string",6035 "description": "decimal number as a string (never a float)"6036 },6037 {6038 "type": "null"6039 }6040 ]6041 },6042 "source": {6043 "type": "string"6044 },6045 "ts": {6046 "anyOf": [6047 {6048 "type": "integer",6049 "minimum": -9007199254740991,6050 "maximum": 9007199254740991,6051 "description": "milliseconds since the Unix epoch"6052 },6053 {6054 "type": "null"6055 }6056 ]6057 },6058 "stale": {6059 "type": "boolean"6060 }6061 },6062 "required": [6063 "value",6064 "source",6065 "ts",6066 "stale"6067 ],6068 "additionalProperties": false,6069 "description": "one figure with where it comes from, when it was read, and whether it is older than its freshness bound"6070 }6071 },6072 "required": [6073 "price",6074 "funding",6075 "openInterest",6076 "volume24h"6077 ],6078 "additionalProperties": {}6079 },6080 "valuation": {6081 "type": "object",6082 "properties": {6083 "syntheticPrice": {6084 "type": "object",6085 "properties": {6086 "value": {6087 "anyOf": [6088 {6089 "type": "string",6090 "description": "decimal number as a string (never a float)"6091 },6092 {6093 "type": "null"6094 }6095 ]6096 }6097 },6098 "required": [6099 "value"6100 ],6101 "additionalProperties": {}6102 },6103 "contractMarketValue": {6104 "type": "object",6105 "properties": {6106 "value": {6107 "anyOf": [6108 {6109 "type": "string",6110 "description": "decimal number as a string (never a float)"6111 },6112 {6113 "type": "null"6114 }6115 ]6116 },6117 "reason": {6118 "type": [6119 "string",6120 "null"6121 ]6122 }6123 },6124 "required": [6125 "value",6126 "reason"6127 ],6128 "additionalProperties": {}6129 },6130 "notionalExposure": {6131 "type": "object",6132 "properties": {6133 "value": {6134 "anyOf": [6135 {6136 "type": "string",6137 "description": "decimal number as a string (never a float)"6138 },6139 {6140 "type": "null"6141 }6142 ]6143 },6144 "hypothetical": {6145 "type": "boolean",6146 "const": true6147 }6148 },6149 "required": [6150 "value",6151 "hypothetical"6152 ],6153 "additionalProperties": {}6154 },6155 "impliedValuation": {6156 "type": "object",6157 "properties": {6158 "value": {6159 "anyOf": [6160 {6161 "type": "string",6162 "description": "decimal number as a string (never a float)"6163 },6164 {6165 "type": "null"6166 }6167 ]6168 },6169 "formula": {6170 "type": [6171 "string",6172 "null"6173 ]6174 },6175 "reason": {6176 "type": [6177 "string",6178 "null"6179 ]6180 },6181 "reasonCode": {6182 "type": [6183 "string",6184 "null"6185 ]6186 }6187 },6188 "required": [6189 "value",6190 "formula",6191 "reason",6192 "reasonCode"6193 ],6194 "additionalProperties": {},6195 "description": "null + reason unless the reviewed definition gives the formula"6196 },6197 "lastPrivateValuation": {6198 "anyOf": [6199 {6200 "type": "object",6201 "properties": {6202 "value": {6203 "type": "string",6204 "description": "decimal number as a string (never a float)"6205 },6206 "kind": {6207 "type": "string"6208 },6209 "date": {6210 "type": "string"6211 },6212 "sourceUrl": {6213 "type": "string"6214 }6215 },6216 "required": [6217 "value",6218 "kind",6219 "date",6220 "sourceUrl"6221 ],6222 "additionalProperties": {}6223 },6224 {6225 "type": "null"6226 }6227 ]6228 },6229 "premiumDiscount": {6230 "type": "object",6231 "properties": {6232 "premiumBps": {6233 "anyOf": [6234 {6235 "type": "string",6236 "description": "decimal number as a string (never a float)"6237 },6238 {6239 "type": "null"6240 }6241 ]6242 }6243 },6244 "required": [6245 "premiumBps"6246 ],6247 "additionalProperties": {}6248 },6249 "caveats": {6250 "type": "array",6251 "items": {6252 "type": "object",6253 "properties": {6254 "code": {6255 "type": "string"6256 },6257 "text": {6258 "type": "string"6259 }6260 },6261 "required": [6262 "code",6263 "text"6264 ],6265 "additionalProperties": {}6266 }6267 }6268 },6269 "required": [6270 "syntheticPrice",6271 "contractMarketValue",6272 "notionalExposure",6273 "impliedValuation",6274 "lastPrivateValuation",6275 "premiumDiscount",6276 "caveats"6277 ],6278 "additionalProperties": {}6279 },6280 "tradable": {6281 "type": "boolean",6282 "const": false6283 },6284 "notTradable": {6285 "type": "object",6286 "properties": {6287 "code": {6288 "type": "string"6289 },6290 "reasons": {6291 "type": "array",6292 "items": {6293 "type": "string"6294 }6295 }6296 },6297 "required": [6298 "code",6299 "reasons"6300 ],6301 "additionalProperties": false6302 },6303 "error": {6304 "type": [6305 "string",6306 "null"6307 ]6308 }6309 },6310 "required": [6311 "id",6312 "venue",6313 "platform",6314 "symbol",6315 "company",6316 "status",6317 "review",6318 "contract",6319 "market",6320 "valuation",6321 "tradable",6322 "notTradable",6323 "error"6324 ],6325 "additionalProperties": {}6326 },6327 "book": {6328 "type": "object",6329 "properties": {},6330 "additionalProperties": {}6331 },6332 "candles": {6333 "type": "object",6334 "properties": {},6335 "additionalProperties": {}6336 },6337 "references": {6338 "type": "array",6339 "items": {6340 "type": "object",6341 "properties": {6342 "kind": {6343 "type": "string"6344 },6345 "date": {6346 "type": "string"6347 },6348 "sourceUrl": {6349 "type": "string"6350 }6351 },6352 "required": [6353 "kind",6354 "date",6355 "sourceUrl"6356 ],6357 "additionalProperties": {}6358 }6359 },6360 "ts": {6361 "type": "integer",6362 "minimum": -9007199254740991,6363 "maximum": 9007199254740991,6364 "description": "milliseconds since the Unix epoch"6365 }6366 },6367 "required": [6368 "market",6369 "book",6370 "candles",6371 "references",6372 "ts"6373 ],6374 "additionalProperties": {}6375 },6376 "example": {6377 "market": {6378 "id": "hyperliquid:io:ANTH",6379 "venue": "hyperliquid",6380 "platform": "Hyperliquid · EntropyIO (dex io)",6381 "operator": "EntropyIO",6382 "symbol": "io:ANTH",6383 "company": {6384 "slug": "anthropic",6385 "name": "Anthropic, PBC"6386 },6387 "status": "live",6388 "review": {6389 "state": "reviewed",6390 "reasons": [],6391 "reviewedAt": "2026-11-15",6392 "validUntil": "2026-11-18T00:00:00Z",6393 "fingerprintChecked": true6394 },6395 "contract": {6396 "nature": "cash-settled perpetual quoted in market cap, pure synthetic, no ownership",6397 "unit": {6398 "kind": "valuation_usd_billions",6399 "label": "USD billions of fully diluted company valuation (1.00 = $1B)"6400 },6401 "quoteCurrency": "USD",6402 "collateral": "USDC",6403 "underlying": "Anthropic, PBC",6404 "contractSize": "1 contract = 1 unit of ANTH; smallest size 0.001",6405 "multiplier": {6406 "value": "1",6407 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)"6408 },6409 "settlement": "If unlisted at 18 Aug 2028: cash-settled to the 6-month trailing TWAP of the mark. Early-settlement notice: 30-day TWAP. M&A: the confirmed deal market cap, else 30-day TWAP.",6410 "ipoConversion": "Stays a market-cap perpetual: \"The oracle switches to Share price × Fully diluted share count ÷ 1,000,000,000 at the first official opening trade.\" The share count is fixed once fr…",6411 "oracle": "Blend of an internal price (5-minute-half-life EMA of the book mid, weight up to 0.95 by executable depth) and an undisclosed aggregate of external sources (\"other derivative instr…",6412 "liquidation": "Hyperliquid margining of the builder dex: liquidation when account or isolated-position equity falls below the maintenance margin (half of the initial margin at maximum leverage); …",6413 "maxLeverage": "15",6414 "margin": "cross_allowed",6415 "lotSize": "0.001",6416 "szDecimals": 3,6417 "fundingIntervalSec": 3600,6418 "assetId": 200001,6419 "dex": "io",6420 "oiCapUsd": "275000000",6421 "fundingMultiplier": "0.125",6422 "onChainDescription": "",6423 "unconfirmedConvention": null,6424 "sources": [6425 "https://docs.entropy.io/market-types/pre-ipo-perpetuals"6426 ]6427 },6428 "market": {6429 "price": {6430 "value": "1683.9",6431 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",6432 "ts": 1794953724740,6433 "stale": false6434 },6435 "oracle": {6436 "value": "1684",6437 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — oracle price",6438 "ts": 1794953724740,6439 "stale": false6440 },6441 "mid": {6442 "value": "1680.6",6443 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — book mid",6444 "ts": 1794953724740,6445 "stale": false6446 },6447 "funding": {6448 "value": "-0.0000113686",6449 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — funding rate per interval",6450 "ts": 1794953724740,6451 "stale": false,6452 "intervalSec": 36006453 },6454 "openInterest": {6455 "value": "117475.832",6456 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — open interest, contracts",6457 "ts": 1794953724740,6458 "stale": false6459 },6460 "openInterestUsd": {6461 "value": "197817553.5048",6462 "source": "wallet arithmetic: open interest × mark × contract multiplier (not a venue field)",6463 "ts": 1794953724740,6464 "stale": false6465 },6466 "volume24h": {6467 "value": "34445966.2849999964",6468 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h notional volume, USD",6469 "ts": 1794953724740,6470 "stale": false6471 },6472 "volumeBase24h": {6473 "value": "20388.063",6474 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — 24 h volume, contracts",6475 "ts": 1794953724740,6476 "stale": false6477 },6478 "frozen": false6479 },6480 "valuation": {6481 "syntheticPrice": {6482 "value": "1683.9",6483 "source": "Hyperliquid info metaAndAssetCtxs (dex io) — mark price",6484 "ts": 1794953724740,6485 "stale": false,6486 "unit": "valuation_usd_billions",6487 "unitLabel": "USD billions of fully diluted company valuation (1.00 = $1B)",6488 "priceKind": "mark"6489 },6490 "contractMarketValue": {6491 "value": "1683.9",6492 "formula": "contract value = price × 1 (contract size defined by the venue: Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBase…",6493 "reason": null,6494 "source": "Hyperliquid: linear contract of one unit — notional = size × price (position value = szi × mark; dayNtlVlm ÷ dayBaseVlm = price, checked on the live contexts of 2026-11-16)",6495 "ts": 17949537247406496 },6497 "notionalExposure": {6498 "value": "1683.9",6499 "formula": "size × contract value, negative for a short",6500 "reason": null,6501 "position": {6502 "side": "long",6503 "size": "1"6504 },6505 "hypothetical": true,6506 "ts": 17949537247406507 },6508 "impliedValuation": {6509 "value": "1683900000000",6510 "formula": "implied fully diluted valuation (USD) = price × 1 000 000 000",6511 "formulaId": "price_x_1e9",6512 "formulaSource": {6513 "url": "https://docs.entropy.io/market-types/pre-ipo-perpetuals",6514 "quote": "pre-IPO perpetuals are quoted in market cap: a price of $1 represents $1B of the company's fully diluted valuation.",6515 "readAt": "2026-11-15"6516 },6517 "asOf": 1794953724740,6518 "label": "market-implied, from the price of a derivative on Hyperliquid · EntropyIO (dex io) — not a company figure",6519 "reason": null,6520 "reasonCode": null6521 },6522 "lastPrivateValuation": {6523 "value": "965000000000",6524 "kind": "primary_round",6525 "detail": "Series H, $65B raised, post-money",6526 "date": "2026-05-28",6527 "sourceUrl": "https://www.anthropic.com/news/series-h",6528 "confidence": "high"6529 },6530 "lastPrivateValuationReason": null,6531 "premiumDiscount": {6532 "premiumBps": "7449.7409",6533 "reason": null,6534 "caveat": "the reference is a priced round post money dated 2026-05-28; the contract price is dated 2026-11-17. The two figures are of different kinds and dates"6535 },6536 "caveats": [6537 {6538 "code": "synthetic",6539 "text": "a synthetic price is the price of a derivative contract: it gives no claim on shares and can trade far from any share transaction"6540 }6541 ]6542 },6543 "tradable": false,6544 "notTradable": {6545 "code": "builder_dex_read_only",6546 "reasons": [6547 "Builder-deployed (HIP-3) Hyperliquid markets are served for market data only: the wallet's trading path covers the validator-operated dex alone (pinned asset table, signer policy),…"6548 ]6549 },6550 "error": null6551 },6552 "book": {6553 "bids": [6554 [6555 "1680.4"6556 ],6557 [6558 "1680.2"6559 ],6560 [6561 "1680.1"6562 ]6563 ],6564 "asks": [6565 [6566 "1680.8"6567 ],6568 [6569 "1681"6570 ],6571 [6572 "1681.1"6573 ]6574 ],6575 "ts": 1794953724827,6576 "stale": false,6577 "source": "Hyperliquid info l2Book"6578 },6579 "candles": {6580 "interval": "1d",6581 "candles": [6582 {6583 "ts": 1794700800000,6584 "open": "1779.8",6585 "high": "1785.7",6586 "low": "1752.3",6587 "close": "1777.2",6588 "volume": "4532.974"6589 }6590 ],6591 "ts": 1794953725389,6592 "stale": false,6593 "source": "Hyperliquid info candleSnapshot"6594 },6595 "references": [6596 {6597 "company": "anthropic",6598 "valueUsd": "965000000000",6599 "kind": "primary_round",6600 "detail": "Series H, $65B raised, post-money",6601 "date": "2026-05-28",6602 "sourceUrl": "https://www.anthropic.com/news/series-h",6603 "confidence": "high",6604 "postMoney": true6605 }6606 ],6607 "company": {6608 "slug": "anthropic",6609 "name": "Anthropic, PBC",6610 "note": "IPO reported for pricing on 18 Nov 2026 and first trade on 19 Nov 2026 (press; the SEC filing states no date). Every Anthropic contract changes methodology, unit or oracle around that date.",6611 "contracts": [6612 "hyperliquid:io:ANTH"6613 ],6614 "lastPrivateValuation": {6615 "value": "965000000000",6616 "kind": "primary_round",6617 "detail": "Series H, $65B raised, post-money",6618 "date": "2026-05-28",6619 "sourceUrl": "https://www.anthropic.com/news/series-h",6620 "confidence": "high"6621 },6622 "divergence": [6623 {6624 "unit": "usd_per_share",6625 "unitLabel": "USD per 1 share (share class not specified by the operator)",6626 "contracts": [6627 {6628 "id": "hyperliquid:para:ANTH",6629 "price": "96.26",6630 "ts": 17949537248436631 }6632 ],6633 "spreadBps": "7.58",6634 "note": "spread between the highest and the lowest mark of contracts quoted in the same unit; different contracts with different settlement rules — shown side by side, never averaged"6635 }6636 ]6637 },6638 "sameCompany": [6639 {6640 "id": "hyperliquid:para:ANTH",6641 "platform": "Hyperliquid · Paragon (dex para)",6642 "price": {6643 "value": "96.26",6644 "source": "Hyperliquid info metaAndAssetCtxs (dex para) — mark price",6645 "ts": 1794953724843,6646 "stale": false6647 },6648 "unit": {6649 "kind": "usd_per_share",6650 "label": "USD per 1 share (share class not specified by the operator)"6651 },6652 "review": "reviewed"6653 }6654 ],6655 "notice": {6656 "tradable": false,6657 "code": "private_markets_display_only",6658 "text": "Displayed for information only — not tradable from this wallet. These are synthetic derivative contracts: they give no claim on any share. Trading is disabled for two reasons: juri…"6659 },6660 "position": {6661 "side": "long",6662 "size": "1"6663 },6664 "ts": 1794953725389,6665 "source": "venue"6666 }6667 }6668 }6669 },6670 "400": {6671 "description": "The request is not valid: `bad_request`",6672 "content": {6673 "application/json": {6674 "schema": {6675 "$ref": "#/components/schemas/Error"6676 }6677 }6678 }6679 },6680 "401": {6681 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",6682 "content": {6683 "application/json": {6684 "schema": {6685 "$ref": "#/components/schemas/Error"6686 }6687 }6688 }6689 },6690 "403": {6691 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",6692 "content": {6693 "application/json": {6694 "schema": {6695 "$ref": "#/components/schemas/Error"6696 }6697 }6698 }6699 },6700 "404": {6701 "description": "The object named by the request does not exist: `not_a_private_market`, `unknown_private_market`",6702 "content": {6703 "application/json": {6704 "schema": {6705 "$ref": "#/components/schemas/Error"6706 }6707 }6708 }6709 },6710 "429": {6711 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",6712 "content": {6713 "application/json": {6714 "schema": {6715 "$ref": "#/components/schemas/Error"6716 }6717 }6718 }6719 },6720 "500": {6721 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",6722 "content": {6723 "application/json": {6724 "schema": {6725 "$ref": "#/components/schemas/Error"6726 }6727 }6728 }6729 },6730 "503": {6731 "description": "A backing service is unavailable; nothing was done: `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",6732 "content": {6733 "application/json": {6734 "schema": {6735 "$ref": "#/components/schemas/Error"6736 }6737 }6738 }6739 }6740 }6741 }6742 },6743 "/api/v1/trading/portfolio": {6744 "get": {6745 "operationId": "getPortfolio",6746 "tags": [6747 "Portfolio"6748 ],6749 "summary": "Wallet value and derivative accounts, per mode",6750 "description": "Wallet balances valued in USD, then every derivatives account with its `mode`. Every amount is a decimal string. Paper and live are never added together.",6751 "security": [6752 {6753 "bearerKey": [6754 "wallet:read"6755 ]6756 }6757 ],6758 "x-spw-scope": "wallet:read",6759 "x-spw-implemented": true,6760 "x-spw-errors": [6761 {6762 "status": 401,6763 "code": "unauthenticated"6764 },6765 {6766 "status": 403,6767 "code": "insufficient_scope"6768 },6769 {6770 "status": 403,6771 "code": "ip_not_allowed"6772 },6773 {6774 "status": 403,6775 "code": "mixed_credentials"6776 },6777 {6778 "status": 429,6779 "code": "auth_throttled"6780 },6781 {6782 "status": 429,6783 "code": "rate_limited"6784 },6785 {6786 "status": 500,6787 "code": "internal"6788 },6789 {6790 "status": 503,6791 "code": "service_unavailable"6792 },6793 {6794 "status": 503,6795 "code": "signer_unreachable"6796 }6797 ],6798 "x-spw-example-recorded": true,6799 "x-spw-example-note": "Cut to one balance. The test wallet is empty; `totals` are three separate figures, never summed.",6800 "x-codeSamples": [6801 {6802 "lang": "Shell",6803 "label": "curl",6804 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/portfolio\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""6805 },6806 {6807 "lang": "TypeScript",6808 "label": "TypeScript",6809 "source": "const portfolio = await client.getPortfolio();"6810 },6811 {6812 "lang": "Python",6813 "label": "Python",6814 "source": "portfolio = client.get_portfolio()"6815 }6816 ],6817 "parameters": [],6818 "responses": {6819 "200": {6820 "description": "OK (the example is a recorded answer)",6821 "content": {6822 "application/json": {6823 "schema": {6824 "type": "object",6825 "properties": {6826 "asOf": {6827 "type": "string"6828 },6829 "wallet": {6830 "type": "object",6831 "properties": {6832 "valueUsd": {6833 "anyOf": [6834 {6835 "type": "string",6836 "description": "decimal number as a string (never a float)"6837 },6838 {6839 "type": "null"6840 }6841 ],6842 "description": "USD, a decimal string; null when the price feed is unavailable"6843 },6844 "priced": {6845 "type": "integer",6846 "minimum": -9007199254740991,6847 "maximum": 90071992547409916848 },6849 "unpriced": {6850 "type": "integer",6851 "minimum": -9007199254740991,6852 "maximum": 90071992547409916853 },6854 "pricesAsOf": {6855 "type": [6856 "string",6857 "null"6858 ]6859 },6860 "balances": {6861 "type": "array",6862 "items": {6863 "type": "object",6864 "properties": {6865 "network": {6866 "type": "string"6867 },6868 "symbol": {6869 "type": "string"6870 },6871 "display": {6872 "type": [6873 "string",6874 "null"6875 ]6876 },6877 "valueUsd": {6878 "anyOf": [6879 {6880 "type": "string",6881 "description": "decimal number as a string (never a float)"6882 },6883 {6884 "type": "null"6885 }6886 ],6887 "description": "USD, a decimal string; null when the asset has no price or no readable balance"6888 }6889 },6890 "required": [6891 "network",6892 "symbol",6893 "display",6894 "valueUsd"6895 ],6896 "additionalProperties": {}6897 }6898 }6899 },6900 "required": [6901 "valueUsd",6902 "priced",6903 "unpriced",6904 "pricesAsOf",6905 "balances"6906 ],6907 "additionalProperties": false6908 },6909 "accounts": {6910 "type": "array",6911 "items": {6912 "type": "object",6913 "properties": {6914 "mode": {6915 "type": "string",6916 "enum": [6917 "paper",6918 "live"6919 ],6920 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."6921 },6922 "venue": {6923 "type": "string"6924 },6925 "accountId": {6926 "type": "string"6927 },6928 "equity": {6929 "anyOf": [6930 {6931 "type": "string",6932 "description": "decimal number as a string (never a float)"6933 },6934 {6935 "type": "null"6936 }6937 ]6938 },6939 "error": {6940 "type": [6941 "string",6942 "null"6943 ]6944 }6945 },6946 "required": [6947 "mode",6948 "venue",6949 "accountId",6950 "equity",6951 "error"6952 ],6953 "additionalProperties": {}6954 }6955 },6956 "totals": {6957 "type": "object",6958 "properties": {6959 "walletUsd": {6960 "anyOf": [6961 {6962 "type": "string",6963 "description": "decimal number as a string (never a float)"6964 },6965 {6966 "type": "null"6967 }6968 ]6969 },6970 "liveVenueEquity": {6971 "anyOf": [6972 {6973 "type": "string",6974 "description": "decimal number as a string (never a float)"6975 },6976 {6977 "type": "null"6978 }6979 ]6980 },6981 "paperEquity": {6982 "anyOf": [6983 {6984 "type": "string",6985 "description": "decimal number as a string (never a float)"6986 },6987 {6988 "type": "null"6989 }6990 ]6991 },6992 "note": {6993 "type": "string",6994 "description": "what the three figures are, in a sentence"6995 }6996 },6997 "required": [6998 "walletUsd",6999 "liveVenueEquity",7000 "paperEquity",7001 "note"7002 ],7003 "additionalProperties": false,7004 "description": "three separate figures; there is no sum across modes"7005 },7006 "halted": {7007 "description": "emergency halt of the signer; null when the signer does not say",7008 "type": [7009 "boolean",7010 "null"7011 ]7012 },7013 "errors": {7014 "type": "array",7015 "items": {7016 "type": "object",7017 "properties": {7018 "source": {7019 "type": "string"7020 },7021 "message": {7022 "type": "string"7023 }7024 },7025 "required": [7026 "source",7027 "message"7028 ],7029 "additionalProperties": false7030 }7031 }7032 },7033 "required": [7034 "asOf",7035 "wallet",7036 "accounts",7037 "totals",7038 "halted",7039 "errors"7040 ],7041 "additionalProperties": false7042 },7043 "example": {7044 "asOf": "2026-11-17T22:15:27.274Z",7045 "wallet": {7046 "valueUsd": "0",7047 "priced": 0,7048 "unpriced": 0,7049 "pricesAsOf": "2026-11-17T22:15:27.274Z",7050 "balances": [7051 {7052 "network": "ethereum",7053 "networkName": "Ethereum",7054 "asset": "native",7055 "symbol": "ETH",7056 "name": "Ether",7057 "decimals": 18,7058 "amount": "0",7059 "display": "0",7060 "error": null,7061 "valueUsd": "0",7062 "priceSource": "coingecko",7063 "priceAt": "2026-11-17T22:14:49.000Z",7064 "priceDivergent": false,7065 "priceDivergenceBps": null7066 }7067 ]7068 },7069 "accounts": [7070 {7071 "mode": "paper",7072 "venue": "hyperliquid",7073 "network": "mainnet",7074 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",7075 "label": "SDK paper",7076 "equity": "10000",7077 "collateral": "10000",7078 "error": null,7079 "source": "paper"7080 }7081 ],7082 "totals": {7083 "walletUsd": "0",7084 "liveVenueEquity": "0",7085 "paperEquity": "10000",7086 "note": "three separate figures: the wallet (on-chain, USD), venue accounts on mainnet (live), paper accounts (simulated). They are never added together; testnet accounts are listed but not summed."7087 },7088 "halted": false,7089 "errors": []7090 }7091 }7092 }7093 },7094 "401": {7095 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",7096 "content": {7097 "application/json": {7098 "schema": {7099 "$ref": "#/components/schemas/Error"7100 }7101 }7102 }7103 },7104 "403": {7105 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",7106 "content": {7107 "application/json": {7108 "schema": {7109 "$ref": "#/components/schemas/Error"7110 }7111 }7112 }7113 },7114 "429": {7115 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",7116 "content": {7117 "application/json": {7118 "schema": {7119 "$ref": "#/components/schemas/Error"7120 }7121 }7122 }7123 },7124 "500": {7125 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",7126 "content": {7127 "application/json": {7128 "schema": {7129 "$ref": "#/components/schemas/Error"7130 }7131 }7132 }7133 },7134 "503": {7135 "description": "A backing service is unavailable; nothing was done: `service_unavailable`, `signer_unreachable`",7136 "content": {7137 "application/json": {7138 "schema": {7139 "$ref": "#/components/schemas/Error"7140 }7141 }7142 }7143 }7144 }7145 }7146 },7147 "/api/v1/trading/balances": {7148 "get": {7149 "operationId": "getBalances",7150 "tags": [7151 "Portfolio"7152 ],7153 "summary": "On-chain balances of the wallet",7154 "description": "One row per asset of the wallet registry, read from the chains now: `amount` is the exact integer of base units as a string, `display` the same in the asset's decimals. A network that cannot be read gives rows with `error` (and an entry in `errors`), never a zero; 503 only when no network answered. Not valued: GET /portfolio adds prices.",7155 "security": [7156 {7157 "bearerKey": [7158 "wallet:read"7159 ]7160 }7161 ],7162 "x-spw-scope": "wallet:read",7163 "x-spw-implemented": true,7164 "x-spw-errors": [7165 {7166 "status": 400,7167 "code": "bad_request"7168 },7169 {7170 "status": 401,7171 "code": "unauthenticated"7172 },7173 {7174 "status": 403,7175 "code": "insufficient_scope"7176 },7177 {7178 "status": 403,7179 "code": "ip_not_allowed"7180 },7181 {7182 "status": 403,7183 "code": "mixed_credentials"7184 },7185 {7186 "status": 403,7187 "code": "restricted"7188 },7189 {7190 "status": 404,7191 "code": "unknown_network"7192 },7193 {7194 "status": 429,7195 "code": "auth_throttled"7196 },7197 {7198 "status": 429,7199 "code": "rate_limited"7200 },7201 {7202 "status": 500,7203 "code": "internal"7204 },7205 {7206 "status": 503,7207 "code": "service_unavailable"7208 },7209 {7210 "status": 503,7211 "code": "signer_unreachable"7212 }7213 ],7214 "x-spw-example-recorded": true,7215 "x-codeSamples": [7216 {7217 "lang": "Shell",7218 "label": "curl",7219 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/balances?network=base\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""7220 },7221 {7222 "lang": "TypeScript",7223 "label": "TypeScript",7224 "source": "const { balances } = await client.getBalances({ network: 'base' });"7225 },7226 {7227 "lang": "Python",7228 "label": "Python",7229 "source": "balances = client.get_balances(network=\"base\").balances"7230 }7231 ],7232 "parameters": [7233 {7234 "name": "network",7235 "in": "query",7236 "required": false,7237 "description": "one network id (e.g. `base`, `arbitrum`, `solana`); default: every network of the wallet",7238 "schema": {7239 "type": "string",7240 "maxLength": 247241 },7242 "example": "base"7243 }7244 ],7245 "responses": {7246 "200": {7247 "description": "OK (the example is a recorded answer)",7248 "content": {7249 "application/json": {7250 "schema": {7251 "type": "object",7252 "properties": {7253 "asOf": {7254 "type": "string"7255 },7256 "balances": {7257 "type": "array",7258 "items": {7259 "type": "object",7260 "properties": {7261 "network": {7262 "type": "string"7263 },7264 "asset": {7265 "type": "string"7266 },7267 "symbol": {7268 "type": "string"7269 },7270 "decimals": {7271 "type": "integer",7272 "minimum": -9007199254740991,7273 "maximum": 90071992547409917274 },7275 "amount": {7276 "type": [7277 "string",7278 "null"7279 ]7280 },7281 "display": {7282 "type": [7283 "string",7284 "null"7285 ]7286 },7287 "error": {7288 "type": [7289 "string",7290 "null"7291 ]7292 }7293 },7294 "required": [7295 "network",7296 "asset",7297 "symbol",7298 "decimals",7299 "amount",7300 "display",7301 "error"7302 ],7303 "additionalProperties": {}7304 }7305 },7306 "errors": {7307 "type": "array",7308 "items": {7309 "type": "object",7310 "properties": {7311 "source": {7312 "type": "string"7313 },7314 "message": {7315 "type": "string"7316 }7317 },7318 "required": [7319 "source",7320 "message"7321 ],7322 "additionalProperties": false7323 }7324 },7325 "halted": {7326 "description": "emergency halt of the signer; null when the signer does not say",7327 "type": [7328 "boolean",7329 "null"7330 ]7331 }7332 },7333 "required": [7334 "asOf",7335 "balances",7336 "errors",7337 "halted"7338 ],7339 "additionalProperties": false7340 },7341 "example": {7342 "asOf": "2026-11-17T22:15:28.199Z",7343 "balances": [7344 {7345 "network": "base",7346 "networkName": "Base",7347 "asset": "native",7348 "symbol": "ETH",7349 "name": "Ether",7350 "decimals": 18,7351 "amount": "0",7352 "display": "0",7353 "error": null7354 },7355 {7356 "network": "base",7357 "networkName": "Base",7358 "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",7359 "symbol": "USDC",7360 "name": "USD Coin",7361 "decimals": 6,7362 "amount": "0",7363 "display": "0",7364 "error": null7365 }7366 ],7367 "errors": [],7368 "halted": false7369 }7370 }7371 }7372 },7373 "400": {7374 "description": "The request is not valid: `bad_request`",7375 "content": {7376 "application/json": {7377 "schema": {7378 "$ref": "#/components/schemas/Error"7379 }7380 }7381 }7382 },7383 "401": {7384 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",7385 "content": {7386 "application/json": {7387 "schema": {7388 "$ref": "#/components/schemas/Error"7389 }7390 }7391 }7392 },7393 "403": {7394 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",7395 "content": {7396 "application/json": {7397 "schema": {7398 "$ref": "#/components/schemas/Error"7399 }7400 }7401 }7402 },7403 "404": {7404 "description": "The object named by the request does not exist: `unknown_network`",7405 "content": {7406 "application/json": {7407 "schema": {7408 "$ref": "#/components/schemas/Error"7409 }7410 }7411 }7412 },7413 "429": {7414 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",7415 "content": {7416 "application/json": {7417 "schema": {7418 "$ref": "#/components/schemas/Error"7419 }7420 }7421 }7422 },7423 "500": {7424 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",7425 "content": {7426 "application/json": {7427 "schema": {7428 "$ref": "#/components/schemas/Error"7429 }7430 }7431 }7432 },7433 "503": {7434 "description": "A backing service is unavailable; nothing was done: `service_unavailable`, `signer_unreachable`",7435 "content": {7436 "application/json": {7437 "schema": {7438 "$ref": "#/components/schemas/Error"7439 }7440 }7441 }7442 }7443 }7444 }7445 },7446 "/api/v1/trading/activity": {7447 "get": {7448 "operationId": "getActivity",7449 "tags": [7450 "Portfolio"7451 ],7452 "summary": "Wallet activity and fills, newest first",7453 "description": "Sends, swaps, bridges, receipts and derivative fills, newest first, in one stable order (time, then id). Paginated: `nextCursor` of a page is the `cursor` of the next; null at the end. An item that appears after the first page was read is not inserted into the pages that follow.",7454 "security": [7455 {7456 "bearerKey": [7457 "wallet:read"7458 ]7459 }7460 ],7461 "x-spw-scope": "wallet:read",7462 "x-spw-implemented": true,7463 "x-spw-errors": [7464 {7465 "status": 400,7466 "code": "bad_request"7467 },7468 {7469 "status": 400,7470 "code": "invalid_cursor"7471 },7472 {7473 "status": 401,7474 "code": "unauthenticated"7475 },7476 {7477 "status": 403,7478 "code": "insufficient_scope"7479 },7480 {7481 "status": 403,7482 "code": "ip_not_allowed"7483 },7484 {7485 "status": 403,7486 "code": "mixed_credentials"7487 },7488 {7489 "status": 429,7490 "code": "auth_throttled"7491 },7492 {7493 "status": 429,7494 "code": "rate_limited"7495 },7496 {7497 "status": 500,7498 "code": "internal"7499 }7500 ],7501 "x-spw-example-recorded": true,7502 "x-codeSamples": [7503 {7504 "lang": "Shell",7505 "label": "curl",7506 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/activity?limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""7507 },7508 {7509 "lang": "TypeScript",7510 "label": "TypeScript",7511 "source": "const page = await client.getActivity({ limit: 2 });\nfor await (const item of client.iterateActivity()) console.log(item.kind, item.at); // every page"7512 },7513 {7514 "lang": "Python",7515 "label": "Python",7516 "source": "page = client.get_activity(limit=2)\nfor item in client.iter_activity(): # every page\n print(item.kind, item.at)"7517 }7518 ],7519 "parameters": [7520 {7521 "name": "limit",7522 "in": "query",7523 "required": false,7524 "description": "rows returned at most",7525 "schema": {7526 "default": 100,7527 "type": "integer",7528 "minimum": 1,7529 "maximum": 5007530 },7531 "example": 27532 },7533 {7534 "name": "cursor",7535 "in": "query",7536 "required": false,7537 "description": "opaque position returned as `nextCursor` by the previous page; send it with the same filters",7538 "schema": {7539 "type": "string",7540 "minLength": 1,7541 "maxLength": 400,7542 "pattern": "^[A-Za-z0-9_-]+$"7543 }7544 }7545 ],7546 "responses": {7547 "200": {7548 "description": "OK (the example is a recorded answer)",7549 "content": {7550 "application/json": {7551 "schema": {7552 "type": "object",7553 "properties": {7554 "items": {7555 "type": "array",7556 "items": {7557 "type": "object",7558 "properties": {7559 "kind": {7560 "type": "string"7561 },7562 "at": {7563 "type": "string"7564 },7565 "mode": {7566 "type": "string",7567 "enum": [7568 "paper",7569 "live"7570 ],7571 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."7572 }7573 },7574 "required": [7575 "kind",7576 "at",7577 "mode"7578 ],7579 "additionalProperties": {}7580 }7581 },7582 "nextCursor": {7583 "description": "pass it as `cursor` to read the next (older) page; null when there is none",7584 "type": [7585 "string",7586 "null"7587 ]7588 }7589 },7590 "required": [7591 "items",7592 "nextCursor"7593 ],7594 "additionalProperties": false7595 },7596 "example": {7597 "items": [7598 {7599 "kind": "fill",7600 "mode": "paper",7601 "at": "2026-11-17T22:15:31.480Z",7602 "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-6",7603 "venue": "hyperliquid",7604 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",7605 "instrument": "hyperliquid:BTC",7606 "side": "sell",7607 "price": "64426",7608 "size": "0.00078",7609 "fee": "0.022613526",7610 "closedPnl": "-0.00468"7611 },7612 {7613 "kind": "fill",7614 "mode": "paper",7615 "at": "2026-11-17T22:15:31.456Z",7616 "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:paper-f-4",7617 "venue": "hyperliquid",7618 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",7619 "instrument": "hyperliquid:BTC",7620 "side": "sell",7621 "price": "64426",7622 "size": "0.00077",7623 "fee": "0.022323609",7624 "closedPnl": "-0.00462"7625 }7626 ],7627 "nextCursor": "WyIxNzk0OTUzNzMxNDU2MDAwIiwiZiIsIjZhMmM4MzUxLWNkNzktNDRlMi1iNzVhLWYzOTI4MGQwZWJjMjpwYXBlci1mLTQiXQ"7628 }7629 }7630 }7631 },7632 "400": {7633 "description": "The request is not valid: `bad_request`, `invalid_cursor`",7634 "content": {7635 "application/json": {7636 "schema": {7637 "$ref": "#/components/schemas/Error"7638 }7639 }7640 }7641 },7642 "401": {7643 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",7644 "content": {7645 "application/json": {7646 "schema": {7647 "$ref": "#/components/schemas/Error"7648 }7649 }7650 }7651 },7652 "403": {7653 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",7654 "content": {7655 "application/json": {7656 "schema": {7657 "$ref": "#/components/schemas/Error"7658 }7659 }7660 }7661 },7662 "429": {7663 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",7664 "content": {7665 "application/json": {7666 "schema": {7667 "$ref": "#/components/schemas/Error"7668 }7669 }7670 }7671 },7672 "500": {7673 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",7674 "content": {7675 "application/json": {7676 "schema": {7677 "$ref": "#/components/schemas/Error"7678 }7679 }7680 }7681 }7682 }7683 }7684 },7685 "/api/v1/trading/nfts": {7686 "get": {7687 "operationId": "listNfts",7688 "tags": [7689 "Nfts"7690 ],7691 "summary": "NFTs of the wallet (what the chain confirmed as held)",7692 "description": "The inventory as last synchronised: Solana (Token Metadata, programmable, Token-2022, Core, compressed through an index) and the EVM networks (ERC-721, ERC-1155). Every row names the source and confidence of its ownership. NFTs carry NO value: `valuation.state` is `unavailable` (never zero, never a floor) and they are not part of GET /portfolio. Paginated: `nextCursor` of a page is the `cursor` of the next.",7693 "security": [7694 {7695 "bearerKey": [7696 "wallet:read"7697 ]7698 }7699 ],7700 "x-spw-scope": "wallet:read",7701 "x-spw-implemented": true,7702 "x-spw-errors": [7703 {7704 "status": 400,7705 "code": "bad_request"7706 },7707 {7708 "status": 400,7709 "code": "invalid_cursor"7710 },7711 {7712 "status": 401,7713 "code": "unauthenticated"7714 },7715 {7716 "status": 403,7717 "code": "insufficient_scope"7718 },7719 {7720 "status": 403,7721 "code": "ip_not_allowed"7722 },7723 {7724 "status": 403,7725 "code": "mixed_credentials"7726 },7727 {7728 "status": 403,7729 "code": "restricted"7730 },7731 {7732 "status": 404,7733 "code": "unknown_network"7734 },7735 {7736 "status": 404,7737 "code": "unknown_nft"7738 },7739 {7740 "status": 429,7741 "code": "auth_throttled"7742 },7743 {7744 "status": 429,7745 "code": "rate_limited"7746 },7747 {7748 "status": 500,7749 "code": "internal"7750 },7751 {7752 "status": 503,7753 "code": "nft_disabled"7754 },7755 {7756 "status": 503,7757 "code": "signer_unreachable"7758 }7759 ],7760 "x-spw-example-recorded": true,7761 "x-spw-example-note": "The test wallet holds no NFT: the list is empty, and `valuation` is always `unavailable`.",7762 "x-codeSamples": [7763 {7764 "lang": "Shell",7765 "label": "curl",7766 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/nfts?limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""7767 },7768 {7769 "lang": "TypeScript",7770 "label": "TypeScript",7771 "source": "const { items, nextCursor } = await client.listNfts({ limit: 2 });"7772 },7773 {7774 "lang": "Python",7775 "label": "Python",7776 "source": "nfts = client.list_nfts(limit=2)"7777 }7778 ],7779 "parameters": [7780 {7781 "name": "network",7782 "in": "query",7783 "required": false,7784 "description": "one network id; default: all",7785 "schema": {7786 "type": "string",7787 "maxLength": 247788 }7789 },7790 {7791 "name": "collection",7792 "in": "query",7793 "required": false,7794 "description": "collection key",7795 "schema": {7796 "type": "string",7797 "maxLength": 2607798 }7799 },7800 {7801 "name": "status",7802 "in": "query",7803 "required": false,7804 "description": "in_wallet: held now; left: was found in the wallet and is no longer held; tracked: added by hand. Default: held, tracked, or left within the last 30 days",7805 "schema": {7806 "type": "string",7807 "enum": [7808 "in_wallet",7809 "left",7810 "tracked"7811 ]7812 }7813 },7814 {7815 "name": "q",7816 "in": "query",7817 "required": false,7818 "description": "case-insensitive text matched on the name, the key or the collection name",7819 "schema": {7820 "type": "string",7821 "maxLength": 807822 }7823 },7824 {7825 "name": "sort",7826 "in": "query",7827 "required": false,7828 "description": "order of the list",7829 "schema": {7830 "default": "recent",7831 "type": "string",7832 "enum": [7833 "recent",7834 "name"7835 ]7836 }7837 },7838 {7839 "name": "spam",7840 "in": "query",7841 "required": false,7842 "description": "items an indexer flags as spam are hidden by default, never deleted",7843 "schema": {7844 "default": "hide",7845 "type": "string",7846 "enum": [7847 "hide",7848 "show",7849 "only"7850 ]7851 }7852 },7853 {7854 "name": "limit",7855 "in": "query",7856 "required": false,7857 "description": "rows returned at most",7858 "schema": {7859 "default": 48,7860 "type": "integer",7861 "minimum": 1,7862 "maximum": 1007863 },7864 "example": 27865 },7866 {7867 "name": "cursor",7868 "in": "query",7869 "required": false,7870 "description": "opaque position returned as `nextCursor` by the previous page; send it with the same filters",7871 "schema": {7872 "type": "string",7873 "minLength": 1,7874 "maxLength": 400,7875 "pattern": "^[A-Za-z0-9_-]+$"7876 }7877 }7878 ],7879 "responses": {7880 "200": {7881 "description": "OK (the example is a recorded answer)",7882 "content": {7883 "application/json": {7884 "schema": {7885 "type": "object",7886 "properties": {7887 "items": {7888 "type": "array",7889 "items": {7890 "type": "object",7891 "properties": {7892 "key": {7893 "type": "string",7894 "description": "`family:network:asset-id` — the id every NFT operation takes"7895 },7896 "network": {7897 "type": "string"7898 },7899 "family": {7900 "type": "string"7901 },7902 "standard": {7903 "type": "string"7904 },7905 "assetId": {7906 "type": "string"7907 },7908 "contractAddress": {7909 "type": [7910 "string",7911 "null"7912 ]7913 },7914 "tokenId": {7915 "description": "decimal string (up to 2^256 − 1), never a number",7916 "type": [7917 "string",7918 "null"7919 ]7920 },7921 "mintAddress": {7922 "type": [7923 "string",7924 "null"7925 ]7926 },7927 "quantity": {7928 "type": "string",7929 "pattern": "^(0|[1-9][0-9]{0,77})$",7930 "description": "exact integer of base units, as a string"7931 },7932 "name": {7933 "description": "declared by the creator — not chain truth",7934 "type": [7935 "string",7936 "null"7937 ]7938 },7939 "onchainName": {7940 "type": [7941 "string",7942 "null"7943 ]7944 },7945 "collection": {7946 "anyOf": [7947 {7948 "type": "object",7949 "properties": {7950 "key": {7951 "type": "string"7952 },7953 "id": {7954 "type": "string"7955 },7956 "name": {7957 "type": [7958 "string",7959 "null"7960 ]7961 },7962 "verifiedOnChain": {7963 "type": "object",7964 "properties": {7965 "state": {7966 "type": "string",7967 "enum": [7968 "known",7969 "none",7970 "unknown",7971 "unsupported"7972 ]7973 }7974 },7975 "required": [7976 "state"7977 ],7978 "additionalProperties": {},7979 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"7980 }7981 },7982 "required": [7983 "key",7984 "id",7985 "name",7986 "verifiedOnChain"7987 ],7988 "additionalProperties": {}7989 },7990 {7991 "type": "null"7992 }7993 ]7994 },7995 "state": {7996 "type": "string"7997 },7998 "inWallet": {7999 "type": "boolean"8000 },8001 "transferable": {8002 "type": "boolean"8003 },8004 "transferBlockedBy": {8005 "type": "array",8006 "items": {8007 "type": "string"8008 }8009 },8010 "spam": {8011 "anyOf": [8012 {8013 "type": "object",8014 "properties": {8015 "by": {8016 "type": "string"8017 }8018 },8019 "required": [8020 "by"8021 ],8022 "additionalProperties": false8023 },8024 {8025 "type": "null"8026 }8027 ],8028 "description": "an indexer's signal, named — never a verdict of this wallet"8029 },8030 "ownershipSource": {8031 "type": "object",8032 "properties": {8033 "category": {8034 "type": "string"8035 },8036 "source": {8037 "type": "string"8038 },8039 "confidence": {8040 "type": "string"8041 },8042 "fetchedAt": {8043 "type": "string"8044 },8045 "stale": {8046 "type": "boolean"8047 }8048 },8049 "required": [8050 "category",8051 "source",8052 "confidence",8053 "fetchedAt",8054 "stale"8055 ],8056 "additionalProperties": {}8057 }8058 },8059 "required": [8060 "key",8061 "network",8062 "family",8063 "standard",8064 "assetId",8065 "contractAddress",8066 "tokenId",8067 "mintAddress",8068 "quantity",8069 "name",8070 "onchainName",8071 "collection",8072 "state",8073 "inWallet",8074 "transferable",8075 "transferBlockedBy",8076 "spam",8077 "ownershipSource"8078 ],8079 "additionalProperties": {}8080 }8081 },8082 "total": {8083 "type": "integer",8084 "minimum": -9007199254740991,8085 "maximum": 90071992547409918086 },8087 "hiddenSpam": {8088 "type": "integer",8089 "minimum": -9007199254740991,8090 "maximum": 90071992547409918091 },8092 "nextCursor": {8093 "description": "pass it as `cursor` to read the next (older) page; null when there is none",8094 "type": [8095 "string",8096 "null"8097 ]8098 },8099 "valuation": {8100 "type": "object",8101 "properties": {8102 "state": {8103 "type": "string",8104 "const": "unavailable"8105 },8106 "reason": {8107 "type": "string"8108 },8109 "note": {8110 "type": "string"8111 }8112 },8113 "required": [8114 "state",8115 "reason",8116 "note"8117 ],8118 "additionalProperties": false,8119 "description": "NFTs have no value in this API: never zero, never a floor"8120 },8121 "asOf": {8122 "type": "string"8123 }8124 },8125 "required": [8126 "items",8127 "total",8128 "hiddenSpam",8129 "nextCursor",8130 "valuation",8131 "asOf"8132 ],8133 "additionalProperties": false8134 },8135 "example": {8136 "items": [],8137 "total": 0,8138 "hiddenSpam": 0,8139 "nextCursor": null,8140 "valuation": {8141 "state": "unavailable",8142 "reason": "no_reliable_valuation",8143 "note": "an NFT has no value this wallet can establish: it is not counted as zero and not valued at a collection floor; it is not part of GET /portfolio"8144 },8145 "asOf": "2026-11-17T22:15:28.204Z"8146 }8147 }8148 }8149 },8150 "400": {8151 "description": "The request is not valid: `bad_request`, `invalid_cursor`",8152 "content": {8153 "application/json": {8154 "schema": {8155 "$ref": "#/components/schemas/Error"8156 }8157 }8158 }8159 },8160 "401": {8161 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",8162 "content": {8163 "application/json": {8164 "schema": {8165 "$ref": "#/components/schemas/Error"8166 }8167 }8168 }8169 },8170 "403": {8171 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",8172 "content": {8173 "application/json": {8174 "schema": {8175 "$ref": "#/components/schemas/Error"8176 }8177 }8178 }8179 },8180 "404": {8181 "description": "The object named by the request does not exist: `unknown_network`, `unknown_nft`",8182 "content": {8183 "application/json": {8184 "schema": {8185 "$ref": "#/components/schemas/Error"8186 }8187 }8188 }8189 },8190 "429": {8191 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",8192 "content": {8193 "application/json": {8194 "schema": {8195 "$ref": "#/components/schemas/Error"8196 }8197 }8198 }8199 },8200 "500": {8201 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",8202 "content": {8203 "application/json": {8204 "schema": {8205 "$ref": "#/components/schemas/Error"8206 }8207 }8208 }8209 },8210 "503": {8211 "description": "A backing service is unavailable; nothing was done: `nft_disabled`, `signer_unreachable`",8212 "content": {8213 "application/json": {8214 "schema": {8215 "$ref": "#/components/schemas/Error"8216 }8217 }8218 }8219 }8220 }8221 }8222 },8223 "/api/v1/trading/nfts/item": {8224 "get": {8225 "operationId": "getNft",8226 "tags": [8227 "Nfts"8228 ],8229 "summary": "One NFT of the wallet: identity, ownership, creator metadata, sources",8230 "description": "Only an NFT of the inventory (404 `unknown_nft` otherwise — a looked-up item is not the wallet's). On-chain facts, creator-declared metadata and indexed data are separate fields, each with its source. `marketActions` lists the market actions: none exists in this version.",8231 "security": [8232 {8233 "bearerKey": [8234 "wallet:read"8235 ]8236 }8237 ],8238 "x-spw-scope": "wallet:read",8239 "x-spw-implemented": true,8240 "x-spw-errors": [8241 {8242 "status": 400,8243 "code": "bad_request"8244 },8245 {8246 "status": 400,8247 "code": "invalid_cursor"8248 },8249 {8250 "status": 401,8251 "code": "unauthenticated"8252 },8253 {8254 "status": 403,8255 "code": "insufficient_scope"8256 },8257 {8258 "status": 403,8259 "code": "ip_not_allowed"8260 },8261 {8262 "status": 403,8263 "code": "mixed_credentials"8264 },8265 {8266 "status": 403,8267 "code": "restricted"8268 },8269 {8270 "status": 404,8271 "code": "unknown_network"8272 },8273 {8274 "status": 404,8275 "code": "unknown_nft"8276 },8277 {8278 "status": 429,8279 "code": "auth_throttled"8280 },8281 {8282 "status": 429,8283 "code": "rate_limited"8284 },8285 {8286 "status": 500,8287 "code": "internal"8288 },8289 {8290 "status": 503,8291 "code": "nft_disabled"8292 },8293 {8294 "status": 503,8295 "code": "signer_unreachable"8296 }8297 ],8298 "x-spw-example-recorded": false,8299 "x-codeSamples": [8300 {8301 "lang": "Shell",8302 "label": "curl",8303 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/nfts/item?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""8304 },8305 {8306 "lang": "TypeScript",8307 "label": "TypeScript",8308 "source": "const { nft } = await client.getNft('evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1');"8309 },8310 {8311 "lang": "Python",8312 "label": "Python",8313 "source": "nft = client.get_nft(\"evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1\").nft"8314 }8315 ],8316 "parameters": [8317 {8318 "name": "key",8319 "in": "query",8320 "required": true,8321 "description": "`family:network:asset-id`, as returned by GET /nfts",8322 "schema": {8323 "type": "string",8324 "minLength": 5,8325 "maxLength": 2608326 },8327 "example": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1"8328 }8329 ],8330 "responses": {8331 "200": {8332 "description": "OK",8333 "content": {8334 "application/json": {8335 "schema": {8336 "type": "object",8337 "properties": {8338 "nft": {8339 "type": "object",8340 "properties": {8341 "key": {8342 "type": "string",8343 "description": "`family:network:asset-id` — the id every NFT operation takes"8344 },8345 "network": {8346 "type": "string"8347 },8348 "family": {8349 "type": "string"8350 },8351 "standard": {8352 "type": "string"8353 },8354 "assetId": {8355 "type": "string"8356 },8357 "contractAddress": {8358 "type": [8359 "string",8360 "null"8361 ]8362 },8363 "tokenId": {8364 "description": "decimal string (up to 2^256 − 1), never a number",8365 "type": [8366 "string",8367 "null"8368 ]8369 },8370 "mintAddress": {8371 "type": [8372 "string",8373 "null"8374 ]8375 },8376 "quantity": {8377 "type": "string",8378 "pattern": "^(0|[1-9][0-9]{0,77})$",8379 "description": "exact integer of base units, as a string"8380 },8381 "name": {8382 "description": "declared by the creator — not chain truth",8383 "type": [8384 "string",8385 "null"8386 ]8387 },8388 "onchainName": {8389 "type": [8390 "string",8391 "null"8392 ]8393 },8394 "collection": {8395 "anyOf": [8396 {8397 "type": "object",8398 "properties": {8399 "key": {8400 "type": "string"8401 },8402 "id": {8403 "type": "string"8404 },8405 "name": {8406 "type": [8407 "string",8408 "null"8409 ]8410 },8411 "verifiedOnChain": {8412 "type": "object",8413 "properties": {8414 "state": {8415 "type": "string",8416 "enum": [8417 "known",8418 "none",8419 "unknown",8420 "unsupported"8421 ]8422 }8423 },8424 "required": [8425 "state"8426 ],8427 "additionalProperties": {},8428 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"8429 }8430 },8431 "required": [8432 "key",8433 "id",8434 "name",8435 "verifiedOnChain"8436 ],8437 "additionalProperties": {}8438 },8439 {8440 "type": "null"8441 }8442 ]8443 },8444 "state": {8445 "type": "string"8446 },8447 "inWallet": {8448 "type": "boolean"8449 },8450 "transferable": {8451 "type": "boolean"8452 },8453 "transferBlockedBy": {8454 "type": "array",8455 "items": {8456 "type": "string"8457 }8458 },8459 "spam": {8460 "anyOf": [8461 {8462 "type": "object",8463 "properties": {8464 "by": {8465 "type": "string"8466 }8467 },8468 "required": [8469 "by"8470 ],8471 "additionalProperties": false8472 },8473 {8474 "type": "null"8475 }8476 ],8477 "description": "an indexer's signal, named — never a verdict of this wallet"8478 },8479 "ownershipSource": {8480 "type": "object",8481 "properties": {8482 "category": {8483 "type": "string"8484 },8485 "source": {8486 "type": "string"8487 },8488 "confidence": {8489 "type": "string"8490 },8491 "fetchedAt": {8492 "type": "string"8493 },8494 "stale": {8495 "type": "boolean"8496 }8497 },8498 "required": [8499 "category",8500 "source",8501 "confidence",8502 "fetchedAt",8503 "stale"8504 ],8505 "additionalProperties": {}8506 },8507 "ownership": {8508 "type": "object",8509 "properties": {8510 "state": {8511 "type": "string"8512 },8513 "owner": {8514 "type": "object",8515 "properties": {8516 "state": {8517 "type": "string",8518 "enum": [8519 "known",8520 "none",8521 "unknown",8522 "unsupported"8523 ]8524 }8525 },8526 "required": [8527 "state"8528 ],8529 "additionalProperties": {},8530 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"8531 },8532 "heldByWallet": {8533 "type": "boolean"8534 }8535 },8536 "required": [8537 "state",8538 "owner",8539 "heldByWallet"8540 ],8541 "additionalProperties": {}8542 },8543 "metadata": {8544 "type": "object",8545 "properties": {8546 "status": {8547 "type": "string"8548 },8549 "name": {8550 "type": [8551 "string",8552 "null"8553 ]8554 },8555 "description": {8556 "type": [8557 "string",8558 "null"8559 ]8560 },8561 "attributes": {8562 "type": "array",8563 "items": {8564 "type": "object",8565 "properties": {8566 "traitType": {8567 "type": [8568 "string",8569 "null"8570 ]8571 },8572 "value": {8573 "type": "string"8574 }8575 },8576 "required": [8577 "traitType",8578 "value"8579 ],8580 "additionalProperties": {}8581 }8582 }8583 },8584 "required": [8585 "status",8586 "name",8587 "description",8588 "attributes"8589 ],8590 "additionalProperties": {},8591 "description": "declared by the creator: text, never chain truth"8592 },8593 "sources": {8594 "type": "array",8595 "items": {8596 "type": "object",8597 "properties": {8598 "category": {8599 "type": "string",8600 "enum": [8601 "onchain",8602 "creator_metadata",8603 "indexed",8604 "market",8605 "computed"8606 ]8607 },8608 "source": {8609 "type": "string"8610 },8611 "stale": {8612 "type": "boolean"8613 }8614 },8615 "required": [8616 "category",8617 "source",8618 "stale"8619 ],8620 "additionalProperties": {}8621 }8622 }8623 },8624 "required": [8625 "key",8626 "network",8627 "family",8628 "standard",8629 "assetId",8630 "contractAddress",8631 "tokenId",8632 "mintAddress",8633 "quantity",8634 "name",8635 "onchainName",8636 "collection",8637 "state",8638 "inWallet",8639 "transferable",8640 "transferBlockedBy",8641 "spam",8642 "ownershipSource",8643 "ownership",8644 "metadata",8645 "sources"8646 ],8647 "additionalProperties": {}8648 },8649 "marketActions": {8650 "type": "array",8651 "items": {8652 "type": "object",8653 "properties": {8654 "id": {8655 "type": "string"8656 },8657 "available": {8658 "type": "boolean",8659 "const": false8660 },8661 "reason": {8662 "type": "string"8663 }8664 },8665 "required": [8666 "id",8667 "available",8668 "reason"8669 ],8670 "additionalProperties": false8671 },8672 "description": "the market actions, none of which exists in this version: every one is `available: false` with its reason"8673 }8674 },8675 "required": [8676 "nft",8677 "marketActions"8678 ],8679 "additionalProperties": {}8680 },8681 "example": {8682 "nft": {8683 "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",8684 "network": "ethereum",8685 "family": "evm",8686 "standard": "erc721",8687 "assetId": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",8688 "contractAddress": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",8689 "tokenId": "1",8690 "mintAddress": null,8691 "quantity": "1",8692 "name": "Example #1",8693 "onchainName": null,8694 "collection": {8695 "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",8696 "id": "0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d",8697 "name": "Example Collection",8698 "verifiedOnChain": {8699 "state": "unsupported"8700 }8701 },8702 "state": "held",8703 "inWallet": true,8704 "transferable": true,8705 "transferBlockedBy": [],8706 "spam": null,8707 "ownershipSource": {8708 "category": "onchain",8709 "source": "rpc:ownerOf",8710 "confidence": "confirmed",8711 "fetchedAt": "2026-11-17T22:15:29.000Z",8712 "stale": false8713 },8714 "ownership": {8715 "state": "held",8716 "owner": {8717 "state": "known",8718 "value": "0x00000000000000000000000000000000000000aa"8719 },8720 "heldByWallet": true8721 },8722 "metadata": {8723 "status": "ok",8724 "name": "Example #1",8725 "description": "Declared by the creator.",8726 "attributes": [8727 {8728 "traitType": "Background",8729 "value": "Blue"8730 }8731 ]8732 },8733 "sources": [8734 {8735 "category": "onchain",8736 "source": "rpc:ownerOf",8737 "stale": false8738 },8739 {8740 "category": "creator_metadata",8741 "source": "tokenURI",8742 "stale": false8743 }8744 ]8745 },8746 "marketActions": [8747 {8748 "id": "sell",8749 "available": false,8750 "reason": "market_writes_not_built"8751 }8752 ]8753 }8754 }8755 }8756 },8757 "400": {8758 "description": "The request is not valid: `bad_request`, `invalid_cursor`",8759 "content": {8760 "application/json": {8761 "schema": {8762 "$ref": "#/components/schemas/Error"8763 }8764 }8765 }8766 },8767 "401": {8768 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",8769 "content": {8770 "application/json": {8771 "schema": {8772 "$ref": "#/components/schemas/Error"8773 }8774 }8775 }8776 },8777 "403": {8778 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",8779 "content": {8780 "application/json": {8781 "schema": {8782 "$ref": "#/components/schemas/Error"8783 }8784 }8785 }8786 },8787 "404": {8788 "description": "The object named by the request does not exist: `unknown_network`, `unknown_nft`",8789 "content": {8790 "application/json": {8791 "schema": {8792 "$ref": "#/components/schemas/Error"8793 }8794 }8795 }8796 },8797 "429": {8798 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",8799 "content": {8800 "application/json": {8801 "schema": {8802 "$ref": "#/components/schemas/Error"8803 }8804 }8805 }8806 },8807 "500": {8808 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",8809 "content": {8810 "application/json": {8811 "schema": {8812 "$ref": "#/components/schemas/Error"8813 }8814 }8815 }8816 },8817 "503": {8818 "description": "A backing service is unavailable; nothing was done: `nft_disabled`, `signer_unreachable`",8819 "content": {8820 "application/json": {8821 "schema": {8822 "$ref": "#/components/schemas/Error"8823 }8824 }8825 }8826 }8827 }8828 }8829 },8830 "/api/v1/trading/nfts/activity": {8831 "get": {8832 "operationId": "getNftActivity",8833 "tags": [8834 "Nfts"8835 ],8836 "summary": "On-chain events of one NFT of the wallet",8837 "description": "Mints, transfers and burns read from the chain. A transfer is never a sale: `price` is null unless SP Wallet linked a payment of the SAME transaction through a decoded marketplace event (Seaport `OrderFulfilled`), in which case the event is a `sale` and `interpretedBy` names the decoder. `completeness` says how much history the sources gave.",8838 "security": [8839 {8840 "bearerKey": [8841 "wallet:read"8842 ]8843 }8844 ],8845 "x-spw-scope": "wallet:read",8846 "x-spw-implemented": true,8847 "x-spw-errors": [8848 {8849 "status": 400,8850 "code": "bad_request"8851 },8852 {8853 "status": 400,8854 "code": "invalid_cursor"8855 },8856 {8857 "status": 400,8858 "code": "nft_bad_identifier"8859 },8860 {8861 "status": 401,8862 "code": "unauthenticated"8863 },8864 {8865 "status": 403,8866 "code": "insufficient_scope"8867 },8868 {8869 "status": 403,8870 "code": "ip_not_allowed"8871 },8872 {8873 "status": 403,8874 "code": "mixed_credentials"8875 },8876 {8877 "status": 403,8878 "code": "restricted"8879 },8880 {8881 "status": 404,8882 "code": "nft_not_found"8883 },8884 {8885 "status": 404,8886 "code": "unknown_network"8887 },8888 {8889 "status": 404,8890 "code": "unknown_nft"8891 },8892 {8893 "status": 422,8894 "code": "nft_unsupported_chain"8895 },8896 {8897 "status": 422,8898 "code": "nft_unsupported_standard"8899 },8900 {8901 "status": 429,8902 "code": "auth_throttled"8903 },8904 {8905 "status": 429,8906 "code": "nft_budget_exhausted"8907 },8908 {8909 "status": 429,8910 "code": "nft_provider_rate_limited"8911 },8912 {8913 "status": 429,8914 "code": "rate_limited"8915 },8916 {8917 "status": 500,8918 "code": "internal"8919 },8920 {8921 "status": 502,8922 "code": "nft_provider_bad_answer"8923 },8924 {8925 "status": 502,8926 "code": "nft_provider_disagreement"8927 },8928 {8929 "status": 503,8930 "code": "nft_disabled"8931 },8932 {8933 "status": 503,8934 "code": "nft_provider_method_unsupported"8935 },8936 {8937 "status": 503,8938 "code": "nft_provider_not_configured"8939 },8940 {8941 "status": 503,8942 "code": "nft_provider_unavailable"8943 },8944 {8945 "status": 503,8946 "code": "signer_unreachable"8947 }8948 ],8949 "x-spw-example-recorded": false,8950 "x-spw-example-note": "A transfer has no price: `price` is set only when a decoded marketplace event of the same transaction links a payment.",8951 "x-codeSamples": [8952 {8953 "lang": "Shell",8954 "label": "curl",8955 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/nfts/activity?key=evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d%2F1&limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""8956 },8957 {8958 "lang": "TypeScript",8959 "label": "TypeScript",8960 "source": "const { events } = await client.getNftActivity({ key: 'evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1', limit: 2 });"8961 },8962 {8963 "lang": "Python",8964 "label": "Python",8965 "source": "events = client.get_nft_activity(\"evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1\", limit=2).events"8966 }8967 ],8968 "parameters": [8969 {8970 "name": "key",8971 "in": "query",8972 "required": true,8973 "description": "`family:network:asset-id`, as returned by GET /nfts",8974 "schema": {8975 "type": "string",8976 "minLength": 5,8977 "maxLength": 2608978 },8979 "example": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1"8980 },8981 {8982 "name": "limit",8983 "in": "query",8984 "required": false,8985 "description": "rows returned at most",8986 "schema": {8987 "default": 20,8988 "type": "integer",8989 "minimum": 1,8990 "maximum": 508991 },8992 "example": 28993 },8994 {8995 "name": "cursor",8996 "in": "query",8997 "required": false,8998 "description": "`nextCursor` of the previous page",8999 "schema": {9000 "type": "string",9001 "maxLength": 4009002 }9003 },9004 {9005 "name": "type",9006 "in": "query",9007 "required": false,9008 "description": "only events of this type",9009 "schema": {9010 "type": "string",9011 "enum": [9012 "mint",9013 "transfer",9014 "transfer-in",9015 "transfer-out",9016 "burn",9017 "sale",9018 "unknown"9019 ]9020 }9021 }9022 ],9023 "responses": {9024 "200": {9025 "description": "OK",9026 "content": {9027 "application/json": {9028 "schema": {9029 "type": "object",9030 "properties": {9031 "key": {9032 "type": "string"9033 },9034 "events": {9035 "type": "array",9036 "items": {9037 "type": "object",9038 "properties": {9039 "id": {9040 "type": "string"9041 },9042 "type": {9043 "type": "string"9044 },9045 "tx": {9046 "type": "string"9047 },9048 "at": {9049 "type": [9050 "string",9051 "null"9052 ]9053 },9054 "from": {9055 "type": [9056 "string",9057 "null"9058 ]9059 },9060 "to": {9061 "type": [9062 "string",9063 "null"9064 ]9065 },9066 "quantity": {9067 "type": "string"9068 },9069 "finality": {9070 "type": "string"9071 },9072 "price": {9073 "anyOf": [9074 {9075 "type": "object",9076 "properties": {9077 "amount": {9078 "type": "string",9079 "pattern": "^(0|[1-9][0-9]{0,77})$",9080 "description": "exact integer of base units, as a string"9081 },9082 "currency": {9083 "type": "object",9084 "properties": {9085 "network": {9086 "type": "string"9087 },9088 "asset": {9089 "type": "string",9090 "description": "`native`, or the exact mint / contract"9091 },9092 "symbol": {9093 "type": "string"9094 },9095 "decimals": {9096 "type": "integer",9097 "minimum": -9007199254740991,9098 "maximum": 90071992547409919099 }9100 },9101 "required": [9102 "network",9103 "asset",9104 "symbol",9105 "decimals"9106 ],9107 "additionalProperties": false9108 }9109 },9110 "required": [9111 "amount",9112 "currency"9113 ],9114 "additionalProperties": {}9115 },9116 {9117 "type": "null"9118 }9119 ],9120 "description": "set ONLY when a payment of the same transaction was linked by a decoded marketplace event; a transfer alone never has one"9121 },9122 "interpretedBy": {9123 "type": "string"9124 }9125 },9126 "required": [9127 "id",9128 "type",9129 "tx",9130 "at",9131 "from",9132 "to",9133 "quantity",9134 "finality",9135 "price",9136 "interpretedBy"9137 ],9138 "additionalProperties": {}9139 }9140 },9141 "nextCursor": {9142 "description": "pass it as `cursor` to read the next (older) page; null when there is none",9143 "type": [9144 "string",9145 "null"9146 ]9147 },9148 "completeness": {9149 "type": "string"9150 },9151 "note": {9152 "type": [9153 "string",9154 "null"9155 ]9156 },9157 "error": {9158 "type": [9159 "string",9160 "null"9161 ]9162 }9163 },9164 "required": [9165 "key",9166 "events",9167 "nextCursor",9168 "completeness",9169 "note",9170 "error"9171 ],9172 "additionalProperties": false9173 },9174 "example": {9175 "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",9176 "events": [9177 {9178 "id": "0x5c1f…e2a9:14",9179 "type": "transfer-in",9180 "tx": "0x5c1f0d2b7a9e4c3f8b6a1d0e9f7c5b3a2d1e0f9c8b7a6d5e4f3c2b1a0f9ee2a9",9181 "at": "2026-10-02T14:11:23.000Z",9182 "from": "0x00000000000000000000000000000000000000bb",9183 "to": "0x00000000000000000000000000000000000000aa",9184 "quantity": "1",9185 "finality": "final",9186 "price": null,9187 "interpretedBy": "chain"9188 }9189 ],9190 "nextCursor": null,9191 "completeness": "partial",9192 "note": null,9193 "error": null9194 }9195 }9196 }9197 },9198 "400": {9199 "description": "The request is not valid: `bad_request`, `invalid_cursor`, `nft_bad_identifier`",9200 "content": {9201 "application/json": {9202 "schema": {9203 "$ref": "#/components/schemas/Error"9204 }9205 }9206 }9207 },9208 "401": {9209 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",9210 "content": {9211 "application/json": {9212 "schema": {9213 "$ref": "#/components/schemas/Error"9214 }9215 }9216 }9217 },9218 "403": {9219 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",9220 "content": {9221 "application/json": {9222 "schema": {9223 "$ref": "#/components/schemas/Error"9224 }9225 }9226 }9227 },9228 "404": {9229 "description": "The object named by the request does not exist: `nft_not_found`, `unknown_network`, `unknown_nft`",9230 "content": {9231 "application/json": {9232 "schema": {9233 "$ref": "#/components/schemas/Error"9234 }9235 }9236 }9237 },9238 "422": {9239 "description": "A valid request that cannot be carried out: `nft_unsupported_chain`, `nft_unsupported_standard`",9240 "content": {9241 "application/json": {9242 "schema": {9243 "$ref": "#/components/schemas/Error"9244 }9245 }9246 }9247 },9248 "429": {9249 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited`",9250 "content": {9251 "application/json": {9252 "schema": {9253 "$ref": "#/components/schemas/Error"9254 }9255 }9256 }9257 },9258 "500": {9259 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",9260 "content": {9261 "application/json": {9262 "schema": {9263 "$ref": "#/components/schemas/Error"9264 }9265 }9266 }9267 },9268 "502": {9269 "description": "Error: `nft_provider_bad_answer`, `nft_provider_disagreement`",9270 "content": {9271 "application/json": {9272 "schema": {9273 "$ref": "#/components/schemas/Error"9274 }9275 }9276 }9277 },9278 "503": {9279 "description": "A backing service is unavailable; nothing was done: `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable`",9280 "content": {9281 "application/json": {9282 "schema": {9283 "$ref": "#/components/schemas/Error"9284 }9285 }9286 }9287 }9288 }9289 }9290 },9291 "/api/v1/trading/nfts/market": {9292 "get": {9293 "operationId": "getNftMarket",9294 "tags": [9295 "Nfts"9296 ],9297 "summary": "Market data of any NFT, one row per source",9298 "description": "The item is named by its chain identifiers and read on-chain first. Then every configured market source answers on its own row: asking price, best offer, last sale, collection floor — five different notions, each in its own currency (network + exact mint / contract + decimals), with the source, its date and `stale`. A source without its key answers `needs_key` with the variable name; nothing is ever filled in. Sources are never merged: disagreements are listed in `contradictions`. Says nothing about the wallet. `rates` are secondary; a rate from a price source licensed for internal use is withheld from an API key.",9299 "security": [9300 {9301 "bearerKey": [9302 "markets:read"9303 ]9304 }9305 ],9306 "x-spw-scope": "markets:read",9307 "x-spw-implemented": true,9308 "x-spw-errors": [9309 {9310 "status": 400,9311 "code": "bad_request"9312 },9313 {9314 "status": 400,9315 "code": "nft_bad_identifier"9316 },9317 {9318 "status": 401,9319 "code": "unauthenticated"9320 },9321 {9322 "status": 403,9323 "code": "insufficient_scope"9324 },9325 {9326 "status": 403,9327 "code": "ip_not_allowed"9328 },9329 {9330 "status": 403,9331 "code": "mixed_credentials"9332 },9333 {9334 "status": 403,9335 "code": "restricted"9336 },9337 {9338 "status": 404,9339 "code": "nft_not_found"9340 },9341 {9342 "status": 404,9343 "code": "unknown_network"9344 },9345 {9346 "status": 422,9347 "code": "nft_unsupported_chain"9348 },9349 {9350 "status": 422,9351 "code": "nft_unsupported_standard"9352 },9353 {9354 "status": 429,9355 "code": "auth_throttled"9356 },9357 {9358 "status": 429,9359 "code": "nft_budget_exhausted"9360 },9361 {9362 "status": 429,9363 "code": "nft_provider_rate_limited"9364 },9365 {9366 "status": 429,9367 "code": "rate_limited"9368 },9369 {9370 "status": 500,9371 "code": "internal"9372 },9373 {9374 "status": 502,9375 "code": "nft_provider_bad_answer"9376 },9377 {9378 "status": 502,9379 "code": "nft_provider_disagreement"9380 },9381 {9382 "status": 503,9383 "code": "nft_disabled"9384 },9385 {9386 "status": 503,9387 "code": "nft_provider_method_unsupported"9388 },9389 {9390 "status": 503,9391 "code": "nft_provider_not_configured"9392 },9393 {9394 "status": 503,9395 "code": "nft_provider_unavailable"9396 },9397 {9398 "status": 503,9399 "code": "signer_unreachable"9400 }9401 ],9402 "x-spw-example-recorded": true,9403 "x-spw-example-note": "Recorded on a server without a marketplace key: the source answers `needs_key` and names the variable. Nothing is filled in.",9404 "x-codeSamples": [9405 {9406 "lang": "Shell",9407 "label": "curl",9408 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/nfts/market?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""9409 },9410 {9411 "lang": "TypeScript",9412 "label": "TypeScript",9413 "source": "const market = await client.getNftMarket({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1' });"9414 },9415 {9416 "lang": "Python",9417 "label": "Python",9418 "source": "market = client.get_nft_market(network=\"ethereum\", address=\"0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D\", token_id=\"1\")"9419 }9420 ],9421 "parameters": [9422 {9423 "name": "network",9424 "in": "query",9425 "required": true,9426 "description": "network id, e.g. `ethereum`, `base`, `solana`",9427 "schema": {9428 "type": "string",9429 "maxLength": 249430 },9431 "example": "ethereum"9432 },9433 {9434 "name": "address",9435 "in": "query",9436 "required": true,9437 "description": "EVM: the contract; Solana: the mint / asset address",9438 "schema": {9439 "type": "string",9440 "minLength": 26,9441 "maxLength": 649442 },9443 "example": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"9444 },9445 {9446 "name": "tokenId",9447 "in": "query",9448 "required": false,9449 "description": "EVM: required, decimal or 0x-hex",9450 "schema": {9451 "type": "string",9452 "maxLength": 809453 },9454 "example": "1"9455 }9456 ],9457 "responses": {9458 "200": {9459 "description": "OK (the example is a recorded answer)",9460 "content": {9461 "application/json": {9462 "schema": {9463 "type": "object",9464 "properties": {9465 "key": {9466 "type": "string"9467 },9468 "network": {9469 "type": "string"9470 },9471 "standard": {9472 "type": "string"9473 },9474 "sources": {9475 "type": "array",9476 "items": {9477 "type": "object",9478 "properties": {9479 "status": {9480 "type": "object",9481 "properties": {9482 "provider": {9483 "type": "string"9484 },9485 "name": {9486 "type": "string"9487 },9488 "state": {9489 "type": "string",9490 "enum": [9491 "ok",9492 "needs_key",9493 "off",9494 "not_covered",9495 "error"9496 ]9497 },9498 "code": {9499 "type": [9500 "string",9501 "null"9502 ]9503 },9504 "unlockedBy": {9505 "description": "NAME of the server variable that turns the source on",9506 "type": [9507 "string",9508 "null"9509 ]9510 },9511 "stale": {9512 "type": "boolean",9513 "description": "true: the last answer of a source that is failing now"9514 }9515 },9516 "required": [9517 "provider",9518 "name",9519 "state",9520 "code",9521 "unlockedBy",9522 "stale"9523 ],9524 "additionalProperties": {}9525 },9526 "url": {9527 "type": [9528 "string",9529 "null"9530 ]9531 },9532 "listed": {9533 "type": "object",9534 "properties": {9535 "state": {9536 "type": "string",9537 "enum": [9538 "known",9539 "none",9540 "unknown",9541 "unsupported"9542 ]9543 }9544 },9545 "required": [9546 "state"9547 ],9548 "additionalProperties": {},9549 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"9550 },9551 "ask": {9552 "type": "object",9553 "properties": {9554 "state": {9555 "type": "string",9556 "enum": [9557 "known",9558 "none",9559 "unknown",9560 "unsupported"9561 ]9562 }9563 },9564 "required": [9565 "state"9566 ],9567 "additionalProperties": {},9568 "description": "asking price of a live listing"9569 },9570 "bestOffer": {9571 "type": "object",9572 "properties": {9573 "state": {9574 "type": "string",9575 "enum": [9576 "known",9577 "none",9578 "unknown",9579 "unsupported"9580 ]9581 }9582 },9583 "required": [9584 "state"9585 ],9586 "additionalProperties": {},9587 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"9588 },9589 "lastSale": {9590 "type": "object",9591 "properties": {9592 "state": {9593 "type": "string",9594 "enum": [9595 "known",9596 "none",9597 "unknown",9598 "unsupported"9599 ]9600 }9601 },9602 "required": [9603 "state"9604 ],9605 "additionalProperties": {},9606 "description": "last sale the source reports"9607 },9608 "collectionFloor": {9609 "type": "object",9610 "properties": {9611 "state": {9612 "type": "string",9613 "enum": [9614 "known",9615 "none",9616 "unknown",9617 "unsupported"9618 ]9619 }9620 },9621 "required": [9622 "state"9623 ],9624 "additionalProperties": {},9625 "description": "a statistic of the COLLECTION — never the value of this item"9626 },9627 "verification": {9628 "anyOf": [9629 {9630 "type": "object",9631 "properties": {9632 "state": {9633 "type": "string",9634 "enum": [9635 "verified",9636 "not_verified",9637 "unknown"9638 ]9639 },9640 "providerValue": {9641 "type": [9642 "string",9643 "null"9644 ]9645 },9646 "by": {9647 "type": "string"9648 }9649 },9650 "required": [9651 "state",9652 "providerValue",9653 "by"9654 ],9655 "additionalProperties": {}9656 },9657 {9658 "type": "null"9659 }9660 ],9661 "description": "the marketplace's own badge, named — not an on-chain verification"9662 },9663 "rarity": {9664 "type": "object",9665 "properties": {9666 "state": {9667 "type": "string",9668 "enum": [9669 "known",9670 "none",9671 "unknown",9672 "unsupported"9673 ]9674 }9675 },9676 "required": [9677 "state"9678 ],9679 "additionalProperties": {},9680 "description": "`known` carries `value`; `none` = established as absent; `unknown` = could not be established (`reason` may say why); `unsupported` = the standard has no such notion. Zero is a value"9681 }9682 },9683 "required": [9684 "status",9685 "url",9686 "listed",9687 "ask",9688 "bestOffer",9689 "lastSale",9690 "collectionFloor",9691 "verification",9692 "rarity"9693 ],9694 "additionalProperties": {}9695 },9696 "description": "ONE ROW PER SOURCE: never merged, never averaged"9697 },9698 "contradictions": {9699 "type": "array",9700 "items": {9701 "type": "object",9702 "properties": {9703 "field": {9704 "type": "string"9705 },9706 "providers": {9707 "type": "array",9708 "items": {9709 "type": "string"9710 }9711 },9712 "note": {9713 "type": "string"9714 }9715 },9716 "required": [9717 "field",9718 "providers",9719 "note"9720 ],9721 "additionalProperties": {}9722 }9723 },9724 "rates": {9725 "type": "object",9726 "propertyNames": {9727 "type": "string"9728 },9729 "additionalProperties": {9730 "type": "object",9731 "properties": {9732 "symbol": {9733 "type": "string"9734 },9735 "usd": {9736 "anyOf": [9737 {9738 "type": "string",9739 "description": "decimal number as a string (never a float)"9740 },9741 {9742 "type": "null"9743 }9744 ]9745 },9746 "cad": {9747 "anyOf": [9748 {9749 "type": "string",9750 "description": "decimal number as a string (never a float)"9751 },9752 {9753 "type": "null"9754 }9755 ]9756 },9757 "source": {9758 "type": "string"9759 },9760 "priceAt": {9761 "type": [9762 "string",9763 "null"9764 ]9765 },9766 "stale": {9767 "type": "boolean"9768 },9769 "withheld": {9770 "description": "set, with `usd` and `cad` null, when the price source is licensed for internal use and the caller is an API key",9771 "type": [9772 "string",9773 "null"9774 ]9775 }9776 },9777 "required": [9778 "symbol",9779 "usd",9780 "cad",9781 "source",9782 "priceAt",9783 "stale",9784 "withheld"9785 ],9786 "additionalProperties": {}9787 },9788 "description": "fiat rates of the currencies quoted, keyed `network:asset` — secondary information with its own source and date"9789 },9790 "value": {9791 "type": "object",9792 "properties": {9793 "state": {9794 "type": "string",9795 "const": "unavailable"9796 },9797 "reason": {9798 "type": "string"9799 }9800 },9801 "required": [9802 "state",9803 "reason"9804 ],9805 "additionalProperties": false9806 },9807 "marketActions": {9808 "type": "array",9809 "items": {9810 "type": "object",9811 "properties": {9812 "id": {9813 "type": "string"9814 },9815 "available": {9816 "type": "boolean",9817 "const": false9818 },9819 "reason": {9820 "type": "string"9821 }9822 },9823 "required": [9824 "id",9825 "available",9826 "reason"9827 ],9828 "additionalProperties": false9829 },9830 "description": "the market actions, none of which exists in this version: every one is `available: false` with its reason"9831 },9832 "asOf": {9833 "type": "string"9834 }9835 },9836 "required": [9837 "key",9838 "network",9839 "standard",9840 "sources",9841 "contradictions",9842 "rates",9843 "value",9844 "marketActions",9845 "asOf"9846 ],9847 "additionalProperties": {}9848 },9849 "example": {9850 "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",9851 "network": "ethereum",9852 "standard": "erc721",9853 "sources": [9854 {9855 "url": null,9856 "listed": {9857 "state": "unknown"9858 },9859 "ask": {9860 "state": "unknown"9861 },9862 "bestOffer": {9863 "state": "unknown"9864 },9865 "lastSale": {9866 "state": "unknown"9867 },9868 "collection": null,9869 "collectionFloor": {9870 "state": "unknown"9871 },9872 "verification": null,9873 "flags": {9874 "suspicious": {9875 "state": "unknown"9876 },9877 "disabled": {9878 "state": "unknown"9879 },9880 "nsfw": {9881 "state": "unknown"9882 }9883 },9884 "rarity": {9885 "state": "unknown"9886 },9887 "status": {9888 "provider": "opensea",9889 "name": "OpenSea",9890 "state": "needs_key",9891 "code": "no_api_key",9892 "unlockedBy": "OPENSEA_API_KEY",9893 "stale": false,9894 "stamp": null,9895 "attribution": null9896 }9897 }9898 ],9899 "contradictions": [],9900 "rates": {},9901 "value": {9902 "state": "unavailable",9903 "reason": "no_valuation_from_floor_or_single_quote"9904 },9905 "marketActions": [9906 {9907 "id": "buy",9908 "available": false,9909 "reason": "market_writes_not_built"9910 },9911 {9912 "id": "sell",9913 "available": false,9914 "reason": "market_writes_not_built"9915 }9916 ],9917 "asOf": "2026-11-17T22:15:29.113Z"9918 }9919 }9920 }9921 },9922 "400": {9923 "description": "The request is not valid: `bad_request`, `nft_bad_identifier`",9924 "content": {9925 "application/json": {9926 "schema": {9927 "$ref": "#/components/schemas/Error"9928 }9929 }9930 }9931 },9932 "401": {9933 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",9934 "content": {9935 "application/json": {9936 "schema": {9937 "$ref": "#/components/schemas/Error"9938 }9939 }9940 }9941 },9942 "403": {9943 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",9944 "content": {9945 "application/json": {9946 "schema": {9947 "$ref": "#/components/schemas/Error"9948 }9949 }9950 }9951 },9952 "404": {9953 "description": "The object named by the request does not exist: `nft_not_found`, `unknown_network`",9954 "content": {9955 "application/json": {9956 "schema": {9957 "$ref": "#/components/schemas/Error"9958 }9959 }9960 }9961 },9962 "422": {9963 "description": "A valid request that cannot be carried out: `nft_unsupported_chain`, `nft_unsupported_standard`",9964 "content": {9965 "application/json": {9966 "schema": {9967 "$ref": "#/components/schemas/Error"9968 }9969 }9970 }9971 },9972 "429": {9973 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited`",9974 "content": {9975 "application/json": {9976 "schema": {9977 "$ref": "#/components/schemas/Error"9978 }9979 }9980 }9981 },9982 "500": {9983 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",9984 "content": {9985 "application/json": {9986 "schema": {9987 "$ref": "#/components/schemas/Error"9988 }9989 }9990 }9991 },9992 "502": {9993 "description": "Error: `nft_provider_bad_answer`, `nft_provider_disagreement`",9994 "content": {9995 "application/json": {9996 "schema": {9997 "$ref": "#/components/schemas/Error"9998 }9999 }10000 }10001 },10002 "503": {10003 "description": "A backing service is unavailable; nothing was done: `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable`",10004 "content": {10005 "application/json": {10006 "schema": {10007 "$ref": "#/components/schemas/Error"10008 }10009 }10010 }10011 }10012 }10013 }10014 },10015 "/api/v1/trading/nfts/market/events": {10016 "get": {10017 "operationId": "getNftMarketEvents",10018 "tags": [10019 "Nfts"10020 ],10021 "summary": "Market events of any NFT (sales, listings, offers), per source",10022 "description": "What each market source reports, newest first, with the payment token and quantity when the source gives them. Filter by `type`, `after`, `before`. One list per source: a `nextCursor` is passed back as `cursor` together with `provider`. A wash-trade flag is passed through when a source has one (`unknown` otherwise). These are market statements, listed apart from the chain's transfers (GET /nfts/activity).",10023 "security": [10024 {10025 "bearerKey": [10026 "markets:read"10027 ]10028 }10029 ],10030 "x-spw-scope": "markets:read",10031 "x-spw-implemented": true,10032 "x-spw-errors": [10033 {10034 "status": 400,10035 "code": "bad_request"10036 },10037 {10038 "status": 400,10039 "code": "nft_bad_identifier"10040 },10041 {10042 "status": 401,10043 "code": "unauthenticated"10044 },10045 {10046 "status": 403,10047 "code": "insufficient_scope"10048 },10049 {10050 "status": 403,10051 "code": "ip_not_allowed"10052 },10053 {10054 "status": 403,10055 "code": "mixed_credentials"10056 },10057 {10058 "status": 403,10059 "code": "restricted"10060 },10061 {10062 "status": 404,10063 "code": "nft_not_found"10064 },10065 {10066 "status": 404,10067 "code": "unknown_network"10068 },10069 {10070 "status": 422,10071 "code": "nft_unsupported_chain"10072 },10073 {10074 "status": 422,10075 "code": "nft_unsupported_standard"10076 },10077 {10078 "status": 429,10079 "code": "auth_throttled"10080 },10081 {10082 "status": 429,10083 "code": "nft_budget_exhausted"10084 },10085 {10086 "status": 429,10087 "code": "nft_provider_rate_limited"10088 },10089 {10090 "status": 429,10091 "code": "rate_limited"10092 },10093 {10094 "status": 500,10095 "code": "internal"10096 },10097 {10098 "status": 502,10099 "code": "nft_provider_bad_answer"10100 },10101 {10102 "status": 502,10103 "code": "nft_provider_disagreement"10104 },10105 {10106 "status": 503,10107 "code": "nft_disabled"10108 },10109 {10110 "status": 503,10111 "code": "nft_provider_method_unsupported"10112 },10113 {10114 "status": 503,10115 "code": "nft_provider_not_configured"10116 },10117 {10118 "status": 503,10119 "code": "nft_provider_unavailable"10120 },10121 {10122 "status": 503,10123 "code": "signer_unreachable"10124 }10125 ],10126 "x-spw-example-recorded": true,10127 "x-spw-example-note": "Recorded on a server without a marketplace key: the source answers `needs_key` and lists no event. With a key, each event carries `type`, `at`, `tx`, `from`, `to`, `quantity`, `price` (amount in base units + currency) and `flags.washTrade`.",10128 "x-codeSamples": [10129 {10130 "lang": "Shell",10131 "label": "curl",10132 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/nfts/market/events?network=ethereum&address=0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D&tokenId=1&type=sale&limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""10133 },10134 {10135 "lang": "TypeScript",10136 "label": "TypeScript",10137 "source": "const { sources } = await client.getNftMarketEvents({ network: 'ethereum', address: '0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D', tokenId: '1', type: 'sale', limit: 2 });"10138 },10139 {10140 "lang": "Python",10141 "label": "Python",10142 "source": "sources = client.get_nft_market_events(network=\"ethereum\", address=\"0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D\", token_id=\"1\", type=\"sale\", limit=2).sources"10143 }10144 ],10145 "parameters": [10146 {10147 "name": "network",10148 "in": "query",10149 "required": true,10150 "description": "network id, e.g. `ethereum`, `base`, `solana`",10151 "schema": {10152 "type": "string",10153 "maxLength": 2410154 },10155 "example": "ethereum"10156 },10157 {10158 "name": "address",10159 "in": "query",10160 "required": true,10161 "description": "EVM: the contract; Solana: the mint / asset address",10162 "schema": {10163 "type": "string",10164 "minLength": 26,10165 "maxLength": 6410166 },10167 "example": "0xBC4CA0EdA7647A8aB7C2061c2E118A18a936f13D"10168 },10169 {10170 "name": "tokenId",10171 "in": "query",10172 "required": false,10173 "description": "EVM: required, decimal or 0x-hex",10174 "schema": {10175 "type": "string",10176 "maxLength": 8010177 },10178 "example": "1"10179 },10180 {10181 "name": "provider",10182 "in": "query",10183 "required": false,10184 "description": "only this source (its id is `sources[].status.provider`); required with `cursor`",10185 "schema": {10186 "type": "string",10187 "pattern": "^[a-z][a-z0-9-]{1,30}$"10188 }10189 },10190 {10191 "name": "type",10192 "in": "query",10193 "required": false,10194 "description": "comma-separated: sale, list, delist, offer, cancel-offer, transfer, mint",10195 "schema": {10196 "type": "string",10197 "maxLength": 120,10198 "pattern": "^[a-z,-]+$"10199 },10200 "example": "sale"10201 },10202 {10203 "name": "after",10204 "in": "query",10205 "required": false,10206 "description": "only events after this instant (ISO 8601)",10207 "schema": {10208 "type": "string",10209 "format": "date-time",10210 "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"10211 }10212 },10213 {10214 "name": "before",10215 "in": "query",10216 "required": false,10217 "description": "only events before this instant (ISO 8601)",10218 "schema": {10219 "type": "string",10220 "format": "date-time",10221 "pattern": "^(?:(?:\\d\\d[2468][048]|\\d\\d[13579][26]|\\d\\d0[48]|[02468][048]00|[13579][26]00)-02-29|\\d{4}-(?:(?:0[13578]|1[02])-(?:0[1-9]|[12]\\d|3[01])|(?:0[469]|11)-(?:0[1-9]|[12]\\d|30)|(?:02)-(?:0[1-9]|1\\d|2[0-8])))T(?:(?:[01]\\d|2[0-3]):[0-5]\\d:[0-5]\\d(?:\\.\\d+)?(?:Z))$"10222 }10223 },10224 {10225 "name": "cursor",10226 "in": "query",10227 "required": false,10228 "description": "a position in ONE source's list: send it with `provider`",10229 "schema": {10230 "type": "string",10231 "maxLength": 60010232 }10233 },10234 {10235 "name": "limit",10236 "in": "query",10237 "required": false,10238 "description": "rows returned at most",10239 "schema": {10240 "default": 20,10241 "type": "integer",10242 "minimum": 1,10243 "maximum": 5010244 },10245 "example": 210246 }10247 ],10248 "responses": {10249 "200": {10250 "description": "OK (the example is a recorded answer)",10251 "content": {10252 "application/json": {10253 "schema": {10254 "type": "object",10255 "properties": {10256 "key": {10257 "type": "string"10258 },10259 "sources": {10260 "type": "array",10261 "items": {10262 "type": "object",10263 "properties": {10264 "status": {10265 "type": "object",10266 "properties": {10267 "provider": {10268 "type": "string"10269 },10270 "name": {10271 "type": "string"10272 },10273 "state": {10274 "type": "string",10275 "enum": [10276 "ok",10277 "needs_key",10278 "off",10279 "not_covered",10280 "error"10281 ]10282 },10283 "code": {10284 "type": [10285 "string",10286 "null"10287 ]10288 },10289 "unlockedBy": {10290 "description": "NAME of the server variable that turns the source on",10291 "type": [10292 "string",10293 "null"10294 ]10295 },10296 "stale": {10297 "type": "boolean",10298 "description": "true: the last answer of a source that is failing now"10299 }10300 },10301 "required": [10302 "provider",10303 "name",10304 "state",10305 "code",10306 "unlockedBy",10307 "stale"10308 ],10309 "additionalProperties": {}10310 },10311 "events": {10312 "type": "array",10313 "items": {10314 "type": "object",10315 "properties": {10316 "type": {10317 "type": "string",10318 "enum": [10319 "sale",10320 "list",10321 "delist",10322 "offer",10323 "cancel-offer",10324 "accept-offer",10325 "transfer",10326 "mint",10327 "unknown"10328 ]10329 },10330 "providerType": {10331 "type": "string"10332 },10333 "at": {10334 "type": [10335 "string",10336 "null"10337 ]10338 },10339 "tx": {10340 "type": [10341 "string",10342 "null"10343 ]10344 },10345 "from": {10346 "type": [10347 "string",10348 "null"10349 ]10350 },10351 "to": {10352 "type": [10353 "string",10354 "null"10355 ]10356 },10357 "quantity": {10358 "type": "string",10359 "pattern": "^(0|[1-9][0-9]{0,77})$",10360 "description": "exact integer of base units, as a string"10361 },10362 "price": {10363 "anyOf": [10364 {10365 "type": "object",10366 "properties": {10367 "amount": {10368 "type": "string",10369 "pattern": "^(0|[1-9][0-9]{0,77})$",10370 "description": "exact integer of base units, as a string"10371 },10372 "currency": {10373 "type": "object",10374 "properties": {10375 "network": {10376 "type": "string"10377 },10378 "asset": {10379 "type": "string",10380 "description": "`native`, or the exact mint / contract"10381 },10382 "symbol": {10383 "type": "string"10384 },10385 "decimals": {10386 "type": "integer",10387 "minimum": -9007199254740991,10388 "maximum": 900719925474099110389 }10390 },10391 "required": [10392 "network",10393 "asset",10394 "symbol",10395 "decimals"10396 ],10397 "additionalProperties": false10398 },10399 "precision": {10400 "type": "string",10401 "enum": [10402 "exact",10403 "source_decimal"10404 ],10405 "description": "`source_decimal`: the source gave a decimal number, converted digit by digit"10406 }10407 },10408 "required": [10409 "amount",10410 "currency",10411 "precision"10412 ],10413 "additionalProperties": false10414 },10415 {10416 "type": "null"10417 }10418 ]10419 },10420 "flags": {10421 "type": "object",10422 "properties": {10423 "washTrade": {10424 "type": "object",10425 "properties": {10426 "state": {10427 "type": "string",10428 "enum": [10429 "known",10430 "none",10431 "unknown",10432 "unsupported"10433 ]10434 }10435 },10436 "required": [10437 "state"10438 ],10439 "additionalProperties": {},10440 "description": "as the SOURCE reports it; `unknown` when it has no such flag — never filtered"10441 }10442 },10443 "required": [10444 "washTrade"10445 ],10446 "additionalProperties": {}10447 }10448 },10449 "required": [10450 "type",10451 "providerType",10452 "at",10453 "tx",10454 "from",10455 "to",10456 "quantity",10457 "price",10458 "flags"10459 ],10460 "additionalProperties": {}10461 }10462 },10463 "nextCursor": {10464 "description": "pass it as `cursor` to read the next (older) page; null when there is none",10465 "type": [10466 "string",10467 "null"10468 ]10469 }10470 },10471 "required": [10472 "status",10473 "events",10474 "nextCursor"10475 ],10476 "additionalProperties": false10477 }10478 },10479 "rates": {10480 "type": "object",10481 "propertyNames": {10482 "type": "string"10483 },10484 "additionalProperties": {10485 "type": "object",10486 "properties": {10487 "symbol": {10488 "type": "string"10489 },10490 "usd": {10491 "anyOf": [10492 {10493 "type": "string",10494 "description": "decimal number as a string (never a float)"10495 },10496 {10497 "type": "null"10498 }10499 ]10500 },10501 "cad": {10502 "anyOf": [10503 {10504 "type": "string",10505 "description": "decimal number as a string (never a float)"10506 },10507 {10508 "type": "null"10509 }10510 ]10511 },10512 "source": {10513 "type": "string"10514 },10515 "priceAt": {10516 "type": [10517 "string",10518 "null"10519 ]10520 },10521 "stale": {10522 "type": "boolean"10523 },10524 "withheld": {10525 "description": "set, with `usd` and `cad` null, when the price source is licensed for internal use and the caller is an API key",10526 "type": [10527 "string",10528 "null"10529 ]10530 }10531 },10532 "required": [10533 "symbol",10534 "usd",10535 "cad",10536 "source",10537 "priceAt",10538 "stale",10539 "withheld"10540 ],10541 "additionalProperties": {}10542 }10543 },10544 "asOf": {10545 "type": "string"10546 }10547 },10548 "required": [10549 "key",10550 "sources",10551 "rates",10552 "asOf"10553 ],10554 "additionalProperties": false10555 },10556 "example": {10557 "key": "evm:ethereum:0xbc4ca0eda7647a8ab7c2061c2e118a18a936f13d/1",10558 "sources": [10559 {10560 "status": {10561 "provider": "opensea",10562 "name": "OpenSea",10563 "state": "needs_key",10564 "code": "no_api_key",10565 "unlockedBy": "OPENSEA_API_KEY",10566 "stale": false,10567 "stamp": null,10568 "attribution": null10569 },10570 "events": [],10571 "nextCursor": null10572 }10573 ],10574 "rates": {},10575 "asOf": "2026-11-17T22:37:24.187Z"10576 }10577 }10578 }10579 },10580 "400": {10581 "description": "The request is not valid: `bad_request`, `nft_bad_identifier`",10582 "content": {10583 "application/json": {10584 "schema": {10585 "$ref": "#/components/schemas/Error"10586 }10587 }10588 }10589 },10590 "401": {10591 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",10592 "content": {10593 "application/json": {10594 "schema": {10595 "$ref": "#/components/schemas/Error"10596 }10597 }10598 }10599 },10600 "403": {10601 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",10602 "content": {10603 "application/json": {10604 "schema": {10605 "$ref": "#/components/schemas/Error"10606 }10607 }10608 }10609 },10610 "404": {10611 "description": "The object named by the request does not exist: `nft_not_found`, `unknown_network`",10612 "content": {10613 "application/json": {10614 "schema": {10615 "$ref": "#/components/schemas/Error"10616 }10617 }10618 }10619 },10620 "422": {10621 "description": "A valid request that cannot be carried out: `nft_unsupported_chain`, `nft_unsupported_standard`",10622 "content": {10623 "application/json": {10624 "schema": {10625 "$ref": "#/components/schemas/Error"10626 }10627 }10628 }10629 },10630 "429": {10631 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `nft_budget_exhausted`, `nft_provider_rate_limited`, `rate_limited`",10632 "content": {10633 "application/json": {10634 "schema": {10635 "$ref": "#/components/schemas/Error"10636 }10637 }10638 }10639 },10640 "500": {10641 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",10642 "content": {10643 "application/json": {10644 "schema": {10645 "$ref": "#/components/schemas/Error"10646 }10647 }10648 }10649 },10650 "502": {10651 "description": "Error: `nft_provider_bad_answer`, `nft_provider_disagreement`",10652 "content": {10653 "application/json": {10654 "schema": {10655 "$ref": "#/components/schemas/Error"10656 }10657 }10658 }10659 },10660 "503": {10661 "description": "A backing service is unavailable; nothing was done: `nft_disabled`, `nft_provider_method_unsupported`, `nft_provider_not_configured`, `nft_provider_unavailable`, `signer_unreachable`",10662 "content": {10663 "application/json": {10664 "schema": {10665 "$ref": "#/components/schemas/Error"10666 }10667 }10668 }10669 }10670 }10671 }10672 },10673 "/api/v1/trading/positions": {10674 "get": {10675 "operationId": "listPositions",10676 "tags": [10677 "Positions"10678 ],10679 "summary": "Open positions, paper and live separated by `mode`",10680 "description": "Every open derivatives position of the wallet — paper accounts, Hyperliquid venue accounts, GMX (read on-chain) — each with its `mode`. `id` is what POST /positions/{id}/close and /reduce take; it contains colons: URL-encode it. A source that cannot be read is listed in `errors`; 503 only when none answered. Sizes and prices are decimal strings.",10681 "security": [10682 {10683 "bearerKey": [10684 "positions:read"10685 ]10686 }10687 ],10688 "x-spw-scope": "positions:read",10689 "x-spw-implemented": true,10690 "x-spw-errors": [10691 {10692 "status": 400,10693 "code": "bad_request"10694 },10695 {10696 "status": 401,10697 "code": "unauthenticated"10698 },10699 {10700 "status": 403,10701 "code": "insufficient_scope"10702 },10703 {10704 "status": 403,10705 "code": "ip_not_allowed"10706 },10707 {10708 "status": 403,10709 "code": "mixed_credentials"10710 },10711 {10712 "status": 403,10713 "code": "restricted"10714 },10715 {10716 "status": 429,10717 "code": "auth_throttled"10718 },10719 {10720 "status": 429,10721 "code": "rate_limited"10722 },10723 {10724 "status": 500,10725 "code": "internal"10726 },10727 {10728 "status": 503,10729 "code": "service_unavailable"10730 }10731 ],10732 "x-spw-example-recorded": true,10733 "x-spw-example-note": "A position `id` contains colons: URL-encode it in a path (both SDKs do).",10734 "x-codeSamples": [10735 {10736 "lang": "Shell",10737 "label": "curl",10738 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/positions?mode=paper\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""10739 },10740 {10741 "lang": "TypeScript",10742 "label": "TypeScript",10743 "source": "const { positions } = await client.getPositions({ mode: 'paper' });"10744 },10745 {10746 "lang": "Python",10747 "label": "Python",10748 "source": "positions = client.get_positions(mode=\"paper\").positions"10749 }10750 ],10751 "parameters": [10752 {10753 "name": "mode",10754 "in": "query",10755 "required": false,10756 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.",10757 "schema": {10758 "type": "string",10759 "enum": [10760 "paper",10761 "live"10762 ]10763 },10764 "example": "paper"10765 },10766 {10767 "name": "venue",10768 "in": "query",10769 "required": false,10770 "description": "venue id: hyperliquid, gmx, dydx, spot",10771 "schema": {10772 "type": "string",10773 "maxLength": 4010774 }10775 }10776 ],10777 "responses": {10778 "200": {10779 "description": "OK (the example is a recorded answer)",10780 "content": {10781 "application/json": {10782 "schema": {10783 "type": "object",10784 "properties": {10785 "positions": {10786 "type": "array",10787 "items": {10788 "type": "object",10789 "properties": {10790 "id": {10791 "type": "string"10792 },10793 "mode": {10794 "type": "string",10795 "enum": [10796 "paper",10797 "live"10798 ],10799 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."10800 },10801 "venue": {10802 "type": "string"10803 },10804 "accountId": {10805 "type": "string"10806 },10807 "instrument": {10808 "type": [10809 "string",10810 "null"10811 ]10812 },10813 "side": {10814 "type": "string",10815 "enum": [10816 "long",10817 "short"10818 ]10819 },10820 "size": {10821 "type": "string",10822 "description": "decimal number as a string (never a float)"10823 },10824 "entryPrice": {10825 "type": "string",10826 "description": "decimal number as a string (never a float)"10827 },10828 "markPrice": {10829 "anyOf": [10830 {10831 "type": "string",10832 "description": "decimal number as a string (never a float)"10833 },10834 {10835 "type": "null"10836 }10837 ]10838 },10839 "unrealizedPnl": {10840 "anyOf": [10841 {10842 "type": "string",10843 "description": "decimal number as a string (never a float)"10844 },10845 {10846 "type": "null"10847 }10848 ]10849 },10850 "source": {10851 "type": "string"10852 }10853 },10854 "required": [10855 "id",10856 "mode",10857 "venue",10858 "accountId",10859 "instrument",10860 "side",10861 "size",10862 "entryPrice",10863 "markPrice",10864 "unrealizedPnl",10865 "source"10866 ],10867 "additionalProperties": {}10868 }10869 },10870 "errors": {10871 "type": "array",10872 "items": {10873 "type": "object",10874 "properties": {10875 "source": {10876 "type": "string"10877 },10878 "message": {10879 "type": "string"10880 }10881 },10882 "required": [10883 "source",10884 "message"10885 ],10886 "additionalProperties": false10887 }10888 },10889 "ts": {10890 "type": "integer",10891 "minimum": -9007199254740991,10892 "maximum": 9007199254740991,10893 "description": "milliseconds since the Unix epoch"10894 }10895 },10896 "required": [10897 "positions",10898 "errors",10899 "ts"10900 ],10901 "additionalProperties": false10902 },10903 "example": {10904 "positions": [10905 {10906 "id": "paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC",10907 "mode": "paper",10908 "venue": "hyperliquid",10909 "network": "mainnet",10910 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",10911 "instrument": "hyperliquid:BTC",10912 "side": "long",10913 "size": "0.00155",10914 "entryPrice": "64432",10915 "markPrice": "64430.7",10916 "liquidationPrice": null,10917 "leverage": "3",10918 "margin": "33.289195",10919 "unrealizedPnl": "-0.002015",10920 "source": "paper"10921 }10922 ],10923 "errors": [],10924 "ts": 179495373143610925 }10926 }10927 }10928 },10929 "400": {10930 "description": "The request is not valid: `bad_request`",10931 "content": {10932 "application/json": {10933 "schema": {10934 "$ref": "#/components/schemas/Error"10935 }10936 }10937 }10938 },10939 "401": {10940 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",10941 "content": {10942 "application/json": {10943 "schema": {10944 "$ref": "#/components/schemas/Error"10945 }10946 }10947 }10948 },10949 "403": {10950 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",10951 "content": {10952 "application/json": {10953 "schema": {10954 "$ref": "#/components/schemas/Error"10955 }10956 }10957 }10958 },10959 "429": {10960 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",10961 "content": {10962 "application/json": {10963 "schema": {10964 "$ref": "#/components/schemas/Error"10965 }10966 }10967 }10968 },10969 "500": {10970 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",10971 "content": {10972 "application/json": {10973 "schema": {10974 "$ref": "#/components/schemas/Error"10975 }10976 }10977 }10978 },10979 "503": {10980 "description": "A backing service is unavailable; nothing was done: `service_unavailable`",10981 "content": {10982 "application/json": {10983 "schema": {10984 "$ref": "#/components/schemas/Error"10985 }10986 }10987 }10988 }10989 }10990 }10991 },10992 "/api/v1/trading/orders": {10993 "get": {10994 "operationId": "listOrders",10995 "tags": [10996 "Orders"10997 ],10998 "summary": "Orders, newest first",10999 "description": "Every order of the wallet — placed through this API, in the app or by an agent — in one stable order (creation time, then id), newest first. `status` is the unified state; `engineStatus` is the executing engine's own word. Paginated: `nextCursor` of a page is the `cursor` of the next; null at the end. An order created after the first page was read is not inserted into the pages that follow.",11000 "security": [11001 {11002 "bearerKey": [11003 "orders:read"11004 ]11005 }11006 ],11007 "x-spw-scope": "orders:read",11008 "x-spw-implemented": true,11009 "x-spw-errors": [11010 {11011 "status": 400,11012 "code": "bad_request"11013 },11014 {11015 "status": 400,11016 "code": "invalid_cursor"11017 },11018 {11019 "status": 401,11020 "code": "unauthenticated"11021 },11022 {11023 "status": 403,11024 "code": "insufficient_scope"11025 },11026 {11027 "status": 403,11028 "code": "ip_not_allowed"11029 },11030 {11031 "status": 403,11032 "code": "mixed_credentials"11033 },11034 {11035 "status": 403,11036 "code": "restricted"11037 },11038 {11039 "status": 429,11040 "code": "auth_throttled"11041 },11042 {11043 "status": 429,11044 "code": "rate_limited"11045 },11046 {11047 "status": 500,11048 "code": "internal"11049 }11050 ],11051 "x-spw-example-recorded": true,11052 "x-codeSamples": [11053 {11054 "lang": "Shell",11055 "label": "curl",11056 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/orders?open=true&limit=5\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""11057 },11058 {11059 "lang": "TypeScript",11060 "label": "TypeScript",11061 "source": "const { orders, nextCursor } = await client.listOrders({ open: true, limit: 5 });\nfor await (const order of client.iterateOrders({ open: true })) console.log(order.id, order.status); // every page"11062 },11063 {11064 "lang": "Python",11065 "label": "Python",11066 "source": "page = client.list_orders(open=True, limit=5)\nfor order in client.iter_orders(open=True): # every page\n print(order.id, order.status)"11067 }11068 ],11069 "parameters": [11070 {11071 "name": "mode",11072 "in": "query",11073 "required": false,11074 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure.",11075 "schema": {11076 "type": "string",11077 "enum": [11078 "paper",11079 "live"11080 ]11081 }11082 },11083 {11084 "name": "venue",11085 "in": "query",11086 "required": false,11087 "description": "venue id: hyperliquid, gmx, dydx, spot",11088 "schema": {11089 "type": "string",11090 "maxLength": 4011091 }11092 },11093 {11094 "name": "open",11095 "in": "query",11096 "required": false,11097 "description": "true: only orders that are not final; false: only final orders",11098 "schema": {11099 "type": "string",11100 "enum": [11101 "true",11102 "false"11103 ]11104 },11105 "example": "true"11106 },11107 {11108 "name": "limit",11109 "in": "query",11110 "required": false,11111 "description": "rows returned at most",11112 "schema": {11113 "default": 100,11114 "type": "integer",11115 "minimum": 1,11116 "maximum": 50011117 },11118 "example": 511119 },11120 {11121 "name": "cursor",11122 "in": "query",11123 "required": false,11124 "description": "opaque position returned as `nextCursor` by the previous page; send it with the same filters",11125 "schema": {11126 "type": "string",11127 "minLength": 1,11128 "maxLength": 400,11129 "pattern": "^[A-Za-z0-9_-]+$"11130 }11131 }11132 ],11133 "responses": {11134 "200": {11135 "description": "OK (the example is a recorded answer)",11136 "content": {11137 "application/json": {11138 "schema": {11139 "type": "object",11140 "properties": {11141 "orders": {11142 "type": "array",11143 "items": {11144 "$ref": "#/components/schemas/Order"11145 }11146 },11147 "nextCursor": {11148 "description": "pass it as `cursor` to read the next (older) page; null when there is none",11149 "type": [11150 "string",11151 "null"11152 ]11153 },11154 "ts": {11155 "type": "integer",11156 "minimum": -9007199254740991,11157 "maximum": 9007199254740991,11158 "description": "milliseconds since the Unix epoch"11159 }11160 },11161 "required": [11162 "orders",11163 "nextCursor",11164 "ts"11165 ],11166 "additionalProperties": false11167 },11168 "example": {11169 "orders": [11170 {11171 "id": "0x0276bab16d117c8323ee375b61b01d1d",11172 "orderId": "0x0276bab16d117c8323ee375b61b01d1d",11173 "mode": "paper",11174 "venue": "hyperliquid",11175 "network": "mainnet",11176 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",11177 "clientId": "0x0276bab16d117c8323ee375b61b01d1d",11178 "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",11179 "venueOrderId": "paper-o-11",11180 "instrument": "hyperliquid:BTC",11181 "side": "buy",11182 "type": "limit",11183 "size": "0.001",11184 "price": "63775",11185 "triggerPrice": null,11186 "reduceOnly": false,11187 "tif": "gtc",11188 "status": "SUBMITTED",11189 "final": false,11190 "reasonCode": "VENUE_ACCEPTED",11191 "reason": null,11192 "rejectCode": null,11193 "engineStatus": "open",11194 "filled": "0",11195 "avgFillPrice": null,11196 "acknowledged": true,11197 "cancelRequested": false,11198 "origin": "trading_api",11199 "principal": {11200 "kind": "api_key",11201 "id": "spk_0123456789ab"11202 },11203 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",11204 "engine": "paper",11205 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",11206 "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",11207 "notionalUsd": "63.775",11208 "projectionError": null,11209 "version": 4,11210 "createdAt": 1794953786427,11211 "updatedAt": 179495378644511212 }11213 ],11214 "nextCursor": null,11215 "ts": 179495378645211216 }11217 }11218 }11219 },11220 "400": {11221 "description": "The request is not valid: `bad_request`, `invalid_cursor`",11222 "content": {11223 "application/json": {11224 "schema": {11225 "$ref": "#/components/schemas/Error"11226 }11227 }11228 }11229 },11230 "401": {11231 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",11232 "content": {11233 "application/json": {11234 "schema": {11235 "$ref": "#/components/schemas/Error"11236 }11237 }11238 }11239 },11240 "403": {11241 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",11242 "content": {11243 "application/json": {11244 "schema": {11245 "$ref": "#/components/schemas/Error"11246 }11247 }11248 }11249 },11250 "429": {11251 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",11252 "content": {11253 "application/json": {11254 "schema": {11255 "$ref": "#/components/schemas/Error"11256 }11257 }11258 }11259 },11260 "500": {11261 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",11262 "content": {11263 "application/json": {11264 "schema": {11265 "$ref": "#/components/schemas/Error"11266 }11267 }11268 }11269 }11270 }11271 },11272 "post": {11273 "operationId": "placeOrder",11274 "tags": [11275 "Orders"11276 ],11277 "summary": "Place an order",11278 "description": "Idempotent on (principal, Idempotency-Key): a replay answers the same order and never sends a second request to a venue; the same key with a different order answers 409 `idempotency_conflict`.\n\nOwner session: the order is checked and waits `AWAITING_APPROVAL` until the owner approves it with the passkey in the app (paper: executed at once, nothing is signed).\n\nAPI key: needs a trading mandate bound to the key that covers the order exactly (403 `mandate_denied` with the reasons otherwise), then the risk engine, then the venue engine's mandate path — the isolated signer applies the derivative mandate it stores.\n\nLIVE needs `SPW_TRADING_API_EXECUTION=on` on the server (403 `execution_disabled` otherwise) and the existing mainnet locks. Live orders with a key exist on Hyperliquid only.\n\nA refusal after the order exists answers 4xx with the order in `data.order` (state `REJECTED` or `FAILED`). An outcome that is not known is `UNKNOWN`, never a failure.\n\nSpot orders: 403 `spot_execution_requires_agent_vault` for a key; 422 `spot_via_swap_screen` for the owner. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.",11279 "security": [11280 {11281 "bearerKey": [11282 "orders:execute"11283 ]11284 }11285 ],11286 "x-spw-scope": "orders:execute",11287 "x-spw-implemented": true,11288 "x-spw-requires-mandate": true,11289 "x-spw-idempotent": true,11290 "x-spw-errors": [11291 {11292 "status": 400,11293 "code": "bad_policy"11294 },11295 {11296 "status": 400,11297 "code": "bad_request"11298 },11299 {11300 "status": 400,11301 "code": "idempotency"11302 },11303 {11304 "status": 400,11305 "code": "invalid_order"11306 },11307 {11308 "status": 400,11309 "code": "stale_request"11310 },11311 {11312 "status": 401,11313 "code": "unauthenticated"11314 },11315 {11316 "status": 403,11317 "code": "execution_disabled"11318 },11319 {11320 "status": 403,11321 "code": "gmx_disabled"11322 },11323 {11324 "status": 403,11325 "code": "gmx_requires_owner_passkey"11326 },11327 {11328 "status": 403,11329 "code": "insufficient_scope"11330 },11331 {11332 "status": 403,11333 "code": "ip_not_allowed"11334 },11335 {11336 "status": 403,11337 "code": "key_limit_exceeded"11338 },11339 {11340 "status": 403,11341 "code": "mainnet_disabled"11342 },11343 {11344 "status": 403,11345 "code": "mandate_denied"11346 },11347 {11348 "status": 403,11349 "code": "mandate_integrity"11350 },11351 {11352 "status": 403,11353 "code": "mandate_mainnet_disabled"11354 },11355 {11356 "status": 403,11357 "code": "mandate_not_approved"11358 },11359 {11360 "status": 403,11361 "code": "mandate_required"11362 },11363 {11364 "status": 403,11365 "code": "mixed_credentials"11366 },11367 {11368 "status": 403,11369 "code": "owner_session_required"11370 },11371 {11372 "status": 403,11373 "code": "position_not_attributable"11374 },11375 {11376 "status": 403,11377 "code": "restricted"11378 },11379 {11380 "status": 403,11381 "code": "spot_execution_requires_agent_vault"11382 },11383 {11384 "status": 403,11385 "code": "venue_restricted"11386 },11387 {11388 "status": 404,11389 "code": "unknown_account"11390 },11391 {11392 "status": 404,11393 "code": "unknown_instrument"11394 },11395 {11396 "status": 404,11397 "code": "unknown_market"11398 },11399 {11400 "status": 404,11401 "code": "unknown_venue"11402 },11403 {11404 "status": 409,11405 "code": "account_has_active_mandate"11406 },11407 {11408 "status": 409,11409 "code": "account_required"11410 },11411 {11412 "status": 409,11413 "code": "ambiguous_command"11414 },11415 {11416 "status": 409,11417 "code": "ambiguous_order"11418 },11419 {11420 "status": 409,11421 "code": "ambiguous_symbol"11422 },11423 {11424 "status": 409,11425 "code": "bad_state"11426 },11427 {11428 "status": 409,11429 "code": "idempotency_conflict"11430 },11431 {11432 "status": 409,11433 "code": "idempotency_in_progress"11434 },11435 {11436 "status": 422,11437 "code": "authorization_expired"11438 },11439 {11440 "status": 422,11441 "code": "bad_input"11442 },11443 {11444 "status": 422,11445 "code": "bad_mark"11446 },11447 {11448 "status": 422,11449 "code": "bad_order"11450 },11451 {11452 "status": 422,11453 "code": "bad_policy"11454 },11455 {11456 "status": 422,11457 "code": "below_min_notional"11458 },11459 {11460 "status": 422,11461 "code": "below_min_size"11462 },11463 {11464 "status": 422,11465 "code": "daily_loss_exceeded"11466 },11467 {11468 "status": 422,11469 "code": "data_mismatch"11470 },11471 {11472 "status": 422,11473 "code": "duplicate_client_id"11474 },11475 {11476 "status": 422,11477 "code": "fee_cap_not_expressible"11478 },11479 {11480 "status": 422,11481 "code": "gmx_leverage_required"11482 },11483 {11484 "status": 422,11485 "code": "gross_exposure_exceeded"11486 },11487 {11488 "status": 422,11489 "code": "halted"11490 },11491 {11492 "status": 422,11493 "code": "inconsistent_prices"11494 },11495 {11496 "status": 422,11497 "code": "instrument_halted"11498 },11499 {11500 "status": 422,11501 "code": "instrument_mismatch"11502 },11503 {11504 "status": 422,11505 "code": "instrument_not_allowed"11506 },11507 {11508 "status": 422,11509 "code": "instrument_reduce_only"11510 },11511 {11512 "status": 422,11513 "code": "insufficient_collateral"11514 },11515 {11516 "status": 422,11517 "code": "invalid_order"11518 },11519 {11520 "status": 422,11521 "code": "leverage_exceeded"11522 },11523 {11524 "status": 422,11525 "code": "leverage_mismatch"11526 },11527 {11528 "status": 422,11529 "code": "liquidation_too_close"11530 },11531 {11532 "status": 422,11533 "code": "live_not_available"11534 },11535 {11536 "status": 422,11537 "code": "mandate_mismatch"11538 },11539 {11540 "status": 422,11541 "code": "mandate_none"11542 },11543 {11544 "status": 422,11545 "code": "mandate_wind_down"11546 },11547 {11548 "status": 422,11549 "code": "mark_index_divergence"11550 },11551 {11552 "status": 422,11553 "code": "missing_balance"11554 },11555 {11556 "status": 422,11557 "code": "missing_reference_price"11558 },11559 {11560 "status": 422,11561 "code": "mode_read_only"11562 },11563 {11564 "status": 422,11565 "code": "no_account"11566 },11567 {11568 "status": 422,11569 "code": "no_client_id_format"11570 },11571 {11572 "status": 422,11573 "code": "no_instrument"11574 },11575 {11576 "status": 422,11577 "code": "no_position"11578 },11579 {11580 "status": 422,11581 "code": "order_notional_exceeded"11582 },11583 {11584 "status": 422,11585 "code": "order_rate_day"11586 },11587 {11588 "status": 422,11589 "code": "order_rate_minute"11590 },11591 {11592 "status": 422,11593 "code": "paper_unsupported"11594 },11595 {11596 "status": 422,11597 "code": "position_notional_exceeded"11598 },11599 {11600 "status": 422,11601 "code": "price_deviation"11602 },11603 {11604 "status": 422,11605 "code": "price_not_on_tick"11606 },11607 {11608 "status": 422,11609 "code": "price_required"11610 },11611 {11612 "status": 422,11613 "code": "reduce_only_would_flip"11614 },11615 {11616 "status": 422,11617 "code": "reduce_only_would_increase"11618 },11619 {11620 "status": 422,11621 "code": "risk_denied"11622 },11623 {11624 "status": 422,11625 "code": "size_not_on_lot"11626 },11627 {11628 "status": 422,11629 "code": "spot_buy_needs_quote_amount"11630 },11631 {11632 "status": 422,11633 "code": "spot_market_only"11634 },11635 {11636 "status": 422,11637 "code": "spot_paper_not_available"11638 },11639 {11640 "status": 422,11641 "code": "spot_via_swap_screen"11642 },11643 {11644 "status": 422,11645 "code": "stale_book"11646 },11647 {11648 "status": 422,11649 "code": "stale_ticker"11650 },11651 {11652 "status": 422,11653 "code": "swap_not_enabled"11654 },11655 {11656 "status": 422,11657 "code": "total_loss_exceeded"11658 },11659 {11660 "status": 422,11661 "code": "trigger_required"11662 },11663 {11664 "status": 422,11665 "code": "unknown_instrument"11666 },11667 {11668 "status": 422,11669 "code": "unsupported_asset"11670 },11671 {11672 "status": 422,11673 "code": "venue_not_wired"11674 },11675 {11676 "status": 422,11677 "code": "venue_rejected"11678 },11679 {11680 "status": 422,11681 "code": "zero_size"11682 },11683 {11684 "status": 423,11685 "code": "halted"11686 },11687 {11688 "status": 423,11689 "code": "kill_switch_active"11690 },11691 {11692 "status": 423,11693 "code": "read_only_mode"11694 },11695 {11696 "status": 429,11697 "code": "auth_throttled"11698 },11699 {11700 "status": 429,11701 "code": "rate_limited"11702 },11703 {11704 "status": 500,11705 "code": "internal"11706 },11707 {11708 "status": 501,11709 "code": "execution_not_wired"11710 },11711 {11712 "status": 502,11713 "code": "swap_flow_failed"11714 },11715 {11716 "status": 503,11717 "code": "authorization_unknown"11718 },11719 {11720 "status": 503,11721 "code": "mandate_unavailable"11722 },11723 {11724 "status": 503,11725 "code": "no_liquidity"11726 },11727 {11728 "status": 503,11729 "code": "signer_unreachable"11730 },11731 {11732 "status": 503,11733 "code": "stale_data"11734 },11735 {11736 "status": 503,11737 "code": "unknown_instrument"11738 },11739 {11740 "status": 503,11741 "code": "venue_rate_limited"11742 },11743 {11744 "status": 503,11745 "code": "venue_timeout"11746 },11747 {11748 "status": 503,11749 "code": "venue_unavailable"11750 }11751 ],11752 "x-spw-errors-open": true,11753 "x-spw-example-recorded": true,11754 "x-spw-example-note": "A paper market order is filled at once by the paper engine against the real Hyperliquid book: `status` is already `FILLED`.",11755 "x-codeSamples": [11756 {11757 "lang": "Shell",11758 "label": "curl",11759 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/orders\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"mode\":\"paper\",\"instrument\":\"hyperliquid:BTC\",\"side\":\"buy\",\"type\":\"market\",\"notional\":\"100\"}'"11760 },11761 {11762 "lang": "TypeScript",11763 "label": "TypeScript",11764 "source": "const placed = await client.createOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' }, { idempotencyKey: 'bot-2026-11-17-0001' });"11765 },11766 {11767 "lang": "Python",11768 "label": "Python",11769 "source": "placed = client.create_order(mode=\"paper\", instrument=\"hyperliquid:BTC\", side=\"buy\", order_type=\"market\", notional=\"100\", idempotency_key=\"bot-2026-11-17-0001\")"11770 }11771 ],11772 "parameters": [11773 {11774 "name": "Idempotency-Key",11775 "in": "header",11776 "required": true,11777 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",11778 "schema": {11779 "type": "string",11780 "pattern": "^[A-Za-z0-9._:-]{8,100}$"11781 }11782 },11783 {11784 "name": "X-SPW-Timestamp",11785 "in": "header",11786 "required": false,11787 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",11788 "schema": {11789 "type": "string",11790 "pattern": "^\\d{9,11}$"11791 }11792 }11793 ],11794 "requestBody": {11795 "required": true,11796 "content": {11797 "application/json": {11798 "schema": {11799 "type": "object",11800 "properties": {11801 "mode": {11802 "type": "string",11803 "enum": [11804 "paper",11805 "live"11806 ],11807 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."11808 },11809 "accountId": {11810 "description": "paper account or venue account; required when the wallet has several on the venue",11811 "type": "string",11812 "format": "uuid",11813 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"11814 },11815 "instrument": {11816 "type": "string",11817 "minLength": 1,11818 "maxLength": 120,11819 "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"11820 },11821 "side": {11822 "type": "string",11823 "enum": [11824 "buy",11825 "sell"11826 ],11827 "description": "buy opens or adds to a long (or reduces a short); sell the reverse"11828 },11829 "type": {11830 "type": "string",11831 "enum": [11832 "limit",11833 "market",11834 "stop_market",11835 "stop_limit",11836 "take_profit_market",11837 "take_profit_limit"11838 ],11839 "description": "market: immediate, bounded by `slippageBps`. limit: rests at `price`. stop_* and take_profit_*: wait for `triggerPrice`, then act as a market order or as a limit order at `price`"11840 },11841 "size": {11842 "description": "quantity of the base asset. Exactly one of `size` and `notional` is required",11843 "type": "string",11844 "pattern": "^\\d+(\\.\\d+)?$"11845 },11846 "notional": {11847 "description": "value of the order in the quote currency of the instrument (USD or a USD stablecoin on every venue of this wallet). The SERVER turns it into a size: notional / reference price, rounded DOWN to the lot size — the reference is the limit price, else the trigger price, else the mark price read now (503 `stale_data` when it is stale; 422 `below_min_size` under one lot). The answer carries the size that was used. Exactly one of `size` and `notional` is required. A SPOT order: a SELL names `size` (the quantity sold); a BUY names `notional` — the amount of the quote asset to spend — because a swap is exact-input",11848 "type": "string",11849 "pattern": "^\\d+(\\.\\d+)?$"11850 },11851 "price": {11852 "description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",11853 "type": "string",11854 "pattern": "^\\d+(\\.\\d+)?$"11855 },11856 "triggerPrice": {11857 "description": "price at which a stop or take-profit order is triggered; required by the four trigger types",11858 "type": "string",11859 "pattern": "^\\d+(\\.\\d+)?$"11860 },11861 "reduceOnly": {11862 "default": false,11863 "description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",11864 "type": "boolean"11865 },11866 "tif": {11867 "default": "gtc",11868 "description": "time in force of a limit order: gtc = rests until cancelled, ioc = fills what it can at once and cancels the rest, alo = add liquidity only (post-only)",11869 "type": "string",11870 "enum": [11871 "gtc",11872 "ioc",11873 "alo"11874 ]11875 },11876 "slippageBps": {11877 "description": "market orders: the worst acceptable price, in basis points from the reference price",11878 "type": "integer",11879 "minimum": 1,11880 "maximum": 50011881 },11882 "leverage": {11883 "description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",11884 "type": "string",11885 "pattern": "^\\d+(\\.\\d+)?$"11886 },11887 "maxFeeUsd": {11888 "description": "highest fee accepted, USD; default: 10 bps of the notional",11889 "type": "string",11890 "pattern": "^\\d+(\\.\\d+)?$"11891 },11892 "clientOrderId": {11893 "description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",11894 "type": "string",11895 "pattern": "^[A-Za-z0-9._:-]{8,100}$"11896 }11897 },11898 "required": [11899 "mode",11900 "instrument",11901 "side",11902 "type"11903 ],11904 "additionalProperties": false11905 },11906 "example": {11907 "mode": "paper",11908 "instrument": "hyperliquid:BTC",11909 "side": "buy",11910 "type": "market",11911 "notional": "100"11912 }11913 }11914 }11915 },11916 "responses": {11917 "200": {11918 "description": "OK (the example is a recorded answer)",11919 "content": {11920 "application/json": {11921 "schema": {11922 "type": "object",11923 "properties": {11924 "order": {11925 "$ref": "#/components/schemas/Order"11926 },11927 "idempotent": {11928 "type": "boolean",11929 "description": "true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again"11930 },11931 "approval": {11932 "anyOf": [11933 {11934 "type": "object",11935 "properties": {11936 "by": {11937 "type": "string"11938 },11939 "engine": {11940 "type": "string"11941 },11942 "accountId": {11943 "type": "string"11944 },11945 "clientId": {11946 "type": "string"11947 },11948 "hash": {11949 "type": [11950 "string",11951 "null"11952 ]11953 },11954 "expiresAt": {11955 "anyOf": [11956 {11957 "type": "integer",11958 "minimum": -9007199254740991,11959 "maximum": 9007199254740991,11960 "description": "milliseconds since the Unix epoch"11961 },11962 {11963 "type": "null"11964 }11965 ]11966 },11967 "approve": {11968 "type": "object",11969 "properties": {11970 "method": {11971 "type": "string"11972 },11973 "path": {11974 "type": "string"11975 }11976 },11977 "required": [11978 "method",11979 "path"11980 ],11981 "additionalProperties": {}11982 }11983 },11984 "required": [11985 "by",11986 "engine",11987 "accountId",11988 "clientId",11989 "hash",11990 "expiresAt",11991 "approve"11992 ],11993 "additionalProperties": {}11994 },11995 {11996 "type": "null"11997 }11998 ],11999 "description": "set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key"12000 }12001 },12002 "required": [12003 "order",12004 "idempotent",12005 "approval"12006 ],12007 "additionalProperties": {}12008 },12009 "example": {12010 "order": {12011 "id": "0xff18683e8e2aa319d3812cf8a47fc261",12012 "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",12013 "mode": "paper",12014 "venue": "hyperliquid",12015 "network": "mainnet",12016 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",12017 "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",12018 "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",12019 "venueOrderId": "paper-o-1",12020 "instrument": "hyperliquid:BTC",12021 "side": "buy",12022 "type": "market",12023 "size": "0.00155",12024 "price": "64754",12025 "triggerPrice": null,12026 "reduceOnly": false,12027 "tif": "ioc",12028 "status": "FILLED",12029 "final": true,12030 "reasonCode": "VENUE_FILLED",12031 "reason": null,12032 "rejectCode": null,12033 "engineStatus": "filled",12034 "filled": "0.00155",12035 "avgFillPrice": "64432",12036 "acknowledged": true,12037 "cancelRequested": false,12038 "origin": "trading_api",12039 "principal": {12040 "kind": "api_key",12041 "id": "spk_0123456789ab"12042 },12043 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",12044 "engine": "paper",12045 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",12046 "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",12047 "notionalUsd": "100.3687",12048 "projectionError": null,12049 "version": 4,12050 "createdAt": 1794953729578,12051 "updatedAt": 179495372960212052 },12053 "idempotent": false,12054 "approval": null12055 }12056 }12057 }12058 },12059 "400": {12060 "description": "The request is not valid: `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request`",12061 "content": {12062 "application/json": {12063 "schema": {12064 "$ref": "#/components/schemas/Error"12065 }12066 }12067 }12068 },12069 "401": {12070 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",12071 "content": {12072 "application/json": {12073 "schema": {12074 "$ref": "#/components/schemas/Error"12075 }12076 }12077 }12078 },12079 "403": {12080 "description": "Authenticated, and refused: `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted`",12081 "content": {12082 "application/json": {12083 "schema": {12084 "$ref": "#/components/schemas/Error"12085 }12086 }12087 }12088 },12089 "404": {12090 "description": "The object named by the request does not exist: `unknown_account`, `unknown_instrument`, `unknown_market`, `unknown_venue`",12091 "content": {12092 "application/json": {12093 "schema": {12094 "$ref": "#/components/schemas/Error"12095 }12096 }12097 }12098 },12099 "409": {12100 "description": "The request conflicts with the state of the object, or needs a choice: `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_symbol`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",12101 "content": {12102 "application/json": {12103 "schema": {12104 "$ref": "#/components/schemas/Error"12105 }12106 }12107 }12108 },12109 "422": {12110 "description": "A valid request that cannot be carried out: `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size`",12111 "content": {12112 "application/json": {12113 "schema": {12114 "$ref": "#/components/schemas/Error"12115 }12116 }12117 }12118 },12119 "423": {12120 "description": "Blocked by the kill switch, by read-only mode or by a halt: `halted`, `kill_switch_active`, `read_only_mode`",12121 "content": {12122 "application/json": {12123 "schema": {12124 "$ref": "#/components/schemas/Error"12125 }12126 }12127 }12128 },12129 "429": {12130 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",12131 "content": {12132 "application/json": {12133 "schema": {12134 "$ref": "#/components/schemas/Error"12135 }12136 }12137 }12138 },12139 "500": {12140 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",12141 "content": {12142 "application/json": {12143 "schema": {12144 "$ref": "#/components/schemas/Error"12145 }12146 }12147 }12148 },12149 "501": {12150 "description": "Declared but not connected yet. Never a success: nothing was done: `execution_not_wired`",12151 "content": {12152 "application/json": {12153 "schema": {12154 "$ref": "#/components/schemas/Error"12155 }12156 }12157 }12158 },12159 "502": {12160 "description": "Error: `swap_flow_failed`",12161 "content": {12162 "application/json": {12163 "schema": {12164 "$ref": "#/components/schemas/Error"12165 }12166 }12167 }12168 },12169 "503": {12170 "description": "A backing service is unavailable; nothing was done: `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",12171 "content": {12172 "application/json": {12173 "schema": {12174 "$ref": "#/components/schemas/Error"12175 }12176 }12177 }12178 }12179 }12180 }12181 },12182 "/api/v1/trading/orders/{id}": {12183 "get": {12184 "operationId": "getOrder",12185 "tags": [12186 "Orders"12187 ],12188 "summary": "One order and its fills",12189 "description": "The order in its unified state, its fills, and `history`: every transition it went through, oldest first, with the event and the reason code. Poll this to follow an order until `final` is true (both SDKs: `waitForOrder` / `wait_for_order`); `UNKNOWN` is not final — keep reading.",12190 "security": [12191 {12192 "bearerKey": [12193 "orders:read"12194 ]12195 }12196 ],12197 "x-spw-scope": "orders:read",12198 "x-spw-implemented": true,12199 "x-spw-errors": [12200 {12201 "status": 400,12202 "code": "bad_request"12203 },12204 {12205 "status": 401,12206 "code": "unauthenticated"12207 },12208 {12209 "status": 403,12210 "code": "insufficient_scope"12211 },12212 {12213 "status": 403,12214 "code": "ip_not_allowed"12215 },12216 {12217 "status": 403,12218 "code": "mixed_credentials"12219 },12220 {12221 "status": 403,12222 "code": "restricted"12223 },12224 {12225 "status": 404,12226 "code": "unknown_order"12227 },12228 {12229 "status": 429,12230 "code": "auth_throttled"12231 },12232 {12233 "status": 429,12234 "code": "rate_limited"12235 },12236 {12237 "status": 500,12238 "code": "internal"12239 }12240 ],12241 "x-spw-example-recorded": true,12242 "x-spw-example-note": "Fills and history cut to two entries.",12243 "x-codeSamples": [12244 {12245 "lang": "Shell",12246 "label": "curl",12247 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/orders/0xff18683e8e2aa319d3812cf8a47fc261\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""12248 },12249 {12250 "lang": "TypeScript",12251 "label": "TypeScript",12252 "source": "const { order, fills } = await client.getOrder('0xff18683e8e2aa319d3812cf8a47fc261');\nconst done = await client.waitForOrder('0xff18683e8e2aa319d3812cf8a47fc261'); // polls until final; UNKNOWN keeps waiting"12253 },12254 {12255 "lang": "Python",12256 "label": "Python",12257 "source": "detail = client.get_order(\"0xff18683e8e2aa319d3812cf8a47fc261\")\ndone = client.wait_for_order(\"0xff18683e8e2aa319d3812cf8a47fc261\") # polls until final; UNKNOWN keeps waiting"12258 }12259 ],12260 "parameters": [12261 {12262 "name": "id",12263 "in": "path",12264 "required": true,12265 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",12266 "schema": {12267 "type": "string",12268 "minLength": 1,12269 "maxLength": 20012270 },12271 "example": "0xff18683e8e2aa319d3812cf8a47fc261"12272 }12273 ],12274 "responses": {12275 "200": {12276 "description": "OK (the example is a recorded answer)",12277 "content": {12278 "application/json": {12279 "schema": {12280 "type": "object",12281 "properties": {12282 "order": {12283 "$ref": "#/components/schemas/Order"12284 },12285 "fills": {12286 "type": "array",12287 "items": {12288 "type": "object",12289 "properties": {12290 "id": {12291 "type": "string"12292 },12293 "instrument": {12294 "type": "string"12295 },12296 "side": {12297 "type": "string"12298 },12299 "price": {12300 "type": "string",12301 "description": "decimal number as a string (never a float)"12302 },12303 "size": {12304 "type": "string",12305 "description": "decimal number as a string (never a float)"12306 },12307 "fee": {12308 "type": "string",12309 "description": "decimal number as a string (never a float)"12310 },12311 "feeAsset": {12312 "type": "string"12313 },12314 "closedPnl": {12315 "anyOf": [12316 {12317 "type": "string",12318 "description": "decimal number as a string (never a float)"12319 },12320 {12321 "type": "null"12322 }12323 ]12324 },12325 "liquidation": {12326 "type": "boolean"12327 },12328 "ts": {12329 "type": "integer",12330 "minimum": -9007199254740991,12331 "maximum": 9007199254740991,12332 "description": "milliseconds since the Unix epoch"12333 }12334 },12335 "required": [12336 "id",12337 "instrument",12338 "side",12339 "price",12340 "size",12341 "fee",12342 "feeAsset",12343 "closedPnl",12344 "liquidation",12345 "ts"12346 ],12347 "additionalProperties": {}12348 }12349 },12350 "history": {12351 "description": "the transitions of the order, oldest first (absent for `agent:` rows)",12352 "type": "array",12353 "items": {12354 "type": "object",12355 "properties": {},12356 "additionalProperties": {}12357 }12358 }12359 },12360 "required": [12361 "order",12362 "fills"12363 ],12364 "additionalProperties": {}12365 },12366 "example": {12367 "order": {12368 "id": "0xff18683e8e2aa319d3812cf8a47fc261",12369 "orderId": "0xff18683e8e2aa319d3812cf8a47fc261",12370 "mode": "paper",12371 "venue": "hyperliquid",12372 "network": "mainnet",12373 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",12374 "clientId": "0xff18683e8e2aa319d3812cf8a47fc261",12375 "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",12376 "venueOrderId": "paper-o-1",12377 "instrument": "hyperliquid:BTC",12378 "side": "buy",12379 "type": "market",12380 "size": "0.00155",12381 "price": "64754",12382 "triggerPrice": null,12383 "reduceOnly": false,12384 "tif": "ioc",12385 "status": "FILLED",12386 "final": true,12387 "reasonCode": "VENUE_FILLED",12388 "reason": null,12389 "rejectCode": null,12390 "engineStatus": "filled",12391 "filled": "0.00155",12392 "avgFillPrice": "64432",12393 "acknowledged": true,12394 "cancelRequested": false,12395 "origin": "trading_api",12396 "principal": {12397 "kind": "api_key",12398 "id": "spk_0123456789ab"12399 },12400 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",12401 "engine": "paper",12402 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xff18683e8e2aa319d3812cf8a47fc261",12403 "hash": "1d3481aaee13d8c193c215ba06f786da1cc978c805d9d2f57a102564ddf5c386",12404 "notionalUsd": "100.3687",12405 "projectionError": null,12406 "version": 4,12407 "createdAt": 1794953729578,12408 "updatedAt": 1794953729602,12409 "canonical": {12410 "v": 1,12411 "tif": "ioc",12412 "mode": "paper",12413 "side": "buy",12414 "size": "0.00155",12415 "type": "market",12416 "venue": "hyperliquid",12417 "network": "mainnet",12418 "leverage": null,12419 "notional": null,12420 "createdAt": 1794953729578,12421 "expiresAt": 1794953849578,12422 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",12423 "maxFeeUsd": "0.099869",12424 "principal": {12425 "id": "spk_0123456789ab",12426 "kind": "api_key"12427 },12428 "instrument": "hyperliquid:BTC",12429 "limitPrice": null,12430 "marginMode": null,12431 "marketKind": "perp",12432 "reduceOnly": false,12433 "triggerPrice": null,12434 "clientOrderId": "0xff18683e8e2aa319d3812cf8a47fc261",12435 "maxSlippageBps": 5012436 }12437 },12438 "fills": [12439 {12440 "id": "paper-f-2",12441 "instrument": "hyperliquid:BTC",12442 "side": "buy",12443 "price": "64432",12444 "size": "0.00155",12445 "fee": "0.04494132",12446 "feeAsset": "USDC",12447 "closedPnl": null,12448 "liquidation": false,12449 "ts": 179495372959512450 }12451 ],12452 "history": [12453 {12454 "seq": 1,12455 "from": "CREATED",12456 "to": "VALIDATED",12457 "event": "validated",12458 "reason": "VALIDATION_PASSED",12459 "detail": null,12460 "at": 179495372959012461 },12462 {12463 "seq": 2,12464 "from": "VALIDATED",12465 "to": "APPROVED",12466 "event": "approved",12467 "reason": "APPROVED_BY_MANDATE",12468 "detail": null,12469 "at": 179495372959312470 }12471 ]12472 }12473 }12474 }12475 },12476 "400": {12477 "description": "The request is not valid: `bad_request`",12478 "content": {12479 "application/json": {12480 "schema": {12481 "$ref": "#/components/schemas/Error"12482 }12483 }12484 }12485 },12486 "401": {12487 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",12488 "content": {12489 "application/json": {12490 "schema": {12491 "$ref": "#/components/schemas/Error"12492 }12493 }12494 }12495 },12496 "403": {12497 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",12498 "content": {12499 "application/json": {12500 "schema": {12501 "$ref": "#/components/schemas/Error"12502 }12503 }12504 }12505 },12506 "404": {12507 "description": "The object named by the request does not exist: `unknown_order`",12508 "content": {12509 "application/json": {12510 "schema": {12511 "$ref": "#/components/schemas/Error"12512 }12513 }12514 }12515 },12516 "429": {12517 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",12518 "content": {12519 "application/json": {12520 "schema": {12521 "$ref": "#/components/schemas/Error"12522 }12523 }12524 }12525 },12526 "500": {12527 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",12528 "content": {12529 "application/json": {12530 "schema": {12531 "$ref": "#/components/schemas/Error"12532 }12533 }12534 }12535 }12536 }12537 },12538 "delete": {12539 "operationId": "cancelOrder",12540 "tags": [12541 "Orders"12542 ],12543 "summary": "Cancel an order",12544 "description": "A key cancels its OWN orders only (403 `not_your_order`); no trading mandate is required, and the kill switch and read-only mode never stop a cancel: it can only remove what could still execute. At the venue the order is `CANCELLED` when the venue says so. An order that is already final answers 200 with `changed: false`.",12545 "security": [12546 {12547 "bearerKey": [12548 "orders:cancel"12549 ]12550 }12551 ],12552 "x-spw-scope": "orders:cancel",12553 "x-spw-implemented": true,12554 "x-spw-idempotent": true,12555 "x-spw-errors": [12556 {12557 "status": 400,12558 "code": "bad_request"12559 },12560 {12561 "status": 400,12562 "code": "idempotency"12563 },12564 {12565 "status": 400,12566 "code": "stale_request"12567 },12568 {12569 "status": 401,12570 "code": "unauthenticated"12571 },12572 {12573 "status": 403,12574 "code": "gmx_requires_owner_passkey"12575 },12576 {12577 "status": 403,12578 "code": "insufficient_scope"12579 },12580 {12581 "status": 403,12582 "code": "ip_not_allowed"12583 },12584 {12585 "status": 403,12586 "code": "mixed_credentials"12587 },12588 {12589 "status": 403,12590 "code": "not_your_order"12591 },12592 {12593 "status": 403,12594 "code": "owner_session_required"12595 },12596 {12597 "status": 404,12598 "code": "unknown_order"12599 },12600 {12601 "status": 409,12602 "code": "bad_state"12603 },12604 {12605 "status": 409,12606 "code": "idempotency_conflict"12607 },12608 {12609 "status": 409,12610 "code": "idempotency_in_progress"12611 },12612 {12613 "status": 422,12614 "code": "cancel_in_app"12615 },12616 {12617 "status": 422,12618 "code": "venue_rejected"12619 },12620 {12621 "status": 429,12622 "code": "auth_throttled"12623 },12624 {12625 "status": 429,12626 "code": "rate_limited"12627 },12628 {12629 "status": 500,12630 "code": "internal"12631 },12632 {12633 "status": 503,12634 "code": "signer_unreachable"12635 },12636 {12637 "status": 503,12638 "code": "venue_unavailable"12639 }12640 ],12641 "x-spw-example-recorded": true,12642 "x-spw-example-note": "Cancelling again answers 200 with `changed: false`.",12643 "x-codeSamples": [12644 {12645 "lang": "Shell",12646 "label": "curl",12647 "source": "curl -s -X DELETE \"$SP_WALLET_BASE_URL/api/v1/trading/orders/0x0276bab16d117c8323ee375b61b01d1d\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\""12648 },12649 {12650 "lang": "TypeScript",12651 "label": "TypeScript",12652 "source": "const { order, changed } = await client.cancelOrder('0x0276bab16d117c8323ee375b61b01d1d');"12653 },12654 {12655 "lang": "Python",12656 "label": "Python",12657 "source": "cancelled = client.cancel_order(\"0x0276bab16d117c8323ee375b61b01d1d\")"12658 }12659 ],12660 "parameters": [12661 {12662 "name": "id",12663 "in": "path",12664 "required": true,12665 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",12666 "schema": {12667 "type": "string",12668 "minLength": 1,12669 "maxLength": 20012670 },12671 "example": "0x0276bab16d117c8323ee375b61b01d1d"12672 },12673 {12674 "name": "Idempotency-Key",12675 "in": "header",12676 "required": true,12677 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",12678 "schema": {12679 "type": "string",12680 "pattern": "^[A-Za-z0-9._:-]{8,100}$"12681 }12682 },12683 {12684 "name": "X-SPW-Timestamp",12685 "in": "header",12686 "required": false,12687 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",12688 "schema": {12689 "type": "string",12690 "pattern": "^\\d{9,11}$"12691 }12692 }12693 ],12694 "responses": {12695 "200": {12696 "description": "OK (the example is a recorded answer)",12697 "content": {12698 "application/json": {12699 "schema": {12700 "type": "object",12701 "properties": {12702 "order": {12703 "$ref": "#/components/schemas/Order"12704 },12705 "sent": {12706 "type": "boolean",12707 "description": "true: a cancel request went to a venue"12708 },12709 "changed": {12710 "type": "boolean",12711 "description": "false: the order was already final"12712 },12713 "venue": {}12714 },12715 "required": [12716 "order",12717 "sent",12718 "changed"12719 ],12720 "additionalProperties": {}12721 },12722 "example": {12723 "order": {12724 "id": "0x0276bab16d117c8323ee375b61b01d1d",12725 "orderId": "0x0276bab16d117c8323ee375b61b01d1d",12726 "mode": "paper",12727 "venue": "hyperliquid",12728 "network": "mainnet",12729 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",12730 "clientId": "0x0276bab16d117c8323ee375b61b01d1d",12731 "clientOrderId": "0x0276bab16d117c8323ee375b61b01d1d",12732 "venueOrderId": "paper-o-11",12733 "instrument": "hyperliquid:BTC",12734 "side": "buy",12735 "type": "limit",12736 "size": "0.001",12737 "price": "63775",12738 "triggerPrice": null,12739 "reduceOnly": false,12740 "tif": "gtc",12741 "status": "CANCELLED",12742 "final": true,12743 "reasonCode": "CANCELLED_BY_REQUEST",12744 "reason": "cancelled by the user",12745 "rejectCode": null,12746 "engineStatus": "cancelled",12747 "filled": "0",12748 "avgFillPrice": null,12749 "acknowledged": true,12750 "cancelRequested": true,12751 "origin": "trading_api",12752 "principal": {12753 "kind": "api_key",12754 "id": "spk_0123456789ab"12755 },12756 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",12757 "engine": "paper",12758 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0x0276bab16d117c8323ee375b61b01d1d",12759 "hash": "b4864b795d2a07f377c362c714fbafefd82cf6ce9ec67c88fffb0ccd157a62ff",12760 "notionalUsd": "63.775",12761 "projectionError": null,12762 "version": 6,12763 "createdAt": 1794953786427,12764 "updatedAt": 179495378645912765 },12766 "sent": false,12767 "changed": true,12768 "venue": null12769 }12770 }12771 }12772 },12773 "400": {12774 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",12775 "content": {12776 "application/json": {12777 "schema": {12778 "$ref": "#/components/schemas/Error"12779 }12780 }12781 }12782 },12783 "401": {12784 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",12785 "content": {12786 "application/json": {12787 "schema": {12788 "$ref": "#/components/schemas/Error"12789 }12790 }12791 }12792 },12793 "403": {12794 "description": "Authenticated, and refused: `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `not_your_order`, `owner_session_required`",12795 "content": {12796 "application/json": {12797 "schema": {12798 "$ref": "#/components/schemas/Error"12799 }12800 }12801 }12802 },12803 "404": {12804 "description": "The object named by the request does not exist: `unknown_order`",12805 "content": {12806 "application/json": {12807 "schema": {12808 "$ref": "#/components/schemas/Error"12809 }12810 }12811 }12812 },12813 "409": {12814 "description": "The request conflicts with the state of the object, or needs a choice: `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",12815 "content": {12816 "application/json": {12817 "schema": {12818 "$ref": "#/components/schemas/Error"12819 }12820 }12821 }12822 },12823 "422": {12824 "description": "A valid request that cannot be carried out: `cancel_in_app`, `venue_rejected`",12825 "content": {12826 "application/json": {12827 "schema": {12828 "$ref": "#/components/schemas/Error"12829 }12830 }12831 }12832 },12833 "429": {12834 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",12835 "content": {12836 "application/json": {12837 "schema": {12838 "$ref": "#/components/schemas/Error"12839 }12840 }12841 }12842 },12843 "500": {12844 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",12845 "content": {12846 "application/json": {12847 "schema": {12848 "$ref": "#/components/schemas/Error"12849 }12850 }12851 }12852 },12853 "503": {12854 "description": "A backing service is unavailable; nothing was done: `signer_unreachable`, `venue_unavailable`",12855 "content": {12856 "application/json": {12857 "schema": {12858 "$ref": "#/components/schemas/Error"12859 }12860 }12861 }12862 }12863 }12864 }12865 },12866 "/api/v1/trading/strategies": {12867 "get": {12868 "operationId": "listStrategies",12869 "tags": [12870 "Strategies"12871 ],12872 "summary": "Strategy library and the versions pinned to agents",12873 "description": "`library`: the strategy files installed in the laboratory, each with its `path` (what POST /strategies takes) and the SHA-256 of the file. `versions`: the versions registered on agents, with their status. A source that cannot be read is listed in `errors`.",12874 "security": [12875 {12876 "bearerKey": [12877 "strategies:read"12878 ]12879 }12880 ],12881 "x-spw-scope": "strategies:read",12882 "x-spw-implemented": true,12883 "x-spw-errors": [12884 {12885 "status": 400,12886 "code": "bad_request"12887 },12888 {12889 "status": 401,12890 "code": "unauthenticated"12891 },12892 {12893 "status": 403,12894 "code": "insufficient_scope"12895 },12896 {12897 "status": 403,12898 "code": "ip_not_allowed"12899 },12900 {12901 "status": 403,12902 "code": "mixed_credentials"12903 },12904 {12905 "status": 429,12906 "code": "auth_throttled"12907 },12908 {12909 "status": 429,12910 "code": "rate_limited"12911 },12912 {12913 "status": 500,12914 "code": "internal"12915 }12916 ],12917 "x-spw-example-recorded": true,12918 "x-spw-example-note": "Cut to one library entry and one version.",12919 "x-codeSamples": [12920 {12921 "lang": "Shell",12922 "label": "curl",12923 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/strategies?kind=perp\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""12924 },12925 {12926 "lang": "TypeScript",12927 "label": "TypeScript",12928 "source": "const { library, versions } = await client.listStrategies({ kind: 'perp' });"12929 },12930 {12931 "lang": "Python",12932 "label": "Python",12933 "source": "strategies = client.list_strategies(kind=\"perp\")"12934 }12935 ],12936 "parameters": [12937 {12938 "name": "kind",12939 "in": "query",12940 "required": false,12941 "description": "only spot or only perp strategies",12942 "schema": {12943 "type": "string",12944 "enum": [12945 "spot",12946 "perp"12947 ]12948 },12949 "example": "perp"12950 }12951 ],12952 "responses": {12953 "200": {12954 "description": "OK (the example is a recorded answer)",12955 "content": {12956 "application/json": {12957 "schema": {12958 "type": "object",12959 "properties": {12960 "library": {12961 "type": "array",12962 "items": {12963 "type": "object",12964 "properties": {12965 "kind": {12966 "type": "string",12967 "enum": [12968 "spot",12969 "perp"12970 ]12971 },12972 "path": {12973 "type": "string"12974 },12975 "sha256": {12976 "type": "string"12977 }12978 },12979 "required": [12980 "kind",12981 "path",12982 "sha256"12983 ],12984 "additionalProperties": {}12985 }12986 },12987 "versions": {12988 "type": "array",12989 "items": {12990 "type": "object",12991 "properties": {12992 "id": {12993 "type": "string"12994 },12995 "agentId": {12996 "type": "string"12997 },12998 "name": {12999 "type": "string"13000 },13001 "version": {13002 "type": "string"13003 },13004 "sha256": {13005 "type": "string"13006 },13007 "status": {13008 "type": "string"13009 }13010 },13011 "required": [13012 "id",13013 "agentId",13014 "name",13015 "version",13016 "sha256",13017 "status"13018 ],13019 "additionalProperties": {}13020 }13021 },13022 "errors": {13023 "type": "array",13024 "items": {13025 "type": "object",13026 "properties": {13027 "source": {13028 "type": "string"13029 },13030 "message": {13031 "type": "string"13032 }13033 },13034 "required": [13035 "source",13036 "message"13037 ],13038 "additionalProperties": false13039 }13040 }13041 },13042 "required": [13043 "library",13044 "versions",13045 "errors"13046 ],13047 "additionalProperties": false13048 },13049 "example": {13050 "library": [13051 {13052 "kind": "perp",13053 "path": "strategies/basis_cash_carry/1",13054 "sha256": "344831f2ea276d1b3935164287a3e81e5dcc2940841622a88fb3ca218a0a790b",13055 "meta": {13056 "name": "basis_cash_carry",13057 "version": "1",13058 "kind": "perp",13059 "universe": [13060 "BTC"13061 ],13062 "interval": "1h",13063 "lookback": 720,13064 "max_leverage": 1,13065 "max_gross_exposure": 1,13066 "params": {13067 "window": 168,13068 "enter_net_apr": 0.05,13069 "exit_apr": 0.02,13070 "round_trip_cost_bps": 60,13071 "holding_days": 30,13072 "max_adverse_basis_bps": 15,13073 "state_bars": 336,13074 "gross": 0.913075 }13076 }13077 }13078 ],13079 "versions": [13080 {13081 "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",13082 "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",13083 "kind": "perp",13084 "name": "momentum_xs_perp",13085 "version": "2",13086 "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",13087 "status": "backtesting",13088 "hasReport": false,13089 "createdAt": 1794953786690,13090 "approvedAt": null13091 }13092 ],13093 "errors": []13094 }13095 }13096 }13097 },13098 "400": {13099 "description": "The request is not valid: `bad_request`",13100 "content": {13101 "application/json": {13102 "schema": {13103 "$ref": "#/components/schemas/Error"13104 }13105 }13106 }13107 },13108 "401": {13109 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",13110 "content": {13111 "application/json": {13112 "schema": {13113 "$ref": "#/components/schemas/Error"13114 }13115 }13116 }13117 },13118 "403": {13119 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",13120 "content": {13121 "application/json": {13122 "schema": {13123 "$ref": "#/components/schemas/Error"13124 }13125 }13126 }13127 },13128 "429": {13129 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",13130 "content": {13131 "application/json": {13132 "schema": {13133 "$ref": "#/components/schemas/Error"13134 }13135 }13136 }13137 },13138 "500": {13139 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",13140 "content": {13141 "application/json": {13142 "schema": {13143 "$ref": "#/components/schemas/Error"13144 }13145 }13146 }13147 }13148 }13149 },13150 "post": {13151 "operationId": "createStrategy",13152 "tags": [13153 "Strategies"13154 ],13155 "summary": "Register a library strategy version on an agent",13156 "description": "Pins the version by the SHA-256 of its file and queues its backtest. Registers nothing new in the library and approves nothing. `agentId` is required.",13157 "security": [13158 {13159 "bearerKey": [13160 "strategies:manage"13161 ]13162 }13163 ],13164 "x-spw-scope": "strategies:manage",13165 "x-spw-implemented": true,13166 "x-spw-idempotent": true,13167 "x-spw-errors": [13168 {13169 "status": 400,13170 "code": "bad_request"13171 },13172 {13173 "status": 400,13174 "code": "idempotency"13175 },13176 {13177 "status": 400,13178 "code": "stale_request"13179 },13180 {13181 "status": 401,13182 "code": "unauthenticated"13183 },13184 {13185 "status": 403,13186 "code": "insufficient_scope"13187 },13188 {13189 "status": 403,13190 "code": "ip_not_allowed"13191 },13192 {13193 "status": 403,13194 "code": "mixed_credentials"13195 },13196 {13197 "status": 403,13198 "code": "restricted"13199 },13200 {13201 "status": 404,13202 "code": "not_found"13203 },13204 {13205 "status": 409,13206 "code": "idempotency_conflict"13207 },13208 {13209 "status": 409,13210 "code": "idempotency_in_progress"13211 },13212 {13213 "status": 409,13214 "code": "wrong_kind"13215 },13216 {13217 "status": 422,13218 "code": "bad_strategy"13219 },13220 {13221 "status": 429,13222 "code": "auth_throttled"13223 },13224 {13225 "status": 429,13226 "code": "rate_limited"13227 },13228 {13229 "status": 500,13230 "code": "internal"13231 }13232 ],13233 "x-spw-example-recorded": true,13234 "x-codeSamples": [13235 {13236 "lang": "Shell",13237 "label": "curl",13238 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/strategies\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"kind\":\"perp\",\"path\":\"strategies/momentum_xs_perp/2\",\"agentId\":\"fa9c1fd9-a005-4825-bd67-ea180a2eb83d\"}'"13239 },13240 {13241 "lang": "TypeScript",13242 "label": "TypeScript",13243 "source": "const { strategy } = await client.createStrategy({ kind: 'perp', path: 'strategies/momentum_xs_perp/2', agentId: 'fa9c1fd9-a005-4825-bd67-ea180a2eb83d' });"13244 },13245 {13246 "lang": "Python",13247 "label": "Python",13248 "source": "strategy = client.create_strategy(kind=\"perp\", path=\"strategies/momentum_xs_perp/2\", agent_id=\"fa9c1fd9-a005-4825-bd67-ea180a2eb83d\").strategy"13249 }13250 ],13251 "parameters": [13252 {13253 "name": "Idempotency-Key",13254 "in": "header",13255 "required": true,13256 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",13257 "schema": {13258 "type": "string",13259 "pattern": "^[A-Za-z0-9._:-]{8,100}$"13260 }13261 },13262 {13263 "name": "X-SPW-Timestamp",13264 "in": "header",13265 "required": false,13266 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",13267 "schema": {13268 "type": "string",13269 "pattern": "^\\d{9,11}$"13270 }13271 }13272 ],13273 "requestBody": {13274 "required": true,13275 "content": {13276 "application/json": {13277 "schema": {13278 "type": "object",13279 "properties": {13280 "kind": {13281 "type": "string",13282 "enum": [13283 "spot",13284 "perp"13285 ],13286 "description": "must be the kind of the agent (409 `wrong_kind` otherwise)"13287 },13288 "path": {13289 "type": "string",13290 "minLength": 1,13291 "maxLength": 200,13292 "description": "library path of the strategy, from GET /strategies (`library[].path`)"13293 },13294 "agentId": {13295 "description": "the agent the version is registered on; required in practice (400 without it)",13296 "type": "string",13297 "format": "uuid",13298 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"13299 }13300 },13301 "required": [13302 "kind",13303 "path"13304 ],13305 "additionalProperties": false13306 },13307 "example": {13308 "kind": "perp",13309 "path": "strategies/momentum_xs_perp/2",13310 "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d"13311 }13312 }13313 }13314 },13315 "responses": {13316 "200": {13317 "description": "OK (the example is a recorded answer)",13318 "content": {13319 "application/json": {13320 "schema": {13321 "type": "object",13322 "properties": {13323 "strategy": {13324 "type": "object",13325 "properties": {13326 "id": {13327 "type": "string"13328 },13329 "agentId": {13330 "type": "string"13331 },13332 "sha256": {13333 "type": "string"13334 },13335 "status": {13336 "type": "string"13337 }13338 },13339 "required": [13340 "id",13341 "agentId",13342 "sha256",13343 "status"13344 ],13345 "additionalProperties": {}13346 }13347 },13348 "required": [13349 "strategy"13350 ],13351 "additionalProperties": {}13352 },13353 "example": {13354 "strategy": {13355 "id": "450bc266-e1a9-4807-9113-7da6773ddb4e",13356 "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",13357 "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",13358 "status": "backtesting"13359 },13360 "note": "registered and queued for its backtest; approval for LIVE stays the owner's"13361 }13362 }13363 }13364 },13365 "400": {13366 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",13367 "content": {13368 "application/json": {13369 "schema": {13370 "$ref": "#/components/schemas/Error"13371 }13372 }13373 }13374 },13375 "401": {13376 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",13377 "content": {13378 "application/json": {13379 "schema": {13380 "$ref": "#/components/schemas/Error"13381 }13382 }13383 }13384 },13385 "403": {13386 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",13387 "content": {13388 "application/json": {13389 "schema": {13390 "$ref": "#/components/schemas/Error"13391 }13392 }13393 }13394 },13395 "404": {13396 "description": "The object named by the request does not exist: `not_found`",13397 "content": {13398 "application/json": {13399 "schema": {13400 "$ref": "#/components/schemas/Error"13401 }13402 }13403 }13404 },13405 "409": {13406 "description": "The request conflicts with the state of the object, or needs a choice: `idempotency_conflict`, `idempotency_in_progress`, `wrong_kind`",13407 "content": {13408 "application/json": {13409 "schema": {13410 "$ref": "#/components/schemas/Error"13411 }13412 }13413 }13414 },13415 "422": {13416 "description": "A valid request that cannot be carried out: `bad_strategy`",13417 "content": {13418 "application/json": {13419 "schema": {13420 "$ref": "#/components/schemas/Error"13421 }13422 }13423 }13424 },13425 "429": {13426 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",13427 "content": {13428 "application/json": {13429 "schema": {13430 "$ref": "#/components/schemas/Error"13431 }13432 }13433 }13434 },13435 "500": {13436 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",13437 "content": {13438 "application/json": {13439 "schema": {13440 "$ref": "#/components/schemas/Error"13441 }13442 }13443 }13444 }13445 }13446 }13447 },13448 "/api/v1/trading/agents": {13449 "get": {13450 "operationId": "listAgents",13451 "tags": [13452 "Agents"13453 ],13454 "summary": "Trading agents",13455 "description": "Every agent of the wallet. Decide on `lifecycle` (active, paused, stopped) and `tradingMode` (research, paper, live); `state` and `mode` are the historical raw words, kept for compatibility. A key restricted to venues sees only the agents that trade there.",13456 "security": [13457 {13458 "bearerKey": [13459 "agents:read"13460 ]13461 }13462 ],13463 "x-spw-scope": "agents:read",13464 "x-spw-implemented": true,13465 "x-spw-errors": [13466 {13467 "status": 401,13468 "code": "unauthenticated"13469 },13470 {13471 "status": 403,13472 "code": "insufficient_scope"13473 },13474 {13475 "status": 403,13476 "code": "ip_not_allowed"13477 },13478 {13479 "status": 403,13480 "code": "mixed_credentials"13481 },13482 {13483 "status": 429,13484 "code": "auth_throttled"13485 },13486 {13487 "status": 429,13488 "code": "rate_limited"13489 },13490 {13491 "status": 500,13492 "code": "internal"13493 }13494 ],13495 "x-spw-example-recorded": true,13496 "x-codeSamples": [13497 {13498 "lang": "Shell",13499 "label": "curl",13500 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""13501 },13502 {13503 "lang": "TypeScript",13504 "label": "TypeScript",13505 "source": "const { agents } = await client.listAgents();"13506 },13507 {13508 "lang": "Python",13509 "label": "Python",13510 "source": "agents = client.list_agents().agents"13511 }13512 ],13513 "parameters": [],13514 "responses": {13515 "200": {13516 "description": "OK (the example is a recorded answer)",13517 "content": {13518 "application/json": {13519 "schema": {13520 "type": "object",13521 "properties": {13522 "agents": {13523 "type": "array",13524 "items": {13525 "type": "object",13526 "properties": {13527 "id": {13528 "type": "string"13529 },13530 "kind": {13531 "type": "string",13532 "enum": [13533 "spot",13534 "perp",13535 "stream",13536 "supervisor"13537 ]13538 },13539 "name": {13540 "type": "string"13541 },13542 "family": {13543 "type": "string"13544 },13545 "state": {13546 "type": "string",13547 "description": "historical raw state"13548 },13549 "mode": {13550 "type": "string",13551 "description": "historical raw mode"13552 },13553 "lifecycle": {13554 "type": "string",13555 "enum": [13556 "active",13557 "paused",13558 "stopped"13559 ]13560 },13561 "tradingMode": {13562 "anyOf": [13563 {13564 "type": "string",13565 "enum": [13566 "research",13567 "paper",13568 "live"13569 ]13570 },13571 {13572 "type": "null"13573 }13574 ]13575 },13576 "venue": {13577 "type": "string"13578 },13579 "universe": {13580 "type": "array",13581 "items": {13582 "type": "string"13583 }13584 },13585 "interval": {13586 "type": "string"13587 },13588 "configVersion": {13589 "type": "integer",13590 "minimum": -9007199254740991,13591 "maximum": 900719925474099113592 }13593 },13594 "required": [13595 "id",13596 "kind",13597 "name",13598 "family",13599 "state",13600 "mode",13601 "lifecycle",13602 "tradingMode",13603 "venue",13604 "universe",13605 "interval",13606 "configVersion"13607 ],13608 "additionalProperties": {}13609 }13610 }13611 },13612 "required": [13613 "agents"13614 ],13615 "additionalProperties": false13616 },13617 "example": {13618 "agents": [13619 {13620 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",13621 "name": "Docs funding",13622 "mission": "",13623 "kind": "stream",13624 "family": "funding_arb",13625 "template": "funding-arb",13626 "engine": "stream",13627 "state": "CREATED",13628 "phase": "CREATED",13629 "mode": "RESEARCH",13630 "venue": "hyperliquid+dydx",13631 "network": "hyperliquid+dydx",13632 "universe": [13633 "BTC"13634 ],13635 "interval": "stream",13636 "capitalUsd": "1000",13637 "riskLimits": {13638 "maxGrossUsd": 1000,13639 "maxDataAgeMs": 5000,13640 "maxPositionUsd": 500,13641 "maxDailyLossPct": 2,13642 "maxTotalLossPct": 513643 },13644 "configVersion": 1,13645 "strategy": {13646 "name": "funding_differential",13647 "version": "1",13648 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",13649 "path": null,13650 "status": "built_in",13651 "kind": "rule"13652 },13653 "mandate": null,13654 "pausedFrom": null,13655 "live": {13656 "capable": false,13657 "code": "family_not_live",13658 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"13659 },13660 "stopReason": null,13661 "lastBar": null,13662 "createdAt": 1794953757211,13663 "updatedAt": 1794953757211,13664 "lifecycle": "stopped",13665 "tradingMode": "research",13666 "strategyVersionId": null,13667 "mandateId": null,13668 "accountId": null13669 }13670 ]13671 }13672 }13673 }13674 },13675 "401": {13676 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",13677 "content": {13678 "application/json": {13679 "schema": {13680 "$ref": "#/components/schemas/Error"13681 }13682 }13683 }13684 },13685 "403": {13686 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",13687 "content": {13688 "application/json": {13689 "schema": {13690 "$ref": "#/components/schemas/Error"13691 }13692 }13693 }13694 },13695 "429": {13696 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",13697 "content": {13698 "application/json": {13699 "schema": {13700 "$ref": "#/components/schemas/Error"13701 }13702 }13703 }13704 },13705 "500": {13706 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",13707 "content": {13708 "application/json": {13709 "schema": {13710 "$ref": "#/components/schemas/Error"13711 }13712 }13713 }13714 }13715 }13716 },13717 "post": {13718 "operationId": "createAgent",13719 "tags": [13720 "Agents"13721 ],13722 "summary": "Create an agent (from a template, or a perp agent)",13723 "description": "Nothing is signed and no vault is derived. A spot agent is created in the owner's app (403 `owner_required`). A template whose strategy is not installed answers 409 `strategy_not_installed`.",13724 "security": [13725 {13726 "bearerKey": [13727 "agents:manage"13728 ]13729 }13730 ],13731 "x-spw-scope": "agents:manage",13732 "x-spw-implemented": true,13733 "x-spw-idempotent": true,13734 "x-spw-errors": [13735 {13736 "status": 400,13737 "code": "bad_request"13738 },13739 {13740 "status": 400,13741 "code": "idempotency"13742 },13743 {13744 "status": 400,13745 "code": "stale_request"13746 },13747 {13748 "status": 401,13749 "code": "unauthenticated"13750 },13751 {13752 "status": 403,13753 "code": "insufficient_scope"13754 },13755 {13756 "status": 403,13757 "code": "ip_not_allowed"13758 },13759 {13760 "status": 403,13761 "code": "mixed_credentials"13762 },13763 {13764 "status": 403,13765 "code": "owner_required"13766 },13767 {13768 "status": 409,13769 "code": "bad_report"13770 },13771 {13772 "status": 409,13773 "code": "bad_state"13774 },13775 {13776 "status": 409,13777 "code": "exists"13778 },13779 {13780 "status": 409,13781 "code": "halted"13782 },13783 {13784 "status": 409,13785 "code": "idempotency_conflict"13786 },13787 {13788 "status": 409,13789 "code": "idempotency_in_progress"13790 },13791 {13792 "status": 409,13793 "code": "live_unavailable"13794 },13795 {13796 "status": 409,13797 "code": "mandate_required"13798 },13799 {13800 "status": 409,13801 "code": "no_report"13802 },13803 {13804 "status": 409,13805 "code": "no_strategy"13806 },13807 {13808 "status": 409,13809 "code": "strategy_not_installed"13810 },13811 {13812 "status": 409,13813 "code": "wrong_kind"13814 },13815 {13816 "status": 422,13817 "code": "bad_request"13818 },13819 {13820 "status": 422,13821 "code": "universe_mismatch"13822 },13823 {13824 "status": 429,13825 "code": "auth_throttled"13826 },13827 {13828 "status": 429,13829 "code": "rate_limited"13830 },13831 {13832 "status": 500,13833 "code": "internal"13834 }13835 ],13836 "x-spw-example-recorded": true,13837 "x-codeSamples": [13838 {13839 "lang": "Shell",13840 "label": "curl",13841 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/agents\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"template\":\"funding-arb\",\"name\":\"Docs funding\",\"mode\":\"research\"}'"13842 },13843 {13844 "lang": "TypeScript",13845 "label": "TypeScript",13846 "source": "const { agent } = await client.createAgent({ template: 'funding-arb', name: 'Docs funding', mode: 'research' });"13847 },13848 {13849 "lang": "Python",13850 "label": "Python",13851 "source": "agent = client.create_agent(template=\"funding-arb\", name=\"Docs funding\", mode=\"research\").agent"13852 }13853 ],13854 "parameters": [13855 {13856 "name": "Idempotency-Key",13857 "in": "header",13858 "required": true,13859 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",13860 "schema": {13861 "type": "string",13862 "pattern": "^[A-Za-z0-9._:-]{8,100}$"13863 }13864 },13865 {13866 "name": "X-SPW-Timestamp",13867 "in": "header",13868 "required": false,13869 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",13870 "schema": {13871 "type": "string",13872 "pattern": "^\\d{9,11}$"13873 }13874 }13875 ],13876 "requestBody": {13877 "required": true,13878 "content": {13879 "application/json": {13880 "schema": {13881 "type": "object",13882 "properties": {13883 "kind": {13884 "description": "without a template: perp (a spot agent needs a vault from the signer: owner only)",13885 "type": "string",13886 "enum": [13887 "spot",13888 "perp"13889 ]13890 },13891 "template": {13892 "description": "one of GET /agents/templates",13893 "type": "string",13894 "maxLength": 4013895 },13896 "name": {13897 "type": "string",13898 "minLength": 2,13899 "maxLength": 40,13900 "description": "shown in the app and in the lists"13901 },13902 "mission": {13903 "default": "",13904 "description": "free text for people; it changes nothing the agent does",13905 "type": "string",13906 "maxLength": 40013907 },13908 "universe": {13909 "description": "asset symbols the agent trades, e.g. [\"BTC\"]; a fixed-universe strategy needs its exact universe (422 `universe_mismatch`); default: the template's",13910 "minItems": 1,13911 "maxItems": 12,13912 "type": "array",13913 "items": {13914 "type": "string",13915 "pattern": "^[A-Z0-9]{2,15}$"13916 }13917 },13918 "venues": {13919 "description": "venues the agent reads; default: the template's",13920 "minItems": 1,13921 "maxItems": 2,13922 "type": "array",13923 "items": {13924 "type": "string",13925 "enum": [13926 "hyperliquid",13927 "edgex",13928 "dydx",13929 "gmx"13930 ]13931 }13932 },13933 "strategyPath": {13934 "description": "bar templates: which of the template's installed strategies to bind, from GET /agents/templates",13935 "type": "string",13936 "maxLength": 6013937 },13938 "interval": {13939 "description": "bar agents: bar length; default 1h",13940 "type": "string",13941 "enum": [13942 "1h",13943 "4h",13944 "1d"13945 ]13946 },13947 "capitalUsdc": {13948 "description": "simulated capital of the agent, a decimal string; default 1000",13949 "type": "string",13950 "pattern": "^\\d{1,7}(\\.\\d{1,6})?$"13951 },13952 "risk": {13953 "description": "overrides of the agent's own risk limits, by name (the limits in force are in GET /agents/{id}: `riskLimits`)",13954 "type": "object",13955 "propertyNames": {13956 "type": "string"13957 },13958 "additionalProperties": {13959 "type": [13960 "number",13961 "string",13962 "boolean"13963 ]13964 }13965 },13966 "config": {13967 "description": "overrides of the template's parameters, by name",13968 "type": "object",13969 "propertyNames": {13970 "type": "string"13971 },13972 "additionalProperties": {}13973 },13974 "mode": {13975 "default": "research",13976 "description": "research (default): the agent is created and not running. paper: an agent created from a stream or supervisor template is started on paper at once; a bar agent (momentum, mean reversion, …, or `kind: perp`) is created and NOT started — it needs a backtested strategy version first, then POST /agents/{id}/start. `live` is refused (400 `bad_request`): an agent goes live only through POST /agents/{id}/start, under a mandate the owner approved.",13977 "type": "string",13978 "enum": [13979 "research",13980 "paper"13981 ]13982 }13983 },13984 "required": [13985 "name"13986 ],13987 "additionalProperties": false13988 },13989 "example": {13990 "template": "funding-arb",13991 "name": "Docs funding",13992 "mode": "research"13993 }13994 }13995 }13996 },13997 "responses": {13998 "200": {13999 "description": "OK (the example is a recorded answer)",14000 "content": {14001 "application/json": {14002 "schema": {14003 "type": "object",14004 "properties": {14005 "agent": {14006 "type": "object",14007 "properties": {14008 "id": {14009 "type": "string"14010 },14011 "state": {14012 "type": "string",14013 "enum": [14014 "active",14015 "paused",14016 "stopped"14017 ]14018 },14019 "mode": {14020 "type": "string",14021 "enum": [14022 "research",14023 "paper",14024 "live"14025 ],14026 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."14027 }14028 },14029 "required": [14030 "id",14031 "state",14032 "mode"14033 ],14034 "additionalProperties": {}14035 }14036 },14037 "required": [14038 "agent"14039 ],14040 "additionalProperties": {}14041 },14042 "example": {14043 "agent": {14044 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",14045 "name": "Docs funding",14046 "mission": "",14047 "kind": "stream",14048 "family": "funding_arb",14049 "template": "funding-arb",14050 "engine": "stream",14051 "state": "stopped",14052 "phase": "CREATED",14053 "mode": "research",14054 "venue": "hyperliquid+dydx",14055 "network": "hyperliquid+dydx",14056 "universe": [14057 "BTC"14058 ],14059 "interval": "stream",14060 "capitalUsd": "1000",14061 "riskLimits": {14062 "maxGrossUsd": 1000,14063 "maxDataAgeMs": 5000,14064 "maxPositionUsd": 500,14065 "maxDailyLossPct": 2,14066 "maxTotalLossPct": 514067 },14068 "configVersion": 1,14069 "strategy": {14070 "name": "funding_differential",14071 "version": "1",14072 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",14073 "path": null,14074 "status": "built_in",14075 "kind": "rule"14076 },14077 "mandate": null,14078 "pausedFrom": null,14079 "live": {14080 "capable": false,14081 "code": "family_not_live",14082 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"14083 },14084 "stopReason": null,14085 "lastBar": null,14086 "createdAt": 1794953757211,14087 "updatedAt": 179495375721114088 },14089 "strategy": null,14090 "warnings": [14091 {14092 "code": "no_live",14093 "message": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"14094 }14095 ]14096 }14097 }14098 }14099 },14100 "400": {14101 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",14102 "content": {14103 "application/json": {14104 "schema": {14105 "$ref": "#/components/schemas/Error"14106 }14107 }14108 }14109 },14110 "401": {14111 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",14112 "content": {14113 "application/json": {14114 "schema": {14115 "$ref": "#/components/schemas/Error"14116 }14117 }14118 }14119 },14120 "403": {14121 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required`",14122 "content": {14123 "application/json": {14124 "schema": {14125 "$ref": "#/components/schemas/Error"14126 }14127 }14128 }14129 },14130 "409": {14131 "description": "The request conflicts with the state of the object, or needs a choice: `bad_report`, `bad_state`, `exists`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy`, `strategy_not_installed`, `wrong_kind`",14132 "content": {14133 "application/json": {14134 "schema": {14135 "$ref": "#/components/schemas/Error"14136 }14137 }14138 }14139 },14140 "422": {14141 "description": "A valid request that cannot be carried out: `bad_request`, `universe_mismatch`",14142 "content": {14143 "application/json": {14144 "schema": {14145 "$ref": "#/components/schemas/Error"14146 }14147 }14148 }14149 },14150 "429": {14151 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",14152 "content": {14153 "application/json": {14154 "schema": {14155 "$ref": "#/components/schemas/Error"14156 }14157 }14158 }14159 },14160 "500": {14161 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",14162 "content": {14163 "application/json": {14164 "schema": {14165 "$ref": "#/components/schemas/Error"14166 }14167 }14168 }14169 }14170 }14171 }14172 },14173 "/api/v1/trading/risk": {14174 "get": {14175 "operationId": "getRisk",14176 "tags": [14177 "Risk"14178 ],14179 "summary": "Risk state: kill switch, signer limits, capability locks, account policies",14180 "description": "What can stop an order, in one read. `engine.killSwitch` and `engine.readOnly`: the global switches of the risk engine. `killSwitch`: the signer's emergency halt (a different thing). `capabilityLocks`: the server locks, each with `on` and `why` — the lock of live execution through this API (`SPW_TRADING_API_EXECUTION`) is NOT in this list: a preview of a live order shows it as a `lock` refusal. `accounts`: the policy of every derivatives account. `signerPolicy`: the signer's per-transaction and daily limits.",14181 "security": [14182 {14183 "bearerKey": [14184 "positions:read"14185 ]14186 }14187 ],14188 "x-spw-scope": "positions:read",14189 "x-spw-implemented": true,14190 "x-spw-errors": [14191 {14192 "status": 401,14193 "code": "unauthenticated"14194 },14195 {14196 "status": 403,14197 "code": "insufficient_scope"14198 },14199 {14200 "status": 403,14201 "code": "ip_not_allowed"14202 },14203 {14204 "status": 403,14205 "code": "mixed_credentials"14206 },14207 {14208 "status": 429,14209 "code": "auth_throttled"14210 },14211 {14212 "status": 429,14213 "code": "rate_limited"14214 },14215 {14216 "status": 500,14217 "code": "internal"14218 }14219 ],14220 "x-spw-example-recorded": true,14221 "x-spw-example-note": "Cut to one lock and one account; the per-asset maps of the signer policy are cut to four entries.",14222 "x-codeSamples": [14223 {14224 "lang": "Shell",14225 "label": "curl",14226 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/risk\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""14227 },14228 {14229 "lang": "TypeScript",14230 "label": "TypeScript",14231 "source": "const risk = await client.getRisk();\nif (risk.engine.killSwitch.on) console.log('no new risk until the owner releases it');"14232 },14233 {14234 "lang": "Python",14235 "label": "Python",14236 "source": "risk = client.get_risk()\nif risk.engine.kill_switch.on:\n print(\"no new risk until the owner releases it\")"14237 }14238 ],14239 "parameters": [],14240 "responses": {14241 "200": {14242 "description": "OK (the example is a recorded answer)",14243 "content": {14244 "application/json": {14245 "schema": {14246 "type": "object",14247 "properties": {14248 "killSwitch": {14249 "type": "object",14250 "properties": {14251 "signerReachable": {14252 "type": "boolean"14253 },14254 "signerHalted": {14255 "type": [14256 "boolean",14257 "null"14258 ]14259 },14260 "note": {14261 "type": "string"14262 }14263 },14264 "required": [14265 "signerReachable",14266 "signerHalted",14267 "note"14268 ],14269 "additionalProperties": false14270 },14271 "signerPolicy": {14272 "anyOf": [14273 {14274 "type": "object",14275 "properties": {},14276 "additionalProperties": {}14277 },14278 {14279 "type": "null"14280 }14281 ]14282 },14283 "capabilityLocks": {14284 "type": "array",14285 "items": {14286 "type": "object",14287 "properties": {14288 "id": {14289 "type": "string"14290 },14291 "on": {14292 "type": "boolean"14293 },14294 "why": {14295 "type": "string"14296 }14297 },14298 "required": [14299 "id",14300 "on",14301 "why"14302 ],14303 "additionalProperties": false14304 }14305 },14306 "accounts": {14307 "type": "array",14308 "items": {14309 "type": "object",14310 "properties": {14311 "mode": {14312 "type": "string",14313 "enum": [14314 "paper",14315 "live"14316 ],14317 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."14318 },14319 "venue": {14320 "type": "string"14321 },14322 "accountId": {14323 "type": "string"14324 },14325 "policy": {14326 "anyOf": [14327 {14328 "type": "object",14329 "properties": {},14330 "additionalProperties": {}14331 },14332 {14333 "type": "null"14334 }14335 ]14336 },14337 "halted": {14338 "type": [14339 "boolean",14340 "null"14341 ]14342 }14343 },14344 "required": [14345 "mode",14346 "venue",14347 "accountId",14348 "policy",14349 "halted"14350 ],14351 "additionalProperties": {}14352 }14353 },14354 "errors": {14355 "type": "array",14356 "items": {14357 "type": "object",14358 "properties": {14359 "source": {14360 "type": "string"14361 },14362 "message": {14363 "type": "string"14364 }14365 },14366 "required": [14367 "source",14368 "message"14369 ],14370 "additionalProperties": false14371 }14372 },14373 "ts": {14374 "type": "integer",14375 "minimum": -9007199254740991,14376 "maximum": 9007199254740991,14377 "description": "milliseconds since the Unix epoch"14378 },14379 "engine": {14380 "type": "object",14381 "properties": {14382 "killSwitch": {14383 "$ref": "#/components/schemas/Switch"14384 },14385 "readOnly": {14386 "$ref": "#/components/schemas/Switch"14387 },14388 "note": {14389 "type": "string"14390 }14391 },14392 "required": [14393 "killSwitch",14394 "readOnly",14395 "note"14396 ],14397 "additionalProperties": {},14398 "description": "the global switches of the risk engine: `killSwitch.on` blocks every new risk; `readOnly.on` lets only cancels pass"14399 }14400 },14401 "required": [14402 "killSwitch",14403 "signerPolicy",14404 "capabilityLocks",14405 "accounts",14406 "errors",14407 "ts",14408 "engine"14409 ],14410 "additionalProperties": {}14411 },14412 "example": {14413 "killSwitch": {14414 "signerReachable": true,14415 "signerHalted": false,14416 "note": "the signer halt stops signing (reduce-only exits and cancels are still signed since V11) and is lifted on the signer machine only. The global kill switch of the risk engine (`engin…"14417 },14418 "signerPolicy": {14419 "perTx": {14420 "ethereum:ETH": "25000000000000000",14421 "ethereum:USDC": "50000000",14422 "ethereum:USDT": "50000000",14423 "ethereum:PYUSD": "50000000"14424 },14425 "daily": {14426 "ethereum:ETH": "50000000000000000",14427 "ethereum:USDC": "100000000",14428 "ethereum:USDT": "100000000",14429 "ethereum:PYUSD": "100000000"14430 },14431 "maxFee": {14432 "ethereum": "5000000000000000",14433 "base": "300000000000000",14434 "arbitrum": "300000000000000",14435 "optimism": "300000000000000"14436 },14437 "spentToday": {}14438 },14439 "capabilityLocks": [14440 {14441 "id": "deriv_live_mainnet",14442 "on": false,14443 "why": "SPW_DERIV_LIVE_MAINNET is not \"on\": NEW mainnet risk answers mainnet_disabled (orders that open or add, leverage changes, authorizations, collateral moves); cancels and reduce-only…"14444 }14445 ],14446 "accounts": [14447 {14448 "mode": "paper",14449 "venue": "hyperliquid",14450 "network": "mainnet",14451 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",14452 "policy": {14453 "mode": "PAPER",14454 "allowedInstruments": [14455 "hyperliquid:BTC"14456 ],14457 "halt": null,14458 "maxDataAgeMs": 10000,14459 "maxDeviationBps": "200",14460 "maxMarkIndexBps": "100",14461 "maxLeverage": "3",14462 "maxOrderNotional": "10000",14463 "maxGrossExposure": "30000",14464 "maxPositionNotional": "20000",14465 "minFreeCollateral": "1000",14466 "minLiquidationDistanceBps": "1000",14467 "maxDailyLoss": "500",14468 "maxTotalLoss": "2000",14469 "maxOrdersPerMinute": 60,14470 "maxOrdersPerDay": 20014471 },14472 "halted": null,14473 "halt": null14474 }14475 ],14476 "key": {14477 "limits": {14478 "maxOrderNotionalUsd": null,14479 "maxDailyNotionalUsd": null14480 },14481 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",14482 "limitsEnforced": true,14483 "note": "the key's notional limits and its venue / instrument / network restrictions are applied to every order it places, before the mandate and the risk engine"14484 },14485 "errors": [],14486 "ts": 1794953728201,14487 "engine": {14488 "killSwitch": {14489 "on": false,14490 "at": null,14491 "by": null,14492 "reason": null14493 },14494 "readOnly": {14495 "on": false,14496 "at": null,14497 "by": null,14498 "reason": null14499 },14500 "note": "the global kill switch blocks every new risk (cancels and strictly reducing orders pass); read-only mode lets only cancels pass. Releasing either needs the owner's passkey."14501 }14502 }14503 }14504 }14505 },14506 "401": {14507 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",14508 "content": {14509 "application/json": {14510 "schema": {14511 "$ref": "#/components/schemas/Error"14512 }14513 }14514 }14515 },14516 "403": {14517 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",14518 "content": {14519 "application/json": {14520 "schema": {14521 "$ref": "#/components/schemas/Error"14522 }14523 }14524 }14525 },14526 "429": {14527 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",14528 "content": {14529 "application/json": {14530 "schema": {14531 "$ref": "#/components/schemas/Error"14532 }14533 }14534 }14535 },14536 "500": {14537 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",14538 "content": {14539 "application/json": {14540 "schema": {14541 "$ref": "#/components/schemas/Error"14542 }14543 }14544 }14545 }14546 }14547 }14548 },14549 "/api/v1/trading/orders/preview": {14550 "post": {14551 "operationId": "previewOrder",14552 "tags": [14553 "Orders"14554 ],14555 "summary": "Preview an order: every check it would meet, and an estimate",14556 "description": "Resolves the instrument and the account, then runs the key limits, the server locks, the trading mandate (keys and agents), the independent risk engine and the venue engine's own checks on the market as it is now.\n\nAnswers the canonical order and its hash, every check with what was observed and its limit, an estimate (fees, slippage against the real book, liquidation price) and whether an owner passkey approval would be required. Never creates, signs or sends anything; takes no Idempotency-Key.\n\nWhat WOULD refuse the order is in `refusals` (HTTP 200), not an error answer.\n\nA key previews the order it could place: a key with no trading mandate bound to it answers 403 `mandate_required` (the scope itself needs no mandate; the previewed order does). Account figures (equity, free collateral, positions) are answered only to a key that also holds `wallet:read` or `positions:read` (`account.withheld`).",14557 "security": [14558 {14559 "bearerKey": [14560 "orders:prepare"14561 ]14562 }14563 ],14564 "x-spw-scope": "orders:prepare",14565 "x-spw-implemented": true,14566 "x-spw-errors": [14567 {14568 "status": 400,14569 "code": "bad_request"14570 },14571 {14572 "status": 400,14573 "code": "invalid_order"14574 },14575 {14576 "status": 401,14577 "code": "unauthenticated"14578 },14579 {14580 "status": 403,14581 "code": "insufficient_scope"14582 },14583 {14584 "status": 403,14585 "code": "ip_not_allowed"14586 },14587 {14588 "status": 403,14589 "code": "mandate_required"14590 },14591 {14592 "status": 403,14593 "code": "mixed_credentials"14594 },14595 {14596 "status": 403,14597 "code": "owner_session_required"14598 },14599 {14600 "status": 403,14601 "code": "restricted"14602 },14603 {14604 "status": 403,14605 "code": "spot_execution_requires_agent_vault"14606 },14607 {14608 "status": 403,14609 "code": "venue_restricted"14610 },14611 {14612 "status": 404,14613 "code": "unknown_account"14614 },14615 {14616 "status": 404,14617 "code": "unknown_instrument"14618 },14619 {14620 "status": 404,14621 "code": "unknown_market"14622 },14623 {14624 "status": 404,14625 "code": "unknown_venue"14626 },14627 {14628 "status": 409,14629 "code": "account_required"14630 },14631 {14632 "status": 409,14633 "code": "ambiguous_command"14634 },14635 {14636 "status": 409,14637 "code": "ambiguous_order"14638 },14639 {14640 "status": 409,14641 "code": "ambiguous_symbol"14642 },14643 {14644 "status": 422,14645 "code": "below_min_size"14646 },14647 {14648 "status": 422,14649 "code": "fee_cap_not_expressible"14650 },14651 {14652 "status": 422,14653 "code": "gmx_leverage_required"14654 },14655 {14656 "status": 422,14657 "code": "inconsistent_prices"14658 },14659 {14660 "status": 422,14661 "code": "invalid_order"14662 },14663 {14664 "status": 422,14665 "code": "missing_balance"14666 },14667 {14668 "status": 422,14669 "code": "missing_reference_price"14670 },14671 {14672 "status": 422,14673 "code": "no_account"14674 },14675 {14676 "status": 422,14677 "code": "no_client_id_format"14678 },14679 {14680 "status": 422,14681 "code": "no_instrument"14682 },14683 {14684 "status": 422,14685 "code": "no_position"14686 },14687 {14688 "status": 422,14689 "code": "spot_buy_needs_quote_amount"14690 },14691 {14692 "status": 422,14693 "code": "spot_market_only"14694 },14695 {14696 "status": 422,14697 "code": "spot_paper_not_available"14698 },14699 {14700 "status": 422,14701 "code": "spot_via_swap_screen"14702 },14703 {14704 "status": 422,14705 "code": "swap_not_enabled"14706 },14707 {14708 "status": 422,14709 "code": "unknown_instrument"14710 },14711 {14712 "status": 422,14713 "code": "unsupported_asset"14714 },14715 {14716 "status": 422,14717 "code": "venue_not_wired"14718 },14719 {14720 "status": 422,14721 "code": "venue_rejected"14722 },14723 {14724 "status": 422,14725 "code": "zero_size"14726 },14727 {14728 "status": 429,14729 "code": "auth_throttled"14730 },14731 {14732 "status": 429,14733 "code": "rate_limited"14734 },14735 {14736 "status": 500,14737 "code": "internal"14738 },14739 {14740 "status": 501,14741 "code": "execution_not_wired"14742 },14743 {14744 "status": 502,14745 "code": "swap_flow_failed"14746 },14747 {14748 "status": 503,14749 "code": "stale_data"14750 },14751 {14752 "status": 503,14753 "code": "unknown_instrument"14754 },14755 {14756 "status": 503,14757 "code": "venue_rate_limited"14758 },14759 {14760 "status": 503,14761 "code": "venue_timeout"14762 },14763 {14764 "status": 503,14765 "code": "venue_unavailable"14766 }14767 ],14768 "x-spw-example-recorded": true,14769 "x-spw-example-note": "Risk checks cut to two. `wouldExecute` is true exactly when `refusals` is empty.",14770 "x-codeSamples": [14771 {14772 "lang": "Shell",14773 "label": "curl",14774 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/orders/preview\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"mode\":\"paper\",\"instrument\":\"hyperliquid:BTC\",\"side\":\"buy\",\"type\":\"market\",\"notional\":\"100\"}'"14775 },14776 {14777 "lang": "TypeScript",14778 "label": "TypeScript",14779 "source": "const preview = await client.previewOrder({ mode: 'paper', instrument: 'hyperliquid:BTC', side: 'buy', type: 'market', notional: '100' });\nif (!preview.wouldExecute) console.log(preview.refusals);"14780 },14781 {14782 "lang": "Python",14783 "label": "Python",14784 "source": "preview = client.preview_order(mode=\"paper\", instrument=\"hyperliquid:BTC\", side=\"buy\", order_type=\"market\", notional=\"100\")\nif not preview.would_execute:\n print(preview.refusals)"14785 }14786 ],14787 "parameters": [],14788 "requestBody": {14789 "required": true,14790 "content": {14791 "application/json": {14792 "schema": {14793 "type": "object",14794 "properties": {14795 "mode": {14796 "type": "string",14797 "enum": [14798 "paper",14799 "live"14800 ],14801 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."14802 },14803 "accountId": {14804 "description": "paper account or venue account; required when the wallet has several on the venue",14805 "type": "string",14806 "format": "uuid",14807 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"14808 },14809 "instrument": {14810 "type": "string",14811 "minLength": 1,14812 "maxLength": 120,14813 "description": "`venue:symbol` (e.g. `hyperliquid:BTC`, `spot:ETH`); a bare symbol is accepted when it is not ambiguous"14814 },14815 "side": {14816 "type": "string",14817 "enum": [14818 "buy",14819 "sell"14820 ],14821 "description": "buy opens or adds to a long (or reduces a short); sell the reverse"14822 },14823 "type": {14824 "type": "string",14825 "enum": [14826 "limit",14827 "market",14828 "stop_market",14829 "stop_limit",14830 "take_profit_market",14831 "take_profit_limit"14832 ],14833 "description": "market: immediate, bounded by `slippageBps`. limit: rests at `price`. stop_* and take_profit_*: wait for `triggerPrice`, then act as a market order or as a limit order at `price`"14834 },14835 "size": {14836 "description": "quantity of the base asset. Exactly one of `size` and `notional` is required",14837 "type": "string",14838 "pattern": "^\\d+(\\.\\d+)?$"14839 },14840 "notional": {14841 "description": "value of the order in the quote currency of the instrument (USD or a USD stablecoin on every venue of this wallet). The SERVER turns it into a size: notional / reference price, rounded DOWN to the lot size — the reference is the limit price, else the trigger price, else the mark price read now (503 `stale_data` when it is stale; 422 `below_min_size` under one lot). The answer carries the size that was used. Exactly one of `size` and `notional` is required. A SPOT order: a SELL names `size` (the quantity sold); a BUY names `notional` — the amount of the quote asset to spend — because a swap is exact-input",14842 "type": "string",14843 "pattern": "^\\d+(\\.\\d+)?$"14844 },14845 "price": {14846 "description": "limit price, a multiple of the instrument's `tickSize`; required by `limit`, `stop_limit` and `take_profit_limit`, refused on a market order",14847 "type": "string",14848 "pattern": "^\\d+(\\.\\d+)?$"14849 },14850 "triggerPrice": {14851 "description": "price at which a stop or take-profit order is triggered; required by the four trigger types",14852 "type": "string",14853 "pattern": "^\\d+(\\.\\d+)?$"14854 },14855 "reduceOnly": {14856 "default": false,14857 "description": "true: the order may only reduce an existing position — it can neither open, increase nor flip one",14858 "type": "boolean"14859 },14860 "tif": {14861 "default": "gtc",14862 "description": "time in force of a limit order: gtc = rests until cancelled, ioc = fills what it can at once and cancels the rest, alo = add liquidity only (post-only)",14863 "type": "string",14864 "enum": [14865 "gtc",14866 "ioc",14867 "alo"14868 ]14869 },14870 "slippageBps": {14871 "description": "market orders: the worst acceptable price, in basis points from the reference price",14872 "type": "integer",14873 "minimum": 1,14874 "maximum": 50014875 },14876 "leverage": {14877 "description": "paper only: leverage setting of the instrument on the account. On a venue account the leverage is a venue setting",14878 "type": "string",14879 "pattern": "^\\d+(\\.\\d+)?$"14880 },14881 "maxFeeUsd": {14882 "description": "highest fee accepted, USD; default: 10 bps of the notional",14883 "type": "string",14884 "pattern": "^\\d+(\\.\\d+)?$"14885 },14886 "clientOrderId": {14887 "description": "idempotency key of the ORDER; default: the Idempotency-Key header. The order id is derived from it and from the principal",14888 "type": "string",14889 "pattern": "^[A-Za-z0-9._:-]{8,100}$"14890 }14891 },14892 "required": [14893 "mode",14894 "instrument",14895 "side",14896 "type"14897 ],14898 "additionalProperties": false14899 },14900 "example": {14901 "mode": "paper",14902 "instrument": "hyperliquid:BTC",14903 "side": "buy",14904 "type": "market",14905 "notional": "100"14906 }14907 }14908 }14909 },14910 "responses": {14911 "200": {14912 "description": "OK (the example is a recorded answer)",14913 "content": {14914 "application/json": {14915 "schema": {14916 "type": "object",14917 "properties": {14918 "order": {14919 "$ref": "#/components/schemas/CanonicalOrder"14920 },14921 "hash": {14922 "type": "string",14923 "description": "SHA-256 of the canonical bytes, hex"14924 },14925 "resolved": {14926 "anyOf": [14927 {14928 "type": "object",14929 "properties": {14930 "size": {14931 "anyOf": [14932 {14933 "type": "string",14934 "description": "decimal number as a string (never a float)"14935 },14936 {14937 "type": "null"14938 }14939 ],14940 "description": "base units; null when the order is sized by a quote amount the venue converts (a GMX increase)"14941 },14942 "worstPrice": {14943 "anyOf": [14944 {14945 "type": "string",14946 "description": "decimal number as a string (never a float)"14947 },14948 {14949 "type": "null"14950 }14951 ]14952 },14953 "notionalUsd": {14954 "anyOf": [14955 {14956 "type": "string",14957 "description": "decimal number as a string (never a float)"14958 },14959 {14960 "type": "null"14961 }14962 ]14963 }14964 },14965 "required": [14966 "size",14967 "worstPrice",14968 "notionalUsd"14969 ],14970 "additionalProperties": {}14971 },14972 {14973 "type": "null"14974 }14975 ],14976 "description": "what the canonical order leaves open; null when it could not be resolved (see `refusals`)"14977 },14978 "wouldExecute": {14979 "type": "boolean",14980 "description": "true exactly when `refusals` is empty"14981 },14982 "refusals": {14983 "type": "array",14984 "items": {14985 "type": "object",14986 "properties": {14987 "stage": {14988 "type": "string",14989 "enum": [14990 "key",14991 "lock",14992 "mandate",14993 "risk",14994 "engine"14995 ]14996 },14997 "code": {14998 "type": "string"14999 },15000 "message": {15001 "type": "string"15002 },15003 "reasons": {15004 "type": "array",15005 "items": {15006 "type": "string"15007 }15008 }15009 },15010 "required": [15011 "stage",15012 "code",15013 "message"15014 ],15015 "additionalProperties": {}15016 }15017 },15018 "approval": {15019 "type": "object",15020 "properties": {15021 "required": {15022 "type": "boolean"15023 },15024 "by": {15025 "type": "string",15026 "enum": [15027 "owner_passkey",15028 "mandate",15029 "none"15030 ]15031 }15032 },15033 "required": [15034 "required",15035 "by"15036 ],15037 "additionalProperties": {}15038 },15039 "risk": {15040 "type": "object",15041 "properties": {15042 "decision": {15043 "type": "string",15044 "enum": [15045 "allow",15046 "deny"15047 ]15048 },15049 "reducing": {15050 "type": "boolean"15051 },15052 "checks": {15053 "type": "array",15054 "items": {15055 "$ref": "#/components/schemas/RiskCheck"15056 }15057 },15058 "derived": {15059 "anyOf": [15060 {15061 "type": "object",15062 "properties": {15063 "size": {15064 "anyOf": [15065 {15066 "type": "string",15067 "description": "decimal number as a string (never a float)"15068 },15069 {15070 "type": "null"15071 }15072 ]15073 },15074 "notional": {15075 "anyOf": [15076 {15077 "type": "string",15078 "description": "decimal number as a string (never a float)"15079 },15080 {15081 "type": "null"15082 }15083 ]15084 },15085 "referencePrice": {15086 "anyOf": [15087 {15088 "type": "string",15089 "description": "decimal number as a string (never a float)"15090 },15091 {15092 "type": "null"15093 }15094 ]15095 },15096 "positionBefore": {15097 "type": "string",15098 "description": "decimal number as a string (never a float)"15099 },15100 "positionAfter": {15101 "anyOf": [15102 {15103 "type": "string",15104 "description": "decimal number as a string (never a float)"15105 },15106 {15107 "type": "null"15108 }15109 ]15110 }15111 },15112 "required": [15113 "size",15114 "notional",15115 "referencePrice"15116 ],15117 "additionalProperties": {}15118 },15119 {15120 "type": "null"15121 }15122 ],15123 "description": "null for a spot order: of the risk engine only the kill switch and read-only mode apply to it"15124 }15125 },15126 "required": [15127 "decision",15128 "reducing",15129 "checks",15130 "derived"15131 ],15132 "additionalProperties": {}15133 },15134 "mandate": {15135 "anyOf": [15136 {15137 "type": "object",15138 "properties": {15139 "id": {15140 "type": "string"15141 },15142 "decision": {15143 "type": "string",15144 "enum": [15145 "allow",15146 "deny"15147 ]15148 },15149 "reasons": {15150 "type": "array",15151 "items": {15152 "type": "string"15153 }15154 }15155 },15156 "required": [15157 "id",15158 "decision",15159 "reasons"15160 ],15161 "additionalProperties": {}15162 },15163 {15164 "type": "null"15165 }15166 ],15167 "description": "null for the owner session, and when the key's mandate cannot be used (a `mandate` refusal then says why)"15168 },15169 "engine": {15170 "type": "object",15171 "properties": {15172 "name": {15173 "type": "string"15174 },15175 "risk": {15176 "anyOf": [15177 {15178 "type": "object",15179 "properties": {15180 "ok": {15181 "type": "boolean"15182 }15183 },15184 "required": [15185 "ok"15186 ],15187 "additionalProperties": {}15188 },15189 {15190 "type": "null"15191 }15192 ]15193 },15194 "estimate": {15195 "anyOf": [15196 {15197 "type": "object",15198 "properties": {},15199 "additionalProperties": {}15200 },15201 {15202 "type": "null"15203 }15204 ],15205 "description": "fees, slippage against the real book, liquidation price: an estimate"15206 }15207 },15208 "required": [15209 "name",15210 "risk",15211 "estimate"15212 ],15213 "additionalProperties": {}15214 },15215 "account": {15216 "type": "object",15217 "properties": {15218 "id": {15219 "description": "null for a spot order (the wallet itself)",15220 "type": [15221 "string",15222 "null"15223 ]15224 },15225 "venue": {15226 "type": "string"15227 },15228 "network": {15229 "type": "string"15230 },15231 "equity": {15232 "anyOf": [15233 {15234 "type": "string",15235 "description": "decimal number as a string (never a float)"15236 },15237 {15238 "type": "null"15239 }15240 ]15241 },15242 "freeCollateral": {15243 "anyOf": [15244 {15245 "type": "string",15246 "description": "decimal number as a string (never a float)"15247 },15248 {15249 "type": "null"15250 }15251 ]15252 },15253 "withheld": {15254 "type": "boolean",15255 "description": "true: the key holds neither `wallet:read` nor `positions:read`, so `equity`, `freeCollateral`, the position figures of `risk.derived`, and the account figures of the risk checks, of the refusal sentences and of the estimate are omitted"15256 }15257 },15258 "required": [15259 "id",15260 "venue",15261 "network",15262 "withheld"15263 ],15264 "additionalProperties": {}15265 },15266 "ts": {15267 "type": "integer",15268 "minimum": -9007199254740991,15269 "maximum": 9007199254740991,15270 "description": "milliseconds since the Unix epoch"15271 }15272 },15273 "required": [15274 "order",15275 "hash",15276 "resolved",15277 "wouldExecute",15278 "refusals",15279 "approval",15280 "risk",15281 "mandate",15282 "engine",15283 "account",15284 "ts"15285 ],15286 "additionalProperties": {}15287 },15288 "example": {15289 "order": {15290 "v": 1,15291 "venue": "hyperliquid",15292 "network": "mainnet",15293 "instrument": "hyperliquid:BTC",15294 "marketKind": "perp",15295 "side": "buy",15296 "type": "market",15297 "size": "0.00155",15298 "notional": null,15299 "limitPrice": null,15300 "triggerPrice": null,15301 "reduceOnly": false,15302 "tif": "ioc",15303 "maxSlippageBps": 50,15304 "maxFeeUsd": "0.099869",15305 "leverage": null,15306 "marginMode": null,15307 "clientOrderId": "0xc7f8200619c1018d8757a6318aab7a51",15308 "mode": "paper",15309 "principal": {15310 "kind": "api_key",15311 "id": "spk_0123456789ab"15312 },15313 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",15314 "createdAt": 1794953729364,15315 "expiresAt": 179495384936415316 },15317 "hash": "a780accd8e5abce90b3975329e8386b8117bbd470727ae3b442bbaf852163506",15318 "resolved": {15319 "size": "0.00155",15320 "worstPrice": "64754",15321 "notionalUsd": "100.3687"15322 },15323 "wouldExecute": true,15324 "refusals": [],15325 "approval": {15326 "required": false,15327 "by": "mandate",15328 "note": "paper: nothing is signed"15329 },15330 "risk": {15331 "decision": "allow",15332 "reducing": false,15333 "checks": [15334 {15335 "id": "input_valid",15336 "ok": true,15337 "observed": null,15338 "limit": null,15339 "detail": "request, context and limits are well formed",15340 "exempt": false15341 },15342 {15343 "id": "read_only",15344 "ok": true,15345 "observed": "false",15346 "limit": "false",15347 "detail": "not in read-only mode",15348 "exempt": false15349 }15350 ],15351 "derived": {15352 "size": "0.00155",15353 "notional": "99.91207",15354 "referencePrice": "64459.4",15355 "positionBefore": "0",15356 "positionAfter": "0.00155"15357 },15358 "decisionId": 115359 },15360 "mandate": {15361 "id": "84f954ea-0c25-4985-bc19-901d510964d7",15362 "decision": "allow",15363 "reasons": [],15364 "phase": "active"15365 },15366 "engine": {15367 "name": "paper",15368 "risk": {15369 "ok": true15370 },15371 "estimate": {15372 "leverage": "3",15373 "price": "64754",15374 "source": "estimate",15375 "notional": "99.8696",15376 "initialMargin": "33.289866666666666667",15377 "fee": "0.04494132",15378 "avgFillPrice": "64432",15379 "slippageBps": "-0.0776",15380 "liquidationPrice": {15381 "value": null,15382 "source": "estimate",15383 "method": "cross, single-position approximation at a flat maintenance fraction of 0.02; position after the immediate fills; no funding, no fees"15384 },15385 "freeCollateralAfter": "9966.66415868",15386 "filledSize": "0.00155",15387 "restingSize": "0",15388 "status": "filled",15389 "rejectReason": null15390 }15391 },15392 "account": {15393 "id": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",15394 "venue": "hyperliquid",15395 "network": "mainnet",15396 "equity": "10000",15397 "freeCollateral": "10000",15398 "withheld": false15399 },15400 "ts": 179495372936415401 }15402 }15403 }15404 },15405 "400": {15406 "description": "The request is not valid: `bad_request`, `invalid_order`",15407 "content": {15408 "application/json": {15409 "schema": {15410 "$ref": "#/components/schemas/Error"15411 }15412 }15413 }15414 },15415 "401": {15416 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",15417 "content": {15418 "application/json": {15419 "schema": {15420 "$ref": "#/components/schemas/Error"15421 }15422 }15423 }15424 },15425 "403": {15426 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted`",15427 "content": {15428 "application/json": {15429 "schema": {15430 "$ref": "#/components/schemas/Error"15431 }15432 }15433 }15434 },15435 "404": {15436 "description": "The object named by the request does not exist: `unknown_account`, `unknown_instrument`, `unknown_market`, `unknown_venue`",15437 "content": {15438 "application/json": {15439 "schema": {15440 "$ref": "#/components/schemas/Error"15441 }15442 }15443 }15444 },15445 "409": {15446 "description": "The request conflicts with the state of the object, or needs a choice: `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_symbol`",15447 "content": {15448 "application/json": {15449 "schema": {15450 "$ref": "#/components/schemas/Error"15451 }15452 }15453 }15454 },15455 "422": {15456 "description": "A valid request that cannot be carried out: `below_min_size`, `fee_cap_not_expressible`, `gmx_leverage_required`, `inconsistent_prices`, `invalid_order`, `missing_balance`, `missing_reference_price`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `swap_not_enabled`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size`",15457 "content": {15458 "application/json": {15459 "schema": {15460 "$ref": "#/components/schemas/Error"15461 }15462 }15463 }15464 },15465 "429": {15466 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",15467 "content": {15468 "application/json": {15469 "schema": {15470 "$ref": "#/components/schemas/Error"15471 }15472 }15473 }15474 },15475 "500": {15476 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",15477 "content": {15478 "application/json": {15479 "schema": {15480 "$ref": "#/components/schemas/Error"15481 }15482 }15483 }15484 },15485 "501": {15486 "description": "Declared but not connected yet. Never a success: nothing was done: `execution_not_wired`",15487 "content": {15488 "application/json": {15489 "schema": {15490 "$ref": "#/components/schemas/Error"15491 }15492 }15493 }15494 },15495 "502": {15496 "description": "Error: `swap_flow_failed`",15497 "content": {15498 "application/json": {15499 "schema": {15500 "$ref": "#/components/schemas/Error"15501 }15502 }15503 }15504 },15505 "503": {15506 "description": "A backing service is unavailable; nothing was done: `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",15507 "content": {15508 "application/json": {15509 "schema": {15510 "$ref": "#/components/schemas/Error"15511 }15512 }15513 }15514 }15515 }15516 }15517 },15518 "/api/v1/trading/positions/{id}/close": {15519 "post": {15520 "operationId": "closePosition",15521 "tags": [15522 "Positions"15523 ],15524 "summary": "Close a position",15525 "description": "A strictly reduce-only market order on the whole position (`id` from GET /positions). Refused (422 `not_reducing`) if it would not strictly reduce. A key: the position must be on an account and an instrument of its mandate. Passes the kill switch; not read-only mode. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.",15526 "security": [15527 {15528 "bearerKey": [15529 "positions:manage"15530 ]15531 }15532 ],15533 "x-spw-scope": "positions:manage",15534 "x-spw-implemented": true,15535 "x-spw-requires-mandate": true,15536 "x-spw-idempotent": true,15537 "x-spw-errors": [15538 {15539 "status": 400,15540 "code": "bad_policy"15541 },15542 {15543 "status": 400,15544 "code": "bad_request"15545 },15546 {15547 "status": 400,15548 "code": "idempotency"15549 },15550 {15551 "status": 400,15552 "code": "invalid_order"15553 },15554 {15555 "status": 400,15556 "code": "stale_request"15557 },15558 {15559 "status": 401,15560 "code": "unauthenticated"15561 },15562 {15563 "status": 403,15564 "code": "execution_disabled"15565 },15566 {15567 "status": 403,15568 "code": "gmx_disabled"15569 },15570 {15571 "status": 403,15572 "code": "gmx_requires_owner_passkey"15573 },15574 {15575 "status": 403,15576 "code": "insufficient_scope"15577 },15578 {15579 "status": 403,15580 "code": "ip_not_allowed"15581 },15582 {15583 "status": 403,15584 "code": "key_limit_exceeded"15585 },15586 {15587 "status": 403,15588 "code": "mainnet_disabled"15589 },15590 {15591 "status": 403,15592 "code": "mandate_denied"15593 },15594 {15595 "status": 403,15596 "code": "mandate_integrity"15597 },15598 {15599 "status": 403,15600 "code": "mandate_mainnet_disabled"15601 },15602 {15603 "status": 403,15604 "code": "mandate_not_approved"15605 },15606 {15607 "status": 403,15608 "code": "mandate_required"15609 },15610 {15611 "status": 403,15612 "code": "mixed_credentials"15613 },15614 {15615 "status": 403,15616 "code": "owner_session_required"15617 },15618 {15619 "status": 403,15620 "code": "position_not_attributable"15621 },15622 {15623 "status": 403,15624 "code": "restricted"15625 },15626 {15627 "status": 403,15628 "code": "spot_execution_requires_agent_vault"15629 },15630 {15631 "status": 403,15632 "code": "venue_restricted"15633 },15634 {15635 "status": 404,15636 "code": "unknown_account"15637 },15638 {15639 "status": 404,15640 "code": "unknown_instrument"15641 },15642 {15643 "status": 404,15644 "code": "unknown_position"15645 },15646 {15647 "status": 404,15648 "code": "unknown_venue"15649 },15650 {15651 "status": 409,15652 "code": "account_has_active_mandate"15653 },15654 {15655 "status": 409,15656 "code": "account_required"15657 },15658 {15659 "status": 409,15660 "code": "ambiguous_command"15661 },15662 {15663 "status": 409,15664 "code": "ambiguous_order"15665 },15666 {15667 "status": 409,15668 "code": "ambiguous_position"15669 },15670 {15671 "status": 409,15672 "code": "bad_state"15673 },15674 {15675 "status": 409,15676 "code": "idempotency_conflict"15677 },15678 {15679 "status": 409,15680 "code": "idempotency_in_progress"15681 },15682 {15683 "status": 422,15684 "code": "authorization_expired"15685 },15686 {15687 "status": 422,15688 "code": "bad_input"15689 },15690 {15691 "status": 422,15692 "code": "bad_mark"15693 },15694 {15695 "status": 422,15696 "code": "bad_order"15697 },15698 {15699 "status": 422,15700 "code": "bad_policy"15701 },15702 {15703 "status": 422,15704 "code": "below_min_notional"15705 },15706 {15707 "status": 422,15708 "code": "below_min_size"15709 },15710 {15711 "status": 422,15712 "code": "close_in_app"15713 },15714 {15715 "status": 422,15716 "code": "daily_loss_exceeded"15717 },15718 {15719 "status": 422,15720 "code": "data_mismatch"15721 },15722 {15723 "status": 422,15724 "code": "duplicate_client_id"15725 },15726 {15727 "status": 422,15728 "code": "fee_cap_not_expressible"15729 },15730 {15731 "status": 422,15732 "code": "gmx_leverage_required"15733 },15734 {15735 "status": 422,15736 "code": "gross_exposure_exceeded"15737 },15738 {15739 "status": 422,15740 "code": "halted"15741 },15742 {15743 "status": 422,15744 "code": "inconsistent_prices"15745 },15746 {15747 "status": 422,15748 "code": "instrument_halted"15749 },15750 {15751 "status": 422,15752 "code": "instrument_mismatch"15753 },15754 {15755 "status": 422,15756 "code": "instrument_not_allowed"15757 },15758 {15759 "status": 422,15760 "code": "instrument_reduce_only"15761 },15762 {15763 "status": 422,15764 "code": "insufficient_collateral"15765 },15766 {15767 "status": 422,15768 "code": "invalid_order"15769 },15770 {15771 "status": 422,15772 "code": "leverage_exceeded"15773 },15774 {15775 "status": 422,15776 "code": "leverage_mismatch"15777 },15778 {15779 "status": 422,15780 "code": "liquidation_too_close"15781 },15782 {15783 "status": 422,15784 "code": "live_not_available"15785 },15786 {15787 "status": 422,15788 "code": "mandate_mismatch"15789 },15790 {15791 "status": 422,15792 "code": "mandate_none"15793 },15794 {15795 "status": 422,15796 "code": "mandate_wind_down"15797 },15798 {15799 "status": 422,15800 "code": "mark_index_divergence"15801 },15802 {15803 "status": 422,15804 "code": "missing_balance"15805 },15806 {15807 "status": 422,15808 "code": "missing_reference_price"15809 },15810 {15811 "status": 422,15812 "code": "mode_read_only"15813 },15814 {15815 "status": 422,15816 "code": "no_account"15817 },15818 {15819 "status": 422,15820 "code": "no_client_id_format"15821 },15822 {15823 "status": 422,15824 "code": "no_instrument"15825 },15826 {15827 "status": 422,15828 "code": "no_position"15829 },15830 {15831 "status": 422,15832 "code": "not_reducing"15833 },15834 {15835 "status": 422,15836 "code": "order_notional_exceeded"15837 },15838 {15839 "status": 422,15840 "code": "order_rate_day"15841 },15842 {15843 "status": 422,15844 "code": "order_rate_minute"15845 },15846 {15847 "status": 422,15848 "code": "paper_unsupported"15849 },15850 {15851 "status": 422,15852 "code": "position_notional_exceeded"15853 },15854 {15855 "status": 422,15856 "code": "price_deviation"15857 },15858 {15859 "status": 422,15860 "code": "price_not_on_tick"15861 },15862 {15863 "status": 422,15864 "code": "price_required"15865 },15866 {15867 "status": 422,15868 "code": "reduce_only_would_flip"15869 },15870 {15871 "status": 422,15872 "code": "reduce_only_would_increase"15873 },15874 {15875 "status": 422,15876 "code": "risk_denied"15877 },15878 {15879 "status": 422,15880 "code": "size_not_on_lot"15881 },15882 {15883 "status": 422,15884 "code": "spot_buy_needs_quote_amount"15885 },15886 {15887 "status": 422,15888 "code": "spot_market_only"15889 },15890 {15891 "status": 422,15892 "code": "spot_paper_not_available"15893 },15894 {15895 "status": 422,15896 "code": "spot_via_swap_screen"15897 },15898 {15899 "status": 422,15900 "code": "stale_book"15901 },15902 {15903 "status": 422,15904 "code": "stale_ticker"15905 },15906 {15907 "status": 422,15908 "code": "swap_not_enabled"15909 },15910 {15911 "status": 422,15912 "code": "total_loss_exceeded"15913 },15914 {15915 "status": 422,15916 "code": "trigger_required"15917 },15918 {15919 "status": 422,15920 "code": "unknown_instrument"15921 },15922 {15923 "status": 422,15924 "code": "unsupported_asset"15925 },15926 {15927 "status": 422,15928 "code": "venue_not_wired"15929 },15930 {15931 "status": 422,15932 "code": "venue_rejected"15933 },15934 {15935 "status": 422,15936 "code": "zero_size"15937 },15938 {15939 "status": 423,15940 "code": "halted"15941 },15942 {15943 "status": 423,15944 "code": "kill_switch_active"15945 },15946 {15947 "status": 423,15948 "code": "read_only_mode"15949 },15950 {15951 "status": 429,15952 "code": "auth_throttled"15953 },15954 {15955 "status": 429,15956 "code": "rate_limited"15957 },15958 {15959 "status": 500,15960 "code": "internal"15961 },15962 {15963 "status": 501,15964 "code": "execution_not_wired"15965 },15966 {15967 "status": 502,15968 "code": "swap_flow_failed"15969 },15970 {15971 "status": 503,15972 "code": "authorization_unknown"15973 },15974 {15975 "status": 503,15976 "code": "mandate_unavailable"15977 },15978 {15979 "status": 503,15980 "code": "no_liquidity"15981 },15982 {15983 "status": 503,15984 "code": "signer_unreachable"15985 },15986 {15987 "status": 503,15988 "code": "stale_data"15989 },15990 {15991 "status": 503,15992 "code": "unknown_instrument"15993 },15994 {15995 "status": 503,15996 "code": "venue_rate_limited"15997 },15998 {15999 "status": 503,16000 "code": "venue_timeout"16001 },16002 {16003 "status": 503,16004 "code": "venue_unavailable"16005 }16006 ],16007 "x-spw-errors-open": true,16008 "x-spw-example-recorded": true,16009 "x-codeSamples": [16010 {16011 "lang": "Shell",16012 "label": "curl",16013 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/close\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'"16014 },16015 {16016 "lang": "TypeScript",16017 "label": "TypeScript",16018 "source": "const closed = await client.closePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC');"16019 },16020 {16021 "lang": "Python",16022 "label": "Python",16023 "source": "closed = client.close_position(\"paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC\")"16024 }16025 ],16026 "parameters": [16027 {16028 "name": "id",16029 "in": "path",16030 "required": true,16031 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",16032 "schema": {16033 "type": "string",16034 "minLength": 1,16035 "maxLength": 20016036 },16037 "example": "paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC"16038 },16039 {16040 "name": "Idempotency-Key",16041 "in": "header",16042 "required": true,16043 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",16044 "schema": {16045 "type": "string",16046 "pattern": "^[A-Za-z0-9._:-]{8,100}$"16047 }16048 },16049 {16050 "name": "X-SPW-Timestamp",16051 "in": "header",16052 "required": false,16053 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",16054 "schema": {16055 "type": "string",16056 "pattern": "^\\d{9,11}$"16057 }16058 }16059 ],16060 "requestBody": {16061 "required": true,16062 "content": {16063 "application/json": {16064 "schema": {16065 "type": "object",16066 "properties": {16067 "slippageBps": {16068 "description": "worst acceptable price of the closing market order, in basis points from the reference price",16069 "type": "integer",16070 "minimum": 1,16071 "maximum": 50016072 }16073 },16074 "additionalProperties": false16075 },16076 "example": {}16077 }16078 }16079 },16080 "responses": {16081 "200": {16082 "description": "OK (the example is a recorded answer)",16083 "content": {16084 "application/json": {16085 "schema": {16086 "type": "object",16087 "properties": {16088 "order": {16089 "$ref": "#/components/schemas/Order"16090 },16091 "idempotent": {16092 "type": "boolean",16093 "description": "true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again"16094 },16095 "approval": {16096 "anyOf": [16097 {16098 "type": "object",16099 "properties": {16100 "by": {16101 "type": "string"16102 },16103 "engine": {16104 "type": "string"16105 },16106 "accountId": {16107 "type": "string"16108 },16109 "clientId": {16110 "type": "string"16111 },16112 "hash": {16113 "type": [16114 "string",16115 "null"16116 ]16117 },16118 "expiresAt": {16119 "anyOf": [16120 {16121 "type": "integer",16122 "minimum": -9007199254740991,16123 "maximum": 9007199254740991,16124 "description": "milliseconds since the Unix epoch"16125 },16126 {16127 "type": "null"16128 }16129 ]16130 },16131 "approve": {16132 "type": "object",16133 "properties": {16134 "method": {16135 "type": "string"16136 },16137 "path": {16138 "type": "string"16139 }16140 },16141 "required": [16142 "method",16143 "path"16144 ],16145 "additionalProperties": {}16146 }16147 },16148 "required": [16149 "by",16150 "engine",16151 "accountId",16152 "clientId",16153 "hash",16154 "expiresAt",16155 "approve"16156 ],16157 "additionalProperties": {}16158 },16159 {16160 "type": "null"16161 }16162 ],16163 "description": "set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key"16164 }16165 },16166 "required": [16167 "order",16168 "idempotent",16169 "approval"16170 ],16171 "additionalProperties": {}16172 },16173 "example": {16174 "order": {16175 "id": "0xfa8f57b697470c1ec4327676f56a9868",16176 "orderId": "0xfa8f57b697470c1ec4327676f56a9868",16177 "mode": "paper",16178 "venue": "hyperliquid",16179 "network": "mainnet",16180 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",16181 "clientId": "0xfa8f57b697470c1ec4327676f56a9868",16182 "clientOrderId": "0xfa8f57b697470c1ec4327676f56a9868",16183 "venueOrderId": "paper-o-5",16184 "instrument": "hyperliquid:BTC",16185 "side": "sell",16186 "type": "market",16187 "size": "0.00078",16188 "price": "64104",16189 "triggerPrice": null,16190 "reduceOnly": true,16191 "tif": "ioc",16192 "status": "FILLED",16193 "final": true,16194 "reasonCode": "VENUE_FILLED",16195 "reason": null,16196 "rejectCode": null,16197 "engineStatus": "filled",16198 "filled": "0.00078",16199 "avgFillPrice": "64426",16200 "acknowledged": true,16201 "cancelRequested": false,16202 "origin": "trading_api",16203 "principal": {16204 "kind": "api_key",16205 "id": "spk_0123456789ab"16206 },16207 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",16208 "engine": "paper",16209 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xfa8f57b697470c1ec4327676f56a9868",16210 "hash": "73c1d9ea9e8be9bc4f6be7ed0febf7f3947552ec479c497b256798e8d217f7cd",16211 "notionalUsd": "50.00112",16212 "projectionError": null,16213 "version": 4,16214 "createdAt": 1794953731468,16215 "updatedAt": 179495373148716216 },16217 "idempotent": false,16218 "approval": null16219 }16220 }16221 }16222 },16223 "400": {16224 "description": "The request is not valid: `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request`",16225 "content": {16226 "application/json": {16227 "schema": {16228 "$ref": "#/components/schemas/Error"16229 }16230 }16231 }16232 },16233 "401": {16234 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",16235 "content": {16236 "application/json": {16237 "schema": {16238 "$ref": "#/components/schemas/Error"16239 }16240 }16241 }16242 },16243 "403": {16244 "description": "Authenticated, and refused: `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted`",16245 "content": {16246 "application/json": {16247 "schema": {16248 "$ref": "#/components/schemas/Error"16249 }16250 }16251 }16252 },16253 "404": {16254 "description": "The object named by the request does not exist: `unknown_account`, `unknown_instrument`, `unknown_position`, `unknown_venue`",16255 "content": {16256 "application/json": {16257 "schema": {16258 "$ref": "#/components/schemas/Error"16259 }16260 }16261 }16262 },16263 "409": {16264 "description": "The request conflicts with the state of the object, or needs a choice: `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_position`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",16265 "content": {16266 "application/json": {16267 "schema": {16268 "$ref": "#/components/schemas/Error"16269 }16270 }16271 }16272 },16273 "422": {16274 "description": "A valid request that cannot be carried out: `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `close_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size`",16275 "content": {16276 "application/json": {16277 "schema": {16278 "$ref": "#/components/schemas/Error"16279 }16280 }16281 }16282 },16283 "423": {16284 "description": "Blocked by the kill switch, by read-only mode or by a halt: `halted`, `kill_switch_active`, `read_only_mode`",16285 "content": {16286 "application/json": {16287 "schema": {16288 "$ref": "#/components/schemas/Error"16289 }16290 }16291 }16292 },16293 "429": {16294 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",16295 "content": {16296 "application/json": {16297 "schema": {16298 "$ref": "#/components/schemas/Error"16299 }16300 }16301 }16302 },16303 "500": {16304 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",16305 "content": {16306 "application/json": {16307 "schema": {16308 "$ref": "#/components/schemas/Error"16309 }16310 }16311 }16312 },16313 "501": {16314 "description": "Declared but not connected yet. Never a success: nothing was done: `execution_not_wired`",16315 "content": {16316 "application/json": {16317 "schema": {16318 "$ref": "#/components/schemas/Error"16319 }16320 }16321 }16322 },16323 "502": {16324 "description": "Error: `swap_flow_failed`",16325 "content": {16326 "application/json": {16327 "schema": {16328 "$ref": "#/components/schemas/Error"16329 }16330 }16331 }16332 },16333 "503": {16334 "description": "A backing service is unavailable; nothing was done: `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",16335 "content": {16336 "application/json": {16337 "schema": {16338 "$ref": "#/components/schemas/Error"16339 }16340 }16341 }16342 }16343 }16344 }16345 },16346 "/api/v1/trading/positions/{id}/reduce": {16347 "post": {16348 "operationId": "reducePosition",16349 "tags": [16350 "Positions"16351 ],16352 "summary": "Reduce a position",16353 "description": "As close, on a fraction of the position (rounded down to the lot). The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.",16354 "security": [16355 {16356 "bearerKey": [16357 "positions:manage"16358 ]16359 }16360 ],16361 "x-spw-scope": "positions:manage",16362 "x-spw-implemented": true,16363 "x-spw-requires-mandate": true,16364 "x-spw-idempotent": true,16365 "x-spw-errors": [16366 {16367 "status": 400,16368 "code": "bad_policy"16369 },16370 {16371 "status": 400,16372 "code": "bad_request"16373 },16374 {16375 "status": 400,16376 "code": "idempotency"16377 },16378 {16379 "status": 400,16380 "code": "invalid_order"16381 },16382 {16383 "status": 400,16384 "code": "stale_request"16385 },16386 {16387 "status": 401,16388 "code": "unauthenticated"16389 },16390 {16391 "status": 403,16392 "code": "execution_disabled"16393 },16394 {16395 "status": 403,16396 "code": "gmx_disabled"16397 },16398 {16399 "status": 403,16400 "code": "gmx_requires_owner_passkey"16401 },16402 {16403 "status": 403,16404 "code": "insufficient_scope"16405 },16406 {16407 "status": 403,16408 "code": "ip_not_allowed"16409 },16410 {16411 "status": 403,16412 "code": "key_limit_exceeded"16413 },16414 {16415 "status": 403,16416 "code": "mainnet_disabled"16417 },16418 {16419 "status": 403,16420 "code": "mandate_denied"16421 },16422 {16423 "status": 403,16424 "code": "mandate_integrity"16425 },16426 {16427 "status": 403,16428 "code": "mandate_mainnet_disabled"16429 },16430 {16431 "status": 403,16432 "code": "mandate_not_approved"16433 },16434 {16435 "status": 403,16436 "code": "mandate_required"16437 },16438 {16439 "status": 403,16440 "code": "mixed_credentials"16441 },16442 {16443 "status": 403,16444 "code": "owner_session_required"16445 },16446 {16447 "status": 403,16448 "code": "position_not_attributable"16449 },16450 {16451 "status": 403,16452 "code": "restricted"16453 },16454 {16455 "status": 403,16456 "code": "spot_execution_requires_agent_vault"16457 },16458 {16459 "status": 403,16460 "code": "venue_restricted"16461 },16462 {16463 "status": 404,16464 "code": "unknown_account"16465 },16466 {16467 "status": 404,16468 "code": "unknown_instrument"16469 },16470 {16471 "status": 404,16472 "code": "unknown_position"16473 },16474 {16475 "status": 404,16476 "code": "unknown_venue"16477 },16478 {16479 "status": 409,16480 "code": "account_has_active_mandate"16481 },16482 {16483 "status": 409,16484 "code": "account_required"16485 },16486 {16487 "status": 409,16488 "code": "ambiguous_command"16489 },16490 {16491 "status": 409,16492 "code": "ambiguous_order"16493 },16494 {16495 "status": 409,16496 "code": "ambiguous_position"16497 },16498 {16499 "status": 409,16500 "code": "bad_state"16501 },16502 {16503 "status": 409,16504 "code": "idempotency_conflict"16505 },16506 {16507 "status": 409,16508 "code": "idempotency_in_progress"16509 },16510 {16511 "status": 422,16512 "code": "authorization_expired"16513 },16514 {16515 "status": 422,16516 "code": "bad_input"16517 },16518 {16519 "status": 422,16520 "code": "bad_mark"16521 },16522 {16523 "status": 422,16524 "code": "bad_order"16525 },16526 {16527 "status": 422,16528 "code": "bad_policy"16529 },16530 {16531 "status": 422,16532 "code": "below_min_notional"16533 },16534 {16535 "status": 422,16536 "code": "below_min_size"16537 },16538 {16539 "status": 422,16540 "code": "close_in_app"16541 },16542 {16543 "status": 422,16544 "code": "daily_loss_exceeded"16545 },16546 {16547 "status": 422,16548 "code": "data_mismatch"16549 },16550 {16551 "status": 422,16552 "code": "duplicate_client_id"16553 },16554 {16555 "status": 422,16556 "code": "fee_cap_not_expressible"16557 },16558 {16559 "status": 422,16560 "code": "gmx_leverage_required"16561 },16562 {16563 "status": 422,16564 "code": "gross_exposure_exceeded"16565 },16566 {16567 "status": 422,16568 "code": "halted"16569 },16570 {16571 "status": 422,16572 "code": "inconsistent_prices"16573 },16574 {16575 "status": 422,16576 "code": "instrument_halted"16577 },16578 {16579 "status": 422,16580 "code": "instrument_mismatch"16581 },16582 {16583 "status": 422,16584 "code": "instrument_not_allowed"16585 },16586 {16587 "status": 422,16588 "code": "instrument_reduce_only"16589 },16590 {16591 "status": 422,16592 "code": "insufficient_collateral"16593 },16594 {16595 "status": 422,16596 "code": "invalid_order"16597 },16598 {16599 "status": 422,16600 "code": "leverage_exceeded"16601 },16602 {16603 "status": 422,16604 "code": "leverage_mismatch"16605 },16606 {16607 "status": 422,16608 "code": "liquidation_too_close"16609 },16610 {16611 "status": 422,16612 "code": "live_not_available"16613 },16614 {16615 "status": 422,16616 "code": "mandate_mismatch"16617 },16618 {16619 "status": 422,16620 "code": "mandate_none"16621 },16622 {16623 "status": 422,16624 "code": "mandate_wind_down"16625 },16626 {16627 "status": 422,16628 "code": "mark_index_divergence"16629 },16630 {16631 "status": 422,16632 "code": "missing_balance"16633 },16634 {16635 "status": 422,16636 "code": "missing_reference_price"16637 },16638 {16639 "status": 422,16640 "code": "mode_read_only"16641 },16642 {16643 "status": 422,16644 "code": "no_account"16645 },16646 {16647 "status": 422,16648 "code": "no_client_id_format"16649 },16650 {16651 "status": 422,16652 "code": "no_instrument"16653 },16654 {16655 "status": 422,16656 "code": "no_position"16657 },16658 {16659 "status": 422,16660 "code": "not_reducing"16661 },16662 {16663 "status": 422,16664 "code": "order_notional_exceeded"16665 },16666 {16667 "status": 422,16668 "code": "order_rate_day"16669 },16670 {16671 "status": 422,16672 "code": "order_rate_minute"16673 },16674 {16675 "status": 422,16676 "code": "paper_unsupported"16677 },16678 {16679 "status": 422,16680 "code": "position_notional_exceeded"16681 },16682 {16683 "status": 422,16684 "code": "price_deviation"16685 },16686 {16687 "status": 422,16688 "code": "price_not_on_tick"16689 },16690 {16691 "status": 422,16692 "code": "price_required"16693 },16694 {16695 "status": 422,16696 "code": "reduce_only_would_flip"16697 },16698 {16699 "status": 422,16700 "code": "reduce_only_would_increase"16701 },16702 {16703 "status": 422,16704 "code": "risk_denied"16705 },16706 {16707 "status": 422,16708 "code": "size_not_on_lot"16709 },16710 {16711 "status": 422,16712 "code": "spot_buy_needs_quote_amount"16713 },16714 {16715 "status": 422,16716 "code": "spot_market_only"16717 },16718 {16719 "status": 422,16720 "code": "spot_paper_not_available"16721 },16722 {16723 "status": 422,16724 "code": "spot_via_swap_screen"16725 },16726 {16727 "status": 422,16728 "code": "stale_book"16729 },16730 {16731 "status": 422,16732 "code": "stale_ticker"16733 },16734 {16735 "status": 422,16736 "code": "swap_not_enabled"16737 },16738 {16739 "status": 422,16740 "code": "total_loss_exceeded"16741 },16742 {16743 "status": 422,16744 "code": "trigger_required"16745 },16746 {16747 "status": 422,16748 "code": "unknown_instrument"16749 },16750 {16751 "status": 422,16752 "code": "unsupported_asset"16753 },16754 {16755 "status": 422,16756 "code": "venue_not_wired"16757 },16758 {16759 "status": 422,16760 "code": "venue_rejected"16761 },16762 {16763 "status": 422,16764 "code": "zero_size"16765 },16766 {16767 "status": 423,16768 "code": "halted"16769 },16770 {16771 "status": 423,16772 "code": "kill_switch_active"16773 },16774 {16775 "status": 423,16776 "code": "read_only_mode"16777 },16778 {16779 "status": 429,16780 "code": "auth_throttled"16781 },16782 {16783 "status": 429,16784 "code": "rate_limited"16785 },16786 {16787 "status": 500,16788 "code": "internal"16789 },16790 {16791 "status": 501,16792 "code": "execution_not_wired"16793 },16794 {16795 "status": 502,16796 "code": "swap_flow_failed"16797 },16798 {16799 "status": 503,16800 "code": "authorization_unknown"16801 },16802 {16803 "status": 503,16804 "code": "mandate_unavailable"16805 },16806 {16807 "status": 503,16808 "code": "no_liquidity"16809 },16810 {16811 "status": 503,16812 "code": "signer_unreachable"16813 },16814 {16815 "status": 503,16816 "code": "stale_data"16817 },16818 {16819 "status": 503,16820 "code": "unknown_instrument"16821 },16822 {16823 "status": 503,16824 "code": "venue_rate_limited"16825 },16826 {16827 "status": 503,16828 "code": "venue_timeout"16829 },16830 {16831 "status": 503,16832 "code": "venue_unavailable"16833 }16834 ],16835 "x-spw-errors-open": true,16836 "x-spw-example-recorded": true,16837 "x-codeSamples": [16838 {16839 "lang": "Shell",16840 "label": "curl",16841 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/positions/paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC/reduce\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"fraction\":\"0.5\"}'"16842 },16843 {16844 "lang": "TypeScript",16845 "label": "TypeScript",16846 "source": "const reduced = await client.reducePosition('paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC', { fraction: '0.5' });"16847 },16848 {16849 "lang": "Python",16850 "label": "Python",16851 "source": "reduced = client.reduce_position(\"paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC\", fraction=\"0.5\")"16852 }16853 ],16854 "parameters": [16855 {16856 "name": "id",16857 "in": "path",16858 "required": true,16859 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",16860 "schema": {16861 "type": "string",16862 "minLength": 1,16863 "maxLength": 20016864 },16865 "example": "paper:hyperliquid:6a2c8351-cd79-44e2-b75a-f39280d0ebc2:hyperliquid:BTC"16866 },16867 {16868 "name": "Idempotency-Key",16869 "in": "header",16870 "required": true,16871 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",16872 "schema": {16873 "type": "string",16874 "pattern": "^[A-Za-z0-9._:-]{8,100}$"16875 }16876 },16877 {16878 "name": "X-SPW-Timestamp",16879 "in": "header",16880 "required": false,16881 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",16882 "schema": {16883 "type": "string",16884 "pattern": "^\\d{9,11}$"16885 }16886 }16887 ],16888 "requestBody": {16889 "required": true,16890 "content": {16891 "application/json": {16892 "schema": {16893 "type": "object",16894 "properties": {16895 "fraction": {16896 "type": "string",16897 "pattern": "^(0(\\.\\d+)?|1(\\.0+)?)$",16898 "description": "share of the position to close, in (0, 1]"16899 },16900 "slippageBps": {16901 "description": "worst acceptable price of the reducing market order, in basis points from the reference price",16902 "type": "integer",16903 "minimum": 1,16904 "maximum": 50016905 }16906 },16907 "required": [16908 "fraction"16909 ],16910 "additionalProperties": false16911 },16912 "example": {16913 "fraction": "0.5"16914 }16915 }16916 }16917 },16918 "responses": {16919 "200": {16920 "description": "OK (the example is a recorded answer)",16921 "content": {16922 "application/json": {16923 "schema": {16924 "type": "object",16925 "properties": {16926 "order": {16927 "$ref": "#/components/schemas/Order"16928 },16929 "idempotent": {16930 "type": "boolean",16931 "description": "true: this Idempotency-Key (or clientOrderId) already placed this order; nothing was sent again"16932 },16933 "approval": {16934 "anyOf": [16935 {16936 "type": "object",16937 "properties": {16938 "by": {16939 "type": "string"16940 },16941 "engine": {16942 "type": "string"16943 },16944 "accountId": {16945 "type": "string"16946 },16947 "clientId": {16948 "type": "string"16949 },16950 "hash": {16951 "type": [16952 "string",16953 "null"16954 ]16955 },16956 "expiresAt": {16957 "anyOf": [16958 {16959 "type": "integer",16960 "minimum": -9007199254740991,16961 "maximum": 9007199254740991,16962 "description": "milliseconds since the Unix epoch"16963 },16964 {16965 "type": "null"16966 }16967 ]16968 },16969 "approve": {16970 "type": "object",16971 "properties": {16972 "method": {16973 "type": "string"16974 },16975 "path": {16976 "type": "string"16977 }16978 },16979 "required": [16980 "method",16981 "path"16982 ],16983 "additionalProperties": {}16984 }16985 },16986 "required": [16987 "by",16988 "engine",16989 "accountId",16990 "clientId",16991 "hash",16992 "expiresAt",16993 "approve"16994 ],16995 "additionalProperties": {}16996 },16997 {16998 "type": "null"16999 }17000 ],17001 "description": "set while an owner order waits AWAITING_APPROVAL: where the owner approves it with the passkey. Always null for an API key"17002 }17003 },17004 "required": [17005 "order",17006 "idempotent",17007 "approval"17008 ],17009 "additionalProperties": {}17010 },17011 "example": {17012 "order": {17013 "id": "0xae8c2f844447aa3dc5604837d7a7d78f",17014 "orderId": "0xae8c2f844447aa3dc5604837d7a7d78f",17015 "mode": "paper",17016 "venue": "hyperliquid",17017 "network": "mainnet",17018 "accountId": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2",17019 "clientId": "0xae8c2f844447aa3dc5604837d7a7d78f",17020 "clientOrderId": "0xae8c2f844447aa3dc5604837d7a7d78f",17021 "venueOrderId": "paper-o-3",17022 "instrument": "hyperliquid:BTC",17023 "side": "sell",17024 "type": "market",17025 "size": "0.00077",17026 "price": "64104",17027 "triggerPrice": null,17028 "reduceOnly": true,17029 "tif": "ioc",17030 "status": "FILLED",17031 "final": true,17032 "reasonCode": "VENUE_FILLED",17033 "reason": null,17034 "rejectCode": null,17035 "engineStatus": "filled",17036 "filled": "0.00077",17037 "avgFillPrice": "64426",17038 "acknowledged": true,17039 "cancelRequested": false,17040 "origin": "trading_api",17041 "principal": {17042 "kind": "api_key",17043 "id": "spk_0123456789ab"17044 },17045 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",17046 "engine": "paper",17047 "engineRef": "6a2c8351-cd79-44e2-b75a-f39280d0ebc2:0xae8c2f844447aa3dc5604837d7a7d78f",17048 "hash": "1528b646d4c9541d3faddcf092cccca76aa9710a7956c811adb5a5128c1a25ad",17049 "notionalUsd": "49.36008",17050 "projectionError": null,17051 "version": 4,17052 "createdAt": 1794953731442,17053 "updatedAt": 179495373146117054 },17055 "idempotent": false,17056 "approval": null17057 }17058 }17059 }17060 },17061 "400": {17062 "description": "The request is not valid: `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `stale_request`",17063 "content": {17064 "application/json": {17065 "schema": {17066 "$ref": "#/components/schemas/Error"17067 }17068 }17069 }17070 },17071 "401": {17072 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",17073 "content": {17074 "application/json": {17075 "schema": {17076 "$ref": "#/components/schemas/Error"17077 }17078 }17079 }17080 },17081 "403": {17082 "description": "Authenticated, and refused: `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted`",17083 "content": {17084 "application/json": {17085 "schema": {17086 "$ref": "#/components/schemas/Error"17087 }17088 }17089 }17090 },17091 "404": {17092 "description": "The object named by the request does not exist: `unknown_account`, `unknown_instrument`, `unknown_position`, `unknown_venue`",17093 "content": {17094 "application/json": {17095 "schema": {17096 "$ref": "#/components/schemas/Error"17097 }17098 }17099 }17100 },17101 "409": {17102 "description": "The request conflicts with the state of the object, or needs a choice: `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `ambiguous_position`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",17103 "content": {17104 "application/json": {17105 "schema": {17106 "$ref": "#/components/schemas/Error"17107 }17108 }17109 }17110 },17111 "422": {17112 "description": "A valid request that cannot be carried out: `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `close_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size`",17113 "content": {17114 "application/json": {17115 "schema": {17116 "$ref": "#/components/schemas/Error"17117 }17118 }17119 }17120 },17121 "423": {17122 "description": "Blocked by the kill switch, by read-only mode or by a halt: `halted`, `kill_switch_active`, `read_only_mode`",17123 "content": {17124 "application/json": {17125 "schema": {17126 "$ref": "#/components/schemas/Error"17127 }17128 }17129 }17130 },17131 "429": {17132 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",17133 "content": {17134 "application/json": {17135 "schema": {17136 "$ref": "#/components/schemas/Error"17137 }17138 }17139 }17140 },17141 "500": {17142 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",17143 "content": {17144 "application/json": {17145 "schema": {17146 "$ref": "#/components/schemas/Error"17147 }17148 }17149 }17150 },17151 "501": {17152 "description": "Declared but not connected yet. Never a success: nothing was done: `execution_not_wired`",17153 "content": {17154 "application/json": {17155 "schema": {17156 "$ref": "#/components/schemas/Error"17157 }17158 }17159 }17160 },17161 "502": {17162 "description": "Error: `swap_flow_failed`",17163 "content": {17164 "application/json": {17165 "schema": {17166 "$ref": "#/components/schemas/Error"17167 }17168 }17169 }17170 },17171 "503": {17172 "description": "A backing service is unavailable; nothing was done: `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",17173 "content": {17174 "application/json": {17175 "schema": {17176 "$ref": "#/components/schemas/Error"17177 }17178 }17179 }17180 }17181 }17182 }17183 },17184 "/api/v1/trading/commands": {17185 "post": {17186 "operationId": "runCommand",17187 "tags": [17188 "Orders"17189 ],17190 "summary": "Run one line of the trading command grammar",17191 "description": "Deterministic grammar (no model): LONG|SHORT <asset>-PERP <notional> [x<lev>] [LIMIT <px>] [SL <px>] [TP <px>] [ON <venue>], CLOSE <asset>-PERP [pct%], CANCEL ORDER <id>, CANCEL ALL, SHOW POSITIONS|BALANCES|ORDERS|RISK, STOP ALL AGENTS, KILL, and for the owner BUY/SELL (spot).\n\nThe scope checked is the one of the operation the command resolves to: an order needs `orders:execute` (`orders:prepare` with `dryRun`), CLOSE `positions:manage`, CANCEL `orders:cancel`, SHOW the matching read scope, KILL `positions:manage`.\n\nResolution uses the owner's stored defaults (GET/PUT /api/v1/developer/command-defaults) and nothing else: a command the defaults do not settle answers 409 `ambiguous_command` with the questions in `data.questions` and executes nothing.\n\n`kind` says what the command resolved to: `query` (the read answer is in `data`), `control` (a cancel or the kill switch) or `order`. A spot order (BUY ETH 100 USDC, SELL ETH 0.5) is the owner's: it becomes a swap proposal approved with the passkey. The venue engine that executes the order can refuse it with a code of its own rules that this list does not name (`x-spw-errors-open`): the HTTP status still tells the class, and the order is in `data.order`.",17192 "security": [17193 {17194 "bearerKey": [17195 "orders:prepare"17196 ]17197 }17198 ],17199 "x-spw-scope": "orders:prepare",17200 "x-spw-implemented": true,17201 "x-spw-idempotent": true,17202 "x-spw-errors": [17203 {17204 "status": 400,17205 "code": "bad_policy"17206 },17207 {17208 "status": 400,17209 "code": "bad_request"17210 },17211 {17212 "status": 400,17213 "code": "idempotency"17214 },17215 {17216 "status": 400,17217 "code": "invalid_order"17218 },17219 {17220 "status": 400,17221 "code": "parse_error"17222 },17223 {17224 "status": 400,17225 "code": "stale_request"17226 },17227 {17228 "status": 401,17229 "code": "unauthenticated"17230 },17231 {17232 "status": 403,17233 "code": "execution_disabled"17234 },17235 {17236 "status": 403,17237 "code": "gmx_disabled"17238 },17239 {17240 "status": 403,17241 "code": "gmx_requires_owner_passkey"17242 },17243 {17244 "status": 403,17245 "code": "insufficient_scope"17246 },17247 {17248 "status": 403,17249 "code": "ip_not_allowed"17250 },17251 {17252 "status": 403,17253 "code": "key_limit_exceeded"17254 },17255 {17256 "status": 403,17257 "code": "mainnet_disabled"17258 },17259 {17260 "status": 403,17261 "code": "mandate_denied"17262 },17263 {17264 "status": 403,17265 "code": "mandate_integrity"17266 },17267 {17268 "status": 403,17269 "code": "mandate_mainnet_disabled"17270 },17271 {17272 "status": 403,17273 "code": "mandate_not_approved"17274 },17275 {17276 "status": 403,17277 "code": "mandate_required"17278 },17279 {17280 "status": 403,17281 "code": "mixed_credentials"17282 },17283 {17284 "status": 403,17285 "code": "not_your_order"17286 },17287 {17288 "status": 403,17289 "code": "owner_session_required"17290 },17291 {17292 "status": 403,17293 "code": "position_not_attributable"17294 },17295 {17296 "status": 403,17297 "code": "restricted"17298 },17299 {17300 "status": 403,17301 "code": "spot_execution_requires_agent_vault"17302 },17303 {17304 "status": 403,17305 "code": "venue_restricted"17306 },17307 {17308 "status": 404,17309 "code": "unknown_account"17310 },17311 {17312 "status": 404,17313 "code": "unknown_instrument"17314 },17315 {17316 "status": 404,17317 "code": "unknown_order"17318 },17319 {17320 "status": 404,17321 "code": "unknown_venue"17322 },17323 {17324 "status": 409,17325 "code": "account_has_active_mandate"17326 },17327 {17328 "status": 409,17329 "code": "account_required"17330 },17331 {17332 "status": 409,17333 "code": "ambiguous_command"17334 },17335 {17336 "status": 409,17337 "code": "ambiguous_order"17338 },17339 {17340 "status": 409,17341 "code": "bad_state"17342 },17343 {17344 "status": 409,17345 "code": "idempotency_conflict"17346 },17347 {17348 "status": 409,17349 "code": "idempotency_in_progress"17350 },17351 {17352 "status": 422,17353 "code": "authorization_expired"17354 },17355 {17356 "status": 422,17357 "code": "bad_input"17358 },17359 {17360 "status": 422,17361 "code": "bad_mark"17362 },17363 {17364 "status": 422,17365 "code": "bad_order"17366 },17367 {17368 "status": 422,17369 "code": "bad_policy"17370 },17371 {17372 "status": 422,17373 "code": "below_min_notional"17374 },17375 {17376 "status": 422,17377 "code": "below_min_size"17378 },17379 {17380 "status": 422,17381 "code": "cancel_in_app"17382 },17383 {17384 "status": 422,17385 "code": "daily_loss_exceeded"17386 },17387 {17388 "status": 422,17389 "code": "data_mismatch"17390 },17391 {17392 "status": 422,17393 "code": "duplicate_client_id"17394 },17395 {17396 "status": 422,17397 "code": "fee_cap_not_expressible"17398 },17399 {17400 "status": 422,17401 "code": "gmx_leverage_required"17402 },17403 {17404 "status": 422,17405 "code": "gross_exposure_exceeded"17406 },17407 {17408 "status": 422,17409 "code": "halted"17410 },17411 {17412 "status": 422,17413 "code": "inconsistent_prices"17414 },17415 {17416 "status": 422,17417 "code": "instrument_halted"17418 },17419 {17420 "status": 422,17421 "code": "instrument_mismatch"17422 },17423 {17424 "status": 422,17425 "code": "instrument_not_allowed"17426 },17427 {17428 "status": 422,17429 "code": "instrument_reduce_only"17430 },17431 {17432 "status": 422,17433 "code": "insufficient_collateral"17434 },17435 {17436 "status": 422,17437 "code": "invalid_order"17438 },17439 {17440 "status": 422,17441 "code": "leverage_exceeded"17442 },17443 {17444 "status": 422,17445 "code": "leverage_mismatch"17446 },17447 {17448 "status": 422,17449 "code": "liquidation_too_close"17450 },17451 {17452 "status": 422,17453 "code": "live_not_available"17454 },17455 {17456 "status": 422,17457 "code": "mandate_mismatch"17458 },17459 {17460 "status": 422,17461 "code": "mandate_none"17462 },17463 {17464 "status": 422,17465 "code": "mandate_wind_down"17466 },17467 {17468 "status": 422,17469 "code": "mark_index_divergence"17470 },17471 {17472 "status": 422,17473 "code": "missing_balance"17474 },17475 {17476 "status": 422,17477 "code": "missing_reference_price"17478 },17479 {17480 "status": 422,17481 "code": "mode_read_only"17482 },17483 {17484 "status": 422,17485 "code": "no_account"17486 },17487 {17488 "status": 422,17489 "code": "no_client_id_format"17490 },17491 {17492 "status": 422,17493 "code": "no_instrument"17494 },17495 {17496 "status": 422,17497 "code": "no_position"17498 },17499 {17500 "status": 422,17501 "code": "not_reducing"17502 },17503 {17504 "status": 422,17505 "code": "order_notional_exceeded"17506 },17507 {17508 "status": 422,17509 "code": "order_rate_day"17510 },17511 {17512 "status": 422,17513 "code": "order_rate_minute"17514 },17515 {17516 "status": 422,17517 "code": "paper_unsupported"17518 },17519 {17520 "status": 422,17521 "code": "position_notional_exceeded"17522 },17523 {17524 "status": 422,17525 "code": "price_deviation"17526 },17527 {17528 "status": 422,17529 "code": "price_not_on_tick"17530 },17531 {17532 "status": 422,17533 "code": "price_required"17534 },17535 {17536 "status": 422,17537 "code": "reduce_only_would_flip"17538 },17539 {17540 "status": 422,17541 "code": "reduce_only_would_increase"17542 },17543 {17544 "status": 422,17545 "code": "risk_denied"17546 },17547 {17548 "status": 422,17549 "code": "size_not_on_lot"17550 },17551 {17552 "status": 422,17553 "code": "spot_buy_needs_quote_amount"17554 },17555 {17556 "status": 422,17557 "code": "spot_market_only"17558 },17559 {17560 "status": 422,17561 "code": "spot_paper_not_available"17562 },17563 {17564 "status": 422,17565 "code": "spot_via_swap_screen"17566 },17567 {17568 "status": 422,17569 "code": "stale_book"17570 },17571 {17572 "status": 422,17573 "code": "stale_ticker"17574 },17575 {17576 "status": 422,17577 "code": "swap_not_enabled"17578 },17579 {17580 "status": 422,17581 "code": "total_loss_exceeded"17582 },17583 {17584 "status": 422,17585 "code": "trigger_required"17586 },17587 {17588 "status": 422,17589 "code": "unknown_instrument"17590 },17591 {17592 "status": 422,17593 "code": "unsupported_asset"17594 },17595 {17596 "status": 422,17597 "code": "venue_not_wired"17598 },17599 {17600 "status": 422,17601 "code": "venue_rejected"17602 },17603 {17604 "status": 422,17605 "code": "zero_size"17606 },17607 {17608 "status": 423,17609 "code": "halted"17610 },17611 {17612 "status": 423,17613 "code": "kill_switch_active"17614 },17615 {17616 "status": 423,17617 "code": "read_only_mode"17618 },17619 {17620 "status": 429,17621 "code": "auth_throttled"17622 },17623 {17624 "status": 429,17625 "code": "rate_limited"17626 },17627 {17628 "status": 500,17629 "code": "internal"17630 },17631 {17632 "status": 501,17633 "code": "execution_not_wired"17634 },17635 {17636 "status": 502,17637 "code": "swap_flow_failed"17638 },17639 {17640 "status": 503,17641 "code": "authorization_unknown"17642 },17643 {17644 "status": 503,17645 "code": "mandate_unavailable"17646 },17647 {17648 "status": 503,17649 "code": "no_liquidity"17650 },17651 {17652 "status": 503,17653 "code": "service_unavailable"17654 },17655 {17656 "status": 503,17657 "code": "signer_unreachable"17658 },17659 {17660 "status": 503,17661 "code": "stale_data"17662 },17663 {17664 "status": 503,17665 "code": "unknown_instrument"17666 },17667 {17668 "status": 503,17669 "code": "venue_rate_limited"17670 },17671 {17672 "status": 503,17673 "code": "venue_timeout"17674 },17675 {17676 "status": 503,17677 "code": "venue_unavailable"17678 }17679 ],17680 "x-spw-errors-open": true,17681 "x-spw-example-recorded": true,17682 "x-spw-example-note": "A dry run: the canonical order the line resolves to, and nothing created. Needs the owner's command defaults (see Commands).",17683 "x-codeSamples": [17684 {17685 "lang": "Shell",17686 "label": "curl",17687 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/commands\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"text\":\"LONG BTC-PERP 100\",\"mode\":\"paper\",\"dryRun\":true}'"17688 },17689 {17690 "lang": "TypeScript",17691 "label": "TypeScript",17692 "source": "const r = await client.runCommand('LONG BTC-PERP 100', { mode: 'paper', dryRun: true });\nif (r.kind === 'order' && !r.executed) console.log(r.order, r.hash);"17693 },17694 {17695 "lang": "Python",17696 "label": "Python",17697 "source": "r = client.run_command(\"LONG BTC-PERP 100\", mode=\"paper\", dry_run=True)"17698 }17699 ],17700 "parameters": [17701 {17702 "name": "Idempotency-Key",17703 "in": "header",17704 "required": true,17705 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",17706 "schema": {17707 "type": "string",17708 "pattern": "^[A-Za-z0-9._:-]{8,100}$"17709 }17710 },17711 {17712 "name": "X-SPW-Timestamp",17713 "in": "header",17714 "required": false,17715 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",17716 "schema": {17717 "type": "string",17718 "pattern": "^\\d{9,11}$"17719 }17720 }17721 ],17722 "requestBody": {17723 "required": true,17724 "content": {17725 "application/json": {17726 "schema": {17727 "type": "object",17728 "properties": {17729 "text": {17730 "type": "string",17731 "minLength": 1,17732 "maxLength": 300,17733 "description": "one line of the trading command grammar, English or French: LONG BTC-PERP 500 x2, CLOSE BTC-PERP 50%, CANCEL ORDER <id>, SHOW POSITIONS, KILL …"17734 },17735 "mode": {17736 "default": "paper",17737 "type": "string",17738 "enum": [17739 "paper",17740 "live"17741 ],17742 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."17743 },17744 "accountId": {17745 "description": "paper account or venue account; required when the wallet has several on the venue",17746 "type": "string",17747 "format": "uuid",17748 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"17749 },17750 "dryRun": {17751 "default": false,17752 "description": "true: answer the canonical order (or the control) the command resolves to, and do nothing",17753 "type": "boolean"17754 }17755 },17756 "required": [17757 "text"17758 ],17759 "additionalProperties": false17760 },17761 "example": {17762 "text": "LONG BTC-PERP 100",17763 "mode": "paper",17764 "dryRun": true17765 }17766 }17767 }17768 },17769 "responses": {17770 "200": {17771 "description": "OK (the example is a recorded answer)",17772 "content": {17773 "application/json": {17774 "schema": {17775 "anyOf": [17776 {17777 "type": "object",17778 "properties": {17779 "kind": {17780 "type": "string",17781 "const": "query"17782 },17783 "command": {17784 "type": "string",17785 "description": "the parsed command type"17786 },17787 "mode": {17788 "type": "string",17789 "enum": [17790 "paper",17791 "live"17792 ],17793 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."17794 },17795 "dryRun": {17796 "type": "boolean"17797 },17798 "query": {17799 "type": "string"17800 },17801 "data": {17802 "type": "object",17803 "properties": {},17804 "additionalProperties": {},17805 "description": "the answer of the matching read operation"17806 }17807 },17808 "required": [17809 "kind",17810 "command",17811 "mode",17812 "dryRun",17813 "query",17814 "data"17815 ],17816 "additionalProperties": {},17817 "description": "SHOW …"17818 },17819 {17820 "type": "object",17821 "properties": {17822 "kind": {17823 "type": "string",17824 "const": "control"17825 },17826 "command": {17827 "type": "string",17828 "description": "the parsed command type"17829 },17830 "mode": {17831 "type": "string",17832 "enum": [17833 "paper",17834 "live"17835 ],17836 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."17837 },17838 "dryRun": {17839 "type": "boolean"17840 },17841 "executed": {17842 "type": "boolean"17843 },17844 "control": {17845 "type": "object",17846 "properties": {17847 "type": {17848 "type": "string",17849 "enum": [17850 "cancel_order",17851 "cancel_all",17852 "kill_switch_on",17853 "stop_all_agents"17854 ]17855 }17856 },17857 "required": [17858 "type"17859 ],17860 "additionalProperties": {}17861 },17862 "result": {17863 "description": "CANCEL ORDER, executed: the answer of the cancel",17864 "type": "object",17865 "properties": {},17866 "additionalProperties": {}17867 },17868 "results": {17869 "description": "CANCEL ALL, executed: one row per order",17870 "type": "array",17871 "items": {17872 "type": "object",17873 "properties": {17874 "id": {17875 "type": "string"17876 },17877 "ok": {17878 "type": "boolean"17879 }17880 },17881 "required": [17882 "id",17883 "ok"17884 ],17885 "additionalProperties": {}17886 }17887 },17888 "orders": {17889 "description": "CANCEL ALL, dry run: the ids that would be cancelled",17890 "type": "array",17891 "items": {17892 "type": "string"17893 }17894 },17895 "killSwitch": {17896 "$ref": "#/components/schemas/Switch"17897 }17898 },17899 "required": [17900 "kind",17901 "command",17902 "mode",17903 "dryRun",17904 "executed",17905 "control"17906 ],17907 "additionalProperties": {},17908 "description": "CANCEL, KILL, STOP ALL AGENTS"17909 },17910 {17911 "type": "object",17912 "properties": {17913 "kind": {17914 "type": "string",17915 "const": "order"17916 },17917 "command": {17918 "type": "string",17919 "description": "the parsed command type"17920 },17921 "mode": {17922 "type": "string",17923 "enum": [17924 "paper",17925 "live"17926 ],17927 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."17928 },17929 "dryRun": {17930 "type": "boolean"17931 },17932 "executed": {17933 "type": "boolean",17934 "const": false17935 },17936 "order": {17937 "$ref": "#/components/schemas/CanonicalOrder",17938 "description": "the canonical order the command resolves to; nothing was created"17939 },17940 "hash": {17941 "type": "string"17942 },17943 "attached": {17944 "type": "array",17945 "items": {17946 "type": "object",17947 "properties": {17948 "role": {17949 "type": "string",17950 "enum": [17951 "stop_loss",17952 "take_profit"17953 ]17954 },17955 "placed": {17956 "type": "boolean"17957 },17958 "note": {17959 "type": "string"17960 }17961 },17962 "required": [17963 "role",17964 "placed",17965 "note"17966 ],17967 "additionalProperties": {}17968 }17969 },17970 "preview": {17971 "description": "spot: the preview of the swap the order would become",17972 "type": "object",17973 "properties": {},17974 "additionalProperties": {}17975 }17976 },17977 "required": [17978 "kind",17979 "command",17980 "mode",17981 "dryRun",17982 "executed",17983 "order",17984 "hash",17985 "attached"17986 ],17987 "additionalProperties": {},17988 "description": "an order command with `dryRun`"17989 },17990 {17991 "type": "object",17992 "properties": {17993 "kind": {17994 "type": "string",17995 "const": "order"17996 },17997 "command": {17998 "type": "string",17999 "description": "the parsed command type"18000 },18001 "mode": {18002 "type": "string",18003 "enum": [18004 "paper",18005 "live"18006 ],18007 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."18008 },18009 "dryRun": {18010 "type": "boolean"18011 },18012 "executed": {18013 "type": "boolean",18014 "const": true18015 },18016 "order": {18017 "$ref": "#/components/schemas/Order",18018 "description": "the order that was placed, as POST /orders answers it"18019 },18020 "canonical": {18021 "$ref": "#/components/schemas/CanonicalOrder",18022 "description": "the canonical order that was placed"18023 },18024 "hash": {18025 "type": "string"18026 },18027 "idempotent": {18028 "type": "boolean"18029 },18030 "approval": {18031 "anyOf": [18032 {18033 "type": "object",18034 "properties": {},18035 "additionalProperties": {}18036 },18037 {18038 "type": "null"18039 }18040 ]18041 },18042 "attached": {18043 "type": "array",18044 "items": {18045 "type": "object",18046 "properties": {18047 "role": {18048 "type": "string",18049 "enum": [18050 "stop_loss",18051 "take_profit"18052 ]18053 },18054 "placed": {18055 "type": "boolean"18056 },18057 "note": {18058 "type": "string"18059 }18060 },18061 "required": [18062 "role",18063 "placed",18064 "note"18065 ],18066 "additionalProperties": {}18067 }18068 }18069 },18070 "required": [18071 "kind",18072 "command",18073 "mode",18074 "dryRun",18075 "executed",18076 "order",18077 "canonical",18078 "hash",18079 "idempotent",18080 "approval",18081 "attached"18082 ],18083 "additionalProperties": {},18084 "description": "an order command, executed"18085 }18086 ]18087 },18088 "example": {18089 "command": "perp_open",18090 "mode": "paper",18091 "dryRun": true,18092 "kind": "order",18093 "order": {18094 "v": 1,18095 "venue": "hyperliquid",18096 "network": "mainnet",18097 "instrument": "hyperliquid:BTC",18098 "marketKind": "perp",18099 "side": "buy",18100 "type": "market",18101 "size": null,18102 "notional": "100",18103 "limitPrice": null,18104 "triggerPrice": null,18105 "reduceOnly": false,18106 "tif": "ioc",18107 "maxSlippageBps": 50,18108 "maxFeeUsd": "0.1",18109 "leverage": "2",18110 "marginMode": "cross",18111 "clientOrderId": "0x58617397cbaee774b5a74ada6581a070",18112 "mode": "paper",18113 "principal": {18114 "kind": "api_key",18115 "id": "spk_0123456789ab"18116 },18117 "mandateId": "84f954ea-0c25-4985-bc19-901d510964d7",18118 "createdAt": 1794953783632,18119 "expiresAt": 179495384363218120 },18121 "hash": "5a6980aa9a3668f4618c2186974428ca40b83bc68ce2be2194f5a02732c57db5",18122 "attached": [],18123 "executed": false18124 }18125 }18126 }18127 },18128 "400": {18129 "description": "The request is not valid: `bad_policy`, `bad_request`, `idempotency`, `invalid_order`, `parse_error`, `stale_request`",18130 "content": {18131 "application/json": {18132 "schema": {18133 "$ref": "#/components/schemas/Error"18134 }18135 }18136 }18137 },18138 "401": {18139 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",18140 "content": {18141 "application/json": {18142 "schema": {18143 "$ref": "#/components/schemas/Error"18144 }18145 }18146 }18147 },18148 "403": {18149 "description": "Authenticated, and refused: `execution_disabled`, `gmx_disabled`, `gmx_requires_owner_passkey`, `insufficient_scope`, `ip_not_allowed`, `key_limit_exceeded`, `mainnet_disabled`, `mandate_denied`, `mandate_integrity`, `mandate_mainnet_disabled`, `mandate_not_approved`, `mandate_required`, `mixed_credentials`, `not_your_order`, `owner_session_required`, `position_not_attributable`, `restricted`, `spot_execution_requires_agent_vault`, `venue_restricted`",18150 "content": {18151 "application/json": {18152 "schema": {18153 "$ref": "#/components/schemas/Error"18154 }18155 }18156 }18157 },18158 "404": {18159 "description": "The object named by the request does not exist: `unknown_account`, `unknown_instrument`, `unknown_order`, `unknown_venue`",18160 "content": {18161 "application/json": {18162 "schema": {18163 "$ref": "#/components/schemas/Error"18164 }18165 }18166 }18167 },18168 "409": {18169 "description": "The request conflicts with the state of the object, or needs a choice: `account_has_active_mandate`, `account_required`, `ambiguous_command`, `ambiguous_order`, `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",18170 "content": {18171 "application/json": {18172 "schema": {18173 "$ref": "#/components/schemas/Error"18174 }18175 }18176 }18177 },18178 "422": {18179 "description": "A valid request that cannot be carried out: `authorization_expired`, `bad_input`, `bad_mark`, `bad_order`, `bad_policy`, `below_min_notional`, `below_min_size`, `cancel_in_app`, `daily_loss_exceeded`, `data_mismatch`, `duplicate_client_id`, `fee_cap_not_expressible`, `gmx_leverage_required`, `gross_exposure_exceeded`, `halted`, `inconsistent_prices`, `instrument_halted`, `instrument_mismatch`, `instrument_not_allowed`, `instrument_reduce_only`, `insufficient_collateral`, `invalid_order`, `leverage_exceeded`, `leverage_mismatch`, `liquidation_too_close`, `live_not_available`, `mandate_mismatch`, `mandate_none`, `mandate_wind_down`, `mark_index_divergence`, `missing_balance`, `missing_reference_price`, `mode_read_only`, `no_account`, `no_client_id_format`, `no_instrument`, `no_position`, `not_reducing`, `order_notional_exceeded`, `order_rate_day`, `order_rate_minute`, `paper_unsupported`, `position_notional_exceeded`, `price_deviation`, `price_not_on_tick`, `price_required`, `reduce_only_would_flip`, `reduce_only_would_increase`, `risk_denied`, `size_not_on_lot`, `spot_buy_needs_quote_amount`, `spot_market_only`, `spot_paper_not_available`, `spot_via_swap_screen`, `stale_book`, `stale_ticker`, `swap_not_enabled`, `total_loss_exceeded`, `trigger_required`, `unknown_instrument`, `unsupported_asset`, `venue_not_wired`, `venue_rejected`, `zero_size`",18180 "content": {18181 "application/json": {18182 "schema": {18183 "$ref": "#/components/schemas/Error"18184 }18185 }18186 }18187 },18188 "423": {18189 "description": "Blocked by the kill switch, by read-only mode or by a halt: `halted`, `kill_switch_active`, `read_only_mode`",18190 "content": {18191 "application/json": {18192 "schema": {18193 "$ref": "#/components/schemas/Error"18194 }18195 }18196 }18197 },18198 "429": {18199 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",18200 "content": {18201 "application/json": {18202 "schema": {18203 "$ref": "#/components/schemas/Error"18204 }18205 }18206 }18207 },18208 "500": {18209 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",18210 "content": {18211 "application/json": {18212 "schema": {18213 "$ref": "#/components/schemas/Error"18214 }18215 }18216 }18217 },18218 "501": {18219 "description": "Declared but not connected yet. Never a success: nothing was done: `execution_not_wired`",18220 "content": {18221 "application/json": {18222 "schema": {18223 "$ref": "#/components/schemas/Error"18224 }18225 }18226 }18227 },18228 "502": {18229 "description": "Error: `swap_flow_failed`",18230 "content": {18231 "application/json": {18232 "schema": {18233 "$ref": "#/components/schemas/Error"18234 }18235 }18236 }18237 },18238 "503": {18239 "description": "A backing service is unavailable; nothing was done: `authorization_unknown`, `mandate_unavailable`, `no_liquidity`, `service_unavailable`, `signer_unreachable`, `stale_data`, `unknown_instrument`, `venue_rate_limited`, `venue_timeout`, `venue_unavailable`",18240 "content": {18241 "application/json": {18242 "schema": {18243 "$ref": "#/components/schemas/Error"18244 }18245 }18246 }18247 }18248 }18249 }18250 },18251 "/api/v1/trading/risk/kill-switch": {18252 "post": {18253 "operationId": "engageKillSwitch",18254 "tags": [18255 "Risk"18256 ],18257 "summary": "Engage the global kill switch",18258 "description": "Blocks every NEW risk for every principal on every venue and in every mode; cancels and strictly reducing orders still pass. Engaging needs no mandate (it only removes risk) and takes no Idempotency-Key: engaging a switch that is on changes nothing. Releasing it is NOT possible with a key: owner session and passkey only.",18259 "security": [18260 {18261 "bearerKey": [18262 "positions:manage"18263 ]18264 }18265 ],18266 "x-spw-scope": "positions:manage",18267 "x-spw-implemented": true,18268 "x-spw-errors": [18269 {18270 "status": 400,18271 "code": "bad_request"18272 },18273 {18274 "status": 401,18275 "code": "unauthenticated"18276 },18277 {18278 "status": 403,18279 "code": "insufficient_scope"18280 },18281 {18282 "status": 403,18283 "code": "ip_not_allowed"18284 },18285 {18286 "status": 403,18287 "code": "mixed_credentials"18288 },18289 {18290 "status": 429,18291 "code": "auth_throttled"18292 },18293 {18294 "status": 429,18295 "code": "rate_limited"18296 },18297 {18298 "status": 500,18299 "code": "internal"18300 }18301 ],18302 "x-spw-example-recorded": true,18303 "x-spw-example-note": "A key can engage it and can never release it.",18304 "x-codeSamples": [18305 {18306 "lang": "Shell",18307 "label": "curl",18308 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/risk/kill-switch\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"documentation example\"}'"18309 },18310 {18311 "lang": "TypeScript",18312 "label": "TypeScript",18313 "source": "await client.engageKillSwitch('bot detected a runaway loop');"18314 },18315 {18316 "lang": "Python",18317 "label": "Python",18318 "source": "client.engage_kill_switch(\"bot detected a runaway loop\")"18319 }18320 ],18321 "parameters": [],18322 "requestBody": {18323 "required": true,18324 "content": {18325 "application/json": {18326 "schema": {18327 "type": "object",18328 "properties": {18329 "reason": {18330 "default": "",18331 "description": "why, for the audit trail and the `risk.kill_switch` webhook",18332 "type": "string",18333 "maxLength": 20018334 }18335 },18336 "additionalProperties": false18337 },18338 "example": {18339 "reason": "documentation example"18340 }18341 }18342 }18343 },18344 "responses": {18345 "200": {18346 "description": "OK (the example is a recorded answer)",18347 "content": {18348 "application/json": {18349 "schema": {18350 "type": "object",18351 "properties": {18352 "killSwitch": {18353 "$ref": "#/components/schemas/Switch"18354 },18355 "readOnly": {18356 "$ref": "#/components/schemas/Switch"18357 }18358 },18359 "required": [18360 "killSwitch",18361 "readOnly"18362 ],18363 "additionalProperties": {}18364 },18365 "example": {18366 "killSwitch": {18367 "on": true,18368 "at": 1794953765956,18369 "by": {18370 "kind": "api_key",18371 "id": "spk_0123456789ab"18372 },18373 "reason": "documentation example"18374 },18375 "readOnly": {18376 "on": false,18377 "at": null,18378 "by": null,18379 "reason": null18380 }18381 }18382 }18383 }18384 },18385 "400": {18386 "description": "The request is not valid: `bad_request`",18387 "content": {18388 "application/json": {18389 "schema": {18390 "$ref": "#/components/schemas/Error"18391 }18392 }18393 }18394 },18395 "401": {18396 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",18397 "content": {18398 "application/json": {18399 "schema": {18400 "$ref": "#/components/schemas/Error"18401 }18402 }18403 }18404 },18405 "403": {18406 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",18407 "content": {18408 "application/json": {18409 "schema": {18410 "$ref": "#/components/schemas/Error"18411 }18412 }18413 }18414 },18415 "429": {18416 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",18417 "content": {18418 "application/json": {18419 "schema": {18420 "$ref": "#/components/schemas/Error"18421 }18422 }18423 }18424 },18425 "500": {18426 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",18427 "content": {18428 "application/json": {18429 "schema": {18430 "$ref": "#/components/schemas/Error"18431 }18432 }18433 }18434 }18435 }18436 }18437 },18438 "/api/v1/trading/strategies/{id}/backtest": {18439 "post": {18440 "operationId": "backtestStrategy",18441 "tags": [18442 "Strategies"18443 ],18444 "summary": "Run the backtest of a strategy version (asynchronous job)",18445 "description": "Answers a job id; read it with GET /jobs/{id}. The result is a BACKTEST report on the version — never a performance figure.",18446 "security": [18447 {18448 "bearerKey": [18449 "strategies:manage"18450 ]18451 }18452 ],18453 "x-spw-scope": "strategies:manage",18454 "x-spw-implemented": true,18455 "x-spw-idempotent": true,18456 "x-spw-errors": [18457 {18458 "status": 400,18459 "code": "bad_request"18460 },18461 {18462 "status": 400,18463 "code": "idempotency"18464 },18465 {18466 "status": 400,18467 "code": "stale_request"18468 },18469 {18470 "status": 401,18471 "code": "unauthenticated"18472 },18473 {18474 "status": 403,18475 "code": "insufficient_scope"18476 },18477 {18478 "status": 403,18479 "code": "ip_not_allowed"18480 },18481 {18482 "status": 403,18483 "code": "mixed_credentials"18484 },18485 {18486 "status": 403,18487 "code": "restricted"18488 },18489 {18490 "status": 404,18491 "code": "not_found"18492 },18493 {18494 "status": 409,18495 "code": "idempotency_conflict"18496 },18497 {18498 "status": 409,18499 "code": "idempotency_in_progress"18500 },18501 {18502 "status": 429,18503 "code": "auth_throttled"18504 },18505 {18506 "status": 429,18507 "code": "rate_limited"18508 },18509 {18510 "status": 500,18511 "code": "internal"18512 }18513 ],18514 "x-spw-example-recorded": true,18515 "x-codeSamples": [18516 {18517 "lang": "Shell",18518 "label": "curl",18519 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/backtest\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{}'"18520 },18521 {18522 "lang": "TypeScript",18523 "label": "TypeScript",18524 "source": "const { job } = await client.backtestStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e');\nconst done = await client.waitForJob(job.id);"18525 },18526 {18527 "lang": "Python",18528 "label": "Python",18529 "source": "job = client.backtest_strategy(\"450bc266-e1a9-4807-9113-7da6773ddb4e\").job\ndone = client.wait_for_job(job.id)"18530 }18531 ],18532 "parameters": [18533 {18534 "name": "id",18535 "in": "path",18536 "required": true,18537 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",18538 "schema": {18539 "type": "string",18540 "minLength": 1,18541 "maxLength": 20018542 },18543 "example": "450bc266-e1a9-4807-9113-7da6773ddb4e"18544 },18545 {18546 "name": "Idempotency-Key",18547 "in": "header",18548 "required": true,18549 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",18550 "schema": {18551 "type": "string",18552 "pattern": "^[A-Za-z0-9._:-]{8,100}$"18553 }18554 },18555 {18556 "name": "X-SPW-Timestamp",18557 "in": "header",18558 "required": false,18559 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",18560 "schema": {18561 "type": "string",18562 "pattern": "^\\d{9,11}$"18563 }18564 }18565 ],18566 "requestBody": {18567 "required": true,18568 "content": {18569 "application/json": {18570 "schema": {18571 "type": "object",18572 "properties": {18573 "symbols": {18574 "description": "default: the agent's universe",18575 "minItems": 1,18576 "maxItems": 12,18577 "type": "array",18578 "items": {18579 "type": "string",18580 "pattern": "^[A-Z0-9]{2,15}$"18581 }18582 },18583 "interval": {18584 "description": "bar interval; default: the agent's",18585 "type": "string",18586 "enum": [18587 "1h",18588 "1d"18589 ]18590 }18591 },18592 "additionalProperties": false18593 },18594 "example": {}18595 }18596 }18597 },18598 "responses": {18599 "200": {18600 "description": "OK (the example is a recorded answer)",18601 "content": {18602 "application/json": {18603 "schema": {18604 "type": "object",18605 "properties": {18606 "job": {18607 "type": "object",18608 "properties": {18609 "id": {18610 "type": "string"18611 },18612 "kind": {18613 "type": "string"18614 },18615 "status": {18616 "type": "string",18617 "enum": [18618 "queued",18619 "running",18620 "done",18621 "failed",18622 "cancelled"18623 ]18624 },18625 "attempts": {18626 "type": "integer",18627 "minimum": -9007199254740991,18628 "maximum": 900719925474099118629 }18630 },18631 "required": [18632 "id",18633 "kind",18634 "status",18635 "attempts"18636 ],18637 "additionalProperties": {}18638 },18639 "label": {18640 "type": "string"18641 }18642 },18643 "required": [18644 "job"18645 ],18646 "additionalProperties": false18647 },18648 "example": {18649 "job": {18650 "id": "43823b3b-af8c-4c78-8527-638ea5fde77b",18651 "agentId": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",18652 "kind": "backtest",18653 "status": "queued",18654 "deadLettered": false,18655 "attempts": 0,18656 "maxAttempts": 2,18657 "runAt": 1794953786889,18658 "error": null,18659 "result": null,18660 "createdAt": 1794953786889,18661 "updatedAt": 1794953786889,18662 "finishedAt": null18663 },18664 "label": "backtest"18665 }18666 }18667 }18668 },18669 "400": {18670 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",18671 "content": {18672 "application/json": {18673 "schema": {18674 "$ref": "#/components/schemas/Error"18675 }18676 }18677 }18678 },18679 "401": {18680 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",18681 "content": {18682 "application/json": {18683 "schema": {18684 "$ref": "#/components/schemas/Error"18685 }18686 }18687 }18688 },18689 "403": {18690 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",18691 "content": {18692 "application/json": {18693 "schema": {18694 "$ref": "#/components/schemas/Error"18695 }18696 }18697 }18698 },18699 "404": {18700 "description": "The object named by the request does not exist: `not_found`",18701 "content": {18702 "application/json": {18703 "schema": {18704 "$ref": "#/components/schemas/Error"18705 }18706 }18707 }18708 },18709 "409": {18710 "description": "The request conflicts with the state of the object, or needs a choice: `idempotency_conflict`, `idempotency_in_progress`",18711 "content": {18712 "application/json": {18713 "schema": {18714 "$ref": "#/components/schemas/Error"18715 }18716 }18717 }18718 },18719 "429": {18720 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",18721 "content": {18722 "application/json": {18723 "schema": {18724 "$ref": "#/components/schemas/Error"18725 }18726 }18727 }18728 },18729 "500": {18730 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",18731 "content": {18732 "application/json": {18733 "schema": {18734 "$ref": "#/components/schemas/Error"18735 }18736 }18737 }18738 }18739 }18740 }18741 },18742 "/api/v1/trading/strategies/{id}/start": {18743 "post": {18744 "operationId": "startStrategy",18745 "tags": [18746 "Strategies"18747 ],18748 "summary": "Start the agent a strategy version is pinned to",18749 "description": "research and paper sign nothing. Starting a perp agent on `paper` creates its PAPER trading mandate (nothing is signed; its orders go through the unified order service, the risk engine and that mandate): the key needs `agents:manage` and may not be restricted away from the agent's venue or instruments (403 `insufficient_scope` / `restricted`), and a halted paper account answers 409 `halted`. `live` is accepted ONLY when a mandate approved by the owner with the passkey is in force for this agent — for a perp agent a TRADING mandate, which only the owner activates: a key answers 409 `mandate_required` (a key, an agent or this API can never approve a mandate). Families that cannot go live answer 409 `live_unavailable` with the reason.",18750 "security": [18751 {18752 "bearerKey": [18753 "strategies:manage"18754 ]18755 }18756 ],18757 "x-spw-scope": "strategies:manage",18758 "x-spw-implemented": true,18759 "x-spw-idempotent": true,18760 "x-spw-errors": [18761 {18762 "status": 400,18763 "code": "bad_request"18764 },18765 {18766 "status": 400,18767 "code": "idempotency"18768 },18769 {18770 "status": 400,18771 "code": "stale_request"18772 },18773 {18774 "status": 401,18775 "code": "unauthenticated"18776 },18777 {18778 "status": 403,18779 "code": "insufficient_scope"18780 },18781 {18782 "status": 403,18783 "code": "ip_not_allowed"18784 },18785 {18786 "status": 403,18787 "code": "mixed_credentials"18788 },18789 {18790 "status": 403,18791 "code": "owner_required"18792 },18793 {18794 "status": 403,18795 "code": "restricted"18796 },18797 {18798 "status": 404,18799 "code": "not_found"18800 },18801 {18802 "status": 409,18803 "code": "bad_report"18804 },18805 {18806 "status": 409,18807 "code": "bad_request"18808 },18809 {18810 "status": 409,18811 "code": "bad_state"18812 },18813 {18814 "status": 409,18815 "code": "halted"18816 },18817 {18818 "status": 409,18819 "code": "idempotency_conflict"18820 },18821 {18822 "status": 409,18823 "code": "idempotency_in_progress"18824 },18825 {18826 "status": 409,18827 "code": "live_unavailable"18828 },18829 {18830 "status": 409,18831 "code": "mandate_required"18832 },18833 {18834 "status": 409,18835 "code": "no_report"18836 },18837 {18838 "status": 409,18839 "code": "no_strategy"18840 },18841 {18842 "status": 409,18843 "code": "other_version"18844 },18845 {18846 "status": 429,18847 "code": "auth_throttled"18848 },18849 {18850 "status": 429,18851 "code": "rate_limited"18852 },18853 {18854 "status": 500,18855 "code": "internal"18856 }18857 ],18858 "x-spw-example-recorded": true,18859 "x-spw-example-note": "Only the most recent version of an agent starts, and only once its backtest is done (409 `other_version`, `no_report` otherwise).",18860 "x-codeSamples": [18861 {18862 "lang": "Shell",18863 "label": "curl",18864 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/start\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"mode\":\"paper\"}'"18865 },18866 {18867 "lang": "TypeScript",18868 "label": "TypeScript",18869 "source": "await client.startStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { mode: 'paper' });"18870 },18871 {18872 "lang": "Python",18873 "label": "Python",18874 "source": "client.start_strategy(\"450bc266-e1a9-4807-9113-7da6773ddb4e\", mode=\"paper\")"18875 }18876 ],18877 "parameters": [18878 {18879 "name": "id",18880 "in": "path",18881 "required": true,18882 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",18883 "schema": {18884 "type": "string",18885 "minLength": 1,18886 "maxLength": 20018887 },18888 "example": "450bc266-e1a9-4807-9113-7da6773ddb4e"18889 },18890 {18891 "name": "Idempotency-Key",18892 "in": "header",18893 "required": true,18894 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",18895 "schema": {18896 "type": "string",18897 "pattern": "^[A-Za-z0-9._:-]{8,100}$"18898 }18899 },18900 {18901 "name": "X-SPW-Timestamp",18902 "in": "header",18903 "required": false,18904 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",18905 "schema": {18906 "type": "string",18907 "pattern": "^\\d{9,11}$"18908 }18909 }18910 ],18911 "requestBody": {18912 "required": true,18913 "content": {18914 "application/json": {18915 "schema": {18916 "type": "object",18917 "properties": {18918 "mode": {18919 "type": "string",18920 "enum": [18921 "research",18922 "paper",18923 "live"18924 ],18925 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."18926 },18927 "agentId": {18928 "description": "strategy operations only: the agent, when the version id alone does not name it",18929 "type": "string",18930 "format": "uuid",18931 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"18932 }18933 },18934 "required": [18935 "mode"18936 ],18937 "additionalProperties": false18938 },18939 "example": {18940 "mode": "paper"18941 }18942 }18943 }18944 },18945 "responses": {18946 "200": {18947 "description": "OK (the example is a recorded answer)",18948 "content": {18949 "application/json": {18950 "schema": {18951 "type": "object",18952 "properties": {18953 "agent": {18954 "type": "object",18955 "properties": {18956 "id": {18957 "type": "string"18958 },18959 "state": {18960 "type": "string",18961 "enum": [18962 "active",18963 "paused",18964 "stopped"18965 ]18966 },18967 "mode": {18968 "type": "string",18969 "enum": [18970 "research",18971 "paper",18972 "live"18973 ],18974 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."18975 }18976 },18977 "required": [18978 "id",18979 "state",18980 "mode"18981 ],18982 "additionalProperties": {}18983 }18984 },18985 "required": [18986 "agent"18987 ],18988 "additionalProperties": {}18989 },18990 "example": {18991 "agent": {18992 "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",18993 "name": "Docs momentum",18994 "mission": "",18995 "kind": "perp",18996 "family": "momentum",18997 "template": "momentum",18998 "engine": "bar",18999 "state": "active",19000 "phase": "PAPER_TRADING",19001 "mode": "paper",19002 "venue": "hyperliquid",19003 "network": "hyperliquid",19004 "universe": [19005 "BTC",19006 "ETH"19007 ],19008 "interval": "1h",19009 "capitalUsd": "1000",19010 "riskLimits": {19011 "maxLeverage": 2,19012 "minTradePct": 2,19013 "slippageBps": 30,19014 "maxPositionX": 1,19015 "maxDailyLossPct": 3,19016 "maxTotalLossPct": 10,19017 "maxGrossExposureX": 1.519018 },19019 "configVersion": 3,19020 "strategy": {19021 "name": "momentum_xs_perp",19022 "version": "2",19023 "sha256": "75cd4dfae65f6d55667bfaf3fe2eee2b5c98c18edbe8b43dcd8480d88262e272",19024 "path": "strategies/momentum_xs_perp/2",19025 "status": "approved",19026 "kind": "python"19027 },19028 "mandate": null,19029 "pausedFrom": null,19030 "live": {19031 "capable": true,19032 "code": null,19033 "reason": null19034 },19035 "stopReason": null,19036 "lastBar": null,19037 "createdAt": 1794953786472,19038 "updatedAt": 179495504318019039 },19040 "strategyVersionId": "450bc266-e1a9-4807-9113-7da6773ddb4e"19041 }19042 }19043 }19044 },19045 "400": {19046 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",19047 "content": {19048 "application/json": {19049 "schema": {19050 "$ref": "#/components/schemas/Error"19051 }19052 }19053 }19054 },19055 "401": {19056 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",19057 "content": {19058 "application/json": {19059 "schema": {19060 "$ref": "#/components/schemas/Error"19061 }19062 }19063 }19064 },19065 "403": {19066 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required`, `restricted`",19067 "content": {19068 "application/json": {19069 "schema": {19070 "$ref": "#/components/schemas/Error"19071 }19072 }19073 }19074 },19075 "404": {19076 "description": "The object named by the request does not exist: `not_found`",19077 "content": {19078 "application/json": {19079 "schema": {19080 "$ref": "#/components/schemas/Error"19081 }19082 }19083 }19084 },19085 "409": {19086 "description": "The request conflicts with the state of the object, or needs a choice: `bad_report`, `bad_request`, `bad_state`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy`, `other_version`",19087 "content": {19088 "application/json": {19089 "schema": {19090 "$ref": "#/components/schemas/Error"19091 }19092 }19093 }19094 },19095 "429": {19096 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",19097 "content": {19098 "application/json": {19099 "schema": {19100 "$ref": "#/components/schemas/Error"19101 }19102 }19103 }19104 },19105 "500": {19106 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",19107 "content": {19108 "application/json": {19109 "schema": {19110 "$ref": "#/components/schemas/Error"19111 }19112 }19113 }19114 }19115 }19116 }19117 },19118 "/api/v1/trading/strategies/{id}/stop": {19119 "post": {19120 "operationId": "stopStrategy",19121 "tags": [19122 "Strategies"19123 ],19124 "summary": "Stop the agent a strategy version is pinned to",19125 "description": "Always allowed. The safe wind-down: a live perp agent's mandate is revoked and its positions are closed with reduce-only orders; a live spot agent's mandate is revoked at the signer; simulated quotes are withdrawn.",19126 "security": [19127 {19128 "bearerKey": [19129 "strategies:manage"19130 ]19131 }19132 ],19133 "x-spw-scope": "strategies:manage",19134 "x-spw-implemented": true,19135 "x-spw-idempotent": true,19136 "x-spw-errors": [19137 {19138 "status": 400,19139 "code": "bad_request"19140 },19141 {19142 "status": 400,19143 "code": "idempotency"19144 },19145 {19146 "status": 400,19147 "code": "stale_request"19148 },19149 {19150 "status": 401,19151 "code": "unauthenticated"19152 },19153 {19154 "status": 403,19155 "code": "insufficient_scope"19156 },19157 {19158 "status": 403,19159 "code": "ip_not_allowed"19160 },19161 {19162 "status": 403,19163 "code": "mixed_credentials"19164 },19165 {19166 "status": 403,19167 "code": "restricted"19168 },19169 {19170 "status": 404,19171 "code": "not_found"19172 },19173 {19174 "status": 409,19175 "code": "bad_state"19176 },19177 {19178 "status": 409,19179 "code": "idempotency_conflict"19180 },19181 {19182 "status": 409,19183 "code": "idempotency_in_progress"19184 },19185 {19186 "status": 429,19187 "code": "auth_throttled"19188 },19189 {19190 "status": 429,19191 "code": "rate_limited"19192 },19193 {19194 "status": 500,19195 "code": "internal"19196 }19197 ],19198 "x-spw-example-recorded": true,19199 "x-codeSamples": [19200 {19201 "lang": "Shell",19202 "label": "curl",19203 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/strategies/450bc266-e1a9-4807-9113-7da6773ddb4e/stop\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"documentation example\"}'"19204 },19205 {19206 "lang": "TypeScript",19207 "label": "TypeScript",19208 "source": "await client.stopStrategy('450bc266-e1a9-4807-9113-7da6773ddb4e', { reason: 'documentation example' });"19209 },19210 {19211 "lang": "Python",19212 "label": "Python",19213 "source": "client.stop_strategy(\"450bc266-e1a9-4807-9113-7da6773ddb4e\", reason=\"documentation example\")"19214 }19215 ],19216 "parameters": [19217 {19218 "name": "id",19219 "in": "path",19220 "required": true,19221 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",19222 "schema": {19223 "type": "string",19224 "minLength": 1,19225 "maxLength": 20019226 },19227 "example": "450bc266-e1a9-4807-9113-7da6773ddb4e"19228 },19229 {19230 "name": "Idempotency-Key",19231 "in": "header",19232 "required": true,19233 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",19234 "schema": {19235 "type": "string",19236 "pattern": "^[A-Za-z0-9._:-]{8,100}$"19237 }19238 },19239 {19240 "name": "X-SPW-Timestamp",19241 "in": "header",19242 "required": false,19243 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",19244 "schema": {19245 "type": "string",19246 "pattern": "^\\d{9,11}$"19247 }19248 }19249 ],19250 "requestBody": {19251 "required": true,19252 "content": {19253 "application/json": {19254 "schema": {19255 "type": "object",19256 "properties": {19257 "reason": {19258 "default": "",19259 "description": "why, for the agent's journal",19260 "type": "string",19261 "maxLength": 20019262 }19263 },19264 "additionalProperties": false19265 },19266 "example": {19267 "reason": "documentation example"19268 }19269 }19270 }19271 },19272 "responses": {19273 "200": {19274 "description": "OK (the example is a recorded answer)",19275 "content": {19276 "application/json": {19277 "schema": {19278 "type": "object",19279 "properties": {19280 "agent": {19281 "type": "object",19282 "properties": {19283 "id": {19284 "type": "string"19285 },19286 "state": {19287 "type": "string",19288 "enum": [19289 "active",19290 "paused",19291 "stopped"19292 ]19293 },19294 "mode": {19295 "type": "string",19296 "enum": [19297 "research",19298 "paper",19299 "live"19300 ],19301 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."19302 }19303 },19304 "required": [19305 "id",19306 "state",19307 "mode"19308 ],19309 "additionalProperties": {}19310 }19311 },19312 "required": [19313 "agent"19314 ],19315 "additionalProperties": {}19316 },19317 "example": {19318 "agent": {19319 "id": "fa9c1fd9-a005-4825-bd67-ea180a2eb83d",19320 "name": "Docs momentum",19321 "mission": "",19322 "kind": "perp",19323 "family": "momentum",19324 "template": "momentum",19325 "engine": "bar",19326 "state": "stopped",19327 "phase": "STOPPED",19328 "mode": "paper",19329 "venue": "hyperliquid",19330 "network": "hyperliquid",19331 "universe": [19332 "BTC",19333 "ETH"19334 ],19335 "interval": "1h",19336 "capitalUsd": "1000",19337 "riskLimits": {19338 "maxLeverage": 2,19339 "minTradePct": 2,19340 "slippageBps": 30,19341 "maxPositionX": 1,19342 "maxDailyLossPct": 3,19343 "maxTotalLossPct": 10,19344 "maxGrossExposureX": 1.519345 },19346 "configVersion": 2,19347 "strategy": null,19348 "mandate": null,19349 "pausedFrom": null,19350 "live": {19351 "capable": true,19352 "code": null,19353 "reason": null19354 },19355 "stopReason": "stopped by the key:spk_0123456789ab",19356 "lastBar": null,19357 "createdAt": 1794953786472,19358 "updatedAt": 179495378689419359 },19360 "windDown": null19361 }19362 }19363 }19364 },19365 "400": {19366 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",19367 "content": {19368 "application/json": {19369 "schema": {19370 "$ref": "#/components/schemas/Error"19371 }19372 }19373 }19374 },19375 "401": {19376 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",19377 "content": {19378 "application/json": {19379 "schema": {19380 "$ref": "#/components/schemas/Error"19381 }19382 }19383 }19384 },19385 "403": {19386 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",19387 "content": {19388 "application/json": {19389 "schema": {19390 "$ref": "#/components/schemas/Error"19391 }19392 }19393 }19394 },19395 "404": {19396 "description": "The object named by the request does not exist: `not_found`",19397 "content": {19398 "application/json": {19399 "schema": {19400 "$ref": "#/components/schemas/Error"19401 }19402 }19403 }19404 },19405 "409": {19406 "description": "The request conflicts with the state of the object, or needs a choice: `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",19407 "content": {19408 "application/json": {19409 "schema": {19410 "$ref": "#/components/schemas/Error"19411 }19412 }19413 }19414 },19415 "429": {19416 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",19417 "content": {19418 "application/json": {19419 "schema": {19420 "$ref": "#/components/schemas/Error"19421 }19422 }19423 }19424 },19425 "500": {19426 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",19427 "content": {19428 "application/json": {19429 "schema": {19430 "$ref": "#/components/schemas/Error"19431 }19432 }19433 }19434 }19435 }19436 }19437 },19438 "/api/v1/trading/agents/templates": {19439 "get": {19440 "operationId": "listAgentTemplates",19441 "tags": [19442 "Agents"19443 ],19444 "summary": "The seven built-in agents: family, engine, modes, installed strategies",19445 "description": "A bar template is bound BY NAME to laboratory strategies; `strategyInstalled: false` means none of them is installed (no placeholder is ever substituted). `liveReason` says why a family cannot go live.",19446 "security": [19447 {19448 "bearerKey": [19449 "agents:read"19450 ]19451 }19452 ],19453 "x-spw-scope": "agents:read",19454 "x-spw-implemented": true,19455 "x-spw-errors": [19456 {19457 "status": 401,19458 "code": "unauthenticated"19459 },19460 {19461 "status": 403,19462 "code": "insufficient_scope"19463 },19464 {19465 "status": 403,19466 "code": "ip_not_allowed"19467 },19468 {19469 "status": 403,19470 "code": "mixed_credentials"19471 },19472 {19473 "status": 429,19474 "code": "auth_throttled"19475 },19476 {19477 "status": 429,19478 "code": "rate_limited"19479 },19480 {19481 "status": 500,19482 "code": "internal"19483 }19484 ],19485 "x-spw-example-recorded": true,19486 "x-spw-example-note": "Cut to one of the seven templates.",19487 "x-codeSamples": [19488 {19489 "lang": "Shell",19490 "label": "curl",19491 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/templates\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""19492 },19493 {19494 "lang": "TypeScript",19495 "label": "TypeScript",19496 "source": "const { templates } = await client.listAgentTemplates();"19497 },19498 {19499 "lang": "Python",19500 "label": "Python",19501 "source": "templates = client.list_agent_templates().templates"19502 }19503 ],19504 "parameters": [],19505 "responses": {19506 "200": {19507 "description": "OK (the example is a recorded answer)",19508 "content": {19509 "application/json": {19510 "schema": {19511 "type": "object",19512 "properties": {19513 "templates": {19514 "type": "array",19515 "items": {19516 "type": "object",19517 "properties": {19518 "id": {19519 "type": "string"19520 },19521 "family": {19522 "type": "string"19523 },19524 "engine": {19525 "type": "string"19526 },19527 "modes": {19528 "type": "array",19529 "items": {19530 "type": "string",19531 "enum": [19532 "research",19533 "paper",19534 "live"19535 ],19536 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."19537 }19538 },19539 "liveReason": {19540 "type": [19541 "string",19542 "null"19543 ]19544 },19545 "strategyInstalled": {19546 "type": "boolean"19547 }19548 },19549 "required": [19550 "id",19551 "family",19552 "engine",19553 "modes",19554 "liveReason",19555 "strategyInstalled"19556 ],19557 "additionalProperties": {}19558 }19559 }19560 },19561 "required": [19562 "templates"19563 ],19564 "additionalProperties": false19565 },19566 "example": {19567 "templates": [19568 {19569 "id": "stat-arb",19570 "family": "stat_arb",19571 "engine": "bar",19572 "kind": "perp",19573 "name": {19574 "fr": "Arbitrage statistique",19575 "en": "Statistical Arbitrage"19576 },19577 "summary": {19578 "fr": "Paire ou panier co-intégré de contrats perpétuels Hyperliquid : achète l'écart quand il s'éloigne de sa moyenne, le revend quand il y revient.",19579 "en": "A co-integrated pair or basket of Hyperliquid perpetuals: buys the spread when it is far from its mean, sells it back when it returns."19580 },19581 "modes": [19582 "research"19583 ],19584 "liveReason": null,19585 "strategyNames": [19586 "statarb_basket_perp"19587 ],19588 "installed": [19589 {19590 "path": "statarb_basket_perp/1",19591 "name": "statarb_basket_perp",19592 "version": "1",19593 "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",19594 "universe": [19595 "BTC"19596 ],19597 "interval": "1h",19598 "spotLegs": false,19599 "generic": false,19600 "minSymbols": 6,19601 "maxSymbols": 6,19602 "defaultUniverse": null,19603 "liveCapable": false,19604 "liveReason": "its universe includes LINK, AAVE, HYPE, outside the signer's pinned instruments (BTC, ETH, SOL); an agent runs a fixed-universe strategy only on its exact universe, so it stays on paper",19605 "liveCondition": null19606 }19607 ],19608 "strategyInstalled": true,19609 "rule": null,19610 "labBacktest": {19611 "wanted": [],19612 "installed": [],19613 "agentRunnable": false19614 },19615 "labStudies": [],19616 "labVerdicts": [19617 {19618 "available": true,19619 "kind": "strategy",19620 "backtest": true,19621 "name": "statarb_basket_perp",19622 "version": "1",19623 "strategy": "statarb_basket_perp/1",19624 "sha256": "2cca1c2fac270ccb078f39699637ce600292459b29fe591427ef4d33aa7438e1",19625 "symbols": [19626 "BTC"19627 ],19628 "where": "strategies",19629 "installedHashMatches": true,19630 "scope": "agent",19631 "liveCapable": false,19632 "deflatedSharpe": 0.000002855202061682034,19633 "deflatedSharpeThreshold": 0.95,19634 "significant": false,19635 "trialsTested": 31,19636 "ownTrials": 5,19637 "testSharpeCi": [19638 -18.47677072575993819639 ],19640 "splits": {19641 "train": {19642 "netReturn": -0.10170708254821714,19643 "netSharpe": -7.182497476407538,19644 "grossSharpe": -2.942848775728168,19645 "maxDrawdown": 0.10170708254821714,19646 "trades": 384,19647 "stop": {19648 "code": "total_loss",19649 "reason": "total loss limit reached (10 % of the capital)",19650 "ts": "2026-06-29T18:00:00+00:00"19651 },19652 "grossToNet": {19653 "pricePnl": -42.47637,19654 "funding": 0.286722681079791,19655 "fees": 17.985133225783834,19656 "liquidationPenalties": 0,19657 "slippage": 4.3453824145459,19658 "latency": 37.186919588967264,19659 "netPnl": -101.7070825482171619660 }19661 },19662 "validation": {19663 "netReturn": -0.10328278271158842,19664 "netSharpe": -10.506726964730408,19665 "grossSharpe": 0.2656999138474378,19666 "maxDrawdown": 0.10328278271158842,19667 "trades": 870,19668 "stop": {19669 "code": "total_loss",19670 "reason": "total loss limit reached (10 % of the capital)",19671 "ts": "2026-09-25T08:00:00+00:00"19672 },19673 "grossToNet": {19674 "pricePnl": 2.05459,19675 "funding": 0.294203640074876,19676 "fees": 34.364870451549976,19677 "liquidationPenalties": 0,19678 "slippage": 8.0428194421408,19679 "latency": 63.22388645797256,19680 "netPnl": -103.2827827115884219681 }19682 },19683 "test": {19684 "netReturn": -0.10165090743737748,19685 "netSharpe": -11.067904972523419,19686 "grossSharpe": 0.7338473369539557,19687 "maxDrawdown": 0.1024842740501597,19688 "trades": 851,19689 "stop": {19690 "code": "total_loss",19691 "reason": "total loss limit reached (10 % of the capital)",19692 "ts": "2026-11-04T16:00:00+00:00"19693 },19694 "grossToNet": {19695 "pricePnl": 6.1472,19696 "funding": -0.381330817681965,19697 "fees": 37.63228249889594,19698 "liquidationPenalties": 0,19699 "slippage": 8.9354844276773,19700 "latency": 60.84900969312219,19701 "netPnl": -101.6509074373774419702 }19703 }19704 },19705 "stoppedSplits": [19706 "train"19707 ],19708 "checks": {19709 "lookahead": "pass",19710 "data_quality": "pass",19711 "ledger": "pass",19712 "funding_alignment": "pass"19713 },19714 "window": {19715 "start": "2026-05-19T00:00:00+00:00",19716 "end": "2026-11-14T23:00:00+00:00",19717 "interval": "1h",19718 "bars": 432019719 },19720 "splitDates": {19721 "train": [19722 "2026-05-19T00:00:00+00:00"19723 ],19724 "validation": [19725 "2026-09-04T00:00:00+00:00"19726 ],19727 "test": [19728 "2026-10-10T00:00:00+00:00"19729 ]19730 },19731 "dataSha256": "060687f0fc9f948d28ce5c5fd39c32798b3c924c35e0a5bb879dceec408c00f5",19732 "codeSha256": "6ea1cf4df5ceb8b33c0a763ca1c8724c76de60b861714597b73295ec89507356",19733 "engineParityApplied": true,19734 "results": {19735 "dir": "research/results/2026-11-15-v11",19736 "file": "statarb_basket_perp-1.json",19737 "fileSha256": "745a629f00d35b8b76d0e0ea681a7dbe22501b74b86351e80fd23ab3ebe71f14",19738 "matchesManifest": true19739 }19740 }19741 ],19742 "defaults": {19743 "universe": [19744 "BTC"19745 ],19746 "venues": [19747 "hyperliquid"19748 ],19749 "interval": "1h",19750 "capitalUsdc": "1000",19751 "config": {},19752 "risk": {19753 "maxLeverage": 2,19754 "maxGrossExposureX": 1.5,19755 "maxPositionX": 1,19756 "maxDailyLossPct": 3,19757 "maxTotalLossPct": 10,19758 "slippageBps": 30,19759 "minTradePct": 219760 }19761 }19762 }19763 ]19764 }19765 }19766 }19767 },19768 "401": {19769 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",19770 "content": {19771 "application/json": {19772 "schema": {19773 "$ref": "#/components/schemas/Error"19774 }19775 }19776 }19777 },19778 "403": {19779 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`",19780 "content": {19781 "application/json": {19782 "schema": {19783 "$ref": "#/components/schemas/Error"19784 }19785 }19786 }19787 },19788 "429": {19789 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",19790 "content": {19791 "application/json": {19792 "schema": {19793 "$ref": "#/components/schemas/Error"19794 }19795 }19796 }19797 },19798 "500": {19799 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",19800 "content": {19801 "application/json": {19802 "schema": {19803 "$ref": "#/components/schemas/Error"19804 }19805 }19806 }19807 }19808 }19809 }19810 },19811 "/api/v1/trading/agents/{id}": {19812 "get": {19813 "operationId": "getAgent",19814 "tags": [19815 "Agents"19816 ],19817 "summary": "One agent: model, strategy, limits, mandate reference, backtest reports (labelled), worker state",19818 "description": "`agent.state` is active, paused or stopped and `agent.mode` research, paper or live. `mandateDraft` is the mandate the owner would have to approve for this agent to go live (null when none can be drafted). An unknown id, or an agent a restricted key may not see, answers 404 `not_found`.",19819 "security": [19820 {19821 "bearerKey": [19822 "agents:read"19823 ]19824 }19825 ],19826 "x-spw-scope": "agents:read",19827 "x-spw-implemented": true,19828 "x-spw-errors": [19829 {19830 "status": 400,19831 "code": "bad_request"19832 },19833 {19834 "status": 401,19835 "code": "unauthenticated"19836 },19837 {19838 "status": 403,19839 "code": "insufficient_scope"19840 },19841 {19842 "status": 403,19843 "code": "ip_not_allowed"19844 },19845 {19846 "status": 403,19847 "code": "mixed_credentials"19848 },19849 {19850 "status": 403,19851 "code": "restricted"19852 },19853 {19854 "status": 404,19855 "code": "not_found"19856 },19857 {19858 "status": 429,19859 "code": "auth_throttled"19860 },19861 {19862 "status": 429,19863 "code": "rate_limited"19864 },19865 {19866 "status": 500,19867 "code": "internal"19868 }19869 ],19870 "x-spw-example-recorded": true,19871 "x-codeSamples": [19872 {19873 "lang": "Shell",19874 "label": "curl",19875 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""19876 },19877 {19878 "lang": "TypeScript",19879 "label": "TypeScript",19880 "source": "const { agent } = await client.getAgent('b9180e9d-3977-403c-a072-9af105bfd59b');"19881 },19882 {19883 "lang": "Python",19884 "label": "Python",19885 "source": "agent = client.get_agent(\"b9180e9d-3977-403c-a072-9af105bfd59b\").agent"19886 }19887 ],19888 "parameters": [19889 {19890 "name": "id",19891 "in": "path",19892 "required": true,19893 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",19894 "schema": {19895 "type": "string",19896 "minLength": 1,19897 "maxLength": 20019898 },19899 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"19900 }19901 ],19902 "responses": {19903 "200": {19904 "description": "OK (the example is a recorded answer)",19905 "content": {19906 "application/json": {19907 "schema": {19908 "type": "object",19909 "properties": {19910 "agent": {19911 "type": "object",19912 "properties": {19913 "id": {19914 "type": "string"19915 },19916 "family": {19917 "type": "string"19918 },19919 "state": {19920 "type": "string",19921 "enum": [19922 "active",19923 "paused",19924 "stopped"19925 ]19926 },19927 "mode": {19928 "type": "string",19929 "enum": [19930 "research",19931 "paper",19932 "live"19933 ],19934 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."19935 }19936 },19937 "required": [19938 "id",19939 "family",19940 "state",19941 "mode"19942 ],19943 "additionalProperties": {}19944 },19945 "mandateDraft": {19946 "anyOf": [19947 {19948 "type": "object",19949 "properties": {},19950 "additionalProperties": {}19951 },19952 {19953 "type": "null"19954 }19955 ]19956 }19957 },19958 "required": [19959 "agent",19960 "mandateDraft"19961 ],19962 "additionalProperties": {}19963 },19964 "example": {19965 "agent": {19966 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",19967 "name": "Docs funding",19968 "mission": "",19969 "kind": "stream",19970 "family": "funding_arb",19971 "template": "funding-arb",19972 "engine": "stream",19973 "state": "stopped",19974 "phase": "CREATED",19975 "mode": "research",19976 "venue": "hyperliquid+dydx",19977 "network": "hyperliquid+dydx",19978 "universe": [19979 "BTC"19980 ],19981 "interval": "stream",19982 "capitalUsd": "1000",19983 "riskLimits": {19984 "maxGrossUsd": 1000,19985 "maxDataAgeMs": 5000,19986 "maxPositionUsd": 500,19987 "maxDailyLossPct": 2,19988 "maxTotalLossPct": 519989 },19990 "configVersion": 1,19991 "strategy": {19992 "name": "funding_differential",19993 "version": "1",19994 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",19995 "path": null,19996 "status": "built_in",19997 "kind": "rule"19998 },19999 "mandate": null,20000 "pausedFrom": null,20001 "live": {20002 "capable": false,20003 "code": "family_not_live",20004 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"20005 },20006 "stopReason": null,20007 "lastBar": null,20008 "createdAt": 1794953757211,20009 "updatedAt": 1794953757211,20010 "familyModes": {20011 "engine": "stream",20012 "modes": [20013 "research",20014 "paper"20015 ],20016 "liveReason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"20017 },20018 "backtests": {20019 "label": "backtest",20020 "note": "A backtest is a simulation on historical data under stated assumptions. It is not a track record and is never shown as performance.",20021 "versions": [],20022 "recorded": null20023 },20024 "runtime": {20025 "venues": [20026 "hyperliquid",20027 "dydx"20028 ],20029 "rule": "funding_differential",20030 "config": {20031 "notionalUsd": "250",20032 "horizonHours": "24",20033 "minNetCarryBps": "5",20034 "decisionEveryMs": 60000,20035 "exitNetCarryBps": "0"20036 },20037 "counters": null,20038 "hold": null,20039 "lastPass": null,20040 "book": null20041 },20042 "worker": {20043 "lease": null,20044 "tick": null20045 },20046 "jobs": [],20047 "killSwitch": {20048 "engaged": false,20049 "reason": null,20050 "at": null,20051 "by": null,20052 "readOnly": false,20053 "readOnlyReason": null,20054 "release": {20055 "route": "/risk",20056 "passkey": true20057 }20058 }20059 },20060 "mandateDraft": {20061 "draft": "agent:b9180e9d-3977-403c-a072-9af105bfd59b",20062 "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",20063 "family": "funding_arb",20064 "approval": {20065 "route": "/risk?mandate=agent:b9180e9d-3977-403c-a072-9af105bfd59b",20066 "note": "the mandate is approved by the owner with the passkey; the signer judges the approval and enforces the mandate on every order"20067 },20068 "available": false,20069 "code": "family_not_live",20070 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat",20071 "fields": null20072 }20073 }20074 }20075 }20076 },20077 "400": {20078 "description": "The request is not valid: `bad_request`",20079 "content": {20080 "application/json": {20081 "schema": {20082 "$ref": "#/components/schemas/Error"20083 }20084 }20085 }20086 },20087 "401": {20088 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",20089 "content": {20090 "application/json": {20091 "schema": {20092 "$ref": "#/components/schemas/Error"20093 }20094 }20095 }20096 },20097 "403": {20098 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",20099 "content": {20100 "application/json": {20101 "schema": {20102 "$ref": "#/components/schemas/Error"20103 }20104 }20105 }20106 },20107 "404": {20108 "description": "The object named by the request does not exist: `not_found`",20109 "content": {20110 "application/json": {20111 "schema": {20112 "$ref": "#/components/schemas/Error"20113 }20114 }20115 }20116 },20117 "429": {20118 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",20119 "content": {20120 "application/json": {20121 "schema": {20122 "$ref": "#/components/schemas/Error"20123 }20124 }20125 }20126 },20127 "500": {20128 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",20129 "content": {20130 "application/json": {20131 "schema": {20132 "$ref": "#/components/schemas/Error"20133 }20134 }20135 }20136 }20137 }20138 }20139 },20140 "/api/v1/trading/agents/{id}/signals": {20141 "get": {20142 "operationId": "listAgentSignals",20143 "tags": [20144 "Agents"20145 ],20146 "summary": "Signal history of one agent, ONE mode",20147 "description": "Each signal carries the mode, the configuration version, the strategy hash, a digest of its inputs, its output and the decision: `acted`, or `skipped` with a reason code.",20148 "security": [20149 {20150 "bearerKey": [20151 "agents:read"20152 ]20153 }20154 ],20155 "x-spw-scope": "agents:read",20156 "x-spw-implemented": true,20157 "x-spw-errors": [20158 {20159 "status": 400,20160 "code": "bad_request"20161 },20162 {20163 "status": 401,20164 "code": "unauthenticated"20165 },20166 {20167 "status": 403,20168 "code": "insufficient_scope"20169 },20170 {20171 "status": 403,20172 "code": "ip_not_allowed"20173 },20174 {20175 "status": 403,20176 "code": "mixed_credentials"20177 },20178 {20179 "status": 403,20180 "code": "restricted"20181 },20182 {20183 "status": 404,20184 "code": "not_found"20185 },20186 {20187 "status": 429,20188 "code": "auth_throttled"20189 },20190 {20191 "status": 429,20192 "code": "rate_limited"20193 },20194 {20195 "status": 500,20196 "code": "internal"20197 }20198 ],20199 "x-spw-example-recorded": true,20200 "x-codeSamples": [20201 {20202 "lang": "Shell",20203 "label": "curl",20204 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/signals?mode=paper&limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""20205 },20206 {20207 "lang": "TypeScript",20208 "label": "TypeScript",20209 "source": "const { signals } = await client.listAgentSignals('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });"20210 },20211 {20212 "lang": "Python",20213 "label": "Python",20214 "source": "signals = client.list_agent_signals(\"b9180e9d-3977-403c-a072-9af105bfd59b\", mode=\"paper\", limit=2).signals"20215 }20216 ],20217 "parameters": [20218 {20219 "name": "id",20220 "in": "path",20221 "required": true,20222 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",20223 "schema": {20224 "type": "string",20225 "minLength": 1,20226 "maxLength": 20020227 },20228 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"20229 },20230 {20231 "name": "mode",20232 "in": "query",20233 "required": false,20234 "description": "default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it.",20235 "schema": {20236 "type": "string",20237 "enum": [20238 "research",20239 "paper",20240 "live"20241 ]20242 },20243 "example": "paper"20244 },20245 {20246 "name": "limit",20247 "in": "query",20248 "required": false,20249 "description": "rows returned at most",20250 "schema": {20251 "default": 100,20252 "type": "integer",20253 "minimum": 1,20254 "maximum": 50020255 },20256 "example": 220257 },20258 {20259 "name": "before",20260 "in": "query",20261 "required": false,20262 "description": "unix ms: rows strictly before it",20263 "schema": {20264 "type": "integer",20265 "exclusiveMinimum": 0,20266 "maximum": 900719925474099120267 }20268 }20269 ],20270 "responses": {20271 "200": {20272 "description": "OK (the example is a recorded answer)",20273 "content": {20274 "application/json": {20275 "schema": {20276 "type": "object",20277 "properties": {20278 "mode": {20279 "type": "string",20280 "enum": [20281 "research",20282 "paper",20283 "live"20284 ],20285 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."20286 },20287 "signals": {20288 "type": "array",20289 "items": {20290 "type": "object",20291 "properties": {20292 "id": {20293 "type": "string"20294 },20295 "ts": {20296 "type": "integer",20297 "minimum": -9007199254740991,20298 "maximum": 9007199254740991,20299 "description": "milliseconds since the Unix epoch"20300 },20301 "mode": {20302 "type": "string",20303 "enum": [20304 "research",20305 "paper",20306 "live"20307 ],20308 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."20309 },20310 "configVersion": {20311 "type": "integer",20312 "minimum": -9007199254740991,20313 "maximum": 900719925474099120314 },20315 "strategySha256": {20316 "type": "string"20317 },20318 "decision": {20319 "type": "string",20320 "enum": [20321 "pending",20322 "acted",20323 "skipped"20324 ]20325 },20326 "reasonCode": {20327 "type": [20328 "string",20329 "null"20330 ]20331 }20332 },20333 "required": [20334 "id",20335 "ts",20336 "mode",20337 "configVersion",20338 "strategySha256",20339 "decision",20340 "reasonCode"20341 ],20342 "additionalProperties": {}20343 }20344 }20345 },20346 "required": [20347 "mode",20348 "signals"20349 ],20350 "additionalProperties": false20351 },20352 "example": {20353 "mode": "paper",20354 "signals": [20355 {20356 "id": "2",20357 "ts": 1794953758433,20358 "mode": "paper",20359 "kind": "stream",20360 "configVersion": 1,20361 "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",20362 "inputsDigest": "ce04a27eb7d4a2a54c55ea9a63340283bc5ffb6cc7ff9aba8f86947ac273a1a4",20363 "status": "done",20364 "decision": "skipped",20365 "reasonCode": "edge_below_threshold",20366 "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",20367 "output": {20368 "a": {20369 "id": "hyperliquid:BTC",20370 "rate": "0.0000088903",20371 "venue": "hyperliquid",20372 "hourlyBps": 0.088903,20373 "takerRate": 0.00045,20374 "intervalSec": 360020375 },20376 "b": {20377 "id": "dydx:BTC-USD",20378 "rate": "0.00000153333333333333",20379 "venue": "dydx",20380 "hourlyBps": 0.015333333333,20381 "takerRate": 0.0005,20382 "intervalSec": 360020383 },20384 "legs": [],20385 "action": "hold",20386 "reason": "net carry -17.23 bps over 24 h (gross 1.77, fees 19.00) is below 5 bps",20387 "feesBps": 19,20388 "longVenue": "dydx",20389 "reasonCode": "edge_below_threshold",20390 "shortVenue": "hyperliquid",20391 "netCarryBps": -17.234327999992,20392 "grossCarryBps": 1.7656720000079997,20393 "diffBpsPerHour": 0.0735696666669999920394 },20395 "scaled": null,20396 "scale": null,20397 "equity": "1000",20398 "targets": null,20399 "orders": null,20400 "createdAt": 1794953758435,20401 "updatedAt": 179495375843520402 },20403 {20404 "id": "1",20405 "ts": 1794953757448,20406 "mode": "paper",20407 "kind": "stream",20408 "configVersion": 1,20409 "strategySha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",20410 "inputsDigest": null,20411 "status": "hold",20412 "decision": "skipped",20413 "reasonCode": "data_gap",20414 "reason": "hyperliquid:BTC: the stream is reconnecting",20415 "output": null,20416 "scaled": null,20417 "scale": null,20418 "equity": null,20419 "targets": null,20420 "orders": null,20421 "createdAt": 1794953757449,20422 "updatedAt": 179495375744920423 }20424 ]20425 }20426 }20427 }20428 },20429 "400": {20430 "description": "The request is not valid: `bad_request`",20431 "content": {20432 "application/json": {20433 "schema": {20434 "$ref": "#/components/schemas/Error"20435 }20436 }20437 }20438 },20439 "401": {20440 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",20441 "content": {20442 "application/json": {20443 "schema": {20444 "$ref": "#/components/schemas/Error"20445 }20446 }20447 }20448 },20449 "403": {20450 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",20451 "content": {20452 "application/json": {20453 "schema": {20454 "$ref": "#/components/schemas/Error"20455 }20456 }20457 }20458 },20459 "404": {20460 "description": "The object named by the request does not exist: `not_found`",20461 "content": {20462 "application/json": {20463 "schema": {20464 "$ref": "#/components/schemas/Error"20465 }20466 }20467 }20468 },20469 "429": {20470 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",20471 "content": {20472 "application/json": {20473 "schema": {20474 "$ref": "#/components/schemas/Error"20475 }20476 }20477 }20478 },20479 "500": {20480 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",20481 "content": {20482 "application/json": {20483 "schema": {20484 "$ref": "#/components/schemas/Error"20485 }20486 }20487 }20488 }20489 }20490 }20491 },20492 "/api/v1/trading/agents/{id}/journal": {20493 "get": {20494 "operationId": "listAgentJournal",20495 "tags": [20496 "Agents"20497 ],20498 "summary": "Activity journal of one agent, ONE mode",20499 "description": "Decisions, orders, fills, errors, risk denials, mandate events and state changes, newest first.",20500 "security": [20501 {20502 "bearerKey": [20503 "agents:read"20504 ]20505 }20506 ],20507 "x-spw-scope": "agents:read",20508 "x-spw-implemented": true,20509 "x-spw-errors": [20510 {20511 "status": 400,20512 "code": "bad_request"20513 },20514 {20515 "status": 401,20516 "code": "unauthenticated"20517 },20518 {20519 "status": 403,20520 "code": "insufficient_scope"20521 },20522 {20523 "status": 403,20524 "code": "ip_not_allowed"20525 },20526 {20527 "status": 403,20528 "code": "mixed_credentials"20529 },20530 {20531 "status": 403,20532 "code": "restricted"20533 },20534 {20535 "status": 404,20536 "code": "not_found"20537 },20538 {20539 "status": 429,20540 "code": "auth_throttled"20541 },20542 {20543 "status": 429,20544 "code": "rate_limited"20545 },20546 {20547 "status": 500,20548 "code": "internal"20549 }20550 ],20551 "x-spw-example-recorded": true,20552 "x-codeSamples": [20553 {20554 "lang": "Shell",20555 "label": "curl",20556 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/journal?mode=paper&limit=3\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""20557 },20558 {20559 "lang": "TypeScript",20560 "label": "TypeScript",20561 "source": "const { entries } = await client.listAgentJournal('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 3 });"20562 },20563 {20564 "lang": "Python",20565 "label": "Python",20566 "source": "entries = client.list_agent_journal(\"b9180e9d-3977-403c-a072-9af105bfd59b\", mode=\"paper\", limit=3).entries"20567 }20568 ],20569 "parameters": [20570 {20571 "name": "id",20572 "in": "path",20573 "required": true,20574 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",20575 "schema": {20576 "type": "string",20577 "minLength": 1,20578 "maxLength": 20020579 },20580 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"20581 },20582 {20583 "name": "mode",20584 "in": "query",20585 "required": false,20586 "description": "default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it.",20587 "schema": {20588 "type": "string",20589 "enum": [20590 "research",20591 "paper",20592 "live"20593 ]20594 },20595 "example": "paper"20596 },20597 {20598 "name": "limit",20599 "in": "query",20600 "required": false,20601 "description": "rows returned at most",20602 "schema": {20603 "default": 100,20604 "type": "integer",20605 "minimum": 1,20606 "maximum": 50020607 },20608 "example": 320609 },20610 {20611 "name": "before",20612 "in": "query",20613 "required": false,20614 "description": "unix ms: rows strictly before it",20615 "schema": {20616 "type": "integer",20617 "exclusiveMinimum": 0,20618 "maximum": 900719925474099120619 }20620 }20621 ],20622 "responses": {20623 "200": {20624 "description": "OK (the example is a recorded answer)",20625 "content": {20626 "application/json": {20627 "schema": {20628 "type": "object",20629 "properties": {20630 "mode": {20631 "type": "string",20632 "enum": [20633 "research",20634 "paper",20635 "live"20636 ],20637 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."20638 },20639 "entries": {20640 "type": "array",20641 "items": {20642 "type": "object",20643 "properties": {20644 "id": {20645 "type": "string"20646 },20647 "ts": {20648 "type": "integer",20649 "minimum": -9007199254740991,20650 "maximum": 9007199254740991,20651 "description": "milliseconds since the Unix epoch"20652 },20653 "mode": {20654 "type": "string",20655 "enum": [20656 "research",20657 "paper",20658 "live"20659 ],20660 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."20661 },20662 "kind": {20663 "type": "string"20664 },20665 "severity": {20666 "type": "string"20667 },20668 "title": {20669 "type": "string"20670 }20671 },20672 "required": [20673 "id",20674 "ts",20675 "mode",20676 "kind",20677 "severity",20678 "title"20679 ],20680 "additionalProperties": {}20681 }20682 }20683 },20684 "required": [20685 "mode",20686 "entries"20687 ],20688 "additionalProperties": false20689 },20690 "example": {20691 "mode": "paper",20692 "entries": [20693 {20694 "id": "3",20695 "ts": 1794953758433,20696 "mode": "paper",20697 "kind": "state",20698 "severity": "info",20699 "code": "data_ok",20700 "title": "Data is fresh again: decisions resume",20701 "body": "after 1 s (data_gap)",20702 "data": null,20703 "ref": null,20704 "configVersion": 120705 },20706 {20707 "id": "2",20708 "ts": 1794953757448,20709 "mode": "paper",20710 "kind": "hold",20711 "severity": "warning",20712 "code": "data_gap",20713 "title": "Data gap: quoting and decisions paused",20714 "body": "hyperliquid:BTC: the stream is reconnecting",20715 "data": null,20716 "ref": null,20717 "configVersion": 120718 }20719 ]20720 }20721 }20722 }20723 },20724 "400": {20725 "description": "The request is not valid: `bad_request`",20726 "content": {20727 "application/json": {20728 "schema": {20729 "$ref": "#/components/schemas/Error"20730 }20731 }20732 }20733 },20734 "401": {20735 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",20736 "content": {20737 "application/json": {20738 "schema": {20739 "$ref": "#/components/schemas/Error"20740 }20741 }20742 }20743 },20744 "403": {20745 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",20746 "content": {20747 "application/json": {20748 "schema": {20749 "$ref": "#/components/schemas/Error"20750 }20751 }20752 }20753 },20754 "404": {20755 "description": "The object named by the request does not exist: `not_found`",20756 "content": {20757 "application/json": {20758 "schema": {20759 "$ref": "#/components/schemas/Error"20760 }20761 }20762 }20763 },20764 "429": {20765 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",20766 "content": {20767 "application/json": {20768 "schema": {20769 "$ref": "#/components/schemas/Error"20770 }20771 }20772 }20773 },20774 "500": {20775 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",20776 "content": {20777 "application/json": {20778 "schema": {20779 "$ref": "#/components/schemas/Error"20780 }20781 }20782 }20783 }20784 }20785 }20786 },20787 "/api/v1/trading/agents/{id}/orders": {20788 "get": {20789 "operationId": "listAgentOrders",20790 "tags": [20791 "Agents"20792 ],20793 "summary": "Order history of one agent, ONE mode, in the unified order states",20794 "description": "The agent's orders in one mode, newest first, with `state` in the twelve unified order states. Page with `before` (the `ts` of the last row) and `limit`. Research places no order: its list is empty.",20795 "security": [20796 {20797 "bearerKey": [20798 "agents:read"20799 ]20800 }20801 ],20802 "x-spw-scope": "agents:read",20803 "x-spw-implemented": true,20804 "x-spw-errors": [20805 {20806 "status": 400,20807 "code": "bad_request"20808 },20809 {20810 "status": 401,20811 "code": "unauthenticated"20812 },20813 {20814 "status": 403,20815 "code": "insufficient_scope"20816 },20817 {20818 "status": 403,20819 "code": "ip_not_allowed"20820 },20821 {20822 "status": 403,20823 "code": "mixed_credentials"20824 },20825 {20826 "status": 403,20827 "code": "restricted"20828 },20829 {20830 "status": 404,20831 "code": "not_found"20832 },20833 {20834 "status": 429,20835 "code": "auth_throttled"20836 },20837 {20838 "status": 429,20839 "code": "rate_limited"20840 },20841 {20842 "status": 500,20843 "code": "internal"20844 }20845 ],20846 "x-spw-example-recorded": true,20847 "x-spw-example-note": "The recorded agent had placed no order yet.",20848 "x-codeSamples": [20849 {20850 "lang": "Shell",20851 "label": "curl",20852 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/orders?mode=paper&limit=2\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""20853 },20854 {20855 "lang": "TypeScript",20856 "label": "TypeScript",20857 "source": "const { orders } = await client.listAgentOrders('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper', limit: 2 });"20858 },20859 {20860 "lang": "Python",20861 "label": "Python",20862 "source": "orders = client.list_agent_orders(\"b9180e9d-3977-403c-a072-9af105bfd59b\", mode=\"paper\", limit=2).orders"20863 }20864 ],20865 "parameters": [20866 {20867 "name": "id",20868 "in": "path",20869 "required": true,20870 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",20871 "schema": {20872 "type": "string",20873 "minLength": 1,20874 "maxLength": 20020875 },20876 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"20877 },20878 {20879 "name": "mode",20880 "in": "query",20881 "required": false,20882 "description": "default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it.",20883 "schema": {20884 "type": "string",20885 "enum": [20886 "research",20887 "paper",20888 "live"20889 ]20890 },20891 "example": "paper"20892 },20893 {20894 "name": "limit",20895 "in": "query",20896 "required": false,20897 "description": "rows returned at most",20898 "schema": {20899 "default": 100,20900 "type": "integer",20901 "minimum": 1,20902 "maximum": 50020903 },20904 "example": 220905 },20906 {20907 "name": "before",20908 "in": "query",20909 "required": false,20910 "description": "unix ms: rows strictly before it",20911 "schema": {20912 "type": "integer",20913 "exclusiveMinimum": 0,20914 "maximum": 900719925474099120915 }20916 },20917 {20918 "name": "open",20919 "in": "query",20920 "required": false,20921 "description": "true: only the orders that are not final",20922 "schema": {20923 "type": "string",20924 "enum": [20925 "true",20926 "false"20927 ]20928 }20929 }20930 ],20931 "responses": {20932 "200": {20933 "description": "OK (the example is a recorded answer)",20934 "content": {20935 "application/json": {20936 "schema": {20937 "type": "object",20938 "properties": {20939 "mode": {20940 "type": "string",20941 "enum": [20942 "research",20943 "paper",20944 "live"20945 ],20946 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."20947 },20948 "orders": {20949 "type": "array",20950 "items": {20951 "type": "object",20952 "properties": {20953 "id": {20954 "type": "string"20955 },20956 "mode": {20957 "type": "string",20958 "enum": [20959 "paper",20960 "live"20961 ]20962 },20963 "instrument": {20964 "type": "string"20965 },20966 "side": {20967 "type": "string"20968 },20969 "state": {20970 "type": "string",20971 "description": "unified order state (CREATED … FILLED, CANCELLED, REJECTED, FAILED, UNKNOWN)"20972 }20973 },20974 "required": [20975 "id",20976 "mode",20977 "instrument",20978 "side",20979 "state"20980 ],20981 "additionalProperties": {}20982 }20983 }20984 },20985 "required": [20986 "mode",20987 "orders"20988 ],20989 "additionalProperties": false20990 },20991 "example": {20992 "mode": "paper",20993 "orders": []20994 }20995 }20996 }20997 },20998 "400": {20999 "description": "The request is not valid: `bad_request`",21000 "content": {21001 "application/json": {21002 "schema": {21003 "$ref": "#/components/schemas/Error"21004 }21005 }21006 }21007 },21008 "401": {21009 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",21010 "content": {21011 "application/json": {21012 "schema": {21013 "$ref": "#/components/schemas/Error"21014 }21015 }21016 }21017 },21018 "403": {21019 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",21020 "content": {21021 "application/json": {21022 "schema": {21023 "$ref": "#/components/schemas/Error"21024 }21025 }21026 }21027 },21028 "404": {21029 "description": "The object named by the request does not exist: `not_found`",21030 "content": {21031 "application/json": {21032 "schema": {21033 "$ref": "#/components/schemas/Error"21034 }21035 }21036 }21037 },21038 "429": {21039 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",21040 "content": {21041 "application/json": {21042 "schema": {21043 "$ref": "#/components/schemas/Error"21044 }21045 }21046 }21047 },21048 "500": {21049 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",21050 "content": {21051 "application/json": {21052 "schema": {21053 "$ref": "#/components/schemas/Error"21054 }21055 }21056 }21057 }21058 }21059 }21060 },21061 "/api/v1/trading/agents/{id}/performance": {21062 "get": {21063 "operationId": "getAgentPerformance",21064 "tags": [21065 "Agents"21066 ],21067 "summary": "Computed performance of one agent, ONE mode",21068 "description": "Equity curve, returns, volatility, Sharpe, Sortino, max drawdown, win rate, profit factor, turnover, fees, funding, slippage, net PnL — computed from the records of that mode only, with small-sample warnings. Paper and live are never added. Backtests are not here.",21069 "security": [21070 {21071 "bearerKey": [21072 "agents:read"21073 ]21074 }21075 ],21076 "x-spw-scope": "agents:read",21077 "x-spw-implemented": true,21078 "x-spw-errors": [21079 {21080 "status": 400,21081 "code": "bad_request"21082 },21083 {21084 "status": 401,21085 "code": "unauthenticated"21086 },21087 {21088 "status": 403,21089 "code": "insufficient_scope"21090 },21091 {21092 "status": 403,21093 "code": "ip_not_allowed"21094 },21095 {21096 "status": 403,21097 "code": "mixed_credentials"21098 },21099 {21100 "status": 403,21101 "code": "restricted"21102 },21103 {21104 "status": 404,21105 "code": "not_found"21106 },21107 {21108 "status": 429,21109 "code": "auth_throttled"21110 },21111 {21112 "status": 429,21113 "code": "rate_limited"21114 },21115 {21116 "status": 500,21117 "code": "internal"21118 }21119 ],21120 "x-spw-example-recorded": true,21121 "x-spw-example-note": "A figure that cannot be computed is `{ value: null, reason }`, never zero.",21122 "x-codeSamples": [21123 {21124 "lang": "Shell",21125 "label": "curl",21126 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/performance?mode=paper\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""21127 },21128 {21129 "lang": "TypeScript",21130 "label": "TypeScript",21131 "source": "const perf = await client.getAgentPerformance('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });"21132 },21133 {21134 "lang": "Python",21135 "label": "Python",21136 "source": "perf = client.get_agent_performance(\"b9180e9d-3977-403c-a072-9af105bfd59b\", mode=\"paper\")"21137 }21138 ],21139 "parameters": [21140 {21141 "name": "id",21142 "in": "path",21143 "required": true,21144 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",21145 "schema": {21146 "type": "string",21147 "minLength": 1,21148 "maxLength": 20021149 },21150 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"21151 },21152 {21153 "name": "mode",21154 "in": "query",21155 "required": false,21156 "description": "default: the mode the agent is in NOW (for a stopped agent, the one it last ran in) — the answer always says which in `mode`. Name it to read one mode whatever the agent is doing; both SDKs require it.",21157 "schema": {21158 "type": "string",21159 "enum": [21160 "research",21161 "paper",21162 "live"21163 ]21164 },21165 "example": "paper"21166 }21167 ],21168 "responses": {21169 "200": {21170 "description": "OK (the example is a recorded answer)",21171 "content": {21172 "application/json": {21173 "schema": {21174 "type": "object",21175 "properties": {21176 "mode": {21177 "type": "string",21178 "enum": [21179 "research",21180 "paper",21181 "live"21182 ],21183 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."21184 },21185 "label": {21186 "type": "string",21187 "description": "says which mode the figures are for; a backtest is never in this answer"21188 },21189 "points": {21190 "type": "integer",21191 "minimum": -9007199254740991,21192 "maximum": 900719925474099121193 },21194 "warnings": {21195 "type": "array",21196 "items": {21197 "type": "object",21198 "properties": {21199 "code": {21200 "type": "string"21201 },21202 "message": {21203 "type": "string"21204 }21205 },21206 "required": [21207 "code",21208 "message"21209 ],21210 "additionalProperties": false21211 }21212 }21213 },21214 "required": [21215 "mode",21216 "label",21217 "points",21218 "warnings"21219 ],21220 "additionalProperties": {}21221 },21222 "example": {21223 "points": 1,21224 "from": 1794953700000,21225 "to": 1794953700000,21226 "periodsPerYear": null,21227 "totalReturn": {21228 "value": null,21229 "reason": "fewer than two equity points"21230 },21231 "volatility": {21232 "value": null,21233 "reason": "fewer than two returns"21234 },21235 "sharpe": {21236 "value": null,21237 "reason": "fewer than two returns"21238 },21239 "sortino": {21240 "value": null,21241 "reason": "fewer than two returns"21242 },21243 "maxDrawdown": {21244 "value": 0,21245 "reason": null21246 },21247 "winRate": {21248 "value": null,21249 "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"21250 },21251 "profitFactor": {21252 "value": null,21253 "reason": "the simulated book keeps positions at average cost: per-trade results are not kept (win rate and profit factor are not computed)"21254 },21255 "turnover": {21256 "value": 0,21257 "reason": null21258 },21259 "feesUsd": {21260 "value": 0,21261 "reason": null21262 },21263 "fundingUsd": {21264 "value": 0,21265 "reason": null21266 },21267 "slippageUsd": {21268 "value": null,21269 "reason": "simulated fills are at the quote or at the book price read by the decision"21270 },21271 "netPnlUsd": {21272 "value": null,21273 "reason": "fewer than two equity points"21274 },21275 "closedTrades": 0,21276 "orders": 0,21277 "warnings": [21278 {21279 "code": "small_sample",21280 "message": "1 equity point(s): volatility, Sharpe and Sortino on fewer than 30 points say almost nothing"21281 }21282 ],21283 "mode": "paper",21284 "label": "PAPER — simulated orders and fills; no money moved",21285 "equityCurve": [21286 {21287 "ts": 1794953700000,21288 "equity": 100021289 }21290 ]21291 }21292 }21293 }21294 },21295 "400": {21296 "description": "The request is not valid: `bad_request`",21297 "content": {21298 "application/json": {21299 "schema": {21300 "$ref": "#/components/schemas/Error"21301 }21302 }21303 }21304 },21305 "401": {21306 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",21307 "content": {21308 "application/json": {21309 "schema": {21310 "$ref": "#/components/schemas/Error"21311 }21312 }21313 }21314 },21315 "403": {21316 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",21317 "content": {21318 "application/json": {21319 "schema": {21320 "$ref": "#/components/schemas/Error"21321 }21322 }21323 }21324 },21325 "404": {21326 "description": "The object named by the request does not exist: `not_found`",21327 "content": {21328 "application/json": {21329 "schema": {21330 "$ref": "#/components/schemas/Error"21331 }21332 }21333 }21334 },21335 "429": {21336 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",21337 "content": {21338 "application/json": {21339 "schema": {21340 "$ref": "#/components/schemas/Error"21341 }21342 }21343 }21344 },21345 "500": {21346 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",21347 "content": {21348 "application/json": {21349 "schema": {21350 "$ref": "#/components/schemas/Error"21351 }21352 }21353 }21354 }21355 }21356 }21357 },21358 "/api/v1/trading/jobs/{id}": {21359 "get": {21360 "operationId": "getJob",21361 "tags": [21362 "Agents"21363 ],21364 "summary": "One agent job (backtest, wind-down): status and result",21365 "description": "Poll until `job.status` is `done`, `failed` or `cancelled` (both SDKs: `waitForJob` / `wait_for_job`). A backtest's `result` is labelled as a backtest and carries its own warnings (too few data points, missing snapshots).",21366 "security": [21367 {21368 "bearerKey": [21369 "agents:read"21370 ]21371 }21372 ],21373 "x-spw-scope": "agents:read",21374 "x-spw-implemented": true,21375 "x-spw-errors": [21376 {21377 "status": 400,21378 "code": "bad_request"21379 },21380 {21381 "status": 401,21382 "code": "unauthenticated"21383 },21384 {21385 "status": 403,21386 "code": "insufficient_scope"21387 },21388 {21389 "status": 403,21390 "code": "ip_not_allowed"21391 },21392 {21393 "status": 403,21394 "code": "mixed_credentials"21395 },21396 {21397 "status": 403,21398 "code": "restricted"21399 },21400 {21401 "status": 404,21402 "code": "not_found"21403 },21404 {21405 "status": 429,21406 "code": "auth_throttled"21407 },21408 {21409 "status": 429,21410 "code": "rate_limited"21411 },21412 {21413 "status": 500,21414 "code": "internal"21415 }21416 ],21417 "x-spw-example-recorded": true,21418 "x-codeSamples": [21419 {21420 "lang": "Shell",21421 "label": "curl",21422 "source": "curl -s \"$SP_WALLET_BASE_URL/api/v1/trading/jobs/72526d3e-9b2a-4f86-977b-07b6531868a8\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\""21423 },21424 {21425 "lang": "TypeScript",21426 "label": "TypeScript",21427 "source": "const { job } = await client.getJob('72526d3e-9b2a-4f86-977b-07b6531868a8');"21428 },21429 {21430 "lang": "Python",21431 "label": "Python",21432 "source": "job = client.get_job(\"72526d3e-9b2a-4f86-977b-07b6531868a8\").job"21433 }21434 ],21435 "parameters": [21436 {21437 "name": "id",21438 "in": "path",21439 "required": true,21440 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",21441 "schema": {21442 "type": "string",21443 "minLength": 1,21444 "maxLength": 20021445 },21446 "example": "72526d3e-9b2a-4f86-977b-07b6531868a8"21447 }21448 ],21449 "responses": {21450 "200": {21451 "description": "OK (the example is a recorded answer)",21452 "content": {21453 "application/json": {21454 "schema": {21455 "type": "object",21456 "properties": {21457 "job": {21458 "type": "object",21459 "properties": {21460 "id": {21461 "type": "string"21462 },21463 "kind": {21464 "type": "string"21465 },21466 "status": {21467 "type": "string",21468 "enum": [21469 "queued",21470 "running",21471 "done",21472 "failed",21473 "cancelled"21474 ]21475 },21476 "attempts": {21477 "type": "integer",21478 "minimum": -9007199254740991,21479 "maximum": 900719925474099121480 }21481 },21482 "required": [21483 "id",21484 "kind",21485 "status",21486 "attempts"21487 ],21488 "additionalProperties": {}21489 },21490 "label": {21491 "type": "string"21492 }21493 },21494 "required": [21495 "job"21496 ],21497 "additionalProperties": false21498 },21499 "example": {21500 "job": {21501 "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",21502 "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",21503 "kind": "backtest",21504 "status": "done",21505 "deadLettered": false,21506 "attempts": 1,21507 "maxAttempts": 2,21508 "runAt": 1794953761249,21509 "error": null,21510 "result": {21511 "kind": "recorded_replay",21512 "label": "backtest",21513 "missing": 360,21514 "warnings": [21515 "0 recorded instant(s): far too few to conclude anything",21516 "360 of 360 expected snapshots are missing in this window: the replay skipped them"21517 ],21518 "snapshots": 021519 },21520 "createdAt": 1794953761249,21521 "updatedAt": 1794953762380,21522 "finishedAt": 179495376238021523 }21524 }21525 }21526 }21527 },21528 "400": {21529 "description": "The request is not valid: `bad_request`",21530 "content": {21531 "application/json": {21532 "schema": {21533 "$ref": "#/components/schemas/Error"21534 }21535 }21536 }21537 },21538 "401": {21539 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",21540 "content": {21541 "application/json": {21542 "schema": {21543 "$ref": "#/components/schemas/Error"21544 }21545 }21546 }21547 },21548 "403": {21549 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",21550 "content": {21551 "application/json": {21552 "schema": {21553 "$ref": "#/components/schemas/Error"21554 }21555 }21556 }21557 },21558 "404": {21559 "description": "The object named by the request does not exist: `not_found`",21560 "content": {21561 "application/json": {21562 "schema": {21563 "$ref": "#/components/schemas/Error"21564 }21565 }21566 }21567 },21568 "429": {21569 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",21570 "content": {21571 "application/json": {21572 "schema": {21573 "$ref": "#/components/schemas/Error"21574 }21575 }21576 }21577 },21578 "500": {21579 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",21580 "content": {21581 "application/json": {21582 "schema": {21583 "$ref": "#/components/schemas/Error"21584 }21585 }21586 }21587 }21588 }21589 }21590 },21591 "/api/v1/trading/agents/{id}/start": {21592 "post": {21593 "operationId": "startAgent",21594 "tags": [21595 "Agents"21596 ],21597 "summary": "Start an agent in research, paper or live mode",21598 "description": "research and paper sign nothing. Starting a perp agent on `paper` creates its PAPER trading mandate (nothing is signed; its orders go through the unified order service, the risk engine and that mandate): the key needs `agents:manage` and may not be restricted away from the agent's venue or instruments (403 `insufficient_scope` / `restricted`), and a halted paper account answers 409 `halted`. `live` is accepted ONLY when a mandate approved by the owner with the passkey is in force for this agent — for a perp agent a TRADING mandate, which only the owner activates: a key answers 409 `mandate_required` (a key, an agent or this API can never approve a mandate). Families that cannot go live answer 409 `live_unavailable` with the reason.",21599 "security": [21600 {21601 "bearerKey": [21602 "agents:manage"21603 ]21604 }21605 ],21606 "x-spw-scope": "agents:manage",21607 "x-spw-implemented": true,21608 "x-spw-idempotent": true,21609 "x-spw-errors": [21610 {21611 "status": 400,21612 "code": "bad_request"21613 },21614 {21615 "status": 400,21616 "code": "idempotency"21617 },21618 {21619 "status": 400,21620 "code": "stale_request"21621 },21622 {21623 "status": 401,21624 "code": "unauthenticated"21625 },21626 {21627 "status": 403,21628 "code": "insufficient_scope"21629 },21630 {21631 "status": 403,21632 "code": "ip_not_allowed"21633 },21634 {21635 "status": 403,21636 "code": "mixed_credentials"21637 },21638 {21639 "status": 403,21640 "code": "owner_required"21641 },21642 {21643 "status": 403,21644 "code": "restricted"21645 },21646 {21647 "status": 404,21648 "code": "not_found"21649 },21650 {21651 "status": 409,21652 "code": "bad_report"21653 },21654 {21655 "status": 409,21656 "code": "bad_state"21657 },21658 {21659 "status": 409,21660 "code": "halted"21661 },21662 {21663 "status": 409,21664 "code": "idempotency_conflict"21665 },21666 {21667 "status": 409,21668 "code": "idempotency_in_progress"21669 },21670 {21671 "status": 409,21672 "code": "live_unavailable"21673 },21674 {21675 "status": 409,21676 "code": "mandate_required"21677 },21678 {21679 "status": 409,21680 "code": "no_report"21681 },21682 {21683 "status": 409,21684 "code": "no_strategy"21685 },21686 {21687 "status": 429,21688 "code": "auth_throttled"21689 },21690 {21691 "status": 429,21692 "code": "rate_limited"21693 },21694 {21695 "status": 500,21696 "code": "internal"21697 }21698 ],21699 "x-spw-example-recorded": true,21700 "x-codeSamples": [21701 {21702 "lang": "Shell",21703 "label": "curl",21704 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/start\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"mode\":\"paper\"}'"21705 },21706 {21707 "lang": "TypeScript",21708 "label": "TypeScript",21709 "source": "await client.startAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { mode: 'paper' });"21710 },21711 {21712 "lang": "Python",21713 "label": "Python",21714 "source": "client.start_agent(\"b9180e9d-3977-403c-a072-9af105bfd59b\", mode=\"paper\")"21715 }21716 ],21717 "parameters": [21718 {21719 "name": "id",21720 "in": "path",21721 "required": true,21722 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",21723 "schema": {21724 "type": "string",21725 "minLength": 1,21726 "maxLength": 20021727 },21728 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"21729 },21730 {21731 "name": "Idempotency-Key",21732 "in": "header",21733 "required": true,21734 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",21735 "schema": {21736 "type": "string",21737 "pattern": "^[A-Za-z0-9._:-]{8,100}$"21738 }21739 },21740 {21741 "name": "X-SPW-Timestamp",21742 "in": "header",21743 "required": false,21744 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",21745 "schema": {21746 "type": "string",21747 "pattern": "^\\d{9,11}$"21748 }21749 }21750 ],21751 "requestBody": {21752 "required": true,21753 "content": {21754 "application/json": {21755 "schema": {21756 "type": "object",21757 "properties": {21758 "mode": {21759 "type": "string",21760 "enum": [21761 "research",21762 "paper",21763 "live"21764 ],21765 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."21766 },21767 "agentId": {21768 "description": "strategy operations only: the agent, when the version id alone does not name it",21769 "type": "string",21770 "format": "uuid",21771 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"21772 }21773 },21774 "required": [21775 "mode"21776 ],21777 "additionalProperties": false21778 },21779 "example": {21780 "mode": "paper"21781 }21782 }21783 }21784 },21785 "responses": {21786 "200": {21787 "description": "OK (the example is a recorded answer)",21788 "content": {21789 "application/json": {21790 "schema": {21791 "type": "object",21792 "properties": {21793 "agent": {21794 "type": "object",21795 "properties": {21796 "id": {21797 "type": "string"21798 },21799 "state": {21800 "type": "string",21801 "enum": [21802 "active",21803 "paused",21804 "stopped"21805 ]21806 },21807 "mode": {21808 "type": "string",21809 "enum": [21810 "research",21811 "paper",21812 "live"21813 ],21814 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."21815 }21816 },21817 "required": [21818 "id",21819 "state",21820 "mode"21821 ],21822 "additionalProperties": {}21823 }21824 },21825 "required": [21826 "agent"21827 ],21828 "additionalProperties": {}21829 },21830 "example": {21831 "agent": {21832 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",21833 "name": "Docs funding",21834 "mission": "",21835 "kind": "stream",21836 "family": "funding_arb",21837 "template": "funding-arb",21838 "engine": "stream",21839 "state": "active",21840 "phase": "PAPER_TRADING",21841 "mode": "paper",21842 "venue": "hyperliquid+dydx",21843 "network": "hyperliquid+dydx",21844 "universe": [21845 "BTC"21846 ],21847 "interval": "stream",21848 "capitalUsd": "1000",21849 "riskLimits": {21850 "maxGrossUsd": 1000,21851 "maxDataAgeMs": 5000,21852 "maxPositionUsd": 500,21853 "maxDailyLossPct": 2,21854 "maxTotalLossPct": 521855 },21856 "configVersion": 1,21857 "strategy": {21858 "name": "funding_differential",21859 "version": "1",21860 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",21861 "path": null,21862 "status": "built_in",21863 "kind": "rule"21864 },21865 "mandate": null,21866 "pausedFrom": null,21867 "live": {21868 "capable": false,21869 "code": "family_not_live",21870 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"21871 },21872 "stopReason": null,21873 "lastBar": null,21874 "createdAt": 1794953757211,21875 "updatedAt": 179495375723021876 }21877 }21878 }21879 }21880 },21881 "400": {21882 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",21883 "content": {21884 "application/json": {21885 "schema": {21886 "$ref": "#/components/schemas/Error"21887 }21888 }21889 }21890 },21891 "401": {21892 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",21893 "content": {21894 "application/json": {21895 "schema": {21896 "$ref": "#/components/schemas/Error"21897 }21898 }21899 }21900 },21901 "403": {21902 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `owner_required`, `restricted`",21903 "content": {21904 "application/json": {21905 "schema": {21906 "$ref": "#/components/schemas/Error"21907 }21908 }21909 }21910 },21911 "404": {21912 "description": "The object named by the request does not exist: `not_found`",21913 "content": {21914 "application/json": {21915 "schema": {21916 "$ref": "#/components/schemas/Error"21917 }21918 }21919 }21920 },21921 "409": {21922 "description": "The request conflicts with the state of the object, or needs a choice: `bad_report`, `bad_state`, `halted`, `idempotency_conflict`, `idempotency_in_progress`, `live_unavailable`, `mandate_required`, `no_report`, `no_strategy`",21923 "content": {21924 "application/json": {21925 "schema": {21926 "$ref": "#/components/schemas/Error"21927 }21928 }21929 }21930 },21931 "429": {21932 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",21933 "content": {21934 "application/json": {21935 "schema": {21936 "$ref": "#/components/schemas/Error"21937 }21938 }21939 }21940 },21941 "500": {21942 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",21943 "content": {21944 "application/json": {21945 "schema": {21946 "$ref": "#/components/schemas/Error"21947 }21948 }21949 }21950 }21951 }21952 }21953 },21954 "/api/v1/trading/agents/{id}/pause": {21955 "post": {21956 "operationId": "pauseAgent",21957 "tags": [21958 "Agents"21959 ],21960 "summary": "Pause an agent",21961 "description": "No new exposure. A live perp agent keeps its positions and its mandate; a live spot agent's mandate is revoked at the signer (resuming it needs a new owner approval).",21962 "security": [21963 {21964 "bearerKey": [21965 "agents:manage"21966 ]21967 }21968 ],21969 "x-spw-scope": "agents:manage",21970 "x-spw-implemented": true,21971 "x-spw-idempotent": true,21972 "x-spw-errors": [21973 {21974 "status": 400,21975 "code": "bad_request"21976 },21977 {21978 "status": 400,21979 "code": "idempotency"21980 },21981 {21982 "status": 400,21983 "code": "stale_request"21984 },21985 {21986 "status": 401,21987 "code": "unauthenticated"21988 },21989 {21990 "status": 403,21991 "code": "insufficient_scope"21992 },21993 {21994 "status": 403,21995 "code": "ip_not_allowed"21996 },21997 {21998 "status": 403,21999 "code": "mixed_credentials"22000 },22001 {22002 "status": 403,22003 "code": "restricted"22004 },22005 {22006 "status": 404,22007 "code": "not_found"22008 },22009 {22010 "status": 409,22011 "code": "bad_state"22012 },22013 {22014 "status": 409,22015 "code": "idempotency_conflict"22016 },22017 {22018 "status": 409,22019 "code": "idempotency_in_progress"22020 },22021 {22022 "status": 429,22023 "code": "auth_throttled"22024 },22025 {22026 "status": 429,22027 "code": "rate_limited"22028 },22029 {22030 "status": 500,22031 "code": "internal"22032 }22033 ],22034 "x-spw-example-recorded": true,22035 "x-codeSamples": [22036 {22037 "lang": "Shell",22038 "label": "curl",22039 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/pause\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"documentation example\"}'"22040 },22041 {22042 "lang": "TypeScript",22043 "label": "TypeScript",22044 "source": "await client.pauseAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });"22045 },22046 {22047 "lang": "Python",22048 "label": "Python",22049 "source": "client.pause_agent(\"b9180e9d-3977-403c-a072-9af105bfd59b\", reason=\"documentation example\")"22050 }22051 ],22052 "parameters": [22053 {22054 "name": "id",22055 "in": "path",22056 "required": true,22057 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",22058 "schema": {22059 "type": "string",22060 "minLength": 1,22061 "maxLength": 20022062 },22063 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"22064 },22065 {22066 "name": "Idempotency-Key",22067 "in": "header",22068 "required": true,22069 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",22070 "schema": {22071 "type": "string",22072 "pattern": "^[A-Za-z0-9._:-]{8,100}$"22073 }22074 },22075 {22076 "name": "X-SPW-Timestamp",22077 "in": "header",22078 "required": false,22079 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",22080 "schema": {22081 "type": "string",22082 "pattern": "^\\d{9,11}$"22083 }22084 }22085 ],22086 "requestBody": {22087 "required": true,22088 "content": {22089 "application/json": {22090 "schema": {22091 "type": "object",22092 "properties": {22093 "reason": {22094 "default": "",22095 "description": "why, for the agent's journal",22096 "type": "string",22097 "maxLength": 20022098 }22099 },22100 "additionalProperties": false22101 },22102 "example": {22103 "reason": "documentation example"22104 }22105 }22106 }22107 },22108 "responses": {22109 "200": {22110 "description": "OK (the example is a recorded answer)",22111 "content": {22112 "application/json": {22113 "schema": {22114 "type": "object",22115 "properties": {22116 "agent": {22117 "type": "object",22118 "properties": {22119 "id": {22120 "type": "string"22121 },22122 "state": {22123 "type": "string",22124 "enum": [22125 "active",22126 "paused",22127 "stopped"22128 ]22129 },22130 "mode": {22131 "type": "string",22132 "enum": [22133 "research",22134 "paper",22135 "live"22136 ],22137 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."22138 }22139 },22140 "required": [22141 "id",22142 "state",22143 "mode"22144 ],22145 "additionalProperties": {}22146 }22147 },22148 "required": [22149 "agent"22150 ],22151 "additionalProperties": {}22152 },22153 "example": {22154 "agent": {22155 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",22156 "name": "Docs funding",22157 "mission": "",22158 "kind": "stream",22159 "family": "funding_arb",22160 "template": "funding-arb",22161 "engine": "stream",22162 "state": "paused",22163 "phase": "PAUSED",22164 "mode": "paper",22165 "venue": "hyperliquid+dydx",22166 "network": "hyperliquid+dydx",22167 "universe": [22168 "BTC"22169 ],22170 "interval": "stream",22171 "capitalUsd": "1000",22172 "riskLimits": {22173 "maxGrossUsd": 1000,22174 "maxDataAgeMs": 5000,22175 "maxPositionUsd": 500,22176 "maxDailyLossPct": 2,22177 "maxTotalLossPct": 522178 },22179 "configVersion": 1,22180 "strategy": {22181 "name": "funding_differential",22182 "version": "1",22183 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",22184 "path": null,22185 "status": "built_in",22186 "kind": "rule"22187 },22188 "mandate": null,22189 "pausedFrom": "PAPER",22190 "live": {22191 "capable": false,22192 "code": "family_not_live",22193 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"22194 },22195 "stopReason": null,22196 "lastBar": null,22197 "createdAt": 1794953757211,22198 "updatedAt": 179495376376022199 }22200 }22201 }22202 }22203 },22204 "400": {22205 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",22206 "content": {22207 "application/json": {22208 "schema": {22209 "$ref": "#/components/schemas/Error"22210 }22211 }22212 }22213 },22214 "401": {22215 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",22216 "content": {22217 "application/json": {22218 "schema": {22219 "$ref": "#/components/schemas/Error"22220 }22221 }22222 }22223 },22224 "403": {22225 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",22226 "content": {22227 "application/json": {22228 "schema": {22229 "$ref": "#/components/schemas/Error"22230 }22231 }22232 }22233 },22234 "404": {22235 "description": "The object named by the request does not exist: `not_found`",22236 "content": {22237 "application/json": {22238 "schema": {22239 "$ref": "#/components/schemas/Error"22240 }22241 }22242 }22243 },22244 "409": {22245 "description": "The request conflicts with the state of the object, or needs a choice: `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",22246 "content": {22247 "application/json": {22248 "schema": {22249 "$ref": "#/components/schemas/Error"22250 }22251 }22252 }22253 },22254 "429": {22255 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",22256 "content": {22257 "application/json": {22258 "schema": {22259 "$ref": "#/components/schemas/Error"22260 }22261 }22262 }22263 },22264 "500": {22265 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",22266 "content": {22267 "application/json": {22268 "schema": {22269 "$ref": "#/components/schemas/Error"22270 }22271 }22272 }22273 }22274 }22275 }22276 },22277 "/api/v1/trading/agents/{id}/stop": {22278 "post": {22279 "operationId": "stopAgent",22280 "tags": [22281 "Agents"22282 ],22283 "summary": "Stop an agent (always allowed)",22284 "description": "Always allowed. The safe wind-down: a live perp agent's mandate is revoked and its positions are closed with reduce-only orders; a live spot agent's mandate is revoked at the signer; simulated quotes are withdrawn.",22285 "security": [22286 {22287 "bearerKey": [22288 "agents:manage"22289 ]22290 }22291 ],22292 "x-spw-scope": "agents:manage",22293 "x-spw-implemented": true,22294 "x-spw-idempotent": true,22295 "x-spw-errors": [22296 {22297 "status": 400,22298 "code": "bad_request"22299 },22300 {22301 "status": 400,22302 "code": "idempotency"22303 },22304 {22305 "status": 400,22306 "code": "stale_request"22307 },22308 {22309 "status": 401,22310 "code": "unauthenticated"22311 },22312 {22313 "status": 403,22314 "code": "insufficient_scope"22315 },22316 {22317 "status": 403,22318 "code": "ip_not_allowed"22319 },22320 {22321 "status": 403,22322 "code": "mixed_credentials"22323 },22324 {22325 "status": 403,22326 "code": "restricted"22327 },22328 {22329 "status": 404,22330 "code": "not_found"22331 },22332 {22333 "status": 409,22334 "code": "bad_state"22335 },22336 {22337 "status": 409,22338 "code": "idempotency_conflict"22339 },22340 {22341 "status": 409,22342 "code": "idempotency_in_progress"22343 },22344 {22345 "status": 429,22346 "code": "auth_throttled"22347 },22348 {22349 "status": 429,22350 "code": "rate_limited"22351 },22352 {22353 "status": 500,22354 "code": "internal"22355 }22356 ],22357 "x-spw-example-recorded": true,22358 "x-codeSamples": [22359 {22360 "lang": "Shell",22361 "label": "curl",22362 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/stop\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"reason\":\"documentation example\"}'"22363 },22364 {22365 "lang": "TypeScript",22366 "label": "TypeScript",22367 "source": "await client.stopAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { reason: 'documentation example' });"22368 },22369 {22370 "lang": "Python",22371 "label": "Python",22372 "source": "client.stop_agent(\"b9180e9d-3977-403c-a072-9af105bfd59b\", reason=\"documentation example\")"22373 }22374 ],22375 "parameters": [22376 {22377 "name": "id",22378 "in": "path",22379 "required": true,22380 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",22381 "schema": {22382 "type": "string",22383 "minLength": 1,22384 "maxLength": 20022385 },22386 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"22387 },22388 {22389 "name": "Idempotency-Key",22390 "in": "header",22391 "required": true,22392 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",22393 "schema": {22394 "type": "string",22395 "pattern": "^[A-Za-z0-9._:-]{8,100}$"22396 }22397 },22398 {22399 "name": "X-SPW-Timestamp",22400 "in": "header",22401 "required": false,22402 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",22403 "schema": {22404 "type": "string",22405 "pattern": "^\\d{9,11}$"22406 }22407 }22408 ],22409 "requestBody": {22410 "required": true,22411 "content": {22412 "application/json": {22413 "schema": {22414 "type": "object",22415 "properties": {22416 "reason": {22417 "default": "",22418 "description": "why, for the agent's journal",22419 "type": "string",22420 "maxLength": 20022421 }22422 },22423 "additionalProperties": false22424 },22425 "example": {22426 "reason": "documentation example"22427 }22428 }22429 }22430 },22431 "responses": {22432 "200": {22433 "description": "OK (the example is a recorded answer)",22434 "content": {22435 "application/json": {22436 "schema": {22437 "type": "object",22438 "properties": {22439 "agent": {22440 "type": "object",22441 "properties": {22442 "id": {22443 "type": "string"22444 },22445 "state": {22446 "type": "string",22447 "enum": [22448 "active",22449 "paused",22450 "stopped"22451 ]22452 },22453 "mode": {22454 "type": "string",22455 "enum": [22456 "research",22457 "paper",22458 "live"22459 ],22460 "description": "research = analysis and backtests, never an order; paper = explicit simulation; live = a real venue under an owner-approved mandate. One answer never carries two modes."22461 }22462 },22463 "required": [22464 "id",22465 "state",22466 "mode"22467 ],22468 "additionalProperties": {}22469 }22470 },22471 "required": [22472 "agent"22473 ],22474 "additionalProperties": {}22475 },22476 "example": {22477 "agent": {22478 "id": "b9180e9d-3977-403c-a072-9af105bfd59b",22479 "name": "Docs funding",22480 "mission": "",22481 "kind": "stream",22482 "family": "funding_arb",22483 "template": "funding-arb",22484 "engine": "stream",22485 "state": "stopped",22486 "phase": "STOPPED",22487 "mode": "paper",22488 "venue": "hyperliquid+dydx",22489 "network": "hyperliquid+dydx",22490 "universe": [22491 "BTC"22492 ],22493 "interval": "stream",22494 "capitalUsd": "1000",22495 "riskLimits": {22496 "maxGrossUsd": 1000,22497 "maxDataAgeMs": 5000,22498 "maxPositionUsd": 500,22499 "maxDailyLossPct": 2,22500 "maxTotalLossPct": 522501 },22502 "configVersion": 1,22503 "strategy": {22504 "name": "funding_differential",22505 "version": "1",22506 "sha256": "7c53a77d736f7b71e27fb395c798349a14ed65cd42da6b7b0f6bb35ed078f4e3",22507 "path": null,22508 "status": "built_in",22509 "kind": "rule"22510 },22511 "mandate": null,22512 "pausedFrom": "PAPER",22513 "live": {22514 "capable": false,22515 "code": "family_not_live",22516 "reason": "mode réel indisponible : une seule plateforme autorise l'exécution sous mandat"22517 },22518 "stopReason": "stopped by key:spk_0123456789ab: documentation example",22519 "lastBar": null,22520 "createdAt": 1794953757211,22521 "updatedAt": 179495376376722522 },22523 "windDown": null22524 }22525 }22526 }22527 },22528 "400": {22529 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",22530 "content": {22531 "application/json": {22532 "schema": {22533 "$ref": "#/components/schemas/Error"22534 }22535 }22536 }22537 },22538 "401": {22539 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",22540 "content": {22541 "application/json": {22542 "schema": {22543 "$ref": "#/components/schemas/Error"22544 }22545 }22546 }22547 },22548 "403": {22549 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",22550 "content": {22551 "application/json": {22552 "schema": {22553 "$ref": "#/components/schemas/Error"22554 }22555 }22556 }22557 },22558 "404": {22559 "description": "The object named by the request does not exist: `not_found`",22560 "content": {22561 "application/json": {22562 "schema": {22563 "$ref": "#/components/schemas/Error"22564 }22565 }22566 }22567 },22568 "409": {22569 "description": "The request conflicts with the state of the object, or needs a choice: `bad_state`, `idempotency_conflict`, `idempotency_in_progress`",22570 "content": {22571 "application/json": {22572 "schema": {22573 "$ref": "#/components/schemas/Error"22574 }22575 }22576 }22577 },22578 "429": {22579 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",22580 "content": {22581 "application/json": {22582 "schema": {22583 "$ref": "#/components/schemas/Error"22584 }22585 }22586 }22587 },22588 "500": {22589 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",22590 "content": {22591 "application/json": {22592 "schema": {22593 "$ref": "#/components/schemas/Error"22594 }22595 }22596 }22597 }22598 }22599 }22600 },22601 "/api/v1/trading/agents/{id}/backtest": {22602 "post": {22603 "operationId": "backtestAgent",22604 "tags": [22605 "Agents"22606 ],22607 "summary": "Run a backtest for an agent (asynchronous job)",22608 "description": "Bar agents: the laboratory backtest of the strategy version. Stream agents: the rule replayed on the top-of-book snapshots the stream engine recorded. Always a BACKTEST, labelled as such.",22609 "security": [22610 {22611 "bearerKey": [22612 "agents:manage"22613 ]22614 }22615 ],22616 "x-spw-scope": "agents:manage",22617 "x-spw-implemented": true,22618 "x-spw-idempotent": true,22619 "x-spw-errors": [22620 {22621 "status": 400,22622 "code": "bad_request"22623 },22624 {22625 "status": 400,22626 "code": "idempotency"22627 },22628 {22629 "status": 400,22630 "code": "stale_request"22631 },22632 {22633 "status": 401,22634 "code": "unauthenticated"22635 },22636 {22637 "status": 403,22638 "code": "insufficient_scope"22639 },22640 {22641 "status": 403,22642 "code": "ip_not_allowed"22643 },22644 {22645 "status": 403,22646 "code": "mixed_credentials"22647 },22648 {22649 "status": 403,22650 "code": "restricted"22651 },22652 {22653 "status": 404,22654 "code": "not_found"22655 },22656 {22657 "status": 409,22658 "code": "idempotency_conflict"22659 },22660 {22661 "status": 409,22662 "code": "idempotency_in_progress"22663 },22664 {22665 "status": 409,22666 "code": "no_strategy"22667 },22668 {22669 "status": 409,22670 "code": "wrong_kind"22671 },22672 {22673 "status": 429,22674 "code": "auth_throttled"22675 },22676 {22677 "status": 429,22678 "code": "rate_limited"22679 },22680 {22681 "status": 500,22682 "code": "internal"22683 }22684 ],22685 "x-spw-example-recorded": true,22686 "x-codeSamples": [22687 {22688 "lang": "Shell",22689 "label": "curl",22690 "source": "curl -s -X POST \"$SP_WALLET_BASE_URL/api/v1/trading/agents/b9180e9d-3977-403c-a072-9af105bfd59b/backtest\" \\\n -H \"Authorization: Bearer $SP_WALLET_API_KEY\" \\\n -H \"Idempotency-Key: $(uuidgen)\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"hours\":1}'"22691 },22692 {22693 "lang": "TypeScript",22694 "label": "TypeScript",22695 "source": "const { job } = await client.backtestAgent('b9180e9d-3977-403c-a072-9af105bfd59b', { hours: 1 });"22696 },22697 {22698 "lang": "Python",22699 "label": "Python",22700 "source": "job = client.backtest_agent(\"b9180e9d-3977-403c-a072-9af105bfd59b\", hours=1).job"22701 }22702 ],22703 "parameters": [22704 {22705 "name": "id",22706 "in": "path",22707 "required": true,22708 "description": "the `id` a list or a creation of this API returned; URL-encode it (a position id contains colons)",22709 "schema": {22710 "type": "string",22711 "minLength": 1,22712 "maxLength": 20022713 },22714 "example": "b9180e9d-3977-403c-a072-9af105bfd59b"22715 },22716 {22717 "name": "Idempotency-Key",22718 "in": "header",22719 "required": true,22720 "description": "Replay protection: 8 to 100 characters (letters, digits, . _ : -). The same key with the same request returns the first answer; with a different request, 409 `idempotency_conflict`.",22721 "schema": {22722 "type": "string",22723 "pattern": "^[A-Za-z0-9._:-]{8,100}$"22724 }22725 },22726 {22727 "name": "X-SPW-Timestamp",22728 "in": "header",22729 "required": false,22730 "description": "Optional freshness check: Unix seconds; refused (400 `stale_request`) when more than 300 s from the server clock.",22731 "schema": {22732 "type": "string",22733 "pattern": "^\\d{9,11}$"22734 }22735 }22736 ],22737 "requestBody": {22738 "required": true,22739 "content": {22740 "application/json": {22741 "schema": {22742 "type": "object",22743 "properties": {22744 "versionId": {22745 "description": "bar agents: the strategy version to backtest; default: the agent's current one",22746 "type": "string",22747 "format": "uuid",22748 "pattern": "^([0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-8][0-9a-fA-F]{3}-[89abAB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}|00000000-0000-0000-0000-000000000000|ffffffff-ffff-ffff-ffff-ffffffffffff)$"22749 },22750 "hours": {22751 "description": "stream agents: how many hours of recorded snapshots to replay",22752 "type": "integer",22753 "minimum": 1,22754 "maximum": 16822755 }22756 },22757 "additionalProperties": false22758 },22759 "example": {22760 "hours": 122761 }22762 }22763 }22764 },22765 "responses": {22766 "200": {22767 "description": "OK (the example is a recorded answer)",22768 "content": {22769 "application/json": {22770 "schema": {22771 "type": "object",22772 "properties": {22773 "job": {22774 "type": "object",22775 "properties": {22776 "id": {22777 "type": "string"22778 },22779 "kind": {22780 "type": "string"22781 },22782 "status": {22783 "type": "string",22784 "enum": [22785 "queued",22786 "running",22787 "done",22788 "failed",22789 "cancelled"22790 ]22791 },22792 "attempts": {22793 "type": "integer",22794 "minimum": -9007199254740991,22795 "maximum": 900719925474099122796 }22797 },22798 "required": [22799 "id",22800 "kind",22801 "status",22802 "attempts"22803 ],22804 "additionalProperties": {}22805 },22806 "label": {22807 "type": "string"22808 }22809 },22810 "required": [22811 "job"22812 ],22813 "additionalProperties": false22814 },22815 "example": {22816 "job": {22817 "id": "72526d3e-9b2a-4f86-977b-07b6531868a8",22818 "agentId": "b9180e9d-3977-403c-a072-9af105bfd59b",22819 "kind": "backtest",22820 "status": "queued",22821 "deadLettered": false,22822 "attempts": 0,22823 "maxAttempts": 2,22824 "runAt": 1794953761249,22825 "error": null,22826 "result": null,22827 "createdAt": 1794953761249,22828 "updatedAt": 1794953761249,22829 "finishedAt": null22830 },22831 "label": "backtest"22832 }22833 }22834 }22835 },22836 "400": {22837 "description": "The request is not valid: `bad_request`, `idempotency`, `stale_request`",22838 "content": {22839 "application/json": {22840 "schema": {22841 "$ref": "#/components/schemas/Error"22842 }22843 }22844 }22845 },22846 "401": {22847 "description": "Missing, malformed, unknown, expired or revoked key: `unauthenticated`",22848 "content": {22849 "application/json": {22850 "schema": {22851 "$ref": "#/components/schemas/Error"22852 }22853 }22854 }22855 },22856 "403": {22857 "description": "Authenticated, and refused: `insufficient_scope`, `ip_not_allowed`, `mixed_credentials`, `restricted`",22858 "content": {22859 "application/json": {22860 "schema": {22861 "$ref": "#/components/schemas/Error"22862 }22863 }22864 }22865 },22866 "404": {22867 "description": "The object named by the request does not exist: `not_found`",22868 "content": {22869 "application/json": {22870 "schema": {22871 "$ref": "#/components/schemas/Error"22872 }22873 }22874 }22875 },22876 "409": {22877 "description": "The request conflicts with the state of the object, or needs a choice: `idempotency_conflict`, `idempotency_in_progress`, `no_strategy`, `wrong_kind`",22878 "content": {22879 "application/json": {22880 "schema": {22881 "$ref": "#/components/schemas/Error"22882 }22883 }22884 }22885 },22886 "429": {22887 "description": "Too many requests (see the `RateLimit-*` and `Retry-After` headers): `auth_throttled`, `rate_limited`",22888 "content": {22889 "application/json": {22890 "schema": {22891 "$ref": "#/components/schemas/Error"22892 }22893 }22894 }22895 },22896 "500": {22897 "description": "Server error; a mutating call may or may not have run: send it again with the same Idempotency-Key: `internal`",22898 "content": {22899 "application/json": {22900 "schema": {22901 "$ref": "#/components/schemas/Error"22902 }22903 }22904 }22905 }22906 }22907 }22908 }22909 },22910 "components": {22911 "securitySchemes": {22912 "bearerKey": {22913 "type": "http",22914 "scheme": "bearer",22915 "bearerFormat": "spw_live_<key id>_<secret>",22916 "description": "API key shown once at creation. Never sent together with a session cookie."22917 }22918 },22919 "schemas": {22920 "Error": {22921 "type": "object",22922 "properties": {22923 "error": {22924 "type": "string",22925 "description": "stable machine code: one of the operation's `x-spw-errors`"22926 },22927 "message": {22928 "type": "string",22929 "description": "human-readable sentence (English)"22930 },22931 "candidates": {22932 "description": "`ambiguous_symbol`: the `venue:symbol` ids the bare symbol could mean",22933 "type": "array",22934 "items": {22935 "type": "string"22936 }22937 },22938 "data": {22939 "description": "machine-readable detail of a refusal",22940 "type": "object",22941 "properties": {22942 "order": {22943 "$ref": "#/components/schemas/Order",22944 "description": "the order the refusal is about, when one exists (state REJECTED or FAILED)"22945 },22946 "reasons": {22947 "description": "`mandate_denied`: codes of `x-spw-mandate-deny-reasons`; a mandate that cannot be used: the error code in upper case",22948 "type": "array",22949 "items": {22950 "type": "string"22951 }22952 },22953 "failed": {22954 "description": "`risk_denied`, `kill_switch_active`, `read_only_mode`: ids of the failed risk checks",22955 "type": "array",22956 "items": {22957 "type": "string"22958 }22959 },22960 "checks": {22961 "description": "the failed risk checks, each with what was observed and its limit",22962 "type": "array",22963 "items": {22964 "$ref": "#/components/schemas/RiskCheck"22965 }22966 },22967 "decisionId": {22968 "type": "integer",22969 "minimum": -9007199254740991,22970 "maximum": 900719925474099122971 },22972 "questions": {22973 "description": "`ambiguous_command`: what the command and the owner's defaults leave open",22974 "type": "array",22975 "items": {22976 "type": "object",22977 "properties": {22978 "field": {22979 "type": "string"22980 },22981 "options": {22982 "type": "array",22983 "items": {22984 "type": "string"22985 },22986 "description": "the known candidates; empty = a free value is needed"22987 },22988 "message": {22989 "type": "string"22990 }22991 },22992 "required": [22993 "field",22994 "options",22995 "message"22996 ],22997 "additionalProperties": {}22998 }22999 },23000 "code": {23001 "description": "`parse_error`: the grammar's own code",23002 "type": "string"23003 },23004 "token": {23005 "description": "`parse_error`: index of the offending token",23006 "type": "integer",23007 "minimum": -9007199254740991,23008 "maximum": 900719925474099123009 }23010 },23011 "additionalProperties": {}23012 }23013 },23014 "required": [23015 "error",23016 "message"23017 ],23018 "additionalProperties": {}23019 },23020 "Order": {23021 "type": "object",23022 "properties": {23023 "id": {23024 "type": "string",23025 "description": "the id every order operation takes"23026 },23027 "mode": {23028 "type": "string",23029 "enum": [23030 "paper",23031 "live"23032 ],23033 "description": "paper = simulated, live = a venue or on-chain account. The two are never merged in one figure."23034 },23035 "venue": {23036 "type": "string"23037 },23038 "network": {23039 "type": "string"23040 },23041 "accountId": {23042 "type": [23043 "string",23044 "null"23045 ]23046 },23047 "instrument": {23048 "type": [23049 "string",23050 "null"23051 ]23052 },23053 "side": {23054 "type": [23055 "string",23056 "null"23057 ]23058 },23059 "type": {23060 "type": "string"23061 },23062 "status": {23063 "type": "string",23064 "enum": [23065 "CREATED",23066 "VALIDATED",23067 "AWAITING_APPROVAL",23068 "APPROVED",23069 "SUBMITTING",23070 "SUBMITTED",23071 "PARTIALLY_FILLED",23072 "FILLED",23073 "CANCELLED",23074 "REJECTED",23075 "FAILED",23076 "UNKNOWN"23077 ],23078 "description": "unified order state. Final: FILLED, CANCELLED, REJECTED, FAILED. UNKNOWN means the outcome at the venue is not known yet: it is not final and it is not a failure"23079 },23080 "engineStatus": {23081 "description": "the word of the engine that executes the order (paper engine, Hyperliquid engine, GMX operation, agent swap) for the same moment; null before an engine holds it. Informative: decide on `status`",23082 "type": [23083 "string",23084 "null"23085 ]23086 },23087 "final": {23088 "type": "boolean",23089 "description": "true exactly when `status` is FILLED, CANCELLED, REJECTED or FAILED"23090 },23091 "size": {23092 "anyOf": [23093 {23094 "type": "string",23095 "description": "decimal number as a string (never a float)"23096 },23097 {23098 "type": "null"23099 }23100 ]23101 },23102 "price": {23103 "anyOf": [23104 {23105 "type": "string",23106 "description": "decimal number as a string (never a float)"23107 },23108 {23109 "type": "null"23110 }23111 ]23112 },23113 "triggerPrice": {23114 "anyOf": [23115 {23116 "type": "string",23117 "description": "decimal number as a string (never a float)"23118 },23119 {23120 "type": "null"23121 }23122 ]23123 },23124 "reduceOnly": {23125 "type": "boolean"23126 },23127 "tif": {23128 "type": "string"23129 },23130 "filled": {23131 "description": "cumulative filled size, base units",23132 "type": "string"23133 },23134 "avgFillPrice": {23135 "anyOf": [23136 {23137 "type": "string",23138 "description": "decimal number as a string (never a float)"23139 },23140 {23141 "type": "null"23142 }23143 ]23144 },23145 "reasonCode": {23146 "description": "closed reason code of the current state (state machine)",23147 "type": [23148 "string",23149 "null"23150 ]23151 },23152 "reason": {23153 "description": "sentence for people",23154 "type": [23155 "string",23156 "null"23157 ]23158 },23159 "rejectCode": {23160 "description": "API error code of the refusal, when the order was refused",23161 "type": [23162 "string",23163 "null"23164 ]23165 },23166 "clientOrderId": {23167 "type": [23168 "string",23169 "null"23170 ]23171 },23172 "orderId": {23173 "type": "string"23174 },23175 "origin": {23176 "type": "string"23177 },23178 "mandateId": {23179 "type": [23180 "string",23181 "null"23182 ]23183 },23184 "notionalUsd": {23185 "anyOf": [23186 {23187 "type": "string",23188 "description": "decimal number as a string (never a float)"23189 },23190 {23191 "type": "null"23192 }23193 ]23194 },23195 "createdAt": {23196 "type": "integer",23197 "minimum": -9007199254740991,23198 "maximum": 9007199254740991,23199 "description": "milliseconds since the Unix epoch"23200 },23201 "updatedAt": {23202 "type": "integer",23203 "minimum": -9007199254740991,23204 "maximum": 9007199254740991,23205 "description": "milliseconds since the Unix epoch"23206 }23207 },23208 "required": [23209 "id",23210 "mode",23211 "venue",23212 "network",23213 "accountId",23214 "instrument",23215 "side",23216 "type",23217 "status",23218 "engineStatus",23219 "final",23220 "createdAt",23221 "updatedAt"23222 ],23223 "additionalProperties": {}23224 },23225 "CanonicalOrder": {23226 "type": "object",23227 "properties": {23228 "v": {23229 "type": "number",23230 "const": 123231 },23232 "venue": {23233 "type": "string"23234 },23235 "network": {23236 "type": "string"23237 },23238 "instrument": {23239 "type": "string"23240 },23241 "marketKind": {23242 "type": "string",23243 "enum": [23244 "spot",23245 "perp"23246 ]23247 },23248 "side": {23249 "type": "string",23250 "enum": [23251 "buy",23252 "sell"23253 ]23254 },23255 "type": {23256 "type": "string",23257 "enum": [23258 "market",23259 "limit",23260 "stop",23261 "take_profit"23262 ]23263 },23264 "size": {23265 "anyOf": [23266 {23267 "type": "string",23268 "description": "decimal number as a string (never a float)"23269 },23270 {23271 "type": "null"23272 }23273 ]23274 },23275 "notional": {23276 "anyOf": [23277 {23278 "type": "string",23279 "description": "decimal number as a string (never a float)"23280 },23281 {23282 "type": "null"23283 }23284 ]23285 },23286 "limitPrice": {23287 "anyOf": [23288 {23289 "type": "string",23290 "description": "decimal number as a string (never a float)"23291 },23292 {23293 "type": "null"23294 }23295 ]23296 },23297 "triggerPrice": {23298 "anyOf": [23299 {23300 "type": "string",23301 "description": "decimal number as a string (never a float)"23302 },23303 {23304 "type": "null"23305 }23306 ]23307 },23308 "reduceOnly": {23309 "type": "boolean"23310 },23311 "tif": {23312 "type": "string"23313 },23314 "maxSlippageBps": {23315 "type": "integer",23316 "minimum": -9007199254740991,23317 "maximum": 900719925474099123318 },23319 "maxFeeUsd": {23320 "type": "string",23321 "description": "decimal number as a string (never a float)"23322 },23323 "leverage": {23324 "anyOf": [23325 {23326 "type": "string",23327 "description": "decimal number as a string (never a float)"23328 },23329 {23330 "type": "null"23331 }23332 ]23333 },23334 "clientOrderId": {23335 "type": "string"23336 },23337 "mode": {23338 "type": "string",23339 "enum": [23340 "research",23341 "paper",23342 "live"23343 ]23344 },23345 "principal": {23346 "type": "object",23347 "properties": {23348 "kind": {23349 "type": "string",23350 "enum": [23351 "owner",23352 "agent",23353 "api_key"23354 ]23355 },23356 "id": {23357 "type": "string"23358 }23359 },23360 "required": [23361 "kind",23362 "id"23363 ],23364 "additionalProperties": {}23365 },23366 "mandateId": {23367 "type": [23368 "string",23369 "null"23370 ]23371 },23372 "createdAt": {23373 "type": "integer",23374 "minimum": -9007199254740991,23375 "maximum": 9007199254740991,23376 "description": "milliseconds since the Unix epoch"23377 },23378 "expiresAt": {23379 "type": "integer",23380 "minimum": -9007199254740991,23381 "maximum": 9007199254740991,23382 "description": "milliseconds since the Unix epoch"23383 }23384 },23385 "required": [23386 "v",23387 "venue",23388 "network",23389 "instrument",23390 "marketKind",23391 "side",23392 "type",23393 "size",23394 "notional",23395 "limitPrice",23396 "triggerPrice",23397 "reduceOnly",23398 "tif",23399 "maxSlippageBps",23400 "maxFeeUsd",23401 "leverage",23402 "clientOrderId",23403 "mode",23404 "principal",23405 "mandateId",23406 "createdAt",23407 "expiresAt"23408 ],23409 "additionalProperties": {},23410 "description": "the canonical order SPW-ORDER-INTENT-v1: what is hashed, checked by the mandate and the risk engine, and handed to the engine"23411 },23412 "RiskCheck": {23413 "type": "object",23414 "properties": {23415 "id": {23416 "type": "string",23417 "description": "one of `x-spw-risk-checks`"23418 },23419 "ok": {23420 "type": "boolean"23421 },23422 "observed": {23423 "type": [23424 "string",23425 "null"23426 ]23427 },23428 "limit": {23429 "type": [23430 "string",23431 "null"23432 ]23433 },23434 "detail": {23435 "type": "string"23436 },23437 "exempt": {23438 "type": "boolean"23439 }23440 },23441 "required": [23442 "id",23443 "ok",23444 "observed",23445 "limit",23446 "detail",23447 "exempt"23448 ],23449 "additionalProperties": {}23450 },23451 "Switch": {23452 "type": "object",23453 "properties": {23454 "on": {23455 "type": "boolean"23456 },23457 "at": {23458 "anyOf": [23459 {23460 "type": "integer",23461 "minimum": -9007199254740991,23462 "maximum": 9007199254740991,23463 "description": "milliseconds since the Unix epoch"23464 },23465 {23466 "type": "null"23467 }23468 ]23469 },23470 "by": {23471 "anyOf": [23472 {23473 "type": "object",23474 "properties": {23475 "kind": {23476 "type": "string"23477 },23478 "id": {23479 "type": "string"23480 }23481 },23482 "required": [23483 "kind",23484 "id"23485 ],23486 "additionalProperties": {}23487 },23488 {23489 "type": "null"23490 }23491 ]23492 },23493 "reason": {23494 "type": [23495 "string",23496 "null"23497 ]23498 }23499 },23500 "required": [23501 "on",23502 "at",23503 "by",23504 "reason"23505 ],23506 "additionalProperties": {}23507 }23508 }23509 },23510 "x-spw-scopes": [23511 {23512 "scope": "wallet:read",23513 "execution": false23514 },23515 {23516 "scope": "markets:read",23517 "execution": false23518 },23519 {23520 "scope": "orders:read",23521 "execution": false23522 },23523 {23524 "scope": "orders:prepare",23525 "execution": false23526 },23527 {23528 "scope": "orders:execute",23529 "execution": true23530 },23531 {23532 "scope": "orders:cancel",23533 "execution": true23534 },23535 {23536 "scope": "positions:read",23537 "execution": false23538 },23539 {23540 "scope": "positions:manage",23541 "execution": true23542 },23543 {23544 "scope": "strategies:read",23545 "execution": false23546 },23547 {23548 "scope": "strategies:manage",23549 "execution": false23550 },23551 {23552 "scope": "agents:read",23553 "execution": false23554 },23555 {23556 "scope": "agents:manage",23557 "execution": false23558 }23559 ],23560 "x-spw-scope-docs": {23561 "wallet:read": "Balances, the portfolio, activity, the wallet's NFTs.",23562 "markets:read": "Markets, order books, candles, the venue comparator, private markets, NFT market data, and the websocket stream.",23563 "orders:read": "Orders and their fills.",23564 "orders:prepare": "Preview an order; dry-run a command. Creates nothing.",23565 "orders:execute": "Place an order. Execution scope: inert without a mandate bound to the key.",23566 "orders:cancel": "Cancel the key's own orders. Needs no mandate: a cancel only removes risk.",23567 "positions:read": "Positions and the risk state.",23568 "positions:manage": "Close or reduce a position (needs a mandate); engage the kill switch (needs none).",23569 "strategies:read": "The strategy library and the versions pinned to agents.",23570 "strategies:manage": "Register, backtest, start and stop strategy versions. Research and paper sign nothing.",23571 "agents:read": "Agents, their signals, journal, orders, performance, jobs.",23572 "agents:manage": "Create, start, pause, stop and backtest agents. Going live needs the agent's own owner-approved mandate."23573 },23574 "x-spw-order-states": [23575 {23576 "state": "CREATED",23577 "final": false23578 },23579 {23580 "state": "VALIDATED",23581 "final": false23582 },23583 {23584 "state": "AWAITING_APPROVAL",23585 "final": false23586 },23587 {23588 "state": "APPROVED",23589 "final": false23590 },23591 {23592 "state": "SUBMITTING",23593 "final": false23594 },23595 {23596 "state": "SUBMITTED",23597 "final": false23598 },23599 {23600 "state": "PARTIALLY_FILLED",23601 "final": false23602 },23603 {23604 "state": "FILLED",23605 "final": true23606 },23607 {23608 "state": "CANCELLED",23609 "final": true23610 },23611 {23612 "state": "REJECTED",23613 "final": true23614 },23615 {23616 "state": "FAILED",23617 "final": true23618 },23619 {23620 "state": "UNKNOWN",23621 "final": false23622 }23623 ],23624 "x-spw-order-state-docs": {23625 "CREATED": "recorded; nothing checked yet",23626 "VALIDATED": "passed the mandate and the risk engine",23627 "AWAITING_APPROVAL": "an owner order waits for the passkey in the app (never the case for a key)",23628 "APPROVED": "approved; about to be handed to its engine",23629 "SUBMITTING": "being sent to the venue (or the paper engine)",23630 "SUBMITTED": "accepted by the venue and resting; nothing filled yet",23631 "PARTIALLY_FILLED": "partly filled; the rest is still working",23632 "FILLED": "completely filled. Final",23633 "CANCELLED": "withdrawn, expired or cancelled. Final",23634 "REJECTED": "refused by a rule: validation, mandate, risk, signer policy or the venue. Final; `reasonCode` and `rejectCode` say which",23635 "FAILED": "a technical failure after which it is PROVEN that no order exists at the venue. Final",23636 "UNKNOWN": "the outcome at the venue is not known yet. NOT final and NOT a failure: the server resolves it by asking the venue — keep reading the order, do not send it again under a new key"23637 },23638 "x-spw-mandate-deny-reasons": [23639 "INVALID_INPUT",23640 "MANDATE_NOT_YET_VALID",23641 "MANDATE_ENDED",23642 "MANDATE_REVOKED",23643 "WIND_DOWN_REDUCING_ONLY",23644 "PRINCIPAL_MISMATCH",23645 "MANDATE_ID_MISMATCH",23646 "MODE_MISMATCH",23647 "ACCOUNT_NOT_ALLOWED",23648 "VENUE_NOT_ALLOWED",23649 "NETWORK_NOT_ALLOWED",23650 "INSTRUMENT_NOT_ALLOWED",23651 "MARKET_KIND_NOT_ALLOWED",23652 "ORDER_TYPE_NOT_ALLOWED",23653 "NOTIONAL_UNKNOWN",23654 "ORDER_NOTIONAL_EXCEEDED",23655 "POSITION_NOTIONAL_EXCEEDED",23656 "CAPITAL_EXCEEDED",23657 "LEVERAGE_EXCEEDED",23658 "LEVERAGE_UNKNOWN",23659 "DAILY_LOSS_REACHED",23660 "BELOW_FLOOR_EQUITY",23661 "RATE_PER_MINUTE",23662 "RATE_PER_HOUR",23663 "RATE_PER_DAY",23664 "SLIPPAGE_ABOVE_MANDATE",23665 "FEE_ABOVE_MANDATE",23666 "ORDER_OUTLIVES_MANDATE",23667 "STOP_LOSS_GTE",23668 "STOP_DRAWDOWN_GTE",23669 "STOP_CONSECUTIVE_REJECTS_GTE",23670 "STOP_DATA_STALE_GTE",23671 "STOP_SIGNER_UNREACHABLE_GTE"23672 ],23673 "x-spw-mandate-deny-reason-docs": {23674 "INVALID_INPUT": "the order or the usage figures could not be evaluated",23675 "MANDATE_NOT_YET_VALID": "the mandate's validity window has not started",23676 "MANDATE_ENDED": "the mandate has ended (past its end date and its wind-down)",23677 "MANDATE_REVOKED": "the mandate was revoked",23678 "WIND_DOWN_REDUCING_ONLY": "the mandate is winding down: only strictly reducing orders pass",23679 "PRINCIPAL_MISMATCH": "the mandate was approved for another key or agent",23680 "MANDATE_ID_MISMATCH": "the order names another mandate",23681 "MODE_MISMATCH": "a paper mandate cannot place a live order, nor the reverse",23682 "ACCOUNT_NOT_ALLOWED": "the account is not one of the mandate's",23683 "VENUE_NOT_ALLOWED": "the venue is not one of the mandate's",23684 "NETWORK_NOT_ALLOWED": "the network is not one of the mandate's",23685 "INSTRUMENT_NOT_ALLOWED": "the instrument is not in the mandate's list",23686 "MARKET_KIND_NOT_ALLOWED": "spot or perp is not allowed by the mandate",23687 "ORDER_TYPE_NOT_ALLOWED": "the order type (market, limit, stop, take-profit) is not in the mandate's list",23688 "NOTIONAL_UNKNOWN": "the order cannot be valued (no reference price), so the limits cannot be checked",23689 "ORDER_NOTIONAL_EXCEEDED": "the order is above `maxOrderNotionalUsd`",23690 "POSITION_NOTIONAL_EXCEEDED": "the resulting position is above `maxPositionNotionalUsd`",23691 "CAPITAL_EXCEEDED": "the capital in use after the order is above `maxCapitalUsd`",23692 "LEVERAGE_EXCEEDED": "the leverage is above `maxLeverage`",23693 "LEVERAGE_UNKNOWN": "the leverage the order would run under is not known",23694 "DAILY_LOSS_REACHED": "today's realised loss under the mandate reached `maxDailyLossUsd`",23695 "BELOW_FLOOR_EQUITY": "the equity of the mandated accounts is below `floorEquityUsd`",23696 "RATE_PER_MINUTE": "the mandate's orders-per-minute limit is reached",23697 "RATE_PER_HOUR": "the mandate's orders-per-hour limit is reached",23698 "RATE_PER_DAY": "the mandate's orders-per-day limit is reached",23699 "SLIPPAGE_ABOVE_MANDATE": "the order's slippage bound is above the mandate's `maxSlippageBps`",23700 "FEE_ABOVE_MANDATE": "the order's fee cap is above the mandate's `maxFeeUsd`",23701 "ORDER_OUTLIVES_MANDATE": "the order would stay valid after the mandate ends",23702 "STOP_LOSS_GTE": "stop condition: the total loss under the mandate reached its threshold",23703 "STOP_DRAWDOWN_GTE": "stop condition: the drawdown from the peak equity reached its threshold",23704 "STOP_CONSECUTIVE_REJECTS_GTE": "stop condition: too many consecutive rejected orders",23705 "STOP_DATA_STALE_GTE": "stop condition: the market data is too old",23706 "STOP_SIGNER_UNREACHABLE_GTE": "stop condition: the signer has been unreachable for too long"23707 },23708 "x-spw-error-catalog": {23709 "account_has_active_mandate": {23710 "statuses": [23711 40923712 ],23713 "meaning": "This venue account already carries the mandate of another principal: one venue account serves one principal at a time.",23714 "action": "Use another account, or the owner revokes the other mandate."23715 },23716 "account_required": {23717 "statuses": [23718 40923719 ],23720 "meaning": "The wallet has several accounts on this venue in this mode.",23721 "action": "Name one with `accountId` (GET /portfolio lists them)."23722 },23723 "ambiguous_command": {23724 "statuses": [23725 40923726 ],23727 "meaning": "The command line and the owner's stored defaults leave something open (venue, network, leverage, margin mode, fee cap, order validity). Nothing was executed.",23728 "action": "Read `data.questions` (each has a `field` and its `options`). Say it in the command (`x2`, `ON hyperliquid`) or have the owner set the defaults once."23729 },23730 "ambiguous_order": {23731 "statuses": [23732 40923733 ],23734 "meaning": "The order and the owner's defaults do not settle everything (spot).",23735 "action": "Read `data.questions`; name what is missing, or the owner sets the command defaults."23736 },23737 "ambiguous_position": {23738 "statuses": [23739 40923740 ],23741 "meaning": "The wallet holds a long and a short on this GMX market.",23742 "action": "Name the position by its key."23743 },23744 "ambiguous_symbol": {23745 "statuses": [23746 40923747 ],23748 "meaning": "A bare symbol (`BTC`) exists on several venues.",23749 "action": "Name one of `candidates` as `venue:symbol` (e.g. `hyperliquid:BTC`)."23750 },23751 "auth_throttled": {23752 "statuses": [23753 42923754 ],23755 "meaning": "Ten failed authentications in a minute from this address: every key request from it is refused for the rest of the window, valid keys included.",23756 "action": "Stop sending a bad key. Wait 60 seconds (`Retry-After`)."23757 },23758 "authorization_expired": {23759 "statuses": [23760 42223761 ],23762 "meaning": "The venue authorization of the account has expired.",23763 "action": "The owner approves a new one with the passkey."23764 },23765 "authorization_unknown": {23766 "statuses": [23767 50323768 ],23769 "meaning": "The signer gave no usable answer: it may or may not have stored the authorization.",23770 "action": "The owner uses \"recover\" on the venue account."23771 },23772 "bad_input": {23773 "statuses": [23774 42223775 ],23776 "meaning": "The engine's risk context could not be evaluated.",23777 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."23778 },23779 "bad_mark": {23780 "statuses": [23781 42223782 ],23783 "meaning": "The mark price is not positive.",23784 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."23785 },23786 "bad_order": {23787 "statuses": [23788 42223789 ],23790 "meaning": "The engine cannot express the order (e.g. too many decimals for the asset).",23791 "action": "Fix the request; sending it again unchanged gives the same answer."23792 },23793 "bad_policy": {23794 "statuses": [23795 400,23796 42223797 ],23798 "meaning": "The risk policy of the account is invalid, or names an instrument that is not in the pinned asset table.",23799 "action": "Only the owner can change this, in the app, with the passkey."23800 },23801 "bad_report": {23802 "statuses": [23803 40923804 ],23805 "meaning": "The backtest report disqualifies this version: it cannot run, even on paper.",23806 "action": "Register another version."23807 },23808 "bad_request": {23809 "statuses": [23810 400,23811 409,23812 42223813 ],23814 "meaning": "The path parameters, the query or the JSON body do not match the operation's schema (an unknown field is refused: bodies are strict), or a value is out of its range.",23815 "action": "Fix the request; sending it again unchanged gives the same answer. The schema of each operation is in this reference and in the OpenAPI document."23816 },23817 "bad_state": {23818 "statuses": [23819 40923820 ],23821 "meaning": "The object is not in a state that allows this: an order being handed to its engine right now, a swap already approved, an agent or job already in that state.",23822 "action": "Read the object again; for an order, ask again in a moment."23823 },23824 "bad_strategy": {23825 "statuses": [23826 42223827 ],23828 "meaning": "The laboratory refused the strategy file.",23829 "action": "Read `message`; pick a path from GET /strategies (`library`)."23830 },23831 "below_min_notional": {23832 "statuses": [23833 42223834 ],23835 "meaning": "The order is worth less than the venue's minimum.",23836 "action": "Raise it above `minNotional`."23837 },23838 "below_min_size": {23839 "statuses": [23840 42223841 ],23842 "meaning": "The size is under one lot, or the `notional` buys less than one lot at the reference price, or the fraction of a position is less than one lot.",23843 "action": "Raise the size/notional. `lotSize`, `minOrderSize` and `minNotional` are in GET /markets/{symbol}."23844 },23845 "cancel_in_app": {23846 "statuses": [23847 42223848 ],23849 "meaning": "This order is cancelled in the app (a spot agent's swap, a GMX order).",23850 "action": "Do it in the app."23851 },23852 "close_in_app": {23853 "statuses": [23854 42223855 ],23856 "meaning": "A GMX position is closed by a wallet transaction approved with the passkey.",23857 "action": "Do it in the app."23858 },23859 "daily_loss_exceeded": {23860 "statuses": [23861 42223862 ],23863 "meaning": "The account's daily loss limit is reached.",23864 "action": "No new risk today; reductions pass."23865 },23866 "data_mismatch": {23867 "statuses": [23868 42223869 ],23870 "meaning": "The ticker or book the engine holds is for another instrument.",23871 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."23872 },23873 "duplicate_client_id": {23874 "statuses": [23875 42223876 ],23877 "meaning": "This client order id was already used on the account.",23878 "action": "Use a new `clientOrderId` / Idempotency-Key for a new order."23879 },23880 "execution_disabled": {23881 "statuses": [23882 40323883 ],23884 "meaning": "Live execution through the trading API is closed on this server (`SPW_TRADING_API_EXECUTION` is not `on`). Nothing was created.",23885 "action": "Paper is not affected; cancels and strictly reducing orders still pass. The server operator opens the lock."23886 },23887 "execution_not_wired": {23888 "statuses": [23889 50123890 ],23891 "meaning": "The operation exists in the contract and is not connected on this server (or, for STOP ALL AGENTS, could stop nothing from here). Never a success: nothing was done.",23892 "action": "Do not retry. Use the operation the message points to."23893 },23894 "exists": {23895 "statuses": [23896 40923897 ],23898 "meaning": "A risk-management (supervisor) agent already exists.",23899 "action": "Stop it before creating another."23900 },23901 "fee_cap_not_expressible": {23902 "statuses": [23903 42223904 ],23905 "meaning": "The quote asset is not one the owner's defaults count as USD, so the fee cap cannot be expressed.",23906 "action": "Use a USD quote, or the owner adds it to the defaults (`usdQuotes`)."23907 },23908 "gmx_disabled": {23909 "statuses": [23910 40323911 ],23912 "meaning": "GMX live trading is switched off (server lock or owner setting).",23913 "action": "Only the owner can change this, in the app, with the passkey."23914 },23915 "gmx_leverage_required": {23916 "statuses": [23917 42223918 ],23919 "meaning": "A GMX increase must name its `leverage` (GMX has no leverage setting to fall back on).",23920 "action": "Owner orders only: add `leverage`."23921 },23922 "gmx_requires_owner_passkey": {23923 "statuses": [23924 40323925 ],23926 "meaning": "Every GMX order is a wallet transaction the owner approves with the passkey: a key or an agent cannot place, close or cancel one.",23927 "action": "Do it in the app."23928 },23929 "gross_exposure_exceeded": {23930 "statuses": [23931 42223932 ],23933 "meaning": "The resulting gross exposure exceeds the account policy.",23934 "action": "Reduce first, or send a smaller order."23935 },23936 "halted": {23937 "statuses": [23938 409,23939 422,23940 42323941 ],23942 "meaning": "423/422: the signer's emergency halt is active, or the account is halted. 409 (agents): the agent's paper account is halted.",23943 "action": "Cancels and reduce-only exits are still signed. The halt is lifted on the signer machine only."23944 },23945 "idempotency": {23946 "statuses": [23947 40023948 ],23949 "meaning": "A mutating call without a valid `Idempotency-Key` header (8 to 100 characters: letters, digits, `.` `_` `:` `-`).",23950 "action": "Send the header. One key per logical action; keep it for retries."23951 },23952 "idempotency_conflict": {23953 "statuses": [23954 40923955 ],23956 "meaning": "This Idempotency-Key (or `clientOrderId`) was already used with a DIFFERENT request, or belongs to another principal.",23957 "action": "A new action needs a new key. To retry the first action, send the first request again, byte for byte."23958 },23959 "idempotency_in_progress": {23960 "statuses": [23961 40923962 ],23963 "meaning": "The first call with this Idempotency-Key is still running, or just ended without an answer.",23964 "action": "Wait a second and send the same call again."23965 },23966 "inconsistent_prices": {23967 "statuses": [23968 42223969 ],23970 "meaning": "The stop-loss / take-profit are on the wrong side of the entry or of each other.",23971 "action": "A long: SL below entry, TP above. A short: the reverse."23972 },23973 "instrument_halted": {23974 "statuses": [23975 42223976 ],23977 "meaning": "The venue has halted this instrument.",23978 "action": "Nothing to do until the venue reopens it."23979 },23980 "instrument_mismatch": {23981 "statuses": [23982 42223983 ],23984 "meaning": "The account is on one venue and the instrument on another.",23985 "action": "Name the account of the instrument's venue."23986 },23987 "instrument_not_allowed": {23988 "statuses": [23989 42223990 ],23991 "meaning": "The instrument is not allowed by the account's authorization or policy.",23992 "action": "Trade an allowed instrument, or the owner widens the policy."23993 },23994 "instrument_reduce_only": {23995 "statuses": [23996 42223997 ],23998 "meaning": "The venue only accepts orders that reduce a position on this instrument.",23999 "action": "Send reduce-only orders."24000 },24001 "insufficient_collateral": {24002 "statuses": [24003 42224004 ],24005 "meaning": "Not enough free collateral on the account for this order.",24006 "action": "Send a smaller order, or the owner adds collateral to the account."24007 },24008 "insufficient_scope": {24009 "statuses": [24010 40324011 ],24012 "meaning": "The key does not hold the permission (scope) this operation needs. For POST /commands: the scope of the operation the command resolves to.",24013 "action": "Use a key that holds the scope named in `message`. Adding a scope to a key needs the owner's passkey."24014 },24015 "internal": {24016 "statuses": [24017 50024018 ],24019 "meaning": "The server failed. A mutating call may or may not have run.",24020 "action": "Send the same call again with the SAME Idempotency-Key: it either returns the stored answer or runs once. Do not create a new key for a retry."24021 },24022 "invalid_cursor": {24023 "statuses": [24024 40024025 ],24026 "meaning": "The `cursor` is not one a previous page of this list returned.",24027 "action": "Start again without a cursor; send a cursor with the same filters it came with."24028 },24029 "invalid_order": {24030 "statuses": [24031 400,24032 42224033 ],24034 "meaning": "The order is not well-formed for its type: a limit without `price`, a stop without `triggerPrice`, `reduceOnly` on spot, a research-mode order, a mandate or principal that is not the caller's.",24035 "action": "Fix the request; sending it again unchanged gives the same answer."24036 },24037 "ip_not_allowed": {24038 "statuses": [24039 40324040 ],24041 "meaning": "The key has an IP allow-list and the request came from another address.",24042 "action": "Call from an allowed address, or have the owner change the key's restrictions."24043 },24044 "key_limit_exceeded": {24045 "statuses": [24046 40324047 ],24048 "meaning": "The order is above the key's own notional limit (per order or per day), or cannot be valued so the limit cannot be checked.",24049 "action": "Send a smaller order; the limits are on the key (Developer → Keys)."24050 },24051 "kill_switch_active": {24052 "statuses": [24053 42324054 ],24055 "meaning": "The global kill switch is on: no new risk for anybody, on any venue, in any mode.",24056 "action": "Cancels and strictly reducing orders still pass. Only the owner releases it, with the passkey."24057 },24058 "leverage_exceeded": {24059 "statuses": [24060 42224061 ],24062 "meaning": "The leverage is above the authorized maximum (policy, mandate or venue).",24063 "action": "Lower it."24064 },24065 "leverage_mismatch": {24066 "statuses": [24067 42224068 ],24069 "meaning": "A live order names a leverage that is not the venue's current setting for the instrument.",24070 "action": "Send the order without `leverage`, or the owner changes the setting in the app."24071 },24072 "liquidation_too_close": {24073 "statuses": [24074 42224075 ],24076 "meaning": "The estimated liquidation price after the order is closer to the mark than the policy allows.",24077 "action": "Smaller size or lower leverage."24078 },24079 "live_not_available": {24080 "statuses": [24081 42224082 ],24083 "meaning": "A paper account can only be PAPER or READ_ONLY.",24084 "action": "Use a venue account for live."24085 },24086 "live_unavailable": {24087 "statuses": [24088 40924089 ],24090 "meaning": "This agent family cannot go live (the message says why).",24091 "action": "Run it on paper."24092 },24093 "mainnet_disabled": {24094 "statuses": [24095 40324096 ],24097 "meaning": "The server lock for new mainnet risk is closed (`SPW_DERIV_LIVE_MAINNET`).",24098 "action": "Paper works; cancels and reductions pass. Only the owner can change this, in the app, with the passkey."24099 },24100 "mandate_denied": {24101 "statuses": [24102 40324103 ],24104 "meaning": "The order is outside the mandate. `data.reasons` lists EVERY reason (codes of the mandate table, e.g. `ORDER_NOTIONAL_EXCEEDED`, `INSTRUMENT_NOT_ALLOWED`); `data.order` is the order, state REJECTED.",24105 "action": "Change the order to fit the mandate; a wider mandate is a new mandate approved by the owner."24106 },24107 "mandate_integrity": {24108 "statuses": [24109 40324110 ],24111 "meaning": "The stored mandate no longer hashes to what the owner's passkey approved. It is unusable and gets revoked.",24112 "action": "The owner approves a new mandate."24113 },24114 "mandate_mainnet_disabled": {24115 "statuses": [24116 40324117 ],24118 "meaning": "The server lock for mandates on mainnet is closed (`SPW_DERIV_MANDATE_MAINNET`).",24119 "action": "Paper works; cancels and reductions pass. Only the owner can change this, in the app, with the passkey."24120 },24121 "mandate_mismatch": {24122 "statuses": [24123 42224124 ],24125 "meaning": "The mandate was approved for another strategy version or another agent.",24126 "action": "The owner approves a mandate for this one."24127 },24128 "mandate_none": {24129 "statuses": [24130 42224131 ],24132 "meaning": "Live: no derivative mandate is in force at the signer for this venue account.",24133 "action": "The owner approves a live mandate with the passkey."24134 },24135 "mandate_not_approved": {24136 "statuses": [24137 40324138 ],24139 "meaning": "The mandate bound to this principal was never approved, or is no longer active.",24140 "action": "The owner approves a mandate and binds it."24141 },24142 "mandate_required": {24143 "statuses": [24144 403,24145 40924146 ],24147 "meaning": "403: an execution scope is inert on this key because no trading mandate is bound to it. 409 (agents): going live needs a mandate the owner approved for that agent.",24148 "action": "The owner creates and approves a mandate for the key (Settings → Risk → Trading mandates), then binds it to the key. See Mandates."24149 },24150 "mandate_unavailable": {24151 "statuses": [24152 50324153 ],24154 "meaning": "Live mandates are not available on this server (a server lock).",24155 "action": "Paper works. Only the owner can change this, in the app, with the passkey."24156 },24157 "mandate_wind_down": {24158 "statuses": [24159 42224160 ],24161 "meaning": "The mandate was revoked or has expired: for 24 h only cancels and reduce-only orders are placed.",24162 "action": "Reduce or close; new risk needs a new mandate."24163 },24164 "mark_index_divergence": {24165 "statuses": [24166 42224167 ],24168 "meaning": "Mark and index prices are further apart than the policy allows.",24169 "action": "Retry later."24170 },24171 "markets_unavailable": {24172 "statuses": [24173 50324174 ],24175 "meaning": "No market source at all could be read.",24176 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24177 },24178 "missing_balance": {24179 "statuses": [24180 42224181 ],24182 "meaning": "A percentage of a balance was asked and the balance could not be read.",24183 "action": "Retry, or name an absolute quantity."24184 },24185 "missing_reference_price": {24186 "statuses": [24187 42224188 ],24189 "meaning": "No USD reference price is available to express the fee cap.",24190 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24191 },24192 "mixed_credentials": {24193 "statuses": [24194 40324195 ],24196 "meaning": "The request carried an API key and a session cookie (or a stream ticket) together.",24197 "action": "Send exactly one credential. A script never sends the cookie."24198 },24199 "mode_read_only": {24200 "statuses": [24201 42224202 ],24203 "meaning": "The venue account is read-only: live trading was never authorized with the owner's passkey, or the authorization was revoked.",24204 "action": "The owner authorizes the account in Futures → Accounts."24205 },24206 "nft_bad_identifier": {24207 "statuses": [24208 40024209 ],24210 "meaning": "The address or token id is not well-formed for the network.",24211 "action": "Fix the request; sending it again unchanged gives the same answer."24212 },24213 "nft_budget_exhausted": {24214 "statuses": [24215 42924216 ],24217 "meaning": "The wallet's own request budget for a metered provider is spent for now.",24218 "action": "Retry later; do not poll."24219 },24220 "nft_disabled": {24221 "statuses": [24222 50324223 ],24224 "meaning": "The NFT module is switched off on this server.",24225 "action": "The server operator enables it."24226 },24227 "nft_not_found": {24228 "statuses": [24229 40424230 ],24231 "meaning": "The chain does not know this item.",24232 "action": "Check network, address and token id."24233 },24234 "nft_provider_bad_answer": {24235 "statuses": [24236 50224237 ],24238 "meaning": "A provider answered something that could not be interpreted.",24239 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24240 },24241 "nft_provider_disagreement": {24242 "statuses": [24243 50224244 ],24245 "meaning": "Sources disagree on a fact the answer needs.",24246 "action": "Read GET /nfts/market: each source is on its own row."24247 },24248 "nft_provider_method_unsupported": {24249 "statuses": [24250 50324251 ],24252 "meaning": "The provider cannot answer this kind of question for this network.",24253 "action": "Nothing to do."24254 },24255 "nft_provider_not_configured": {24256 "statuses": [24257 50324258 ],24259 "meaning": "The provider this call needs has no key on the server.",24260 "action": "The answer names the server variable; the operator sets it."24261 },24262 "nft_provider_rate_limited": {24263 "statuses": [24264 42924265 ],24266 "meaning": "A market-data provider is rate-limiting this wallet.",24267 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24268 },24269 "nft_provider_unavailable": {24270 "statuses": [24271 50324272 ],24273 "meaning": "A provider is down.",24274 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24275 },24276 "nft_unsupported_chain": {24277 "statuses": [24278 42224279 ],24280 "meaning": "No NFT adapter for this network.",24281 "action": "Use Solana or one of the EVM networks."24282 },24283 "nft_unsupported_standard": {24284 "statuses": [24285 42224286 ],24287 "meaning": "The contract is not an NFT standard this wallet reads.",24288 "action": "Nothing to do."24289 },24290 "no_account": {24291 "statuses": [24292 42224293 ],24294 "meaning": "No paper account (mode `paper`) or no authorized venue account (mode `live`) on this venue.",24295 "action": "The owner creates a paper account, or authorizes a venue account with the passkey, in Futures → Accounts."24296 },24297 "no_client_id_format": {24298 "statuses": [24299 42224300 ],24301 "meaning": "The venue has no client-order-id format this wallet can derive.",24302 "action": "Use a venue the wallet trades."24303 },24304 "no_instrument": {24305 "statuses": [24306 42224307 ],24308 "meaning": "The command names an asset no instrument of the catalogue matches (on that venue/network).",24309 "action": "Check the asset and the venue."24310 },24311 "no_liquidity": {24312 "statuses": [24313 50324314 ],24315 "meaning": "The book has no bid/ask from which to derive a price for a market order.",24316 "action": "Retry later, or send a limit order."24317 },24318 "no_orderbook": {24319 "statuses": [24320 42224321 ],24322 "meaning": "The venue has no order book (GMX is a liquidity pool; spot market data stores bars).",24323 "action": "Use GET /markets/{symbol} for the price."24324 },24325 "no_position": {24326 "statuses": [24327 42224328 ],24329 "meaning": "There is no open position to close or reduce on that instrument and account.",24330 "action": "Read GET /positions first."24331 },24332 "no_report": {24333 "statuses": [24334 40924335 ],24336 "meaning": "The strategy version has no backtest report.",24337 "action": "Run POST /strategies/{id}/backtest and wait for the job."24338 },24339 "no_strategy": {24340 "statuses": [24341 40924342 ],24343 "meaning": "The agent has no approved strategy version.",24344 "action": "Register one with POST /strategies and let its backtest finish."24345 },24346 "not_a_private_market": {24347 "statuses": [24348 40424349 ],24350 "meaning": "The instrument exists and is not a private-company contract.",24351 "action": "Read it with GET /markets/{symbol}."24352 },24353 "not_found": {24354 "statuses": [24355 40424356 ],24357 "meaning": "Agents: no such agent, strategy version or job (or the key is restricted away from it). Any other path: not an operation of this API.",24358 "action": "Check the id; list with GET /agents or GET /strategies. For a path, see the operation list."24359 },24360 "not_reducing": {24361 "statuses": [24362 42224363 ],24364 "meaning": "The order would not strictly reduce an existing position: nothing was placed.",24365 "action": "Read GET /positions; the position may already be closed."24366 },24367 "not_your_order": {24368 "statuses": [24369 40324370 ],24371 "meaning": "A key cancels its own orders only.",24372 "action": "The owner cancels anything, in the app."24373 },24374 "order_notional_exceeded": {24375 "statuses": [24376 42224377 ],24378 "meaning": "The order is above the account policy's notional per order.",24379 "action": "Send a smaller order."24380 },24381 "order_rate_day": {24382 "statuses": [24383 42224384 ],24385 "meaning": "Too many orders on this account today (account policy).",24386 "action": "Wait for the next day; Only the owner can change this, in the app, with the passkey."24387 },24388 "order_rate_minute": {24389 "statuses": [24390 42224391 ],24392 "meaning": "Too many orders on this account in the last minute (account policy).",24393 "action": "Slow down."24394 },24395 "other_version": {24396 "statuses": [24397 40924398 ],24399 "meaning": "Only the most recent version of an agent can be started (or: the agent runs another approved version).",24400 "action": "Register the version again, or start the current one."24401 },24402 "owner_required": {24403 "statuses": [24404 40324405 ],24406 "meaning": "Only the owner can do this: create a spot agent (its vault is derived by the signer), let the supervisor act on live agents.",24407 "action": "Do it in the app."24408 },24409 "owner_session_required": {24410 "statuses": [24411 40324412 ],24413 "meaning": "A spot order (a swap proposal) is prepared and withdrawn in the owner's session, not with a key.",24414 "action": "Do it in the app."24415 },24416 "paper_unsupported": {24417 "statuses": [24418 42224419 ],24420 "meaning": "The venue has no order book, so the paper engine cannot fill against it (GMX).",24421 "action": "Paper-trade on Hyperliquid."24422 },24423 "parse_error": {24424 "statuses": [24425 40024426 ],24427 "meaning": "The text is not a sentence of the command grammar. `data.code` is the grammar's own code and `data.token` the index of the offending token.",24428 "action": "Fix the line; the grammar is in the Commands section."24429 },24430 "position_not_attributable": {24431 "statuses": [24432 40324433 ],24434 "meaning": "A key or an agent closes only the part of a position its own fills opened; this position (or that share of it) was opened by the owner or another principal.",24435 "action": "Close only what the key opened; the owner closes anything."24436 },24437 "position_notional_exceeded": {24438 "statuses": [24439 42224440 ],24441 "meaning": "The resulting position exceeds the account policy for the instrument.",24442 "action": "Send a smaller order."24443 },24444 "price_deviation": {24445 "statuses": [24446 42224447 ],24448 "meaning": "The price is further from the mark (or the trigger) than the account policy allows (`maxDeviationBps`; GET /risk shows the policy of each account).",24449 "action": "Price the order closer to the mark. The mark is in GET /markets/{symbol}."24450 },24451 "price_not_on_tick": {24452 "statuses": [24453 42224454 ],24455 "meaning": "The price is not a multiple of the instrument's `tickSize` (or has too many decimals for the venue).",24456 "action": "Round the price to `tickSize` — as a decimal STRING, not a float."24457 },24458 "price_required": {24459 "statuses": [24460 42224461 ],24462 "meaning": "A limit order needs `price` (a market order needs a worst acceptable price, which the server derives).",24463 "action": "Add `price`."24464 },24465 "rate_limited": {24466 "statuses": [24467 42924468 ],24469 "meaning": "More calls than the key's per-minute limit in the current one-minute window.",24470 "action": "Wait `Retry-After` seconds (also `RateLimit-Reset`), then go on. Both SDKs do this for you."24471 },24472 "read_only_mode": {24473 "statuses": [24474 42324475 ],24476 "meaning": "Read-only mode is on: only cancels pass (or: an agent in research mode places no order).",24477 "action": "Cancel if needed; the owner releases it with the passkey."24478 },24479 "reduce_only_would_flip": {24480 "statuses": [24481 42224482 ],24483 "meaning": "A reduce-only order is larger than the position.",24484 "action": "Size it at most to the position; POST /positions/{id}/close does it for you."24485 },24486 "reduce_only_would_increase": {24487 "statuses": [24488 42224489 ],24490 "meaning": "A reduce-only order would open or increase a position.",24491 "action": "Check the side and the position."24492 },24493 "restricted": {24494 "statuses": [24495 40324496 ],24497 "meaning": "The key's restrictions (venues, instruments, networks) exclude what the call names.",24498 "action": "Use a venue, instrument or network the key is allowed on, or have the owner widen the key (passkey)."24499 },24500 "risk_denied": {24501 "statuses": [24502 42224503 ],24504 "meaning": "The independent risk engine refused the order. `data.failed` lists the failed check ids and `data.checks` gives, for each, what was observed and the limit; `data.order` is the order, state REJECTED.",24505 "action": "Read `data.checks`. Frequent: a limit never configured on the live book, stale prices, an order too large for the collateral. See the risk checks table."24506 },24507 "service_unavailable": {24508 "statuses": [24509 50324510 ],24511 "meaning": "No network / no position source could be read.",24512 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24513 },24514 "signer_unreachable": {24515 "statuses": [24516 50324517 ],24518 "meaning": "The isolated signer cannot be reached: balances, the portfolio and anything that needs a signature are unavailable.",24519 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key. If it lasts, the owner checks the signer machine."24520 },24521 "size_not_on_lot": {24522 "statuses": [24523 42224524 ],24525 "meaning": "The size is not a multiple of `lotSize`.",24526 "action": "Round the size down to `lotSize`, or send `notional` and let the server size it."24527 },24528 "spot_buy_needs_quote_amount": {24529 "statuses": [24530 42224531 ],24532 "meaning": "A swap is exact-input: a spot BUY names the amount of the quote asset to spend.",24533 "action": "Send `notional` (not `size`) for a spot buy, or the command `BUY ETH 100 USDC`."24534 },24535 "spot_execution_requires_agent_vault": {24536 "statuses": [24537 40324538 ],24539 "meaning": "An API key cannot place a spot order: spot execution for keys and agents exists only through an agent vault under a spot mandate.",24540 "action": "Trade perpetuals with the key, or let a spot agent do it."24541 },24542 "spot_market_only": {24543 "statuses": [24544 42224545 ],24546 "meaning": "A spot order here is an immediate swap bounded by `slippageBps`: resting and trigger orders do not exist for spot.",24547 "action": "Send `type: \"market\"`."24548 },24549 "spot_paper_not_available": {24550 "statuses": [24551 42224552 ],24553 "meaning": "There is no paper spot engine for the owner.",24554 "action": "Use mode `live` (a real swap, approved with the passkey); paper spot exists for agents only."24555 },24556 "spot_via_swap_screen": {24557 "statuses": [24558 42224559 ],24560 "meaning": "An owner's spot order is a swap proposal approved with the passkey.",24561 "action": "Prepare it in the Swap screen."24562 },24563 "stale_book": {24564 "statuses": [24565 42224566 ],24567 "meaning": "The order book is older than the account policy allows.",24568 "action": "Retry in a few seconds."24569 },24570 "stale_data": {24571 "statuses": [24572 50324573 ],24574 "meaning": "The price or book needed is older than its freshness bound (e.g. a notional cannot be turned into a size at a stale mark).",24575 "action": "Retry in a few seconds. A limit order sized with `size` names its own price and does not depend on the mark."24576 },24577 "stale_request": {24578 "statuses": [24579 40024580 ],24581 "meaning": "`X-SPW-Timestamp` was sent and is more than 300 s from the server clock (or is not Unix seconds).",24582 "action": "Fix the client clock, or do not send the header: it is optional."24583 },24584 "stale_ticker": {24585 "statuses": [24586 42224587 ],24588 "meaning": "The venue ticker is older than the account policy allows (`maxDataAgeMs`).",24589 "action": "Retry in a few seconds."24590 },24591 "strategy_not_installed": {24592 "statuses": [24593 40924594 ],24595 "meaning": "No strategy of this template is installed in the laboratory. Nothing was created (no placeholder is substituted).",24596 "action": "See `strategyInstalled` in GET /agents/templates."24597 },24598 "swap_flow_failed": {24599 "statuses": [24600 50224601 ],24602 "meaning": "The swap flow returned no proposal.",24603 "action": "Retry; if it lasts, prepare the swap in the app to see the reason."24604 },24605 "swap_not_enabled": {24606 "statuses": [24607 42224608 ],24609 "meaning": "The wallet does not execute swaps on this network.",24610 "action": "Use a network where swaps are enabled."24611 },24612 "total_loss_exceeded": {24613 "statuses": [24614 42224615 ],24616 "meaning": "The account's total loss limit is reached.",24617 "action": "Reductions pass; Only the owner can change this, in the app, with the passkey."24618 },24619 "trigger_required": {24620 "statuses": [24621 42224622 ],24623 "meaning": "A stop or take-profit order needs `triggerPrice`.",24624 "action": "Add `triggerPrice`."24625 },24626 "unauthenticated": {24627 "statuses": [24628 40124629 ],24630 "meaning": "No credential, or a key that is malformed, unknown, wrong, expired or revoked. One answer for all of them, on purpose.",24631 "action": "Check the `Authorization: Bearer spw_live_…` header and the key's status and expiry in Developer → Keys. Ten failures a minute from one address lead to `auth_throttled`."24632 },24633 "universe_mismatch": {24634 "statuses": [24635 42224636 ],24637 "meaning": "A fixed-universe strategy runs on its exact universe; the agent's differs.",24638 "action": "Create the agent with the universe the message lists."24639 },24640 "unknown_account": {24641 "statuses": [24642 40424643 ],24644 "meaning": "No paper account / authorized venue account with this `accountId` on the venue.",24645 "action": "Omit `accountId` when the wallet has one account on the venue; else take it from GET /portfolio (`accounts`)."24646 },24647 "unknown_company": {24648 "statuses": [24649 40424650 ],24651 "meaning": "No reviewed private-company contract under this slug.",24652 "action": "Take slugs from GET /private-markets (`companies`)."24653 },24654 "unknown_instrument": {24655 "statuses": [24656 404,24657 422,24658 50324659 ],24660 "meaning": "404: the venue does not list this instrument. 422: an instrument the order path cannot use (not in the pinned table of the venue). 503: the venue could not be read to find out.",24661 "action": "Take ids from GET /markets (`venue:symbol`). On 503 retry later."24662 },24663 "unknown_market": {24664 "statuses": [24665 40424666 ],24667 "meaning": "A spot symbol without data, or a bare symbol nothing answers to.",24668 "action": "Take the id from GET /markets."24669 },24670 "unknown_network": {24671 "statuses": [24672 40424673 ],24674 "meaning": "The network id is not one of the wallet's.",24675 "action": "Take network ids from GET /balances."24676 },24677 "unknown_nft": {24678 "statuses": [24679 40424680 ],24681 "meaning": "This NFT is not in the wallet's inventory.",24682 "action": "Take `key` from GET /nfts. For any other item use GET /nfts/market."24683 },24684 "unknown_order": {24685 "statuses": [24686 40424687 ],24688 "meaning": "No order with this id (or none this key may see).",24689 "action": "Take ids from GET /orders or from the answer of POST /orders."24690 },24691 "unknown_position": {24692 "statuses": [24693 40424694 ],24695 "meaning": "The position id is not of the form GET /positions returns, or names nothing.",24696 "action": "Take `id` from GET /positions and URL-encode it."24697 },24698 "unknown_private_market": {24699 "statuses": [24700 40424701 ],24702 "meaning": "This id is not a private-company market known to the venues the wallet reads.",24703 "action": "Take ids from GET /private-markets."24704 },24705 "unknown_underlying": {24706 "statuses": [24707 40424708 ],24709 "meaning": "No perpetual is mapped to this underlying in the comparator.",24710 "action": "Use an underlying that GET /markets lists as a `base`."24711 },24712 "unknown_venue": {24713 "statuses": [24714 40424715 ],24716 "meaning": "The venue id is not one this wallet knows (`hyperliquid`, `gmx`, `dydx`, `edgex`, `spot`).",24717 "action": "List the ids with GET /markets."24718 },24719 "unsupported_asset": {24720 "statuses": [24721 42224722 ],24723 "meaning": "The base or quote asset is not exactly one asset of the wallet registry on that network.",24724 "action": "Name assets the wallet lists in GET /balances."24725 },24726 "unsupported_interval": {24727 "statuses": [24728 42224729 ],24730 "meaning": "Spot market data does not store this candle interval.",24731 "action": "Use one of the intervals the message lists."24732 },24733 "venue_not_wired": {24734 "statuses": [24735 42224736 ],24737 "meaning": "Live orders on this venue are not placed through this endpoint (GMX: prepared in the app, one passkey per order). This endpoint places live orders on Hyperliquid only.",24738 "action": "Use `hyperliquid:*` for live orders through the API."24739 },24740 "venue_rate_limited": {24741 "statuses": [24742 50324743 ],24744 "meaning": "The venue is rate-limiting this wallet.",24745 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24746 },24747 "venue_rejected": {24748 "statuses": [24749 42224750 ],24751 "meaning": "The venue itself refused (the message quotes it): the order, a cancel, a margin mode it does not offer.",24752 "action": "Read `message`; fix the order."24753 },24754 "venue_restricted": {24755 "statuses": [24756 40324757 ],24758 "meaning": "The venue is never tradable from this wallet (dYdX and edgeX: market data only, a jurisdiction restriction).",24759 "action": "Read its data; trade on Hyperliquid."24760 },24761 "venue_timeout": {24762 "statuses": [24763 50324764 ],24765 "meaning": "The venue did not answer in time and no earlier value can stand in.",24766 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24767 },24768 "venue_unavailable": {24769 "statuses": [24770 50324771 ],24772 "meaning": "The venue (or the signer, for the wallet address) could not be read, so no honest answer exists.",24773 "action": "Nothing was done. Retry with backoff; a mutating call keeps the same Idempotency-Key."24774 },24775 "wrong_kind": {24776 "statuses": [24777 40924778 ],24779 "meaning": "The strategy and the agent are of different kinds (spot / perp), or the operation does not apply to this kind of agent.",24780 "action": "Match the kinds."24781 },24782 "zero_size": {24783 "statuses": [24784 42224785 ],24786 "meaning": "The quantity resolves to zero.",24787 "action": "Raise the amount."24788 }24789 },24790 "x-spw-risk-checks": [24791 "input_valid",24792 "read_only",24793 "kill_switch",24794 "reduce_only_valid",24795 "venue_allowed",24796 "instrument_allowed",24797 "instrument_status",24798 "signer_status",24799 "venue_connection",24800 "price_freshness",24801 "price_consistency",24802 "order_notional",24803 "daily_notional",24804 "order_rate_minute",24805 "order_rate_hour",24806 "order_rate_day",24807 "position_size",24808 "order_leverage",24809 "account_leverage",24810 "gross_exposure",24811 "net_exposure",24812 "asset_exposure",24813 "venue_exposure",24814 "collateral_concentration",24815 "daily_loss",24816 "total_loss",24817 "drawdown",24818 "liquidation_distance",24819 "slippage",24820 "min_liquidity",24821 "context_complete"24822 ],24823 "x-spw-not-found": {24824 "status": 404,24825 "error": "not_found"24826 },24827 "x-spw-webhook-events": [24828 {24829 "event": "key.revoked",24830 "emitted": true,24831 "description": "an API key was revoked (or replaced by a rotation)",24832 "payload": "{ keyId, name, reason }"24833 },24834 {24835 "event": "risk.kill_switch",24836 "emitted": true,24837 "description": "the emergency halt of the signer was triggered (source \"signer\"), or the global kill switch of the risk engine was engaged or released (source \"risk_engine\")",24838 "payload": "{ source: \"signer\", halted: true } | { source: \"risk_engine\", engaged, by, reason }"24839 },24840 {24841 "event": "agent.updated",24842 "emitted": true,24843 "description": "an agent was started, paused or stopped (by the owner, an API key or the risk-management agent)",24844 "payload": "{ agentId, kind, state, mode }"24845 },24846 {24847 "event": "risk.proposal",24848 "emitted": true,24849 "description": "the risk-management agent proposes a reduction or a pause, or acted (paused an agent, engaged the kill switch)",24850 "payload": "{ supervisorId, agentId, mode, action, code, acted, message, metrics }"24851 },24852 {24853 "event": "order.updated",24854 "emitted": true,24855 "description": "an order changed state: one event per transition of the unified order state machine, for every principal, mode and venue",24856 "payload": "{ orderId, mode, venue, instrument, status, previous, event, reason, seq, principal, mandateId }"24857 }24858 ]24859}24860