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

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

• HTTP 헤더: X-PAYMENT → PAYMENT-SIGNATURE, PAYMENT-REQUIRED

• 네트워크 표기: base-sepolia → eip155:84532 (CAIP 표준)

• 체인 지원: 단일 체인 → 멀티체인 (Base, Solana, Polygon 등)

• 트랜스포트: HTTP만 → HTTP, MCP, A2A

• 세션: 없음 → 지갑 기반 세션 지원

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

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

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

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 결제가 가능해졌습니다.

레포지토리도 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/               # 한국 커뮤니티 링크

• 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

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

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

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

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 조합으로 마이크로페이먼트를 직접 경험해보세요.

• awesome-x402-on-base

• x402 v2 출시 발표

• 공식 x402 레포

• x402 v2 스펙 (한글)

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

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

• HTTP 헤더: X-PAYMENT → PAYMENT-SIGNATURE, PAYMENT-REQUIRED

• 네트워크 표기: base-sepolia → eip155:84532 (CAIP 표준)

• 체인 지원: 단일 체인 → 멀티체인 (Base, Solana, Polygon 등)

• 트랜스포트: HTTP만 → HTTP, MCP, A2A

• 세션: 없음 → 지갑 기반 세션 지원

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

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

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

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 결제가 가능해졌습니다.

레포지토리도 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/               # 한국 커뮤니티 링크

• 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

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

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

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

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 조합으로 마이크로페이먼트를 직접 경험해보세요.

• awesome-x402-on-base

• x402 v2 출시 발표

• 공식 x402 레포

• x402 v2 스펙 (한글)