메인 콘텐츠로 건너뛰기
X402은 Coinbase가 제안한 “HTTP 402 기반 과금” 온체인 결제 프로토콜입니다. 서버는 token이 없는 요청에 대해 402 Payment Required를 반환하고, accepts: [...] 필드에 허용 가능한 체인 / 자산 / 가격을 나열합니다. 클라이언트는 로컬에서 권한 부여에 서명하고(EVM에서는 Permit2 / EIP-712, Solana에서는 SPL token transfer 권한 부여), base64 인코딩된 envelope를 PAYMENT-SIGNATURE 헤더에 넣어 재전송합니다. 서버는 검증 후 실제로 온체인에서 정산한 뒤 비즈니스 결과를 반환합니다.
Ace Data Cloud의 X402 클라이언트는 대상 API를 직접 호출하고, 해당 요청이 실시간으로 반환한 402 Payment Required 및 accepts를 가격 및 서명의 근거로 사용합니다. Facilitator의 결제 기능은 /.well-known/x402에서 검증할 수 있습니다.
@acedatacloud/sdk와 acedatacloud는 모두 paymentHandler 훅을 노출합니다. SDK가 직접 발송한 요청이 402를 받으면, 주입한 handler를 호출하여 PAYMENT-SIGNATURE 헤더를 얻은 후 원래 요청을 다시 전송합니다. @acedatacloud/x402-client / acedatacloud-x402를 SDK와 함께 사용하면, 전체 흐름은 비즈니스 코드에 완전히 투명합니다. 즉, client.openai.chat.completions.create(...)만 사용하면 되며, token 모드와 똑같아 보이지만 내부적으로는 호출당 과금되고 사전 충전이 필요 없습니다. 이 문서에서는:
  • 실제로 TS 측의 「token 없음 + X402 handler 주입」 흐름을 한 번 완주했습니다(T12 검증)
  • EVM / Solana 두 서명 흐름의 차이를 나열했습니다
  • viem 프라이빗 키 모드, 브라우저 지갑 모드, Python EVMAccountSigner 모드의 세 가지 어댑테이션을 제공합니다
  • 쉽게 실수하는 preferScheme / prefer_scheme 필드를 명확히 설명합니다

1. 프로토콜 개요(필독)

성공한 X402 호출 하나에는 3개의 HTTP RTT가 포함됩니다:
X402 envelope는 JSON 한 조각이며, base64 인코딩 후 PAYMENT-SIGNATURE 헤더에 넣습니다. 구조(발췌):
envelope 최상위에는 x402Version: 2가 있으며, accepted 객체를 사용하여 이번에 선택한 scheme 및 network(CAIP-2 식별자)를 선언합니다. preferScheme / prefer_scheme은 서버가 동시에 여러 scheme을 제공할 때 선호 항목을 선택하는 데 사용됩니다. 서버가 exact만 노출하면 이 필드는 무시됩니다. upto로 설정했지만 서버가 이를 노출하지 않으면 첫 번째 일치 항목으로 폴백합니다.

2. TypeScript: 브라우저 지갑 + 서버 측 viem 두 가지 사용법

설치

테스트된 버전 번호:

createX402PaymentHandler 전체 시그니처

반환값은 (ctx) => Promise&lt;{ headers: Record<string, string> }>이며, SDK의 paymentHandler 훅 시그니처와 정확히 일치합니다.

사용법 1: 브라우저(MetaMask / WalletConnect)

첫 호출 시 브라우저에서 두 번의 서명 프롬프트가 표시됩니다. 첫 번째는 USDC에 대한 Permit2 일회성 approve이며(금액은 MaxUint256, 온체인에 기록됨), 두 번째는 X402 envelope의 EIP-712 서명입니다(온체인에 기록되지 않으며, facilitator 검증용일 뿐입니다). 이후 호출에는 두 번째 서명만 필요하므로, 경험상 “한 번 서명 클릭 → 결과 획득”입니다.

사용법 2: Node 서버 측 + viem 프라이빗 키(백엔드 / CLI에 적합)

