# Hyperliquid API — Full Reference

> Zero-custody REST trading API for Hyperliquid, built by Quicknode. Build an order as plain JSON, sign the returned hash locally, send it back — your private keys never leave your machine. Trade perpetuals, spot, HIP-3, and HIP-4 markets. No SDK, no dependencies: any HTTP client and any EIP-712 signer works.

This is the complete reference in a single file, intended for LLMs and agents. The interactive version is at https://hyperliquidapi.com/docs.

Note: hyperliquidapi.com is an independent service built by Quicknode. It is not affiliated with Hyperliquid Corp or the Hyper Foundation.

## Base

- Endpoint: `https://send.hyperliquidapi.com`
- Protocol: REST over HTTPS
- Authentication: client-side EIP-712 signing (no API keys)
- Custody: non-custodial — keys never leave your environment
- Markets: perpetuals, spot, HIP-3, HIP-4
- Order format: human-readable (`asset`, `side`, `price`, `size`, `tif`) or native wire format
- CORS: enabled (`Access-Control-Allow-Origin: *`), so browser clients can call the API directly
- Geo: restricted jurisdictions (including the US, UK, HK, and sanctioned countries) are blocked at the API level per Hyperliquid's Terms of Use

## The build · sign · send flow

Every write action is three steps through `POST /exchange`:

1. Build — POST the action with no signature. The API resolves the asset, injects the builder fee, applies optional priority, and returns `{ action, hash, nonce, ... }`.
2. Sign — sign the returned hash locally with your private key (any EIP-712 signer). The key never touches the API.
3. Send — POST the returned action + nonce + signature back to `/exchange`. The API verifies approval and forwards to Hyperliquid.

Read and build calls (build requests and the GET helpers) require no signature and can be called directly.

### Full worked example

Step 1 — build (no signature):

```
curl -s -X POST https://send.hyperliquidapi.com/exchange \
  -H "Content-Type: application/json" \
  -d '{"action":{"type":"order","orders":[{"asset":"BTC","side":"buy","price":"100000","size":"0.001","tif":"ioc"}]}}'

→ { "hash": "0x9f2c…", "nonce": 1719000000000, "action": { … }, "isSpot": false, "builderFee": "0.04%", "builder": "0x…" }
```

Step 2 — sign the returned hash locally (pseudocode; use any EIP-712 signer):

```
signature = signTypedData(privateKey, typedData)   // your machine only — the key never leaves
```

Step 3 — send (with signature):

```
curl -s -X POST https://send.hyperliquidapi.com/exchange \
  -H "Content-Type: application/json" \
  -d '{"action":{ …returned action… },"nonce":1719000000000,"signature":{"r":"0x…","s":"0x…","v":28}}'

→ { "success": true, "user": "0x…", "exchangeResponse": { … }, "orders": [ … ] }
```

## Endpoints

All exchange operations go through `POST /exchange`. Build calls omit the signature; send calls include it.

### Exchange — Build (no signature)

POST /exchange without a signature. Accepts human-readable or wire format, injects the builder fee, applies optional priorityFee where supported, and returns the exact action + hash to sign.

- Build Order — `POST /exchange` → `{ hash, nonce, action, isSpot, builderFee, builder, priorityFee? }`
- Build Market Order — `POST /exchange` → `{ hash, nonce, action (with computed price), isSpot, builderFee, builder, appliedSlippage, priorityFee? }`
- Build Close Position — `POST /exchange` → `{ hash, nonce, action, appliedSlippage, closePositionContext, priorityFee? }`
- Build Cancel — `POST /exchange` → `{ hash, nonce, action, summary, assets }`
- Build Modify — `POST /exchange` → `{ hash, nonce, action, summary, assets }`
- Build Approval — `POST /exchange` → `{ hash, nonce, details: { builder, maxFeeRate, chain }, typedData }`
- Build Revoke — `POST /exchange` → `{ hash, nonce, details: { builder, maxFeeRate: "0%", chain }, typedData }`
- Build Outcome Action — `POST /exchange` → `{ hash, nonce, action, actionType, nextStep }`
- Build Priority Funding Deposit — `POST /exchange` → `{ hash, nonce, action, actionType, typedData, nextStep }`
- Build User-Signed Action — `POST /exchange` → `{ hash, nonce, action, actionType, typedData, nextStep }`
- Build Leverage or Margin Action — `POST /exchange` → `{ hash, nonce, action, actionType, nextStep }`

### Exchange — Send (with signature)

