agentic-payments

Multi-agent payment authorization system for autonomous AI commerce

Introduction

agentic-payments enables AI agents to make autonomous purchases, execute trades, process invoices, and coordinate multi-agent transactions with cryptographic authorization. From shopping assistants that compare prices across merchants, to robo-advisors executing investment strategies, to swarms of specialized agents collaborating on enterprise procurement—this library provides the payment infrastructure for the agentic economy.

Real-World Applications:

• E-Commerce: AI shopping agents with weekly budgets and merchant restrictions
• Finance: Robo-advisors executing trades within risk-managed portfolios
• Enterprise: Multi-agent swarms requiring consensus for high-value purchases
• Accounting: Automated AP/AR with policy-based approval workflows
• Subscriptions: Autonomous renewal management with spending caps

Model Context Protocol (MCP) Integration: Connect AI assistants like Claude, ChatGPT, and Cline directly to payment authorization through natural language. No code required—AI assistants can create mandates, sign transactions, verify consensus, and manage payment workflows conversationally.

Four Complementary Protocols:

• MCP (Model Context Protocol): Stdio and HTTP interfaces for AI assistant integration
• AP2 (Agent Payments Protocol): Cryptographic payment mandates with Ed25519 signatures
• ACP (Agentic Commerce Protocol): REST API integration with Stripe-compatible checkout
• Active Mandate: Autonomous payment capsules with spend caps, time windows, and instant revocation
• Visa TAP (Trusted Agent Protocol): QUIC transport with RFC 9421 HTTP message signatures for ultra-low latency payments

Key Innovation: Multi-agent Byzantine consensus allows fleets of specialized AI agents (purchasing, finance, compliance, audit) to collaboratively authorize transactions, ensuring no single compromised agent can approve fraudulent payments.

Built with TypeScript for Node.js, Deno, Bun, and browsers. Production-ready with comprehensive error handling and <200KB bundle size.

🎯 Features

• ✅ Active Mandates: Spend caps, time windows, merchant rules, and instant revocation
• ✅ Ed25519 Cryptography: Fast, secure signature verification (<1ms)
• ✅ Multi-Agent Consensus: Byzantine fault-tolerant verification with configurable thresholds
• ✅ Intent Mandates: Authorize AI agents for specific purchase intentions
• ✅ Cart Mandates: Pre-approve shopping carts with line-item verification
• ✅ Payment Tracking: Monitor payment status from authorization to capture
• ✅ MCP Protocol: Stdio and HTTP transports for AI assistant integration (Claude, Cline, etc.)
• ✅ Visa TAP QUIC Transport: Ultra-low latency payment authorization with 0-RTT connection resumption
• ✅ RFC 9421 HTTP Signatures: Cryptographic request signing for secure payment authentication
• ✅ Production Ready: 100% TypeScript, comprehensive error handling, <200KB
• ✅ CLI Tools: Command-line interface for mandate management and testing

📦 Installation

# Install the library
npm install agentic-payments

MCP Server (AI Assistant Integration)

# Run stdio transport (local - for Claude Desktop, Cline)
npx -y agentic-payments mcp

# Run HTTP transport (remote - for web integrations)
npx -y agentic-payments mcp --transport http --port 3000

🚀 Quick Start

The library provides three interfaces: CLI commands for terminal use, MCP server for AI assistants, and programmatic API for JavaScript/TypeScript applications.

CLI: Active Mandate Management

Create and manage payment mandates directly from your terminal:

# Create a new Active Mandate
npx agentic-payments active-mandate create \
  --agent "shopping-bot@agentics" \
  --holder "[email protected]" \
  --amount 50000 \
  --currency USD \
  --period daily \
  --kind intent \
  --output mandate.json

# Sign the mandate with Ed25519
npx agentic-payments active-mandate sign \
  --file mandate.json \
  --key <your-private-key-hex> \
  --output signed-mandate.json

# Verify mandate signature and validity
npx agentic-payments active-mandate verify \
  --file signed-mandate.json \
  --verbose

# Revoke a mandate
npx agentic-payments active-mandate revoke \
  --id mandate_abc123 \
  --reason "User request"

# List all revoked mandates
npx agentic-payments active-mandate revocations

🔌 MCP Integration Tutorial

