메인 콘텐츠로 건너뛰기
API 요청에 직접 결제하는 것 외에도, Ace Data Cloud는 X402로 콘솔 주문을 결제하는 것도 지원합니다. 주문 결제와 API 호출의 핵심 프로토콜은 동일합니다: 첫 번째 요청은 402를 반환하고, 클라이언트가 PAYMENT-SIGNATURE에 서명한 다음 동일한 요청으로 재시도합니다. 차이점은 주문 결제가 플랫폼 API에 해당하므로 계정 토큰이 필요하다는 것입니다. 반면 x402.acedata.cloud의 AI API를 직접 호출하는 경우 X402만 사용하면 되며 API Token은 필요하지 않습니다.

주문 준비

Ace Data Cloud 콘솔에 들어가 결제해야 하는 주문을 선택하고 주문 ID를 기록합니다. 아직 주문이 없다면 요금제 페이지에서 결제 대기 주문을 생성할 수 있습니다. 주문 가격은 페이지에 표시된 내용을 기준으로 하며, X402 402 응답의 amount는 최종 서명 기준입니다.

계정 토큰 생성

주문 결제 요청에는 계정 토큰이 필요합니다. 플랫폼 Token 페이지를 열고 platform-v1-... 형식의 token을 생성합니다. 이후 요청에서는 다음을 사용합니다:
계정 토큰은 일반 API Token과 다릅니다. 일반 API Token은 API 크레딧을 사용하는 데 쓰이며, 계정 토큰은 주문 결제와 같이 계정을 대신하여 플랫폼 리소스를 작업하는 데 쓰입니다.

402 트리거

먼저 PAYMENT-SIGNATURE 없이 한 번 요청을 전송합니다:
상태 402가 반환되며, 응답에는 accepts가 포함됩니다:
주문 결제는 공식 x402 v2를 사용합니다: x402Version은 2이고, network는 CAIP-2 식별자를 사용하며, 금액 필드는 amount입니다. 10 Credits 주문을 생성하고 402를 트리거한 프로그램 실행 결과:
다음 거래 기록은 이전 정책 하의 과거 실측 샘플이며, 금액과 거래 해시는 원래대로 유지됩니다. 새 X402 주문에는 더 이상 결제 방식 할인이 적용되지 않습니다. 이번 402 응답의 amount를 서명 및 결제 기준으로 사용하세요.
결과 설명:
  • 주문 생성에 성공한 후 상태는 Pending이며, 이때 아직 온체인 결제가 이루어지지 않았습니다.
  • 첫 번째 pay/ 요청에는 PAYMENT-SIGNATURE가 포함되지 않았으므로 HTTP 402가 반환됩니다.
  • accepts는 Base exact와 Solana exact를 동시에 제공하며, 이 튜토리얼에서는 이후 Base를 선택합니다.
  • 주문 생성 시 가격은 1.26이었고, 이전 X402 결제 할인 정책 기간에 결제되어 실제 서명 및 정산 금액은 1.2 USDC, 즉 1200000 atomic USDC였습니다.
여기서 resource는 서버가 반환하고 서명에 참여하는 필드이므로, 클라이언트는 그 안의 프로토콜, 경로 또는 주문 ID를 임의로 변경해서는 안 됩니다.

서명 및 재시도

주문 결제는 @acedatacloud/x402-client 또는 acedatacloud-x402의 저수준 서명 함수를 재사용할 수 있습니다. 다음은 TypeScript 예시입니다:
동일한 주문에 Base exact로 서명하고 재시도한 후의 프로그램 실행 결과:
온체인 확인 결과:
결과 설명:
  • status 200은 플랫폼 주문 결제 인터페이스가 이번 PAYMENT-SIGNATURE를 수락했음을 나타냅니다.
  • has_x_payment_response True는 응답 헤더에 Base64로 인코딩된 PAYMENT-RESPONSE 영수증이 포함되어 있음을 나타냅니다.
  • settle_header.success=True 및 network=base는 Facilitator가 Base settlement를 완료했음을 나타냅니다.
  • 주문의 최종 상태는 Finished이고, pay_way는 X402이며, pay_id에는 온체인 거래 해시가 기록됩니다.
  • BaseScan의 Transfer 이벤트는 결제 주소가 플랫폼 수금 주소로 1200000 atomic USDC, 즉 1.2 USDC를 전송했음을 보여줍니다.

성공 응답 및 영수증

