Superior Trade Terminal

Bootstrap Hyperliquid account setup via POST /v3/account/{address}/hyperliquid. Initializes the trading account and returns id, status, and address.

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

Cancel a bracket order via DELETE /v2/bracket/{id}. Cancels the bracket's open orders (tolerating ones already filled or gone), market-closes any open position reduce-only, marks the bracket 'cancelled', and frees its wallet. WRITE - real funds when the entry has FILLED (cancelling then MARKET-CLOSES the open position immediately, reduce-only; warn explicitly and REQUIRE Steward confirmation before calling). Fetch current state via GetBracketOrder first: status 'resting' needs plain confirmation; status 'filled' needs the explicit MARKET-CLOSE warning plus confirmation. The API has no amend - time-boxing an existing bracket means cancel then re-place with alive_until, confirming both actions. Errors: 409 bracket_not_active (already in a terminal state - report its actual status instead of retrying), 404 (not found or not owned).

Check historical candle data availability via GET /v2/backtesting-data/{exchange}?pair={pair}&timeframe={timeframe}. Returns available flag, pair, timeframe, date range, and candle count.

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 polymarket ready true; (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. Errors beyond the shared model: 400 (invalid transition / missing credentials), 409 (not ready), 404.

Start or stop a paper deployment via PUT \/v2\/paper-deployment\/{id}\/status. Action 'start' begins paper trading from pending\/stopped; 'stop' halts it from running. alive_until (optional, ISO-8601 with timezone) is applied when starting.

WRITE (real funds - moves native USDC via CCTP to the Lighter account; explicit Steward confirmation with source chain + amount + payer + owner\/beneficiary summary). The intent address the API returns is what the payer funds DIRECTLY with native USDC on source_chain - funds move via CCTP and bypass Superior balances entirely. Show the returned intent address EXACTLY; never invent or truncate one. owner_address is the Superior-managed Privy wallet CREDITED on Lighter; optional source_address is the external payer (paying does NOT make it the owner). source_chain: arbitrum, base, or avalanche. amount: native USDC decimal string, minimum 5, up to 6 decimals. IDEMPOTENCY: idempotency_key (min 8 chars) sent as the Idempotency-Key REQUEST HEADER by the platform wrapper; generate once per deposit attempt and REUSE the SAME key when retrying that same attempt; a new key means a new deposit. The key rides in headersParameters ONLY and is never a body field. Errors: 400 (validation\/precision), 404 (feature disabled), 409 (active deposit exists \/ idempotency key reused with different input), 502.

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).

Create AND start a credential-free paper deployment. WRITE (simulated funds only — server forces dry_run true; zero credentials, zero real funds). Only ONE paper deployment may be active per user; a 409 means another paper deployment is active — run SuperiorTrade_ListPaperDeployments status 'running' first. config is a standard Freqtrade config (exchange block, nested pair_whitelist, numeric stake_amount); dry_run_wallet is a map of simulated balances with STRING values (e.g. {'USDC': '1000'}). code gets the full sanitize pass: markdown fences stripped, IStrategy inheritance, PascalCase class ending in 'Strategy', TA-Lib multi-output destructuring. alive_until (ISO-8601 with timezone) schedules an auto-stop — suggest ~7 days. Errors: 400 validation_failed / invalid_code, 409 (another paper deployment active), 401.

WRITE (simulated funds only — plans a filled-tick backtest job; NOT on the real-money gate list, no Steward money confirmation required). NautilusTrader TradeTick replay — fills come from real historical trades, not candles. tenantId is a stable per-Steward identifier — pick one and REUSE it for every backtest. marketSlugs are exact slugs from SuperiorTrade_SearchPolymarketMarkets (min 1), never invented. timerange holds ISO-8601 date-times INSIDE the candidate's coverage window. venueProfile is 'polymarket-london'. strategySource is inline Nautilus Python (max 262144 chars) — when provided the runner executes it; drive logic from on_trade_tick, since quote-only strategies get ZERO callbacks in replay. strategyConfig field names must match the strategy's StrategyConfig class. Infrastructure fields (datasetRef, datasetPrefix, resultPrefix, resultBucket, codeRef, configRef) are deliberately NOT exposed — never invent them. Errors beyond the shared model: 409 (coverage missing for a slug — re-run search and adjust; never blind-retry), 400 validation_failed.

Create a new trading account via POST /v3/account. Returns id, name, wallet_address, hyperliquid_wallet_address, polymarket_wallet_address, and created_at.

