Hyperliquid SDK

The SDK automatically refreshes asset maps (used for symbol conversion) every 60 seconds. To prevent rate limiting or reduce overhead when running multiple instances, you can disable or control this behavior.

When to disable:

• Running multiple SDK instances from the same IP.
• Only performing order placement/cancellation without needing symbol conversion.
• Experiencing HTTP 429 (rate limit) errors.
• Using external price oracles.

Configuration and Runtime Methods:

• disableAssetMapRefresh: true: Disables automatic refresh in the constructor.
• assetMapRefreshIntervalMs: <number>: Sets the interval (e.g., 300000 for 5 minutes).
• sdk.isAssetMapRefreshEnabled(): Checks current status.
• sdk.disableAssetMapRefresh(): Disables at runtime.
• sdk.enableAssetMapRefresh(): Enables at runtime.
• sdk.setAssetMapRefreshInterval(ms): Updates interval at runtime.
• await sdk.refreshAssetMapsNow(): Triggers a manual refresh.

const sdk = new Hyperliquid({
  privateKey: 'your-private-key',
  testnet: false,
  enableWs: false,
  disableAssetMapRefresh: true,
});

// Manual refresh if needed
await sdk.refreshAssetMapsNow();

For high-frequency trading, the SDK allows executing exchange methods over WebSocket instead of HTTP using sdk.wsPayloads. This provides lower latency and handles signing/nonces automatically.

Requirements:

• enableWs: true must be set in the constructor.
• privateKey must be provided for authenticated exchange methods.
• You must call await sdk.connect() and ensure the connection is established before sending requests.

Core Method Groups:

• Order Management: placeOrder, cancelOrder, cancelAllOrders, modifyOrder, batchModifyOrders.
• TWAP: placeTwapOrder, cancelTwapOrder.
• Account/Leverage: updateLeverage, updateIsolatedMargin.
• Transfers: transferBetweenSpotAndPerp, usdTransfer, spotTransfer, initiateWithdrawal, vaultTransfer.
• Advanced: approveAgent, approveBuilderFee, scheduleCancel, setReferrer.

const { Hyperliquid } = require('hyperliquid');

async function testWebSocketPostRequests() {
  const sdk = new Hyperliquid({
    enableWs: true,
    privateKey: 'your_private_key',
    testnet: false,
  });

  try {
    await sdk.connect();
    await new Promise(resolve => setTimeout(resolve, 1000)); // Wait for connection

    // Example: Place Order
    const orderResponse = await sdk.wsPayloads.placeOrder({
      coin: 'BTC-PERP',
      is_buy: true,
      sz: '0.001',
      limit_px: '50000',
      order_type: { limit: { tif: 'Gtc' } },
      reduce_only: false,
    });
    console.log('Place Order Response:', orderResponse);

    // Example: Cancel All Orders
    const cancelAllResponse = await sdk.wsPayloads.cancelAllOrders();
    console.log('Cancel All Orders Response:', cancelAllResponse);

  } catch (error) {
    console.error('Error:', error);
  } finally {
    sdk.disconnect();
  }
}

When performing spot token operations (like sdk.exchange.spotTransfer), the token parameter must follow a specific string format: "TOKEN_NAME:TOKEN_ADDRESS".

To ensure correctness, you can retrieve the required metadata using sdk.info.spot.getSpotMeta(). Each token object in the returned array contains a tokenId field which serves as the address.

Correct Format Example: "PURR:0xeb62eee3685fc4c43992febcd9e75443"

// Transfer spot tokens to another address
// IMPORTANT: Token format must be "TOKEN_NAME:TOKEN_ADDRESS"
sdk.exchange
  .spotTransfer(
    '0x1234567890123456789012345678901234567890', // destination address
    'PURR:0xeb62eee3685fc4c43992febcd9e75443', // token format: "NAME:ADDRESS"
    '1.0' // amount as string
  )
  .then(transferResult => {
    console.log(transferResult);
  })
  .catch(error => {
    console.error('Error transferring spot tokens:', error);
  });