메인 콘텐츠로 건너뛰기
Ace Data Cloud X402는 현재 exact와 upto 두 가지 scheme를 사용합니다. 이들은 서로 다른 과금 문제를 해결합니다.

exact

exact는 이번 요청이 대상 API에 들어가기 전에 가격을 확정할 수 있음을 의미합니다. 클라이언트가 서명한 금액이 최종 차감 금액입니다. 적합한 경우:
  • 고정 가격 이미지 생성;
  • 고정 가격 비디오 작업 생성;
  • 고정 가격 검색 또는 도구 API;
  • 주문 결제.
EVM exact는 USDC EIP-3009 TransferWithAuthorization을 사용합니다:
Facilitator는 /verify 단계에서 서명과 금액을 검증하고, /settle 단계에서 이 권한 부여를 체인에 제출합니다.

upto

upto는 클라이언트가 최대 한도를 승인하고, Ace Data Cloud가 요청 완료 후 실제 사용량에 따라 정산하며, 실제 차감 금액은 한도를 초과할 수 없음을 의미합니다. 적합한 경우:
  • 채팅 완성: 최종 가격은 prompt tokens 및 completion tokens에 따라 달라집니다;
  • 스트리밍 응답: 실제 출력 길이가 끝난 후에야 알 수 있습니다;
  • 미래의 사후 계량 API.
upto는 Permit2 PermitWitnessTransferFrom을 사용합니다. 클라이언트가 서명하는 것은 고정 이체가 아니라 witness가 포함된 한도 승인입니다:
permitted.amount는 한도이며, 반드시 최종 차감 금액인 것은 아닙니다. Gateway는 /record 단계에서 실제 사용량을 amount로 변환하여 Facilitator에 전달합니다. Facilitator는 amount <= permitted.amount인 경우에만 정산을 허용합니다. Base upto의 프로그램 실행 결과:
설명:
  • 402에서 반환된 승인 한도는 95215 atomic USDC이며, 클라이언트는 이 한도에 따라 서명합니다.
  • 모델이 실제로 응답한 후 3 atomic USDC만 정산되었으며, 온체인 거래는 이미 BaseScan에서 조회할 수 있습니다.
  • 이 결과는 upto의 핵심 차이를 보여 줍니다: 서명 금액은 한도이며, 온체인 settlement는 한도보다 작을 수 있습니다.
  • 실제 사용량이 한도를 초과하면 Facilitator는 settlement를 거부해야 하며, 클라이언트는 더 높은 한도로 다시 승인해야 합니다.
upto는 현재 Base에서만 제공됩니다. 사후 계량이 필요한 경우 Base를 사용하세요.

Permit2 approve가 필요한 이유

upto는 최종적으로 x402 proxy가 Permit2를 통해 결제 지갑에서 USDC를 가져옵니다. 처음 사용하기 전에 결제 지갑은 Permit2에 ERC-20 allowance를 한 번 부여해야 합니다. Python CLI:
프로그램 방식:
승인이 완료된 후에도 매 요청마다 새로운 upto envelope에 서명해야 합니다. nonce, deadline, witness 및 금액 한도가 모두 다르기 때문입니다.

0 금액 정산

upto는 실제 금액이 0인 경우를 지원합니다. 예를 들어 대상 API가 성공적으로 과금 가능한 사용량을 생성하지 못한 경우, Gateway는 amount = "0"을 전달할 수 있습니다. Facilitator는 성공을 반환하지만 온체인 거래를 발생시키지 않습니다. 이를 통해 “요청이 성공하지 않았는데도 여전히 온체인 비용이 차감되는” 문제를 피할 수 있습니다.

선택 권장 사항

어느 것을 선택해야 할지 확실하지 않다면 먼저 SDK 기본 동작을 사용하세요. SDK는 서버가 반환한 일치하는 네트워크 payment requirement를 선택합니다.

Base upto 체크리스트

연동 또는 문제 해결 시, 다음 매개변수가 동일한 402 응답에서 왔는지 확인하고 클라이언트 서명 시 일관되게 유지하세요: 일반적인 오류 및 처리 방법: