メインコンテンツへスキップ
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 上で paid retry が 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 リトライを手動で処理する必要がないことを意味します。