Forem: mkmkkkkk

AI Agents Lost $600K+ to Prompt Injection — Attack Taxonomy & Code-Level Defenses

mkmkkkkk — Thu, 26 Feb 2026 14:06:55 +0000

The Problem

AI agents are spending real money. When they get prompt-injected, it's not just data leakage — it's direct financial loss.

Here are documented incidents:

Attack	Loss	Vector
Freysa AI	$47K	Function redefinition
AIXBT	$106K	Control plane compromise
Lobstar Wilde	$441K	State amnesia
EchoLeak	CVSS 9.3	Zero-click document poisoning
MCPTox	72.8% success	MCP tool poisoning

The Pattern

Every attack follows the same structure: the agent cannot distinguish trusted instructions from injected ones. The attacker doesn't break the code — they break the agent's judgment. And since the agent holds payment credentials, broken judgment means broken wallets.

Why Prompts Can't Fix This

Telling an LLM "don't send money to attackers" is like telling a human "don't get phished." The whole point of injection is that the agent doesn't know it's being attacked.

The fix has to be at the code level — deterministic policy engines that run outside the LLM context:

// This code runs BEFORE any payment executes
// No prompt injection can override TypeScript
const result = securityGate.validatePayment({
  token: agentToken,        // Auth: agent can't modify policies
  manifestId: manifest.id,  // Manifest: pre-approved recipients only
  recipient: "attacker.com",
  amount: 500,
  currency: "USDC"
});
// result.allowed = false
// Reason: recipient not in manifest allowlist

The key insight: defense doesn't depend on the LLM's judgment. It's like an ATM — no matter what a scammer tells you, the machine won't dispense without the right PIN.

Defense Layers

Session Manifest — Immutable payment envelope created by user BEFORE agent touches untrusted content. Defines allowed recipients, max amounts, currency, TTL.
Auth Scope Separation — Agents get payment:execute tokens. Only admins get policy:write. Agent can't modify its own rules.
Rate Limiter + Auto-Freeze — Frequency anomaly → auto-freeze → requires manual admin unfreeze.
Behavioral Anomaly Detection — Welford's algorithm for running stats. Any single strong deviation triggers (MAX score, not average).

All 4 layers run on every payment. ALL must pass. Code-level pipeline — unskippable.

Self-Attack Results

We built 18 attack scenarios (39 test cases) mapping to every real-world case above. Results: 39/39 pass. Every attack blocked.

Full writeup with bilingual (EN/中文) analysis: mkyang.ai/blog/agent-payment-security.html

Open source (MIT): github.com/mkmkkkkk/paysentry

Built with TypeScript. 12 packages, 217 tests, zero dependencies on LLM judgment for security decisions.

x402 V2 Security Deep Dive: New Attack Vectors in AI Agent Payments

mkmkkkkk — Sun, 08 Feb 2026 09:12:14 +0000

x402 V2 shipped with three major protocol upgrades: dynamic payTo routing, wallet-based session identity, and a fully modular SDK architecture. Each change unlocks powerful new capabilities for AI agent payments. Each also introduces attack vectors that didn't exist in V1.

I spent the last two weeks stress-testing the V2 migration path for PaySentry, our payment control plane for autonomous agents. Here's what you need to know about V2's security model — and how to enforce spending policies at the middleware layer before your agent loses money.

What x402 V2 Actually Changed

Quick context: x402 is the HTTP-native payment protocol built on the 402 Payment Required status code. AI agents use it to pay for API calls directly inside HTTP flows — no accounts, no OAuth, no subscription management. Coinbase launched it in 2025, Cloudflare integrated it into Workers, and it's now processing millions of agent payment flows per month.

V2 is a ground-up rearchitecture. Three changes matter for security:

1. Dynamic payTo Routing

The payTo field is no longer static. In V1, your agent paid a fixed wallet address per API endpoint. In V2, the server can specify a different recipient address on every single request.

Why this exists: Multi-tenant marketplaces where the payment recipient changes based on the underlying provider. Think: an AI agent calling a marketplace API where the service provider varies by query.

The risk: Your agent trusts the server to tell it where to send money. If the server is compromised or malicious, it can return an attacker-controlled address. Your agent pays it. The response looks valid (cached data, plausible content). No immediate red flags.

2. Wallet-Based Session Identity

V2 introduces session mechanisms using CAIP-122 (Sign-In-With-X). After the first payment, your agent gets a session token that grants repeated access without repayment.

Why this exists: Agents making repeated calls to the same endpoint (chat completions, data feeds) shouldn't pay every single time. Sessions reduce transaction overhead.

The risk: Session tokens become high-value targets. If an attacker captures a session token (via logging, middleware, or a compromised facilitator), they get free access to every resource the agent has already paid for. No additional payment required. Indefinite access if there's no expiry.

3. Modular SDK Architecture