The Model Context Protocol (MCP) allows AI assistants like Claude, Cline, and ChatGPT to interact with payment authorization systems through natural language. This tutorial walks you through setting up and using the MCP server for agentic payments.

Part 1: Starting the MCP Server

The agentic-payments MCP server supports two transport modes:

Stdio Transport (recommended for local development):

# Start the server in stdio mode (default)
npx -y agentic-payments mcp

# The server is now listening on stdin/stdout
# Perfect for Claude Desktop, Cline, and other local integrations

HTTP/SSE Transport (for remote or web-based integrations):

# Start the HTTP server on port 3000
npx -y agentic-payments mcp --transport http --port 3000

# Server endpoints:
# - http://localhost:3000/health    (health check)
# - http://localhost:3000/sse       (SSE stream for MCP)
# - http://localhost:3000/message   (JSON-RPC messages)
# - http://localhost:3000/sessions  (active sessions)

Verify the HTTP server is running:

# Check health endpoint
curl http://localhost:3000/health

# Response:
# {
#   "status": "healthy",
#   "version": "0.1.0",
#   "server": "agentic-payments", "mcp",
#   "transport": "http/sse",
#   "activeSessions": 0
# }

Part 2: Connecting AI Assistants

Claude Desktop (local integration via stdio):

1. Edit your Claude Desktop config file:

   • macOS: ~/.config/claude/claude_desktop_config.json
   • Windows: %APPDATA%\Claude\claude_desktop_config.json

2. Add the MCP server:

{
  "mcpServers": {
    "agentic-payments": {
      "command": "npx",
      "args": ["-y", "agentic-payments", "mcp"]
    }
  }
}

3. Restart Claude Desktop and verify the server appears in the MCP menu

Claude Code (local integration via stdio):

# Add the MCP server to Claude Code
claude mcp add agentic-payments npx -y agentic-payments mcp

# Verify it's connected
claude mcp list

# You should see agentic-payments with status "Connected"

Cline Extension (VS Code integration via stdio):

1. Open VS Code settings for Cline
2. Add to MCP servers configuration:

{
  "agentic-payments": {
    "command": "npx",
    "args": ["-y", "agentic-payments", "mcp"]
  }
}

HTTP/SSE Integration (remote or web applications):

import { Client } from '@modelcontextprotocol/sdk/client/index.js';
import { SSEClientTransport } from '@modelcontextprotocol/sdk/client/sse.js';

// Connect to remote MCP server
const transport = new SSEClientTransport(
  new URL('http://localhost:3000/sse')
);

const client = new Client({
  name: 'payment-client',
  version: '1.0.0'
}, {
  capabilities: {}
});

// Establish connection
await client.connect(transport);

// List available tools
const tools = await client.listTools();
console.log('Available tools:', tools.tools.map(t => t.name));

// Call a tool
const result = await client.callTool({
  name: 'create_active_mandate',
  arguments: {
    agent: '[email protected]',
    holder: '[email protected]',
    amount: 50000,
    currency: 'USD',
    period: 'weekly',
    kind: 'intent',
    expires_at: '2025-12-31T23:59:59Z'
  }
});

console.log('Mandate created:', result);

Part 3: Available MCP Tools

The MCP server exposes 10 tools for AI assistants:

| Tool | Purpose | Key Parameters | |------|---------|---------------| | create_active_mandate | Create payment mandates with spend caps | agent, holder, amount, period | | sign_mandate | Ed25519 cryptographic signing | mandate, private_key | | verify_mandate | Signature verification + guard checks | signed_mandate | | revoke_mandate | Instant mandate revocation | mandate_id, reason | | list_revocations | Query all revoked mandates | None | | generate_agent_identity | Create Ed25519 keypairs | include_private_key | | create_intent_mandate | High-level purchase authorization | merchant_id, intent, max_amount | | create_cart_mandate | Shopping cart approval | merchant_id, items | | verify_consensus | Multi-agent Byzantine verification | agent_public_keys, consensus_threshold | | get_mandate_info | Retrieve mandate details | mandate_id |

Part 4: Tutorial - Creating Your First AI Payment Agent

Let's walk through a complete example of authorizing an AI shopping agent:

Step 1: Generate an agent identity

User: "Generate a new agent identity for my shopping bot"

AI: I'll create a new Ed25519 keypair for your agent.
    [Calls: generate_agent_identity]

