x402 Payments: AI 에이전트를 위한 자율 결제 시스템

x402는 에이전트가 자율적으로 결제할 수 있게 해줍니다. 에이전트가 페이월(HTTP 402)에 부딪히면 자동으로 암호화폐 결제에 서명하고, 요청을 재시도하며, 계속 진행합니다—사람의 개입이 필요 없습니다. 이를 통해 AI 서비스를 위한 네이티브 수익화 계층을 만들 수 있습니다.

왜 x402를 사용해야 할까요?

기존 결제 시스템은 자율 에이전트에게 적합하지 않습니다:

문제	기존 결제 시스템	x402
에이전트가 페이월에 부딪힘	❌ 사람이 신용카드를 입력할 때까지 대기	✅ 자동 서명 및 재시도
소액 결제 ($0.001)	❌ 수수료가 결제 금액을 초과	✅ L2에서 저비용
정산	❌ 1-3일 소요	✅ 즉시
검증	❌ Stripe API 신뢰 필요	✅ 암호화 증명

작동 원리

단계	발생하는 일
1. 요청	에이전트가 유료 API 엔드포인트 호출
2. 402 응답	서버가 결제 요구사항 반환 (v2는 PAYMENT-REQUIRED, 레거시 v1은 JSON 본문)
3. 서명	에이전트가 EIP-712 타입 데이터 페이로드 서명 (아직 가스 없음)
4. 재시도	에이전트가 서명된 결제 헤더와 함께 요청 재전송 (v2는 PAYMENT-SIGNATURE, v1은 X-PAYMENT)
5. 검증 및 실행	Facilitator가 서명을 검증하고 온체인에서 전송 실행
6. 성공	서버가 요청된 데이터 반환

x402 vs 대안

측면	x402	Stripe	Lightning
정산	즉시	1-3일	즉시
에이전트 자율성	자동 서명	웹훅 필요	수동 채널
소액 결제	✅ L2 수수료	❌ 높은 수수료	✅
검증	암호화	API 호출	노드 검증

---

빠른 시작

pip install spoon-ai x402
export PRIVATE_KEY="your-wallet-private-key"
export X402_RECEIVER_ADDRESS="0xYourReceiverWallet"

import asyncio
from spoon_ai.payments import X402PaymentService, X402PaymentRequest

# 결제 서비스 초기화
service = X402PaymentService()

async def main():
    # 결제 요청 생성
    request = X402PaymentRequest(
        amount_usdc="0.01",  # USDC 금액
        resource="/premium-data",
        description="프리미엄 데이터 접근"
    )

    # 서명하고 결제 영수증 생성
    receipt = await service.sign_and_pay(request)
    print(f"결제 서명됨: {receipt}")

asyncio.run(main())

참고: 에이전트 기반 x402 결제의 경우, 결제 기능이 구성된 에이전트가 402 응답을 자동으로 처리합니다. 완전한 통합 패턴은 x402 패키지의 전체 예제를 참조하세요.

---

구성 요소

구성 요소	SpoonOS 내 역할
x402 facilitator	서명된 결제 페이로드를 검증하고 정산하는 공개 서비스 (기본값: https://x402.org/facilitator)
Paywall server	무료 요청을 402 페이로드로 거부하고 유효한 호출을 에이전트로 전달하는 FastAPI 라우터 (spoon_ai.payments.app)
SpoonReact agent	HTTP 프로브를 발행하고, 도구를 통해 결제에 서명하며, 메모리에 결제 영수증을 저장합니다
Signer	프로세스 내에서 로드된 PRIVATE_KEY 또는 TURNKEY_* 변수를 통해 구성된 Turnkey 신원 중 하나

설정 방법

대부분의 배포는 .env 항목과 (선택적으로) 설정 오버라이드만 필요합니다:

X402_RECEIVER_ADDRESS=0xwallet-that-receives-fees
X402_FACILITATOR_URL=https://x402.org/facilitator
X402_DEFAULT_ASSET=
X402_DEFAULT_NETWORK=
X402_DEFAULT_SCHEME=exact
X402_DEFAULT_AMOUNT_USDC=
X402_PAYWALL_APP_NAME=SpoonOS Agent Services
X402_PAYWALL_APP_LOGO=https://your-domain.example/logo.png
X402_DEMO_URL=https://www.x402.org/protected

핵심 포인트:

• 시스템은 항상 로컬 PRIVATE_KEY를 선호합니다. 해당 변수가 비어 있고 Turnkey 자격 증명(TURNKEY_*)이 존재하면, SpoonOS는 투명하게 호스팅된 서명으로 전환합니다.
• CLI 워크플로우(spoon-cli 또는 레거시 main.py CLI)에서 CLI config.json의 x402 블록은 이러한 기본값(브랜딩, 설명, 타임아웃 등)을 미러링합니다. 환경별 차이가 필요한 경우 해당 파일을 업데이트하세요. 핵심 SDK는 여전히 환경 변수에서 값을 읽습니다.
• X402_DEFAULT_ASSET을 설정하면 모든 타입 데이터 도메인이 실제 USDC 컨트랙트를 참조하여 서명이 facilitator 검증을 통과합니다.

런타임 생명주기

유료 재시도가 실패하는 경우(예: verify_payment가 헤더를 거부하거나 facilitator가 오류를 보고하는 경우), 페이월 서버는 즉시 다른 402 또는 오류 페이로드를 반환하고 에이전트는 수정된 매개변수로 x402_paywalled_request를 다시 실행할지 결정합니다. 성공적인 검증은 즉시 정산 및 대상 에이전트 실행으로 이동하므로, 결제 헤더가 수락되면 추가 재시도 주기가 없습니다 (v2는 PAYMENT-SIGNATURE, 레거시 v1은 X-PAYMENT).

운영 체크리스트

1. 공개 데모를 위해 https://faucet.circle.com/를 사용하여 0.01 USDC를 민팅하세요.
2. 최종적으로 정산을 받는 지갑과 X402_RECEIVER_ADDRESS를 일치시키세요.
3. facilitator 응답을 모니터링하세요. invalid_exact_evm_payload_signature 오류는 일반적으로 asset, chainId, 또는 nonce 인코딩이 더 이상 페이월 챌린지와 일치하지 않음을 의미합니다.
4. X402PaymentService.decode_payment_response(header)를 사용하여 로그나 분석 파이프라인에 결제 영수증을 보관하세요.