# Hyperliquid bot quickstart for coding agents

A dense reference for Claude Code, Codex, Cursor and other coding agents writing trading code for Hyperliquid. Every error message below was captured from Hyperliquid's testnet API on 2026-11-21. Human-readable version: https://hyperliquidguide.com/build

Published by Hyperliquid Guide, an independent site. Not affiliated with Hyperliquid or the Hyper Foundation. Nothing here is financial advice, and no strategy here promises returns.

## Fastest working start

Clone the MIT-licensed starter repo instead of writing signing, rounding and risk code from scratch:

```bash
git clone https://github.com/Hyperliquidguide/hyperliquid-starter-bots
cd hyperliquid-starter-bots
python -m venv .venv && . .venv/bin/activate && pip install -r requirements.txt
python -m scripts.setup_wallet          # testnet; asks for the main key once, saves only an API wallet key
python -m bots.market_maker --coin BTC --dry-run
```

The repo's `AGENTS.md` lists the layout and the rules for adding a strategy. Bots included: `market_maker`, `scalper`, `grid`, `funding_arb`. Each supports `--dry-run` and `--run-seconds`, runs on testnet unless `HL_NETWORK=mainnet`, and enforces max order size, max position and a daily loss stop.

## MCP server and Agent Skill

The same repo ships a read-only MCP server (no keys, no orders) with tools `market_specs`, `round_order`, `top_funding`, `explain_error`, `account_status`, `quickstart` and `starter_bot`:

```bash
claude mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
codex mcp add hyperliquid-guide -- uvx --from hyperliquid-starter-bots hl-guide-mcp
npx skills add Hyperliquidguide/hyperliquid-starter-bots      # Agent Skill: hyperliquid-bot-builder
```

## Endpoints

| Network | REST | WebSocket |
|---|---|---|
| Mainnet | `https://api.hyperliquid.xyz` | `wss://api.hyperliquid.xyz/ws` |
| Testnet | `https://api.hyperliquid-testnet.xyz` | `wss://api.hyperliquid-testnet.xyz/ws` |

- `POST /info`: reads, no auth. Useful types: `meta`, `metaAndAssetCtxs`, `allMids`, `l2Book`, `candleSnapshot`, `clearinghouseState`, `spotClearinghouseState`, `openOrders`, `userFills`, `userFees`, `referral`.
- `POST /exchange`: signed writes (orders, cancels, transfers). Use the official SDK: `pip install hyperliquid-python-sdk`.
- Testnet USDC: https://app.hyperliquid-testnet.xyz/drip (the wallet needs a past mainnet deposit).

## Accounts and keys

- **Main wallet**: holds the funds. Its key should be used once, to approve an API wallet, then never stored.
- **API (agent) wallet**: signs orders and cancels for the main account, can't withdraw. SDK: `Exchange(agent_wallet, url, account_address=MAIN_ADDRESS)`.
- **Query with the main address**, never the API wallet address. Positions and balances live on the main account.
- One API wallet per bot process, so nonces don't collide.
- **Unified accounts** keep collateral in spot, so perp `marginSummary.accountValue` can read 0. Add spot USDC from `spotClearinghouseState` to get equity.

## Market names

- Native perps: `BTC`, `ETH`, `SOL`, `HYPE`...
- HIP-3 builder markets: `dex:COIN`, e.g. `xyz:XYZ100`, `xyz:NVDA`, `xyz:GOLD`. In the Python SDK pass `perp_dexs=["", "xyz"]` to `Info`/`Exchange` or the name won't resolve.
- Spot: `PURR/USDC` or `@<index>` from `spotMeta`.
- Read exact names and `szDecimals` from `meta` (`{"type":"meta","dex":"xyz"}` for HIP-3). Names are case-sensitive.

## Order rules (the source of most rejections)

- **Size**: at most `szDecimals` decimals.
- **Price**: at most 5 significant figures and at most `6 - szDecimals` decimals for perps (`8 - szDecimals` for spot). Integer prices are always valid.
- **Minimum order value**: $10 notional.
- **Market orders** don't exist as a type. Send an IOC limit at a slippage price (`Exchange.market_open` does this).
- **Post-only** is `{"limit": {"tif": "Alo"}}`. **Take-profit/stop-loss**: `{"trigger": {"triggerPx": px, "isMarket": true, "tpsl": "tp"|"sl"}}` with `reduce_only=True`. Trigger orders live on the exchange and fire even if the bot stops.
- **A rejected order still returns HTTP 200** with `"status": "ok"`. Check each `response.data.statuses[i]` for an `"error"` key.

