Cover photo

x402 v2 Launch: Easier Payments for AI Agents

The Next Step in HTTP 402 Micropayments - Multichain, MCP, A2A Transports

On December 11th, x402 v2 was released. This is a major upgrade to HTTP-native micropayments. This post covers the key changes in v2 and recent updates to the awesome-x402-on-base repository.

Full Spec: x402 v2 Protocol Specification (Korean) | Official Spec (English)

What's New in v2

  • HTTP Headers: X-PAYMENT → PAYMENT-SIGNATURE, PAYMENT-REQUIRED

  • Network Notation: base-sepolia → eip155:84532 (CAIP standard)

  • Chain Support: Single chain → Multichain (Base, Solana, Polygon, etc.)

  • Transports: HTTP only → HTTP, MCP, A2A

  • Sessions: None → Wallet-based session support

Multichain Support (CAIP Standard)

Network notation now follows the CAIP standard. Instead of base-sepolia, you use chain IDs like eip155:84532. This allows a single spec to support multiple chains including Base, Solana, and Polygon.

MCP Transport for AI Agents

Model Context Protocol (MCP) transport has been added. When AI agents call paid tools on MCP servers, they send payment information in the _meta field of JSON-RPC messages.

This enables scenarios where MCP clients like Claude or Cursor automatically pay while using tools. For example, paying $0.01 per call when invoking a financial analysis tool.

A2A (Agent-to-Agent) Transport

Based on Google's A2A Protocol, agents can pay each other directly. Agents declare x402 support in their AgentCard and track payment flows (payment-required → payment-submitted → payment-completed) through the Task state machine.

Other Changes

Plugin Architecture

v1 had a monolithic SDK structure, but v2 has transitioned to a modular plugin architecture. You combine independent plugins by chain (@x402/evm, @x402/svm) and payment scheme. Adding new chains or payment methods doesn't require touching existing code.

Session Management (Sign-In-With-X)

Instead of sending a payment signature with every request, you can log in once with your wallet and reuse a session token. The @x402/paywall package provides this feature, significantly improving UX for repeated API calls.

Dynamic Routing (payTo)

In v1, the payment recipient was fixed in server settings, but in v2, you can dynamically specify the payTo address per request. This is useful for marketplace scenarios where direct payments to multiple sellers are needed.

Discovery API (Bazaar)

A feature for automatically discovering API endpoints that support x402. Agents can search for resources with conditions like "financial data APIs under $0.01". It's essentially a paid API marketplace infrastructure.

Enhanced Security

Support for smart contract wallet (ERC1271) and counterfactual wallet (ERC6492) signature verification. Account Abstraction wallet users can now use x402 payments.

awesome-x402-on-base Updates

The repository structure has been reorganized for v2.

Directory Structure Changes

awesome-x402-on-base/
├── external/x402/           # Official x402 (submodule)
├── docs/korean/
│   ├── v1/examples/         # v1 Python example guides (4)
│   ├── v2/                   # v2 docs (in progress)
│   └── x402-v2-specification.ko.md  # v2 spec Korean translation
├── examples/
│   ├── v1/                   # v1 examples (ap2-demo-coffee-shop)
│   └── v2/                   # v2 examples (coming soon)
└── resources/               # Korean community links

Key Additions (12/16)

  • x402 v2 Protocol Spec Korean Doc - Full translation of HTTP/MCP/A2A transports, payment schemes, Facilitator API

  • Bilingual Support - Korean/English versions for all READMEs

  • CONTRIBUTING.md - Contribution guide

  • GitHub Issue Templates - For feature/example suggestions

Path Changes

Official example paths have changed with v2 release:

# Before (v1)
external/x402/examples/python/clients/requests

# After (v1 legacy)
external/x402/examples/python/legacy/clients/requests

Korean docs have also moved:

# Before
docs/korean/examples/*.ko.md

# After
docs/korean/v1/examples/*.ko.md

Getting Started

1) Clone & Sync Submodule

git clone --recursive https://github.com/Daehan-Base/awesome-x402-on-base.git
git submodule update --init --recursive

2) Read v2 Spec

# Korean v2 spec
docs/korean/x402-v2-specification.ko.md

# Official spec (English)
external/x402/specs/

3) Try v1 Examples (Python)

cd external/x402/examples/python/legacy/clients/requests
cp .env-local .env
# Add PRIVATE_KEY to .env
uv sync && uv run python main.py

Korean guide: docs/korean/v1/examples/python-requests-client.ko.md

Conclusion

x402 v2 is an upgrade optimized for AI agent payments. With MCP/A2A transports, the flow of agents paying while using tools has become much more natural.

Experience micropayments firsthand with the Base + x402 v2 combination.

Reference