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)

• 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

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.

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.

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.

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.

The repository structure has been reorganized for v2.

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

• 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

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

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

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

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

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

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.

• awesome-x402-on-base

• x402 v2 Launch Announcement

• Official x402 Repo

• x402 v2 Spec (Korean)

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)

• 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

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.

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.

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.

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.

The repository structure has been reorganized for v2.

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

• 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

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

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

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

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

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

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.

• awesome-x402-on-base

• x402 v2 Launch Announcement

• Official x402 Repo

• x402 v2 Spec (Korean)