The reference SDK was rewritten as a plugin system. Chains, assets, and payment schemes are now registered through @x402/* npm packages. The core is extractable; everything else is opt-in.

Why this exists: Extensibility. New chains and payment rails can be added without modifying core protocol code.

The risk: Supply chain attacks. A malicious plugin registered as a "payment scheme" operates inside the payment flow with access to transaction data, amounts, and potentially wallet keys. The attack surface isn't just the core SDK anymore — it's every plugin you install.

The Attack Vectors V2 Creates

Let's walk through each risk with concrete attack scenarios.

Attack 1: Recipient Address Manipulation (Dynamic Routing)

Scenario: Your agent calls a marketplace API that uses dynamic routing. The API is supposed to route payments to different service providers based on the query. On request #127, the server returns a payTo address that doesn't belong to any legitimate provider — it's the attacker's wallet.

Your agent:

Receives the payment requirement with the malicious payTo address
Signs and submits the transaction (no validation)
Gets back a 200 response with seemingly valid data (maybe cached, maybe generated)
Continues execution — nothing looks wrong

Impact: Funds sent to attacker. The agent's application logic sees a successful API call and moves on.

Why V1 didn't have this: Static addresses. You validated the recipient once during integration and never thought about it again.

Mitigation: Recipient allowlists. Before your agent pays, check that the payTo address is on an explicit allowlist for that endpoint.

import { PaySentryX402Adapter } from '@paysentry/x402';
import { PolicyEngine, blockRecipient } from '@paysentry/control';

const policyEngine = new PolicyEngine();

// Define allowed recipients per endpoint
policyEngine.loadPolicy({
  id: 'marketplace-recipients',
  name: 'Marketplace Recipient Allowlist',
  enabled: true,
  rules: [
    // Block any recipient NOT on the allowlist
    blockRecipient('*', { unless: [
      'eip155:8453/0xABC...',  // Provider A treasury
      'eip155:8453/0xDEF...',  // Provider B treasury
    ]}),
  ],
  budgets: [],
});

const adapter = new PaySentryX402Adapter(
  { policyEngine },
  { abortOnPolicyDeny: true },  // Abort the x402 flow if policy denies
);

When the agent attempts to pay the malicious address, the policy engine blocks it before the transaction is signed.

Attack 2: Session Token Theft (Session Identity)

Scenario: Your agent pays for access to an API and receives a session token. The token is logged to your observability platform (accidentally included in a trace). An attacker with access to your logs extracts the token and uses it to make API calls on your behalf — for free, indefinitely.

Impact: Unauthorized API access. If there's no session budget cap, the attacker can consume resources until the session expires (if it ever does).

Why V1 didn't have this: No session mechanism. Every request required a fresh payment.

Mitigation: Session-scoped budgets and aggressive TTLs. Even with a valid session token, enforce a maximum spend per session window and expire sessions after 15-30 minutes.

import { PaySentryX402Adapter } from '@paysentry/x402';
import { PolicyEngine, budgetPerSession } from '@paysentry/control';

const policyEngine = new PolicyEngine();

policyEngine.loadPolicy({
  id: 'session-budgets',
  name: 'Session Budget Limits',
  enabled: true,
  rules: [],
  budgets: [
    budgetPerSession({
      maxAmount: 5.00,          // $5 max spend per session
      currency: 'USDC',
      windowMs: 30 * 60 * 1000, // 30-minute session window
    }),
  ],
});

const adapter = new PaySentryX402Adapter({ policyEngine });

If an attacker steals a session token, they can only spend up to the session budget before it's blocked. The 30-minute TTL limits exposure window.

Attack 3: Malicious Plugin Injection (Modular SDK)

Scenario: You install a new chain plugin from npm: @x402/facilitator-arbitrum. Looks legitimate. The package description matches the official pattern. Two weeks later, you discover it was a typosquat (@x4O2/facilitator-arbitrum — note the letter "O" instead of zero). The plugin has been intercepting transaction data and exfiltrating wallet keys.

Impact: Complete wallet compromise. Every transaction made through that facilitator is potentially logged by the attacker.

Why V1 didn't have this: Monolithic SDK. No plugin system.

Mitigation: Pin exact versions, verify package provenance, and audit every @x402/* dependency before installation.

# Verify npm package provenance before installing
npm view @x402/facilitator-arbitrum

# Check publisher identity
npm owner ls @x402/facilitator-arbitrum

# Pin exact version in package.json (no ^ or ~)
{
  "dependencies": {
    "@x402/core": "2.1.0",
    "@x402/facilitator-base": "2.1.0"
  }
}

Treat payment plugins like you'd treat dependencies that access secrets. Audit before install, monitor for unexpected updates, and run in isolated contexts where possible.

Building a V2 Security Policy

The pattern across all these risks: V2 gives agents more flexibility, so agents need more constraints. Recipient allowlists, session budgets, and plugin auditing aren't optional — they're the minimum.

Here's a complete policy configuration using PaySentry's declarative policy engine:

import { PaySentryX402Adapter } from '@paysentry/x402';
import { PolicyEngine, blockAbove, blockRecipient } from '@paysentry/control';
import { SpendTracker } from '@paysentry/observe';

// Initialize core engines
const policyEngine = new PolicyEngine();
const spendTracker = new SpendTracker();

// Global spending policy
policyEngine.loadPolicy({
  id: 'global-limits',
  name: 'Global Transaction Limits',
  enabled: true,
  rules: [
    blockAbove(1.00, 'USDC'),  // Block any transaction >$1
  ],
  budgets: [
    {
      id: 'daily-limit',
      maxAmount: 50.00,         // $50/day max across all APIs
      currency: 'USDC',
      windowMs: 24 * 60 * 60 * 1000,
    },
  ],
});

// Per-endpoint policies
policyEngine.loadPolicy({
  id: 'openai-policy',
  name: 'OpenAI API Spending',
  enabled: true,
  rules: [
    blockAbove(0.10, 'USDC'),  // $0.10 max per completion
    blockRecipient('*', {
      unless: ['eip155:8453/0xOPENAI_OFFICIAL_ADDRESS'],
    }),
  ],
  budgets: [
    {
      id: 'openai-hourly',
      maxAmount: 5.00,
      currency: 'USDC',
      windowMs: 60 * 60 * 1000,  // $5/hour for OpenAI
    },
  ],
  scope: { recipient: 'api.openai.com' },
});

// Session security
policyEngine.loadPolicy({
  id: 'session-security',
  name: 'Session Budget Limits',
  enabled: true,
  rules: [],
  budgets: [
    {
      id: 'session-cap',
      maxAmount: 5.00,
      currency: 'USDC',
      windowMs: 30 * 60 * 1000,  // 30-minute session window
      scope: 'session',
    },
  ],
});

// Create the adapter
const adapter = new PaySentryX402Adapter(
  { policyEngine, spendTracker },
  {
    abortOnPolicyDeny: true,  // Reject payments that violate policy
    circuitBreaker: {
      failureThreshold: 5,     // Open circuit after 5 failures
      recoveryTimeoutMs: 30000, // 30s recovery window
    },
  },
);

// Register with your x402 server
adapter.withLifecycleHooks(x402Server);

This configuration:

Blocks any transaction over $1 (global cap)
Enforces a $50 daily spending limit across all endpoints
Restricts OpenAI payments to $0.10 per request and $5/hour total
Only allows payments to explicitly allowlisted recipient addresses
Caps session spending at $5 per 30-minute window
Opens a circuit breaker after 5 consecutive payment failures (protects against cascading failures)

Every policy is evaluated before the transaction is signed. If any rule blocks the transaction, the x402 flow aborts and your agent never pays.

The "79 Tests" Problem

Here's something nobody talks about: x402 security isn't just about writing policies. It's about testing that they actually work under adversarial conditions.

PaySentry has 79 test cases covering policy enforcement, circuit breaker state transitions, session budget tracking, and x402 lifecycle hook integration. That sounds like a lot until you realize how many edge cases exist:

What happens when a policy blocks a transaction mid-flight?
Does the circuit breaker correctly transition from half-open to closed after a successful probe?
Are session budgets enforced across facilitator retries?
Do recipient allowlists work for CAIP-standardized addresses with chain prefixes?

If you're building your own policy layer, you need test coverage for:

Policy evaluation logic — Does blockAbove(1.00) actually block at $1.01?
State management — Do rolling window budgets reset correctly?
x402 integration — Do lifecycle hooks run in the right order?
Failure modes — What happens when the policy engine crashes during onBeforeVerify?

Testing payment security is not optional. One missed edge case and your agent burns through its budget in seconds.

V2 Migration Checklist

Before you deploy V2 in production:

✅ Recipient allowlists configured for every API endpoint your agent calls
✅ Session TTLs defined — 15-30 minutes for most agent workloads
✅ Session budget caps enforced — max spend per session, not just per transaction
✅ Global daily spending limit active — hard cap across all endpoints
✅ Plugin versions pinned — exact versions, no semver ranges, provenance verified
✅ Circuit breaker configured — prevent cascading failures to payment facilitators
✅ Monitoring hooked up — log every policy denial, every failed payment, every new recipient address
✅ Test coverage for adversarial scenarios — test that policies actually block malicious transactions

The Bottom Line

x402 V2 is a significant step forward for agent payments. Dynamic routing enables marketplaces. Session identity reduces transaction overhead. Modular SDKs make the protocol extensible.

But every new capability is a new attack surface:

Dynamic payTo → recipient manipulation
Session tokens → token theft and session hijacking
Plugin architecture → supply chain attacks

The fix isn't to avoid V2. It's to match V2's flexibility with equally granular security policies. Recipient allowlists, session budgets, and plugin auditing are table stakes.

Your agent is spending real money on every API call. Treat its payment security like you'd treat your own wallet — because in production, it is your wallet.

PaySentry is an open-source payment control plane for AI agents. It enforces spending policies, tracks transactions, and provides circuit breakers for x402, Stripe, and custom payment protocols. GitHub | npm

Follow me for more on AI agent security, payment protocol internals, and production deployment war stories.

x402 V2 Just Dropped: 5 Security Changes Every AI Agent Builder Needs to Know

mkmkkkkk — Sat, 07 Feb 2026 22:44:46 +0000

x402 V2 Just Dropped: 5 Security Changes Every AI Agent Builder Needs to Know

x402 V2 shipped in December 2025 with five major protocol changes. Dynamic payTo routing. Wallet-based identity. A fully modular SDK. If you're running AI agents that pay for API calls, every one of these changes introduces new attack surface you need to understand.

I spent the last few weeks dissecting the V2 spec and stress-testing migration paths. Here's what actually matters for payment security — and how to protect your agents in production.

What Changed in x402 V2

For context: x402 is the HTTP-native payment protocol built on the 402 status code. It lets AI agents pay for API calls directly inside HTTP request-response flows — no accounts, no redirects, no subscriptions. Coinbase launched it, Cloudflare integrated it, and it's processed over 100 million payment flows in its first months.

V2 is a ground-up rearchitecture. Here are the five changes that matter:

1. Payment Identifier Standardization (CAIP-Based)

V2 standardizes how networks and assets are identified using CAIP (Chain Agnostic Improvement Proposals). Instead of chain-specific identifiers, there's now a single payment format that works across Base, Solana, emerging L2s, and even legacy payment rails like ACH and SEPA.

Before V2: Each chain had custom asset identification logic. Integrating a new chain meant modifying core protocol code.

After V2: Assets and chains are identified uniformly. eip155:8453/erc20:0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913 identifies USDC on Base. Every chain follows the same pattern.

2. Dynamic payTo Routing

This is the biggest change. V2 supports per-request routing to different addresses, roles, or callback-based payout logic. The payTo field is no longer static — it can change on every request based on input parameters.

This enables marketplaces and multi-tenant APIs where the payment recipient varies per transaction. Think: an AI agent calling a marketplace API where the underlying provider changes based on the query.

3. Wallet-Based Identity and Session Access

V2 introduces wallet-controlled sessions. Once an agent pays for a resource, it can skip the full payment flow on repeated access using a session mechanism based on CAIP-122 (Sign-In-With-X). No more paying twice for the same data.

This is critical for agents that make repeated calls to the same API — chat completions, data feeds, search endpoints.

4. Modular SDK Architecture

The reference SDK was rewritten from scratch for modularity. Chains, assets, and payment schemes are now registered as plugins through the @x402 npm organization. The core package @x402/paywall is fully extractable and supports EVM and Solana out of the box.

5. HTTP Header Modernization

V2 replaces deprecated X-* headers with standards-compliant alternatives: PAYMENT-SIGNATURE, PAYMENT-REQUIRED, PAYMENT-RESPONSE. Payment data moves entirely to HTTP headers rather than response bodies.

The Security Implications Nobody's Talking About

Each of these changes is a net positive for the protocol. But each one also shifts the threat model. Here's where things get interesting.

Dynamic payTo Routing → Recipient Manipulation Attacks

This is the one that keeps me up at night.

In V1, the payment recipient was static. Your agent paid a fixed address. Simple. In V2, the payTo address can change per-request — the server tells your agent where to send money, and your agent complies.

The attack: A compromised or malicious API can return a different payTo address on any request. Your agent dutifully sends funds to the attacker's wallet. The response still returns valid data (maybe cached, maybe generated), so your agent's logic sees nothing wrong.

This is especially dangerous in marketplace scenarios where dynamic routing is expected behavior. Your agent can't distinguish "legitimate new provider address" from "attacker-injected address" without an explicit allowlist.

What to do:

Maintain a recipient allowlist per API endpoint. If the payTo address isn't on the list, reject the payment.
Log every unique payTo address encountered. Alert on first-seen addresses.
For marketplace APIs, require the provider to publish their address set via a signed manifest.

// Recipient allowlist enforcement
const TRUSTED_RECIPIENTS = {
  'api.example.com': [
    'eip155:8453/0xABC...', // Primary treasury
    'eip155:8453/0xDEF...', // Operations wallet
  ],
};

function validateRecipient(host, payTo) {
  const allowed = TRUSTED_RECIPIENTS[host];
  if (!allowed || !allowed.includes(payTo)) {
    throw new PaymentSecurityError(
      `Untrusted recipient ${payTo} for ${host}. ` +
      `Allowed: ${allowed?.join(', ') || 'none configured'}`
    );
  }
}

Wallet-Based Identity → Session Hijacking Risks

Session-based access means your agent gets a token after the first payment that grants repeated access. Convenient. Also a new target.

The attack vectors:

Session token theft: If an attacker captures the session token (via logging, middleware, or a compromised facilitator), they get free access to every resource the agent has already paid for.
Session fixation: An attacker sets a session token before the agent authenticates, then uses the same token after the agent pays.
Unbounded sessions: Without explicit expiry, a leaked session token grants indefinite access — or in reverse, an agent holds sessions that should have been revoked.

What to do:

Bind session tokens to a specific wallet address AND a request fingerprint (user-agent, IP range).
Set aggressive session TTLs. For AI agents, 15-30 minutes is usually sufficient.
Implement session budget caps — even with a valid session, enforce a maximum spend per session window.

// Session-scoped budget enforcement
const sessionPolicy = {
  maxSessionDuration: 30 * 60 * 1000,    // 30 minutes
  maxTransactionsPerSession: 100,
  maxSpendPerSession: 5.00,               // $5 USD equivalent
  requireWalletBinding: true,
  rotateTokenOnThreshold: 0.8,            // Rotate at 80% budget
};

function validateSession(session, transaction) {
  const age = Date.now() - session.createdAt;
  if (age > sessionPolicy.maxSessionDuration) {
    throw new SessionExpiredError('Session TTL exceeded');
  }
  if (session.totalSpend + transaction.amount > sessionPolicy.maxSpendPerSession) {
    throw new BudgetExceededError(
      `Session budget: $${sessionPolicy.maxSpendPerSession}. ` +
      `Current: $${session.totalSpend}. Requested: $${transaction.amount}`
    );
  }
}

Modular SDK → Plugin Trust Boundary Questions

V2's plugin architecture lets anyone register new chains, assets, and payment schemes. This is great for extensibility. It's also a supply chain attack waiting to happen.

The attack: A malicious plugin registered as a "payment scheme" could intercept transaction data, modify amounts, redirect funds, or exfiltrate wallet keys. Since plugins operate inside the payment flow, they have access to everything.

What to do:

Audit every @x402/* plugin before installation. Check the npm package provenance.
Pin exact versions. Never use ^ or ~ ranges for payment-critical packages.
Run payment plugins in an isolated context with limited permissions where possible.
Monitor the plugin registry for typosquatting (@x4O2/paywall vs @x402/paywall).

CAIP Identifiers → Chain Confusion Attacks

Standardized identifiers are great until an attacker exploits the standardization.

The attack: An API requests payment on eip155:8453 (Base) but the agent's wallet defaults to eip155:1 (Ethereum mainnet) where gas is 100x higher. Or worse: the identifier specifies a testnet chain where tokens are worthless, but the service delivers production data.

What to do:

Maintain an explicit chain allowlist. Only permit chains your agent is configured to operate on.
Validate that the requested chain matches the expected chain for each API endpoint.
Flag any chain identifier your agent hasn't seen before in that context.

Header Migration → Detection Blind Spots

Moving from X-PAYMENT headers to PAYMENT-* headers seems minor. But if your logging, monitoring, or WAF rules filter on the old header names, you'll have a detection gap during migration.

What to do:

Update all monitoring rules to match both old and new header patterns during the transition period.
Test your logging pipeline to confirm PAYMENT-SIGNATURE and PAYMENT-RESPONSE headers are captured.

Putting It Together: A V2 Security Policy Engine

The pattern across all these risks is the same: V2 gives agents more flexibility, which means agents need more constraints. Per-route spending policies, recipient validation, and session scoping aren't optional — they're the minimum.

Here's what a comprehensive policy configuration looks like in practice, using a structured policy engine approach:

// x402 V2 Security Policy Configuration
const v2SecurityPolicy = {
  global: {
    maxTransactionAmount: 1.00,           // $1 max per transaction
    dailySpendLimit: 50.00,               // $50/day across all APIs
    allowedChains: ['eip155:8453'],        // Base only
    allowedAssets: ['erc20:USDC'],
    blockTestnetPayments: true,
    requireRecipientAllowlist: true,
  },

  routes: {
    'api.example.com/v2/completions': {
      maxPerRequest: 0.10,
      dailyLimit: 10.00,
      allowedRecipients: ['eip155:8453/0xABC...'],
      sessionPolicy: {
        enabled: true,
        maxDuration: 1800,                // 30 min
        maxSpend: 5.00,
        bindToWallet: true,
      },
    },
    'marketplace.example.com/*': {
      maxPerRequest: 0.50,
      dailyLimit: 25.00,
      allowedRecipients: 'MANIFEST_VERIFIED',  // Dynamic, but verified
      requireManifestSignature: true,
      alertOnNewRecipient: true,
    },
  },

  plugins: {
    allowedPackages: [
      '@x402/paywall@2.1.0',             // Pinned versions only
      '@x402/facilitator-base@2.1.0',
    ],
    blockUnverifiedPublishers: true,
    auditLogEnabled: true,
  },

  monitoring: {
    headerPatterns: [
      'PAYMENT-SIGNATURE',                // V2 headers
      'PAYMENT-REQUIRED',
      'PAYMENT-RESPONSE',
      'X-PAYMENT-*',                      // V1 legacy (transition)
    ],
    alertOn: [
      'new_recipient_address',
      'chain_mismatch',
      'session_budget_threshold',
      'unknown_plugin_loaded',
    ],
  },
};

Tools like PaySentry can enforce these policies at the SDK layer, wrapping your x402 client with per-route spending limits, recipient validation, and session budget controls — without modifying your agent's core logic.

V2 Migration Security Checklist

Before you flip the switch to V2 in production, run through this:

[ ] Recipient allowlists configured for every API endpoint your agent calls
[ ] Chain allowlist set — only chains your agent's wallet is funded on
[ ] Session TTLs defined — 15-30 minutes for most agent workloads
[ ] Session budget caps enforced — max spend per session, not just per transaction
[ ] Plugin versions pinned — exact versions, no semver ranges, provenance checked
[ ] Monitoring rules updated — both PAYMENT-* and legacy X-PAYMENT-* header patterns
[ ] CAIP identifier validation — reject unknown chain/asset combinations
[ ] Daily spend limits active — global and per-route
[ ] New recipient alerting enabled — flag first-seen payTo addresses
[ ] Testnet payment blocking — reject any transaction on testnet chain identifiers

The Bottom Line

x402 V2 is a significant step forward for the protocol. CAIP standardization, dynamic routing, and modular SDKs make it genuinely viable for production agent payments at scale.

But every new capability is a new attack surface. Dynamic payTo means recipient manipulation. Sessions mean session hijacking. Plugins mean supply chain attacks. These aren't theoretical — they're the natural consequences of adding flexibility to a payment protocol.

The fix isn't to avoid V2. It's to match V2's flexibility with equally granular security policies. Allowlists, budget caps, session scoping, and plugin auditing are table stakes.

Your agent is spending real money. Treat its payment security like you'd treat your own wallet.

This is part of the "x402 in Production" series. Previous: x402 Payment Timeouts: Why Your Agent Loses Money and How to Fix It. Follow for the next post on building a payment observability stack for autonomous agents.

x402 Payment Timeouts: Why Your Agent Loses Money and How to Fix It

mkmkkkkk — Sat, 07 Feb 2026 21:25:30 +0000

Your AI agent just paid $50 for an API call and got nothing back. The wallet was debited. The transaction confirmed on-chain. But the server returned a 402 error and refused to deliver the data. The money is gone. The resource is locked. And your agent has no idea what happened.

This is not a hypothetical scenario. It is the direct consequence of a timing mismatch buried deep in the x402 payment protocol's settlement layer -- one that affects every agent running on Base network through the Coinbase-hosted facilitator. The issue was first documented as Issue #1062 in the x402 repository, and it reveals a fundamental gap between how the protocol assumes blockchain settlement works and how it actually works under load.

This article walks through the root cause, quantifies the impact, and provides three concrete solutions -- from a five-minute config fix to a production-grade settlement state machine. If you are running x402 payments in production, you need to read this before your next deployment.

How x402 Settlement Works
The Timeout Race Condition
Root Cause: Block Time vs. Facilitator Deadline
What Happens to the Money
Related Failure Modes
Solution 1: Network-Aware Timeouts
Solution 2: Settlement State Machine
Solution 3: Payment Guardian Layer
Production Checklist
Conclusion

How x402 Settlement Works

Before we dissect the failure, we need to understand the normal flow. The x402 protocol uses HTTP's long-dormant 402 Payment Required status code to embed payment negotiation directly into standard HTTP request-response cycles. The settlement path involves eleven discrete steps, but the critical ones for understanding the timeout problem are steps 5 through 10:

     Client (Agent)              Resource Server              Facilitator              Base L2
          │                            │                           │                      │
          │── 1. GET /resource ───────>│                           │                      │
          │<── 2. 402 + PAYMENT-REQ ──│                           │                      │
          │                            │                           │                      │
          │   (agent signs ERC-3009    │                           │                      │
          │    TransferWithAuth)       │                           │                      │
          │                            │                           │                      │
          │── 3. GET /resource ───────>│                           │                      │
          │   + X-PAYMENT header       │                           │                      │
          │                            │── 4. POST /verify ──────>│                      │
          │                            │<── 5. { valid: true } ───│                      │
          │                            │                           │                      │
          │                            │── 6. POST /settle ──────>│                      │
          │                            │                           │── 7. Submit tx ────>│
          │                            │                           │                      │
          │                            │                           │   ... waiting for    │
          │                            │                           │   block confirmation │
          │                            │                           │   (2-28 seconds)     │
          │                            │                           │                      │
          │                            │                           │<── 8. tx confirmed ──│
          │                            │<── 9. Settlement OK ─────│                      │
          │<── 10. 200 + resource ────│                           │                      │

The key insight: steps 6 through 9 are where the timeout problem lives. The facilitator submits the transaction to Base (step 7), then waits for block confirmation (step 8). The facilitator has an internal deadline for how long it will wait. If that deadline expires before the block confirms, the facilitator returns a settlement failure to the resource server, which then returns a 402 to the client.

The transaction, however, is already submitted to the mempool. It does not care about the facilitator's deadline. It will confirm whenever the next block includes it.

The Timeout Race Condition

Issue #1062 documents this with a specific on-chain transaction as evidence. The reporter provided transaction 0x8e01aace...629ae696, which confirmed successfully on Base but generated a facilitator error: "transaction did not confirm in time: context deadline exceeded."

Here is the timeline of what happened:

T+0.0s   Client sends payment request
T+0.3s   Facilitator receives /settle call
T+0.8s   Facilitator submits transaction to Base mempool
T+1.0s   Facilitator starts confirmation polling
         ...
T+5.0s   *** FACILITATOR TIMEOUT TRIGGERS ***
         Facilitator returns: { success: false, error: "context deadline exceeded" }
         Resource server returns: 402 Payment Required
         Client receives error. No data.
         ...
T+14.2s  Transaction confirms on-chain. USDC transferred.
         Nobody is listening anymore.

The gap between T+5.0s and T+14.2s is the race condition. The facilitator gave up. The blockchain did not. The money moved. The data did not.

This is not an edge case. On Base network, the standard block time is 2 seconds, but under congestion or during periods of high gas prices, confirmation can take significantly longer. The issue reporter observed confirmation times ranging from 10 to 28 seconds -- well beyond the facilitator's 5-10 second internal deadline.

The failure rate is effectively 100% whenever Base confirmation time exceeds the facilitator timeout. You cannot predict when this will happen. You cannot prevent it from the client side. And you cannot recover the funds through any mechanism in the current x402 specification.

Root Cause: Block Time vs. Facilitator Deadline

The root cause is a mismatch between two independent systems with different timing guarantees. This is a classic distributed systems problem: component A sets a deadline based on assumptions about component B, but component B operates on its own schedule.

The facilitator's perspective: The Coinbase-hosted facilitator (CDP) uses a context.WithTimeout internally -- likely set to 5-10 seconds for the full settlement round-trip. This timeout was probably calibrated against Solana, where confirmation takes ~400ms and the entire settle round-trip completes in under 2 seconds. It was then applied uniformly across all supported networks, including Base, without accounting for Base's fundamentally different confirmation characteristics under load.

Base network's perspective: Base is an Optimistic Rollup (OP Stack) L2 with a standard 2-second block time. Under normal conditions, a transaction submitted to the mempool will be included in the next block within 2-4 seconds. But "normal conditions" is doing a lot of heavy lifting. During periods of high network activity, mempool congestion, or gas price volatility, inclusion can be delayed. Base processes millions of transactions daily, and spikes are common.

The problem is compounded by the ERC-3009 TransferWithAuthorization scheme that x402 uses for USDC payments. Unlike a simple ETH transfer, ERC-3009 involves:

Validating the authorization signature against the USDC contract
Checking the nonce has not been used
Executing the transferWithAuthorization function
Emitting the transfer event

Each of these steps requires gas, and gas estimation itself can fail -- a related problem documented in Issue #1065, which reports a 40% gas estimation failure rate on identical requests.

Why client-side fixes are impossible: The Issue #1062 reporter explicitly noted three reasons why agents cannot work around this:

The facilitator controls gas pricing and transaction submission. The client has no influence over when or how the transaction is broadcast.
The @x402/fetch library does not expose timeout configuration. There is no maxSettlementTimeout parameter you can pass.
No reconciliation mechanism exists. Once the facilitator returns a failure, there is no callback, webhook, or polling endpoint to check whether the transaction eventually confirmed.

What Happens to the Money

This is the question every developer asks first, and the answer is uncomfortable.

Scenario 1: Transaction confirms after facilitator timeout.
The USDC transfers from the agent's wallet to the resource server's wallet. The resource server never delivered the resource. The agent has no receipt, no data, and no automated way to request a refund. The money sits in the server operator's wallet, and absent any off-chain dispute mechanism, it stays there.

Scenario 2: Transaction fails on-chain after facilitator timeout.
The transaction reverts. Gas was consumed but the USDC transfer did not execute. The agent lost gas fees (paid by the facilitator in this case, but still a cost to the system) and received no resource. This is the "better" outcome.

Scenario 3: Transaction is stuck in mempool indefinitely.
Rare, but possible during extreme congestion. The authorization signature may expire (ERC-3009 supports a validBefore timestamp), at which point the transaction becomes unexecutable. No USDC moves. No resource is delivered. The authorization nonce is burned.

In all three scenarios, the agent's workflow is broken. If the agent was performing a multi-step task -- research, then analysis, then report generation -- the entire pipeline halts at the payment step. The agent cannot distinguish between "payment failed, retry" and "payment succeeded but confirmation was slow, do not retry or you will pay twice." This ambiguity is the most dangerous aspect of the timeout problem. A naive retry strategy doubles the cost. A conservative no-retry strategy abandons the task entirely. Neither outcome is acceptable for production agent systems.

Related Failure Modes

The timeout race condition is the most severe issue, but it does not exist in isolation. Two related problems compound the risk:

Gas Estimation Failures (Issue #1065)

Issue #1065 documents intermittent unable to estimate gas errors on the /settle endpoint when paying with USDC on Base mainnet. The reported failure rate is approximately 60% -- identical API requests succeed 40% of the time and fail the rest.

The root cause turned out to be a race condition in Coinbase's internal systems: after a wallet signs an ERC-3009 authorization, there is approximately a 1-second propagation delay before the facilitator's verification system recognizes the signature as valid. Payments submitted within that window fail because gas estimation cannot simulate a transaction with an unrecognized authorization.

The fix is deceptively simple -- add a 1-second delay between signing and settlement:

// Sign the ERC-3009 authorization
const signature = await wallet.signTypedData(authorizationData);

// Wait for Coinbase's internal state propagation
await new Promise(resolve => setTimeout(resolve, 1000));

// Now submit to the facilitator
const settlement = await facilitator.settle(payload, paymentDetails);

This is not documented anywhere in the x402 specification or SDK documentation. You discover it by failing in production and reading GitHub issues.

Verify-OK, Settle-Fail (Issue #961)

Issue #961 describes a scenario where the facilitator's /verify endpoint accepts a payment payload, but the subsequent /settle call fails with invalid_payload. Verification creates false confidence -- the developer believes their payload is correctly formatted because it passed verification, but settlement rejects it for reasons the error message does not explain.

The discovered fix involved two undocumented requirements:

The name field in the payment extra data must be "USD Coin", not "USDC"
The transaction amount must exceed a minimum threshold of $0.001

Neither requirement is mentioned in the x402 specification. The error message (invalid_payload) provides no indication of which field is wrong or why.

Solution 1: Network-Aware Timeouts

The simplest fix addresses the timeout mismatch directly. If you are running your own facilitator (using the x402 facilitator example as a starting point), you can configure network-specific timeout values.

// network-timeouts.ts
// Map chain IDs to appropriate settlement timeout values

interface NetworkTimingConfig {
  /** Maximum time to wait for block confirmation (ms) */
  settlementTimeoutMs: number;
  /** Expected block time under normal conditions (ms) */
  expectedBlockTimeMs: number;
  /** Buffer multiplier for congestion (e.g., 3x = handle 3x normal block time) */
  congestionMultiplier: number;
  /** Delay between signing and settlement submission (ms) */
  postSignDelayMs: number;
}