Result:
- Public key: d837326487bbc4ad027eeb20f3f7e059...
- Agent can now sign payment mandates
- Store the private key securely (shown once)

Step 2: Create a payment mandate

User: "Create a weekly $500 mandate for grocery shopping"

AI: I'll create an Active Mandate with:
    - Weekly spending cap: $500
    - Purpose: Grocery shopping
    - Valid until: end of year
    [Calls: create_active_mandate]

Result:
- Mandate ID: mandate_c06a6e57-80a7-4c44-84b8-d6a5dd2d0686
- Status: Unsigned (needs signing)
- Cap: $500.00 weekly

Step 3: Sign the mandate

User: "Sign this mandate with the agent's private key"

AI: Signing the mandate with Ed25519...
    [Calls: sign_mandate]

Result:
- Mandate now cryptographically signed
- Signature: 64-byte Ed25519 signature
- Ready for payment authorization

Step 4: Create a shopping cart

User: "Create a grocery cart: 2 laptops at $999 each, 2 mice at $29.99 each"

AI: Building shopping cart mandate...
    [Calls: create_cart_mandate]

Result:
- Items: 2
- Total: $1058.98
- Merchant: amazon.com
- Status: Approved (within weekly cap)

Step 5: Verify before purchase

User: "Verify this mandate is still valid before processing payment"

AI: Running full verification...
    [Calls: verify_mandate]

Result:
✓ Signature valid
✓ Not expired
✓ Not revoked
✓ Within spending cap
→ Payment authorized

Step 6: Revoke if needed

User: "Cancel the shopping mandate"

AI: Revoking mandate immediately...
    [Calls: revoke_mandate]

Result:
- Mandate revoked at: 2025-09-30 15:38:14 UTC
- Reason: User cancellation
- All future payments blocked

Part 5: Multi-Agent Consensus Example

For high-value transactions, use multi-agent verification:

User: "Verify this $10,000 transaction with 3 agents requiring 67% consensus"

AI: Setting up Byzantine fault-tolerant verification...
    [Calls: verify_consensus with 3 agent public keys]

Process:
1. Agent 1: ✓ Verified
2. Agent 2: ✓ Verified
3. Agent 3: ✓ Verified

Result:
- Consensus: YES (100% agreement)
- Byzantine tolerance: Can handle 1 compromised agent
- Transaction authorized

Part 6: Testing Your Integration

Test stdio integration:

# Test that AI can access the tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y agentic-payments mcp

Test HTTP integration:

# Run the test suite
node tests/mcp/http-simple-test.js

# Or manually test endpoints
curl http://localhost:3000/health
curl http://localhost:3000/sessions

Expected output from test suite:

🧪 Testing MCP HTTP/SSE Integration (Simple)

1️⃣  Creating MCP client...
2️⃣  Connecting to server...
   ✓ Connected successfully

3️⃣  Listing available tools...
   ✓ Found 10 tools

4️⃣  Testing create_active_mandate...
   ✓ Mandate created: mandate_c06a6e57-80a7-4c44-84b8-d6a5dd2d0686
   ✓ Amount: $1000.00 monthly

✅ All HTTP/SSE integration tests passed!

Part 7: Troubleshooting

Server won't start:

# Check if port is already in use
lsof -i :3000

# Kill existing process
pkill -f "agentic-payments", "mcp"

# Try again
npx -y agentic-payments mcp --transport http --port 3000

AI can't see the tools:

• Verify the server is running: curl http://localhost:3000/health
• Check Claude Desktop config syntax is valid JSON
• Restart your AI assistant after config changes
• Check logs: MCP servers log to stderr

Session not found errors:

• The HTTP transport automatically manages session IDs
• Each SSE connection creates a new session
• Sessions auto-cleanup after 30 seconds of inactivity
• Check /sessions endpoint to see active sessions

Further Reading

For comprehensive details on implementation, security, and deployment:

• Full MCP Implementation Guide
• Active Mandate Specification
• Security Best Practices

🧪 CLI Commands

Full command reference for terminal-based mandate management, identity generation, and system operations.

Active Mandate Commands

