x402 Payments

Execute instant payments with sub-400ms settlement via x402 protocol. Agent-to-agent, agent-to-merchant, and cross-platform transactions with cryptographic finality.

---

Overview

x402 is a next-generation settlement protocol optimized for machine-to-machine transactions:

• Sub-400ms Settlement - 100x faster than traditional ACH

• Cryptographic Finality - Immutable proof of payment

• Zero Internal Fees - No cost for agent-to-agent transfers

• Multi-Currency Support - USD, USDC, SOL, ETH

• Programmable Logic - Smart contract-based conditions

---

Sending Payments

Basic Payment

const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r',
  to: 'vercel.com.x402',
  amount: 250,
  currency: 'USDC',
  memo: 'Pro plan subscription - March 2026'
});

console.log(`Payment ID: ${payment.id}`);
console.log(`Settled in: ${payment.settlementTime}ms`);
console.log(`TX Hash: ${payment.x402TxHash}`);

Response:

{
  "id": "pay_9x7c5v3b2n1m",
  "from": "acc_7k3m9n2p4q1r",
  "to": "vercel.com.x402",
  "amount": "250.00",
  "currency": "USDC",
  "status": "settled",
  "settlementTime": 287,
  "x402TxHash": "0x8f3a9e2c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a8e9f0c1d2e3f4a5b6c7d8e9f0",
  "createdAt": "2026-03-13T10:32:15Z",
  "settledAt": "2026-03-13T10:32:15.287Z"
}

Payment with Metadata

const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r',
  to: 'aws.amazon.com.x402',
  amount: 1200,
  currency: 'USDC',
  memo: 'EC2 compute - March 2026',
  metadata: {
    invoiceId: 'inv_aws_march_2026',
    costCenter: 'engineering',
    project: 'ml-training',
    billingPeriod: '2026-03'
  }
});

---

Agent-to-Agent Payments

Direct Transfer

// Agent 1 sends to Agent 2
const payment = await vault.x402.send({
  from: 'acc_agent_001',
  to: 'openclaw_002.moltvault.x402',
  amount: 500,
  currency: 'USDC',
  memo: 'Shared compute costs'
});

// Zero fees, <400ms settlement

Pooled Payments

// Split payment across multiple agents
const pooledPayment = await vault.x402.sendMultiple({
  from: 'acc_main',
  recipients: [
    { to: 'agent_001.moltvault.x402', amount: 100 },
    { to: 'agent_002.moltvault.x402', amount: 150 },
    { to: 'agent_003.moltvault.x402', amount: 200 }
  ],
  currency: 'USDC',
  memo: 'Team budget allocation'
});

// Atomic execution - all or none

---

Payment Status & Tracking

Check Payment Status

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

console.log(payment.status);
// "pending" | "settling" | "settled" | "failed"

Real-Time Status Updates

// Subscribe to payment status via WebSocket
vault.x402.on('payment.status', (event) => {
  console.log(`Payment ${event.paymentId}: ${event.status}`);
  if (event.status === 'settled') {
    console.log(`Settled in ${event.settlementTime}ms`);
    console.log(`TX Hash: ${event.x402TxHash}`);
  }
});

Payment History

const payments = await vault.x402.listPayments({
  accountId: 'acc_7k3m9n2p4q1r',
  status: 'settled',
  startDate: '2026-03-01',
  endDate: '2026-03-31',
  limit: 100
});

payments.forEach(p => {
  console.log(`${p.createdAt}: ${p.amount} ${p.currency} to ${p.to}`);
});

---

Payment Confirmations

Cryptographic Proof

Every x402 payment includes cryptographic proof:

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

console.log(payment.proof);
// {
//   txHash: "0x8f3a9e2c1d4b5a6f7e8d9c0b1a2f3e4d5c6b7a8e9f0c1d2e3f4a5b6c7d8e9f0",
//   blockNumber: 12345678,
//   timestamp: "2026-03-13T10:32:15.287Z",
//   signatures: ["0xabc...", "0xdef..."],
//   merkleProof: ["0x123...", "0x456..."]
// }

Verify Payment On-Chain

const verified = await vault.x402.verifyPayment({
  txHash: payment.x402TxHash,
  expectedAmount: 250,
  expectedRecipient: 'vercel.com.x402'
});

console.log(verified);
// {
//   valid: true,
//   confirmations: 142,
//   finalized: true
// }

---

Advanced Payment Features

Scheduled Payments

// Schedule recurring payment
const scheduled = await vault.x402.createSchedule({
  from: 'acc_7k3m9n2p4q1r',
  to: 'vercel.com.x402',
  amount: 250,
  currency: 'USDC',
  schedule: {
    frequency: 'monthly',
    dayOfMonth: 1,
    startDate: '2026-04-01',
    endDate: '2026-12-31'
  },
  memo: 'Pro plan - Automated monthly payment'
});

// Cancel scheduled payment
await vault.x402.cancelSchedule(scheduled.id);

Conditional Payments

// Payment executes only if conditions are met
const conditional = await vault.x402.sendConditional({
  from: 'acc_7k3m9n2p4q1r',
  to: 'contractor.x402',
  amount: 5000,
  currency: 'USDC',
  conditions: {
    type: 'milestone_completion',
    milestoneId: 'project_phase_1',
    verificationEndpoint: 'https://api.yourapp.com/verify-milestone',
    expiresAt: '2026-04-01T00:00:00Z'
  }
});

// Payment only settles when milestone is verified

Escrow Payments