주문 결제가 성공한 후 응답 본문은 주문 정보입니다. 플랫폼은 또한 응답 헤더 PAYMENT-RESPONSE에 Base64로 인코딩된 settlement response를 포함하며, 디코딩 후 일반적인 필드는 다음과 같습니다: 대사가 필요한 경우 주문 ID, 결제 지갑 주소, transaction 및 주문 최종 상태를 함께 저장하는 것이 좋습니다.

주의 사항

  • 주문 결제에는 플랫폼 계정 토큰이 필요하며, X402 지갑 서명만으로 완료할 수 없습니다.
  • amount는 USDC atomic units를 사용하며, 1200000은 1.2 USDC를 나타냅니다.
  • 수금 주소나 자산 주소를 직접 조합하지 말고, 402 응답의 accepts를 기준으로 하십시오.
  • 동일한 PAYMENT-SIGNATURE가 반복 제출되면 Facilitator는 nonce를 기준으로 재생 공격 방지를 수행합니다.

결제 실패 응답

PAYMENT-SIGNATURE를 포함하지 않은 첫 번째 HTTP 402는 정상적인 결제 챌린지이며, 결제 실패를 의미하지 않습니다. 서명 후 검증 또는 결제가 실패한 경우에도 호환성을 위한 대체 수단으로 표준 문자열 error가 유지되며, 안정적인 오류 구조는 extensions.acedatacloud.paymentError에서 반환됩니다:
클라이언트는 우선 code에 따라 현지화해야 하며, 알 수 없는 code는 일반적인 결제 실패로 대체해야 합니다. charged는 3상태 필드입니다. 결제 전에 명확히 거부된 경우에만 false가 반환됩니다. 필드가 없으면 청구 상태를 알 수 없음을 의미하며, “청구되지 않음”으로 해석할 수 없습니다. 현재 주문은 Failed에 진입한 후 원래 주문으로 재시도할 수 없으므로, 지갑 문제를 수정한 후 새 주문을 생성하십시오. 주문 목록 및 상세 정보의 metadata.x402.last_error와 metadata.x402.errors는 동일한 code, stage, retryable, charged 및 params 그룹을 유지합니다. 공개 설명 텍스트는 reason에 저장되고, 발생 시간은 timestamp에 저장됩니다. 예를 들어 insufficient_token_balance는 선택한 네트워크에서 USDC 잔액이 부족함을 의미하고, invalid_signature는 결제 서명이 유효하지 않음을 의미합니다. 주문을 다시 읽어도 이들은 일반적인 payment_failed로 변경되지 않습니다. 전체 PAYMENT-SIGNATURE, 지갑 서명, 승인 payload, Facilitator 원본 진단 정보 또는 RPC 응답을 기록하거나 제출하지 마십시오. 고객 지원 조사에는 주문 ID와 공개 오류 code만 필요합니다.

Base 및 Solana 결제의 ACE 재매입 소각

재매입 정책을 활성화한 후, 조건을 충족하는 Base 메인넷 Circle USDC 및 Solana 메인넷 USDC의 실제 수령 금액 중 3%는 ACE를 구매하고 소각하는 데 사용되며, 결제 지갑에 추가로 청구되지 않습니다. 충전 시 한 번 적립되며, 이후 이 Credits를 사용하여 API를 호출할 때는 중복 적립되지 않습니다. 과거 할인 주문 및 이전 정책 주문에는 자동으로 소급 적립되지 않습니다. Base 결제는 Base 체인에 결제 영수증을 유지하고, ACE 구매 및 소각은 Solana에서 비동기적으로 실행됩니다. 조건을 충족하는 결제는 실제 수령 금액을 기준으로 정확히 3%가 적립되며, 단일 건 또는 일일 재매입 금액에 대한 고정 상한은 없습니다. 사용 가능한 자금, 시장 호가 및 온체인 확인은 여전히 완료 시간에 영향을 미칠 수 있습니다. 주문 상세의 ace_burn 객체는 settlement_network, settlement_transaction 및 execution_network를 제공하며, 완료 후 swap_signature와 burn_signature를 제공합니다. Pending 또는 Processing은 소각되었음을 의미하지 않습니다. Completed만이 최종 온체인 증명이 대조되었음을 나타냅니다. Base 결제가 아직 최종 확인에 도달하지 않은 경우 재매입은 확인을 기다리지만, 이미 입금된 Credits에는 영향을 주지 않습니다.