x402 v2 출시: AI 에이전트 결제가 더 쉬워졌다

12월 11일, x402 v2가 출시됐습니다. HTTP 네이티브 마이크로페이먼트의 큰 업그레이드입니다. 이 글에서는 v2의 핵심 변경사항과 awesome-x402-on-base 레포의 최근 업데이트를 정리합니다.

상세 스펙: x402 v2 프로토콜 명세서 (한글)

v2, 뭐가 달라졌나

HTTP 헤더: X-PAYMENT → PAYMENT-SIGNATURE, PAYMENT-REQUIRED
네트워크 표기: base-sepolia → eip155:84532 (CAIP 표준)
체인 지원: 단일 체인 → 멀티체인 (Base, Solana, Polygon 등)
트랜스포트: HTTP만 → HTTP, MCP, A2A
세션: 없음 → 지갑 기반 세션 지원

멀티체인 지원 (CAIP 표준)

네트워크 표기가 CAIP 표준으로 바뀌었습니다. base-sepolia 대신 eip155:84532처럼 체인 ID를 명시합니다. Base뿐 아니라 Solana, Polygon 등 여러 체인을 하나의 스펙으로 지원합니다.

AI 에이전트를 위한 MCP 트랜스포트

Model Context Protocol (MCP) 트랜스포트가 추가됐습니다. AI 에이전트가 MCP 서버의 유료 도구를 호출할 때, JSON-RPC 메시지의 _meta 필드에 결제 정보를 담아 전송합니다.

Claude, Cursor 같은 MCP 클라이언트가 도구를 쓰면서 자동 결제하는 시나리오가 가능해집니다. 예를 들어, 금융 분석 도구를 호출하면서 호출당 $0.01을 지불하는 식입니다.

A2A (Agent-to-Agent) 트랜스포트

Google A2A 프로토콜 기반으로 에이전트끼리 직접 결제할 수 있습니다. 에이전트는 자신의 AgentCard에 x402 지원 여부를 선언하고, Task 상태 머신을 통해 결제 흐름(payment-required → payment-submitted → payment-completed)을 추적합니다.

그 외 변경사항

플러그인 아키텍처

v1은 단일 SDK 구조였지만, v2는 모듈형 플러그인 아키텍처로 전환됐습니다. 체인별(@x402/evm, @x402/svm), 결제 방식별로 독립적인 플러그인을 조합해서 사용합니다. 새로운 체인이나 결제 방식을 추가할 때 기존 코드를 건드리지 않아도 됩니다.

세션 관리 (Sign-In-With-X)

매 요청마다 결제 서명을 보내는 대신, 지갑으로 한 번 로그인하면 세션 토큰을 발급받아 재사용할 수 있습니다. @x402/paywall 패키지가 이 기능을 제공하며, 반복 API 호출 시 UX가 크게 개선됩니다.

동적 라우팅 (payTo)

v1에서는 결제 수신자가 서버 설정에 고정됐지만, v2에서는 요청별로 payTo 주소를 동적으로 지정할 수 있습니다. 마켓플레이스처럼 여러 판매자에게 직접 결제가 필요한 시나리오에 유용합니다.

Discovery API (Bazaar)

x402를 지원하는 API 엔드포인트를 자동으로 검색하는 기능입니다. 에이전트가 "금융 데이터 API 중 $0.01 이하인 것"처럼 조건을 걸어 리소스를 찾을 수 있습니다. 일종의 유료 API 마켓플레이스 인프라입니다.

보안 강화

스마트 컨트랙트 지갑(ERC1271)과 아직 배포되지 않은 카운터팩추얼 지갑(ERC6492) 서명 검증을 지원합니다. Account Abstraction 지갑 사용자도 x402 결제가 가능해졌습니다.

awesome-x402-on-base 업데이트

레포지토리도 v2에 맞춰 구조를 재편했습니다.

디렉토리 구조 변경

awesome-x402-on-base/
├── external/x402/           # 공식 x402 (서브모듈)
├── docs/korean/
│   ├── v1/examples/         # v1 Python 예제 가이드 (4개)
│   ├── v2/                  # v2 문서 (준비 중)
│   └── x402-v2-specification.ko.md  # ⭐ v2 스펙 한글 번역
├── examples/
│   ├── v1/                  # v1 예제 (ap2-demo-coffee-shop)
│   └── v2/                  # v2 예제 (준비 중)
└── resources/               # 한국 커뮤니티 링크

주요 추가 사항 (12/16)

x402 v2 프로토콜 스펙 한글 문서 - HTTP/MCP/A2A 트랜스포트, 결제 방식, Facilitator API 등 전체 번역

경로 변경 안내

v2 출시로 공식 예제 경로가 바뀌었습니다:

# 이전 (v1)
external/x402/examples/python/clients/requests

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

한글 문서도 이동했습니다:

# 이전
docs/korean/examples/*.ko.md

# 현재
docs/korean/v1/examples/*.ko.md

바로 시작하기

1) 클론 & 서브모듈 동기화

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

2) v2 스펙 읽기

# 한글 v2 스펙
docs/korean/x402-v2-specification.ko.md

# 공식 스펙 (영문)
external/x402/specs/

3) v1 예제 돌려보기 (Python)

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

한글 해설: docs/korean/v1/examples/python-requests-client.ko.md

마치며

x402 v2는 AI 에이전트 결제에 최적화된 업그레이드입니다. MCP/A2A 트랜스포트로 에이전트가 도구를 쓰면서 자동 결제하는 흐름이 훨씬 자연스러워졌습니다.

Base + x402 v2 조합으로 마이크로페이먼트를 직접 경험해보세요.

Base Korea 대한베이스