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 {
  useAgentWallet,
  useSpendingStatus,
  useFetchWithPayment,
  useCostEstimate,
  useProtocolDetection,
} 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);