# Base에서 x402 써보기: 한글 가이드 + AI 에이전트 지원 *HTTP 402 마이크로페이먼트, 즉시 결제를 Base에서 직접 돌려보는 가이드* By [_logan.base.eth](https://paragraph.com/@logan-d-able) · 2025-12-11 x402, x402onbase, agentic_commerce, agentic_payment --- **awesome-x402-on-base**는 대한 베이스에서 만든 x402 온보딩 허브입니다. 공식 x402 레포를 서브모듈로 통째로 가져와서 최신 예제를 바로 돌려볼 수 있고, 예제마다 한글 해설을 작성해두었습니다. Claude나 Cursor 같은 AI 에이전트가 문서를 읽고 바로 실행할 수 있도록 가드레일도 정리해 뒀고요. **왜 만들었나** ---------- **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](https://github.com/Daehan-Base/awesome-x402-on-base) --- *Originally published on [_logan.base.eth](https://paragraph.com/@logan-d-able/trying-x402-on-base-korean-guide-ai-agent-support-kor)*