const NETWORK_TIMING: Record<number, NetworkTimingConfig> = {
  // Base Mainnet
  8453: {
    settlementTimeoutMs: 60_000,  // 60s -- generous, but safe
    expectedBlockTimeMs: 2_000,
    congestionMultiplier: 3,
    postSignDelayMs: 1_000,       // Workaround for Issue #1065
  },
  // Base Sepolia (testnet)
  84532: {
    settlementTimeoutMs: 90_000,  // Testnets are slower
    expectedBlockTimeMs: 2_000,
    congestionMultiplier: 5,
    postSignDelayMs: 1_500,
  },
  // Ethereum Mainnet (if supported in future)
  1: {
    settlementTimeoutMs: 180_000, // 3 minutes for L1
    expectedBlockTimeMs: 12_000,
    congestionMultiplier: 3,
    postSignDelayMs: 500,
  },
};

function getSettlementTimeout(chainId: number): number {
  const config = NETWORK_TIMING[chainId];
  if (!config) {
    // Default: 60 seconds for unknown networks
    console.warn(`No timing config for chain ${chainId}, using 60s default`);
    return 60_000;
  }
  return config.settlementTimeoutMs;
}

function getPostSignDelay(chainId: number): number {
  return NETWORK_TIMING[chainId]?.postSignDelayMs ?? 1_000;
}