POST /exchange with the action from a build response plus its nonce and signature. Verifies approval and priority rules, then forwards to Hyperliquid.

- Send Order — `POST /exchange` → `{ success, user, exchangeResponse, orders? }`
- Send Cancel — `POST /exchange` → `{ success, user, exchangeResponse }`
- Send Modify — `POST /exchange` → `{ success, user, exchangeResponse }`
- Send Approval — `POST /exchange` → `{ approved, builder, maxFeeRate, user, message, exchangeResponse }`
- Send Revoke — `POST /exchange` → `{ revoked, builder, user, message, exchangeResponse }`
- Send Outcome Action — `POST /exchange` → `{ success, user, exchangeResponse }`
- Send User-Signed Action — `POST /exchange` → `{ success, user, exchangeResponse }`
- Send Leverage or Margin Action — `POST /exchange` → `{ success, user, exchangeResponse }`

### Enhanced endpoints (read-only helpers)

- Check Approval — `GET /approval?user=0x…` → `{ approved, maxFeeRate, maxFeeRaw, canTradePerps, canTradeSpot, feeBreakdown }`
- Open Orders — `POST /openOrders` → `{ orders, count, cancelActions: { all, byAsset } }`
- Order Status — `POST /orderStatus` → `{ status, explanation, coin, asset, name, isSpot, order, statusTimestamp }`
- Preflight — `POST /preflight` → `{ valid, errors, assetInfo, estimatedFee, priorityFee?, isSpot }`
- List Markets — `GET /markets` → `{ perps, spot, hip3, hip4 }` (optional `?dex=` filter for HIP-3)
- List Outcomes — `GET /outcomes` → `{ quoteToken, outcomes, questions, encoding, actions }`
- Outcome Balances — `GET /outcomes/balances?user=0x…&outcome=10` → `{ user, outcome, quote, yes, no, actions }`
- List Dexes — `GET /dexes` → `[{ name, index }, …]`
- Health — `GET /health`

## Order action — body fields

