Agent SDK Reference

npm install @veridex/agentic-payments

import { createAgentWallet } from '@veridex/agentic-payments';
 
const agent = await createAgentWallet(config);

interface AgentWalletConfig {
  masterCredential: {
    credentialId: string;
    publicKeyX: bigint;
    publicKeyY: bigint;
    keyHash: string;
  };
  session: {
    dailyLimitUSD: number;
    perTransactionLimitUSD: number;
    expiryHours: number;
    allowedChains: number[];  // Wormhole chain IDs
  };
  erc8004?: ERC8004Config;
  relayerUrl?: string;
  relayerApiKey?: string;
  x402?: X402ClientConfig;
  mcp?: { enabled: boolean };
}
 
interface ERC8004Config {
  enabled: boolean;
  testnet?: boolean;                // Use testnet registry addresses (default: false)
  registryProvider?: any;           // Custom ethers provider for registry chain
  agentId?: bigint;                 // Pre-registered agent ID
  minReputationScore?: number;      // Minimum reputation (0-100) for trust gate
  trustedReviewers?: string[];      // Only count feedback from these addresses
}

const agent = await createAgentWallet({
  masterCredential: {
    credentialId: 'abc123',
    publicKeyX: BigInt('0x...'),
    publicKeyY: BigInt('0x...'),
    keyHash: '0x...',
  },
  session: {
    dailyLimitUSD: 100,
    perTransactionLimitUSD: 25,
    expiryHours: 24,
    allowedChains: [10004], // Base Sepolia
  },
  erc8004: {
    enabled: true,
    testnet: true,
    minReputationScore: 30,
  },
  relayerUrl: 'https://relayer.veridex.network',
});

const response = await agent.fetch(url, options?);

// Agent automatically handles 402 Payment Required responses
const response = await agent.fetch('https://paid-api.example.com/market-data');
const data = await response.json();
console.log('Market data:', data);

const receipt = await agent.pay(params);

interface PaymentParams {
  chain: number;        // Wormhole chain ID (e.g., 10004 for Base Sepolia)
  token: string;        // Token symbol ('ETH', 'USDC', 'native')
  amount: string;       // Amount in smallest unit (e.g., '1000000' for 1 USDC)
  recipient: string;    // Recipient address
  protocol?: string;    // Payment protocol (default: 'direct')
}

interface PaymentReceipt {
  txHash: string;
  status: 'confirmed' | 'pending' | 'failed';
  chain: number;
  token: string;
  amount: bigint;
  recipient: string;
  protocol: string;
  timestamp: number;
}

const receipt = await agent.pay({
  chain: 10004,          // Base Sepolia
  token: 'USDC',
  amount: '5000000',     // 5 USDC (6 decimals)
  recipient: '0x742d35Cc6634C0532925a3b844Bc9e7595f5A234',
});
 
console.log('Tx:', receipt.txHash);
console.log('Status:', receipt.status);

const status = agent.getSessionStatus();

interface SessionStatus {
  isValid: boolean;
  keyHash: string;
  expiry: number;                    // Unix timestamp
  remainingDailyLimitUSD: number;
  totalSpentUSD: number;
  masterKeyHash: string;
  address: string;                   // Session wallet address
  limits: {
    dailyLimitUSD: number;
    perTransactionLimitUSD: number;
  };
}

const status = agent.getSessionStatus();
 
console.log('Session valid:', status.isValid);
console.log('Spent today:', `$${status.totalSpentUSD.toFixed(2)}`);
console.log('Remaining:', `$${status.remainingDailyLimitUSD.toFixed(2)}`);
console.log('Wallet:', status.address);

const balances = await agent.getBalance(chain?);

const balances = await agent.getBalance(10004);
for (const entry of balances) {
  console.log(`${entry.token.symbol}: ${entry.formatted}`);
}

const portfolio = await agent.getMultiChainBalance();

const history = await agent.getPaymentHistory(options?);

interface HistoryOptions {
  limit?: number;
  offset?: number;
  chain?: number;
  token?: string;
  since?: number;    // Unix timestamp
}

await agent.revokeSession();

