TL;DR

  • X402 Vercel Gateway는 서버리스 환경에서 FastAPI 엔드포인트를 HTTP 402 Payment Required(x402) 프로토콜로 보호하며, 결제 1회당 요청 1회만 허용하는 프로덕션 준비형 참조 구현임
  • 자율형 인공지능 에이전트는 신용카드 입력이나 2단계 인증(2FA)을 수행하기 어려우므로, API에 기계 친화적 결제 표준이 필요함
  • 서버리스 인스턴스별 메모리 딕셔너리만 사용하면 동일한 거래 해시로 10,000건의 동시 요청이 통과할 수 있어, 0.005 USDC 결제 1회로 상위 LLM 또는 데이터베이스 할당량이 소진될 수 있음
  • 게이트웨이는 Solana JSON-RPC의 postTokenBalances - preTokenBalances 검증으로 결제 금액을 확인하고, Upstash Redis SETNX로 거래 해시를 전역 원자적으로 소진 처리함
  • 저장된 거래 해시는 24시간 TTL로 잠기며, 검증에 성공한 최초 요청에는 보호 데이터를 반환하고 재사용 요청에는 HTTP 402를 반환함

문제: 에이전트 마찰 장벽

  • AutoGPT, LangChain, MCP 또는 사용자 지정 봇을 통한 자율형 인공지능 에이전트는 신용카드 양식을 작성하거나 2단계 인증(2FA) 절차를 완료할 수 없음
  • 에이전트 간(A2A) 경제적 상호작용이 증가하면서 API에 기계 네이티브 수익화 표준이 필요함
  • x402 프로토콜은 표준 HTTP 오류 코드와 암호화된 소액 거래를 결합해, 보호된 연산 또는 데이터를 제공하기 전에 호출자에게 결제를 요구함
  • 결제 수단으로 Solana USDC 또는 EVM 기반 거래가 사용됨

치명적 결함: 서버리스의 임시 상태

  • 많은 개발자는 사용된 거래 해시를 추적하기 위해 메모리 딕셔너리나 로컬 캐시로 게이트웨이를 보호함
  • 이 방식은 Docker에서는 작동하지만 서버리스에서는 실패함
  • Vercel과 AWS Lambda 같은 서버리스 플랫폼의 연산 환경은 상태가 없고 수평적으로 임시 생성되므로, 각 인스턴스가 빈 딕셔너리에서 시작함
  • 공격자가 0.005 USDC를 한 번 결제한 뒤 동일한 tx_hash로 10,000건의 동시 요청을 보내면, Vercel이 수십 개의 콜드 마이크로 가상 머신을 생성할 수 있음
  • 모든 인스턴스가 거래 해시를 처음 보는 상태가 되므로 10,000건의 요청이 검증을 통과하고, 결제는 한 번만 이뤄진 채 상위 LLM 또는 데이터베이스 할당량이 소진될 수 있음

해결책: 원자적 분산 상태와 온체인 증명

  • 게이트웨이는 두 단계 암호화·원자적 프로토콜로 서버리스 상태 문제를 해결함
  • 온체인 차액 검증: jsonParsed 옵션을 포함한 Solana JSON-RPC getTransaction을 조회하고, postTokenBalances - preTokenBalances를 계산해 대상 연결 토큰 계정(ATA)이 정확한 결제 금액을 수령했는지 수학적으로 증명함
  • 원자적 분산 잠금(SETNX): Upstash Redis의 SETNX(Set if Not eXists) 명령으로 모든 서버리스 리전에서 거래 해시를 전역 원자적으로 소진 처리함
  • 처리 순서는 다음과 같음
  • 거래의 온체인 결제 증명을 검증함
  • 검증 실패 시 HTTP 402와 Invalid payment proof를 반환함
  • 검증 성공 시 x402:tx:{tx_hash} 키를 Upstash Redis에 기록하고 24시간 TTL을 설정함
  • 키를 처음 획득한 요청에는 보호 데이터를 반환함
  • 이미 키가 존재하면 HTTP 402와 Replay Attack Detected를 반환함

아키텍처

  • 게이트웨이: Vercel Edge 기반 FastAPI가 POST /api/v1/protected-data 엔드포인트를 제공함
  • 결제 요청 흐름
  • 에이전트가 보호 데이터 엔드포인트를 호출함
  • 게이트웨이가 HTTP 402와 함께 recipient, amount_usdc, invoice_id를 반환함
  • 에이전트가 SPL 토큰 전송과 invoice_id 메모에 서명하고 브로드캐스트함
  • Solana JSON-RPC 노드가 확인된 tx_hash를 에이전트에 반환함
  • 결제 증명 검증 흐름
  • 에이전트가 X-Payment-Proof: <tx_hash> 헤더와 함께 보호 데이터 엔드포인트를 다시 호출함
  • 게이트웨이가 Solana JSON-RPC의 getTransaction(tx_hash)를 호출함
  • RPC 노드가 거래 메타데이터와 토큰 잔액을 반환함
  • 게이트웨이가 postTokenBalance - preTokenBalance == amount인지 검증함
  • 중복 결제 방지 흐름
  • 게이트웨이가 Redis에 SETNX x402:tx:<tx_hash>를 24시간 TTL로 실행함
  • 잠금 획득(nx=True) 시 Redis가 OK (1)을 반환하고, 게이트웨이가 HTTP 200과 보호 데이터를 전달함
  • 재사용 시도(nx=False) 시 Redis가 Nil (0)을 반환하고, 게이트웨이가 HTTP 402와 Replay Attack을 전달함

빠른 시작

1. 복제 및 설치

  • 저장소를 다음 URL에서 복제함: https://github.com/roblambert9/x402-vercel-gateway.git
  • 저장소 디렉터리로 이동하고 Python 가상 환경 .venv를 생성·활성화함
  • requirements.txt에 정의된 의존성을 pip install -r requirements.txt로 설치함
  • Windows에서는 가상 환경 활성화 명령으로 .venv\Scripts\activate를 사용하고, 그 외 환경에서는 source .venv/bin/activate를 사용함

2. 환경 변수 구성

  • .env 파일을 생성하거나 Vercel 대시보드에서 다음 환경 변수를 설정함
  • SOLANA_RPC_URL: Solana JSON-RPC 엔드포인트이며 예시는 https://api.devnet.solana.com임
  • RECIPIENT_WALLET: 수신 Solana 주소이며 예시는 YourWalletPublicKey...임
  • USDC_MINT_ADDRESS: USDC의 민트 주소이며 Devnet 예시는 4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU임
  • UPSTASH_REDIS_REST_URL: Upstash Redis REST URL이며 예시는 https://your-db.upstash.io임
  • UPSTASH_REDIS_REST_TOKEN: Upstash Redis REST 토큰이며 예시는 AXxxxx...임

3. 로컬 실행

  • uvicorn main:app --reload --port 8000 명령으로 로컬 서버를 실행함

4. 실거래 통합 테스트 실행

  • Devnet에서 실제 SPL 전송에 서명하고 브로드캐스트한 뒤 게이트웨이의 HTTP 402 챌린지 응답을 검증하는 자동화 테스트를 python tests/live_fire_devnet.py로 실행함

Vercel 배포

  • vercel --prod 명령으로 프로덕션 배포를 실행함
  • Upstash Redis 통합이 Vercel 프로젝트의 환경 변수에 연결돼 있는지 확인함

라이선스

  • MIT License로 제공되며, 자체 에이전트 서비스에서 무료로 사용하고 통합할 수 있음
  • Rob Lambert가 구축함