WRITE (real funds adjacent — removes the deployment record WITHOUT closing venue positions; requires Steward confirmation). A running deployment must be STOPPED first (SuperiorTrade_ControlNautilusDeployment 'stop'). Soft-delete: removes the record only. It does NOT close venue positions — check exposure first and offer exit-all (SuperiorTrade_ExitPolymarketPortfolio) when positions remain. Errors beyond the shared model: 400 (still running), 404.

Deposit USDC to Hyperliquid from an external wallet via POST \/v2\/portfolio\/hyperliquid\/deposit. chain 'arbitrum' (or 'arbitrum_one' \/ 'arbitrum-one' \/ '42161') is the source chain alias; asset_address is the native USDC token address on Arbitrum One: 0xaf88d065e77c8cC2239327C5EDb3A432268e5831. amount is a USDC decimal string, minimum 5 USDC, precision limited to 6 decimals. from is optional: must be one of the authenticated user's trading wallets; when omitted, the default main trading wallet is used. Returns tx_hash, status, and amount.

WRITE (real funds — moves real USDC into Polymarket as pUSD; requires explicit Steward confirmation with a summary block: Chain, Asset, Amount, From, Route). Routes: Polygon native USDC / USDC.e wrap 1:1 via the official Collateral Onramp (route 'direct-onramp'); 'relay' forces Relay exact-input routing; 'auto' lets the API choose. Arbitrum USDC ALWAYS goes via Relay. Relay routes are exact-INPUT: the pUSD received can be slightly lower than the amount after Relay fees or price impact — warn the Steward before any Relay-routed deposit. Minimum 5 USDC, up to 6 decimals, amount as a decimal string. from is REQUIRED and must be the Superior wallet holding the source-chain USDC (from ListTradingAccounts). There are NO Polymarket withdrawals in the API — never promise one. Verify arrival by re-checking SuperiorTrade_GetAccountExchangeStatus balance (poll about every 20 seconds, budget 5 minutes) and report the actual balance change. Errors beyond the shared model: 400 (validation / unsupported asset / insufficient balance), 403 (wallet not owned), 502 (route failed).

Close all positions and orders for a deployment via POST /v2/portfolio/hyperliquid/exit. Returns orders_cancelled, positions_closed, and transferred_to_main amounts.

