# Hyperliquid API

> Zero-custody REST builder API for Hyperliquid, built by Quicknode. Sign transactions locally, send via API. Trade perpetuals, spot, HIP-3, and HIP-4 markets programmatically. Private keys never leave your machine.

Hyperliquid API uses a build-sign-send pattern: (1) POST /exchange with your action (no signature) to get a hash, (2) sign the hash locally with your private key, (3) POST /exchange again with the action + nonce + signature.

- Endpoint: `https://send.hyperliquidapi.com`
- Protocol: REST API over HTTPS
- Authentication: Client-side EIP-712 signing (no API keys)
- Custody: Fully non-custodial — keys never leave your environment
- Languages: Python, TypeScript, Rust (any HTTP client works)
- Markets: Perpetuals, spot, HIP-3, and HIP-4 markets
- Order format: Human-readable (`asset`, `side`, `price`, `size`, `tif`) or native wire format

## REST Endpoints

All exchange operations (orders, cancels, modifies, approvals, staking deposits, transfers, and account setup actions) go through `POST /exchange`. Build calls omit the signature; send calls include it.

| Endpoint | Method | Description |
|---|---|---|
| `/exchange` | POST | All exchange operations (build without signature, send with signature) |
| `/approval?user=ADDRESS` | GET | Check approval status for an address |
| `/openOrders` | POST | Enriched open orders with pre-built cancel actions |
| `/orderStatus` | POST | Order status with plain-English explanation |
| `/preflight` | POST | Validate an order without signing |
| `/markets` | GET | All perp, spot, HIP-3, and HIP-4 markets (optional `?dex=` filter for HIP-3) |
| `/outcomes` | GET | Enriched HIP-4 outcome metadata with Yes/No aliases and helper action shapes |
| `/outcomes/balances?user=ADDRESS&outcome=ID` | GET | USDH and Yes/No side balances for one outcome |
| `/dexes` | GET | All HIP-3 dex names and indices |
| `/health` | GET | Health check |

## Human-Readable Order Format

Orders accept friendly field names — no SDK needed:

| Human-readable | Wire format | Notes |
|---|---|---|
| `asset`: "BTC" | `a`: "BTC" | Asset name or index. HIP-4 uses `"#10"` or native index `100000010` |
| `side`: "buy" | `b`: true | "buy"/"sell"/"long"/"short" |
| `price`: "100000" | `p`: "100000" | String, omit for market orders |
| `size`: "0.001" | `s`: "0.001" | String |
| `tif`: "ioc" | `t`: {"limit":{"tif":"Ioc"}} | "ioc", "gtc", "alo", or "market" |
| top-level `priorityFee`: 10000 | `grouping`: {"p": 10000} | Optional order priority rate; part of the signed action. Not supported for HIP-4 `#` markets |

Both formats are accepted. `grouping` may be `"na"`, `"normalTpsl"`, `"positionTpsl"`, or `{"p": <priorityFee>}`. `grouping` defaults to "na" if omitted. `reduce_only` defaults to false.

`priorityFee` is Hyperliquid order priority `p`. Hyperliquid interprets it as `p / 100000000` of filled notional, converted to HYPE; `priorityFee: 10000` is 1 bp. Priority fees are charged from undelegated staking HYPE, not spot USDC. If the account does not have enough delegatable/undelegated staking HYPE, Hyperliquid can reject the signed order with "Insufficient delegatable balance for priority order." Use `cDeposit` through `/exchange` to move spot HYPE into undelegated staking HYPE. When using build-sign-send, sign and send the returned action unchanged because `grouping: {"p": ...}` is part of the signed payload. HIP-4 prediction markets (`#` aliases and asset indices >= `100000000`) do not support priority fees; send HIP-4 orders with `grouping: "na"`.

HIP-4 prediction markets settle against USDH. Use spot market `@230` to buy USDH with USDC before trading HIP-4. HIP-4 orders must meet Hyperliquid's 10 USDH minimum order value.

Outcome market mint/burn actions use the same `/exchange` build-sign-send flow. Prefer the customer-friendly helper actions: `outcomeSplit`, `outcomeMerge`, `outcomeMergeQuestion`, and `outcomeNegate`; the API normalizes them into Hyperliquid's raw `userOutcome` action before hashing. Raw `userOutcome` is also accepted with exactly one operation: `splitOutcome: { outcome, amount }`, `mergeOutcome: { outcome, amount }`, `mergeQuestion: { question, amount }`, or `negateOutcome: { question, outcome, amount }`. `mergeOutcome.amount` and `mergeQuestion.amount` may be `null` to mean max. These are L1 actions with no builder fee, signed like cancels/passthrough actions, not HyperliquidTransaction typed-data actions. Use `GET /outcomes` to discover outcome ids and `GET /outcomes/balances?user=ADDRESS&outcome=ID` to check USDH, Yes, and No balances before signing.

## Exchange Actions — Approval

- **Build approval**: POST /exchange with `{"action": {"type": "approveBuilderFee", "maxFeeRate": "1%"}}` (no signature). Returns `{ hash, nonce, details, typedData }`.
- **Send approval**: POST /exchange with `{"action": {"type": "approveBuilderFee", "maxFeeRate": "1%"}, "nonce": ..., "signature": {...}}`. Returns `{ approved, builder, maxFeeRate, user, message, exchangeResponse }`.
- **Check approval**: GET /approval?user=ADDRESS. Returns `{ approved, maxFeeRate, canTradePerps, canTradeSpot, feeBreakdown }`.
- **Build revoke**: POST /exchange with `{"action": {"type": "approveBuilderFee", "maxFeeRate": "0%"}}`. Returns `{ hash, nonce, details, typedData }`.
- **Send revoke**: POST /exchange with same action + nonce + signature. Returns `{ revoked, builder, user, message, exchangeResponse }`.

