Skip to main content

Core Concepts

x402 Payment Flow​

  1. Client calls a paid agent
  2. Server responds with 402 Payment Required
  3. Client's SDK asks the Treasurer whether to authorize
  4. If approved → Wallet produces signed payment
  5. SDK retries the request with payment metadata
  6. Server verifies → executes request → returns response

This loop is handled automatically by the SDK.

Roles​

Seller (Paid Agent Server)

  • Sets the price
  • Requires payment
  • Verifies payment on each request

Buyer (Calling Agent / Client)

  • Calls paid services
  • SDK handles payment detection & retries

Key Components​

1. X402Treasurer​

Controls whether payments are approved or rejected.

Useful for:

  • budgets
  • user confirmations
  • spending policies

Default: NaiveTreasurer (auto-approve everything).

2. X402Wallet​

Generates cryptographically signed payment payloads.

Wallet types:

  • AccountWallet — EOA/private key
  • SmartAccountWallet — ERC-4337 + ERC-1271 signatures

3. Client Components​

Python (A2A)

  • X402Client — A2A client with payment middleware
  • X402RemoteA2aAgent — Simple wrapper to call paid remote agents

TypeScript (MCP)

  • X402McpClient — MCP client that auto-handles x402 retries & signatures

4. Server Components​

Python (A2A)

  • to_a2a() — turns an ADK agent into a paid A2A service
  • make_x402_before_agent_callback() — adds payment requirements

TypeScript (MCP)

  • withX402Payment() — FastMCP middleware to require & verify payment