# Create mandate
npx agentic-payments active-mandate create [options]
  -a, --agent <name>           Agent identifier
  -h, --holder <name>          Holder/user identifier
  --amount <number>            Spend cap (minor units, e.g., 12000 = $120.00)
  --currency <code>            Currency code (default: USD)
  --period <type>              Spend period: single|daily|weekly|monthly
  -k, --kind <type>            Mandate kind: intent|cart
  --merchant-allow <hosts>     Comma-separated allowed merchants
  --merchant-block <hosts>     Comma-separated blocked merchants
  --expires <iso>              Expiration date (ISO8601)
  -o, --output <file>          Save to file

# Sign mandate
npx agentic-payments active-mandate sign [options]
  -f, --file <path>            Mandate file to sign
  -k, --key <hex>              Private key (64-byte hex)
  -o, --output <file>          Save signed mandate

# Verify mandate
npx agentic-payments active-mandate verify [options]
  -f, --file <path>            Signed mandate file
  -v, --verbose                Show detailed validation

# Revoke mandate
npx agentic-payments active-mandate revoke [options]
  -i, --id <mandate_id>        Mandate ID to revoke
  -r, --reason <text>          Revocation reason

# List revocations
npx agentic-payments active-mandate revocations

Generate Agent Identity

npx agentic-payments generate --format json

Verify Payment

npx agentic-payments verify --amount 100 --agents 5

System Status

npx agentic-payments system status

API: Multi-Agent Consensus

Byzantine fault-tolerant payment verification using multiple AI agents to prevent fraud and ensure agreement:

import { AgentIdentity, IntentMandate, VerificationSystemBuilder } from 'agentic-payments';

// 1. Create verification agents
const agent1 = await AgentIdentity.generate();
const agent2 = await AgentIdentity.generate();
const agent3 = await AgentIdentity.generate();

// 2. Build consensus system (requires 67% agreement)
const system = new VerificationSystemBuilder()
  .consensusThreshold(0.67)
  .minAgents(2)
  .addAgent(agent1)
  .addAgent(agent2)
  .addAgent(agent3)
  .build();

// 3. Create and sign payment mandate
const mandate = new IntentMandate({
  merchantId: 'shop_12345',
  customerId: 'user_67890',
  intent: 'Monthly premium subscription',
  maxAmount: 29.99,
  currency: 'USD',
  expiresAt: Date.now() + 86400000 // 24 hours
});

await mandate.sign(agent1);

// 4. Verify with Byzantine fault tolerance
const message = new TextEncoder().encode(JSON.stringify(mandate.toJSON()));
const signature = mandate.getSignature();
const result = await system.verifyWithConsensus(signature, message, agent1.publicKey());

console.log(`✅ Verified: ${result.isValid}`);
console.log(`Consensus: ${(result.consensusReached ? 'YES' : 'NO')}`);

💡 Usage Examples

Real-world scenarios showing how AI agents use cryptographic mandates for autonomous commerce.

E-Commerce: AI Shopping Agent

Authorize AI shopping assistants with spending limits, merchant restrictions, and time-bound budgets:

import { AgentIdentity, CartMandate, validateAndVerify } from 'agentic-payments';

// User authorizes shopping agent with Active Mandate
const mandate = {
  mandate_id: 'mandate_grocery_001',
  kind: 'cart',
  agent: '[email protected]',
  holder: '[email protected]',
  cap: {
    amount: 20000,        // $200.00 weekly grocery budget
    currency: 'USD',
    period: 'weekly'
  },
  merchant_allow: ['wholefoodsmarket.com', 'instacart.com'],
  expires_at: '2025-12-31T23:59:59Z'
};

// AI agent builds shopping cart
const cart = new CartMandate({
  merchantId: 'wholefoodsmarket.com',
  customerId: '[email protected]',
  items: [
    { id: 'sku_001', name: 'Organic Bananas', quantity: 2, unitPrice: 399 },
    { id: 'sku_002', name: 'Almond Milk', quantity: 1, unitPrice: 549 },
    { id: 'sku_003', name: 'Sourdough Bread', quantity: 1, unitPrice: 649 }
  ],
  currency: 'USD'
});

const agent = await AgentIdentity.generate();
await cart.sign(agent);

// Verify and process
const totalAmount = cart.getTotalAmount();
console.log(`Cart total: $${(totalAmount / 100).toFixed(2)}`);
console.log(`Within budget: ${totalAmount <= mandate.cap.amount}`);

Use case: AI shopping assistants that compare prices, build optimized carts, and complete purchases autonomously while respecting user-defined spending limits.

