Skip to main content

SDK Architecture & Primitives

x402 payment flow​

The x402 payment flow follows a request → challenge → authorize → retry loop:

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

This loop is handled automatically by the SDK.

Roles​

Seller (paid agent server)​

The seller:

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

Buyer (calling agent / client)​

The buyer:

  • Calls paid services
  • Uses the SDK to handle payment detection and retries

Key components​

1. X402Treasurer​

Controls whether payments are approved or rejected. The treasurer is responsible for payment authorization decisions and can enforce spending policies, budgets, and user confirmations.

Recommended treasurer for production use. Required when using agents created on the ampersend Platform.

  • Connects your agent to the ampersend API
  • Enforces spending limits and budgets configured in the ampersend Platform
  • Reports spending and payment activity for monitoring and analytics
  • Provides centralized control and compliance features
  • Supports both EOA and Smart Account wallets

NaiveTreasurer (testing only)​

Automatically approves all payments without any limits or monitoring.

  • Only for testing or when creating standalone agents not connected to the ampersend Platform
  • No spending limits or budget enforcement
  • No payment reporting or monitoring
  • Useful for demos and local development

2. X402Wallet​

Generates cryptographically signed payment payloads.

Wallet types:

  • AccountWallet — EOA / private key
  • SmartAccountWallet — ERC-4337 + ERC-1271 signatures. Currently supports accounts with ERC-7579 and Rhinestone's OwnableValidator.

Note: When using the ampersend Platform, agents always use a SmartAccountWallet. This provides enhanced security, programmability, and integration with the Platform’s management features.

3. Client components​

Python (A2A)​

  • X402Client — A2A client with payment middleware
  • X402RemoteA2aAgent — Wrapper to call paid remote agents
  • X402RemoteA2aAgentToolset — Toolset that enables agents to use paid remote agents as tools

TypeScript (MCP)​

  • X402McpClient — MCP client that auto-handles x402 retries and 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 and verify payment