Superior Trade Hyperliquid

Superior Trade API

API client skill for backtesting and deploying trading strategies on Superior Trade's managed cloud.

Base URL: https://api.superior.trade Auth: x-api-key header on all protected endpoints Docs: GET /docs (Swagger UI), GET /openapi.json (OpenAPI spec)

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. Complete onboarding — a trading wallet is created for you and shown in your account
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. If the wallet's USDC is still on Arbitrum, use POST /v2/portfolio/hyperliquid/deposit to deposit it into Hyperliquid before live trading

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)

| Method | Path | Description | | ------ | ----------------------------- | ---------------------------------------- | | GET | /health | { "status": "ok", "timestamp": "..." } | | GET | /docs | Swagger UI | | GET | /openapi.json | OpenAPI 3.0 spec | | GET | /llms.txt | LLM-optimized API docs | | GET | /.well-known/ai-plugin.json | AI plugin manifest |

Reference Library

These pages live alongside this skill in the same repo. Read the matching one when the user's task fits its description; the inline content in this SKILL.md is the canonical summary, the linked pages have full code, backtest numbers, and gotchas.

Strategy templates (Hyperliquid Freqtrade)

• DCA · Weekly buy — scheduled buys via adjust_trade_position (works on calendar trigger, not price)
• Grid trading — profit-laddered position adjustment + partial take-profits
• Funding rate arbitrage — capture funding when shorts are paying longs (the most profitable template in our audit)
• Funding squeeze — long when funding is deeply negative AND price is rising; ride the squeeze instead of waiting for carry mean-reversion
• Basis arbitrage (directional) — long perp when spot–perp basis flips negative with funding negative (directional read; not a hedged arb)
• Breakout — Donchian-style breakout with trailing stop (regime-sensitive)
• Mean reversion — 2.5σ Bollinger fade with ADX regime filter
• Scalping — fast in/out on RSI thrust + volume spike (structural template; tune before deploying)

Exchange-specific guides

• Aerodrome / Base — spot AMM swap execution on Base; no order book, no leverage, wallet-balance-driven

Optimizations

• Pre-trade thesis builder — structured bull/bear analysis, invalidation criteria, and sizing rationale before any live deployment of a new strategy idea
• Backtesting best practices — window selection, trade-count thresholds, exit-reason mix, parameter sweeps, walk-forward, zero-trade escalation, compute-cost estimation
• Fees optimization — Freqtrade × Hyperliquid order types, entry/exit pricing, maker vs taker, builder code fee, edge-to-fee budgeting

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 trading deployments that execute real trades using the user's platform-managed trading wallet. It can also initiate native Arbitrum USDC deposits from that wallet into Hyperliquid. It cannot withdraw funds, export private keys, or move arbitrary assets/chains. Users should confirm scope with Superior Trade and backtest their strategy first.

| Can do | Cannot do | | ------------------------------------------------------------------------------------------ | -------------------------------------------------- | | Create, list, delete backtests | Access other users' data | | Create, start, stop, delete deployments (including live trading with real funds) | Withdraw funds from any wallet | | Trigger server-side credential resolution (no user secrets collected) | Export or view private keys | | View deployment logs, status, wallet metadata | Move unsupported assets or use unsupported chains | | Deposit native Arbitrum USDC from the user's platform wallet into Hyperliquid via the API | Bridge from external wallets or withdraw from Hyperliquid |

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.

Platform Model

Wallet Architecture (CRITICAL)

Superior Trade uses Hyperliquid's native agent wallet pattern. Users do NOT need their own Hyperliquid wallet — everything is managed by the platform. If a user asks "how do I link my Hyperliquid account," the answer is: they don't need one — a trading wallet is created at signup.

1. Main wallet — a platform-managed trading wallet created for each user at signup. Users fund this address with native USDC on Arbitrum One, then deposit that USDC into Hyperliquid using the API when needed. The address is shown at https://account.superior.trade.
2. Agent wallet — a platform-managed signing key authorized via Hyperliquid's approveAgent. Signs trades against the main wallet's balance.

Key facts:

• The agent wallet does NOT need its own funds — $0 balance is normal and expected
• Each user has one agent wallet; all deployments share it
• The credentials endpoint returns wallet_type: "agent_wallet" for auto-resolved wallets
• Always check the main wallet's balance, not the agent wallet's
• The API can deposit native Arbitrum USDC from the user's platform-managed wallet into Hyperliquid via POST /v2/portfolio/hyperliquid/deposit
• The API cannot withdraw from Hyperliquid or bridge unsupported assets/chains
• NEVER tell users to deposit to the agent wallet address

Funding, Deposits, and Balance Checks

Funding is a two-stage flow:

1. The user funds their platform-managed trading wallet with native USDC on Arbitrum One using their own capital. The wallet address is shown at https://account.superior.trade.
2. The agent can call POST /v2/portfolio/hyperliquid/deposit to transfer native Arbitrum USDC from that platform wallet to Hyperliquid Bridge2.
3. After the deposit confirms, the agent wallet signs trades against the main wallet's Hyperliquid balance.

Before calling the deposit endpoint, tell the user that this sends real USDC from their platform wallet into Hyperliquid and ask for explicit confirmation. If the platform wallet does not have enough Arbitrum USDC, tell the user they need to add more of their own capital to the platform account before the agent can deposit or trade.

