메인 콘텐츠로 건너뛰기
TypeScript는 Ace Data Cloud X402를 연동하는 가장 권장되는 방법 중 하나입니다. 공식 SDK는 일반 API 호출, 작업 폴링, 오류 처리 및 자동 재시도를 담당하며, @acedatacloud/x402-client는 402 Payment Required를 만났을 때 PAYMENT-SIGNATURE 요청 헤더에 서명하는 역할을 담당합니다. 소스 코드 및 패키지 주소:

의존성 설치

Base를 사용하는 경우 EVM 서명 기능이 필요합니다:
Solana를 사용하는 경우 Solana wallet adapter 또는 @solana/web3.js가 필요합니다:
깨끗한 npm 프로젝트의 설치 및 가져오기 검사 출력:
결과 설명:
  • @acedatacloud/sdk와 @acedatacloud/x402-client는 모두 npm에서 설치하고 Node.js로 가져올 수 있습니다.
  • ethers는 EVM typed data 서명에 사용되며, @solana/web3.js는 Solana transaction 구성에 사용됩니다.

Base 예시

브라우저에서는 window.ethereum을 직접 사용할 수 있습니다. Node.js에서는 ethers.Wallet로 EIP-1193 스타일 provider를 한 겹 감쌀 수 있습니다.

브라우저 지갑 예시

프런트엔드 애플리케이션에서 MetaMask, Coinbase Wallet 또는 WalletConnect를 사용할 때는 일반적으로 EIP-1193 provider를 직접 전달합니다:
브라우저 지갑은 서명 확인을 표시합니다. 사용자가 서명하는 것은 임의의 메시지가 아니라 API가 반환한 결제 요구 사항입니다. 수신 주소, USDC 계약, 금액, 유효 기간 및 nonce가 모두 서명에 포함됩니다.

Solana 예시

Solana는 SPL USDC TransferChecked를 사용합니다. 전달되는 wallet adapter는 publicKey와 signAndSendTransaction을 노출해야 합니다.
Solana 경로는 현재 exact만 지원하고 upto는 지원하지 않습니다. API가 여러 accepts를 반환하면 handler는 network = 'solana'인 항목을 선택합니다. Solana 경로는 동일한 공개 API에서 유료 재시도가 HTTP 200 및 ADC_SOLANA_E2E_OK를 반환할 수 있음이 검증되었습니다. 공개 RPC 조회는 속도 제한이 있을 수 있으므로, 이 문서에는 Solana tx hash를 작성하지 않습니다. 온체인 대사가 필요한 경우 자체 Solana RPC 또는 콘솔 기록 확인을 사용하십시오.

exact 또는 upto 선택

현재 TypeScript handler는 서버가 반환한 첫 번째 일치 네트워크의 payment requirement를 선택합니다. Ace Data Cloud의 API는 일반적으로 동일한 네트워크의 exact를 upto 앞에 배치하므로, 후불 계량을 명확히 사용하려면 preferScheme: 'upto'를 전달해야 합니다. 예시:
서버 측에서 해당 네트워크의 upto requirement를 반환하지 않으면 handler는 자동으로 해당 네트워크에서 사용 가능한 첫 번째 requirement로 폴백하며, 일반적으로 exact입니다. upto는 Permit2를 한 번에 승인해야 합니다. upto는 현재 Base에서만 제공되므로, Base USDC에 대해 한 번만 승인하면 됩니다:
Base upto는 공개 API 검증을 완료했습니다: HTTP 402 -> HTTP 200, 후불 settlement tx는 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036입니다. 전체 출력은 과금 방식 설명을 참조하십시오.

SDK가 수행하는 작업

@acedatacloud/sdk의 transport는 402를 수신하면 payment handler를 한 번 실행합니다:
@acedatacloud/x402-client가 반환하는 handler는 다음을 수행합니다:
  1. ctx.accepts에서 대상 네트워크의 payment requirement를 선택합니다.
  2. 네트워크에 따라 EVM EIP-712 서명 또는 Solana transfer transaction을 구성합니다.
  3. envelope를 Base64로 직렬화합니다.
  4. { headers: { 'PAYMENT-SIGNATURE': '<base64>' } }를 반환합니다.
  5. SDK가 원래 요청 본문으로 자동 재시도합니다.
이는 비즈니스 코드가 일반 SDK 호출처럼 작성되기만 하면 되며, 402 재시도를 수동으로 처리할 필요가 없음을 의미합니다.