PAYMENT-SIGNATURE に署名してから、同じリクエストで再試行します。
違いは、注文支払いはアカウントトークンを必要とするプラットフォーム API であるのに対し、x402.acedata.cloud の AI API を直接呼び出す場合は X402 のみを使用でき、API Token は必要ないことです。
注文の準備
Ace Data Cloud コンソールにアクセスし、支払いが必要な注文を選択して、注文 ID を記録します。 まだ注文がない場合は、プランページで支払い待ちの注文を作成できます。注文価格はページ上の表示に従い、X402 402 レスポンス内のamount が最終的な署名の基準となります。
アカウントトークンの作成
注文支払いリクエストにはアカウントトークンが必要です。プラットフォーム Token ページを開き、platform-v1-... 形式の token を作成します。
以降のリクエストでは以下を使用します:
402 のトリガー
まず、PAYMENT-SIGNATURE を含まないリクエストを送信します:
accepts が含まれます:
x402Version は 2、network は CAIP-2 識別子を使用し、金額フィールドは amount です。
10 Credits の注文を作成して 402 をトリガーしたプログラム実行結果:
以下の取引記録は旧ポリシー下の過去の実測サンプルであり、金額とトランザクションハッシュは原文のまま保持しています。新しい X402 注文では支払い方法の割引は適用されません。今回の 402 レスポンスの amount を署名および支払いの基準としてください。
- 注文作成成功後の状態は
Pendingであり、この時点ではまだオンチェーン支払いは行われていません。 - 最初の
pay/リクエストにはPAYMENT-SIGNATUREが含まれていないため、HTTP 402 が返されます。 acceptsは Baseexactと Solanaexactの両方を提示しており、本チュートリアルでは以降 Base を選択します。- 注文作成時の価格は
1.26で、旧 X402 支払い優遇ポリシー期間中に支払われたため、実際の署名および決済金額は1.2USDC、すなわち1200000atomic USDC でした。
resource はサーバー側から返され、署名に参加するフィールドです。クライアント側でその中のプロトコル、パス、または注文 ID を独自に書き換えないでください。
署名して再試行
注文支払いでは、@acedatacloud/x402-client または acedatacloud-x402 の低レベル署名関数を再利用できます。以下は TypeScript の例です:
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イベントは、支払いアドレスがプラットフォームの受取アドレスへ1200000atomic USDC、すなわち1.2USDC を送金したことを示します。
成功レスポンスとレシート
注文の支払いに成功した後、レスポンスボディは注文情報です。プラットフォームはさらに、レスポンスヘッダーPAYMENT-RESPONSE に Base64 エンコードされた settlement response を含めます。デコード後の一般的なフィールドは以下のとおりです:
照合が必要な場合は、注文 ID、支払いウォレットアドレス、
transaction、および注文の最終ステータスを同時に保存することを推奨します。
注意事項
- 注文の支払いにはプラットフォームアカウントトークンが必要であり、X402 ウォレット署名だけでは完了できません。
amountは USDC atomic units を使用し、1200000は1.2USDC を示します。- 受取アドレスや資産アドレスを独自に組み立てず、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 には影響しません。