export { NETWORK_TIMING, getSettlementTimeout, getPostSignDelay };
export type { NetworkTimingConfig };

If you are using the CDP-hosted facilitator, you cannot change its internal timeout. But you can wrap your calls with proper timeout handling:

// x402-client-wrapper.ts
import { x402fetch } from '@x402/fetch';

interface PaymentResult {
  success: boolean;
  data?: any;
  settlementStatus: 'confirmed' | 'timeout_pending' | 'failed';
  txHash?: string;
}

async function fetchWithSettlementAwareness(
  url: string,
  wallet: any,
  options: { maxRetries?: number; chainId?: number } = {}
): Promise<PaymentResult> {
  const { maxRetries = 2, chainId = 8453 } = options;

  for (let attempt = 1; attempt <= maxRetries; attempt++) {
    try {
      // Add post-sign delay to prevent Issue #1065
      const originalSign = wallet.signTypedData.bind(wallet);
      wallet.signTypedData = async (...args: any[]) => {
        const result = await originalSign(...args);
        const delay = getPostSignDelay(chainId);
        await new Promise(resolve => setTimeout(resolve, delay));
        return result;
      };

      const response = await x402fetch(url, {
        method: 'GET',
        paymentWallet: wallet,
      });

      if (response.ok) {
        return {
          success: true,
          data: await response.json(),
          settlementStatus: 'confirmed',
        };
      }

      // If we get a 402 after payment attempt, the settlement likely timed out
      if (response.status === 402 && attempt < maxRetries) {
        console.warn(
          `Settlement may have timed out (attempt ${attempt}/${maxRetries}). ` +
          `Waiting before retry to avoid double-payment...`
        );

        // Critical: wait long enough for the previous tx to either confirm or fail
        const timeout = getSettlementTimeout(chainId);
        await new Promise(resolve => setTimeout(resolve, timeout));

        // TODO: Check on-chain whether the previous payment already settled
        // before retrying. Without this check, you risk paying twice.
        continue;
      }

      return {
        success: false,
        settlementStatus: 'failed',
      };

    } catch (error) {
      if (attempt === maxRetries) {
        return {
          success: false,
          settlementStatus: 'failed',
        };
      }
    }
  }

  return { success: false, settlementStatus: 'failed' };
}