- `action.orders[].asset` (string) — asset name, e.g. `"BTC"`, `"HYPE"`, `"xyz:SILVER"`, or `"#100"` (HIP-4; the alias encodes outcomeId × 10 + side, side 0 = Yes and 1 = No, so `#100` is outcome 10's Yes side)
- `action.orders[].side` (string) — `"buy"` or `"sell"`
- `action.orders[].price` (string) — limit price (omit for market orders)
- `action.orders[].size` (string) — order size
- `action.orders[].tif` (string) — `"ioc"`, `"gtc"`, `"alo"`, or `"market"`
- `priorityFee` (number|string, optional) — IOC-only priority rate `p`, max 80000; `p=10000` is 1 bp. Encoded as `action.grouping {"p": priorityFee}` before signing
- `vaultAddress` (string, optional) — trade on behalf of a vault
- `slippage` (number, optional) — market-order slippage tolerance (default 3%, range 0.1%–10%)

Both human-readable and native wire format are accepted. `grouping` may be `"na"`, `"normalTpsl"`, `"positionTpsl"`, or `{"p": <priorityFee>}`; it defaults to `"na"`. `reduce_only` defaults to false.

## Priority fees

`priorityFee` is Hyperliquid order priority `p`. Hyperliquid interprets it as `p / 100000000` of filled notional, converted to HYPE; `priorityFee: 10000` is 1 bp and `80000` is the maximum. Priority fees are valid only when every order is IOC (worker market orders and `closePosition` generate IOC limit orders). They are charged from undelegated staking HYPE, not spot USDC. If the account lacks delegatable/undelegated staking HYPE, Hyperliquid can reject 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 `#` markets do not support priority fees; send HIP-4 orders with `grouping: "na"`.

## HIP-3 and HIP-4 markets

- HIP-3: community-deployed perp/spot markets, traded through the same endpoints. Asset names look like `"xyz:SILVER"`.
- HIP-4: on-chain outcome markets. They quote and settle in USDC. Reference a side with a `#` alias encoding outcomeId × 10 + side (0 = Yes, 1 = No): `"#100"` is outcome 10's Yes side, native asset index `100000100`, and meet Hyperliquid's minimum order value. Priority fees are not supported on HIP-4 `#` markets — send them with `grouping: "na"`.

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. Splitting an outcome spends USDC and mints equal Yes/No shares. Raw `userOutcome` is also accepted with exactly one operation: `splitOutcome`, `mergeOutcome`, `mergeQuestion`, or `negateOutcome` (`amount` may be `null` to mean max on merges). Use `GET /outcomes` to discover outcome ids and `GET /outcomes/balances?user=0x…&outcome=…` to check quote and Yes/No side balances before signing.

## Errors

Every error uses the appropriate HTTP status code and includes `error`, `message`, and `guidance` with exactly what to do next.

- 403 `NOT_APPROVED` — not approved / fee too low → run the approval flow or visit `/approve`
- 422 `BUILDER_MISMATCH` — builder mismatch → POST `/exchange` without a signature; it injects the correct builder
- 422 `SIGNATURE_INVALID` — invalid signature → sign the exact hash from the build response (`r`/`s`: 0x hex, `v`: 27 or 28)
- 422 `HL_EXCHANGE_*` — exchange rejection → see `errorCode` and `actionRequired` in the response
- 400 `INVALID_JSON` — invalid request body → send valid JSON to the correct endpoint
- 422 `INVALID_PARAMS` — invalid params → check required fields and types
- 500 `INTERNAL_ERROR` — internal error → retry in a few seconds

Errors that are fixable client-side include recovery data. For example, a 403 `NOT_APPROVED` response carries an `approvalRequired` block with `{ hash, nonce, maxFeeRate, typedData, approveUrl, nextStep }` so a client can sign and complete approval inline.

## Fees

Two fees apply per trade: our builder fee (injected into your order) and Hyperliquid's own exchange fee (maker/taker, charged by the protocol).

Builder fee (charged by us, injected into each order):
- Perpetuals: 0.04% (protocol max 0.1%)
- Spot: 0.05% (protocol max 1%)

Exchange fee (charged by Hyperliquid, by volume tier):
- Perpetuals: taker 0.045%, maker 0.015%
- Spot: taker 0.070%, maker 0.040%

You approve a `maxFeeRate` ceiling (e.g. "1%") for the builder fee; the actual builder fee is always within your approved limit, and you can revoke at any time.

## FAQ

- What is Hyperliquid API? A zero-custody REST builder API for Hyperliquid, built by Quicknode. Trade perpetuals, spot, HIP-3, and HIP-4 markets programmatically while your private keys never leave your machine.
- How does the build-sign-send pattern work? Three steps: build (POST with no signature, get the action + hash), sign (sign the hash locally with your key), send (POST the action + nonce + signature). Your private key is never transmitted.
- What are the trading fees? A builder fee of 0.04% on perpetual trades and 0.05% on spot trades, on top of Hyperliquid's native exchange fees.
- Do I need an SDK or any dependencies? No. It is a plain REST API over HTTPS — no SDK to install and no dependencies. Any language with an HTTP client and an EIP-712 signer can integrate.
- Is Hyperliquid API custodial? No. It is fully non-custodial: you sign every transaction locally, and the API only forwards your pre-signed transactions to Hyperliquid.
- How do I add a priority fee to an order? Set the top-level `priorityFee` on an IOC order. The API encodes it into `action.grouping` as `{ p: priorityFee }` before hashing, so sign and send the returned action unchanged. `10000` is 1 bp, max is 80000. Not supported on HIP-4 `#` markets.
- How do I fund order priority fees? Priority fees are paid from undelegated staking HYPE. Build a `cDeposit` action through `/exchange`, sign the returned hash, then send it (e.g. `wei: 100000` moves 0.001 HYPE into undelegated staking HYPE).
- What markets can I trade? Perpetuals, spot, HIP-3 markets, and HIP-4 outcome markets. HIP-4 uses `#` aliases encoding outcomeId × 10 + side (0 = Yes, 1 = No), like `#100`, or native indices like `100000100`, and quotes/settles in USDC.
- How do I trade HIP-4 outcome markets? Use the same `/exchange` build-sign-send flow, set the asset to a `#` alias or native index, and meet Hyperliquid's minimum order value. HIP-4 markets settle in USDC; send them with `grouping: "na"` because priority fees are not supported.
- How do I cancel or modify an order? Send a cancel with the order id, or use `batchModify` — both follow the same build-sign-send pattern as placing orders.
- Do I need to share my private key? No. Your private key never leaves your machine; the API cannot execute anything without your signature.

## Links

- Homepage: https://hyperliquidapi.com
- Docs (interactive): https://hyperliquidapi.com/docs
- Approve & fund: https://hyperliquidapi.com/approve
- Quicknode: https://www.quicknode.com
- Discord: https://discord.gg/A77uVda5sS

Powered by Quicknode.