Installation

Veridex provides two packages depending on your use case:

@veridex/sdk — Core SDK for passkey wallets, vaults, sessions, and cross-chain transfers
@veridex/agentic-payments — Agent SDK for autonomous AI agent payments, x402 protocol, and MCP tools

Prerequisites

Node.js 18+ or Bun
A browser frontend for passkey operations (see note below)
A WebAuthn-compatible browser (Chrome, Safari, Firefox, Edge)
TypeScript 5.0+ (recommended)
ethers v6 (peer dependency for the core SDK)

⚠️

Frontend Required for Passkeys: The core SDK uses WebAuthn browser APIs for passkey registration and authentication. These operations (sdk.passkey.register(), sdk.passkey.authenticate()) must run in a client-side browser context (HTTPS or localhost) — they cannot run in Node.js, server components, or CLI scripts. You need a frontend (React, Next.js, plain HTML, etc.) to create and authenticate passkeys. Server-side code can handle balance queries, transaction verification, and relayer calls, but the initial passkey creation must happen in the browser.

Agent SDK Exception: The Agent SDK (@veridex/agentic-payments) runs server-side in Node.js, but it requires a masterCredential that was originally created via a browser frontend. The typical flow is: human creates passkey in browser → configures spending limits → agent backend receives credentials and operates autonomously within those limits.

Install the Core SDK

For building passkey-authenticated wallets and dApps:

npm install @veridex/sdk ethers

Install the Agent SDK

For building autonomous AI agents that can make payments:

npm install @veridex/agentic-payments

The Agent SDK (@veridex/agentic-payments) includes @veridex/sdk as a dependency and re-exports core functions like createSDK and generateSecp256k1KeyPair for convenience.

Package Comparison

Feature	`@veridex/sdk`	`@veridex/agentic-payments`
Passkey registration & login	✅	✅ (via re-export)
Vault management	✅	✅
Session key management	✅ `SessionManager`	✅ `SessionKeyManager` (enhanced)
Spending limits	✅ `SpendingLimitsManager`	✅ `SpendingTracker` (USD-aware)
Cross-chain transfers	✅	✅ `CrossChainRouter`
ERC-8004 low-level utilities	✅ `erc8004/` module	✅ (via re-export)
ERC-8004 identity clients	—	✅ `IdentityClient`, `ReputationClient`
Registration file management	—	✅ `RegistrationFileManager`
Trust gates & reputation	—	✅ `TrustGate`, `ReputationPipeline`
Agent discovery	—	✅ `AgentDiscovery`
Protocol detection (x402/UCP/ACP/AP2)	—	✅ `ProtocolDetector`
AI agent orchestration	—	✅ `AgentWallet`
MCP tools (Claude/Cursor)	—	✅ `MCPServer`
UCP credentials	—	✅ `UCPCredentialProvider`
Audit logging & compliance	—	✅ `AuditLogger`, `ComplianceExporter`
Multi-chain clients	EVM, Solana, Aptos, Sui, Starknet, Stacks, Monad	All + `MonadChainClient`, `StacksChainClient`
Pyth price oracle	—	✅ `PythOracle`

TypeScript Configuration

For TypeScript projects, ensure your tsconfig.json includes:

{
  "compilerOptions": {
    "target": "ES2020",
    "module": "ESNext",
    "moduleResolution": "bundler",
    "esModuleInterop": true,
    "strict": true
  }
}

Browser Support

Veridex uses WebAuthn (Passkeys) which requires:

Browser	Minimum Version
Chrome	67+
Safari	14+
Firefox	60+
Edge	79+

Passkeys require a secure context (HTTPS) in production. For local development, localhost is allowed.

Framework Integration

React / Next.js (Core SDK)

// lib/veridex.ts
import { createSDK } from '@veridex/sdk';
 
export const sdk = createSDK('base', {
  network: 'testnet',
  relayerUrl: process.env.NEXT_PUBLIC_RELAYER_URL,
});

Node.js / Backend (Agent SDK)

// agent.ts
import { createAgentWallet } from '@veridex/agentic-payments';
 
const agent = await createAgentWallet({
  masterCredential: {
    credentialId: process.env.CREDENTIAL_ID!,
    publicKeyX: BigInt(process.env.PUBLIC_KEY_X!),
    publicKeyY: BigInt(process.env.PUBLIC_KEY_Y!),
    keyHash: process.env.KEY_HASH!,
  },
  session: {
    dailyLimitUSD: 100,
    perTransactionLimitUSD: 25,
    expiryHours: 24,
    allowedChains: [10004],
  },
});

Stacks Integration

// For Stacks-specific operations
import { createSDK, StacksClient } from '@veridex/sdk';
 
const sdk = createSDK('stacks', { network: 'testnet' });

Verify Installation

Core SDK

// test-sdk.ts
import { createSDK, getChainConfig, getSupportedChains } from '@veridex/sdk';
 
const sdk = createSDK('base', { network: 'testnet' });
const chains = getSupportedChains('testnet');
 
console.log('SDK initialized successfully!');
console.log('Supported chains:', chains);
console.log('Base config:', getChainConfig('base', 'testnet'));

Agent SDK

// test-agent.ts
import { createAgentWallet, PythOracle } from '@veridex/agentic-payments';
 
// Test Pyth oracle
const oracle = new PythOracle();
const ethPrice = await oracle.getPrice('ETH');
const stxPrice = await oracle.getPrice('STX');
 
console.log('Agent SDK loaded successfully!');
console.log('ETH price:', ethPrice);
console.log('STX price:', stxPrice);

Run with:

npx tsx test-sdk.ts

Next Steps

Quick Start

Build your first passkey wallet

Core Concepts

Understand how Veridex works

Agent SDK Guide

Build autonomous agent payments

Quick Start Core Concepts