Skip to main content

x402 v2

x402 is the HTTP 402 ("Payment Required") protocol, a lightweight alternative to the full ACTP escrow flow for high-frequency, low-value, latency-sensitive calls. The X402Adapter in the SDK routes any https://… payment destination through this path.

The defining feature: payment travels inline with the HTTP request via an X-Payment header. The seller verifies, executes, settles, and returns the response: one round-trip from the caller's perspective, with no on-chain escrow lifecycle.

When to use x402 vs ACTP escrow​

WorkloadRight tool
LLM inference, $0.001–$0.01/callx402
Search API queries, sub-centx402
Single-shot translations under $0.05x402
Bulk jobs $1+, output quality mattersACTP escrow
Multi-step deliverableACTP escrow
Anything where the consumer might disputeACTP escrow

x402 has no dispute window. Once the seller settles, the payment is final. Use it only where each call is cheap enough to write off if one goes wrong, and where you trust the seller's response enough not to need an escrow lock.

Mainnet vs sepolia​

  • Mainnet: Adapter routes payment directly buyer → seller via @x402/fetch + the Coinbase x402 facilitator. Zero AGIRAILS fee on this path; the protocol takes no cut of x402 traffic. The x402_relay contract address in deployments/base-mainnet.json is null by design.
  • Sepolia: The legacy X402Relay contract is still deployed for fee-splitting integration tests (status: deprecated in deployments/base-sepolia.json). Opt in by setting relay_address in X402AdapterConfig; the relay takes a small bps cut and forwards the rest. Mainnet does not have a deployed relay.

SDK surface​

The high-level pay() API dispatches automatically to the right adapter:

import { ACTPClient } from '@agirails/sdk';
const client = await ACTPClient.create({ network: 'mainnet', wallet: 'auto' });

// HTTPS target → routes through X402Adapter (priority 70)
await client.basic.pay({
  to: 'https://api.example.com/predict',
  amount: '0.01',
});

// 0x address target → routes through StandardAdapter or BasicAdapter
await client.basic.pay({
  to: '0xPROVIDER…',
  amount: '5.00',
  service: 'translate',
});

For a lower-level handle, instantiate X402Adapter directly (V1 does not export a separate x402Client factory; the adapter is the entry point):

import { X402Adapter, type X402AdapterConfig } from '@agirails/sdk';

const adapter = new X402Adapter(
  // X402AdapterConfig per SDK reference: signer, network, optional relay
  { /* ...config... */ } as X402AdapterConfig,
);

// The adapter handles the 402 dance: initial request, read X-Payment-Request
// header, sign EIP-712 authorization, retry with X-Payment header.
const result = await adapter.pay({
  to: 'https://api.example.com/predict',
  amount: '0.01',
  // body/method/headers per UnifiedPayParams; see /reference/sdk-js
});

X402Adapter is the V1 entry point. Most application code uses ACTPClient.pay() (above) instead; the router picks the adapter automatically based on the to target.

EIP-3009 vs Permit2​

x402 v2 supports both signing modes:

  • EIP-3009 (authorizeTransfer): the original USDC.authorizeTransfer flow; broadest server compatibility.
  • Permit2: Uniswap's universal allowance signature; smaller payload but requires the seller to integrate Permit2-aware verification.

The SDK negotiates: it reads the seller's X-Payment-Request header for supported modes and picks the most efficient one both sides understand. You don't configure this; just check the response header X-Payment-Settlement-Method if you care which mode was used.

CAIP-2 network identifiers​

x402 payments are network-namespaced via CAIP-2:

  • Base mainnet: eip155:8453
  • Base sepolia: eip155:84532

The seller's X-Payment-Request includes the network it accepts; if the buyer's wallet is on a different network, you get X402NetworkNotAllowedError. Both sides must agree.

Settlement proof​

A successful x402 response includes:

X-Payment-Settlement: 0xSETTLEMENT_TX_HASH…
X-Payment-Settlement-Amount: 0.01
X-Payment-Settlement-Method: EIP-3009

Always verify the settlement tx exists on-chain before treating the call as paid. The SDK does this verification by default; raw fetch users should explicitly check. A 200 response without a valid settlement header is a fraud signal; drop the provider from your registry.

Integration with wallet=auto​

When the consumer's wallet is in wallet=auto mode, the x402 payment is gasless end to end: the buyer signs the transfer authorization off-chain and pays only USDC, and the facilitator broadcasts the settlement transaction and covers its gas. Neither the buyer nor the seller touches ETH. This means x402 + auto-wallet is the cheapest possible per-call billing path on Base.

What x402 doesn't give you​

  • No reputation accumulation. x402 payments don't write EAS attestations the way ACTP transactions do. Provider reputation only builds via ACTP escrow flows.
  • No quote negotiation. Price is fixed in the seller's X-Payment-Request. Take it or skip.
  • No dispute. Once settled, the money is the seller's.
  • No partial refunds. All-or-nothing; the seller either accepts and serves, or returns 402 again.

For all of the above, you want ACTP escrow.

See also​