--- name: nava description: >- Use Nava when asked to verify an SDK transaction, set up or manage Policy Guardian agents and policies, inspect a policy verdict, explain a Guardian rejection, swap tokens or place, cancel, or leverage orders through Nava, run Nava Hyperliquid or Uniswap CLI commands, or configure their MCP tools. Covers reads, prepared actions, policy-gated writes, credential separation, terminal-verdict handling, and MCP host configuration. --- # Nava Guardian Treat Guardian as a deterministic policy-verification layer. Submit the venue-native proposed action and evaluate it against the active, versioned policy attached to the agent. Do not describe this path as prompt-intent or semantic alignment. ## Running the CLI Nothing has to be installed first. `@navalabs/sdk` ships the single `nava` binary and is designed to be run one-shot; the only requirement is Node.js 18 or newer. Prefer this over asking the user to install anything. Install the adapter for the protocol you need — it ships the `nava` binary and brings `@navalabs/sdk` with it, so one package is enough. `@navalabs/sdk` alone covers the base verification commands and no protocol. | Surface | Zero-install command | | --- | --- | | Base verification | `pnpm --package=@navalabs/sdk dlx nava ` | | Hyperliquid | `pnpm --package=@navalabs/hyperliquid-adapter dlx nava hyperliquid ` | | Uniswap | `pnpm --package=@navalabs/uniswap-adapter dlx nava uniswap ` | Need both protocols? Add both adapters. They share one `nava`, and every installed protocol is reachable from it. The four base operations exist on **both** surfaces under the same names — as `nava ` on the CLI, and as **unprefixed** MCP tools (protocol tools are namespaced `.`; these are not): | Operation | CLI | MCP tool | | --- | --- | --- | | `request-verification` | `nava request-verification` | `request-verification` | | `await-verification` | `nava await-verification` | `await-verification` | | `check-verification-status` | `nava check-verification-status` | `check-verification-status` | | `get-user-address` | `nava get-user-address` | `get-user-address` | Their options, defaults, and required environment are in [Base surface](references/base.md). Protocol operations are listed in each protocol reference. Other package managers: - npm: `npx -p @navalabs/uniswap-adapter nava uniswap ` - yarn: `yarn dlx -p @navalabs/uniswap-adapter nava uniswap ` - bun: `bun add @navalabs/uniswap-adapter`, then `bunx nava uniswap ` When the adapter is already a project dependency, drop the wrapper and run `nava ` (or `pnpm exec nava …`) directly. Two failure modes to expect: - Running a protocol operation whose adapter is not installed fails with `The adapter is not installed or could not be loaded`. Add that adapter package; do not switch to a different invocation or reach for the TypeScript API instead. - `nava --help` lists the four base commands, then the protocols this install registers. A bare `@navalabs/sdk` registers none and says so. A sibling adapter that is installed but not registered by the running bin still dispatches, so absence from the list is not proof a protocol is unavailable — running the operation is. `nava --help` lists that protocol's commands, and `nava --help` prints the command's own options. Do not pin the SDK and an adapter to one shared version. They version independently; omit versions unless a specific one is required. ## Runtime prerequisites - For MCP workflows, require an MCP host that can run a local stdio server and inject environment variables or secrets. Install the applicable protocol adapter alongside `@navalabs/sdk`. - For Guardian verification, require the appropriate management or agent credential and a wallet registered to that agent. Explanation-only requests can work from a supplied verdict without runtime access. ## Authentication state Determine the available authority before reading account state, submitting a verification, or preparing a write. Never ask the user to paste credentials into chat; request secure runtime injection instead. | State | What is available | Next step | | --- | --- | --- | | Agent runtime authenticated | An agent API key and that agent's registered verification wallet | Confirm the agent, wallet, network, and policy context; then perform only the requested read or Guardian-gated action. | | Interactive authentication available | The user can approve an OAuth or code-based flow but has no agent key in the runtime | Offer `mcpOAuth` or `codeBased` through `bootstrapGuardian`; securely inject the returned agent key, then confirm the selected agent and wallet. | | Management authenticated | A management bearer token or admin key | Use the management bootstrap only when the user asks to create/manage an agent, wallet, API key, or policy. | | Unauthenticated | No agent key, interactive flow, or management credential | State the blocker. Offer the interactive path, secure injection of an existing agent key, or management provisioning. Do not fabricate an agent or submit a request. | Agent credentials do not create a blockchain wallet, private key, or RPC endpoint. For an on-chain write, those are separate runtime credentials and must correspond to the registered wallet. Read [Guardian](references/guardian.md#authentication-and-agent-selection) before selecting or initiating any authentication path. ## Universal rules - Keep API keys, private keys, and wallet credentials out of source files, conversation memory, logs, and command output. Use environment variables or an approved credential store. - Get explicit user authorization for the exact material parameters before any write or broadcast. A fully specified imperative request can supply that authorization; ask before acting when the network, protocol version, amount, price bound, slippage, or other material parameter is unresolved. - Treat the runtime verdict as authoritative. Do not infer that a planned policy check is enforced merely because a policy field or UI control exists. - Report verification as final only after a terminal verdict. Report execution as complete only after the relevant tool returns terminal execution success and, where applicable, a confirmed transaction or venue result. - Never retry a rejected action blindly. Explain the returned verdict and ask for direction if a materially different action would be required. - Never suggest splitting, disguising, or otherwise changing an action to evade a policy boundary. - Keep verification and execution distinct. An `approved` verdict permits the evaluated action under the returned policy version; it does not by itself prove that the action was broadcast, filled, or confirmed. ## Route the request Read every applicable reference before acting. For a protocol write, read both the protocol reference and `references/guardian.md`. | Request | Read before acting | | --- | --- | | Policy verification, Guardian setup, agent policy management, verdict inspection, or rejection explanation | [Guardian](references/guardian.md) | | Submitting, polling, or re-reading a verification directly (the four base operations) | [Base surface](references/base.md) | | Privy device-auth wallet workflow | [SDK Privy](references/sdk-privy.md) | | Hyperliquid | [Hyperliquid](references/hyperliquid.md) | | Uniswap | [Uniswap](references/uniswap.md) | To choose a surface: if protocol MCP tools are already available in your session, use the MCP invocation listed in that protocol reference; otherwise use its CLI invocation. Also read the reference when asked to configure a host that does not have the tools yet. The two MCP surfaces differ: Hyperliquid MCP registers verified write tools that can broadcast, while Uniswap MCP tools prepare calldata only. Despite its name, `uniswap.execute-swap` does not broadcast a swap. ## Cross-surface traps Verified against the current SDK. Each one produces a plausible-looking wrong result rather than an obvious failure. - **`isError` is not "rejected".** Verified-write and operational tools derive `isError` from the payload's `success`; read and build tools always return `isError: false` unless the call threw. A failed `uniswap.execute-swap` build and a **REJECTED** `await-verification` verdict are both `isError: false`. Branch on `success` / `canExecute` / `verdict`, never on `isError`. - **`--reason` is `prompt` on the wire.** The CLI flag is `--reason` and the base MCP tools take `prompt`; both are sent to the API as `prompt`. It is an input field only — a verdict payload carries `humanReason` and `reasonCode`, never `prompt`. - **Hyperliquid `network` is MCP-only.** Every Hyperliquid MCP tool takes an optional `network` field, but the CLI rejects `--network` outright and reads `HYPERLIQUID_NETWORK` / `HL_NETWORK` instead. - **`--order-id` is not the same type everywhere.** Hyperliquid takes a positive **integer**; other venues take a **string**. Do not carry a value across. - **Per-command `--help` is complete for the four base commands only.** `nava request-verification --help` lists its options. Protocol commands answer with the operation's description and a link to the operations reference, not their options, so the protocol references below remain the parameter documentation for those. `--help` in any position — or `-h` as the first argument — prints help and exits 0 without running the operation; anything else on the line is reported as ignored. A non-leading `-h` is an option value, not a help request. The protocol operation tables are maintained alongside the SDK `ProtocolSurface` descriptors — update both together. Shared policy and credential guidance remains hand-written here.