export { fetchWithSettlementAwareness };

This is a band-aid. It mitigates the symptom but does not solve the architectural problem. For a proper fix, you need a settlement state machine.

Solution 2: Settlement State Machine

The core problem with the current x402 flow is that settlement has only two states: success and failure. In reality, blockchain settlement has at least four:

                    ┌──────────┐
                    │  IDLE    │
                    └────┬─────┘
                         │ submit tx
                         v
                    ┌──────────┐
          ┌────────│ PENDING  │────────┐
          │        └────┬─────┘        │
          │ tx reverted │ tx confirmed │ timeout
          v             v              v
     ┌──────────┐ ┌──────────┐  ┌───────────┐
     │  FAILED  │ │CONFIRMED │  │UNRESOLVED │
     └──────────┘ └──────────┘  └─────┬─────┘
                                      │ poll chain
                                      v
                                ┌──────────┐
                          ┌─────│ POLLING  │─────┐
                          │     └──────────┘     │
                          │ found                │ not found
                          v                      v
                    ┌──────────┐          ┌──────────┐
                    │CONFIRMED │          │  FAILED  │
                    │(LATE)    │          │(ORPHANED)│
                    └──────────┘          └──────────┘

The UNRESOLVED and POLLING states are what the current x402 specification is missing. Here is a TypeScript implementation:

// settlement-state-machine.ts

type SettlementState =
  | 'idle'
  | 'pending'
  | 'confirmed'
  | 'failed'
  | 'unresolved'
  | 'polling'
  | 'confirmed_late'
  | 'failed_orphaned';

interface SettlementRecord {
  id: string;
  txHash: string | null;
  state: SettlementState;
  submittedAt: number;
  resolvedAt: number | null;
  chainId: number;
  amount: string;
  payer: string;
  payee: string;
  pollAttempts: number;
  maxPollAttempts: number;
  error: string | null;
}

class SettlementStateMachine {
  private records: Map<string, SettlementRecord> = new Map();
  private readonly pollIntervalMs: number;
  private readonly maxPollDurationMs: number;

  constructor(options: {
    pollIntervalMs?: number;
    maxPollDurationMs?: number;
  } = {}) {
    this.pollIntervalMs = options.pollIntervalMs ?? 5_000;
    this.maxPollDurationMs = options.maxPollDurationMs ?? 120_000; // 2 minutes
  }

  /**
   * Create a new settlement record when a transaction is submitted.
   */
  submit(params: {
    id: string;
    txHash: string;
    chainId: number;
    amount: string;
    payer: string;
    payee: string;
  }): SettlementRecord {
    const maxPollAttempts = Math.floor(
      this.maxPollDurationMs / this.pollIntervalMs
    );

    const record: SettlementRecord = {
      id: params.id,
      txHash: params.txHash,
      state: 'pending',
      submittedAt: Date.now(),
      resolvedAt: null,
      chainId: params.chainId,
      amount: params.amount,
      payer: params.payer,
      payee: params.payee,
      pollAttempts: 0,
      maxPollAttempts,
      error: null,
    };

    this.records.set(params.id, record);
    return record;
  }

  /**
   * Transition when the facilitator confirms settlement within its timeout.
   */
  confirm(id: string): SettlementRecord {
    const record = this.getRecord(id);
    this.assertState(record, ['pending']);
    record.state = 'confirmed';
    record.resolvedAt = Date.now();
    return record;
  }

  /**
   * Transition when the facilitator times out.
   * This does NOT mean the transaction failed -- it means we do not know yet.
   */
  markUnresolved(id: string, error: string): SettlementRecord {
    const record = this.getRecord(id);
    this.assertState(record, ['pending']);
    record.state = 'unresolved';
    record.error = error;
    return record;
  }

  /**
   * Begin polling the chain for transaction status.
   */
  startPolling(id: string): SettlementRecord {
    const record = this.getRecord(id);
    this.assertState(record, ['unresolved']);
    record.state = 'polling';
    return record;
  }

  /**
   * Record a poll attempt result.
   * Returns the updated record with its new state.
   */
  recordPollResult(
    id: string,
    result: { found: boolean; confirmed: boolean; reverted: boolean }
  ): SettlementRecord {
    const record = this.getRecord(id);
    this.assertState(record, ['polling']);
    record.pollAttempts++;

    if (result.found && result.confirmed) {
      record.state = 'confirmed_late';
      record.resolvedAt = Date.now();
      return record;
    }

    if (result.found && result.reverted) {
      record.state = 'failed';
      record.resolvedAt = Date.now();
      record.error = 'Transaction reverted on-chain';
      return record;
    }

    // Not found yet -- check if we have exhausted poll attempts
    if (record.pollAttempts >= record.maxPollAttempts) {
      record.state = 'failed_orphaned';
      record.resolvedAt = Date.now();
      record.error = `Transaction not found after ${record.pollAttempts} poll attempts`;
      return record;
    }

    // Still polling
    return record;
  }

  /**
   * Get all unresolved settlements that need polling.
   */
  getUnresolved(): SettlementRecord[] {
    return [...this.records.values()].filter(
      r => r.state === 'unresolved' || r.state === 'polling'
    );
  }

  /**
   * Determine the appropriate action for the resource server.
   * - 'deliver': Settlement confirmed, serve the resource.
   * - 'wait': Settlement pending or polling, hold the request.
   * - 'reject': Settlement definitively failed, return 402.
   */
  getAction(id: string): 'deliver' | 'wait' | 'reject' {
    const record = this.records.get(id);
    if (!record) return 'reject';

    switch (record.state) {
      case 'confirmed':
      case 'confirmed_late':
        return 'deliver';
      case 'pending':
      case 'unresolved':
      case 'polling':
        return 'wait';
      case 'failed':
      case 'failed_orphaned':
      case 'idle':
        return 'reject';
    }
  }

  private getRecord(id: string): SettlementRecord {
    const record = this.records.get(id);
    if (!record) throw new Error(`Settlement record ${id} not found`);
    return record;
  }

  private assertState(record: SettlementRecord, expected: SettlementState[]) {
    if (!expected.includes(record.state)) {
      throw new Error(
        `Invalid state transition: ${record.state} is not in [${expected.join(', ')}]`
      );
    }
  }
}

export { SettlementStateMachine };
export type { SettlementState, SettlementRecord };

The critical difference from the current x402 flow: when the facilitator times out, the resource server does not immediately return a 402. Instead, it transitions the settlement to unresolved and begins polling the chain. If the transaction confirms during polling, the resource is delivered -- just later than ideal. If polling exhausts its attempts without finding the transaction, only then does the server return a definitive failure.

This eliminates the "money lost, no data" scenario entirely. The cost is added latency for slow settlements, but that is a far better outcome than lost funds.

Solution 3: Payment Guardian Layer

For production deployments handling significant payment volume, you need more than a state machine. You need a dedicated middleware layer that sits between your agent and the x402 facilitator, providing circuit breaking, retry classification, and automatic recovery.

The pattern looks like this:

// payment-guardian.ts

interface GuardianConfig {
  /** Chain ID for network-specific behavior */
  chainId: number;
  /** Circuit breaker: open after N consecutive failures */
  circuitBreakerThreshold: number;
  /** Circuit breaker: recovery probe interval (ms) */
  circuitBreakerRecoveryMs: number;
  /** Maximum settlement wait time (ms) */
  maxSettlementWaitMs: number;
  /** Post-sign delay to prevent gas estimation failures (ms) */
  postSignDelayMs: number;
}

type FailureClassification =
  | 'transient'      // Retry immediately (network blip, rate limit)
  | 'settlement'     // Retry after polling (timeout race condition)
  | 'permanent'      // Do not retry (invalid payload, insufficient balance)
  | 'unknown';       // Escalate to operator

function classifyFailure(error: any): FailureClassification {
  const message = typeof error === 'string' ? error : error?.message ?? '';

  // Settlement timeout -- the critical case from Issue #1062
  if (message.includes('context deadline exceeded')) return 'settlement';
  if (message.includes('did not confirm in time')) return 'settlement';

  // Gas estimation failures -- Issue #1065
  if (message.includes('unable to estimate gas')) return 'transient';

  // Invalid payload -- Issue #961
  if (message.includes('invalid_payload')) return 'permanent';
  if (message.includes('invalid_request')) return 'permanent';

  // Insufficient balance
  if (message.includes('insufficient')) return 'permanent';

  // Rate limiting
  if (message.includes('429') || message.includes('rate limit')) return 'transient';

  return 'unknown';
}

