SDK Reference

npm install @veridex/sdk ethers

import { createSDK } from '@veridex/sdk';
 
const sdk = createSDK(chain, config?);

interface SimpleSDKConfig {
  network?: 'testnet' | 'mainnet';     // Default: 'testnet'
  rpcUrl?: string;                      // Custom RPC URL
  relayerUrl?: string;                  // Relayer for gasless transactions
  relayerApiKey?: string;               // Relayer API key
  sponsorPrivateKey?: string;           // For gasless vault creation
  integratorSponsorKey?: string;        // Platform-level sponsorship
  rpcUrls?: Record<ChainName, string>;  // Multi-chain RPC URLs
}

// Simplest — testnet by default
const sdk = createSDK('base');
 
// With relayer for gasless transactions
const sdk = createSDK('base', {
  network: 'testnet',
  relayerUrl: 'https://relayer.veridex.network',
});
 
// Stacks
const stacksSdk = createSDK('stacks', { network: 'testnet' });

import { VeridexSDK } from '@veridex/sdk';
import { EVMClient } from '@veridex/sdk/chains/evm';
 
const evmClient = new EVMClient({
  chainId: 84532,
  wormholeChainId: 10004,
  rpcUrl: 'https://sepolia.base.org',
  hubContractAddress: '0x66D87dE68327f48A099c5B9bE97020Feab9a7c82',
  wormholeCoreBridge: '0x79A1027a6A159502049F10906D333EC57E95F083',
  name: 'Base Sepolia',
  explorerUrl: 'https://sepolia.basescan.org',
  vaultFactory: '0xCFaEb5652aa2Ee60b2229dC8895B4159749C7e53',
  vaultImplementation: '0x0d13367C16c6f0B24eD275CC67C7D9f42878285c',
});
 
const sdk = new VeridexSDK({
  chain: evmClient,
  persistWallet: true,
  testnet: true,
  relayerUrl: '/api/relayer',
  relayerApiKey: process.env.NEXT_PUBLIC_RELAYER_API_KEY,
  queryApiKey: process.env.NEXT_PUBLIC_WORMHOLE_QUERY_API_KEY,
  sponsorPrivateKey: process.env.NEXT_PUBLIC_VERIDEX_SPONSOR_KEY,
  chainRpcUrls: {
    10004: 'https://sepolia.base.org',
    10005: 'https://sepolia.optimism.io',
    10003: 'https://sepolia-rollup.arbitrum.io/rpc',
  },
});

interface VeridexSDKConfig {
  chain: EVMClient;                              // Hub chain client
  persistWallet?: boolean;                       // Persist wallet state (default: true)
  testnet?: boolean;                             // Use testnet (default: true)
  relayerUrl?: string;                           // Relayer URL for gasless transactions
  relayerApiKey?: string;                        // Relayer API key
  queryApiKey?: string;                          // Wormhole query API key
  sponsorPrivateKey?: string;                    // For gasless vault creation
  integratorSponsorKey?: string;                 // Platform-level sponsorship
  chainRpcUrls?: Record<number, string>;         // RPC URLs keyed by Wormhole chain ID
}

let sdkInstance: any = null;
 
export async function getVeridexSDK() {
  if (!sdkInstance) {
    const { createSDK } = await import('@veridex/sdk');
    sdkInstance = createSDK('base', {
      network: 'testnet',
      relayerUrl: process.env.NEXT_PUBLIC_RELAYER_URL,
    });
  }
  return sdkInstance;
}

import { createHubSDK, createTestnetSDK, createMainnetSDK, createSessionSDK } from '@veridex/sdk';
 
const hubSdk = createHubSDK();                    // Base hub chain
const testSdk = createTestnetSDK('optimism');      // Force testnet
const mainSdk = createMainnetSDK('base');          // Force mainnet
const sessSdk = createSessionSDK('base');          // Session-optimized

