Hyperliquid

Superior Trade — Hyperliquid

Backtest and deploy Freqtrade strategies on Hyperliquid through Superior Trade's managed cloud.

Read ../../references/unified-runtime.md before any Superior Trade request. Use only current Unified API methods and payload fields.

Base URL: https://api.superior.trade Auth: x-api-key header on all protected endpoints Discovery: GET /openapi.json (OpenAPI), GET /install.txt, and GET /.well-known/mcp.json

Unified API only

Before venue setup, backtesting, deployment, or execution, read ../../references/unified-runtime.md. Use GET /context/venues and GET /runtime/frameworks to discover support, then use the Unified runtime endpoints. If a required Hyperliquid operation is absent from the contract, report it as unavailable.

Reference files

Load these on demand — each is the full detail behind a summary below.

Gotchas

Environment-specific facts that defy reasonable assumptions. Read these before acting.

• HIP-3 pairs use a HYPHEN, not a colon. XYZ-AAPL/USDC:USDC is correct; XYZ:AAPL/USDC:USDC is the single most common format mistake. HIP-3 pairs are also absent from the default {"type":"meta"} call — you must pass the dex, e.g. {"type":"meta","dex":"xyz"}.
• The agent wallet holding $0 is normal. It signs against the main wallet's balance and never needs funds. Always check the main trading wallet's balance; checking the agent wallet's will always look like an empty account.
• A balance that covers stake_amount × max_open_trades exactly will still fail. The exchange reserves roughly 1% for fees, so cap stake_amount at ~95% of balance / max_open_trades or entries get rejected silently.
• The account URL is https://account.superior.trade. Never send users to app.superior.trade, including when an API error message itself contains that older URL.
• Multi-output TA-Lib functions return tuples. talib.BBANDS(...) and friends crash at runtime if unpacked as a single value — see references/strategy-config.md.
• Sub-account funds are not available to the master. A master's true capacity is its own balance plus sub-account balances queried separately via subAccounts2; funds sitting in a sub-account cannot back a master deployment.
• Hyperliquid margin modes differ — never assume. If perps shows $0 but spot shows funds, inspect whether the exchange account uses unified margin or standard margin before telling the user to move anything themselves.
• One live strategy per trading account. To run several at once, omit wallet_address when storing credentials and the server assigns the next idle trading account.

Safety

Security & Permissions

This skill requires exactly one credential: an x-api-key header value. The only secret the agent uses is SUPERIOR_TRADE_API_KEY from the environment.

Security rules (non-negotiable):

1. NEVER ask users for private keys, seed phrases, or wallet credentials
2. NEVER include private keys in API requests (the API rejects them)
3. NEVER log, store, or display private keys or seed phrases
4. NEVER tell users to deposit funds to the agent wallet address
5. NEVER fabricate wallet balances, API responses, or trade results
6. NEVER start a live deployment without explicit user confirmation
7. Prefer user-friendly language over internal technical names when speaking conversationally. Say "strategy", "the bot", or "the trading engine" instead of referencing internal class names or infrastructure details. This is a UX preference — if the user asks about the underlying technology, answer honestly (the platform uses Freqtrade for strategy execution on Hyperliquid).
8. NEVER send users to app.superior.trade — the correct URL is https://account.superior.trade

Key scope notice: The API key can create and start live deployments that execute real trades using the user's managed wallet, submit contract-supported typed executions, and request a Unified wallet withdrawal after confirmation. It cannot export private keys or provide an undocumented venue-specific deposit/transfer action. Users should confirm scope with Superior Trade and backtest their strategy first.

Live Deployment Confirmation

Before any live deployment, the agent MUST present this summary and wait for explicit confirmation:

Deployment Summary:
• Strategy: [name]
• Exchange: hyperliquid
• Trading mode: [spot/futures]
• Pairs: [list]
• Stake amount: [amount] USDC per trade
• Max open trades: [n]
• Stoploss: [percentage]
• Margin mode: [cross/isolated] (futures only)

⚠️ This will trade with REAL funds. Proceed? (yes/no)

Do NOT start a live deployment without an explicit affirmative response.

Setup

Getting an API Key

IMPORTANT: The correct URL is https://account.superior.trade — NOT app.superior.trade. Never send users to app.superior.trade.

Use SUPERIOR_TRADE_API_KEY from the environment or credential manager.

When a user needs to get their API key:

