<100 subscribers
Disclaimer
본 리뷰는 Web2/AI 엔지니어로서 개인적으로 분석한 내용을 정리한 것입니다. 해당 문서의 모든 의견과 해석은 작성자 개인의 것이며, Coinbase 혹은 Base의 공식적 관점을 대변하지 않습니다.
또한 기술은 지속적으로 업데이트될 수 있으므로, 최신 정보는 공식 문서를 반드시 참고하시기 바랍니다.
최근 Coinbase가 공개한 x402는 HTTP 402 Payment Required를 현실 세계에 적용 가능한 형태로 되살린, 매우 실험적이면서도 실용적인 프로토콜입니다.
웹2 환경에서 API·SaaS 과금은 보통 Billing 시스템 + API Gateway + Webhook + 콘솔을 모두 개발자가 직접 구축해야 하지만, x402는 HTTP 결제 표준화 + 결제 인증 + 정산(Settlement)을 하나의 흐름으로 통합해 API 단에서 즉시 유료화를 가능하게 합니다.
저는 Base Korea Developer Ambassador로 활동하며, 온체인 개발과 에이전트 결제 생태계를 꾸준히 지켜보고 있는 입장에서 이번 기술을 리뷰해보려 합니다. 단순한 기능 소개가 아니라, 1) 빌더의 관점에서 실제 서비스에 적용할 수 있는지, 2) x402에서 제공하는 (특히 Python SDK) 개발 경험이 어떤지를 중심으로 살펴보는 것이 목적입니다.
이번 글은 x402 공식 저장소(https://github.com/coinbase/x402)의 Python SDK v0.2.1 기준으로 작성되었으며, FastAPI/Flask 기반 서버 미들웨어, 클라이언트 요청 흐름, 그리고 결제 · 정산 처리 플로우를 중심으로 정리합니다.
Coinbase에서 구현되어있는 x402는 서버단에서 사용할 수 있는 FastAPI 미들웨어, Flask는 서버 예제 및 클라이언트에서 사용할 수 있는 x402HttpxClient (httpx) 및 x402_requests (requests) 클래스를 제공합니다.
유저쪽 로직의 경우 사용하는 유저 입장에서 언제 x402 프로세스가 처리되었는지 굳이 알 필요가 없으므로 로직을 숨겨두었습니다.
Middleware의 경우, 서버단에서 필요한 API 엔드포인트( ex, 구매 요청)에 쉽게 등록할 수 있도록 되어있습니다.
예제에서는 고정된 값을 반환하지만, 커머스의 경우 구매 요청 시 전달받은 장바구니 정보 혹은 유저 정보를 기반으로 고객에게 금액을 청구할 수 있습니다.
x402의 프로세스 흐름 (유료 API 기능을 호출하는 경우)
1. 유저가 서버에 요청을 합니다.
2. 서버는 유저가 X-PAYMENT 헤더의 내용을 전달했는지 확인합니다.
2.1. 전달하지 않은 경우
2.1.1. x402PaymentRequired 응답을 전송합니다.
여기에는 x402의 버전, 청구 금액, 청구할 주소(Base) 등이 포함됩니다.
2.1.2. 유저는 402 HTTP Status code와 함께, x402PaymentRequired 응답을 받게됩니다.
2.1.3. x402PaymentRequired 내용을 확인하고, EIP-3009: Transfer with Authorization 스킴에 맞게, 내용을 작성하고 서명을 진행합니다.
EIP-3009는 송금을 다른 주체에게 처리할 수 있도록 하기 위한 이더리움의 스탠다드 입니다.
from, to, value, validAfter, validBefore, nonce 포함. EIP‑712 도메인(name, version, chainId, verifyingContract)으로 서명 범위 고정
이 정보를 기반으로 서명 후, 값이 잘못 작성되지 않았음을 보장합니다.
2.1.4. 서버로 전달할 데이터와, 서명을 Base64로 인코딩하여 X-PAYMENT 헤더에 담아 다시 서버에 동일한 요청을 보냅니다.
2.2.1 에서 이어서 진행
2.2. 전달한 경우
2.2.1. X-PAYMENT 헤더의 정보에서 현재 API에서 지원하는 결제 정보들 중 일치 하는 것을 찾습니다.
정리하자면, x402는 퍼실리테이터(Facilitator)를 통해 결제 검증과 정산을 위임하고, 서버와 클라이언트는 HTTP 헤더(X-PAYMENT / X-PAYMENT-RESPONSE) 만 주고받으며 결제 흐름을 완성할 수 있는 구조를 제공합니다. 서버 개발자가 블록체인 로직을 직접 다루지 않아도 되고, 기존 API 흐름을 유지한 채 결제 기능만 자연스럽게 추가할 수 있다는 점이 큰 장점입니다.
Base 빌더 생태계의 관점에서 보면, x402는 Agent-to-Agent 결제 인프라의 초기 조각을 제공하고 있으며, 아직 초기 버전임에도 방향성은 매우 분명합니다. 앞으로 Base 및 온체인 빌더들이 적극적으로 활용할 기반 기술로 성장할 여지가 충분합니다.
무엇보다 Coinbase는 Base 체인을 중심으로 ‘AI 커머스 시대’의 문을 열고 있습니다. Web2 개발자조차 블록체인을 깊이 이해하지 않아도, 단순한 HTTP 호출 수준에서 온체인 결제를 붙일 수 있는 환경이 열리고 있습니다. 저는 이 변화의 최전선에서 Base Korea Developer Ambassador로 활동하며 생태계를 함께 만들어가고 있다는 사실을 큰 영광으로 생각합니다.
온체인 결제 표준화는 이제 시작에 불과합니다. 그 여정 속에서 x402는 분명 중요한 출발선에 서 있으며, 이 기술이 만들어갈 다음 단계를 기대해봅니다.
Github - coinbase/x402
A payments protocol for the internet. Built on HTTP. - coinbase/x402
Disclaimer
본 리뷰는 Web2/AI 엔지니어로서 개인적으로 분석한 내용을 정리한 것입니다. 해당 문서의 모든 의견과 해석은 작성자 개인의 것이며, Coinbase 혹은 Base의 공식적 관점을 대변하지 않습니다.
또한 기술은 지속적으로 업데이트될 수 있으므로, 최신 정보는 공식 문서를 반드시 참고하시기 바랍니다.
최근 Coinbase가 공개한 x402는 HTTP 402 Payment Required를 현실 세계에 적용 가능한 형태로 되살린, 매우 실험적이면서도 실용적인 프로토콜입니다.
웹2 환경에서 API·SaaS 과금은 보통 Billing 시스템 + API Gateway + Webhook + 콘솔을 모두 개발자가 직접 구축해야 하지만, x402는 HTTP 결제 표준화 + 결제 인증 + 정산(Settlement)을 하나의 흐름으로 통합해 API 단에서 즉시 유료화를 가능하게 합니다.
저는 Base Korea Developer Ambassador로 활동하며, 온체인 개발과 에이전트 결제 생태계를 꾸준히 지켜보고 있는 입장에서 이번 기술을 리뷰해보려 합니다. 단순한 기능 소개가 아니라, 1) 빌더의 관점에서 실제 서비스에 적용할 수 있는지, 2) x402에서 제공하는 (특히 Python SDK) 개발 경험이 어떤지를 중심으로 살펴보는 것이 목적입니다.
이번 글은 x402 공식 저장소(https://github.com/coinbase/x402)의 Python SDK v0.2.1 기준으로 작성되었으며, FastAPI/Flask 기반 서버 미들웨어, 클라이언트 요청 흐름, 그리고 결제 · 정산 처리 플로우를 중심으로 정리합니다.
Coinbase에서 구현되어있는 x402는 서버단에서 사용할 수 있는 FastAPI 미들웨어, Flask는 서버 예제 및 클라이언트에서 사용할 수 있는 x402HttpxClient (httpx) 및 x402_requests (requests) 클래스를 제공합니다.
유저쪽 로직의 경우 사용하는 유저 입장에서 언제 x402 프로세스가 처리되었는지 굳이 알 필요가 없으므로 로직을 숨겨두었습니다.
Middleware의 경우, 서버단에서 필요한 API 엔드포인트( ex, 구매 요청)에 쉽게 등록할 수 있도록 되어있습니다.
예제에서는 고정된 값을 반환하지만, 커머스의 경우 구매 요청 시 전달받은 장바구니 정보 혹은 유저 정보를 기반으로 고객에게 금액을 청구할 수 있습니다.
x402의 프로세스 흐름 (유료 API 기능을 호출하는 경우)
1. 유저가 서버에 요청을 합니다.
2. 서버는 유저가 X-PAYMENT 헤더의 내용을 전달했는지 확인합니다.
2.1. 전달하지 않은 경우
2.1.1. x402PaymentRequired 응답을 전송합니다.
여기에는 x402의 버전, 청구 금액, 청구할 주소(Base) 등이 포함됩니다.
2.1.2. 유저는 402 HTTP Status code와 함께, x402PaymentRequired 응답을 받게됩니다.
2.1.3. x402PaymentRequired 내용을 확인하고, EIP-3009: Transfer with Authorization 스킴에 맞게, 내용을 작성하고 서명을 진행합니다.
EIP-3009는 송금을 다른 주체에게 처리할 수 있도록 하기 위한 이더리움의 스탠다드 입니다.
from, to, value, validAfter, validBefore, nonce 포함. EIP‑712 도메인(name, version, chainId, verifyingContract)으로 서명 범위 고정
이 정보를 기반으로 서명 후, 값이 잘못 작성되지 않았음을 보장합니다.
2.1.4. 서버로 전달할 데이터와, 서명을 Base64로 인코딩하여 X-PAYMENT 헤더에 담아 다시 서버에 동일한 요청을 보냅니다.
2.2.1 에서 이어서 진행
2.2. 전달한 경우
2.2.1. X-PAYMENT 헤더의 정보에서 현재 API에서 지원하는 결제 정보들 중 일치 하는 것을 찾습니다.
정리하자면, x402는 퍼실리테이터(Facilitator)를 통해 결제 검증과 정산을 위임하고, 서버와 클라이언트는 HTTP 헤더(X-PAYMENT / X-PAYMENT-RESPONSE) 만 주고받으며 결제 흐름을 완성할 수 있는 구조를 제공합니다. 서버 개발자가 블록체인 로직을 직접 다루지 않아도 되고, 기존 API 흐름을 유지한 채 결제 기능만 자연스럽게 추가할 수 있다는 점이 큰 장점입니다.
Base 빌더 생태계의 관점에서 보면, x402는 Agent-to-Agent 결제 인프라의 초기 조각을 제공하고 있으며, 아직 초기 버전임에도 방향성은 매우 분명합니다. 앞으로 Base 및 온체인 빌더들이 적극적으로 활용할 기반 기술로 성장할 여지가 충분합니다.
무엇보다 Coinbase는 Base 체인을 중심으로 ‘AI 커머스 시대’의 문을 열고 있습니다. Web2 개발자조차 블록체인을 깊이 이해하지 않아도, 단순한 HTTP 호출 수준에서 온체인 결제를 붙일 수 있는 환경이 열리고 있습니다. 저는 이 변화의 최전선에서 Base Korea Developer Ambassador로 활동하며 생태계를 함께 만들어가고 있다는 사실을 큰 영광으로 생각합니다.
온체인 결제 표준화는 이제 시작에 불과합니다. 그 여정 속에서 x402는 분명 중요한 출발선에 서 있으며, 이 기술이 만들어갈 다음 단계를 기대해봅니다.
Github - coinbase/x402
A payments protocol for the internet. Built on HTTP. - coinbase/x402
해당 API에서 요구할 수 있는 토큰을 여러 종류로 정의할 수 있기 때문입니다. (ex, EIP3009 호환 ERC-20, USDC on Base)
2.2.2. 현재 API에서 지원하는 결제 정보가 있다면, facilitator를 통해 검증(/verify)합니다.
유저로부터 받은 결제 정보와, 청구 정보가 일치하는지 그리고 전달 받은 EIP-3009의 요구사항과 맞는지 검증합니다.
facilitator(퍼실리테이터)는 이러한 내용들을 검증, 정산, 전송 해주는 역할을 합니다. (ex, coinbase…)
블록체인 관련 로직은 퍼실리테이터가 처리해주기 때문에 유저, 서버는 블록체인 로직을 신경쓸 필요가 없습니다.
2.2.3. 전달 받은 내용이 문제가 없다면, 서버는 유저가 요청한 내용을 처리합니다.
2.2.4. 결과를 반환하기 전에 퍼실리테이터로 통해 정산(/settle) 요청을 합니다.
퍼실리테이터가 트랜잭션 생성·서명·브로드캐스트 및 컨펌 대기를 수행합니다.
2.2.5. 정산 성공 시 X-PAYMENT-RESPONSE 헤더에 정산 결과(예: txHash, network, payer 등, Base64-encoded JSON)를 담아 반환합니다.
3. 유저는 결과를 반환 받습니다.
이 때, 유저쪽 로직을 구현하는 개발자가 x402 에서 제공하는 x402HttpxClient 로 개발했다면, 2. 에 해당하는 로직을 신경 쓸 필요가 없습니다.
해당 API에서 요구할 수 있는 토큰을 여러 종류로 정의할 수 있기 때문입니다. (ex, EIP3009 호환 ERC-20, USDC on Base)
2.2.2. 현재 API에서 지원하는 결제 정보가 있다면, facilitator를 통해 검증(/verify)합니다.
유저로부터 받은 결제 정보와, 청구 정보가 일치하는지 그리고 전달 받은 EIP-3009의 요구사항과 맞는지 검증합니다.
facilitator(퍼실리테이터)는 이러한 내용들을 검증, 정산, 전송 해주는 역할을 합니다. (ex, coinbase…)
블록체인 관련 로직은 퍼실리테이터가 처리해주기 때문에 유저, 서버는 블록체인 로직을 신경쓸 필요가 없습니다.
2.2.3. 전달 받은 내용이 문제가 없다면, 서버는 유저가 요청한 내용을 처리합니다.
2.2.4. 결과를 반환하기 전에 퍼실리테이터로 통해 정산(/settle) 요청을 합니다.
퍼실리테이터가 트랜잭션 생성·서명·브로드캐스트 및 컨펌 대기를 수행합니다.
2.2.5. 정산 성공 시 X-PAYMENT-RESPONSE 헤더에 정산 결과(예: txHash, network, payer 등, Base64-encoded JSON)를 담아 반환합니다.
3. 유저는 결과를 반환 받습니다.
이 때, 유저쪽 로직을 구현하는 개발자가 x402 에서 제공하는 x402HttpxClient 로 개발했다면, 2. 에 해당하는 로직을 신경 쓸 필요가 없습니다.
Share Dialog
Share Dialog
2 comments
I've written down what I've learned while reviewing the documentation for my recent project using x402. I plan to write this as a series going forward, and I thought it would be helpful to share it with Base builders in Korea
https://x.com/lo_gan__/status/1982465687382855684?s=46