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, Baseupto및 주문 결제에는 모두 공개적으로 열 수 있는 explorer 주소가 있습니다. - Base
upto의 서명 상한은95215atomic USDC이고 실제 settlement는3atomic 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 응답과 일치하는지 확인하십시오.
