Cover photo

Trying x402 on Base: Korean Guide + AI Agent Support

HTTP 402 Micro-Payments: A Guide to Running Instant Payments Directly from Base

awesome-x402-on-base is an x402 onboarding hub created by the Base Korea Developer Ambassador team. We've integrated the official x402 repo as a submodule so you can run the latest examples immediately, with Korean tutorials added for each example. We've also structured the documentation with guardrails so AI agents like Claude or Cursor can read and execute directly.

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