@navalabs/sdk

Nava Guardian verifies an exact proposed transaction against the active policy for its registered agent. It returns a structured verdict. The integrating application owns any signing and protocol submission after approval.

Install

npm install @navalabs/sdk

Requires Node.js >= 22.12.

Which package to install

@navalabs/sdk is protocol-neutral: it carries the runtime, the nava binary, the nava-mcp server, and the six base operations (verification plus advisory policy/state reads). Protocol operations live in adapters, which depend on this package and ship their own nava and nava-mcp, so an adapter is a complete install on its own.

| You want | Install | |---|---| | Guardian verification, bootstrapGuardian, the base CLI/MCP tools | @navalabs/sdk | | Uniswap V3/V4 | @navalabs/uniswap-adapter | | Hyperliquid perps | @navalabs/hyperliquid-adapter | | Both protocols | both adapters |

Adapters remain optional peer dependencies of this package, which is what keeps dynamic sibling loading legal under strict resolvers. Several packages declare the nava and nava-mcp bin names; which one a package manager links varies and is not warned about, so every copy dispatches every installed protocol.

Run a protocol command whose adapter is not installed and it fails with:

The uniswap adapter is not installed or could not be loaded: <import error>

Over MCP the same gap is not a failure. nava-mcp starts with the base tools plus every installed protocol. With NAVA_PROTOCOLS unset it stays silent about protocols you never installed; name one explicitly and it reports the missing adapter. nava --help lists only the protocols the running binary registers, so a bare @navalabs/sdk lists none and prints an install hint.

Do not pin the SDK and an adapter to one shared version: they version independently.

Zero-install

Nothing has to be installed first; packages can be fetched per run.

pnpm --package=@navalabs/sdk dlx nava check-verification-status --request-hash 0x…
pnpm --package=@navalabs/uniswap-adapter \
  dlx nava uniswap get-quote --protocol v3 --currency-in USDC.e --currency-out WETH --amount-in 1

A protocol run needs only that protocol's adapter. It depends on @navalabs/sdk and ships its own nava. Other package managers: npx -p @navalabs/uniswap-adapter nava uniswap <operation>, yarn dlx -p … the same way, or for bun bun add @navalabs/uniswap-adapter then bunx nava ….

Subpath exports

| Import | Contents | |---|---| | @navalabs/sdk | NavaClient, GuardianClient, GuardianVerdictClient, bootstrapGuardian. Start here. | | @navalabs/sdk/escrow | Agent-execution bootstrap: bootstrapAgentExecution, createAgentClient, signAgentTransaction, the KeyStore adapters, P-256 helpers. | | @navalabs/sdk/mcp | startServer, createMCPServer, the protocol registrar plumbing: what nava-mcp runs. | | @navalabs/sdk/cli | runCli and the argv helpers: what nava runs, and what an adapter's CLI module plugs into. | | @navalabs/sdk/surface | The ProtocolSurface descriptor framework: defineProtocolSurface, defineOperation, createCliModule. |

import { NavaClient } from '@navalabs/sdk';
import { bootstrapAgentExecution } from '@navalabs/sdk/escrow';
import { startServer } from '@navalabs/sdk/mcp';
import { defineProtocolSurface } from '@navalabs/sdk/surface';

These five paths and the two bins (nava, nava-mcp) are the stable public contract. Legacy moduleResolution: "node" consumers resolve the subpath types through typesVersions rather than exports.

Verify an action

NavaClient has two modes, chosen by the config you pass.

Agent key. One agent API key bound to one wallet:

import { NavaClient } from '@navalabs/sdk';

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

const created = await nava.requestVerification({
  prompt: 'Swap WETH for USDC on Uniswap',
  proposedTx: {
    protocol: 'uniswap',
    chainId: 11155111,
    to: '0x...',
    data: '0x...',
    value: '0',
  },
});

const verdict = await nava.checkVerificationStatus(created.requestHash!);
if (verdict.verdict?.outcome !== 'approved') throw new Error('Not approved');
// The application may now decide whether to sign and submit this exact action.

When baseUrl is omitted, the client talks to https://internal.navalabs.dev/api. Set baseUrl or NAVA_BASE_URL for another environment.

Integration key (partner backend). One integration serves many users' wallets. The wallet address on each call selects the agent and policy server-side. Integration keys are server-only: the constructor throws in a browser or a web/service worker unless you pass allowBrowser: true.

import { randomUUID } from 'node:crypto';
import { NavaClient } from '@navalabs/sdk';

const nava = new NavaClient({
  integration: {
    appId: process.env.NAVA_APP_ID!, // integration app ID (UUID)
    apiKey: process.env.NAVA_INTEGRATION_KEY!,
  },
  // Required in this mode; no default host serves /integrator/*.
  baseUrl: 'https://devnet.navalabs.dev/nava-service',
});

const walletAddress = '0x...'; // one of the editor's stored walletAddresses
const policy = await nava.getPolicy({ walletAddress, chainId: 11155111 });
if (policy.status === 'initial') throw new Error('No saved policy yet');