const credential = await sdk.passkey.register(username, displayName);

interface PasskeyCredential {
  credentialId: string;
  publicKeyX: bigint;
  publicKeyY: bigint;
  keyHash: string;
}

const { credential, signature } = await sdk.passkey.authenticate();

const credential = sdk.passkey.getCredential();

sdk.passkey.setCredential(credential);

const credentials = sdk.passkey.getAllStoredCredentials();

const signature = await sdk.passkey.sign(challenge);

sdk.passkey.saveToLocalStorage();

const credential = sdk.passkey.loadFromLocalStorage();
if (credential) {
  sdk.setCredential(credential);
}

const hasStored = sdk.passkey.hasStoredCredential();

await sdk.passkey.saveCredentialToRelayer();

const credential = await sdk.passkey.loadCredentialFromRelayer();

sdk.setCredential(credential);

sdk.clearCredential();

const address = sdk.getVaultAddress();

const config = sdk.getChainConfig();

const identity = await sdk.getUnifiedIdentity();

interface UnifiedIdentity {
  keyHash: string;
  addresses: Array<{
    wormholeChainId: number;
    chainName: string;
    address: string;
    deployed: boolean;
  }>;
}

const identity = await sdk.getUnifiedIdentity();
const baseAddr = identity.addresses.find(a => a.wormholeChainId === 10004);
console.log('Base vault:', baseAddr?.address, 'deployed:', baseAddr?.deployed);

const exists = await sdk.vaultExists();

const receiveAddr = sdk.getReceiveAddress();

const nonce = await sdk.getNonce();

const prepared = await sdk.prepareTransfer(params);

interface TransferParams {
  targetChain: number;   // Wormhole chain ID
  token: string;         // Token address or 'native'
  recipient: string;     // Recipient address
  amount: bigint;        // Amount in smallest unit
}

interface PreparedTransfer {
  params: TransferParams;
  actionPayload: string;
  nonce: bigint;
  challenge: string;
  estimatedGas: bigint;
  gasPrice: bigint;
  messageFee: bigint;
  totalCost: bigint;
  formattedCost: string;
  preparedAt: number;
  expiresAt: number;      // 5 minutes TTL
}

const prepared = await sdk.prepareTransfer({
  targetChain: 10004,
  token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e',
  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f5A234',
  amount: 1000000n,
});
 
console.log('Gas cost:', prepared.formattedCost);
console.log('Expires:', new Date(prepared.expiresAt));

const result = await sdk.executeTransfer(prepared, signer);

interface DispatchResult {
  transactionHash: string;
  sequence: bigint;
  userKeyHash: string;
  targetChain: number;
  blockNumber: number;
}

const result = await sdk.transferViaRelayer(params);

interface TransferResult {
  transactionHash: string;
  sequence?: bigint;
  status: 'pending' | 'confirmed' | 'failed';
}

import { ethers } from 'ethers';
 
const result = await sdk.transferViaRelayer({
  targetChain: 10004,  // Base Sepolia
  token: '0x036CbD53842c5426634e7929541eC2318f3dCF7e', // USDC
  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f5A234',
  amount: ethers.parseUnits('10', 6), // 10 USDC
});
 
console.log('Tx:', result.transactionHash);

const summary = await sdk.getTransactionSummary(prepared);

interface TransactionSummary {
  title: string;           // e.g., "Transfer"
  description: string;     // e.g., "Send 1.0 USDC to 0x742d...5A234"
  details: ActionDetails;
  risks: RiskWarning[];    // e.g., large_transaction, unknown_recipient
  gasCost: string;
  expiresIn: number;
}

const prepared = await sdk.prepareTransfer({ ... });
const summary = await sdk.getTransactionSummary(prepared);
 
console.log(summary.title);        // "Transfer"
console.log(summary.description);  // "Send 1.0 USDC to 0x742d...5A234"
if (summary.risks.length > 0) {
  console.warn('Risks:', summary.risks.map(r => r.message));
}