// Hold payment in escrow until release conditions met
const escrow = await vault.x402.createEscrow({
  from: 'acc_buyer',
  to: 'acc_seller',
  amount: 10000,
  currency: 'USDC',
  releaseConditions: {
    approvers: ['[email protected]', '[email protected]'],
    minApprovals: 2,
    timelock: '7d'
  },
  disputeResolver: '[email protected]'
});

// Release escrow
await vault.x402.releaseEscrow(escrow.id, {
  approver: '[email protected]',
  signature: '0xabc...'
});

---

Payment Batching

Batch Multiple Payments

// Execute multiple payments atomically
const batch = await vault.x402.batchSend({
  from: 'acc_7k3m9n2p4q1r',
  payments: [
    { to: 'aws.amazon.com.x402', amount: 1200, memo: 'EC2 compute' },
    { to: 'vercel.com.x402', amount: 250, memo: 'Hosting' },
    { to: 'openai.com.x402', amount: 800, memo: 'API credits' },
    { to: 'anthropic.com.x402', amount: 500, memo: 'Claude usage' }
  ],
  currency: 'USDC'
});

console.log(`Batch ${batch.id}: ${batch.payments.length} payments`);
console.log(`Total: ${batch.totalAmount} ${batch.currency}`);
console.log(`Settled in: ${batch.settlementTime}ms`);

---

Cross-Currency Payments

Automatic Conversion

// Pay in different currency than account holds
const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r', // USDC account
  to: 'merchant.x402',
  amount: 1,
  currency: 'ETH', // Pay in ETH
  conversionRate: 'market', // Use current market rate
  slippageTolerance: 0.5 // 0.5% slippage
});

console.log(payment.conversion);
// {
//   fromCurrency: "USDC",
//   toCurrency: "ETH",
//   fromAmount: "3250.00",
//   toAmount: "1.00",
//   rate: "3250.00",
//   fee: "16.25"
// }

---

Payment Limits & Controls

Velocity Limits

Payment velocity is governed by account policies:

// Check if payment would exceed limits
const check = await vault.x402.checkLimits({
  accountId: 'acc_7k3m9n2p4q1r',
  amount: 5000,
  currency: 'USDC'
});

console.log(check);
// {
//   allowed: true,
//   dailyRemaining: "3500.00",
//   monthlyRemaining: "85000.00"
// }

Merchant Whitelisting

// Only payments to whitelisted merchants allowed
const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r',
  to: 'random-merchant.x402',
  amount: 100,
  currency: 'USDC'
});

// Rejected if merchant not in whitelist
// Error: "Merchant not whitelisted in account policy"

---

Payment Notifications

Webhooks

Receive real-time payment notifications:

await vault.webhooks.create({
  url: 'https://api.yourapp.com/webhooks/payments',
  events: [
    'payment.created',
    'payment.settling',
    'payment.settled',
    'payment.failed'
  ]
});

Webhook Payload:

{
  "event": "payment.settled",
  "data": {
    "paymentId": "pay_9x7c5v3b2n1m",
    "accountId": "acc_7k3m9n2p4q1r",
    "amount": "250.00",
    "currency": "USDC",
    "to": "vercel.com.x402",
    "settlementTime": 287,
    "x402TxHash": "0x8f3a..."
  },
  "timestamp": "2026-03-13T10:32:15.287Z"
}

---

Error Handling

Common Payment Errors

try {
  const payment = await vault.x402.send({...});
} catch (error) {
  switch (error.code) {
    case 'insufficient_balance':
      console.error('Not enough funds in account');
      break;
    case 'policy_violation':
      console.error('Payment blocked by spending policy');
      break;
    case 'invalid_recipient':
      console.error('Invalid x402 address');
      break;
    case 'rate_limit_exceeded':
      console.error('Too many payments in short period');
      break;
    default:
      console.error('Payment failed:', error.message);
  }
}

Retry Logic

async function sendPaymentWithRetry(paymentParams, maxRetries = 3) {
  for (let i = 0; i < maxRetries; i++) {
    try {
      return await vault.x402.send(paymentParams);
    } catch (error) {
      if (error.code === 'network_error' && i < maxRetries - 1) {
        await sleep(1000 * (i + 1)); // Exponential backoff
        continue;
      }
      throw error;
    }
  }
}

---

Performance & Reliability

Settlement Speed

Average settlement times by currency:

Currency	Average	p95	p99
USDC	280ms	350ms	390ms
SOL	310ms	380ms	410ms
ETH	320ms	390ms	420ms
USD	450ms	550ms	650ms

Reliability

• Success Rate: 99.98%

• Uptime: 99.95%

• Failed Payment Handling: Automatic refund to sender

---

Best Practices

1. Idempotency

Use idempotency keys to prevent duplicate payments:

const payment = await vault.x402.send({
  from: 'acc_7k3m9n2p4q1r',
  to: 'merchant.x402',
  amount: 250,
  currency: 'USDC',
  idempotencyKey: `payment-${Date.now()}-${uuid()}`
});

2. Balance Checks

Always check balance before sending:

const balance = await vault.accounts.getBalance('acc_7k3m9n2p4q1r');
if (balance.available >= paymentAmount) {
  await vault.x402.send({...});
}

3. Webhook Verification

Verify webhook signatures:

const isValid = vault.webhooks.verify(
  payload,
  signature,
  webhookSecret
);

if (!isValid) {
  throw new Error('Invalid webhook signature');
}

---

Next Steps

• Spending Policies - Configure payment authorization

• Agent Accounts - Manage account balances

• Webhooks - Real-time payment notifications

• x402 Protocol Specification - Technical details

---

Sub-400ms settlement with cryptographic finality