Superior Trade Core

WRITE (real funds prerequisite — provisions the Hyperliquid signing-agent wallet and signs on-chain approvals (referrer, builder fee, agent wallet); requires Steward confirmation before the call). address is the trading-account wallet from ListTradingAccounts — other wallets are rejected. Body-less POST (the literal {} body is the 411 workaround). After bootstrap verify readiness with GetAccountExchangeStatus (exchange hyperliquid) before any Hyperliquid money operation. Tool-specific errors beyond the shared model: 404 not owned, 502 (report the exact message; do not blind-retry).

WRITE (real funds prerequisite — enables Polymarket trading for a wallet; requires Steward confirmation). Body-less POST — the literal {} body is the 411 workaround. address MUST be a trading-account wallet from ListTradingAccounts — other wallets are rejected. The response is onboarding guidance plus the accepted Polygon deposit asset (native Polygon USDC 0x3c499c542cef5e3811e1192ce70d8cc03d5c3359, 6 decimals) and gasless true. The response is guidance, NOT a deposit address. After bootstrap ALWAYS verify readiness with GetAccountExchangeStatus (exchange polymarket) and proceed only when onboarding.ready is true. Tool-specific errors beyond the shared model: 404 not owned, 502 (report the exact message; do not blind-retry).

WRITE (real funds — action 'start' begins live trading with real money and requires explicit Steward confirmation with the real-money warning PLUS the mandatory pre-start checklist; 'stop' halts a running deployment and needs no money gate). start requires: status pending or stopped, credentials stored, venue readiness passing, and valid instrument_ids — otherwise a 400/409 explains what is missing; resolve it rather than retrying. A successful start means the runtime is provisioning, NOT that trading has begun — verify via logs. PRE-START CHECKLIST (mandatory, no skipped items): (1) backtest reviewed with non-zero fills; (2) GetAccountExchangeStatus ready true for the venue; (3) credentials stored on an owned, ready wallet; (4) market end_date beyond the strategy horizon; (5) current exposure reviewed via the public positions read when relevant. Use action 'stop' and a nonexistent id on probe paths — NEVER probe with action=start against a real id. Errors beyond the shared model: 400 (invalid transition / missing credentials), 409 (not ready), 404.

