/hyperliquid

name: hyperliquid
description: "Use when backtesting, deploying, checking funding readiness, or debugging a Hyperliquid strategy through Superior Trade Unified API — writing Freqtrade configs and strategy code, running sweeps, checking managed-wallet balances, trading HIP-3 perps, or diagnosing a deployment that will not start or trade."
metadata:
  version: 5.0.0
  updated: 2026-08-12
  homepage: https://account.superior.trade
  source: https://github.com/Superior-Trade
  primaryEnv: SUPERIOR_TRADE_API_KEY
  auth:
    type: api_key
    env: SUPERIOR_TRADE_API_KEY
    header: x-api-key
    scope: "Read the user's Unified wallet and Hyperliquid context, manage backtests and deployments, submit supported typed executions, and request a contract-supported withdrawal after confirmation. Venue-specific deposits and transfers are unavailable unless Unified OpenAPI explicitly exposes them. Cannot export private keys or access other users' data."
  env:
    - name: SUPERIOR_TRADE_API_KEY
      description: "Superior Trade API key (x-api-key header). Obtained at https://account.superior.trade. Used for Unified wallet/context reads, backtests, deployments, supported typed executions, and contract-supported withdrawals. It cannot export private keys or access other users' data."
      required: true
      type: api_key
  externalEndpoints:
    - url: https://api.superior.trade
      purpose: "All backtesting and deployment operations"
    - url: https://api.hyperliquid.xyz/info
      purpose: "Read-only public queries. Balance checks send the user's public wallet address (not a secret — visible on-chain). Pair validation sends no user data. No authentication or secrets are sent to this endpoint."

Superior Trade — Hyperliquid

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

Read [`../../references/unified-runtime.md`](../../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`](../../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.

| Read | When | | --- | --- | | `references/api.md` | You need Unified route selection for account, context, backtesting, deployment, typed execution, or withdrawal (`POST /wallet/withdraw`). | | `references/strategy-config.md` | You are writing or fixing config JSON or strategy Python — config fields, code template, TA-Lib usage, multi-entry (DCA/grid), funding-rate access, `minimal_roi` shapes. | | `references/wallets-and-accounts.md` | Anything about wallets, balances, deposits, sub-accounts, multi-strategy capacity, pair formats, or HIP-3 tickers. | | `references/troubleshooting.md` | A deployment or backtest is failing, trading zero times, hitting rate limits, or showing orphan positions. |

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" ins