메인 콘텐츠로 건너뛰기
이 튜토리얼은 최소한의 API 요청으로 Ace Data Cloud X402의 전체 흐름을 설명합니다. 목표는 먼저 복잡한 코드를 작성하는 것이 아니라, 먼저 이해하는 것입니다: 왜 첫 번째 요청은 402를 반환하는지, accepts에는 무엇이 있는지, 그리고 PAYMENT-SIGNATURE는 어떻게 동일한 API 요청을 결제 완료 요청으로 바꾸는지.

준비 사항

다음을 준비해야 합니다: X402로 Ace Data Cloud API를 호출할 때 API Token은 필요하지 않습니다. SDK의 첫 번째 요청에는 Authorization이 포함되지 않으며, Gateway는 402 Payment Required와 결제 요구 사항을 반환합니다. SDK는 서명 후 자동으로 재시도합니다.

SDK 설치

소스 코드 및 패키지 주소: TypeScript:
Python:
Solana를 사용하려면 해당 의존성도 설치해야 합니다:
Python 버전의 Solana signer 의존성은 이미 acedatacloud-x402에 포함되어 있습니다. 깨끗한 임시 환경에서의 설치 및 import 검사 출력:
결과 설명:
  • npm 패키지와 PyPI 패키지는 모두 실제로 배포된 패키지이며, 문서의 자리 표시자 이름이 아닙니다.
  • acedatacloud-x402[cli]는 CLI를 설치하며, approve-permit2 하위 명령은 upto 시나리오의 Permit2 승인에 사용할 수 있습니다.

첫 번째 요청은 402를 반환합니다

먼저 curl을 사용하여 미결제 요청이 무엇을 반환하는지 확인할 수 있습니다. 아래 예시는 PAYMENT-SIGNATURE를 포함하지 않으므로 요금이 부과되지 않습니다:
응답 본문에는 accepts 배열이 포함되며, 일반적인 구조는 다음과 같습니다:
동일한 챌린지 내용은 base64 형식으로 PAYMENT-REQUIRED 응답 헤더에도 포함되므로, 클라이언트는 body를 파싱하지 않고도 결제 요구 사항을 읽을 수 있습니다. 프로덕션 API의 미결제 요청 프로그램 출력 요약은 다음과 같습니다:
결과 설명:
  • 첫 번째 요청에는 Authorization 또는 PAYMENT-SIGNATURE가 포함되지 않으므로 HTTP 402를 반환하며, 요금이 부과되지 않습니다.
  • accepts는 이번 요청에서 유일하게 신뢰할 수 있는 서명 근거이며, 선택 가능한 네트워크, scheme, 금액 상한, 수금 주소 및 자산 주소를 포함합니다.
  • network는 CAIP-2 식별자이며, 클라이언트가 네트워크를 선택할 때는 CAIP-2 문자열로 일치시켜야 합니다.
  • 이번 gpt-4o-mini 최소 채팅 요청의 최대 금액은 95215 atomic USDC, 즉 0.095215 USDC입니다.
  • 매 요청마다 해당 402 응답을 읽어야 하며, 예시 금액을 비즈니스 코드에 하드코딩하지 마십시오.
필드 의미:

SDK로 결제 재시도 완료하기

다음은 최소 TypeScript 예시입니다. 이는 network: 'base'를 지정하며, handler는 이번 402 응답에서 Base의 payment requirement를 선택합니다. 실제 금액과 수금 주소는 여전히 accepts를 기준으로 합니다:
이 코드 뒤에서는 네 단계가 발생합니다:
  1. SDK가 Authorization 없이 일반 API 요청을 한 번 전송합니다.
  2. Gateway가 402 Payment Required 및 accepts를 반환합니다.
  3. createX402PaymentHandler가 network = 'base'의 payment requirement를 선택하고 PAYMENT-SIGNATURE를 서명합니다.
  4. SDK가 동일한 요청 본문으로 재시도하고, Gateway는 Facilitator를 호출하여 검증 및 정산한 후 대상 API로 전달합니다.

Facilitator 지원 기능 확인

X402 API는 리소스 디렉터리에 의존하지 않습니다. 클라이언트는 알려진 API를 직접 호출하고, 해당 요청에 대해 실시간으로 반환되는 402 Payment Required 및 accepts를 유일한 가격 및 서명 근거로 사용합니다. Facilitator의 기능 선언은 다음 위치에 있습니다:
이는 /supported, /verify, /settle 및 현재 활성화된 결제 네트워크만 설명하며, API 리소스는 나열하지 않습니다. Ace Data Cloud의 프로덕션 Facilitator 주소는 다음과 같습니다:
지원하는 네트워크와 scheme을 확인할 수 있습니다:
반환되는 kinds는 Facilitator가 지원하는 네트워크와 scheme을 나열합니다. 실제 호출 시에는 여전히 API가 반환하는 accepts를 기준으로 합니다. Facilitator /supported 출력:
결과 설명:
  • /supported는 Facilitator가 이러한 네트워크와 scheme에 대한 검증 및 정산 기능을 갖추고 있음을 나타냅니다.
  • Base와 Solana는 모두 exact를 지원하며, upto는 현재 Base에서만 제공됩니다.
  • 특정 API가 특정 네트워크를 허용하는지는 여전히 해당 API의 402 accepts를 기준으로 합니다.