@acedatacloud/x402-client は 402 Payment Required に遭遇した際に PAYMENT-SIGNATURE リクエストヘッダーへ署名する役割を担います。
ソースコードとパッケージのアドレス:
- SDK リポジトリ:https://github.com/AceDataCloud/SDK
- X402 Client リポジトリ:https://github.com/AceDataCloud/X402Client
- npm SDK:https://www.npmjs.com/package/@acedatacloud/sdk
- npm X402 Client:https://www.npmjs.com/package/@acedatacloud/x402-client
依存関係のインストール
@solana/web3.js が必要です:
@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 を直接渡します:Solana の例
Solana は SPL USDCTransferChecked を使用します。渡す wallet adapter は publicKey と signAndSendTransaction を公開している必要があります。
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 に対して一度だけ承認すればよいです:
upto は公開 API の検証を完了しています:HTTP 402 -> HTTP 200、後払い settlement tx は 0x4b0b836ce1cd1171cdbc37df1637150b024214ec28e7f6f2d09122f15cbfc036 です。完全な出力は課金プランの説明を参照してください。
SDK が行うこと
@acedatacloud/sdk の transport は、402 を受信すると payment handler を一度実行します:
@acedatacloud/x402-client が返す handler は次を行います:
ctx.acceptsから対象ネットワークの payment requirement を選択します。- ネットワークに応じて EVM EIP-712 署名または Solana transfer transaction を構築します。
- envelope を Base64 にシリアライズします。
{ headers: { 'PAYMENT-SIGNATURE': '<base64>' } }を返します。- SDK が元のリクエストボディを使用して自動的にリトライします。

