# Hyperliquid API

> Zero-custody REST builder API for Hyperliquid, built by Quicknode. Sign transactions locally, send via API. Trade perpetuals, spot, and HIP-3 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, and HIP-3 markets
- Order format: Human-readable (`asset`, `side`, `price`, `size`, `tif`) or native wire format

## REST Endpoints

All exchange operations (orders, cancels, modifies, approvals) 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, and HIP-3 markets (optional `?dex=` filter) |
| `/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 |
| `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" |

Both formats are accepted. `grouping` defaults to "na" if omitted. `reduce_only` defaults to false.

## 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 — Orders

- **Build order**: POST /exchange with `{"action": {"type": "order", "orders": [{"asset": "BTC", "side": "buy", "price": "100000", "size": "0.001", "tif": "ioc"}]}}`. Returns `{ hash, nonce, action, isSpot, builderFee, builder }`.
- **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 }`.

## 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 }`. Optional `?dex=` filter.
- **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