@navalabs/hyperliquid-adapter

@navalabs/hyperliquid-adapter

Nava Hyperliquid adapter — pure perps protocol primitives, Nava-verified writes, plus MCP and CLI integrations for the Nava SDK.

pnpm add @navalabs/hyperliquid-adapter

This package is a complete install. It ships the nava binary and the nava-mcp server, and depends on @navalabs/sdk for the runtime and the six base verification operations — no second package to add.

Installing other adapters alongside it works the same way. They share one nava and one nava-mcp, and every installed protocol is reachable from whichever copy your package manager links.

Operations

Eight, under the same names on both surfaces:

Operation	Kind	CLI	MCP tool
get-markets	read	nava hyperliquid get-markets	hyperliquid.get-markets
get-account-summary	read	nava hyperliquid get-account-summary	hyperliquid.get-account-summary
get-positions	read	nava hyperliquid get-positions	hyperliquid.get-positions
get-open-orders	read	nava hyperliquid get-open-orders	hyperliquid.get-open-orders
get-price	read	nava hyperliquid get-price	hyperliquid.get-price
place-order	verified-write	nava hyperliquid place-order	hyperliquid.place-order
cancel-order	verified-write	nava hyperliquid cancel-order	hyperliquid.cancel-order
update-leverage	verified-write	nava hyperliquid update-leverage	hyperliquid.update-leverage

nava hyperliquid get-markets --filter BTC
nava hyperliquid place-order --asset BTC --side sell --size 0.01 \
  --order-type limit --limit-price 64000 --tif Gtc \
  --mode dry-run --reason 'Trim BTC exposure per momentum signal'

NAVA_PROTOCOLS=hyperliquid nava-mcp

The CLI has no --network flag — network is environment-only over the CLI, while MCP callers pass an optional network field per call.

The three writes call Guardian themselves

place-order, cancel-order, and update-leverage are the only mutating operations, and all three submit to Guardian and wait for a verdict internally. There is no separate *Verified variant. Do not call request-verification separately for a Hyperliquid action: the EIP-712 payload is constructed internally, so a hand-rolled proposal would not be the action that gets signed.

• --reason / reason is required on all three, and becomes the audit prompt recorded against the verdict.
• mode: 'dry-run' verifies and stops without signing or submitting. direct (the default) signs and submits only after an APPROVED verdict.
• A terminal UNDECIDED verdict is rejected unless allowUndecidedExecution (or HYPERLIQUID_ALLOW_UNDECIDED_EXECUTION / HL_ALLOW_UNDECIDED_EXECUTION) is true, in which case direct signs and submits after UNDECIDED too. Any other non-terminal or REJECTED status always fails regardless of the flag.

See node_modules/@navalabs/sdk/skills/nava/references/guardian.md for the full verification contract.

Assets, sizes, and prices

Assets are Hyperliquid perp symbols (BTC, ETH, DYDX), matched case-insensitively — never contract addresses and never the numeric asset index; the adapter resolves the index itself from the venue's meta universe.

Sizes and prices are positive decimal strings in whole units ("0.01", "64250.5"). The adapter truncates size to the asset's szDecimals and price to Hyperliquid's tick rules, and rejects a value that truncates to zero rather than rounding it up.

TypeScript

import { NavaClient } from '@navalabs/sdk';
import { privateKeyToAccount } from 'viem/accounts';
import { createHyperliquidTools } from '@navalabs/hyperliquid-adapter';

const tools = createHyperliquidTools({
  privateKey: process.env.HYPERLIQUID_PRIVATE_KEY!,
  walletAddress: process.env.HYPERLIQUID_WALLET_ADDRESS!,
  nava: new NavaClient({
    apiKey: process.env.NAVA_API_KEY!,
    walletAddress: process.env.WALLET_ADDRESS!,
    // Omit `baseUrl` to use https://internal.navalabs.dev/api
  }),
  privateKeyToAccount,
});

const markets = await tools.getMarkets({ filter: 'BTC' });

Import	Contents
@navalabs/hyperliquid-adapter	createHyperliquidTools and its config types. Start here.
/adapter	The runtime factories alone: createHyperliquidTools, createHyperliquidReadTools, createHyperliquidWriteTools, parseHyperliquidVerificationMode.
/actions	Pure primitives only: buildPlaceOrderAction, buildCancelOrderAction, buildUpdateLeverageAction, buildHyperliquidTypedData, hyperliquidActionHash. No signing, no submission.
/mcp	createProtocolRegistrarFactory and the advertised zod schemas — what nava-mcp imports.
/cli	hyperliquidCliModule plus the argv parsers — what the nava bin imports.

Asset/index resolution, signing, and submission against @nktkas/hyperliquid are internal to the runtime tools, not part of /actions.

Environment

Reads need no credentials at all — get-markets, get-price, and, when an address is passed explicitly, get-account-summary, get-positions, get-open-orders.

Variable	Required	Description
HYPERLIQUID_PRIVATE_KEY (or HL_AGENT_PRIVATE_KEY, PRIVATE_KEY)	verified writes	EOA or agent private key used for order signing.
HYPERLIQUID_WALLET_ADDRESS (or HL_WALLET_ADDRESS, WALLET_ADDRESS)	verified writes, and reads that omit an address	Default wallet for reads and writes.
HYPERLIQUID_NETWORK (or HL_NETWORK)	no	mainnet (default) or testnet. CLI-only — MCP callers pass network per call.
HYPERLIQUID_MODE (or HL_MODE)	no	Default execution mode when a call omits it.
HYPERLIQUID_ALLOW_UNDECIDED_EXECUTION (or HL_ALLOW_UNDECIDED_EXECUTION)	no	true lets a terminal UNDECIDED verdict through to execution by default.
NAVA_API_KEY	to run nava-mcp at all	Nava Guardian key. Required globally by the MCP server, not just for writes.
NAVA_BASE_URL	no	Nava API origin. Defaults to https://internal.navalabs.dev/api.
WALLET_ADDRESS	to run nava-mcp at all	Wallet registered with Nava Guardian. Required globally by the MCP server.

Full parameter reference

Every option, requirement, default, and worked example lives in the bundled Nava skill that ships with @navalabs/sdk, at node_modules/@navalabs/sdk/skills/nava/references/hyperliquid.md. There is no per-command --help; that file is the parameter reference.