Why We Built This

x402 is a payment protocol leveraging HTTP 402 "Payment Required". Payments complete in about 2 seconds, gas fees are under $0.0001, and minimum payments start at $0.001. One header, one signature—works anywhere: web, AI, or IoT.

Base is an L2 with ultra-low gas fees, fast finality, and native USDC support. It makes micropayments actually practical.

The official repo is great, but it lacked Korean onboarding, Base-specific tips, and documentation structured for AI agents to use as a guide. So we built it ourselves.

Repository Structure

• external/x402/ (read-only): Coinbase official x402 examples and SDK submodule. Do not modify.

• docs/korean/: Korean tutorials and getting started guide. Structured step-by-step so Web2 developers can follow along.

• examples/: Base-specific examples (work in progress). Gas optimization, USDC integration, deployment patterns coming soon.

• resources/: Korean community links and reference materials.

We've clearly documented paths, rules, and guardrails for AI agents. Claude or Cursor can handle exploration → summarization → execution autonomously.

Why x402 + Base Works Well

• x402: HTTP-native payments. Minimal authentication or session management burden, easy to integrate anywhere.

• Base: Cheap gas, fast finality, native USDC. Perfect for micropayments and agent-to-agent transactions.

Getting Started

1) Clone & Sync Submodules

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

git submodule update --init --recursive

2) Open the Guide

In docs/korean/getting_started.ko.md, you can set up your CDP account, API Key, Wallet Secret, environment variables, and test funds all at once.

3) Run Examples (Python)

• Sync client: external/x402/examples/python/clients/requests

• Async client: external/x402/examples/python/clients/httpx

• Paid API server: external/x402/examples/python/servers

• Service discovery: external/x402/examples/python/discovery

