Authentication

Public market data and account queries do not require a signature. Exchange actions, such as placing or cancelling an order, require a private key or signer.

Read account state

Set accountAddress to query an account without configuring a signer. This example reads its perpetual positions.

import { RestClient } from '@siebly/hyperliquid-api';

async function main() {
  const accountAddress = process.env.HYPERLIQUID_ACCOUNT_ADDRESS;
  if (!accountAddress) throw new Error('Set HYPERLIQUID_ACCOUNT_ADDRESS.');

  const client = new RestClient({ accountAddress });
  const account = await client.getPerpAccountSummary();
  console.log(account.assetPositions);
}

main().catch((error) => {
  console.error(error);
  process.exitCode = 1;
});

Set HYPERLIQUID_ACCOUNT_ADDRESS before running the example. Perpetual positions are in assetPositions. For unified accounts or portfolio margin, getSpotBalances() returns balances across Spot and perps.

Account methods resolve addresses in this order: request user, vaultAddress, accountAddress, then the configured signer.

getPerpAccountSummary · AccountRequest

Configure a private key

Pass privateKey and the managed account address to RestClient. This example configures Testnet.

import { RestClient } from '@siebly/hyperliquid-api';

export function createTradingClient() {
  const privateKey = process.env.HYPERLIQUID_PRIVATE_KEY;
  const accountAddress = process.env.HYPERLIQUID_ACCOUNT_ADDRESS;
  if (!privateKey || !accountAddress) {
    throw new Error('Set HYPERLIQUID_PRIVATE_KEY and HYPERLIQUID_ACCOUNT_ADDRESS.');
  }

  return new RestClient({
    testnet: true,
    privateKey,
    accountAddress,
  });
}

Keep the private key in a server-side environment variable, outside source files and browser bundles.

API wallets and vaults

An API wallet signs for another account. Set accountAddress to the managed account so queries return its balances and positions.

vaultAddress selects a vault or subaccount for supported actions and takes precedence over accountAddress for account queries. The signer must be authorized for the requested action. See the Hyperliquid tutorial for the account and API wallet setup workflow.

Custom signers

Pass signer instead of privateKey to supply a HyperliquidSigner. The interface requires signTypedData() and supports an address or getAddress() for address resolution. An ethers Wallet can satisfy this interface.

WebsocketAPIClient accepts the same signing options. WebsocketClient subscriptions use account addresses and do not need a private key.

RestClientOptions · WebsocketAPIClientOptions · Order results and errors