## Exchange Actions — User-Signed Typed Data

These HyperliquidTransaction EIP-712 actions are built and sent through the same `/exchange` endpoint: `cDeposit`, `cWithdraw`, `tokenDelegate`, `usdClassTransfer`, `usdSend`, `spotSend`, `withdraw3`, `approveAgent`, `sendAsset`, and `userSetAbstraction`.

- **Build priority funding deposit**: POST /exchange with `{"action": {"type": "cDeposit", "wei": 100000}}`. `wei` uses 8 HYPE decimals, so `100000` is `0.001 HYPE`. Worker injects `hyperliquidChain`, `signatureChainId`, and `nonce`, then returns `{ hash, nonce, action, actionType, typedData, nextStep }`.
- **Send priority funding deposit**: POST /exchange with the returned action + nonce + signature. Returns `{ success, user, exchangeResponse }`.
- **Build USD class transfer**: POST /exchange with `{"action": {"type": "usdClassTransfer", "amount": "15", "toPerp": true}}`. Sign and send the returned action unchanged.

`cDeposit` moves spot HYPE into undelegated staking HYPE. Priority orders spend priority gas from undelegated staking HYPE, so customers can fund priority fees without using the Hyperliquid UI.

## Exchange Actions — Orders

- **Build order**: POST /exchange with `{"action": {"type": "order", "orders": [{"asset": "BTC", "side": "buy", "price": "100000", "size": "0.001", "tif": "ioc"}]}}`. HIP-4 prediction markets can use `asset: "#10"` or native `a: 100000010`; do not include `priorityFee` on HIP-4. Optional top-level `priorityFee` encodes `action.grouping` as `{"p": priorityFee}` before signing for supported markets; `10000` is 1 bp. Returns `{ hash, nonce, action, isSpot, builderFee, builder, priorityFee? }`.
- **Build market order**: Same as above but with `"tif": "market"` and no price. Worker auto-computes price from mid + 3% slippage.
- **Build close position**: POST /exchange with `{"action": {"type": "closePosition", "asset": "HYPE", "user": "0x..."}}`. Worker queries position, builds counter-order. Optional `"fraction": 0.5` for partial close. Returns `{ hash, nonce, action, closePositionContext }`.
- **Send order**: POST /exchange with action from build response + nonce + signature. Returns `{ success, user, exchangeResponse }`.
- **Build cancel**: POST /exchange with `{"action": {"type": "cancel", "cancels": [{"a": "BTC", "o": 12345}]}}`. Returns `{ hash, nonce, action, summary, assets }`.
- **Send cancel**: POST /exchange with cancel action + nonce + signature. Returns `{ success, user, exchangeResponse }`.
- **Build modify**: POST /exchange with `{"action": {"type": "batchModify", "modifies": [{"oid": 12345, "order": {"asset": "BTC", "side": "buy", "price": "100001", "size": "0.001", "tif": "gtc"}}]}}`. Returns `{ hash, nonce, action, summary, assets }`.
- **Send modify**: POST /exchange with modify action + nonce + signature. Returns `{ success, user, exchangeResponse }`.
- **List outcomes**: GET /outcomes. Returns `{ quoteToken, outcomes, questions, encoding, actions }`; each outcome includes Yes/No aliases such as `#100`, token names such as `+100`, and asset ids.
- **Outcome balances**: GET `/outcomes/balances?user=ADDRESS&outcome=10`. Returns USDH plus Yes/No side balances for that outcome.
- **Build outcome action**: POST /exchange with `{"action": {"type": "outcomeSplit", "outcome": 10, "amount": "1.0"}}`. For merging, use `{"type": "outcomeMerge", "outcome": 10, "amount": "1.0"}` or omit/set `amount: null` for max. Returns `{ hash, nonce, action, actionType, nextStep }` with canonical `userOutcome` action.
- **Send outcome action**: POST /exchange with userOutcome action + nonce + signature. Returns `{ success, user, exchangeResponse }`.

## Enhanced Endpoints

- **Open orders**: POST /openOrders with `{"user": "0x..."}`. Returns enriched orders with pre-built cancel actions.
- **Order status**: POST /orderStatus with `{"user": "0x...", "oid": 12345}`. Returns status with plain-English explanation.
- **Preflight**: POST /preflight with `{"action": {...}}`. Validates order without signing. Accepts human-readable format.
- **List markets**: GET /markets. Returns `{ perps, spot, hip3, hip4 }`. Optional `?dex=` filter for HIP-3.
- **List outcomes**: GET /outcomes. Returns enriched HIP-4 outcome ids, questions, Yes/No encodings, and helper actions.
- **Outcome balances**: GET `/outcomes/balances?user=ADDRESS&outcome=10`. Returns USDH and Yes/No side balances.
- **List dexes**: GET /dexes. Returns `[{ name, index }, ...]`.

## Fees

- Perpetuals: 0.04% builder fee per trade (on top of Hyperliquid exchange fees)
- Spot: 0.05% builder fee per trade (on top of Hyperliquid exchange fees)
- One-time approval required before trading (POST /exchange with approveBuilderFee action)

## Links

- [Homepage & Documentation](https://hyperliquidapi.com): Full API reference, interactive playground, quickstart guides, and code examples
- [Approve Builder Fee](https://hyperliquidapi.com/approve): One-time wallet approval flow for trading via Hyperliquid API
- [Quicknode](https://www.quicknode.com): Built by Quicknode
- [Discord](https://discord.gg/A77uVda5sS): Community support