메인 콘텐츠로 건너뛰기
x402는 HTTP 402 Payment Required 상태 코드를 기반으로 한 결제 프로토콜입니다. 수동 빌링, 신용카드 또는 구독 관리 없이 API 접근을 위한 기계 간 마이크로결제를 가능하게 합니다. USDC로 요청당 결제하고 즉시 API 접근을 받으세요.

동작 원리

상세 플로우

  1. 클라이언트가 요청을 보냅니다 — API 키 없이 또는 만료된 키로 ChainStream API에 요청합니다.
  2. 게이트웨이가 HTTP 402를 반환합니다/x402/purchase를 가리키는 메시지와 함께.
  3. 클라이언트가 GET /x402/purchase?plan=<plan>을 호출합니다 (결제 헤더 없이). 서버가 x402 결제 요구사항과 함께 HTTP 402를 반환합니다: 디코딩된 JSON 본문은 x402 v2 프로토콜을 따릅니다:
  4. 클라이언트가 USDC 전송에 서명합니다@x402 SDK를 사용하고 결제 증빙과 함께 GET /x402/purchase?plan=<plan>을 재시도합니다:
  5. 서버가 결제를 검증하고 정산합니다, 그런 다음 구독 세부 정보를 반환합니다:
    클라이언트는 향후 모든 API 호출에 apiKey를 저장합니다.

CLI 통합

ChainStream CLI는 callWithAutoPayment를 통해 x402 결제를 자동으로 처리합니다. 모든 명령이 402를 만나면 CLI가 플랜 선택과 결제를 안내합니다.

자동 플로우

CLI가 402 응답을 만나면:
  1. /x402/pricing에서 사용 가능한 플랜을 가져와 선택 테이블을 표시
  2. 플랜 선택을 요청
  3. 결제 방법 선택: x402 (Base/Solana USDC) 또는 MPP (Tempo USDC.e)
  4. x402인 경우: @x402/fetch를 통해 결제를 서명하고 전송, 반환된 API Key를 설정에 저장
  5. MPP인 경우: 수동 구매를 위한 tempo request 명령을 출력
  6. 새 API Key로 원래 명령을 재시도
API Key만 있고 지갑이 없는 경우, CLI는 x402를 건너뛰고 MPP 안내를 출력합니다.

지갑 설정

CLI에서 x402 결제를 위해 자금이 있는 지갑이 필요합니다:

수동 통합

커스텀 통합의 경우 @x402 패키지 패밀리를 사용하여 x402 플로우를 구현할 수 있습니다.

의존성

@x402/fetch 사용 (추천)

가장 간단한 통합 — 표준 fetch를 x402 지원으로 래핑:

수동 플로우 (고급)

결제 플로우를 완전히 제어하려면:

결제 지원 체인

가스 수수료 무료

ChainStream은 자체 x402 facilitator를 운영하여 에이전트를 대신해 온체인 결제 트랜잭션을 제출합니다. 이는 다음을 의미합니다:
  • 가스 수수료 없음 — facilitator가 모든 가스 비용을 부담 (Base ETH / Solana SOL)
  • 에이전트 지갑에 USDC만 필요 — 가스용 네이티브 토큰을 보유할 필요 없음
  • 에이전트는 USDC 전송 승인에 서명하고, facilitator가 브로드캐스트하고 실행 비용을 지불
이를 통해 AI 에이전트의 가장 큰 마찰점인 여러 체인에서 네이티브 가스 토큰을 취득하고 관리하는 문제를 해결합니다.

보안 고려사항

  • 결제 한도: 예상치 못한 과금을 방지하기 위해 @x402/fetch 사용 시 항상 maxAmount를 설정하세요.
  • 검증: facilitator는 정산 전에 서명된 결제를 온체인에서 검증합니다. 유효하지 않은 서명은 거부됩니다.
  • 멱등성: 결제가 정산되었지만 응답이 실패한 경우 (네트워크 오류), 동일한 Payment-Signature를 다시 제출할 수 있습니다. 결제는 한 번만 소비됩니다.
  • 컴플라이언스: 지불자 주소는 정산 전에 스크리닝됩니다. 제재 대상 주소는 거부됩니다.