An unofficial TypeScript SDK for interacting with the Hyperliquid API.
npm install hyperliquid-ts
import { HyperliquidAPI } from 'hyperliquid-ts';
const api = new HyperliquidAPI('YOUR_PRIVATE_KEY');
// Example: Get all mids
api.info.getAllMids().then(allMids => {
console.log(allMids);
});
Note: Private key is optional but required for authenticated endpoints.
The SDK is structured into several major components/classes covering the main HL APIs:
- info: General information endpoints
- general: General market information
- spot: Spot market information
- perpetuals: Perpetuals market information
- exchange: Trading and account management endpoints
- subscriptions: WebSocket subscriptions
- custom: Custom utility methods and endpoints
Access general market information:
// Get all mids
api.info.getAllMids();
// Get L2 order book
api.info.getL2Book('BTC-PERP');
// Get user open orders
api.info.getUserOpenOrders('USER_ADDRESS');
// Get trade info
const oid = 123456
api.info.getTradeInfo('USER_ADDRESS', oid);
Access information specific to perpetual markets:
// Get perpetuals metadata
api.info.perpetuals.getMeta();
// Get perpetuals metadata and asset contexts
api.info.perpetuals.getMetaAndAssetCtxs();
// Get user's perpetuals clearinghouse state
api.info.perpetuals.getClearinghouseState('USER_ADDRESS');
// Get user funding information
api.info.perpetuals.getUserFunding('USER_ADDRESS', startTime, endTime);
// Get user non-funding ledger updates
api.info.perpetuals.getUserNonFundingLedgerUpdates('USER_ADDRESS', startTime, endTime);
// Get funding history for a specific coin
api.info.perpetuals.getFundingHistory('BTC-PERP', startTime, endTime);
// Get spot metadata
api.info.spot.getSpotMeta();
// Get spot clearinghouse state for a user
api.info.spot.getSpotClearinghouseState('USER_ADDRESS');
// Get spot metadata and asset contexts
api.info.spot.getSpotMetaAndAssetCtxs();
Access and filter the trading leaderboard:
// Get the current leaderboard
api.leaderboard.getLeaderboard();
// Get filtered and sorted leaderboard
api.leaderboard.getFilteredAndSortedLeaderboard({
timeWindow: 'day',
minAccountValue: 1000,
minVolume: 10000,
maxTrades: 100
}, 'pnl');
// Get extended trader information
api.leaderboard.getExtendedTraderInfo(traderEntry, 'week');
// Get a trader's best trade
api.leaderboard.getBestTrade('TRADER_ADDRESS', 'month');
The Leaderboard API also provide methods for more detailed analysis:
// Get a trader's trade count
api.leaderboard.getTraderTradeCount('TRADER_ADDRESS', startTime, endTime);
// Get a trader's open positions
api.leaderboard.getTraderOpenPositions('TRADER_ADDRESS');
Note: The leaderboard data is cached for 24 hours to improve performance. You can manually clear the cache if needed:
await api.leaderboard.clearCache();
The SDK now includes a SymbolConverter to handle any differences between exchange and internal symbol representations:
// Convert from exchange to internal format
api.info.convertSymbol('BTC-0', 'internal');
// Convert from internal to exchange format
api.info.convertSymbol('BTC-PERP-0', 'reverse');
// Get all available assets
const assets = api.info.getAllAssets();
console.log(assets.perp); // List of perpetual assets
console.log(assets.spot); // List of spot assets
Please refer to SYMBOLS.md for more detailed info
Manage orders and perform account actions:
// Place an order
api.exchange.placeOrder({
coin: 'BTC-PERP',
is_buy: true,
sz: 1,
limit_px: 30000,
order_type: { limit: { tif: 'Gtc' } },
reduce_only: false
});
// Cancel an order
api.exchange.cancelOrder({
coin: 'BTC-PERP',
o: 123456 // order ID
});
// Transfer between spot and perpetual accounts
api.exchange.transferBetweenSpotAndPerp(100, true); // 100 USDC from spot to perp
Subscribe to real-time data:
// Subscribe to all mids
api.subscriptions.subscribeToAllMids(data => {
console.log('All mids update:', data);
});
// Subscribe to trades for a specific symbol
api.subscriptions.subscribeToTrades('BTC-PERP', trades => {
console.log('New trades:', trades);
});
// Unsubscribe from trades
api.subscriptions.unsubscribeFromTrades('BTC-PERP', callbackFunction);
// Cancel all orders
api.custom.cancelAllOrders();
// Cancel all orders for a specific symbol
api.custom.cancelAllOrders('BTC-PERP');
// Get all tradable assets
const assets = api.custom.getAllAssets();
The SDK uses custom error types. Wrap API calls in try-catch blocks:
try {
const result = await api.exchange.placeOrder(/* ... */);
} catch (error) {
if (error instanceof HyperliquidAPIError) {
console.error('API Error:', error.message, 'Code:', error.code);
} else {
console.error('Unexpected error:', error);
}
}
The SDK implements rate limiting to comply with API restrictions. You don't need to manage this manually.
The WebSocket connection is managed automatically. Use connect
and disconnect
methods if you need manual control:
await api.connect();
// ... perform operations
api.disconnect();
The SDK provides TypeScript types for all API responses and parameters. Import them as needed:
import type { OrderRequest, UserOpenOrders } from 'hyperliquid-ts';
For detailed API documentation, refer to the official Hyperliquid API docs.
Contributions are welcome! Please submit pull requests or open issues on the GitHub repository.
This project is licensed under the MIT License.