Finance: Investment Agent

AI robo-advisors execute trades autonomously within pre-approved limits and time windows:

import { IntentMandate, AgentIdentity } from 'agentic-payments';

// User authorizes trading agent
const tradingMandate = new IntentMandate({
  merchantId: 'exchange.trading.com',
  customerId: 'investor_123',
  intent: 'Purchase index fund ETF',
  maxAmount: 5000.00,
  currency: 'USD',
  expiresAt: Date.now() + 3600000 // 1 hour execution window
});

const tradingAgent = await AgentIdentity.generate();
await tradingMandate.sign(tradingAgent);

console.log('✅ Trading agent authorized for ETF purchase');
console.log(`Max investment: $${tradingMandate.getData().maxAmount}`);
console.log(`Expires: ${new Date(tradingMandate.getData().expiresAt).toLocaleString()}`);

Use case: Robo-advisors and AI trading systems that rebalance portfolios, execute DCA strategies, or respond to market conditions with pre-authorized transaction limits.

Accounting: Expense Management

Automate accounts payable with AI agents that approve, categorize, and process vendor payments:

import { PaymentMandate, AgentIdentity } from 'agentic-payments';

// Finance agent approves recurring vendor payment
const expenseAgent = await AgentIdentity.generate();

const vendorPayment = new PaymentMandate({
  sourceId: 'expense_recurring_001',
  type: 'intent',
  amount: 299.99,
  currency: 'USD',
  paymentMethod: 'ach_vendor_account'
});

await vendorPayment.sign(expenseAgent);
vendorPayment.updateStatus('authorized');

console.log(`Payment status: ${vendorPayment.getStatus()}`);
console.log(`Authorized: ${vendorPayment.isComplete()}`);

Use case: Automated accounts payable, expense report processing, and vendor management where AI agents categorize, approve, and execute payments based on policy rules.

Visa TAP: Ultra-Low Latency Payments with QUIC

Send payment authorizations over QUIC for 50-70% faster processing than HTTP/2:

import { VisaTapQuicTransport, signHttpMessage } from 'agentic-payments';
import { AgentIdentity } from 'agentic-payments';

// 1. Create QUIC transport connection
const transport = new VisaTapQuicTransport({
  host: 'merchant.com',
  port: 8443,
  enable0RTT: true,              // 0-RTT reconnection (<1ms)
  maxConcurrentStreams: 100      // 100+ parallel payments
});

await transport.connect();
console.log('✅ Connected via QUIC');

// 2. Sign payment request with RFC 9421
const agent = await AgentIdentity.generate();
const privateKeyHex = Buffer.from(agent.privateKey).toString('hex');

const signed = await signHttpMessage(
  {
    method: 'POST',
    authority: 'merchant.com',
    path: '/api/payments',
    contentDigest: 'sha-256=:...:',
  },
  privateKeyHex,
  'did:agent:shopping-bot'
);

// 3. Send payment via QUIC
const mandate = {
  mandate_id: 'mandate_001',
  agent: '[email protected]',
  holder: '[email protected]',
  amount: 5000,
  currency: 'USD',
  period: 'single',
  kind: 'intent'
};

const response = await transport.sendPayment({
  ...mandate,
  signature: signed.signature,
  public_key: Buffer.from(agent.publicKey()).toString('hex')
});

console.log(`Transaction ID: ${response.transactionId}`);
console.log(`Status: ${response.status}`);
console.log(`Latency: ${response.processingTime}ms`);

await transport.close();

Performance Benefits:

• 50-70% faster than HTTP/2 for payment authorization
• 0-RTT reconnection for sub-millisecond session resumption
• Connection migration for seamless mobile network handoffs
• 100+ concurrent streams per connection
• No head-of-line blocking unlike HTTP/2

Use case: High-frequency trading, real-time payments, mobile commerce, and latency-sensitive payment flows where every millisecond counts.

Agent Fleet Management

Deploy multiple specialized AI agents with consensus-based approval for high-value transactions:

import { VerificationSystemBuilder, AgentIdentity } from 'agentic-payments';

// Create specialized agent fleet
const purchasingAgent = await AgentIdentity.generate();
const financeAgent = await AgentIdentity.generate();
const complianceAgent = await AgentIdentity.generate();
const auditAgent = await AgentIdentity.generate();

