Superior Trade Suite v2

Start or stop a deployment via PATCH /v2/deployment/{id}/status with {action: 'start'|'stop'} — PATCH is the recommended method; the legacy PUT on the same path is deprecated for start/stop. Action 'start' begins the bot (live if credentials stored, paper if not), provisions the runtime with the stored credentials, resolves subaccount conflicts, and — for HIP-3 configs — enables Hyperliquid unified-account mode on the trading wallet so spot USDC counts as perp margin. Starting via the legacy PUT skips the unified-account step and can leave a HIP-3 or API-provisioned account silently unable to trade ('Available balance: 0' on every signal) — if a running deployment shows that symptom, stop it and start it again with this tool. Action 'stop' halts the bot — platform automatically cancels all open orders and closes all positions on Hyperliquid before stopping. Returns {id, status}. WRITE operation — requires Steward confirmation before starting. Errors: 400 (invalid transition, missing credentials, invalid strategy code, or subaccount_required — the main wallet is already running another deployment; recovery: stop the other deployment, target a different trading account, or delete+recreate this deployment and StoreCredentials with a subaccount_address — see the SUBACCOUNT_REQUIRED RECOVERY constraint), 401, 404.

Create a new backtest via POST /v2/backtesting. Submits strategy code, trading configuration, and the historical timerange. timerange is a REQUIRED top-level body field, a sibling of config and code — omitting it returns 400 validation_failed with details path 'timerange' ('expected object, received undefined'). Nesting timerange inside config does NOT work. Returns {id, status: 'pending', message}. Must call SuperiorTrade_StartBacktest to begin execution. Response 201. Errors: 400 validation_failed (check details array), 400 invalid_code, 400 limit_exceeded (max 10 — delete completed/failed backtests first via DELETE /v2/backtesting/{id}), 401.

Create a trading bot deployment via POST /v2/deployment. Returns {id, config, code, name, replicas, status: 'pending', deployment_name, created_at}. Without credentials the bot runs in dry-run/paper mode. WRITE operation — requires Steward confirmation. Errors: 400 validation_failed, 400 invalid_code, 400 limit_exceeded (max 10), 401.

Cancel (if running) and delete a backtest via DELETE /v2/backtesting/{id}. Permanent removal. Returns {message: 'Backtest deleted'}. WRITE operation — requires Steward confirmation. Errors: 401, 404.

Delete a deployment via DELETE /v2/deployment/{id}. Closes all positions and orders on Hyperliquid before deleting. Returns {message: 'Deployment deleted'}. Deleting stopped deployments may return 500 — safe to ignore. Permanent removal. WRITE operation — requires Steward confirmation. Errors: 401, 404.

Close all open orders and liquidate all positions for a deployment via POST /v2/deployment/{id}/exit. Deployment MUST be stopped first (use SuperiorTrade_ControlDeployment stop). Hyperliquid deployments only — Aerodrome swaps are atomic with no open positions (see the Aerodrome skill). Returns {id, status, orders_cancelled, positions_closed}. WRITE operation — requires Steward confirmation. Errors: 400 invalid_request (deployment still running or credentials missing), 401, 404.