const log = await agent.exportAuditLog(format?);

agent.onSpendingAlert((alert) => {
  console.log('Alert:', alert.type, alert.message);
});

const tools = agent.getMCPTools();

interface MCPTool {
  name: string;                    // e.g., 'veridex_pay', 'veridex_balance'
  description: string;             // Human-readable description
  inputSchema: {
    type: 'object';
    properties: Record<string, any>;
    required?: string[];
  };
  handler: (args: any) => Promise<any>;  // Execute the tool
}

import { FunctionDeclaration, SchemaType } from '@google/generative-ai';
 
const mcpTools = agent.getMCPTools();
 
const geminiTools = mcpTools.map(tool => ({
  declaration: {
    name: tool.name,
    description: tool.description,
    parameters: {
      type: SchemaType.OBJECT,
      properties: tool.inputSchema.properties,
      required: tool.inputSchema.required || [],
    },
  },
  execute: async (args: any) => {
    const result = await tool.handler(args);
    // Serialize BigInts for JSON compatibility
    return JSON.parse(JSON.stringify(result, (key, value) =>
      typeof value === 'bigint' ? value.toString() : value
    ));
  },
}));

const openaiTools = mcpTools.map(tool => ({
  type: 'function' as const,
  function: {
    name: tool.name,
    description: tool.description,
    parameters: tool.inputSchema,
  },
}));

await agent.importSession(sessionData);

interface SessionData {
  keyHash: string;
  encryptedPrivateKey: string;
  publicKey: string;
  config: {
    dailyLimitUSD: number;
    perTransactionLimitUSD: number;
    expiryTimestamp: number;
    allowedChains: number[];
  };
  masterKeyHash: string;
}

// Backend receives session data from frontend
app.post('/api/provision', async (req, res) => {
  const { sessionData } = req.body;
  const wallet = await getAgentWallet();
  await wallet.importSession(sessionData);
  console.log('Session injected into Wallet.');
  res.json({ success: true });
});

import { SessionKeyManager } from '@veridex/agentic-payments';
 
const manager = new SessionKeyManager();
 
// Create a session
const session = await manager.createSession(masterCredential, {
  dailyLimitUSD: 50,
  perTransactionLimitUSD: 10,
  expiryTimestamp: Date.now() + 24 * 60 * 60 * 1000,
});
 
// Check limits before payment
const check = manager.checkLimits(session, amountUSD);
if (check.allowed) {
  // Execute payment...
  await manager.recordSpending(session, amountUSD);
}
 
// Revoke when done
await manager.revokeSession(session.keyHash);

import { X402Client } from '@veridex/agentic-payments';

import { PaymentParser } from '@veridex/agentic-payments';
 
const parser = new PaymentParser();
const requirements = parser.parse(response.headers);
// { amount, recipient, network, token, ... }

import {
  EVMChainClient,
  SolanaChainClient,
  AptosChainClient,
  SuiChainClient,
  StarknetChainClient,
  StacksChainClient,
  ChainClientFactory,
} from '@veridex/agentic-payments';

import { StacksChainClient } from '@veridex/agentic-payments';
 
const client = new StacksChainClient({
  network: 'testnet',
});
 
// Get STX price
const stxPrice = await client.getNativeTokenPriceUSD();
 
// Get vault balance
const balance = await client.getVaultBalance(address);

import { StacksSpendingTracker } from '@veridex/agentic-payments';
 
const tracker = new StacksSpendingTracker({
  dailyLimitUSD: 100,
  network: 'testnet',
});
 
// Convert STX amount to USD
const usdValue = await tracker.convertToUSD(1000000n, 'STX');
 
// Check if payment is within limits
const allowed = await tracker.checkPayment(amountMicroSTX);

import { PythOracle, PYTH_FEED_IDS } from '@veridex/agentic-payments';
 
const oracle = new PythOracle();
 
// Get price by symbol (auto-resolves feed ID)
const ethPrice = await oracle.getPrice('ETH');
const stxPrice = await oracle.getPrice('STX');
const btcPrice = await oracle.getPrice('BTC');
 
// Get price by feed ID
const price = await oracle.getPrice(PYTH_FEED_IDS.SOL);
 