Korean tutorials are mapped 1:1 in docs/korean/examples/*.ko.md.

Security Essentials

• Keep keys in .env and never commit them. No hardcoding or logging either.

• Use base-sepolia for development; mainnet keys only in production.

• Get test funds from CDP Faucet or Circle Faucet for Base Sepolia USDC.

• Don't touch external/x402/; do customizations in examples/ and docs/.

Roadmap

• Phase 1 ✅: Structure, submodule setup, basic Korean docs

• Phase 2 🔄: Base migration guide, gas optimization, automation tools

• Phase 3 ⏳: AI agent integration examples (LangChain, Claude, etc.), production deployment & security

• Phase 4 ⏳: English translation, global expansion

For AI Agent Users

• Rules and guardrails are documented in claude.md and agents.md. Your agents won't get lost.

• Examples and tutorials are mapped 1:1, making "find code → configure → run → verify" flows easy to automate.

• Security guidelines included as a first-line safety measure when using agents.

Closing

Want to try x402 on Base? Follow the Korean guide and run the official examples. You'll quickly see how lightweight HTTP 402-based payments integrate into web, AI, and IoT workflows.

Start with awesome-x402-on-base, where "code → tutorial → execution" lives in one place.

Reference

https://github.com/Daehan-Base/awesome-x402-on-base

왜 만들었나

x402는 HTTP 402 "Payment Required"를 활용한 결제 프로토콜입니다. 결제 완료까지 2초 남짓, 가스비는 $0.0001도 안 되고, $0.001부터 결제가 됩니다. 헤더 하나, 서명 하나면 웹이든 AI든 IoT든 어디서든 붙일 수 있어요.

Base는 초저가 가스비에 빠른 확정, 네이티브 USDC까지 갖춘 L2입니다. 마이크로페이먼트를 실제로 쓸 만한 수준으로 끌어올려 줍니다.

공식 레포가 잘 되어 있지만, 한글 온보딩이랑 Base 맞춤 팁이 없었고 AI 에이전트가 가이드로 사용할 문서를 보완하면 좋을 것 같아 직접 만들었습니다.

레포 구조

• external/x402/ (읽기 전용): Coinbase 공식 x402 예제·SDK 서브모듈. 읽기 전용 입니다.

• docs/korean/: 한글 튜토리얼과 시작 가이드. Web2 개발자도 따라올 수 있게 단계별로 구성했습니다.

• examples/: Base 특화 예제 (작성 중). 가스 최적화, USDC 통합, 배포 패턴 등 추가 예정.

• resources/: 한국 커뮤니티 링크 등 참고 자료.

AI 에이전트용으로 경로, 규칙, 가드레일을 문서에 명확하게 적어두었습니다. Claude나 Cursor가 탐색 → 요약 → 실행까지 알아서 해낼 수 있어요.

x402 + Base, 왜 잘 맞나

• x402: HTTP 네이티브 결제. 인증이나 세션 관리 부담이 거의 없어서 붙이기 편합니다.

• Base: 가스비 싸고 확정 빠르고 USDC 네이티브. 마이크로페이먼트랑 에이전트 결제에 딱입니다.

바로 시작하기

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

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

git submodule update --init --recursive

2) 가이드 열기

docs/korean/getting_started.ko.md에서 CDP 계정, API Key, Wallet Secret, 환경 변수, 테스트 자금까지 한 번에 설정할 수 있습니다.

3) 예제 돌려보기 (Python)

• 동기 클라이언트: external/x402/examples/python/clients/requests

• 비동기 클라이언트: external/x402/examples/python/clients/httpx

• 유료 API 서버: external/x402/examples/python/servers

• 서비스 검색: external/x402/examples/python/discovery

한글 해설은 docs/korean/examples/*.ko.md에 1:1로 매핑해 뒀습니다.

보안, 이것만 지키세요

• 키는 .env에 넣고 절대 커밋하지 마세요. 하드코딩이나 로그 출력도 안 됩니다.

• 개발은 base-sepolia, 메인넷 키는 프로덕션에서만.

• 테스트 자금은 CDP Faucet이나 Circle Faucet에서 Base Sepolia USDC로 받으세요.

• external/x402/는 손대지 말고, 커스터마이즈는 examples/랑 docs/에서 하세요.

로드맵

• Phase 1 ✅: 구조 잡기, 서브모듈 연결, 기본 한글 문서

• Phase 2 🔄: Base 전환 가이드, 가스 최적화, 자동화 도구

• Phase 3 ⏳: AI 에이전트 통합 예제 (LangChain, Claude 등), 프로덕션 배포·보안

• Phase 4 ⏳: 영어 번역, 글로벌 확장

AI 에이전트 쓰시는 분들께

• 금지/허용 규칙을 문서(claude.md, agents.md)에 작성해두었습니다. 에이전트가 헤매지 않아요.

• 예제-해설이 1:1이라 "코드 찾기 → 설정 → 실행 → 확인" 흐름을 자동화하기 좋습니다.

• 보안 수칙을 포함하고 있어 에이전트를 사용하는 경우를 위한 1차 안전장치를 설정해두었습니다.

마치며

Base에서 x402 붙여보고 싶으면 한글 가이드 따라 공식 예제 돌려보세요. HTTP 402 기반 결제가 얼마나 가볍게 웹이나 AI, IoT 워크플로우에 붙는지 금방 느끼실 겁니다.

"코드 → 해설 → 실행"이 한 곳에 있는 awesome-x402-on-base에서 시작해 보세요.

Reference

• https://github.com/Daehan-Base/awesome-x402-on-base

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 기반 서버 미들웨어, 클라이언트 요청 흐름, 그리고 결제 · 정산 처리 플로우를 중심으로 정리합니다.

Overview

• Coinbase에서 구현되어있는 x402는 서버단에서 사용할 수 있는 FastAPI 미들웨어, Flask는 서버 예제 및 클라이언트에서 사용할 수 있는 x402HttpxClient (httpx) 및 x402_requests (requests) 클래스를 제공합니다.

  • 유저쪽 로직의 경우 사용하는 유저 입장에서 언제 x402 프로세스가 처리되었는지 굳이 알 필요가 없으므로 로직을 숨겨두었습니다.

  • Middleware의 경우, 서버단에서 필요한 API 엔드포인트( ex, 구매 요청)에 쉽게 등록할 수 있도록 되어있습니다.

    • 예제에서는 고정된 값을 반환하지만, 커머스의 경우 구매 요청 시 전달받은 장바구니 정보 혹은 유저 정보를 기반으로 고객에게 금액을 청구할 수 있습니다.

Payment Process Flow Example

• 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에서 지원하는 결제 정보들 중 일치 하는 것을 찾습니다.

    • 해당 API에서 요구할 수 있는 토큰을 여러 종류로 정의할 수 있기 때문입니다. (ex, EIP3009 호환 ERC-20, USDC on Base)

  • 2.2.2. 현재 API에서 지원하는 결제 정보가 있다면, facilitator를 통해 검증(/verify)합니다.

    • 유저로부터 받은 결제 정보와, 청구 정보가 일치하는지 그리고 전달 받은 EIP-3009의 요구사항과 맞는지 검증합니다.

    • facilitator(퍼실리테이터)는 이러한 내용들을 검증, 정산, 전송 해주는 역할을 합니다. (ex, coinbase…)

      • 블록체인 관련 로직은 퍼실리테이터가 처리해주기 때문에 유저, 서버는 블록체인 로직을 신경쓸 필요가 없습니다.

      • https://www.x402scan.com/facilitators

  • 2.2.3. 전달 받은 내용이 문제가 없다면, 서버는 유저가 요청한 내용을 처리합니다.

  • 2.2.4. 결과를 반환하기 전에 퍼실리테이터로 통해 정산(/settle) 요청을 합니다.

    • 퍼실리테이터가 트랜잭션 생성·서명·브로드캐스트 및 컨펌 대기를 수행합니다.

  • 2.2.5. 정산 성공 시 X-PAYMENT-RESPONSE 헤더에 정산 결과(예: txHash, network, payer 등, Base64-encoded JSON)를 담아 반환합니다.

  3. 유저는 결과를 반환 받습니다.

  • 이 때, 유저쪽 로직을 구현하는 개발자가 x402 에서 제공하는 x402HttpxClient 로 개발했다면, 2. 에 해당하는 로직을 신경 쓸 필요가 없습니다.

정리하자면, 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는 분명 중요한 출발선에 서 있으며, 이 기술이 만들어갈 다음 단계를 기대해봅니다.

References

1. Github - coinbase/x402

GitHub - coinbase/x402: A payments protocol for the internet. Built on HTTP.

A payments protocol for the internet. Built on HTTP. - coinbase/x402

https://github.com

2. CDP Docs- x402

   Welcome to x402 - Coinbase Developer Documentation

   x402 is a new open payment protocol developed by Coinbase that enables instant, automatic stablecoin payments directly over HTTP. By reviving the x402 uses a simple request-response flow with programmatic payments.

   https://docs.cdp.coinbase.com

   

3. x402.org

   x402.org

   An open standard for internet-native payments

   https://www.x402.org