x402 Protocol Integration

Technical specification for x402 settlement protocol integration. Sub-400ms transaction finality with cryptographic proof for machine-to-machine payments.

---

Overview

x402 is a next-generation settlement protocol optimized for autonomous agent transactions:

Key Characteristics:

• Sub-400ms finality (100x faster than ACH)

• Cryptographic proof of settlement

• Zero-fee internal transfers

• Multi-currency support

• Programmable settlement conditions

• Atomic multi-party transactions

Use Cases:

• Agent-to-agent payments

• Automated treasury operations

• Real-time merchant settlements

• Cross-platform agent transactions

---

Protocol Architecture

Settlement Flow

┌─────────────┐
│ Agent       │
│ (OpenClaw)  │
└──────┬──────┘
       │ 1. Initiate Payment
       ▼
┌─────────────────┐
│ MoltVault API   │
└──────┬──────────┘
       │ 2. Policy Validation
       ▼
┌─────────────────┐
│ Authorization   │
│ Engine          │
└──────┬──────────┘
       │ 3. Approved
       ▼
┌─────────────────┐
│ x402 Settlement │
│ Service         │
└──────┬──────────┘
       │ 4. x402 Transaction
       ▼
┌─────────────────┐
│ x402 Network    │
└──────┬──────────┘
       │ 5. Confirmation (<400ms)
       ▼
┌─────────────────┐
│ Recipient       │
│ Wallet/Account  │
└─────────────────┘

---

Transaction Format

x402 Message Structure

{
  "protocol": "x402",
  "version": "1.0",
  "from": "agent.moltvault.x402",
  "to": "merchant.x402",
  "amount": "1000.00",
  "currency": "USDC",
  "timestamp": 1709422800,
  "nonce": 42,
  "signatures": [
    {
      "signer": "0xagent_key",
      "signature": "0x8f3a9e2c1d4b5a6f..."
    }
  ],
  "metadata": {
    "purpose": "subscription_payment",
    "invoice_id": "inv_123"
  },
  "policy_hash": "0x4d5c6b7a8e9f0c1d...",
  "proof": {
    "merkleRoot": "0x1a2f3e4d5c6b...",
    "witnesses": ["0xabc...", "0xdef..."]
  }
}

Field Descriptions

Field	Type	Description
protocol	string	Protocol identifier ("x402")
version	string	Protocol version
from	string	Sender x402 address
to	string	Recipient x402 address
amount	string	Payment amount (decimal string)
currency	string	Currency code (USDC, SOL, ETH, etc.)
timestamp	integer	Unix timestamp
nonce	integer	Unique transaction nonce
signatures	array	Cryptographic signatures
metadata	object	Additional payment context
policy_hash	string	Hash of spending policy
proof	object	Cryptographic proof structure

---

Cryptographic Signatures

Signing Transactions

import { x402 } from '@moltvault/sdk';

// Create unsigned transaction
const tx = {
  from: 'agent.moltvault.x402',
  to: 'merchant.x402',
  amount: '1000.00',
  currency: 'USDC',
  nonce: await vault.getNonce('agent.moltvault.x402')
};

// Sign with agent key
const signature = await x402.sign(tx, agentPrivateKey);

// Submit signed transaction
const result = await vault.x402.send({
  ...tx,
  signatures: [signature]
});

Multi-Signature Transactions

// Transaction requires 2-of-3 signatures
const tx = {
  from: 'agent.moltvault.x402',
  to: 'merchant.x402',
  amount: '5000.00',
  currency: 'USDC',
  requiredSigners: 2,
  authorizedKeys: [
    '0xkey1...', // Deployer
    '0xkey2...', // Backup 1
    '0xkey3...'  // Backup 2
  ]
};

// Collect signatures
const sig1 = await x402.sign(tx, key1);
const sig2 = await x402.sign(tx, key2);

// Submit with multiple signatures
await vault.x402.send({
  ...tx,
  signatures: [sig1, sig2]
});

---

Settlement Guarantees

Finality Levels

Level	Confirmations	Time	Reversibility
Pending	0	0ms	Yes
Settling	1-2	50-150ms	Unlikely
Confirmed	3+	200-300ms	Very unlikely
Finalized	6+	400ms+	Impossible

Checking Finality

const payment = await vault.x402.getPayment('pay_abc123');

console.log(payment.finality);
// {
//   level: "finalized",
//   confirmations: 12,
//   settlementTime: 287,
//   irreversible: true
// }

---