// Get native token price for a chain
const nativePrice = await oracle.getNativeTokenPrice('stacks');

import { AuditLogger } from '@veridex/agentic-payments';
 
const logger = new AuditLogger();
 
// Get recent logs
const logs = await logger.getLogs({ limit: 50 });
 
// Filter by chain
const baseLogs = await logger.getLogs({ chain: 10004 });

import { AlertManager } from '@veridex/agentic-payments';
 
const alerts = new AlertManager();
alerts.onAlert((alert) => {
  if (alert.type === 'approaching_limit') {
    console.warn('Approaching daily limit!');
  }
});

import { ComplianceExporter } from '@veridex/agentic-payments';
 
const exporter = new ComplianceExporter();
const csv = exporter.exportToCSV(logs);
const json = exporter.exportToJSON(logs);

const result = await agent.register(options);

interface RegisterAgentOptions {
  name: string;
  description: string;
  services?: Array<{ name: string; endpoint: string }>;
  x402Support?: boolean;
  ipfsConfig?: { gateway: string; apiKey: string; provider: 'pinata' | 'web3.storage' };
}

const { agentId, agentURI } = await agent.register({
  name: 'Sentiment Analyzer',
  description: 'NLP-powered sentiment analysis for crypto markets',
  services: [{ name: 'analyze', endpoint: 'https://my-agent.com/analyze' }],
  x402Support: true,
});
 
console.log(`Registered as agent #${agentId}`);
console.log(`URI: ${agentURI}`);

const identity = await agent.getIdentity();

const agentId = agent.getAgentId();

await agent.submitFeedback(agentId, options);

interface FeedbackOptions {
  score: number;           // 0-100
  tags?: string[];         // e.g., ['fast', 'accurate']
  comment?: string;
  feedbackURI?: string;    // Optional URI with detailed feedback
}

await agent.submitFeedback(42n, {
  score: 85,
  tags: ['fast', 'accurate', 'reliable'],
  comment: 'Excellent sentiment analysis results',
});

const summary = await agent.getReputation(agentId, trustedReviewers?);

interface FeedbackSummary {
  feedbackCount: number;
  normalizedScore: number;    // 0-100
  tags: string[];
  recentFeedback: FeedbackEntry[];
}

const score = await agent.getReputationScore(agentId, trustedReviewers?);

const agents = await agent.discover(query);

interface DiscoveryQuery {
  category?: string;
  chain?: string;
  minReputation?: number;
  tags?: string[];
  limit?: number;
}

const sentimentAgents = await agent.discover({
  category: 'sentiment',
  minReputation: 30,
  limit: 10,
});
 
for (const a of sentimentAgents) {
  console.log(`Agent #${a.agentId}: ${a.name}`);
}

const resolved = await agent.resolveAgent(input);

interface ResolvedAgent {
  agentId: bigint;
  name: string;
  agentURI: string;
  reputationScore: number;
  resolvedFrom: 'uai' | 'url' | 'address' | 'search';
}

const trust = await agent.checkMerchantTrust(endpoint);

interface TrustCheckResult {
  trusted: boolean;
  score: number;          // 0-100
  agentId?: bigint;
  reason?: string;        // Why trusted/untrusted
}

const trust = await agent.checkMerchantTrust('https://data-provider.com');
if (trust.trusted) {
  console.log(`Trusted (score: ${trust.score}/100)`);
} else {
  console.log(`Untrusted: ${trust.reason}`);
}

const identityClient = agent.getIdentityClient();
const reputationClient = agent.getReputationClient();
const discovery = agent.getAgentDiscovery();

import { IdentityClient } from '@veridex/agentic-payments';
import { ethers } from 'ethers';
 
const provider = new ethers.JsonRpcProvider('https://mainnet.base.org');
const signer = new ethers.Wallet(privateKey, provider);
const identity = new IdentityClient(provider, signer, { testnet: false });
 
// Register with auto-built registration file
const { agentId, agentURI } = await identity.registerWithFile({
  name: 'My Agent',
  description: 'Does cool things',
  services: [{ name: 'api', endpoint: 'https://my-agent.com/api' }],
});
 