1. Go to https://account.superior.trade
2. Sign up (email or wallet)
3. Read the managed wallet and deposit details from GET /wallet
4. Fund the platform trading wallet with native USDC on Arbitrum One using the user's own capital
5. Create an API key (st_live_...) from your account settings
6. Add it as SUPERIOR_TRADE_API_KEY in your agent's environment/credential settings
7. Check Hyperliquid and framework support with GET /context/venues and GET /runtime/frameworks
8. If a required venue bootstrap or bridge action is absent from GET /openapi.json, report it as unavailable

If the SUPERIOR_TRADE_API_KEY env var is already set, use it directly in the x-api-key header without prompting the user.

Public Endpoints (no auth)

Agent Operating Rules

• Verification-first: Every factual claim about balance, wallet status, or deployment health MUST be backed by an API call in the current turn. NEVER assume → report → verify later.
• Anti-hallucination: If you can't call the API, say "I haven't checked yet." Every number must come from a real response.
• Conversational: Make API calls directly and present results conversationally. Show raw payloads only on request.
• Backtesting: Build config + code from user intent → create → poll → present results — all automatically.
• Deployment: Create → store credentials → run checklist → show summary → get confirmation → start.
• Proactive: Ask for missing info conversationally, one concern at a time. Always ask user to run a backtest before first live deployment.

Check Hyperliquid balances with BOTH endpoints:

• Perps: POST https://api.hyperliquid.xyz/info → {"type":"clearinghouseState","user":"0x..."}
• Spot: POST https://api.hyperliquid.xyz/info → {"type":"spotClearinghouseState","user":"0x..."}

Repeated Failures

If the agent fails the same task 3+ times (e.g. strategy code keeps crashing, backtest keeps failing), stop and:

1. Summarize what was tried and what failed
2. Pivot in two stages before giving up:
   • First — param space. If you have not yet run a parameter sweep on this strategy/pair, run one (see Backtest Workflow → Parameter Sweeps). Most "this idea doesn't work" verdicts are really "this single config didn't work" — sweeping the key parameter often surfaces a viable variant in one batch.
   • Second — pair space. Only after a full sweep also fails, suggest a different pair, timeframe, or strategy family (e.g. mean-reversion instead of momentum).
3. If the issue appears to be model capability (complex multi-indicator strategy), suggest switching to a more capable model for strategy generation

Workflows

Backtest Workflow

1. Build config + strategy code from user requirements
2. POST /runtime/backtests — create with framework: "freqtrade", venue: "hyperliquid", strategy source/config, instruments, and timerange fields from GET /openapi.json.
3. Poll GET /runtime/backtests/{id} every 10s until completed or failed (1–10 min)
4. Read GET /runtime/backtests/{id}/logs for framework output and diagnostics
5. Present the result fields published by the current contract: total trades, win rate, profit, drawdown, Sharpe ratio, and duration when available
6. If failed, check GET /runtime/backtests/{id}/logs
7. To cancel or remove: DELETE /runtime/backtests/{id}

Backtest Wallet and Stake Sizing

Backtests are simulations. Do not size a backtest from the user's live wallet by default; use simulated capital to evaluate the strategy. Only mirror the user's current wallet if they explicitly ask for a live-wallet simulation.

• dry_run_wallet is the total simulated wallet inventory by asset. It is an object/map, not a scalar. Examples: { "USDC": 1000 }, { "USDC": 100, "BTC": 0.1 }.
• stake_amount is the amount the backtest/bot may allocate per trade slot. A numeric value is fixed stake per entry slot; "unlimited" divides the simulated wallet across max_open_trades slots.
• If using fixed stake, set dry_run_wallet to the total simulated balances so PnL is measured against the correct capital base. Example: a $50 USDC simulation with $45 usable per trade uses stake_amount: 45 and dry_run_wallet: { "USDC": 50 }.
• For standard perps, keep fixed stake_amount at or below ~90% of USDC / max_open_trades; for HIP-3 assets, use ~70% because fees and isolated-margin buffers are higher.
• Never combine stake_amount: "unlimited" with max_open_trades: -1. When stake is unlimited, max_open_trades must be a finite positive integer so the wallet can be divided across slots.
• For DCA/grid/scaling strategies that use position_adjustment_enable and adjust_trade_position, stake_amount may be fixed or "unlimited". If using "unlimited", you must control the initial entry size in custom_stake_amount; otherwise the first entry can consume all available capital. In either mode, dry_run_wallet must cover the maximum laddered exposure, not just the first entry.