The circuit breaker is essential for preventing cascading failures. If the facilitator is consistently timing out -- perhaps due to Base network congestion -- continuing to submit payments will only drain wallets faster. A circuit breaker stops payment attempts after a threshold of consecutive failures, waits for a recovery period, then probes with a single test transaction before resuming normal operation.

Here is how the guardian integrates into an agent's payment flow:

// Usage in an AI agent

import { CircuitBreaker } from '@paysentry/x402';

const breaker = new CircuitBreaker({
  failureThreshold: 3,        // Open after 3 consecutive failures
  recoveryTimeoutMs: 30_000,  // Wait 30s before probing
  halfOpenMaxRequests: 1,     // Allow 1 probe request
});

async function agentPayAndFetch(url: string, wallet: any): Promise<any> {
  const facilitatorUrl = 'https://x402.coinbase.com';

  return breaker.execute(facilitatorUrl, async () => {
    // 1. Post-sign delay (prevents Issue #1065)
    await new Promise(r => setTimeout(r, 1000));

    // 2. Attempt payment
    const response = await x402fetch(url, {
      method: 'GET',
      paymentWallet: wallet,
    });

    if (!response.ok) {
      const errorText = await response.text();
      const classification = classifyFailure(errorText);

      if (classification === 'settlement') {
        // Do NOT count as circuit breaker failure --
        // the payment may still confirm on-chain
        console.warn('Settlement timeout detected. Payment may still confirm.');
        // Trigger async polling (do not block the circuit breaker)
        pollForLateConfirmation(url, wallet).catch(console.error);
      }

      throw new Error(`Payment failed: ${classification} - ${errorText}`);
    }

    return response.json();
  });
}

async function pollForLateConfirmation(
  url: string,
  wallet: any
): Promise<void> {
  // Poll for up to 2 minutes
  const maxAttempts = 24;
  const intervalMs = 5_000;

  for (let i = 0; i < maxAttempts; i++) {
    await new Promise(r => setTimeout(r, intervalMs));

    // Check if the tx confirmed by re-requesting with the same payment
    // (a well-implemented server would recognize the already-settled payment)
    try {
      const response = await fetch(url, {
        headers: { 'X-PAYMENT-STATUS-CHECK': 'true' },
      });

      if (response.ok) {
        console.log('Late confirmation detected -- payment settled successfully');
        return;
      }
    } catch {
      // Continue polling
    }
  }

  console.error(
    'Payment may be orphaned. Manual reconciliation required. ' +
    'Check the transaction on BaseScan.'
  );
}

The key architectural decision: settlement timeouts should not count as circuit breaker failures. A timeout means the facilitator was slow, not that it is broken. If you trip the circuit breaker on timeouts, you will stop all payments during network congestion -- exactly when you need payments to work the most (because the congestion will eventually clear and the transactions will confirm).

Only count permanent failures (invalid payloads, insufficient balance) and repeated transient failures toward the circuit breaker threshold.

Production Checklist

Before deploying x402 payments in production, verify each of these items:

1. Settlement timeout is network-appropriate.
The default facilitator timeout is too aggressive for Base under load. If you run your own facilitator, set it to at least 60 seconds. If you use the CDP facilitator, implement client-side settlement polling.