// Query an agent
const agent = await identity.getAgent(agentId);
console.log(agent.name, agent.agentURI, agent.agentWallet);
 
// Get agent URI
const uri = await identity.getAgentURI(agentId);

import { ReputationClient } from '@veridex/agentic-payments';
 
const reputation = new ReputationClient(provider, signer, { testnet: false });
 
// Submit feedback
await reputation.submitFeedback(agentId, {
  score: 85,
  tags: ['fast', 'accurate'],
});
 
// Get summary
const summary = await reputation.getSummary(agentId, []);
 
// Get normalized score (0-100)
const score = await reputation.getReputationScore(agentId);
 
// Revoke feedback
await reputation.revokeFeedback(agentId);

import { RegistrationFileManager } from '@veridex/agentic-payments';
 
// Build a registration file
const file = RegistrationFileManager.buildRegistrationFile({
  name: 'My Agent',
  description: 'Does cool things',
  services: [{ name: 'api', endpoint: 'https://my-agent.com/api' }],
});
 
// Validate against ERC-8004 schema
const { valid, errors } = RegistrationFileManager.validate(file);
 
// Encode as data URI (no external deps)
const dataURI = RegistrationFileManager.buildDataURI(file);
 
// Publish to IPFS
const manager = new RegistrationFileManager({
  ipfs: { gateway: 'https://api.pinata.cloud', apiKey: '...', provider: 'pinata' },
});
const ipfsURI = await manager.publishToIPFS(file);
 
// Fetch from URI
const fetched = await RegistrationFileManager.fetchFromURI(ipfsURI);
 
// Add/remove services
const updated = RegistrationFileManager.addService(file, {
  name: 'new-service',
  endpoint: 'https://my-agent.com/new',
});
 
// Build well-known file for zero-lookup resolution
const wellKnown = RegistrationFileManager.buildWellKnownFile(agentId, uai, ipfsURI);
// Serve at: /.well-known/agent-registration.json

import { TrustGate } from '@veridex/agentic-payments';
 
const gate = new TrustGate(reputationClient, identityClient, {
  minReputation: 30,
  trustedReviewers: ['0x...'],
  trustModel: 'reputation',
  mode: 'reject',   // 'reject' throws, 'warn' logs
});
 
const result = await gate.check(agentId);
// result.trusted, result.score, result.reason

import { AgentDiscovery } from '@veridex/agentic-payments';
 
const discovery = new AgentDiscovery(identityClient, reputationClient);
 
// Resolve from URL (checks /.well-known/agent-registration.json)
const fromUrl = await discovery.resolve('https://my-agent.com');
 
// Resolve from UAI (CAIP-2 extended format)
const fromUai = await discovery.resolve('eip155:8453:0x8004A169...:42');
 
// Resolve from chain address
const fromAddr = await discovery.resolve('0x742d35Cc6634C0532925a3b844Bc9e7595f5A234');

import { ProtocolRegistry } from '@veridex/agentic-payments';
 
const registry = new ProtocolRegistry();
 
// Find by capabilities
const escrowProtocols = registry.findByCapabilities(['escrow', 'refund']);
 
// Find best for requirements
const best = registry.findBest({
  capabilities: ['one_time_payment', 'cross_chain'],
  chainId: 10004,
  token: 'USDC',
  amountUSD: 5,
});
 
// Find by chain
const baseProtocols = registry.findByChain(10004);

import { createPaymentIntent, intentToProposedAction, isIntentExpired } from '@veridex/agentic-payments';
 
const intent = createPaymentIntent('x402', costEstimate, resourceUrl, {
  recipient: '0x...',
  ttlMs: 300_000,
  description: 'Premium API access',
});
 
// Check expiry
if (isIntentExpired(intent)) { /* handle */ }
 
// Convert for policy evaluation
const action = intentToProposedAction(intent);

import { SettlementVerifier, EVMSettlementStrategy } from '@veridex/agentic-payments';
 
const verifier = new SettlementVerifier({
  rpcEndpoints: { 10004: 'https://sepolia.base.org' },
  confirmations: 1,
  timeoutMs: 30_000,
});
 