// Require 75% consensus for payment approval
const fleetSystem = new VerificationSystemBuilder()
  .consensusThreshold(0.75)
  .minAgents(3)
  .addAgent(purchasingAgent)
  .addAgent(financeAgent)
  .addAgent(complianceAgent)
  .addAgent(auditAgent)
  .build();

console.log('✅ Multi-agent payment authorization system active');
console.log(`Agents: ${fleetSystem.metrics().totalVerifications}`);
console.log(`Consensus: 75% required (3 of 4 agents)`);

Use case: Enterprise workflows where purchases require multi-party approval, segregation of duties, or Byzantine fault tolerance against compromised agents.

📖 API Reference

Complete TypeScript/JavaScript API for programmatic integration into applications.

Active Mandate API

Core functions for mandate validation, signature verification, and execution guards:

import {
  validateAndVerify,
  guardExecution,
  revoke,
  isRevoked,
  getAllRevocations
} from 'agentic-payments';

// Validate schema and verify Ed25519 signature
const result = validateAndVerify(signedMandate);
if (result.valid && result.parsed) {
  console.log('✓ Valid mandate');
}

// Check execution guards (time windows, revocation)
const guard = guardExecution(result.parsed);
if (guard.allowed) {
  // Execute payment
} else {
  console.log(`Blocked: ${guard.reason}`);
}

// Revoke mandate
const revocation = revoke('mandate_123', 'User cancelled');

// Check revocation status
if (isRevoked('mandate_123')) {
  console.log('Mandate has been revoked');
}

// List all revocations
const revocations = getAllRevocations();
console.log(`Total revoked: ${revocations.length}`);

Agent Identity

Generate Ed25519 keypairs for AI agents, sign messages, and verify cryptographic signatures:

import { AgentIdentity } from 'agentic-payments';

// Generate new Ed25519 keypair
const agent = await AgentIdentity.generate();
console.log(`Agent ID: ${agent.id}`);
console.log(`Public Key: ${Buffer.from(agent.publicKey()).toString('hex')}`);

// Sign message
const message = new TextEncoder().encode('payment authorization');
const signature = await agent.sign(message);

// Verify signature
const isValid = AgentIdentity.verify(
  agent.publicKey(),
  message,
  signature.bytes
);
console.log(`Valid signature: ${isValid}`);

Verification System

Build multi-agent consensus systems with configurable thresholds and Byzantine fault tolerance:

import { VerificationSystemBuilder } from 'agentic-payments';

const system = new VerificationSystemBuilder()
  .consensusThreshold(0.67)  // 67% agreement required
  .minAgents(2)
  .maxAgents(10)
  .timeout(5000)             // 5 second timeout
  .parallel(true)            // Parallel verification
  .addAgent(agent1)
  .addAgent(agent2)
  .addAgent(agent3)
  .build();

// Verify with consensus
const result = await system.verifyWithConsensus(signature, message, publicKey);

console.log(`Verified: ${result.isValid}`);
console.log(`Consensus: ${result.consensusReached}`);
console.log(`Agents: ${result.agentResults.length}`);

// Get metrics
const metrics = system.metrics();
console.log(`Total verifications: ${metrics.totalVerifications}`);
console.log(`Success rate: ${metrics.successfulVerifications / metrics.totalVerifications}`);

// Cleanup
system.shutdown();

Intent Mandates

High-level purchase authorizations with maximum amounts and expiration times:

import { IntentMandate } from 'agentic-payments';

const mandate = new IntentMandate({
  merchantId: 'merchant_123',
  customerId: 'customer_456',
  intent: 'Purchase premium subscription',
  maxAmount: 99.99,
  currency: 'USD',
  expiresAt: Date.now() + 86400000
});

await mandate.sign(agent);

// Validate before use
const validation = mandate.validate();
if (!validation.valid) {
  console.error('Errors:', validation.errors);
}

const json = mandate.toJSON();

Cart Mandates

Shopping cart approvals with line-item details and automatic total calculation:

import { CartMandate } from 'agentic-payments';

const cart = new CartMandate({
  merchantId: 'shop_123',
  customerId: 'user_456',
  items: [
    { id: 'item1', name: 'Product A', quantity: 2, unitPrice: 1999 },
    { id: 'item2', name: 'Product B', quantity: 1, unitPrice: 2999 }
  ],
  currency: 'USD',
  expiresAt: Date.now() + 3600000
});