const prepared = await sdk.prepareBridge(params);

interface BridgeParams {
  sourceChain: number;        // Source Wormhole chain ID
  destinationChain: number;   // Destination Wormhole chain ID
  token: string;
  recipient: string;
  amount: bigint;
}

const result = await sdk.executeBridge(prepared, signer, onProgress?);

sdk.executeBridge(prepared, signer, (progress) => {
  console.log(`Step ${progress.step}/${progress.totalSteps}: ${progress.message}`);
  // Steps: signing → dispatching → waiting_confirmations → fetching_vaa → relaying → completed
});

const result = await sdk.bridgeViaRelayer(params, onProgress?);

const result = await sdk.bridgeWithTracking(params, signer, onProgress?);

const fees = await sdk.getBridgeFees(params);

interface CrossChainFees {
  sourceGas: bigint;
  messageFee: bigint;
  relayerFee: bigint;
  totalCost: bigint;
  formattedTotal: string;
  currency: string;
}

const limits = await sdk.getSpendingLimits(chainId?);

const formatted = await sdk.getFormattedSpendingLimits();
console.log(`${formatted.dailyUsedPercentage}% of daily limit used`);
console.log(`Resets in: ${formatted.timeUntilReset}`);

import { ethers } from 'ethers';
 
const check = await sdk.checkSpendingLimit(ethers.parseEther('1.0'));
if (!check.allowed) {
  console.log(check.message);
  console.log('Suggestions:', check.suggestions);
}

const prepared = await sdk.prepareSetDailyLimit(ethers.parseEther('5.0'));
// Sign and execute with sdk.executeTransfer(prepared, signer)

const prepared = await sdk.preparePauseVault();

const canSponsor = sdk.isSponsorshipAvailable();

const result = await sdk.ensureSponsoredVaultsOnAllChains();
console.log(`Created vaults on ${result.results.filter(r => r.success).length} chains`);

const tokens = sdk.getTokenList();
for (const token of tokens) {
  console.log(`${token.symbol}: ${token.address} (${token.decimals} decimals)`);
}

interface TokenInfo {
  address: string;
  symbol: string;
  name: string;
  decimals: number;
  wormholeChainId: number;
  logoUrl?: string;
}

const native = await sdk.getVaultNativeBalance();
console.log(`${native.token.symbol}: ${native.formatted}`);

const portfolio = await sdk.getVaultBalances();
for (const entry of portfolio.tokens) {
  console.log(`${entry.token.symbol}: ${entry.formatted}`);
}
console.log('Total USD:', portfolio.totalUsdValue);

const balance = await sdk.getVaultTokenBalance(tokenAddress);
console.log(`${balance.token.symbol}: ${balance.formatted}`);

const results = await sdk.getMultiChainBalances([10004, 10005, 10003]);
for (const chain of results) {
  console.log(`${chain.chainName}: ${chain.tokens.length} tokens`);
}

const portfolio = await sdk.balance.getPortfolioBalance(chainId, address);
const multi = await sdk.balance.getMultiChainBalances(address, [10004, 10005]);

sdk.transactions.track(txHash, chainId, callback?, sequence?);

const result = await sdk.sponsor.createVault(chainId, credential);

import {
  EVMClient,
  SolanaClient,
  AptosClient,
  SuiClient,
  StarknetClient,
  StacksClient,
} from '@veridex/sdk';

import {
  SessionManager,
  generateSecp256k1KeyPair,
  computeSessionKeyHash,
  signWithSessionKey,
  hashAction,
  verifySessionSignature,
  deriveEncryptionKey,
  encrypt,
  decrypt,
  createSessionStorage,
} from '@veridex/sdk';

import {
  getChainConfig,
  getSupportedChains,
  getHubChains,
  isChainSupported,
  getDefaultHub,
  CHAIN_PRESETS,
  CHAIN_NAMES,
} from '@veridex/sdk';
 
