@navalabs/sdk-core

@navalabs/sdk-core

Shared primitives that power Nava SDK packages. A dependency-light entry point for consumers who only need the base Nava client, chain and protocol registries, or wallet/crypto utilities — without the Guardian verification client, agent-execution runtime, CLI, and MCP server that live in @navalabs/sdk, or the protocol tooling in the adapter packages.

When to use which package

Need	Package
Chain/protocol registries, Nava HTTP client, wallet adapters	@navalabs/sdk-core
Full SDK (NavaClient, Guardian verification and management, the nava CLI, the nava-mcp server, agent-execution bootstrap)	@navalabs/sdk
Uniswap V3/V4 swap and pool tooling	@navalabs/uniswap-adapter
Hyperliquid perps tooling	@navalabs/hyperliquid-adapter

A protocol operation needs that protocol's adapter. Each adapter depends on @navalabs/sdk and ships its own nava and nava-mcp binaries, so installing the adapter alone is enough. Adapters remain optional peer dependencies of @navalabs/sdk, never bundled into it.

@navalabs/sdk and both adapters depend on @navalabs/sdk-core, so you do not need to install @navalabs/sdk-core explicitly unless you want just the primitives.

Install

pnpm add @navalabs/sdk-core
# or: npm install @navalabs/sdk-core
# or: yarn add @navalabs/sdk-core

Requires Node.js >= 18.

Quick start — Nava API client

Identical client surface to @navalabs/sdk, but without the escrow orchestration layer.

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

const nava = new NavaClient({
  apiKey: 'nava_live_...',
  walletAddress: '0xYourAgentWallet',
  // Omit `baseUrl` to use https://internal.navalabs.dev/api
});

// `proposedTx.chainId` is required and must be a chain the registry supports —
// `requestVerification` throws at the SDK boundary otherwise.
const created = await nava.requestVerification({
  prompt: 'Send 0.1 ETH to Alice',
  proposedTx: {
    protocol: 'evm',
    chainId: 11155111,
    to: '0xAlice',
    value: '100000000000000000',
    data: '0x',
  },
});

const status = await nava.waitForVerification(created.requestHash!);
if (!status.canExecute) throw new Error(status.message);

When baseUrl is omitted, the client talks to https://internal.navalabs.dev/api. Set baseUrl for another environment (devnet is https://devnet.navalabs.dev/nava-service).

The request field is prompt and the action field is proposedTx (RequestVerificationParams). A verdict applies only to the exact action submitted — Nava never signs or broadcasts; the calling application owns execution, and only after an approved verdict.

Getting an agent API key

Agents authenticate with a long-lived agent x-api-key. Obtain one through the Nava UI at https://app.navalabs.dev via OAuth consent or the interactive connect flow, then pass it to NavaClient. SIWE sign-in is no longer exposed by the SDK.

Registries

ChainRegistry and ProtocolRegistry expose chain metadata (RPC URLs, block explorers, native tokens) and protocol descriptors (nava, uniswap, hyperliquid, polymarket) with typed token and pool entries. The registry is data only — a descriptor existing here does not imply a published adapter. polymarket has no published adapter and is not reachable from the nava CLI or nava-mcp.

import {
  ChainRegistry,
  ProtocolRegistry,
  CHAIN_REGISTRY_ENTRIES,
  PROTOCOL_REGISTRY_ENTRIES,
} from '@navalabs/sdk-core';

const sepolia = ChainRegistry.getByChainId(11155111);
const uniswap = ProtocolRegistry.get('uniswap', 1);

Wallet services

Unified WalletServiceFactory produces signers for different custody backends via runtime-typed configs:

import {
  WalletServiceFactory,
  isPrivyWalletConfig,
  isFireblocksWalletConfig,
  type WalletConfig,
} from '@navalabs/sdk-core';

const wallet = WalletServiceFactory.create(config); // PrivyWalletConfig | FireblocksWalletConfig

Supported backends: Privy (@privy-io/node), Fireblocks (@fireblocks/ts-sdk) including JWT auth, and KMS signing (@aws-sdk/client-kms).

Crypto utilities

PGP and P-256 key generation and format validation:

import {
  generatePgpKeyPair,
  generateP256KeyPair,
  validatePgpKey,
  validateP256PublicKey,
  generateNonce,
  getCurrentEnvironment,
} from '@navalabs/sdk-core';

Exports summary

• HTTP client & errors: NavaClient, NavaFetchError, NavaTimeoutError, navaFetchJson, navaFetchRaw
• Registries: ChainRegistry, ProtocolRegistry, and their *_ENTRIES arrays
• Wallet services: WalletServiceFactory, IWalletService, PrivyWalletConfig, FireblocksWalletConfig, FireblocksAuthMethod, FireblocksBasePath
• Platform services: BlockchainService, StorageService, EncryptionService, NavaApiClient, PublicNonceService, FireblocksService, FireblocksJWTService, KMSService, KMSSigningService
• Crypto: generatePgpKeyPair, generateP256KeyPair, validatePgpKey, validateP256PublicKey, generateNonce
• Utilities: Logger, logger, mcpLogger, TransactionGenerator
• Types: TransactionSchema, TransactionRequest, AgentContext, ExecutionResult, VerificationStatusResponse, ApprovalDecision, ChainRegistryEntry, ProtocolRegistryEntry, and more — the package's type declarations (dist/index.d.ts) are the full list.

License

MIT