verifier.registerStrategy(new EVMSettlementStrategy('x402', {
  10004: 'https://sepolia.base.org',
}));
 
const proof = await verifier.verify(settlement, traceHash);
// → { txHash, traceHashInCalldata, chain }

import {
  PolicyEngine,
  SpendingLimitRule,
  VelocityRule,
  AssetWhitelistRule,
  ChainWhitelistRule,
  ProtocolWhitelistRule,
  CounterpartyRule,
  TimeWindowRule,
  HumanApprovalRule,
} from '@veridex/agentic-payments';
 
const engine = new PolicyEngine();
engine.addRule(new SpendingLimitRule());
engine.addRule(new VelocityRule({ maxPerMinute: 5, maxPerHour: 50 }));
engine.addRule(new AssetWhitelistRule());
engine.addRule(new ChainWhitelistRule());
 
const verdict = await engine.evaluate(proposedAction, context);
// verdict.verdict: 'allow' | 'deny' | 'escalate'
// verdict.reasons: string[]

import {
  InjectionDetector,
  ToolSanitizer,
  OutputGuard,
  AnomalyDetector,
} from '@veridex/agentic-payments';
 
// Prompt injection detection
const detector = new InjectionDetector();
const result = detector.detect(input);
// result.detected, result.matches: [{ category, pattern, matched }]
 
// Tool description sanitization (strips hidden instructions)
const sanitizer = new ToolSanitizer(detector);
const sanitized = sanitizer.sanitizeToolDescription(tool);
// sanitized.safe, sanitized.strippedContent
 
// Tool pinning for rug-pull detection
sanitizer.pinToolDescriptions(tools);
const validation = sanitizer.validatePins(tools);
// validation[i].valid, validation[i].reason
 
// Secret scanning on outputs
const guard = new OutputGuard();
const scan = guard.scanForSecrets(text);
// scan.found, scan.matches: [{ type, value }]
 
// Anomaly detection
const anomaly = new AnomalyDetector({
  baselineWindowMs: 7 * 24 * 60 * 60 * 1000,
  amountStdDevThreshold: 2.5,
});
const analysis = anomaly.analyze(action, history, Date.now());
// analysis.detected, analysis.anomalies, analysis.riskScore

import { TraceInterceptor, EvidenceBundle } from '@veridex/agentic-payments';
 
const interceptor = new TraceInterceptor(storageAdapter);
const trace = await interceptor.captureTrace({
  traceId: 'unique-id',
  agentId: 'agent-1',
  toolCalls: [{ name: 'veridex_pay', args: {}, result: {} }],
  reasoning: { prompt: '...', response: '...' },
});
 
const bundle = new EvidenceBundle(trace);
const evidence = bundle.build();

import {
  MemoryStorage,
  PostgresStorage,
  FilecoinStorage,
  StorachaStorage,
} from '@veridex/agentic-payments';
 
// PostgreSQL — works with pg, postgres.js, drizzle, etc.
const postgres = new PostgresStorage({
  db: pool, // any object with query(sql, params) method
  tableName: 'veridex_traces',
  autoCreateTable: true,
});
 
// Filecoin Cloud via @filoz/synapse-sdk
import { Synapse } from '@filoz/synapse-sdk';
import { privateKeyToAccount } from 'viem/accounts';
const synapse = Synapse.create({ account: privateKeyToAccount('0x...'), source: 'veridex' });
const filecoin = new FilecoinStorage({ client: synapse.storage });
 
// Storacha via @storacha/client
import * as Client from '@storacha/client';
import * as Proof from '@storacha/client/proof';
import { Signer } from '@storacha/client/principal/ed25519';
const principal = Signer.parse(process.env.KEY);
const client = await Client.create({ principal, store: new StoreMemory() });
const proof = await Proof.parse(process.env.PROOF);
const space = await client.addSpace(proof);
await client.setCurrentSpace(space.did());
const storacha = new StorachaStorage({ client });

import { EscalationManager } from '@veridex/agentic-payments';
 
const escalation = new EscalationManager(5 * 60 * 1000); // 5 min timeout
 
