accepts에는 무엇이 있는지, 그리고 PAYMENT-SIGNATURE는 어떻게 동일한 API 요청을 결제 완료 요청으로 바꾸는지.
준비 사항
다음을 준비해야 합니다:
X402로 Ace Data Cloud API를 호출할 때 API Token은 필요하지 않습니다. SDK의 첫 번째 요청에는
Authorization이 포함되지 않으며, Gateway는 402 Payment Required와 결제 요구 사항을 반환합니다. SDK는 서명 후 자동으로 재시도합니다.
SDK 설치
소스 코드 및 패키지 주소:- SDK 저장소: https://github.com/AceDataCloud/SDK
- X402 Client 저장소: https://github.com/AceDataCloud/X402Client
- npm:
@acedatacloud/sdk,@acedatacloud/x402-client - PyPI:
acedatacloud,acedatacloud-x402
acedatacloud-x402에 포함되어 있습니다.
깨끗한 임시 환경에서의 설치 및 import 검사 출력:
- npm 패키지와 PyPI 패키지는 모두 실제로 배포된 패키지이며, 문서의 자리 표시자 이름이 아닙니다.
acedatacloud-x402[cli]는 CLI를 설치하며,approve-permit2하위 명령은upto시나리오의 Permit2 승인에 사용할 수 있습니다.
첫 번째 요청은 402를 반환합니다
먼저curl을 사용하여 미결제 요청이 무엇을 반환하는지 확인할 수 있습니다. 아래 예시는 PAYMENT-SIGNATURE를 포함하지 않으므로 요금이 부과되지 않습니다:
accepts 배열이 포함되며, 일반적인 구조는 다음과 같습니다:
PAYMENT-REQUIRED 응답 헤더에도 포함되므로, 클라이언트는 body를 파싱하지 않고도 결제 요구 사항을 읽을 수 있습니다.
프로덕션 API의 미결제 요청 프로그램 출력 요약은 다음과 같습니다:
- 첫 번째 요청에는
Authorization또는PAYMENT-SIGNATURE가 포함되지 않으므로 HTTP 402를 반환하며, 요금이 부과되지 않습니다. accepts는 이번 요청에서 유일하게 신뢰할 수 있는 서명 근거이며, 선택 가능한 네트워크, scheme, 금액 상한, 수금 주소 및 자산 주소를 포함합니다.network는 CAIP-2 식별자이며, 클라이언트가 네트워크를 선택할 때는 CAIP-2 문자열로 일치시켜야 합니다.- 이번
gpt-4o-mini최소 채팅 요청의 최대 금액은95215atomic USDC, 즉0.095215USDC입니다. - 매 요청마다 해당 402 응답을 읽어야 하며, 예시 금액을 비즈니스 코드에 하드코딩하지 마십시오.
SDK로 결제 재시도 완료하기
다음은 최소 TypeScript 예시입니다. 이는network: 'base'를 지정하며, handler는 이번 402 응답에서 Base의 payment requirement를 선택합니다. 실제 금액과 수금 주소는 여전히 accepts를 기준으로 합니다:
- SDK가
Authorization없이 일반 API 요청을 한 번 전송합니다. - Gateway가
402 Payment Required및accepts를 반환합니다. createX402PaymentHandler가network = 'base'의 payment requirement를 선택하고PAYMENT-SIGNATURE를 서명합니다.- SDK가 동일한 요청 본문으로 재시도하고, Gateway는 Facilitator를 호출하여 검증 및 정산한 후 대상 API로 전달합니다.
Facilitator 지원 기능 확인
X402 API는 리소스 디렉터리에 의존하지 않습니다. 클라이언트는 알려진 API를 직접 호출하고, 해당 요청에 대해 실시간으로 반환되는402 Payment Required 및 accepts를 유일한 가격 및 서명 근거로 사용합니다.
Facilitator의 기능 선언은 다음 위치에 있습니다:
/supported, /verify, /settle 및 현재 활성화된 결제 네트워크만 설명하며, API 리소스는 나열하지 않습니다.
Ace Data Cloud의 프로덕션 Facilitator 주소는 다음과 같습니다:
kinds는 Facilitator가 지원하는 네트워크와 scheme을 나열합니다. 실제 호출 시에는 여전히 API가 반환하는 accepts를 기준으로 합니다.
Facilitator /supported 출력:
/supported는 Facilitator가 이러한 네트워크와 scheme에 대한 검증 및 정산 기능을 갖추고 있음을 나타냅니다.- Base와 Solana는 모두
exact를 지원하며,upto는 현재 Base에서만 제공됩니다. - 특정 API가 특정 네트워크를 허용하는지는 여전히 해당 API의 402
accepts를 기준으로 합니다.