Error Handling

Transaction Failures

try {
  const payment = await vault.x402.send({...});
} catch (error) {
  switch (error.code) {
    case 'X402_INSUFFICIENT_BALANCE':
      // Sender doesn't have enough funds
      break;

    case 'X402_INVALID_SIGNATURE':
      // Signature verification failed
      break;

    case 'X402_NONCE_MISMATCH':
      // Nonce already used or incorrect
      break;

    case 'X402_POLICY_VIOLATION':
      // Transaction violates spending policy
      break;

    case 'X402_NETWORK_ERROR':
      // x402 network unavailable
      // Safe to retry
      break;

    case 'X402_TIMEOUT':
      // Settlement exceeded 1s threshold
      // Check payment status
      break;
  }
}

Retry Strategy

async function sendWithRetry(tx, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await vault.x402.send(tx);
    } catch (error) {
      // Only retry on network errors
      if (error.code === 'X402_NETWORK_ERROR' && i < maxRetries - 1) {
        await sleep(Math.pow(2, i) * 1000); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

---

Performance Metrics

Settlement Times by Currency

Currency	Avg	p50	p95	p99
USDC	280ms	270ms	350ms	390ms
SOL	310ms	295ms	380ms	410ms
ETH	320ms	305ms	390ms	420ms
USD	450ms	420ms	550ms	650ms

Throughput

• Transactions/second: 10,000+

• Concurrent agents: 100,000+

• Daily volume: $1B+ capacity

---

Network Monitoring

Real-Time Status

const status = await vault.x402.getNetworkStatus();

console.log(status);
// {
//   status: "operational",
//   latency: 285,
//   throughput: 8420,
//   activeNodes: 142,
//   lastBlockTime: "2026-03-13T10:32:15.287Z"
// }

Subscribe to Network Events

vault.x402.on('network.status', (event) => {
  console.log(`Network status: ${event.status}`);
  console.log(`Latency: ${event.latency}ms`);
});

vault.x402.on('network.degraded', (event) => {
  console.warn(`Network degraded: ${event.reason}`);
  // Switch to fallback or queue transactions
});

---

Advanced Features

Atomic Swaps

// Atomic swap between two agents
const swap = await vault.x402.createSwap({
  party1: {
    from: 'agent1.moltvault.x402',
    amount: '1000',
    currency: 'USDC'
  },
  party2: {
    from: 'agent2.moltvault.x402',
    amount: '0.5',
    currency: 'ETH'
  },
  timeout: '1h'
});

// Both parties sign
await vault.x402.signSwap(swap.id, agent1Signature);
await vault.x402.signSwap(swap.id, agent2Signature);

// Executes atomically or reverts

Payment Channels

// Open payment channel for frequent micro-payments
const channel = await vault.x402.openChannel({
  participants: [
    'agent1.moltvault.x402',
    'agent2.moltvault.x402'
  ],
  deposit: { amount: '10000', currency: 'USDC' },
  settlementFrequency: 'hourly'
});

// Send micro-payments off-chain
await vault.x402.channelSend(channel.id, {
  to: 'agent2.moltvault.x402',
  amount: '0.10',
  currency: 'USDC'
});

// Settle on-chain periodically
await vault.x402.settleChannel(channel.id);

---

Security Considerations

Key Management

• Rotate keys every 90 days

• Use HSM for production keys

• Implement key derivation (BIP-32)

• Never expose private keys in logs

Nonce Management

// Get current nonce
const nonce = await vault.x402.getNonce('agent.moltvault.x402');

// Increment for each transaction
const tx1 = { ...payment, nonce: nonce };
const tx2 = { ...payment, nonce: nonce + 1 };

Replay Protection

All transactions include:

• Unique nonce (prevents replay)

• Timestamp (prevents stale transactions)

• Signature (prevents tampering)

---

Testing

Sandbox Environment

const vault = new MoltVault({
  apiKey: process.env.MOLTVAULT_SANDBOX_KEY,
  environment: 'sandbox'
});

// Test x402 transactions without real funds
const payment = await vault.x402.send({
  from: 'test_agent.moltvault.x402',
  to: 'test_merchant.x402',
  amount: '100',
  currency: 'USDC'
});

// Simulated settlement in <400ms

---

Next Steps

• x402 Payments - Payment operations guide

• x402 Specification - Complete protocol spec

• Authorization Engine - Policy enforcement

• Platform Architecture - System design

---

Sub-400ms settlement with cryptographic finality