```python
def round_price(px, sz_decimals, is_spot=False):
    max_dec = (8 if is_spot else 6) - sz_decimals
    return float(px) if px >= 1e5 and float(px).is_integer() else round(float(f"{px:.5g}"), max_dec)

def round_size(sz, sz_decimals):
    f = 10 ** sz_decimals
    return int(sz * f + 1e-9) / f   # round down
```

## Error messages and fixes

| Error (exact text) | Cause | Fix |
|---|---|---|
| `Order has invalid price.` | Too many decimals or significant figures | Round with the rule above |
| `Order has invalid size.` | More decimals than `szDecimals` | Round size down to `szDecimals` |
| `Order must have minimum value of $10. asset=N` | Notional under $10 | Raise size; recheck after rounding down |
| `Post only order would have immediately matched, bbo was BID@ASK. asset=N` | ALO price crosses the book | Quote at or behind the best bid/ask |
| `Order could not immediately match against any resting orders. asset=N` | IOC found no liquidity at that price | Widen slippage or use a resting order |
| `Insufficient margin to place order. asset=N` | Not enough collateral at current leverage | Smaller size, more collateral, or `update_leverage` |
| `User or API Wallet 0x... does not exist.` | API wallet not approved for this account, or the account has never been funded | Approve the agent from the main wallet; deposit first |
| `Referrer already set` | `setReferrer` on an account that has one | Nothing to do; it can't be changed |

## Fees (base tier, check live values before relying on them)

- Perps: 0.045% taker, 0.015% maker. Spot: 0.070% / 0.040%.
- Most HIP-3 markets on trade.xyz run in growth mode: about 0.009% taker / 0.003% maker, and volume there gets about a tenth of the usual credit toward fee tiers and rate limits.
- Volume tiers, HYPE staking discounts (5% to 40%) and maker rebates by share of maker volume: https://hyperliquidguide.com/guides/fees/fees-explained and https://hyperliquidguide.com/pro
- Your account's live rates: `{"type":"userFees","user":"0x..."}` → `userCrossRate` (taker), `userAddRate` (maker).

## Rate limits (Hyperliquid docs)

- Per address: one action per $1 of cumulative traded volume, plus a 10,000-request starting buffer.
- Per IP: 1,200 REST weight a minute. An order action weighs `1 + floor(batch_size / 40)`, so batch orders.
- WebSocket: 10 connections, 1,000 subscriptions and 2,000 messages a minute per IP. Poll REST no faster than every 1 to 2 seconds per market; subscribe for anything faster.
- Open orders: 1,000, plus one per $5M of volume, up to 5,000.

## Referral codes (measured, with disclosure)

What we measured on testnet on 2026-11-21:

- `setReferrer` signed by an **API wallet** sets the referrer on the main account it trades for.
- It works on an account that has already traded, until about **$10,000 of lifetime volume** (accepted at $5,990, refused at $12,877).
- Past that point the API still answers `ok` but records the referrer as `N/A`, permanently. Re-read `{"type":"referral","user":...}` → `referredBy` to confirm.
- A referral gives the trader 4% off fees on their first $25M of volume. The referrer receives a share of the fees from Hyperliquid. It never costs the trader more.

Disclosure: Hyperliquid Guide's starter repo applies its code `CONCEPT211` to accounts that have no referrer, prints that it did so, and skips it when `HL_REFERRAL=off`. If you build on it, tell your user and keep the opt-out.

## Safety defaults worth keeping

- Testnet first, then mainnet with the smallest size that clears the $10 minimum.
- Cancel open orders on exit. Put stops on the exchange, not only in the bot's memory.
- Keep keys in a gitignored `.env`. Never print or commit them.
- Cap order size, position size and daily loss in code, not just in config.

## More

- Starter repo: https://github.com/Hyperliquidguide/hyperliquid-starter-bots
- API guide: https://hyperliquidguide.com/guides/trading/hyperliquid-api-guide.md
- Market making: https://hyperliquidguide.com/guides/trading/hyperliquid-market-making-guide.md
- Every guide as Markdown: https://hyperliquidguide.com/llms.txt and https://hyperliquidguide.com/llms-full.txt
- Hyperliquid's own docs: https://hyperliquid.gitbook.io/hyperliquid-docs