// Get all supported chains
const chains = getSupportedChains('testnet');
// ['base', 'optimism', 'arbitrum', 'solana', 'aptos', 'sui', 'starknet', 'stacks']
 
// Get chain config
const config = getChainConfig('stacks', 'testnet');
console.log('Wormhole ID:', config.wormholeChainId); // 50003

import {
  NATIVE_TOKEN_ADDRESS,
  BASE_SEPOLIA_TOKENS,
  TOKEN_REGISTRY,
  getTokenList,
  getTokenBySymbol,
  getTokenByAddress,
  isNativeToken,
} from '@veridex/sdk';
 
const usdc = getTokenBySymbol(10004, 'USDC');
console.log('USDC address:', usdc?.address);

import {
  // Addresses
  getERC8004Addresses,
  isERC8004Chain,
  ERC8004_CHAINS,
 
  // ABIs
  IDENTITY_REGISTRY_ABI,
  IDENTITY_REGISTRY_READ_ABI,
  REPUTATION_REGISTRY_ABI,
  REPUTATION_REGISTRY_READ_ABI,
  VALIDATION_REGISTRY_ABI,
 
  // Types
  type ERC8004AgentRegistration,
  type ERC8004MetadataEntry,
  type ERC8004FeedbackEntry,
  type ERC8004FeedbackSummary,
  type ERC8004ValidationStatus,
  type UniversalAgentIdentifier,
} from '@veridex/sdk';

const addresses = getERC8004Addresses('mainnet');
// {
//   identityRegistry: '0x8004A169FB4a3325136EB29fA0ceB6D2e539a432',
//   reputationRegistry: '0x8004BAa17C55a88189AE136b182e5fdA19dE9b63',
// }
 
const testnetAddresses = getERC8004Addresses('testnet');
// {
//   identityRegistry: '0x8004A818BFB912233c491871b3d84c89A494BD9e',
//   reputationRegistry: '0x8004B663056A597Dffe9eCcC1965A193B7388713',
// }

const supported = isERC8004Chain('base');      // true
const supported2 = isERC8004Chain('monad');    // true
const supported3 = isERC8004Chain('solana');   // false (non-EVM)

console.log(ERC8004_CHAINS);
// ['base', 'ethereum', 'polygon', 'arbitrum', 'optimism', 'linea', 'megaeth', 'monad', ...]

import type {
  // Config
  VeridexConfig, SimpleSDKConfig, ChainConfig, ChainName, NetworkType,
 
  // Passkey
  PasskeyCredential, WebAuthnSignature,
 
  // Cross-Origin Authentication
  CrossOriginAuth, CrossOriginAuthConfig, CrossOriginSession,
  ServerSessionToken, AuthPortalMessage,
  createCrossOriginAuth, sendAuthResponse, sendAuthError,
  DEFAULT_AUTH_PORTAL_URL, DEFAULT_RELAYER_URL, AUTH_MESSAGE_TYPES,
 
  // Actions
  TransferParams, ExecuteParams, BridgeParams,
  DispatchResult, PreparedTransfer, PreparedBridge,
 
  // Results
  TransferResult, BridgeResult, CrossChainFees,
 
  // Spending Limits
  SpendingLimits, FormattedSpendingLimits, LimitCheckResult,
 
  // Sessions
  SessionConfig, SessionSignature, KeyPair,
 
  // Balances
  TokenBalance, PortfolioBalance,
 
  // Transaction Summaries
  TransactionSummary, RiskWarning,
 
  // Vault & Identity
  VaultInfo, UnifiedIdentity,
 
  // ERC-8004
  ERC8004AgentRegistration, ERC8004MetadataEntry,
  ERC8004FeedbackEntry, ERC8004FeedbackSummary,
  ERC8004ValidationStatus, UniversalAgentIdentifier,
} from '@veridex/sdk';