Operations reference

Every operation the SDK ships, with its parameters, in one place. 18 operations: 4 base verification operations plus 14 contributed by the two adapters: 8 Hyperliquid and 6 Uniswap.

One kebab-case token names each operation on both transports. The CLI spells it nava <protocol> <token>; MCP spells it <protocol>.<token>. The base four are un-namespaced on both. There are no camelCase aliases; naming is enforced when the surface descriptor loads, so an alias cannot exist.

Option and field names differ only in case: --currency-in on the CLI is currencyIn over MCP. Where the two transports differ in behaviour, the row says so, and the differences are collected under Transport asymmetries.

The safety boundary is not the same for both adapters

Each adapter has an operation whose name sounds like it trades. Only one of them can reach a venue.

execute-swap does not broadcast a swap. Despite the name, every Uniswap write is a build operation returning unsigned calldata and nothing else.

An approving verdict permits the exact evaluated action under the returned policy version; it is not itself an instruction to execute. What follows differs by adapter: Hyperliquid's three writes do sign and send on an approving verdict when the mode is direct, which is the point of a verified-write. Uniswap never does, so signing and submission stay with your application.

Base verification

Only @navalabs/sdk is required. None of these sign or broadcast anything.

request-verification

Submit one proposed transaction to Guardian. Returns a requestHash and does not wait.

The CLI flag is --reason, the API and MCP field is prompt. One value, three spellings, and it is an input name only. A verdict comes back carrying humanReason and reasonCode, never prompt.

await-verification

Submit, then poll until a terminal verdict. Everything request-verification takes, plus:

The default ceiling is 58 seconds of waiting, not 60. The loop polls maxAttempts times and sleeps only between polls: 30 polls, 29 sleeps, 29 × 2000 ms. The timeout message multiplies interval by attempts and so reports 60 s.

Exhausting the attempts is neither a rejection nor an approval, and the two transports fail closed differently:

• MCP returns status: "PENDING" with success: false and isError: true.
• The CLI and the TypeScript client throw NavaTimeoutError. On the CLI that is exit 1 with the error on stderr; there is no PENDING payload on stdout.

Either way, poll again with check-verification-status or raise the attempt count. A timeout is never permission.

check-verification-status

Re-read the status and structured verdict for a requestHash.

An unknown hash is not an error. It returns status: "NONE" with canExecute: false. A status carrying no structured verdict is not approval.

get-user-address

Return the authenticated session wallet address. Takes no options or fields at all, and the CLI hard-errors on any argument.

Hyperliquid

8 operations. Requires @navalabs/hyperliquid-adapter.

Assets are perp symbols (BTC, ETH, DYDX), matched case-insensitively. Never a contract address and never the numeric asset index; the adapter resolves the index itself. An unknown symbol fails with unknown asset "<symbol>" on <network> and the first ten available names. Use get-markets to list what the configured network carries.

Sizes and prices are positive decimal strings in whole units ("0.01", "64250.5"), never base units and never scientific notation. Size is truncated to the asset's szDecimals and price to the venue's tick rules; a value that truncates to zero is rejected rather than rounded up.

Every Hyperliquid MCP tool takes an optional network field (mainnet or testnet, default mainnet). It is omitted from the tables below because it applies uniformly. The CLI has no such flag and refuses it; see Transport asymmetries.

Reads

The writes call Guardian themselves

place-order, cancel-order, and update-leverage build the venue-native action, submit it to Guardian, and wait for a terminal verdict before signing or sending anything to the exchange. Do not call request-verification separately for a Hyperliquid action: these operations take no proposed transaction, the EIP-712 payload is constructed internally, and a hand-rolled proposal would not be the action that gets signed.

All three share these:

A rejected verdict returns success: false, the message under error, and the requestHash and decision under verification. Nothing is signed. Explain the verdict; do not resubmit unchanged.

Both defaults are environment-overridable, and one fails open. They apply only when the flag or field is absent and the variable is unset:

Booleans must be exactly true or false; any other value errors naming the variable. An explicit flag always wins. Do not describe an action as verified-before-execution on the strength of the documented default alone; pass both explicitly when the answer matters.

place-order

Plus --reason, --mode, and --allow-undecided from above.

Verify a small BTC short without reaching the exchange:

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'

cancel-order

Plus --reason, --mode, and --allow-undecided.

update-leverage

Plus --reason, --mode, and --allow-undecided.

Uniswap

6 operations. Requires @navalabs/uniswap-adapter.

All three build operations return unsigned calldata and nothing more.

Currencies take either a symbol or a contract address. Both resolve against the same pool registry, and find-all-pools returns both spellings for every token, so use whichever the surrounding code already has. A symbol resolves only if it is configured on the chain in use; an unknown symbol, an unknown address, or a token with no configured decimals is an error naming the token, never a guess. Recover with find-all-pools.

Amounts are decimal strings in whole token units ("1.5"), never base units.

Native ETH is not an alias for WETH. Wrapping is a separate, explicitly requested wrap-eth transaction and is never folded into a swap.

You must name the protocol version; the adapter does not infer V3 or V4. The chain comes from UNISWAP_CHAIN_ID, else CHAIN_ID; it is required, and there is no per-call override on either transport.

Options

Building and then verifying a swap

The two currency forms are interchangeable:

nava uniswap find-all-pools --protocol v3
 
nava uniswap execute-swap --protocol v3 \
  --currency-in 0x36b687FB3495D2CBB026DEeDAF480713c7554624 \
  --currency-out 0xB256fD3f0B6d95a3bA308c3259F1Cc31C547d071 \
  --amount-in 1 --slippage-percent 0.5
 
# identical, using symbols:
nava uniswap execute-swap --protocol v3 \
  --currency-in TKA --currency-out TKB \
  --amount-in 1 --slippage-percent 0.5

The result carries every unsigned {order, to, data, value} descriptor in data.allTransactions, with data.requiredApprovals and data.swap splitting the same descriptors out by role. A first swap for a token returns two or three: an ERC-20→Permit2 approval, a Permit2→Router approval, and the swap. Verify each one separately, in order:

nava request-verification \
  --proposed-tx-json '{"protocol":"uniswap","chainId":11155111,"to":"0x…","data":"0x…","value":"0"}' \
  --reason 'Approve TKA spend for the router before the swap'

Signing and submission stay with your application.

Transport asymmetries

Neither transport is a superset of the other. These are the differences that change what a call accepts or means:

The CLI's --network refusal reports itself:

$ nava hyperliquid get-markets --network testnet
--network is not supported. Set HYPERLIQUID_NETWORK or HL_NETWORK instead.

One more asymmetry deserves its own treatment, because it produces a plausible-looking wrong answer rather than an obvious failure: isError does not mean rejected.

What no operation does

• No Uniswap operation signs or broadcasts anything; every one returns unsigned calldata. The Hyperliquid writes do reach the exchange, but only in direct mode and only on a terminal verdict that permits it: an approval, or UNDECIDED with --allow-undecided set.
• A verdict permits the exact evaluated action under the returned policy version. A materially changed action needs its own verification.
• Never retry a rejected action unchanged, and never reshape one to get around a policy boundary. Explain the returned verdict.