# @navalabs/hyperliquid-adapter

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

Latest version **0.9.0** (published 2026-09-23) · MIT license · 0 weekly downloads

## Install

```sh
npm install @navalabs/hyperliquid-adapter
pnpm add @navalabs/hyperliquid-adapter
yarn add @navalabs/hyperliquid-adapter
bun add @navalabs/hyperliquid-adapter
```

Provides the commands `nava`, `nava-mcp`.

## Health

**Score 70/100 (B)** — status: active.

Positive: has types; esm support; no vulnerabilities; recently updated; high maintenance score; high quality score.

Warnings: low downloads; pre 1.0.

## Facts

| | |
|---|---|
| Version | 0.9.0 |
| Published | 2026-09-23 |
| First published | 2026-05-28 |
| Weekly downloads | 0 |
| License | MIT |
| TypeScript types | bundled |
| Module format | ESM + CommonJS |
| Node | >=18.0.0 |
| Dependencies | 7 |
| Unpacked size | 268.4 KB |
| Known vulnerabilities | 0 |
| Install scripts | no |
| Maintainers | vmichalik, navalabs-admin, navaarch, tim-nava, bernardo-nava |
| Keywords | nava, hyperliquid, perpetuals, eip712, verified, mcp, adapter |

## Links

- npm: https://www.npmjs.com/package/@navalabs/hyperliquid-adapter
- Repository: https://github.com/navalabs-dev/sdk
- Homepage: https://github.com/navalabs-dev/sdk#readme
- Issues: https://github.com/navalabs-dev/sdk/issues
- npm.io page: https://npm.io/package/@navalabs/hyperliquid-adapter

## Dependencies (7)

- [zod](https://npm.io/package/zod.md) ^3.24.3
- [viem](https://npm.io/package/viem.md) 2.47.6
- [dotenv](https://npm.io/package/dotenv.md) ^16.0.0
- [@navalabs/sdk](https://npm.io/package/@navalabs/sdk.md) 0.16.0
- [@navalabs/sdk-core](https://npm.io/package/@navalabs/sdk-core.md) 0.16.0
- [@nktkas/hyperliquid](https://npm.io/package/@nktkas/hyperliquid.md) ^0.32.2
- [@modelcontextprotocol/sdk](https://npm.io/package/@modelcontextprotocol/sdk.md) ^1.12.1

## Alternatives

- [@sindresorhus/slugify](https://npm.io/package/@sindresorhus/slugify.md) — 3.7M weekly downloads
- [solid-js](https://npm.io/package/solid-js.md) — 2.7M weekly downloads
- [expo-glass-effect](https://npm.io/package/expo-glass-effect.md) — 2.5M weekly downloads
- [nanoassert](https://npm.io/package/nanoassert.md) — 780.8K weekly downloads
- [@ffmpeg/ffmpeg](https://npm.io/package/@ffmpeg/ffmpeg.md) — 529.5K weekly downloads

## Recent versions

- 0.9.0 (latest) — 2026-09-23
- 0.8.1 — 2026-09-15
- 0.8.0 — 2026-09-02
- 0.7.0 — 2026-08-31
- 0.6.0 — 2026-08-20
- 0.5.0 — 2026-08-07
- 0.3.0 — 2026-06-26
- 0.2.0 — 2026-05-28

## README

# @navalabs/hyperliquid-adapter

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

```bash
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` |

```sh
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

```ts
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.

---
_Source: https://npm.io/package/@navalabs/hyperliquid-adapter · Machine-readable twin of the npm.io package page. Health data is recomputed on every publish._