---
name: hyperliquid-api
description: Work with the Hyperliquid public API, HyperCore REST endpoints, exchange actions, WebSocket subscriptions, signing, nonce handling, rate limits, and trading/request examples. Use when building, debugging, reviewing, or explaining Hyperliquid API integrations, including info endpoint queries, signed exchange endpoint actions, API wallet setup, order/cancel payloads, spot/perp asset IDs, WebSocket feeds, and latency-sensitive trading clients.
license: MIT
---

# Hyperliquid API

## Overview

Use this skill to design, debug, or review Hyperliquid API integrations. Prefer official SDKs for signed actions; when implementing directly, verify action payloads, signing scheme, nonces, asset IDs, rate limits, and endpoint-specific request body shapes before producing code.

## Workflow

1. Classify the task:
   - Read-only market/account data: use `POST /info` and read `references/rest-endpoints.md`.
   - Trading, transfers, staking, vaults, API wallets, builder fees, or other signed actions: use `POST /exchange` and read `references/rest-endpoints.md` plus `references/signing-limits-errors.md`.
   - Streaming data or low-latency user/order events: read `references/websocket.md`.
   - Asset naming, precision, base URLs, notation, or account activation: read `references/api-basics.md`.
2. Confirm network and URL:
   - Mainnet REST: `https://api.hyperliquid.xyz`
   - Testnet REST: `https://api.hyperliquid-testnet.xyz`
   - Mainnet WebSocket: `wss://api.hyperliquid.xyz/ws`
   - Testnet WebSocket: `wss://api.hyperliquid-testnet.xyz/ws`
3. For signed exchange actions, prefer Hyperliquid's Python SDK signing helpers. If manual signing is unavoidable, compare against SDK behavior exactly and lower-case addresses before signing/sending.
4. For live or ambiguous details, refresh the official GitBook Markdown with `scripts/query_docs.py` instead of relying only on the bundled summaries.

## References

- `references/api-basics.md`: base URLs, notation, asset IDs, tick/lot size, API wallets, nonces, activation gas, and latency notes.
- `references/rest-endpoints.md`: `POST /info` endpoint catalog and `POST /exchange` signed action catalog.
- `references/websocket.md`: WebSocket connection rules, subscription types, post request format, and heartbeat/timeout rules.
- `references/signing-limits-errors.md`: signing pitfalls, rate limits, user limits, priority fees, and common order/cancel errors.

## Official Docs Refresh

Use the helper to fetch a current official doc page:

```bash
python scripts/query_docs.py for-developers/api/info-endpoint.md
```

Ask GitBook a narrow question against a page:

```bash
python scripts/query_docs.py for-developers/api/exchange-endpoint.md --ask "What fields are required for approveAgent?"
```

If local certificate validation fails in the runtime, add `--insecure` for public documentation lookup only.

## Guardrails

- Do not use an API wallet address to query account state; query the actual master, subaccount, or vault address.
- Treat numeric price/size strings carefully. Remove trailing zeroes for signing, respect `szDecimals`, and validate price significant figures before sending orders.
- Use a unique, monotonically increasing millisecond nonce per signer. Separate high-throughput trading processes with separate API wallets.
- Handle exchange responses as arrays matching the batch length, but also handle single pre-validation errors that reject the whole batch.