const attemptId = randomUUID(); // persist it first; replay with it to recover
const created = await nava.requestVerification({
  escrowAddress: walletAddress,
  prompt: 'Swap WETH for USDC on Uniswap',
  proposedTx: {
    protocol: 'uniswap',
    chainId: 11155111,
    to: '0x...',
    data: '0x...',
    value: '0',
  },
  idempotencyKey: attemptId,
});

const status = await nava.waitForVerification(created.id);
if (!status.canExecute) throw new Error(status.message);
// Execute on the venue, then report it, or cancel if nothing executed:
// await nava.submitUserExecutionTxHash(created.id, venueTxHash); // no hash: submitUserExecution
// await nava.cancelTransaction(created.id);

baseUrl is required in integration mode and has no default. Devnet is https://devnet.navalabs.dev/nava-service. Any scheme is accepted so local stacks can use http; use https everywhere else, because every request carries the key. Every approval reserves spend until it is reported or cancelled, so always send an idempotency key and settle every approval. Integration-mode errors are NavaFetchErrors with a code (unauthorized, wallet_not_found, rate_limited, network_error, report_unconfirmed, and so on); the integration guide gives the action for each. For a one-wallet client, set the top-level walletAddress and type a separately declared config as WalletBoundIntegrationKeyConfig. examples/partner-backend.ts walks the whole flow: choosing the wallet for the chain, same-key recovery, when to cancel and when to retry the report, 401s and stale wallets.

proposedTx.chainId is required and must be a chain the registry supports. requestVerification throws at the SDK boundary otherwise.

Manage Guardian agents and policies

import { bootstrapGuardian } from '@navalabs/sdk';

const context = await bootstrapGuardian({
  bearerToken: process.env.NAVA_MANAGEMENT_TOKEN!,
  agentName: 'Treasury Agent',
  walletAddress: process.env.WALLET_ADDRESS!,
  chainId: 11155111,
  policy: { presetId: 'spot-swapper' },
});

Policy writes use the nested overlay (shared + venues), not flat Uniswap fields. For payments on Base USDC:

import {
  bootstrapGuardian,
  buildErc20TransferProposedTx,
  PAYMENTS_CHAIN_ID,
  PAYMENTS_USDC_ADDRESS,
} from '@navalabs/sdk';

const context = await bootstrapGuardian({
  bearerToken: process.env.NAVA_MANAGEMENT_TOKEN!,
  agentName: 'Payments Agent',
  walletAddress: process.env.WALLET_ADDRESS!,
  chainId: PAYMENTS_CHAIN_ID,
  policy: {
    presetId: 'payments',
    venues: {
      payments: {
        perPaymentCapUsd: 1,
        spendCapPerPeriod: { capUsd: 5, period: 'hour' },
        vendorAllowlist: [],
      },
    },
  },
});

const proposedTx = buildErc20TransferProposedTx({
  chainId: PAYMENTS_CHAIN_ID,
  token: PAYMENTS_USDC_ADDRESS,
  to: '0x2222222222222222222222222222222222222222',
  amount: 500_000n,
});

Use GuardianClient for agent, wallet, API-key, policy, and verdict-history management. Use GuardianVerdictClient with an agent API key for submissions and verdict polling.

CLI and MCP

Six base operations exist on both surfaces, under the same names: as nava <command> on the CLI, and as unprefixed MCP tools:

| 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 | | get-agent-policy | nava get-agent-policy | get-agent-policy | | get-agent-state | nava get-agent-state | get-agent-state |

get-agent-policy and get-agent-state are advisory: an agent that self-rejects based on these reads and never submits leaves no verdict and no audit trail. They need only NAVA_API_KEY. NAVA_BASE_URL is optional and defaults to https://internal.navalabs.dev/api. Verification commands still need NAVA_WALLET_ADDRESS / WALLET_ADDRESS.

Protocol operations are nava <protocol> <operation> on the CLI and <protocol>.<operation> over MCP, kebab-case on both. Every level answers --help; the bundled skill's references remain the full parameter reference.

Start the MCP server with the protocols you want:

NAVA_PROTOCOLS=uniswap,hyperliquid nava-mcp

Note the CLI's --reason flag is sent to the API as prompt.

The bundled agent skill

@navalabs/sdk ships an agent skill at node_modules/@navalabs/sdk/skills/nava/. It is the canonical, hand-maintained description of the CLI and MCP surface: a SKILL.md entrypoint that routes to one reference per protocol plus base.md (the six base operations) and guardian.md (the verification contract, authentication states, and verdict handling).

Install it into an agent that reads skills from disk by copying or symlinking the directory:

mkdir -p .claude/skills
cp -R node_modules/@navalabs/sdk/skills/nava .claude/skills/nava
# or, to track upgrades of the package automatically:
ln -s ../../node_modules/@navalabs/sdk/skills/nava .claude/skills/nava

Point any other agent runtime at node_modules/@navalabs/sdk/skills/nava/SKILL.md as the entrypoint; the references are relative links from it and load on demand.

The references are hand-maintained and describe the CLI and MCP surface of this package.

Guides

• Integration guide: the six-step verification flow, from agent creation to execution.

License

MIT