// Create ticket
const ticket = escalation.escalate(proposedAction, verdict);
// ticket.id, ticket.status: 'pending'
 
// Listen for events
escalation.on('escalated', (t) => notifyAdmin(t));
escalation.on('approved', (t) => proceedWithAction(t));
escalation.on('rejected', (t) => abortAction(t));
escalation.on('timeout', (t) => handleTimeout(t));
 
// Approve or reject
escalation.approve(ticket.id, 'admin@company.com');
escalation.reject(ticket.id, 'admin@company.com', 'Too risky');

import { CircuitBreaker } from '@veridex/agentic-payments';
 
const breaker = new CircuitBreaker({
  failureThreshold: 3,
  resetTimeoutMs: 60_000,
});
 
// Record outcomes
breaker.recordSuccess();
breaker.recordFailure();
 
// Check state before operations
if (breaker.isOpen()) {
  console.warn('Agent is halted');
}
 
// Listen for state changes
breaker.on('open', () => alertOps('Agent halted'));
breaker.on('half-open', () => log('Testing recovery'));
breaker.on('close', () => log('Agent resumed'));

import { MCPServer } from '@veridex/agentic-payments';
 
const server = new MCPServer(agent, {
  allowedTools: ['veridex_pay', 'veridex_check_balance'],
  toolSpendingLimits: { veridex_pay: 10 },
  sanitizeDescriptions: true,
  pinDescriptions: true,
  scanInputs: true,
  scanOutputs: true,
});
 
const tools = server.getTools();

import {
  AgentWalletProvider,
  useAgentWallet,
  useAgentWalletContext,
  usePayment,
  useSessionStatus,
  useFetchWithPayment,
  useCostEstimate,
  useProtocolDetection,
  useMultiChainBalance,
  usePaymentHistory,
  useSpendingAlerts,
  useCanPay,
} from '@veridex/agentic-payments';

import { AgentPaymentError, AgentPaymentErrorCode } from '@veridex/agentic-payments';
 
try {
  await agent.pay({ ... });
} catch (error) {
  if (error instanceof AgentPaymentError) {
    switch (error.code) {
      case AgentPaymentErrorCode.LIMIT_EXCEEDED:
        console.log('Spending limit exceeded:', error.message);
        break;
      case AgentPaymentErrorCode.INSUFFICIENT_BALANCE:
        console.log('Not enough tokens:', error.message);
        console.log('Suggestion:', error.suggestion);
        break;
      case AgentPaymentErrorCode.SESSION_EXPIRED:
        console.log('Session expired, creating new one...');
        break;
      case AgentPaymentErrorCode.NETWORK_ERROR:
        if (error.retryable) {
          console.log('Retryable error, will retry...');
        }
        break;
    }
  }
}

import { createAgentWallet } from '@veridex/agentic-payments';
 
async function runDataAgent() {
  // 1. Initialize agent with spending limits
  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: 50,
      perTransactionLimitUSD: 5,
      expiryHours: 8,
      allowedChains: [10004],
    },
  });
 
  // 2. Set up spending alerts
  agent.onSpendingAlert((alert) => {
    console.warn(`[ALERT] ${alert.type}: ${alert.message}`);
  });
 
  // 3. Fetch paid data (x402 handled automatically)
  const priceData = await agent.fetch('https://data-provider.example.com/api/v1/prices');
  const prices = await priceData.json();
  console.log('Fetched price data:', prices);
 
  // 4. Make a direct payment
  const receipt = await agent.pay({
    chain: 10004,
    token: 'USDC',
    amount: '1000000',
    recipient: '0x...',
  });
  console.log('Payment confirmed:', receipt.txHash);
 
  // 5. Check session status
  const status = agent.getSessionStatus();
  console.log(`Spent: $${status.totalSpentUSD} / $${status.limits!.dailyLimitUSD}`);
 
  // 6. Export audit log
  const auditLog = await agent.exportAuditLog('json');
  console.log('Audit:', auditLog);
 
  // 7. Clean up
  await agent.revokeSession();
}
 
runDataAgent().catch(console.error);