Retrieve full backtest details via GET /v2/backtesting/{id}. Returns id, config, code, status, started_at, completed_at, job_name, created_at, updated_at, plus an inline results field and a result link (spelled resultUrl in the vendor's current v2 contract, result_url in older responses) that are null on completed runs in our own runtime verification. Never block on them and never read a null results field as a failed or empty backtest: the metrics source is SuperiorTrade_GetLogs on the backtest id, whose Freqtrade summary tables carry total trades, win rate, profit, drawdown, Sharpe and durations. All timestamps UTC ISO8601. Errors: 401, 404.

Check whether historical candle data is available for a given exchange + pair + timeframe via GET /v2/backtesting-data/{exchange}?pair={pair}&timeframe={timeframe} — the live API serves this as concrete per-exchange endpoints (/v2/backtesting-data/aerodrome, /v2/backtesting-data/hyperliquid, /v2/backtesting-data/binance); the templated path renders those URLs exactly. Aerodrome fetches OHLCV live from Bitquery, so data is generally available even without pre-downloaded catalogs. Returns {available: boolean, pair, timeframe, from (ISO8601 UTC, earliest candle), to (ISO8601 UTC, latest candle), candles: integer (count available)}. Always call this BEFORE SuperiorTrade_CreateBacktest for Aerodrome — if available is false or candles is below the strategy's startup_candle_count, abort and inform the Steward. On available:false the 200 response carries an error string explaining why. Public-style endpoint but still gated by x-api-key. Errors: 400 validation_failed (missing/invalid parameter), 401, 500 (availability check failed).

Poll backtest status via GET /v2/backtesting/{id}/status. Returns {id, status}. Status values: 'pending', 'running', 'completed', 'failed'. No results payload is returned by this route. On 'completed', read the metrics from SuperiorTrade_GetLogs on the backtest id (the Freqtrade summary tables in the log stream) and the record from SuperiorTrade_GetBacktest; do not wait for a results or result_url value, which stay null. Poll every ~10 seconds; typical completion 1-10 minutes. Errors: 401, 404.

View credential info for a deployment via GET /v2/deployment/{id}/credentials. Does NOT return private keys. Returns {id, credentials_status, exchange, wallet_address, wallet_source ('main_trading_wallet'|'provided'), wallet_type ('main_wallet'|'agent_wallet'), agent_wallet_address, subaccount_address (Hyperliquid only, null unless configured)}. If missing: {credentials_status: 'missing'}. wallet_type indicates whether the returned wallet_address is a main_wallet or agent_wallet. Auto-resolved credentials (wallet_source 'main_trading_wallet') can return wallet_type 'agent_wallet' — this is the signing wallet, NOT the funded main wallet. If wallet_type is 'agent_wallet', the funded main wallet address is not available via this endpoint — ask the Steward for their main wallet address from their dashboard at https://terminal.superior.trade. The agent wallet having $0 is normal. For balance checks, always use the MAIN wallet address (not the agent wallet). Errors: 401, 404.

Retrieve full deployment details via GET /v2/deployment/{id}. Returns id, config, code, name, replicas, status, pods (name/status/restarts), credentials_status ('stored'|'missing'), exchange, subaccount_address (Hyperliquid only, absent unless configured), deployment_name, namespace, created_at, updated_at. All timestamps UTC. Errors: 401, 404.

Poll deployment status via GET /v2/deployment/{id}/status. Returns {id, status, replicas, available_replicas, pods}. Status values: 'pending', 'running', 'stopped'. Errors: 401, 404.

Retrieve logs for a backtest or deployment via GET /v2/backtesting/{id}/logs or GET /v2/deployment/{id}/logs. Returns {items: [{timestamp, message, severity}], nextCursor}. All timestamps UTC. Heartbeat messages are normal. Errors: 401, 404.

List all backtests via GET /v2/backtesting. Returns {items, nextCursor}. Pass cursor query param to paginate. Errors: 401.

List all deployments via GET /v2/deployment. Returns {items, nextCursor}. Pass cursor query param to paginate. Errors: 401.

Start a pending backtest via PUT /v2/backtesting/{id}/status with {action: 'start'}. (The live endpoint also accepts 'stop' to cancel a running/pending backtest, but this wrapper exposes start only — cancel and delete via SuperiorTrade_DeleteBacktest.) Returns {id, status: 'running', previous_status, job_name}. Errors: 401, 404.

Store exchange credentials for a deployment via POST /v2/deployment/{id}/credentials. Enables live trading. Server resolves wallet automatically — do NOT send private_key (API rejects it). Input wallet_address is optional — if provided, specifies which wallet to use (ownership validated server-side); if omitted, server assigns the user's platform-managed main wallet. Optional subaccount_address (Hyperliquid ONLY, must be a valid Ethereum address) binds the deployment to a Hyperliquid subaccount of the main wallet — this is the fix for 400 subaccount_required on start when the main wallet is already running another deployment. Never send subaccount_address for aerodrome. Response returns {id, credentials_status: 'stored', exchange, wallet_address, wallet_source, agent_wallet_address, subaccount_address (null unless configured), updated_at}. IMPORTANT: wallet_address in the RESPONSE is the signing wallet (agent wallet) that signs trades — it does NOT need its own funds, it trades against the main wallet's balance. Do NOT confuse response wallet_address (agent/signing wallet) with the main wallet (where funds live). IDEMPOTENT — won't overwrite existing credentials. Credential update procedure: (1) stop deployment, (2) delete deployment, (3) create new deployment with same config/code, (4) store new credentials. To ADD a subaccount_address to an existing deployment you must follow the same delete/recreate procedure — stored credentials cannot be amended. WRITE operation — requires Steward confirmation with real-money warning. Errors: 400 invalid_request (if private_key sent), 400 invalid_wallet_address, 400 invalid_subaccount_address, 400 duplicate_wallet_address (wallet address OR subaccount already used by another deployment), 400 unsupported_exchange, 400 no_wallet_available, 403 wallet_not_owned, 403 subaccount_not_owned, 401, 500 server_misconfigured.