TS 측의 @acedatacloud/x402-client는 EIP-1193 provider만 허용하며, 프라이빗 키를 직접 관리하지 않습니다. Node / CLI 시나리오에서 표준 방식은 viem을 사용해 프라이빗 키를 WalletClient로 감싼 후, @ethereumjs/util 또는 viem 내부의 EIP-1193 어댑테이션을 사용하는 것입니다.
viem의 EIP-1193 어댑테이션이 충분히 안정적이지 않다고 느껴진다면, 더 저수준의 signEVMUptoPayment 를 사용해 직접 accepts → signed envelope → PAYMENT-SIGNATURE header 경로를 연결하고 SDK 훅을 건너뛸 수도 있습니다. 하지만 프로토콜 업그레이드를 직접 유지 관리하지 않아도 되므로, 여전히 createX402PaymentHandler를 우선 선택하는 것을 권장합니다.

사용법 3: Solana

Solana 체인에서는 현재오직 exact scheme만 노출되므로, preferScheme은 Solana에서 작동하지 않습니다.

3. Python: 프라이빗 키 모드

Python의 acedatacloud-x402는 프라이빗 키로 직접 서명하는 방식입니다(EIP-1193 추상화 없음). 서버 측 / 작업 실행기에 더 적합합니다.

설치

테스트된 버전 번호:

EVM (Base)

Solana

일회성 approve (EVM 최초 1회만)

EVM Base에서 X402는 Permit2를 사용하므로, 지갑이 USDC에 대해 Permit2 컨트랙트에 한 번 MaxUint256 approve를 해야 합니다. acedatacloud-x402에는 approve_permit2가 내장되어 있습니다:
이 거래는 한 번만 전송하면 되며, 이후의 모든 X402 EVM 결제는 이 승인을 사용합니다. Solana에는 필요하지 않습니다.

4. 실제 실행 검증

테스트 목표: TS SDK에 token을 전달하지 않고 X402 handler를 주입했을 때, 정상적으로 요청을 구성하고 시작할 수 있음(실제 온체인 USDC를 소모하지 않는 경량 검증).
출력:
결과 설명:
  • apiToken을 전달하지 않아도 SDK 생성 시오류가 발생하지 않으므로, X402 모드가 실제로 token의 유효한 대체 수단임을 증명합니다.
  • createX402PaymentHandler는 함수(훅)를 반환하며, SDK는 이를 받은 후 402를 수신했을 때만 호출합니다.
  • 실제 온체인 유료 결제가 통과하는 엔드투엔드 테스트는 실제 USDC 차감이 수반되므로 이 튜토리얼에 포함하지 않았습니다. X402 통합 가이드의 e2e 예제를 참고할 수 있습니다.
Python 측 create_x402_payment_handler도 동일한 검증을 수행했습니다 — 함수 반환값은 callable이며, payment_handler=...를 주입할 때 AceDataCloud(...) 생성 시 오류가 발생하지 않습니다. 양쪽의 의미론은 정렬되어 있습니다.

5. 「Bearer token 모드」와의 비교

6. 일반적인 함정

  1. chat 클래스는 반드시 preferScheme=upto여야 합니다: exact를 사용하면 facilitator가 실제 사용량이 아니라 maxAmountRequired를 기준으로 USDC를 차감합니다.
  2. Node 측에서 createX402PaymentHandler에 원시 개인 키를 전달하지 마세요: TS 패키지는 { privateKey }를 받지 않으며, 반드시 EIP-1193 provider로 감싸야 합니다(viem WalletClient 권장).
  3. 첫 호출은 이중 서명입니다: 첫 번째는 Permit2 approve에 서명합니다(온체인, gas 발생), 두 번째는 X402 envelope에 서명합니다(온체인 아님). 이후 호출에서는 두 번째만 남습니다.
  4. Solana에는 Permit2 개념이 없습니다: SPL token transfer 권한에 직접 서명하므로 approve가 필요하지 않습니다. 하지만 현재 Solana 체인에서는 exact만 지원합니다.
  5. 비즈니스 오류와 결제 오류를 구분하세요: 402 → handler 실패 시 X402SignError를 throw합니다(구체적인 유형은 체인별로 다름). 이후 재전송 후 비즈니스 인터페이스의 오류(401 / 422 / 5xx)는 여전히 일반 SDK 예외로 분류됩니다.
  6. viem에 가장 안정적으로 어댑트하는 작성법: evmProvider: walletClient as any는 타입 검사를 잃지만 호환성이 가장 좋습니다. 타입을 유지하려면 viem의 .transport.request를 별도로 { request } 객체로 한 겹 감싸서 전달하세요.

더 알아보기