Hyperliquid JavaScript SDK
Use @siebly/hyperliquid-api to read Hyperliquid market data, manage orders, and consume streams from Node.js. JavaScript and TypeScript use the same clients; request and response types are included.
Choose a client
- RestClient
- Market data, account state, orders, transfers, staking, vaults, subaccounts, HIP-3, and other Info and Exchange operations
- WebsocketClient
- Public market data and address-scoped account subscriptions
- WebsocketAPIClient
- Awaitable Info and signed Exchange requests over the WebSocket POST protocol
Make a first public request
This SDK is an unpublished preview and requires repository access. Contact Siebly for preview access. If you already have access, use Node.js 24+ and npm 11+ to clone and build it with the commands below. Save the example in that repository as an .mjs file.
git clone https://github.com/sieblyio/hyperliquid-api.git
cd hyperliquid-api
npm ci
npm run build
REST walkthrough
After building the preview SDK, read public BTC perpetual data with RestClient. These public requests require no credentials.
Save the code as rest-public.mjs and run:
node rest-public.mjs
import { RestClient } from '@siebly/hyperliquid-api'; const client = new RestClient(); async function main() { try { const status = await client.getExchangeStatus(); console.log('Exchange status:', status); } catch (error) { console.error('Exchange-status request failed:', error); } try { const mids = await client.getAllMids(); console.log('BTC midpoint:', mids.BTC); } catch (error) { console.error('Midpoint request failed:', error); } try { const metadata = await client.getPerpMetadata(); const btc = metadata.universe.find((asset) => asset.name === 'BTC'); console.log('BTC perpetual metadata:', btc); } catch (error) { console.error('Perpetual metadata request failed:', error); } try { const orderBook = await client.getOrderBook({ coin: 'BTC', }); console.log('Best bid:', orderBook?.levels[0][0]); console.log('Best ask:', orderBook?.levels[1][0]); } catch (error) { console.error('Order-book request failed:', error); } try { const candles = await client.getCandles({ coin: 'BTC', interval: '1h', startTime: Date.now() - 24 * 60 * 60 * 1000, }); console.log('Latest hourly candle:', candles.at(-1)); } catch (error) { console.error('Candle request failed:', error); } try { const trades = await client.getRecentTrades({ coin: 'BTC', }); console.log('Most recent trade:', trades[0]); } catch (error) { console.error('Recent-trade request failed:', error); }} main();Expected response
Market values change on each run. These are the fields to check in the logged output.
| Field | Expected result |
|---|---|
| BTC midpoint / metadata | A decimal-string midpoint and a perpetual asset object from universe. |
| Best bid / Best ask | Objects with decimal-string px and sz, plus order count n. |
| Latest hourly candle / Most recent trade | A candle object with millisecond t and T, OHLC and volume strings; a trade with coin, px, sz, and side. |
import { WebsocketClient } from '@siebly/hyperliquid-api'; const client = new WebsocketClient(); async function main() { client .on('open', ({ wsKey }) => { console.log('WebSocket opened:', wsKey); }) .on('reconnecting', ({ wsKey, event }) => { console.log('WebSocket reconnecting:', wsKey, event); }) .on('reconnected', ({ wsKey }) => { console.log('WebSocket reconnected:', wsKey); }) .on('close', ({ wsKey }) => { console.log('WebSocket closed:', wsKey); }) .on('exception', ({ wsKey, event, data }) => { console.error('WebSocket exception:', wsKey, event ?? data); }); client.on('message', ({ channel, data, wsKey }) => { switch (channel) { case 'allMids': console.log('BTC midpoint:', wsKey, data.mids.BTC); break; case 'l2Book': console.log('Best bid:', data.levels[0][0]); console.log('Best ask:', data.levels[1][0]); break; case 'trades': console.log('Trades:', data); break; case 'candle': console.log('One-minute candle:', data); break; } }); client.on('response', ({ channel, data, wsKey }) => { if (channel === 'subscriptionResponse') { console.log('Subscription acknowledgement:', wsKey, data); } }); try { await client.subscribe([ { type: 'allMids' }, { type: 'l2Book', coin: 'BTC' }, { type: 'trades', coin: 'BTC' }, { type: 'candle', coin: 'BTC', interval: '1m' }, ]); } catch (error) { console.error('Market subscription failed:', error); }} main();WebSocket API walkthrough
Read public midpoints through the WebSocket API without a signer. The result maps asset names to decimal-string prices. Close the connection after the request finishes.
Save the code as ws-api-public.mjs and run:
node ws-api-public.mjs
import { WebsocketAPIClient } from '@siebly/hyperliquid-api'; const wsApi = new WebsocketAPIClient(); try { const mids = await wsApi.getAllMids(); console.log('BTC midpoint:', mids.BTC);} finally { wsApi.getWSClient().closeAll();}Hyperliquid API JavaScript Tutorial
A practical JavaScript guide to using @siebly/hyperliquid-api for Hyperliquid market data, account state, perpetual and Spot orders, WebSocket streams, WebSocket API requests, Testnet, proxies, and recovery.
Your app / service
bot, dashboard, worker
@siebly/hyperliquid-api
RestClient, WebsocketClient, WebsocketAPIClient
Hyperliquid APIs
Info requests, signed Exchange actions, streaming subscriptions, and WebSocket POST requests
Common Hyperliquid implementation tasks
Start from the behavior you need, not just from REST or WebSocket as a transport. Market-data driven systems should be event driven. Backfill via the REST API once and let WebSockets passively stream new data to you, as it becomes available.
REST API hydration or backfill
Start from the REST API quickstart and endpoint reference, then normalize exchange-specific IDs, timestamps, symbols, and product scope.
Open quickstartWebSocket consumer
Start from the WebSocket quickstart that matches the task boundary, verify subscription acknowledgement semantics, and keep reconnect handling explicit.
Open WebSocket quickstartAgent prompt recipe
Use the AI prompt generator when the task combines REST API hydration, live streams, in-memory state, operational outputs, or strategy code.
Build an agent promptFor coding agents
Give these files to an agent before implementation so it can find the package, examples, task guidance, and safety rules from the normal SDK-page flow.
AI prompt framework
Prompt generator and task recipes for exchange API projects.
llms.txt
Compact discovery file for agents choosing where to start.
llms-full.txt
Full route and implementation guidance index for machine readers.
SDK catalog
Machine-readable package, docs, examples, and task guidance.
Agent skill
Reusable workflow rules for coding agents using exchange APIs.
Hyperliquid JavaScript FAQ
What does the Hyperliquid JavaScript SDK cover?
Hyperliquid supports Spot, Futures, WebSockets, and WebSocket API workflows. The JavaScript guide covers the main REST and WebSocket integration patterns.
How do I authenticate private Hyperliquid API calls in JavaScript?
The public REST example above needs no credentials. For private calls, follow the authentication setup for @siebly/hyperliquid-api in the full tutorial, including the credentials or signer required by your exchange.
Hyperliquid authentication and setupDoes the Hyperliquid JavaScript SDK help with WebSocket connection management?
Yes. Use the SDK WebSocket client for subscriptions, reconnect handling, and stream lifecycle management instead of building raw socket flows yourself.
When should I use the Hyperliquid WebSocket API instead of REST?
Use REST for standard request and response workflows such as account queries and order management. Use the WebSocket API flow when you want persistent low-latency interactions over a connected session.
Direct Example Files
Open the example files below for JavaScript and TypeScript-compatible request, authentication, WebSocket, and Node.js service patterns.