exact と upto の 2 種類の scheme を使用しています。これらは異なる課金問題を解決します。
exact
exact は、今回のリクエストの価格が対象 API に到達する前に確定できることを意味します。クライアントが署名する金額が最終的な引き落とし金額です。
適しているケース:
- 固定価格の画像生成;
- 固定価格の動画タスク作成;
- 固定価格の検索またはツール API;
- 注文支払い。
exact は USDC EIP-3009 TransferWithAuthorization を使用します:
/verify 段階で署名と金額を検証し、/settle 段階でこの承認をチェーン上に送信します。
upto
upto は、クライアントが最大上限を承認し、Ace Data Cloud がリクエスト完了後に実際の使用量に基づいて決済することを意味します。実際の引き落とし額は上限を超えることはできません。
適しているケース:
- チャット補完:最終価格は prompt tokens と completion tokens に依存します;
- ストリーミング応答:実際の出力長が終了するまでわかりません;
- 将来の後払い計量 API。
upto は Permit2 PermitWitnessTransferFrom を使用します。クライアントが署名するのは固定送金ではなく、witness を伴う上限承認です:
permitted.amount は上限であり、最終的な引き落とし額とは限りません。Gateway は /record 段階で実際の使用量を amount に変換して Facilitator に渡します。Facilitator は amount <= permitted.amount の決済のみを許可します。
Base upto のプログラム実行結果:
- 402 で返される承認上限は
95215atomic USDC であり、クライアントはこの上限で署名します。 - モデルが実際に応答した後、
3atomic USDC のみが決済され、オンチェーン取引はすでに BaseScan で確認できます。 - この結果は
uptoの重要な違いを示しています:署名金額は上限であり、オンチェーン settlement は上限を下回ることができます。 - 実際の使用量が上限を超える場合、Facilitator は settlement を拒否すべきであり、クライアントはより高い上限で再度承認する必要があります。
upto は現在 Base でのみ提供されています。後払い計量が必要な場合は、Base を使用してください。
Permit2 approve が必要な理由
upto は最終的に x402 proxy により Permit2 を通じて支払いウォレットから USDC を引き出します。初回使用前に、支払いウォレットは Permit2 に一度 ERC-20 allowance を付与する必要があります。
Python CLI:
upto envelope に署名する必要があります。
ゼロ金額決済
upto は実際の金額が 0 のケースをサポートします。たとえば、対象 API が課金可能な使用量を正常に生成しなかった場合、Gateway は amount = "0" を渡すことができます。Facilitator は成功を返しますが、オンチェーン取引は送信しません。
これにより、「リクエストが成功しなかったにもかかわらずオンチェーン料金が引き落とされる」という問題を回避できます。
選択の推奨
どちらを選ぶべきかわからない場合は、まず SDK のデフォルト動作を使用してください;SDK はサーバーが返す一致するネットワークの payment requirement を選択します。
Base upto チェックリスト
統合またはトラブルシューティング時は、以下のパラメータが同一の 402 応答から取得され、クライアント署名時に一貫していることを確認してください:
よくあるエラーと対処方法:

