payment scheme.

import { Request, Response, NextFunction } from 'express';
import { verifyAgentPayment } from './payment-verification';

const PAYMENT_NETWORK = 'eip155:8453'; // Base Mainnet
const USDC_CONTRACT = '0x833589cdCD68E48F4B41D8594e886c462287F456';
const SERVICE_PRICE = '5000'; // 0.005 USDC in base units

export function paymentDirectiveMiddleware(req: Request, res: Response, next: NextFunction) {
  const paymentHeader = req.headers['x-agent-payment'];
  
  if (!paymentHeader) {
    res.status(402).json({
      accepts: [{
        scheme: 'exact',
        network: PAYMENT_NETWORK,
        asset: USDC_CONTRACT,
        amount: SERVICE_PRICE
      }]
    });
    return;
  }

  next();
}

Step 2: Client-Side Payment Construction & Retry

The agent client parses the 402 response, constructs an EIP-3009 transferWithAuthorization payload, signs it using the wallet's private key, and attaches the base64-encoded signature to the retry request. EIP-3009 enables gasless meta-transactions, meaning the agent only needs USDC; a facilitator relayer covers the Base gas fees.

import { Wallet, ethers } from 'ethers';
import { fetch as baseFetch } from 'undici';

export class AgentPaymentClient {
  private wallet: Wallet;
  private facilitatorUrl: string;

  constructor(privateKey: string, facilitatorEndpoint: string) {
    this.wallet = new Wallet(privateKey);
    this.facilitatorUrl = facilitatorEndpoint;
  }

  async requestWithPayment(url: string, payload: Record<string, unknown>) {
    let response = await baseFetch(url, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify(payload)
    });

    if (response.status === 402) {
      const directive = await response.json();
      const paymentParams = directive.accepts[0];
      
      const signature = await this.signEIP3009(
        paymentParams.asset,
        paymentParams.amount,
        paymentParams.network
      );

      response = await baseFetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'X-Agent-Payment': btoa(JSON.stringify(signature))
        },
        body: JSON.stringify(payload)
      });
    }

    return response;
  }

  private async signEIP3009(tokenAddress: string, amount: string, chainId: string): Promise<Record<string, string>> {
    const deadline = Math.floor(Date.now() / 1000) + 3600; // 1 hour expiry
    const nonce = ethers.hexlify(ethers.randomBytes(32));
    
    const domain = {
      name: 'USD Coin',
      version: '2',
      chainId: parseInt(chainId.split(':')[1]),
      verifyingContract: tokenAddress
    };

    const types = {
      TransferWithAuthorization: [
        { name: 'from', type: 'address' },
        { name: 'to', type: 'address' },
        { name: 'value', type: 'uint256' },
        { name: 'validAfter', type: 'uint256' },
        { name: 'validBefore', type: 'uint256' },
        { name: 'nonce', type: 'bytes32' }
      ]
    };

    const value = {
      from: this.wallet.address,
      to: process.env.SERVICE_WALLET!,
      value: amount,
      validAfter: 0,
      validBefore: deadline,
      nonce: nonce
    };

    const sig = await this.wallet._signTypedData(domain, types, value);
    return { ...value, signature: sig, deadline };
  }
}

Step 3: Server-Side Verification & Execution

Upon receiving the retry request, the server decodes the payment header, validates the signature against the USDC contract state, checks the deadline and nonce, and confirms the facilitator has submitted the meta-transaction. Only after cryptographic verification does the service execute the business logic.

export async function handlePaidRequest(req: Request, res: Response) {
  const rawPayment = req.headers['x-agent-payment'];
  if (!rawPayment) return res.status(401).json({ error: 'Missing payment' });

  const paymentData = JSON.parse(Buffer.from(rawPayment as string, 'base64').toString());
  const isValid = await verifyAgentPayment(paymentData);

  if (!isValid) {
    return res.status(402).json({ error: 'Invalid or expired payment' });
  }

  // Execute business logic
  const result = await processAgentQuery(req.body);
  res.status(200).json(result);
}

Architecture Rationale

• EIP-3009 over Standard Transfers: Standard ERC-20 transfers require the sender to hold ETH for gas. EIP-3009 enables meta-transactions where a facilitator relayer submits the transaction and gets reimbursed in USDC. This aligns with agent constraints: wallets only need stablecoins, not native chain tokens.
• Base Network Selection: Base provides EVM compatibility with sub-cent transaction fees and high throughput. This makes micro-transactions economically viable. Higher-fee chains would render $0.001–$0.015 calls unprofitable due to gas overhead.
• Signature as Authentication: Traditional auth separates identity verification from billing. x402 merges them. A valid EIP-3009 signature proves wallet ownership and authorizes fund movement simultaneously. This eliminates stateful sessions, reduces server-side storage, and prevents key leakage.
• Facilitator Pattern: The facilitator acts as a gas sponsor and settlement layer. It monitors pending authorizations, batches submissions, and handles on-chain verification. This abstraction keeps agent clients lightweight and ensures payment finality without blocking the request loop.

Pitfall Guide

1. Hardcoding Payment Directives

Explanation: Returning static prices in the 402 response ignores market volatility, compute load, and service degradation. Agents will overpay during low demand or fail during high demand. Fix: Implement a dynamic pricing engine that adjusts amounts based on real-time compute cost, queue depth, and network congestion. Cache directives with short TTLs to balance performance and accuracy.

2. Ignoring Signature Expiration & Nonce Collisions

Explanation: EIP-3009 authorizations include validBefore (deadline) and nonce fields. Failing to validate these allows replay attacks or expired payments. Fix: Strictly enforce deadline checks against server time. Maintain an in-memory or Redis-backed nonce registry to reject duplicate authorizations. Rotate nonces per request to prevent replay.

3. Assuming Multi-Chain Support Out of the Box

Explanation: x402 is currently optimized for Base and USDC. Building cross-chain routing or multi-asset acceptance prematurely adds unnecessary complexity and verification overhead. Fix: Start with a single-chain, single-asset implementation. Abstract the payment verification layer so additional networks can be plugged in later without refactoring the core request flow.

4. Skipping Facilitator Gas Sponsorship

Explanation: Agents cannot reliably hold ETH for gas. If the client attempts direct transfers, requests will fail due to insufficient native balance. Fix: Integrate a dedicated facilitator relayer (e.g., OpenZeppelin Relayer or custom meta-transaction handler). Ensure the facilitator is funded with ETH and configured to accept USDC reimbursements via EIP-3009.

5. Treating HTTP 402 as an Error State

Explanation: Developers often wrap 402 responses in error handlers, causing client libraries to throw exceptions instead of initiating the payment flow. Fix: Treat 402 as a control-flow signal. Client wrappers should intercept the status, parse the directive, execute payment, and retry transparently. Log the event for observability, but do not bubble it as a failure.

6. Inadequate On-Chain Verification

Explanation: Trusting the X-Agent-Payment header without verifying against the USDC contract state allows forged signatures or double-spending. Fix: Always verify the signature against the token contract using isValidSignature or by simulating the meta-transaction. Cross-reference the nonce and deadline with on-chain state before executing business logic.

7. Applying Traditional Rate Limiting

Explanation: Fixed request-per-minute limits conflict with pay-per-call economics. Agents that pay should not be artificially throttled, and free-tier limits become irrelevant. Fix: Replace static rate limits with payment-volume throttling. Allow requests proportional to confirmed USDC transfers. Implement burst allowances backed by real-time payment verification rather than token buckets.

Production Bundle

Action Checklist

• Deploy facilitator relayer: Configure a meta-transaction handler on Base with sufficient ETH for gas sponsorship and USDC reimbursement routing.
• Implement 402 middleware: Add payment directive interception to all public endpoints, returning structured pricing with network, asset, and amount fields.
• Build signature verifier: Create a verification service that validates EIP-3009 payloads against the USDC contract, checking deadlines, nonces, and signature integrity.
• Configure client retry logic: Integrate a payment-aware fetch wrapper that intercepts 402 responses, signs authorizations, and retries with the payment header.
• Add observability hooks: Log payment events, verification outcomes, and facilitator submission status to track settlement latency and failure rates.
• Implement idempotency: Attach request IDs to payment payloads to prevent duplicate processing if network retries occur after successful verification.
• Set up fallback caching: Return cached responses for non-critical endpoints when payment verification fails or facilitator latency exceeds thresholds.

Decision Matrix

Scenario	Recommended Approach	Why	Cost Impact
High-frequency data scraping	x402 Pay-Per-Call	Eliminates key management overhead; scales linearly with agent activity	Low fixed cost, variable per-call expense
On-demand LLM inference	x402 + Dynamic Pricing	Matches compute cost to token output; prevents quota exhaustion	Predictable marginal cost, no tier penalties
Human-administered SaaS	Traditional API Keys	Users expect dashboards, billing history, and manual key rotation	Higher administrative overhead, predictable revenue
Multi-agent orchestration	x402 + Facilitator Pool	Centralized gas sponsorship reduces wallet complexity across agents	Optimized gas spend, streamlined settlement
Regulatory-compliant enterprise	Hybrid (Key + x402)	Maintains audit trails while enabling machine-to-machine billing	Moderate integration cost, full compliance coverage

Configuration Template

// server/config/payment-gateway.ts
export const PAYMENT_CONFIG = {
  network: 'eip155:8453',
  asset: '0x833589cdCD68E48F4B41D8594e886c462287F456',
  scheme: 'exact',
  basePrice: '5000', // 0.005 USDC
  maxPriceMultiplier: 1.5,
  deadlineWindow: 3600, // seconds
  facilitator: {
    endpoint: process.env.FACILITATOR_RPC!,
    gasLimit: 150000,
    maxFeePerGas: '2000000000' // 2 gwei
  },
  verification: {
    contract: '0x833589cdCD68E48F4B41D8594e886c462287F456',
    method: 'transferWithAuthorization',
    nonceStorage: 'redis://localhost:6379'
  }
};

// client/config/agent-wallet.ts
export const AGENT_CONFIG = {
  privateKey: process.env.AGENT_PRIVATE_KEY!,
  paymentHeader: 'X-Agent-Payment',
  retryAttempts: 3,
  retryDelay: 500, // ms
  timeout: 10000, // ms
  fallbackCache: true,
  observability: {
    logPaymentEvents: true,
    trackVerificationLatency: true
  }
};

Quick Start Guide

1. Initialize the facilitator: Deploy a meta-transaction relayer on Base. Fund it with ETH for gas and configure it to accept USDC reimbursements via EIP-3009. Set environment variables for the relayer endpoint and gas parameters.
2. Add payment middleware: Attach the 402 directive interceptor to your API routes. Configure the pricing engine to return network, asset, and amount fields. Ensure the middleware skips verification for internal or health-check endpoints.
3. Integrate the client wrapper: Replace standard fetch calls with the payment-aware client. Configure it to intercept 402 responses, sign EIP-3009 authorizations, and retry with the payment header. Test against a mock 402 endpoint to verify the sign-and-retry loop.
4. Deploy verification service: Implement on-chain signature validation against the USDC contract. Add nonce tracking, deadline enforcement, and facilitator submission logging. Run integration tests with testnet USDC to confirm end-to-end settlement.
5. Monitor and tune: Enable observability hooks to track payment latency, verification success rates, and facilitator gas spend. Adjust dynamic pricing multipliers based on compute load and network conditions. Iterate on retry logic to minimize agent request failures.