Skip to main content
X402는 HTTP 402 Payment Required를 기반으로 한 온체인 결제 프로토콜입니다. Ace Data Cloud의 X402 기능을 통해 호출자는 API 토큰을 생성하거나 계좌 잔액을 미리 충전하지 않고도 매 API 요청마다 USDC로 직접 온체인 결제를 완료할 수 있습니다. 이 문서 세트는 실제 통합 순서에 따라 구성되어 있습니다: 먼저 최소 요청을 실행한 후 SDK를 통합하고, 그 다음 네트워크, 요금제, 주문 결제 및 Facilitator를 이해합니다. 아래 표에 따라 위에서 아래로 읽는 것을 권장합니다.

​
추천 통합 경로

Ace Data Cloud API를 호출하려는 경우, 공식 SDK를 우선적으로 사용하세요:
  • TypeScript: @acedatacloud/sdk + @acedatacloud/x402-client
  • Python: acedatacloud + acedatacloud-x402
공식 소스 코드 및 패키지 주소: SDK는 첫 번째 인증 없는 요청을 자동으로 처리하고, 402 Payment Required를 해석하며, 결제 핸들러를 호출하고, PAYMENT-SIGNATURE를 포함하여 이러한 단계를 재시도합니다. 당신은 USDC가 있는 지갑을 준비하고 사용하고자 하는 네트워크를 선택하기만 하면 됩니다. 자신의 API도 X402 수금을 지원하게 하려면 Facilitator 문서를 읽고 paymentRequirements, paymentPayload, /verify 및 /settle의 관계를 이해해야 합니다.

​
지원 상태

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

​
접속 주의 사항

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

​
공개 검증 가능한 범위

접속 전에 이러한 공개 엔트리와 SDK 동작을 먼저 검증할 수 있습니다:
  • Authorization 또는 PAYMENT-SIGNATURE가 없는 API 요청은 402 Payment Required를 반환하며, 응답의 accepts는 이번 요청의 유일한 서명 근거입니다.
  • TypeScript SDK와 Python SDK는 모두 결제 핸들러를 제공하며, SDK 전송 계층은 402를 수신한 후 핸들러를 호출하고 한 번 재시도합니다.
  • https://facilitator.acedata.cloud/.well-known/x402: Facilitator가 지원하는 네트워크, 스킴 및 프로토콜 엔드포인트를 반환합니다; API 가격은 여전히 목표 요청에서 실시간으로 반환된 402를 기준으로 합니다.
  • https://facilitator.acedata.cloud/supported: Facilitator가 지원하는 네트워크와 스킴을 반환합니다.
  • X402Client 저장소에는 서명 확인, 재시도 및 정산 동작을 위한 고급 체인 상 검증 도구가 포함되어 있습니다; 도구 출력은 온라인 API에서 반환된 accepts를 대체하지 않습니다.
upto는 후속 측정 정산에 해당하며, 채팅 완성, 모델 호출 등 실제 사용량이 응답 후에야 알려지는 API에 적합합니다. 현재 Base만 upto를 제공하며, 서명 검증이 실패하면 체인 ID, facilitator 주소, spender, USDC 계약 및 Permit2 허용량이 402 응답과 일치하는지 확인하십시오.