dexhyper

Simple Hyperliquid API wrapper for Node.js.

Features

• Public /info API requests
• Signed /exchange API requests
• Main account trading
• Vault trading
• Automatic Hyperliquid signature generation
• Symbol → Asset ID conversion
• Supports:
  • Normal perps (BTC, ETH, etc.)
  • Spot markets (HYPE/USDC, PURR/USDC, etc.)
  • HIP dex markets (xyz:XYZ100, hyna:BTC, etc.)

Installation

npm install dexhyper

Import

const api = require("dexhyper");

Public API Requests

No private key required.

const api = require("dexhyper");

const ac = new api();

async function main() {
  const r = await ac.info({
    type: "allMids",
  });

  console.log(r);
}

main();

Or:

const r = await ac.post("/info", {
  type: "allMids",
});

Trading

Create a client using your private key.

const api = require("dexhyper");

const ac = new api("YOUR_PRIVATE_KEY");

Place an order:

const action = {
  type: "order",
  orders: [
    {
      a: 0,
      b: true,
      p: "70000",
      s: "0.001",
      r: false,
      t: {
        limit: {
          tif: "Gtc",
        },
      },
    },
  ],
  grouping: "na",
};

const r = await ac.exchange(action);

console.log(r);

Vault Trading

Use a vault address:

const ac = new api("YOUR_PRIVATE_KEY", "0xVaultAddress");

Trade normally:

await ac.exchange(action);

Or override vault per request:

await ac.exchange(action, {
  vaultAddress: "0xVaultAddress",
});

Symbol → Asset ID Conversion

Build the symbol map once:

const api = require("dexhyper");

global.symMap = await api.buildSymMap();

Convert symbols to Hyperliquid asset IDs:

api.symId("BTC");
api.symId("ETH");
api.symId("BTC-USDC");
api.symId("BTC-USDE");
api.symId("HYPE/USDC");
api.symId("BTC/USDC");
api.symId("xyz:XYZ100");
api.symId("hyna:BTC-USDE");

Example:

global.symMap = await api.buildSymMap();

console.log(api.symId("BTC"));
console.log(api.symId("HYPE/USDC"));
console.log(api.symId("xyz:XYZ100"));

Trading Using Symbols

const api = require("dexhyper");

const ac = new api("YOUR_PRIVATE_KEY");

global.symMap = await api.buildSymMap();

const action = {
  type: "order",
  orders: [
    {
      a: api.symId("xyz:XYZ100"),
      b: true,
      p: "30000",
      s: "0.01",
      r: false,
      t: {
        limit: {
          tif: "Gtc",
        },
      },
    },
  ],
  grouping: "na",
};

await ac.exchange(action);

Supported Symbol Formats

Normal Perps

api.symId("BTC");
api.symId("ETH");
api.symId("SOL");

Perp UI Aliases

Automatically converted:

api.symId("BTC-USDC");
api.symId("BTC-USDE");
api.symId("BTC-USDH");

Spot

api.symId("HYPE/USDC");
api.symId("PURR/USDC");
api.symId("BTC/USDC");

BTC/USDC automatically maps to UBTC/USDC.

ETH/USDC automatically maps to UETH/USDC.

HIP Dex Markets

api.symId("xyz:XYZ100");
api.symId("xyz:AAPL");
api.symId("hyna:BTC");

HIP Dex UI Aliases

Automatically converted:

api.symId("hyna:BTC-USDE");
api.symId("hyna:ETH-USDE");

API

Constructor

new api((privateKey = ""), (vaultAddress = null), {
  mainnet: true,
});

Examples:

const ac = new api();

const ac = new api("PRIVATE_KEY");

const ac = new api("PRIVATE_KEY", "0xVaultAddress");

ac.post()

await ac.post(path, payload);

Example:

await ac.post("/info", {
  type: "allMids",
});

ac.info()

Shortcut for:

ac.post("/info", payload);

Example:

await ac.info({
  type: "meta",
});

ac.exchange()

Signs and sends a Hyperliquid exchange action.

await ac.exchange(action);

Optional parameters:

await ac.exchange(action, {
  vaultAddress,
  expiresAfter,
});

api.buildSymMap()

Builds a symbol map used by symId().

global.symMap = await api.buildSymMap();

Must be called once before using symId().

api.symId()

Converts a symbol into a Hyperliquid asset ID.

const a = api.symId("BTC");

Examples:

api.symId("BTC");
api.symId("BTC-USDC");
api.symId("HYPE/USDC");
api.symId("xyz:XYZ100");

Notes

• /info requests are public.
• /exchange requests require a private key.
• buildSymMap() only uses public APIs.
• Always keep your private key secure.
• Never commit private keys to GitHub.
• Never publish private keys to npm.