메인 콘텐츠로 건너뛰기
X402는 HTTP 402 Payment Required 기반의 온체인 결제 프로토콜입니다. Ace Data Cloud의 X402 기능을 통해 호출자는 API Token을 생성하거나 계정 잔액을 미리 충전하지 않고, 각 API 요청에서 직접 USDC로 온체인 결제를 완료할 수 있습니다. 이 문서 모음은 실제 통합 순서에 따라 구성되어 있습니다. 먼저 최소 요청을 한 번 실행한 다음 SDK를 통합하고, 이후 네트워크, 과금 방식, 주문 결제 및 Facilitator를 이해합니다. 아래 표를 위에서 아래 순서로 읽는 것을 권장합니다.

권장 통합 경로

Ace Data Cloud API만 호출하려는 경우, 공식 SDK를 우선 사용하세요:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
공개 소스 코드 및 패키지 주소: SDK는 첫 번째 무인증 요청 수행, 402 Payment Required 파싱, payment handler 호출, PAYMENT-SIGNATURE를 포함한 재시도 단계를 자동으로 완료합니다. USDC가 있는 지갑을 준비하고 사용할 네트워크를 선택하기만 하면 됩니다. 자체 API도 X402 수금을 지원하도록 하려면 Facilitator 문서를 읽고 paymentRequirements, paymentPayload, /verify, /settle 간의 관계를 이해해야 합니다.

지원 상태

Ace Data Cloud X402는 공개 API, 공식 SDK, Facilitator 및 온체인 정산 경로에서 검증을 완료했습니다. 아래 표는 개발자 통합 시 가장 일반적으로 사용되는 기능 차원에 따라 현재 상태를 요약합니다. 아래 출력은 검증된 경로의 반환 형태를 설명하는 용도로만 사용됩니다. 실제 통합 시에는 항상 현재 API가 반환하는 accepts를 기준으로 하세요.
설명:
  • npm 및 PyPI 패키지 모두 깨끗한 환경에서 설치 및 import에 성공했습니다.
  • 결제되지 않은 API 요청은 402를 반환하며, accepts에는 Base 및 Solana에서 사용 가능한 결제 방식이 포함됩니다.
  • accepts[].network는 CAIP-2 식별자이며, 클라이언트가 네트워크를 선택할 때 반드시 CAIP-2 문자열로 일치시켜야 합니다.
  • TypeScript SDK와 Python SDK 모두 402를 자동으로 처리하고 paid retry를 완료할 수 있습니다.
  • Base exact, Base upto 및 주문 결제에는 모두 공개적으로 열 수 있는 explorer 주소가 있습니다.
  • Base upto의 서명 상한은 95215 atomic USDC이고 실제 settlement는 3 atomic USDC로, 후불 계량이 실제 사용량에 따라 정산되는 특성을 보여 줍니다.
  • Solana exact는 HTTP 402 -> HTTP 200 및 모델 출력을 검증했습니다. 공개 RPC 조회는 속도 제한이 있을 수 있으므로, 엄격한 대사 시에는 자체 Solana RPC 또는 플랫폼 측 settlement 기록을 사용하여 거래 서명을 확인하는 것이 좋습니다.

연동 시 주의사항

개발자가 연동할 때는 문서의 예시 금액이나 주소를 복사하는 대신, 현재 요청이 반환하는 실시간 결제 요구사항을 우선적으로 확인하십시오:
  • accepts[].maxAmountRequired는 현재 요청에서 서명할 수 있는 최대 금액입니다.
  • accepts[].asset는 이번 요청에 사용할 USDC 컨트랙트 또는 mint입니다.
  • accepts[].extra.chainId, accepts[].extra.facilitatorAddress 및 accepts[].extra.verifyingContract는 EVM typed data 서명에 참여합니다.
  • upto는 지갑이 먼저 대상 체인의 USDC를 Permit2에 승인해야 하며, 승인되지 않은 경우 PERMIT2_ALLOWANCE_REQUIRED가 반환됩니다.
  • 후불 계량 사용을 명확히 원하는 경우 TypeScript SDK에서 preferScheme: 'upto'를 전달하십시오. 그렇지 않으면 SDK는 해당 네트워크에서 서버가 반환한 첫 번째 사용 가능한 requirement를 선택합니다.

공개적으로 검증할 수 있는 범위

연동 전에 다음 공개 엔드포인트와 SDK 동작을 먼저 검증할 수 있습니다:
  • Authorization 또는 PAYMENT-SIGNATURE 없이 보낸 API 요청은 402 Payment Required를 반환하며, 응답의 accepts는 이번 요청의 유일한 서명 근거입니다.
  • TypeScript SDK와 Python SDK 모두 payment handler를 제공하며, SDK 전송 계층은 402를 수신한 후 handler를 호출하고 한 번 재시도합니다.
  • https://facilitator.acedata.cloud/.well-known/x402: Facilitator가 지원하는 네트워크, scheme 및 프로토콜 엔드포인트를 반환합니다. API 가격은 여전히 대상 요청이 실시간으로 반환하는 402를 기준으로 합니다.
  • https://facilitator.acedata.cloud/supported: Facilitator가 지원하는 네트워크와 scheme을 반환합니다.
  • X402Client 저장소에는 고급 온체인 검증 도구가 포함되어 있으며, 서명, 재시도 및 settlement 동작을 확인하는 데 사용할 수 있습니다. 도구 출력은 온라인 API가 반환하는 accepts를 대체하지 않습니다.
upto는 후불 계량 settlement에 속하며, 채팅 완성, 모델 호출 등 실제 사용량을 응답 후에야 알 수 있는 API에 적합합니다. 현재 upto는 Base에서만 제공됩니다. 서명 검증에 실패하면 chain id, facilitator 주소, spender, USDC 컨트랙트 및 Permit2 allowance가 402 응답과 일치하는지 확인하십시오.