# Superior Trade Hyperliquid

> Backtest and deploy trading strategies on Superior Trade's managed cloud.

- **Type:** Skill
- **Install:** `agentstack add skill-superior-trade-superior-skills-superior-trade-hyperliquid`
- **Verified:** Yes — security-reviewed for prompt injection and unsafe behavior
- **Seller:** [Superior-Trade](https://agentstack.voostack.com/s/superior-trade)
- **Installs:** 0
- **Category:** [AI & ML](https://agentstack.voostack.com/c/ai-and-ml)
- **Latest version:** 0.1.0
- **License:** MIT
- **Upstream author:** [Superior-Trade](https://github.com/Superior-Trade)
- **Source:** https://github.com/Superior-Trade/superior-skills/tree/main/skills/superior-trade-hyperliquid

## Install

```sh
agentstack add skill-superior-trade-superior-skills-superior-trade-hyperliquid
```

Requires the [AgentStack CLI](https://agentstack.voostack.com/docs/cli). Works with Claude Code, Cursor, and any MCP-compatible agent.

## About

# 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](https://github.com/Superior-Trade/superior-skills/blob/main/skills/dca-weekly/SKILL.md) — scheduled buys via `adjust_trade_position` (works on calendar trigger, not price)
- [Grid trading](https://github.com/Superior-Trade/superior-skills/blob/main/skills/grid-trading/SKILL.md) — profit-laddered position adjustment + partial take-profits
- [Funding rate arbitrage](https://github.com/Superior-Trade/superior-skills/blob/main/skills/funding-rate-arbitrage/SKILL.md) — capture funding when shorts are paying longs (the most profitable template in our audit)
- [Funding squeeze](https://github.com/Superior-Trade/superior-skills/blob/main/skills/funding-squeeze/SKILL.md) — long when funding is deeply negative AND price is rising; ride the squeeze instead of waiting for carry mean-reversion
- [Basis arbitrage (directional)](https://github.com/Superior-Trade/superior-skills/blob/main/skills/basis-arb/SKILL.md) — long perp when spot–perp basis flips negative with funding negative (directional read; not a hedged arb)
- [Breakout](https://github.com/Superior-Trade/superior-skills/blob/main/skills/breakout/SKILL.md) — Donchian-style breakout with trailing stop (regime-sensitive)
- [Mean reversion](https://github.com/Superior-Trade/superior-skills/blob/main/skills/mean-reversion/SKILL.md) — 2.5σ Bollinger fade with ADX regime filter
- [Scalping](https://github.com/Superior-Trade/superior-skills/blob/main/skills/scalping/SKILL.md) — fast in/out on RSI thrust + volume spike (structural template; tune before deploying)

### Exchange-specific guides

- [Aerodrome / Base](https://github.com/Superior-Trade/superior-skills/blob/main/skills/aerodrome/SKILL.md) — spot AMM swap execution on Base; no order book, no leverage, wallet-balance-driven

### Optimizations

- [Pre-trade thesis builder](https://github.com/Superior-Trade/superior-skills/blob/main/skills/trade-thesis/SKILL.md) — structured bull/bear analysis, invalidation criteria, and sizing rationale before any live deployment of a new strategy idea
- [Backtesting best practices](https://github.com/Superior-Trade/superior-skills/blob/main/skills/backtesting/SKILL.md) — window selection, trade-count thresholds, exit-reason mix, parameter sweeps, walk-forward, zero-trade escalation, compute-cost estimation
- [Fees optimization](https://github.com/Superior-Trade/superior-skills/blob/main/skills/fees-optimizations/SKILL.md) — 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:**
```json
{"type":"createSubAccount","user":"","name":"My Strategy"}
```

**Sub-account transfer (main → sub):**
```json
{"type":"subAccountTransfer","from":"","to":"","token":"USDC","amount":1000}
```

**Sub-account transfer (sub → main):**
```json
{"type":"subAccountTransfer","from":"","to":"","token":"USDC","amount":500}
```

**Transfer via sendAsset (main → sub):**
```json
{"type":"sendAsset","destination":"","sourceDex":"spot","destinationDex":"spot","token":"USDC","amount":1000}
```

**Transfer via sendAsset (sub → main):**
```json
{"type":"sendAsset","fromSubAccount":"","destination":"","sourceDex":"spot","destinationDex":"spot","token":"USDC","amount":500}
```

**Set unified account mode on a sub-account:**
```json
{"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:**
```json
{"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](https://github.com/Superior-Trade)
- **Source:** [Superior-Trade/superior-skills](https://github.com/Superior-Trade/superior-skills)
- **License:** MIT

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

## Pricing

- **Free** — Free

## Security capabilities

Automated source analysis of v0.1.0 — what this tool can access:

- **Network access:** yes
- **Filesystem access:** no
- **Shell / process execution:** no
- **Environment & secrets:** no
- **Dynamic code execution:** no

*"Yes" means the capability is present in the source — more access means more to trust, not that it is unsafe.*


## Versions

- **0.1.0** — security scan: passed — Imported from the upstream source.

## Links

- Listing page: https://agentstack.voostack.com/l/skill-superior-trade-superior-skills-superior-trade-hyperliquid
- Seller: https://agentstack.voostack.com/s/superior-trade
- Browse the marketplace: https://agentstack.voostack.com/browse

---
Listed on AgentStack — the marketplace for AI agent skills and MCP servers. Every listing is security-reviewed. Creators keep 70%.