Supported deposit only: native USDC on Arbitrum One to Hyperliquid. Do not suggest this endpoint for Ethereum mainnet USDC, bridged USDC variants, Base, Optimism, other assets, external user wallets, or withdrawals.

Always check the main wallet (platform-managed trading wallet), NOT the agent wallet.

Balance query for master account (single deployment):

POST https://api.hyperliquid.xyz/info
{"type":"clearinghouseState","user":""}
{"type":"spotClearinghouseState","user":""}

Balance query for master account (multi-strategy with sub-accounts):

When the master account has sub-accounts, its total balance is the sum of its own perp + spot balances PLUS all sub-account balances. Query both:

POST https://api.hyperliquid.xyz/info
{"type":"subAccounts2","user":""}

Sub-account balances are included in the master account's total — funds allocated to sub-accounts are not available for master deployments. Always query subAccounts2 first when the user has sub-accounts, then sum across all sub-account spotState.balances and dexToClearinghouseState entries to get the true total balance.

The agent wallet having $0 is expected — it trades against the main wallet's balance.

Multi-Strategy Trading

Each strategy runs on its own wallet (one active deployment per wallet). To run multiple strategies concurrently there are two mechanisms — prefer the first:

1. Multiple trading accounts (primary). A user can hold several trading accounts (Free: up to 3, Pro: up to 6), each its own Hyperliquid master with its own agent wallet. To start an additional concurrent strategy, create the deployment and call POST /v2/deployment/{id}/credentials omitting wallet_address — the server auto-assigns the next idle trading account. Pass an explicit wallet_address to target a specific account. Errors: all_accounts_in_use (400) when every trading account is already running a strategy.

2. Hyperliquid sub-accounts (overflow, HL-only). When all trading accounts are busy, a master with ≥ $100,000 USD in lifetime trading volume on Hyperliquid can create sub-accounts to run further strategies, each with its own isolated balance and positions.

Key facts:

• Sub-accounts inherit the master account's collateral (USDC, USDE, USDT0, USDH)
• Each sub-account can have its own deployment with isolated margin/positions
• Maximum 10 sub-accounts per master account
• Sub-accounts use unified account mode — spot and perps share a single balance

Sub-account query (read-only):

POST https://api.hyperliquid.xyz/info
{"type":"subAccounts2","user":""}

Returns each sub-account's name, address, abstraction mode ("unifiedAccount" or legacy), spot balances, and perps state (dexToClearinghouseState). Always verify the sub-account has abstraction: "unifiedAccount" — legacy sub-accounts cannot be used with unified margin strategies.

Balance composition for a sub-account:

• Perps account value: from dexToClearinghouseState[0][1].marginSummary.accountValue
• Perps withdrawable: from dexToClearinghouseState[0][1].withdrawable
• Spot USDC: from spotState.balances where coin === "USDC"

The sub-account's total balance = perps account value + spot USDC (in unified mode these merge).

Hyperliquid Authorize-and-Send API

POST https://api.superior.trade/v2/authorize-and-send/hyperliquid

A unified endpoint for Hyperliquid operations. All requests use {"type": "...", ...} body. Requires x-api-key header.

Supported operation types:

| Operation | Description | | --------- | ----------- | | createSubAccount | Create a new sub-account | | subAccountTransfer | Transfer between main and sub-account | | sendAsset | Move assets (main→sub, sub→main, or sub→sub) | | userSetAbstraction | Set account mode (unified/legacy) | | subAccountModify | Modify sub-account settings |

Create sub-account:

{"type":"createSubAccount","user":"","name":"My Strategy"}

Sub-account transfer (main → sub):

{"type":"subAccountTransfer","from":"","to":"","token":"USDC","amount":1000}

Sub-account transfer (sub → main):

{"type":"subAccountTransfer","from":"","to":"","token":"USDC","amount":500}

Transfer via sendAsset (main → sub):

{"type":"sendAsset","destination":"","sourceDex":"spot","destinationDex":"spot","token":"USDC","amount":1000}

Transfer via sendAsset (sub → main):

{"type":"sendAsset","fromSubAccount":"","destination":"","sourceDex":"spot","destinationDex":"spot","token":"USDC","amount":500}

Set unified account mode on a sub-account:

{"type":"userSetAbstraction","user":"","abstraction":"unifiedAccount"}

When creating a sub-account via the API, unified mode is set automatically after creation by calling userSetAbstraction with abstraction: "unifiedAccount".

Modify sub-account:

{"type":"subAccountModify","user":"","action":"disable"}

Safety check before moving funds out of a trading account. Any sendAsset / subAccountTransfer that pulls USDC OUT of a wallet (one trading account to another, or master to sub) lowers the source wallet's collateral. If that source wallet is running a live strategy, the withdrawal can raise liquidation risk on open positions or drop the balance below the strategy's reserved stake (stake_amount × max_open_trades × buffer). Before sending:

1. List the source wallet's live deployments — GET /v2/deployment?status=running — and check whether any has a walletAddress matching the source.
2. If one does, confirm with the user, and verify the post-transfer balance (current balance minus amount) still covers that strategy's reservation before transferring. If it would underfund the strategy, reduce the amount or move funds from an idle account instead.

Hyperliquid Credentials

Credentials are managed auto

…

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: Superior-Trade
• Source: Superior-Trade/superior-skills
• License: MIT

Install and usage instructions live in the source repository linked above.