WRITE (real funds — the portfolio kill-switch: cancels ALL open CLOB orders and SELLS ALL outcome-token positions for the wallet; requires DOUBLE confirmation: first show current positions via the public data-api read, https://data-api.polymarket.com/positions?user=WALLET via runtime HTTP, no auth, then get an explicit 'exit all'). There is NO per-deployment exit on v3 — this is portfolio-level and affects every position regardless of which deployment or manual order opened it. Funds land in the Polymarket wallet — no chain withdrawal exists. Errors beyond the shared model: 400, 502.

Check account exchange readiness status via GET /v3/account/{address}/status/{exchange}. Returns ready flag, next_action, and blocked_reason if any.

Surfaces live ranked market intelligence via GET /v2/intelligence/scan. Supports buckets (squeeze, stealth, coiled, basis) and categories (alts, tradfi, both). Returns computed_at timestamp and bucketed results.

Get one bracket order with live enrichment via GET /v2/bracket/{id}. Single record (same shape as a ListBracketOrders item; status enum 'resting' | 'filled' | 'closed' | 'cancelled' | 'expired'). Every status claim to the Steward MUST come from this call or ListBracketOrders in the current turn - never narrate fills from memory. Errors: 404 (not found or not owned - ownership isolation returns the same shape either way). If enrichment fell back to stored state, say "as of last sync".

Get a single copy trader's full profile card via GET /v2/copy-trading/traders/{wallet}. Read-only, no auth required. Tool-specific errors: 404.

Retrieve deployment history via GET \/v2\/deployment-history. Optional filters via wallet_address and deployment_id.

Check available balance and collateral via GET /v3/portfolio/lighter/balance?owner_address={owner_address}. Pre-deposit accounts return zero with needs_deposit — that is a state, not an error. Tool-specific errors: 404.

READ-only — reconcile the persisted deposit record against chain state but NEVER submits funds. The polling surface after CreateLighterDeposit: poll about every 30 seconds with a 30-minute budget (CCTP is cross-chain). Tool-specific errors: 404.

Poll withdrawal status via GET /v3/portfolio/lighter/withdraw/{withdrawalId}?owner_address={owner_address} — reconciles the persisted record against chain state. The persisted status is the only truth about an ambiguous withdrawal. Tool-specific errors: 404.

Retrieve logs for a Nautilus deployment via GET /v3/deployment/{id}/logs. Returns timestamped log entries with severity levels.

Retrieve per-pair intelligence setup card via GET /v2/intelligence/setup/{pair}. Returns a structured snapshot with best_fit bucket, timeframe, score, liquidity tier, and supporting metrics. Use this to drill into a specific pair after a scan.

Retrieve paper deployment details via GET /v2/paper-deployment/{id}. Returns id, status, config, code, and name.

READ. Returns the persisted backtest record — the planned request plus current status metadata. Errors beyond the shared model: 404.

Retrieve logs for a v3 Polymarket backtest via GET /v3/backtest/{id}/logs. Returns {items, nextCursor}. Errors: 401, 404.

READ. Returns 202 while the result is still uploading — retry after a short wait. Then the result JSON: balances in pUSD, total_pnl and return, orders and fills, dataset_provenance, and trades capped at the FIRST 50 fills. Win rate, Sharpe, and drawdown are NOT computed server-side — derive them from trades/positions when the Steward asks, and say the trades list is capped when relevant. ZERO FILLS means the strategy never traded — do NOT offer deployment from a zero-fill backtest. Errors beyond the shared model: 202 (still uploading — wait briefly and retry), 404.

READ. Status progression: pending leads to running leads to completed or failed. Typical runs finish in 1-30 seconds; poll about every 5 seconds with a 5-minute budget, then stop and check logs. Errors beyond the shared model: 404.

List the Steward's bracket orders, newest first, with live-enriched status via GET /v2/bracket. If live enrichment fails upstream, rows fall back to stored state - present status as of the response, never extrapolate fills. Also the way to find which trading-account wallets are currently occupied by brackets. Running DEPLOYMENTS also occupy wallets but are not visible to this skill - the API's 409 wallet_occupied response is the authority on occupancy, not this list alone. Empty items array on a fresh account is normal, not an error. Errors: 401.

List copy traders via GET /v2/copy-trading/traders. Supports filtering by tier, pagination, and offset.

Browse the live paper-trading leaderboard. PUBLIC (no auth), 200 keyless. Each row carries slug, name, prompt (the natural-language seed), params (pair, timeframe, strategy_class), display_rank, live PnL fields, copy_count, a resolved backtest block, and a disclaimer. The disclaimer MUST be surfaced verbatim with every presentation — paper PnL is not a promise of live performance. No fabrication of rows. Errors: 500 (upstream data unavailable) — report the outage honestly and retry later. Present rows by display_rank; the prompt plus params are the trial seed for a leaderboard-sourced paper deployment.

List Nautilus deployments via GET /v3/deployment. Supports pagination and limit.

List paper deployments via GET /v2/paper-deployment. Supports filtering by status, pagination, and optional inclusion of code/config.

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

WRITE (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). Errors: 404 (feature disabled / wallet not owned), 409 (not yet in an onboardable state), 502. Output shape on 201: {account_index, api_key_approval_tx_hash, ...}. Read api_key_approval_tx_hash as proof the key-approval transaction was submitted, NOT that the key is live - poll to 'ready' before any money operation.

Create a new bracket order via POST \/v2\/bracket. Submits pair, side, entry, take_profit, stop_loss, size_usd plus optional leverage, alive_until, account_address. Geometry: long requires stop_loss below entry below take_profit; short requires take_profit below entry below stop_loss. Returns {id (brk_...), wallet_address, pair, side, entry, take_profit, stop_loss, size_usd, leverage, status, alive_until, oids (3 numeric ids for entry \/ take-profit \/ stop-loss), created_at, updated_at}. Use CancelBracketOrder to amend (the API has no amend). WRITE - real funds. Errors: 400 geometry \/ credentials \/ unknown pair (verify via Hyperliquid meta over runtime HTTP), 403 wallet not owned, 409 no_free_wallet or wallet_occupied (offer cancel \/ use another account \/ create one via the Hyperliquid Treasury skill), 502 Hyperliquid rejected - report exact message, never blind-retry.

Query a paper deployment's state or logs via GET /v2/paper-deployment/{id}/{paperDeploymentEndpoint}. Use the endpoint allowlist from the schema. Errors: 401, 404.

Rename a backtest via PATCH \/v2\/backtesting\/{id}. Updates the human-readable name for the backtest.

Rename a trading account via PATCH \/v3\/account\/{address}. Updates the human-readable name for the account.

READ (search over POST; no side effects). query accepts natural language ('BTC 120k before July'), an exact market slug, or a polymarket.com event URL — pass URLs through WHOLE, never parse them yourself. intent ('backtest', 'discovery', 'deploy', 'monitor'; default 'backtest') tunes ranking. Returns ranked candidates with slug, question, volume/liquidity, coverage {start, end}, dataMode, coverageStatus, backtestSupported, and deploymentSupported. It does NOT return token IDs, prices, or instrument ids — those come later in the flow. status 'not_found' means no match: NEVER invent or guess a slug. For backtests require coverageStatus 'available' AND backtestSupported true; 'metadata_only' markets are not backtestable yet. Multiple plausible candidates leads to asking the Steward to choose by question or slug. Errors beyond the shared model: 400 validation_failed.

Send an authorized action to Hyperliquid via POST /v2/authorize-and-send/hyperliquid. Used for submitting signed transactions.

WRITE (real funds - places one immediate REAL Lighter market order; explicit confirmation showing market, side, quote amount, slippage, and wallet, and exactly ONE request per confirmed action). The server loads the stored Lighter API key, signs, and submits. market_id is an integer (0 = ETH perp on mainnet - verify OTHER market ids against live market metadata before use; never guess). side 'buy' or 'sell'. quote_amount is the USDC notional as a decimal string. max_slippage is a string fraction 0-0.5 (default '0.005' = 0.5%). reduce_only default false; price_protection default true. sendTx action variant is NOT exposed - the Mind has no signer and must never fabricate signed payloads. Pre-checks before any order: readiness 'ready', balance sufficient (SuperiorTrade_GetLighterBalance), amount above venue minimums. On min-size or slippage rejections: re-check market metadata and balance, reconfirm, never blind-retry. Errors: 400 (validation/min size/slippage shape), 404 (feature disabled / not owned), 502 (venue rejected - report the exact message).

WRITE (real funds — places or cancels a REAL Polymarket CLOB order; requires explicit confirmation showing venue/wallet/tokenID/side/amount/price/orderType plus 'This places a REAL order.'). The server signs with the owned wallet and stored CLOB credentials. The fast path for one-off bets: NEVER spin up a deployment for a single bet. action is oneOf: placeMarketOrder {type 'placeMarketOrder', tokenID (Polymarket outcome token ID), side 'BUY' or 'SELL', amount (positive decimal STRING — for BUY the pUSD to spend, for SELL the outcome-token size), optional price (worst acceptable, strictly above 0 and at most 1), optional orderType ('FOK' fill-or-kill or 'FAK' fill-available-and-cancel, default FOK), optional from (owned wallet, 0x plus 40 hex, omit for main)} OR cancelOrder {type 'cancelOrder', orderID, optional from}. Optional-param handling: price, orderType, and from are optional fields INSIDE the single action object parameter, so omission happens at action-construction time, not in the bodyTemplate — build the action object with only the fields the Steward confirmed. Venue minimums are roughly 5 pUSD / 5 shares; rate limits roughly 30 orders/min. Exactly ONE request per confirmed action — never auto-retry a submitted order, and never fabricate fill results: report exactly what the response returned. Errors beyond the shared model: 400 (validation / below venue minimums), 403 (wallet not owned), 502 (CLOB rejected — report the exact message).

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.

Transfer USDC between Hyperliquid accounts via POST \/v2\/portfolio\/hyperliquid\/transfer. Body uses the key 'to' (NOT 'to_address') and 'from'. to and from are wallet addresses (must be owned by the Steward). amount is a positive USDC decimal string. Returns from, to, amount, and the venue's response.

Update deployment settings via PATCH \/v2\/deployment\/{id}. Modify name (1-255 characters, trimmed) and\/or alive_until (ISO-8601 date-time with timezone for automatic stop). Pass null to clear a previously scheduled stop.

Withdraw USDC from Hyperliquid to an external wallet via POST \/v3\/portfolio\/hyperliquid\/withdraw. chain 'arbitrum' (or 'arbitrum_one' \/ 'arbitrum-one' \/ '42161') is the destination chain; asset_address is the native USDC token address on Arbitrum One: 0xaf88d065e77c8cC2239327C5EDb3A432268e5831. amount is a USDC decimal string up to 6 decimals; must be well above 1 USDC since Hyperliquid deducts a 1 USDC fee. to is the Arbitrum destination address (confirm via echo-back before sending). from is optional: source trading wallet; when omitted, the default main trading wallet is used.

WRITE (real funds - fast-withdraws Lighter USDC to an external EVM wallet, signed server-side with the stored Lighter key; DOUBLE confirmation with destination echo-back before sending). amount: USDC decimal string, minimum 4, up to 6 decimals. IDEMPOTENCY: idempotency_key (min 8 chars) maps to the Idempotency-Key request header - same reuse rules as deposits: REUSE the SAME key when retrying the same attempt; never mint a new key for an ambiguous outcome. A 202 'unknown' means the state is uncertain: POLL SuperiorTrade_GetLighterWithdrawal - NEVER resubmit with a new key (that can double-send). Errors: 400 (validation/minimum/precision), 404 (feature disabled / not owned), 409 (idempotency key reused with different input), 502.