メインコンテンツへスキップ
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 は三値フィールドです。決済前に明確に拒否された場合にのみ 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% が計上され、固定の1回あたりまたは1日あたりの買い戻し金額上限はありません。利用可能な資金、市場価格、オンチェーン確認は、完了時間に影響する可能性があります。注文詳細の ace_burn オブジェクトは settlement_network、settlement_transaction、および execution_network を提供し、完了後には swap_signature と burn_signature を提供します。Pending または Processing は焼却済みを意味しません。最終的なオンチェーン証明が照合されたことを示すのは Completed のみです。Base 支払いがまだ最終確認に達していない場合、買い戻しは確認を待機しますが、すでに入金された Credits には影響しません。