await cart.sign(agent);

const items = cart.getItems();
const total = cart.getTotalAmount();
console.log(`Total: $${(total / 100).toFixed(2)}`);

Payment Mandates

Track payment lifecycle from authorization through capture with status management:

import { PaymentMandate } from 'agentic-payments';

const payment = new PaymentMandate({
  sourceId: 'intent_123',
  type: 'intent',
  amount: 99.99,
  currency: 'USD',
  paymentMethod: 'card_1234'
});

await payment.sign(agent);
payment.updateStatus('authorized');
payment.updateStatus('captured');

console.log(`Status: ${payment.getStatus()}`);
console.log(`Complete: ${payment.isComplete()}`);

Visa TAP QUIC Transport

Ultra-low latency payment transport with RFC 9421 HTTP message signatures:

import {
  VisaTapQuicTransport,
  signHttpMessage,
  verifyHttpSignature,
  computeContentDigest
} from 'agentic-payments/visa-tap';

// Create QUIC transport
const transport = new VisaTapQuicTransport({
  host: 'payments.merchant.com',
  port: 8443,
  enable0RTT: true,
  timeout: 5000
});

await transport.connect();

// Sign HTTP request per RFC 9421
const body = new TextEncoder().encode(JSON.stringify(mandate));
const contentDigest = computeContentDigest(body);

const signed = await signHttpMessage(
  {
    method: 'POST',
    authority: 'payments.merchant.com',
    path: '/v1/payments',
    contentDigest,
    headers: {
      'Content-Type': 'application/json'
    }
  },
  privateKeyHex,
  'did:agent:payment-bot'
);

// Send payment
const response = await transport.sendPayment(signedMandate);

// Get connection statistics
const stats = transport.getStats();
console.log(`RTT: ${stats?.rtt}ms`);
console.log(`Bytes sent: ${stats?.bytesSent}`);

await transport.close();

API Reference:

| Method | Description | Returns | |--------|-------------|---------| | constructor(config) | Create QUIC transport | VisaTapQuicTransport | | connect() | Establish connection | Promise<void> | | sendPayment(mandate) | Send signed mandate | Promise<PaymentResponse> | | send(data) | Send raw data | Promise<any> | | getStats() | Get connection stats | QuicStats \| null | | isConnected() | Check connection status | boolean | | close() | Close connection | Promise<void> |

RFC 9421 Functions:

| Function | Description | Returns | |----------|-------------|---------| | signHttpMessage() | Sign HTTP request | Promise<SignedHttpMessage> | | verifyHttpSignature() | Verify signature | Promise<boolean> | | computeContentDigest() | SHA-256 digest | string |

Error Handling

Typed error handling with recovery detection and formatted error messages:

import { PaymentError, isRecoverable, formatError } from 'agentic-payments';

try {
  const result = await system.verifyWithConsensus(sig, msg, pubkey);
} catch (error) {
  if (error instanceof PaymentError) {
    console.error(`Error: ${error.code}`);
    console.error(`Recoverable: ${error.recoverable}`);

    if (isRecoverable(error)) {
      // Retry logic
    }
  }
  console.error(formatError(error));
}

🏗️ Architecture

Modular architecture with clear separation between protocols, cryptography, and interfaces:

agentic-payments/
├── src/
│   ├── index.ts              # Main exports
│   ├── identity.ts           # Ed25519 agent identities
│   ├── verification.ts       # Multi-agent consensus
│   ├── mandate.ts            # Payment mandates
│   ├── errors.ts             # Error handling
│   ├── active-mandate/       # Active Mandate implementation
│   │   ├── types.ts          # TypeScript types
│   │   ├── schema.ts         # Zod validation
│   │   ├── signing.ts        # Ed25519 signing
│   │   ├── revocation.ts     # Revocation store
│   │   └── i18n.ts           # Internationalization
│   ├── visa-tap/             # Visa TAP QUIC integration
│   │   ├── types.ts          # Visa TAP TypeScript types
│   │   ├── quic-transport.ts # QUIC transport bridge
│   │   ├── rfc9421.ts        # RFC 9421 HTTP signatures
│   │   └── index.ts          # Visa TAP exports
│   ├── cli/                  # Command-line interface
│   │   ├── index.ts          # CLI entry point
│   │   └── commands/         # CLI commands
│   ├── mcp/                  # Model Context Protocol
│   │   ├── server.ts         # MCP server
│   │   └── tools/            # MCP tools
│   ├── ap2/                  # Agent Payments Protocol
│   └── acp/                  # Agentic Commerce Protocol
└── dist/                     # Compiled output

