x402 결제 프로토콜
x402는 402 Payment Required 상태 코드를 사용하여 HTTP를 통해 즉시 스테이블코인 결제를 가능하게 합니다. AI 에이전트가 API, 데이터, 또는 온디맨드 컴퓨팅 리소스에 대한 비용을 지불할 때 완벽합니다.
빠른 시작
SDK 설치
npm install x402
# 또는
pnpm add x402
환경 설정
# 지갑 개인 키를 안전하게 저장
export WALLET_PRIVATE_KEY="0x..."
# 선택 사항: 네트워크 RPC 지정
export BASE_RPC_URL="https://mainnet.base.org"
x402 작동 방식
- 요청 → 클라이언트가 유료 API 호출
- 402 응답 → 서버가
PAYMENT-REQUIRED헤더에 결제 세부 정보 반환 - 결제 및 재시도 → 클라이언트가 결제 서명 후
PAYMENT-SIGNATURE헤더와 함께 재시도 - 접근 허용 → 서버가 검증 후 정산하고 리소스 반환
x402 클라이언트 사용
TypeScript/Node.js
import { x402Client } from 'x402';
const client = x402Client({
privateKey: process.env.WALLET_PRIVATE_KEY,
network: 'base', // 또는 'ethereum', 'arbitrum' 등
});
// 자동 402 처리
const response = await client.fetch('https://api.example.com/paid-endpoint');
const data = await response.json();
fetch 래퍼 사용
import { wrapFetch } from 'x402';
const fetch402 = wrapFetch(fetch, {
privateKey: process.env.WALLET_PRIVATE_KEY,
});
// 일반 fetch처럼 사용 - 402가 자동으로 처리됨
const res = await fetch402('https://paid-api.com/data');
수동 흐름 (curl)
1단계: 결제 요구 사항 확인
curl -i https://api.example.com/paid-resource
# 402와 함께 PAYMENT-REQUIRED 헤더 (base64 JSON) 반환
2단계: 결제 세부 정보 디코딩
# PAYMENT-REQUIRED 헤더에는 base64로 인코딩된 JSON이 포함됨:
# {
# "amount": "1000000", # 1 USDC (소수점 6자리)
# "currency": "USDC",
# "network": "base",
# "recipient": "0x...",
# "scheme": "exact"
# }
3단계: 서명 및 결제
# x402 CLI 또는 SDK를 사용하여 결제 서명 생성
npx x402 pay \
--amount 1000000 \
--recipient 0x... \
--network base
4단계: 증명과 함께 재시도
curl -H "PAYMENT-SIGNATURE: <base64_payload>" \
https://api.example.com/paid-resource
일반적인 패턴
API 호출 비용 지불
// 호출당 0.001 USDC가 소요되는 날씨 API
const weather = await client.fetch('https://weather-api.x402.org/forecast?city=NYC');
AI 추론 비용 지불
// 토큰당 가격 책정 방식의 LLM API
const completion = await client.fetch('https://llm.example.com/v1/chat', {
method: 'POST',
body: JSON.stringify({ prompt: 'Hello' }),
});
결제 전 잔액 확인
import { getBalance } from 'x402';
const balance = await getBalance({
address: walletAddress,
network: 'base',
token: 'USDC',
});
if (balance < requiredAmount) {
console.log('USDC 잔액 부족');
}
지원 네트워크
| 네트워크 | 체인 ID | 상태 |
|---|---|---|
| Base | 8453 | ✅ 기본 |
| Ethereum | 1 | ✅ 지원 |
| Arbitrum | 42161 | ✅ 지원 |
| Optimism | 10 | ✅ 지원 |
| Polygon | 137 | ✅ 지원 |
결제 방식
- exact: 고정 금액 지불 (예: API 호출당 $0.01)
- upto: 사용량에 따라 최대 금액까지 지불 (예: LLM 토큰)
- subscription: 세션이 있는 지갑 기반 접근 (V2)
에러 처리
try {
const res = await client.fetch(url);
} catch (err) {
if (err.code === 'INSUFFICIENT_BALANCE') {
// 지갑에 자금을 충전해야 함
} else if (err.code === 'PAYMENT_FAILED') {
// 온체인 트랜잭션 실패
} else if (err.code === 'INVALID_PAYMENT_REQUIREMENTS') {
// 서버가 잘못된 402 응답을 보냄
}
}
보안 참고 사항
- 로그나 채팅에 개인 키를 절대 노출하지 마세요.
- 지갑 자격 증명에는 환경 변수를 사용하세요.
- 비밀 주입에는
op run또는 이와 유사한 방법을 선호하세요. - 대규모 트랜잭션을 확인하기 전에 결제 금액을 검토하세요.
V2 기능 (2025년 12월)
- 지갑 기반 신원: 세션을 사용하여 모든 호출에 재결제하지 않음
- 자동 탐색: API가
/.well-known/x402에서 결제 메타데이터 노출 - 다중 촉진자: 결제 프로세서 간 선택
- CAIP 표준: 범용 체인/자산 식별자