WRITE (real funds pathway — plans a live-trading deployment; requires Steward confirmation). deployment.code is the Nautilus strategy source; deployment.config is the strategy config object. Venue binding lives in config: Polymarket leads to config.venue 'polymarket' with an instrument_id formed as the CLOB token id followed by '.POLYMARKET' (the CLOB token id from the market's public token mapping — NEVER a slug or condition id) and region 'london'; Lighter leads to config.venue 'lighter' with an instrument_id formed as the venue symbol followed by '.LIGHTER' (example 'BTC-PERP.LIGHTER') and region 'tokyo'. Returns 202 with status 'starting' when planned; 409 'blocked' with a reason when runtime artifacts are not ready — report the reason verbatim, do not retry blindly. The deployment is NOT live yet: credentials plus start (PATCH status) come next. Errors beyond the shared model: 400 validation_failed, 409 blocked (report the reason verbatim and resolve it).

WRITE (real funds adjacent — creates a new trading account and mints a Superior-managed Privy wallet; burns an irreplaceable account slot; requires explicit Steward confirmation before the call). User has 3 Free + 6 Pro account slots; a well-formed call consumes one slot with no delete API. Optional name parameter is the display label only. Returns id, name, wallet_address, hyperliquid_wallet_address, polymarket_wallet_address, and created_at. Tool-specific errors beyond the shared model: 400 validation_failed.

WRITE (real funds adjacent — soft-delete removes the deployment record WITHOUT closing venue positions; requires Steward confirmation). A running deployment MUST be STOPPED first (SuperiorTrade_ControlNautilusDeployment action='stop'). Pre-delete requirement: deployment must be STOPPED; on-call discipline: check exposure first and offer exit-all (SuperiorTrade_ExitPolymarketPortfolio or SuperiorTrade_ExitHyperliquidPortfolio) when positions remain. The 'still running' 400 is the hard-stop signal — resolve before retry. NEVER probe with a real id — the delete is a soft-delete that removes the record and does NOT close venue positions. Tool-specific errors beyond the shared model: 400 (still running), 404.

Check account exchange readiness status via GET /v3/account/{address}/status/{exchange}. Returns ready flag, next_action, and blocked_reason if any. Two bindings: address (positional {0}) and exchange (positional {1}, enum: hyperliquid | polymarket | lighter | binance). Use this as the authoritative readiness gate before any per-venue money operation: confirm status ready true before bootstrap/deposit/withdraw/order/deployment start. Tool-specific errors beyond the shared model: 404 wallet not owned.

Retrieve historical deployment session records via GET /v2/deployment-history. Each record covers one session from start until stop/delete, including PnL and fills — the post-trade review surface for 'how did my bot do'. All timestamps UTC. Present per-session PnL and fills honestly — never smooth over losing sessions; paginate with next_cursor when the Steward wants more. The path is the BARE /v2/deployment-history with NO bindings (BACKPORTED 2026-08-04 D2: both query filters were OPTIONAL, and this wrapper cannot omit query placeholders. Registered with the BARE base path, NO bindings, and both filters REMOVED from the schema. Accepted v1 trade-off: the wallet_address / deployment_id filters are unavailable. Do NOT re-add them without re-testing the omission path). Tool-specific errors beyond the shared model: 401 (per shared model).

Retrieve logs for a Nautilus deployment via GET /v3/deployment/{id}/logs. Returns timestamped log entries with severity levels. Heartbeat messages are normal, not errors. Tool-specific errors beyond the shared model: 404. Use a nonexistent id (e.g. 00000000-0000-0000-0000-000000000000) on probe paths to exercise the {0} path binding without touching a real deployment.

List Nautilus deployments via GET /v3/deployment. Returns items array with deployment summaries and a next_cursor pagination token. Empty items on a fresh account is normal, not an error. Tool-specific errors beyond the shared model: 401 (per shared model).

List all trading accounts via GET /v3/account. Returns items array with account details and pagination cursor.

WRITE (real funds prerequisite — records the Lighter account index created by the FIRST credited CCTP deposit and approves the Superior-managed Lighter API key, index 4; explicit Steward confirmation before the call). Call ONLY after the first deposit has credited (readiness 'account_created') or when account_ready is true but api_key_ready is false. address is the Superior-managed Privy wallet that owns the Lighter account. After success, poll SuperiorTrade_GetAccountExchangeStatus about every 15 seconds with a 10-minute budget until status 'ready'. On 'key_provisioning_unknown' STOP: freeze all money operations, tell the Steward it needs manual review, NEVER rotate keys or retry onboarding to force it. Body-less POST (411 workaround: literal {} body). Tool-specific errors beyond the shared model: 404 (feature disabled / wallet not owned), 409 (not yet in an onboardable state), 502.

Rename a trading account via PATCH /v3/account/{address}. Updates the human-readable display label only — no effect on wallet_address or any venue state. address is the trading-account wallet owned by the authenticated user (0x + 40 hex, from ListTradingAccounts). name is the new display label. Tool-specific errors beyond the shared model: 400 validation_failed, 404 wallet not owned. NEVER probe with an address from the Steward's account list — a 200 renames one of the Steward's real accounts.

WRITE (real funds gate — storing credentials enables REAL-MONEY trading for this deployment; requires Steward confirmation with the real-money warning: 'Storing credentials enables REAL-MONEY trading for this deployment. Proceed?'). wallet_address is an account wallet selected from the authenticated user's account list (pattern 0x plus 40 hex). Raw private keys are NEVER accepted; the platform signs server-side. The wallet must be venue-ready — check SuperiorTrade_GetAccountExchangeStatus first. Errors beyond the shared model: 400 (invalid address), 403 (wallet not owned), 404.

Update deployment settings via PATCH /v2/deployment/{id}. Currently supports renaming (name, 1-255 characters, trimmed) and scheduling an automatic stop (alive_until, ISO-8601 date-time WITH timezone; set null to clear). alive_until is a real safety lever: a live bot the Steward wants time-boxed gets a hard stop even if nobody is watching. Confirm the resolved stop time back in the Steward's local timezone. Does NOT start/stop the bot (that is SuperiorTrade_ControlDeployment in the Algo Strategist skill) and does not change config or code. BACKPORTED 2026-08-04 D6: name is REQUIRED alongside id (the wrapper only strips the LAST unsupplied body pair, so an alive_until-only update emits a broken comma). Callers read the current name via GetDeployment and pass it back. Tool-specific errors beyond the shared model: 400 validation_failed, 404.