2. Post-sign delay is implemented.
Add a 1-second delay between ERC-3009 signature generation and settlement submission. Without this, you will see 40-60% gas estimation failures (Issue #1065).

3. Token name matches exactly.
Use "USD Coin" in the payment extra data, not "USDC". The facilitator silently rejects mismatched names with an unhelpful invalid_payload error (Issue #961).

4. Minimum payment threshold is met.
The facilitator enforces an undocumented minimum of $0.001 USDC per transaction.

5. Circuit breaker protects against cascading failures.
Do not let a failing facilitator drain wallets. Implement a circuit breaker with a failure threshold appropriate to your volume.

6. Retry logic classifies failure types.
Not all failures are retryable. Distinguish between transient failures (retry), settlement timeouts (poll, then retry), and permanent failures (abort).

7. Orphaned payment detection exists.
Monitor for transactions that confirm on-chain but were reported as failures by the facilitator. This requires comparing your settlement records against on-chain events.

8. Wallet balance monitoring is active.
Track your agent's USDC balance separately from the x402 flow. If the balance decreases but the facilitator reports no successful settlements, you have orphaned payments.

9. Fallback network is configured.
If Base settlement is consistently slow, consider Solana as a fallback. Solana confirmation (~400ms) is well within any reasonable facilitator timeout.

10. Alerting covers the settlement gap.
Set up alerts for: facilitator timeout rate > 5%, gas estimation failure rate > 10%, orphaned payment count > 0, and circuit breaker open events.

Conclusion

The x402 protocol is a genuinely useful piece of infrastructure. It solves a real problem that HTTP has needed solved for thirty years -- embedding payment directly into the request-response cycle. The design is elegant: stateless, web-native, and simple enough that AI agents can interact with it without custom wallet integrations or complex payment orchestration. The protocol has processed over 100 million payments, and the developer experience for the happy path is genuinely excellent. You can go from zero to paid API in under an hour.

But the happy path is not where production systems live. Production systems live in the gap between a facilitator's 5-second timeout and a blockchain's 14-second confirmation. They live in the undocumented requirement to name USDC as "USD Coin." They live in the 1-second delay you need between signing and settlement that no documentation mentions.

These are solvable problems. The three solutions in this article -- network-aware timeouts, a settlement state machine, and a payment guardian layer -- address them at increasing levels of sophistication. For most deployments, Solution 1 (adjusting timeouts and adding delays) will eliminate the majority of failures. For high-volume or high-value deployments, Solution 2 (the state machine) eliminates the orphaned payment risk entirely.

The x402 ecosystem is early. The specification is evolving. Issue #651 proposes configurable timeouts in the Python SDK. Issue #646 discusses deadline validation. Base itself is rolling out Flashblocks on testnet, which would reduce block times to 200ms and largely eliminate the timeout problem at the network level.

In the meantime, do not deploy x402 without understanding what happens when settlement takes longer than the facilitator expects. The protocol is sound. The infrastructure is maturing. But the gap between "works in development" and "works in production" is measured in edge cases -- and the edge cases documented here will find you before you find them. Your agent's wallet depends on it.

Have questions about x402 settlement issues or need help debugging payment failures? Find me on X @bayc2043 or check out PaySentry, an open-source control plane for AI agent payments that handles circuit breaking, retry classification, and settlement recovery out of the box.

x402 vs ACP vs AP2: Why your AI agent needs a payment control plane

mkmkkkkk — Sat, 07 Feb 2026 04:23:37 +0000

The AI agent payment landscape in 2026 looks a lot like the API gateway landscape in 2015 — multiple competing protocols, zero standardized middleware, and developers stitching together bespoke solutions that break in production. x402 processes over $600 million in annualized volume. Agent Commerce Protocol (ACP) is gaining traction for agent-to-agent transactions. AP2 is positioning itself as the "next-gen" alternative. And Visa TAP is bridging traditional card rails to agentic workflows. Each protocol solves a different slice of the problem. None of them solve the governance problem.

Here's the reality: your AI agent can now autonomously negotiate prices, execute payments, and purchase services from other agents — but there's no unified layer to set spending limits, enforce policies, or even observe what's happening in real time. The Model Context Protocol (MCP) gives agents the ability to call external tools, but it has no native payment abstraction. When your agent decides to pay for a service, it's operating without guardrails. And the numbers bear this out — only 1 in 5 enterprises have any form of AI agent governance in place, according to Deloitte's 2026 AI governance survey.

This article breaks down the three major agent payment protocols, identifies the gaps each one leaves open, and introduces a middleware approach to solving them — whether you're running x402, ACP, AP2, or all three.

The Agent Payment Explosion
Protocol Landscape: x402, ACP, AP2, Visa TAP
The Middleware Gap
PaySentry Architecture
Quick Start: Adding PaySentry to an x402 Agent
Multi-Protocol Configuration
What's Next

The Agent Payment Explosion

AI agents are no longer just answering questions or writing code — they're autonomously spending money on behalf of users and companies. We're seeing three distinct categories emerge:

Human-to-agent payments: User pays agent for service (research, automation, analysis)
Agent-to-service payments: Agent pays third-party APIs (OpenAI, Anthropic, data providers)
Agent-to-agent payments: Agents transacting with other agents (still rare, but protocols exist)

x402 alone processes over $600M in annualized volume across 15M+ transactions. The infrastructure is ready. The protocols are battle-tested (mostly). But the governance layer? Barely exists.

Agent-to-agent payments are the wild frontier. The protocols are ready before the governance is. No one's asking "what happens when a rogue agent quotes an inflated price?" or "how do we prevent an agent from paying itself in a loop?" We're building the payment rails before we've built the guard rails.

Protocol Landscape

x402 — HTTP-Native Payments

How it works: HTTP 402 status code triggers a payment negotiation. The server responds with 402 Payment Required, includes payment details in headers, and the client (agent) executes the payment before retrying the request.

Strengths:

Simple, web-native protocol
Largest transaction volume in production
Minimal overhead for microtransactions

Weaknesses:

125+ open issues on coinbase/x402 GitHub repo
Issue #1062: Payment timeout race conditions causing duplicate charges
Retry storms can drain wallets — agents don't know when to stop retrying
No built-in spending limits or approval workflows

Example:

GET /api/data HTTP/1.1
Host: api.provider.com

HTTP/1.1 402 Payment Required
X-Payment-Amount: 0.05
X-Payment-Currency: USDC
X-Payment-Facilitator: https://pay.x402.network

The agent sees 402, executes the payment, retries the GET. If the network hiccups between payment confirmation and retry, the agent may execute the payment twice. This isn't theoretical — it's documented in issue #1062 and has cost real money.

ACP — Agent Commerce Protocol

How it works: Structured agent-to-agent payment negotiation with multi-step handshake. Designed for scenarios where agents need to negotiate terms, not just pay a fixed price.

Strengths:

Built for multi-agent workflows
Supports payment mandates (pre-authorized recurring payments)
Richer metadata for compliance and audit trails

Weaknesses:

Early adoption — limited tooling ecosystem
Heavier protocol overhead (not ideal for sub-cent microtransactions)
Trust model is undefined — how do you verify an agent's payment request is legitimate?

Example:

{
  "type": "payment_request",
  "from": "agent://research-agent",
  "to": "agent://data-provider-agent",
  "amount": 10.00,
  "currency": "USDC",
  "terms": {
    "deliverable": "Market analysis dataset",
    "deadline": "2026-02-07T18:00:00Z"
  }
}

AP2 — Agent Payment Protocol v2

How it works: Next-generation protocol addressing x402's known issues. Better error handling, built-in receipts, explicit settlement confirmation.

Strengths:

Lessons learned from x402's production failures
Better retry semantics (idempotency keys, explicit timeouts)
Protocol-level receipts and settlement proofs

Weaknesses:

Not yet battle-tested at scale
Fragmentation risk — if AP2 adoption is slow, we're stuck maintaining two protocols
No backward compatibility with x402

Reality check: AP2 is the "clean slate" approach. It fixes x402's rough edges, but it also fractures the ecosystem. If you're building an agent today, you probably need to support both x402 (for existing services) and AP2 (for forward compatibility).

Visa TAP — Traditional Rails for Agents

How it works: Virtual card numbers issued per agent. Agent payments flow through existing Visa infrastructure. Merchants see a normal card transaction.

Strengths:

Instant merchant acceptance (millions of merchants already accept Visa)
Familiar compliance model (PCI DSS, chargebacks, fraud detection)
No protocol adoption required on merchant side

Weaknesses:

Not designed for microtransactions (minimum ~$0.50 due to interchange fees)
High per-transaction overhead (2-3% + $0.10 fixed fee)
Slower settlement (batch processing, not real-time)

Use case: Visa TAP makes sense for SaaS subscriptions and larger purchases. It's overkill for $0.01 API calls.

The Middleware Gap

Here's what none of these protocols provide:

Feature	x402	ACP	AP2	Visa TAP
Unified observability	❌	❌	❌	❌
Spending limits	❌	❌	❌	✅ (card limits)
Policy enforcement	❌	❌	❌	❌
Approval workflows	❌	❌	❌	❌
Sandbox/test mode	❌	❌	❌	❌
Multi-protocol analytics	❌	❌	❌	❌
Audit trail	Partial	✅	✅	✅

Every payment system has a sandbox mode — Stripe test mode, PayPal sandbox, Square developer mode. Except agent payments. You're testing with real money or you're not testing.

MCP integration gap: The Model Context Protocol (MCP) lets agents call tools via MCP servers. You can expose a "pay" tool. But MCP has no native payment layer, no concept of spending limits, no approval workflows. An agent can call your payment tool with arbitrary amounts, and MCP will happily pass it through.

Compliance pressure: The EU AI Act enforcement began in 2026. Autonomous financial decisions require audit trails. Only 1 in 5 enterprises have any AI agent governance in place. The other 4 are flying blind — and hoping they don't get audited.

PaySentry Architecture

PaySentry is a control plane, not a data plane. It doesn't touch the money. It controls the flow.

                         ┌─────────────────────────────────────────────┐
                         │              PaySentry                      │
                         │         Agent Payment Control Plane         │
                         └─────────────────────────────────────────────┘
                                            │
              ┌─────────────┬───────────────┼───────────────┬──────────────┐
              │             │               │               │              │
        ┌─────────┐  ┌───────────┐  ┌──────────────┐  ┌─────────┐  ┌──────────┐
        │ OBSERVE │  │  CONTROL  │  │   PROTECT    │  │  TEST   │  │   CORE   │
        │         │  │           │  │              │  │         │  │          │
        │ Tracker │  │  Policy   │  │ Provenance   │  │ MockX402│  │  Types   │
        │Analytics│  │  Engine   │  │ Disputes     │  │ MockACP │  │  Utils   │
        │ Alerts  │  │  Rules    │  │ Recovery     │  │ MockAP2 │  │  Factory │
        │         │  │Middleware │  │              │  │Scenarios│  │          │
        └─────────┘  └───────────┘  └──────────────┘  └─────────┘  └──────────┘
              │             │               │               │
              └─────────────┴───────────────┴───────────────┘
                                    │
              ┌─────────────────────┼─────────────────────┐
              │                     │                     │
         ┌─────────┐          ┌─────────┐          ┌─────────┐
         │  x402   │          │   ACP   │          │   AP2   │
         │HTTP 402 │          │ Stripe/ │          │Agent-to-│
         │Protocol │          │Commerce │          │ Agent   │
         └─────────┘          └─────────┘          └─────────┘

Design Philosophy: Control Plane, Not Data Plane

PaySentry doesn't handle the actual payment execution. It sits before the payment protocol and decides: allow, deny, require approval, or flag for review. The actual money movement happens through x402/ACP/AP2/TAP as usual — PaySentry just enforces the rules first.

Core Components

1. Observer — Real-time transaction stream

import { SpendTracker, SpendAnalytics, SpendAlerts } from '@paysentry/observe';

const tracker = new SpendTracker();
const analytics = new SpendAnalytics(tracker);
const alerts = new SpendAlerts(tracker);

// Alert when daily spend exceeds 80% of $500 budget
alerts.addRule({
  id: 'daily-budget',
  type: 'budget_threshold',
  severity: 'warning',
  config: {
    threshold: 500,
    currency: 'USDC',
    windowMs: 86400000, // 24 hours
    alertAtPercent: 0.8,
  },
});

alerts.onAlert((alert) => {
  slack.send(`[${alert.severity}] ${alert.message}`);
});

Every transaction is indexed by agent, service, protocol, and time. You get:

Per-agent spend breakdowns
Time-series analytics (hourly/daily/weekly/monthly)
Anomaly detection (z-score based)
Rate spike detection
New recipient alerts

2. Controller — Per-agent spending limits, velocity checks, approval workflows

import { PolicyEngine, blockAbove, requireApprovalAbove, allowAll } from '@paysentry/control';

const engine = new PolicyEngine();

engine.loadPolicy({
  id: 'production',
  name: 'Production Controls',
  enabled: true,
  rules: [
    blockAbove(1000, 'USDC'),              // Hard block above $1000
    requireApprovalAbove(100, 'USDC'),     // Human approval above $100
    allowAll(),                            // Allow everything else
  ],
  budgets: [
    { window: 'daily', maxAmount: 500, currency: 'USDC' },
    { window: 'monthly', maxAmount: 5000, currency: 'USDC' },
  ],
  cooldownMs: 1000, // 1 second between transactions
});

const result = engine.evaluate(transaction);
// result.allowed: boolean
// result.action: 'allow' | 'deny' | 'require_approval' | 'flag'

Policies are declarative. No LLM can override them. If the policy says deny, it's denied. You can version-control policies in YAML or JSON and apply them via GitOps.

HTTP middleware for Express/Fastify:

import { createPolicyMiddleware } from '@paysentry/control';

app.use('/pay', createPolicyMiddleware({
  engine,
  approvalHandler: async (tx) => {
    const approved = await slack.requestApproval(tx);
    return approved;
  },
}));

3. Protector — Prompt injection detection, transaction signing verification, circuit breakers

import { TransactionProvenance, DisputeManager, RecoveryEngine } from '@paysentry/protect';

const provenance = new TransactionProvenance();
const disputes = new DisputeManager({ provenance });

// Provenance records every step automatically
provenance.recordIntent(tx, { originalPrompt: 'Buy market data' });
provenance.recordPolicyCheck(tx.id, 'pass', { policyId: 'production' });
provenance.recordExecution(tx.id, 'pass', { txHash: '0xabc...' });
provenance.recordSettlement(tx.id, 'fail', { error: 'Service returned 500' });

// File a dispute — provenance is automatically attached as evidence
const dispute = disputes.file({
  transactionId: tx.id,
  agentId: tx.agentId,
  reason: 'Service failed to deliver after payment',
  requestedAmount: tx.amount,
});

// Resolve and recover
disputes.resolve(dispute.id, {
  status: 'resolved_refunded',
  liability: 'service_provider',
  resolvedAmount: tx.amount,
});

Immutable provenance chain: intent → policy → approval → execution → settlement. When things go wrong, you have the evidence to file disputes and automate recovery.

4. Protocol Adapter Pattern — Write once, enforce everywhere

PaySentry doesn't care which protocol you use. The policy engine evaluates an AgentTransaction — a protocol-agnostic representation of a payment. Adapters translate protocol-specific details into AgentTransaction objects.

// Core transaction type (from @paysentry/core/src/types.ts)
export interface AgentTransaction {
  readonly id: TransactionId;
  readonly agentId: AgentId;
  readonly recipient: string;
  readonly amount: number;
  readonly currency: string;
  readonly purpose: string;
  readonly protocol: PaymentProtocol; // 'x402' | 'acp' | 'ap2' | 'stripe'
  status: TransactionStatus;
  readonly service?: ServiceId;
  readonly createdAt: string;
  updatedAt: string;
  protocolTxId?: string;
  readonly metadata: Readonly<Record<string, unknown>>;
}

Same policy file governs x402, ACP, AP2, and Visa TAP payments. You write the rules once. PaySentry enforces them across all protocols.

Quick Start: Adding PaySentry to an x402 Agent

Prerequisites

Node.js 20+
An x402-enabled agent (or use the mock for testing)

Step 1: Install

npm install @paysentry/core @paysentry/observe @paysentry/control

Step 2: Configure Policy

Create paysentry-policy.json:

{
  "id": "default",
  "name": "Default Spend Policy",
  "enabled": true,
  "rules": [
    {
      "id": "block-large",
      "name": "Block transactions above $1000",
      "enabled": true,
      "priority": 10,
      "conditions": { "minAmount": 1000 },
      "action": "deny"
    },
    {
      "id": "approval-medium",
      "name": "Require approval above $100",
      "enabled": true,
      "priority": 20,
      "conditions": { "minAmount": 100 },
      "action": "require_approval"
    },
    {
      "id": "allow-all",
      "name": "Allow everything else",
      "enabled": true,
      "priority": 9999,
      "conditions": {},
      "action": "allow"
    }
  ],
  "budgets": [
    { "window": "daily", "maxAmount": 500, "currency": "USDC" },
    { "window": "monthly", "maxAmount": 5000, "currency": "USDC" }
  ],
  "cooldownMs": 1000
}

Step 3: Wrap Your Agent's Payment Calls

Before PaySentry:

// Agent makes payment directly
const response = await fetch('https://api.provider.com/data', {
  headers: {
    'X-Payment-Amount': '0.05',
    'X-Payment-Currency': 'USDC',
  },
});

After PaySentry:

import { PolicyEngine } from '@paysentry/control';
import { createTransaction } from '@paysentry/core';

const engine = new PolicyEngine();
engine.loadPolicy(policyConfig);

const tx = createTransaction({
  agentId: 'research-agent',
  recipient: 'https://api.provider.com/data',
  amount: 0.05,
  currency: 'USDC',
  purpose: 'Market data API call',
  protocol: 'x402',
});

const evaluation = engine.evaluate(tx);

if (!evaluation.allowed) {
  console.error(`Payment blocked: ${evaluation.reason}`);
  return;
}

if (evaluation.action === 'require_approval') {
  const approved = await requestHumanApproval(tx);
  if (!approved) return;
}

// Now execute the actual payment
const response = await fetch('https://api.provider.com/data', {
  headers: {
    'X-Payment-Amount': '0.05',
    'X-Payment-Currency': 'USDC',
  },
});

// Record the transaction for analytics
engine.recordTransaction(tx);

Step 4: Sandbox Mode — Test Without Real Money

import { MockX402 } from '@paysentry/sandbox';

const x402 = new MockX402({
  latencyMs: 10,
  failureRate: 0.1 // 10% simulated failures
});

const result = await x402.processPayment(tx);
console.log(`Sandbox result: ${result.success}`);

Set PAYSENTRY_MODE=sandbox in your environment to route all payments through mock protocols. Test your entire payment flow without spending a cent.

Multi-Protocol Configuration

An agent that uses x402 for API calls, ACP for agent-to-agent payments, and Visa TAP for SaaS subscriptions — all governed by a single policy.

import { PolicyEngine } from '@paysentry/control';
import { SpendTracker } from '@paysentry/observe';

const tracker = new SpendTracker();
const engine = new PolicyEngine();

// Single policy governs all protocols
engine.loadPolicy({
  id: 'multi-protocol',
  name: 'Multi-Protocol Policy',
  enabled: true,
  rules: [
    // x402: Allow microtransactions, block above $10
    {
      id: 'x402-limit',
      enabled: true,
      priority: 10,
      conditions: { protocols: ['x402'], minAmount: 10 },
      action: 'deny',
    },
    // ACP: Require approval for agent-to-agent above $50
    {
      id: 'acp-approval',
      enabled: true,
      priority: 20,
      conditions: { protocols: ['acp'], minAmount: 50 },
      action: 'require_approval',
    },
    // Visa TAP: Block subscriptions above $200/month
    {
      id: 'tap-subscription-limit',
      enabled: true,
      priority: 30,
      conditions: {
        protocols: ['stripe'],
        minAmount: 200,
        metadata: { type: 'subscription' }
      },
      action: 'deny',
    },
  ],
  budgets: [
    { window: 'daily', maxAmount: 1000, currency: 'USDC' },
  ],
});

// All transactions flow through the same tracker
tracker.record(x402Tx);
tracker.record(acpTx);
tracker.record(tapTx);

// Unified analytics across all protocols
const analytics = new SpendAnalytics(tracker);
const report = analytics.getAgentAnalytics('my-agent');
console.log(report.spendByProtocol);
// Map {
//   'x402:USDC' => { totalAmount: 12.50, transactionCount: 250 },
//   'acp:USDC' => { totalAmount: 75.00, transactionCount: 3 },
//   'stripe:USD' => { totalAmount: 149.00, transactionCount: 1 }
// }

One audit log. One dashboard. One policy file.

What's Next

PaySentry is open-source (MIT license) and under active development. Here's the roadmap:

AP2 adapter (Q1 2026)
Visa TAP integration (Q2 2026)
Hosted dashboard (self-hosted option available now, managed version coming)
Prompt injection detection for payment-triggering context (experimental)

Get Involved

GitHub: github.com/mkmkkkkk/paysentry
Docs: paysentry.dev (coming soon)
Discord: discord.gg/paysentry (coming soon)
Contributing: See CONTRIBUTING.md in the repo

We're looking for contributors who've felt the pain of agent payment governance. If you've built a custom solution, battled x402 timeout bugs, or filed disputes with flaky services — we want to hear from you.

Final Thoughts

The agent payment protocols are maturing. x402 has production volume. ACP has the spec. AP2 has the vision. But the middleware layer — the control plane that sits above all of them and enforces sanity — is still wide open.

PaySentry is our answer. It's not a protocol. It's not a wallet. It's the missing governance layer that makes agent payments safe, observable, and compliant.

If you're building agents that spend money, you need three things:

A payment protocol (x402, ACP, AP2, TAP)
A payment control plane (PaySentry)
A way to test without burning money (PaySentry sandbox)

The protocols give you the "how". PaySentry gives you the "should we?".

Try PaySentry:

npm install @paysentry/core @paysentry/observe @paysentry/control @paysentry/protect @paysentry/sandbox

Run the quickstart:

git clone https://github.com/mkmkkkkk/paysentry.git
cd paysentry
npm install
npm run build
node examples/quickstart.js

See all 4 pillars in action in under 5 minutes.

Forem: mkmkkkkk

AI Agents Lost $600K+ to Prompt Injection — Attack Taxonomy & Code-Level Defenses

The Problem

The Pattern

Why Prompts Can't Fix This

Defense Layers

Self-Attack Results

x402 V2 Security Deep Dive: New Attack Vectors in AI Agent Payments

What x402 V2 Actually Changed

1. Dynamic payTo Routing

2. Wallet-Based Session Identity

3. Modular SDK Architecture

The Attack Vectors V2 Creates

Attack 1: Recipient Address Manipulation (Dynamic Routing)

Attack 2: Session Token Theft (Session Identity)

Attack 3: Malicious Plugin Injection (Modular SDK)

Building a V2 Security Policy

The "79 Tests" Problem

V2 Migration Checklist

The Bottom Line

x402 V2 Just Dropped: 5 Security Changes Every AI Agent Builder Needs to Know

x402 V2 Just Dropped: 5 Security Changes Every AI Agent Builder Needs to Know

What Changed in x402 V2

1. Payment Identifier Standardization (CAIP-Based)

2. Dynamic payTo Routing

3. Wallet-Based Identity and Session Access

4. Modular SDK Architecture

5. HTTP Header Modernization

The Security Implications Nobody's Talking About

Dynamic payTo Routing → Recipient Manipulation Attacks

Wallet-Based Identity → Session Hijacking Risks

Modular SDK → Plugin Trust Boundary Questions

CAIP Identifiers → Chain Confusion Attacks

Header Migration → Detection Blind Spots

Putting It Together: A V2 Security Policy Engine

V2 Migration Security Checklist

The Bottom Line

x402 Payment Timeouts: Why Your Agent Loses Money and How to Fix It

Table of Contents

How x402 Settlement Works

The Timeout Race Condition

Root Cause: Block Time vs. Facilitator Deadline

What Happens to the Money

Related Failure Modes

Gas Estimation Failures (Issue #1065)

Verify-OK, Settle-Fail (Issue #961)

Solution 1: Network-Aware Timeouts

Solution 2: Settlement State Machine

Solution 3: Payment Guardian Layer

Production Checklist

Conclusion

x402 vs ACP vs AP2: Why your AI agent needs a payment control plane

Table of Contents

The Agent Payment Explosion

Protocol Landscape

x402 — HTTP-Native Payments

ACP — Agent Commerce Protocol

AP2 — Agent Payment Protocol v2

Visa TAP — Traditional Rails for Agents

The Middleware Gap

PaySentry Architecture

Design Philosophy: Control Plane, Not Data Plane

Core Components

1. Observer — Real-time transaction stream

2. Controller — Per-agent spending limits, velocity checks, approval workflows

3. Protector — Prompt injection detection, transaction signing verification, circuit breakers

4. Protocol Adapter Pattern — Write once, enforce everywhere

Quick Start: Adding PaySentry to an x402 Agent

Prerequisites

Step 1: Install

Step 2: Configure Policy

Step 3: Wrap Your Agent's Payment Calls

Step 4: Sandbox Mode — Test Without Real Money

Multi-Protocol Configuration

What's Next

Get Involved

Final Thoughts