Dual-protocol payment infrastructure for autonomous AI commerce (AP2 + ACP)
npm install agentic-payments



> Multi-agent payment authorization system for autonomous AI commerce
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.
- β
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
``bash`Install the library
npm install agentic-payments
`bashRun stdio transport (local - for Claude Desktop, Cline)
npx -y agentic-payments mcp
π Quick Start
The library provides three interfaces: CLI commands for terminal use, MCP server for AI assistants, and programmatic API for JavaScript/TypeScript applications.
$3
Create and manage payment mandates directly from your terminal:
`bash
Create a new Active Mandate
npx agentic-payments active-mandate create \
--agent "shopping-bot@agentics" \
--holder "user@example.com" \
--amount 50000 \
--currency USD \
--period daily \
--kind intent \
--output mandate.jsonSign the mandate with Ed25519
npx agentic-payments active-mandate sign \
--file mandate.json \
--key \
--output signed-mandate.jsonVerify mandate signature and validity
npx agentic-payments active-mandate verify \
--file signed-mandate.json \
--verboseRevoke 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.
$3
The
agentic-payments MCP server supports two transport modes:Stdio Transport (recommended for local development):
`bash
Start the server in stdio mode (default)
npx -y agentic-payments mcpThe 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):
`bash
Start the HTTP server on port 3000
npx -y agentic-payments mcp --transport http --port 3000Server 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:
`bash
Check health endpoint
curl http://localhost:3000/healthResponse:
{
"status": "healthy",
"version": "0.1.0",
"server": "agentic-payments", "mcp",
"transport": "http/sse",
"activeSessions": 0
}
`$3
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.json2. Add the MCP server:
`json
{
"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):
`bash
Add the MCP server to Claude Code
claude mcp add agentic-payments npx -y agentic-payments mcpVerify it's connected
claude mcp listYou 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:
`json
{
"agentic-payments": {
"command": "npx",
"args": ["-y", "agentic-payments", "mcp"]
}
}
`HTTP/SSE Integration (remote or web applications):
`typescript
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: 'shopping-bot@example.com',
holder: 'user@example.com',
amount: 50000,
currency: 'USD',
period: 'weekly',
kind: 'intent',
expires_at: '2025-12-31T23:59:59Z'
}
});
console.log('Mandate created:', result);
`$3
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 |$3
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
`$3
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
`$3
Test stdio integration:
`bash
Test that AI can access the tools
echo '{"jsonrpc":"2.0","id":1,"method":"tools/list"}' | npx -y agentic-payments mcp
`Test HTTP integration:
`bash
Run the test suite
node tests/mcp/http-simple-test.jsOr 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!
`$3
Server won't start:
`bash
Check if port is already in use
lsof -i :3000Kill 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 stderrSession 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$3
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.
$3
`bash
Create mandate
npx agentic-payments active-mandate create [options]
-a, --agent Agent identifier
-h, --holder Holder/user identifier
--amount Spend cap (minor units, e.g., 12000 = $120.00)
--currency Currency code (default: USD)
--period Spend period: single|daily|weekly|monthly
-k, --kind Mandate kind: intent|cart
--merchant-allow Comma-separated allowed merchants
--merchant-block Comma-separated blocked merchants
--expires Expiration date (ISO8601)
-o, --output Save to fileSign mandate
npx agentic-payments active-mandate sign [options]
-f, --file Mandate file to sign
-k, --key Private key (64-byte hex)
-o, --output Save signed mandateVerify mandate
npx agentic-payments active-mandate verify [options]
-f, --file Signed mandate file
-v, --verbose Show detailed validationRevoke mandate
npx agentic-payments active-mandate revoke [options]
-i, --id Mandate ID to revoke
-r, --reason Revocation reasonList revocations
npx agentic-payments active-mandate revocations
`$3
`bash
npx agentic-payments generate --format json
`$3
`bash
npx agentic-payments verify --amount 100 --agents 5
`$3
`bash
npx agentic-payments system status
`
$3
Byzantine fault-tolerant payment verification using multiple AI agents to prevent fraud and ensure agreement:
`typescript
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.
$3
Authorize AI shopping assistants with spending limits, merchant restrictions, and time-bound budgets:
`typescript
import { AgentIdentity, CartMandate, validateAndVerify } from 'agentic-payments';// User authorizes shopping agent with Active Mandate
const mandate = {
mandate_id: 'mandate_grocery_001',
kind: 'cart',
agent: 'grocery-bot@shop.ai',
holder: 'alice@example.com',
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: 'alice@example.com',
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.
$3
AI robo-advisors execute trades autonomously within pre-approved limits and time windows:
`typescript
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.
$3
Automate accounts payable with AI agents that approve, categorize, and process vendor payments:
`typescript
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.
$3
Send payment authorizations over QUIC for 50-70% faster processing than HTTP/2:
`typescript
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: 'shopping-bot@example.com',
holder: 'user@example.com',
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.
$3
Deploy multiple specialized AI agents with consensus-based approval for high-value transactions:
`typescript
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.
$3
Core functions for mandate validation, signature verification, and execution guards:
`typescript
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});
`$3
Generate Ed25519 keypairs for AI agents, sign messages, and verify cryptographic signatures:
`typescript
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});
`$3
Build multi-agent consensus systems with configurable thresholds and Byzantine fault tolerance:
`typescript
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();
`$3
High-level purchase authorizations with maximum amounts and expiration times:
`typescript
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();
`$3
Shopping cart approvals with line-item details and automatic total calculation:
`typescript
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)});
`$3
Track payment lifecycle from authorization through capture with status management:
`typescript
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()});
`$3
Ultra-low latency payment transport with RFC 9421 HTTP message signatures:
`typescript
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 |
| sendPayment(mandate) | Send signed mandate | Promise |
| send(data) | Send raw data | Promise |
| getStats() | Get connection stats | QuicStats \| null |
| isConnected() | Check connection status | boolean |
| close() | Close connection | Promise |RFC 9421 Functions:
| Function | Description | Returns |
|----------|-------------|---------|
|
signHttpMessage() | Sign HTTP request | Promise |
| verifyHttpSignature() | Verify signature | Promise |
| computeContentDigest() | SHA-256 digest | string |$3
Typed error handling with recovery detection and formatted error messages:
`typescript
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:
$3
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 networkKey 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
$3
RFC 9421 Timestamp Checks:
`typescript
// 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
$3
Implement application-level rate limiting:
`typescript
// 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);
`$3
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
$3
Structured Logging:
`typescript
// 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
$3
- 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 |
$3
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 π
`bash
npm install agentic-payments
``