🔒 Security Best Practices

Production deployment guidelines for secure payment authorization:

Key Management

Development vs Production:

• ⚠️ MCP sign_mandate tool: Development/testing ONLY. Never use in production.
• ✅ Production: Use Hardware Security Modules (HSM) or Key Management Services
  • AWS KMS, Azure Key Vault, Google Cloud KMS
  • Sign mandates in secure enclaves
  • Never transmit private keys over network

Key Rotation:

• Rotate agent signing keys quarterly
• Maintain key version metadata in mandate records
• Support multiple active keys during rotation periods
• Revoke old mandates when rotating keys

Signature Validation

RFC 9421 Timestamp Checks:

// verifyHttpSignature includes timestamp validation (default: 5 minutes)
const isValid = await verifyHttpSignature(components, signed, publicKey, 300);

Replay Protection:

• Nonce-based replay prevention (16-byte cryptographic nonces)
• Timestamp validation (configurable max age, default 300 seconds)
• Store processed nonces to prevent replay attacks

Rate Limiting

Implement application-level rate limiting:

// Example: Limit verification attempts per IP
const limiter = rateLimit({
  windowMs: 15 * 60 * 1000, // 15 minutes
  max: 100, // 100 requests per window
  handler: (req, res) => res.status(429).send('Too many requests')
});

app.post('/verify', limiter, verifyHandler);

Network Security

QUIC Transport:

• TLS 1.3 encryption by default (no configuration needed)
• Certificate pinning for merchant endpoints
• Monitor connection statistics for anomalies

MCP Server:

• Use stdio transport for local development only
• HTTP transport requires reverse proxy with TLS in production
• Implement authentication middleware for HTTP endpoints

Logging and Monitoring

Structured Logging:

// Don't log sensitive data
logger.info('Payment authorized', {
  mandateId: mandate.mandate_id,
  amount: mandate.cap.amount,
  // DO NOT log: private keys, signatures, personal data
});

Security Monitoring:

• Alert on repeated verification failures (potential attack)
• Monitor for unusual spending patterns
• Track revocation requests for anomalies
• Log all mandate creation with agent identities

Compliance

• PCI DSS: agentic-payments handles authorization only, not card data
• GDPR: Minimize personal data in mandate metadata
• Audit Trail: All mandates are cryptographically signed and immutable
• Data Retention: Implement mandate expiration and cleanup policies

📊 Performance

Optimized for low-latency payment authorization with minimal bundle impact:

| Operation | Time | Notes | |-----------|------|-------| | Ed25519 Sign | ~2ms | Single signature | | Ed25519 Verify | ~3ms | Single verification | | Consensus (3 agents) | ~10ms | Byzantine fault tolerance | | Mandate Validation | <1ms | Schema + business rules | | QUIC Connection | ~100ms | First connection (vs 300ms HTTP/2) | | QUIC Reconnection | <1ms | 0-RTT session resumption | | RFC 9421 Signing | ~2ms | HTTP message signature | | Bundle Size | <200KB | Gzipped, tree-shakeable |

QUIC Transport Performance

Comparison with HTTP/2 for payment authorization:

| Metric | QUIC (Visa TAP) | HTTP/2 | Improvement | |--------|-----------------|--------|-------------| | First connection | 100ms | 300ms | 66% faster | | Reconnection | <1ms (0-RTT) | 200ms | 99.5% faster | | Mobile handoff | Seamless | Connection drop | Connection migration | | Concurrent streams | 100+ | 100+ | Equal | | Head-of-line blocking | None | Present | Better reliability |

📄 License

Licensed under either of:

• MIT License (LICENSE-MIT)
• Apache License 2.0 (LICENSE-APACHE)

🌟 Credits

• Author: rUv
• Cryptography: Ed25519 via @noble/ed25519 and tweetnacl
• Validation: Zod schemas

🔗 Links

• GitHub Repository
• npm Package
• Issue Tracker

Build the future of autonomous AI commerce 🚀

npm install agentic-payments