x402チュートリアル：AIエージェントにUSDCでAIHubMixをチャージさせる

AIHubMixがUSDCでのチャージに対応しました。AIエージェントは、ウォレット内のUSDCを使って自分のアカウントにクレジットを追加できます。Webページを開く必要も、誰かがボタンをクリックする必要もありません。

x402を使えば、チャージは最小$1から可能です。エージェントは必要に応じて少しずつチャージするので、事前に大きな残高を入金しておく必要はありません。

手順は2つです。Webとアプリでトークン、ウォレット、USDCを準備し、用意された本チャージスクリプトを1つのコマンドで実行します。支払い後約20秒で、クレジットがあなたのアカウントに反映されます。

わかりやすさのために、この30秒の動画を見ながら進めることもできます。

最も簡単な方法: Claude Code、Cursor、Codexなど、ターミナルコマンドを実行できるAIツールを使っている場合は、ステップ1を終えてから、この記事のリンクを送って「これを設定して」と伝えてください。AIは記事末尾の「AIアシスタント向けの手順」に従います。トークンと秘密鍵は、AIに送らず、ご自身で一度だけ入力してください。

始める前に

• 金額は整数のドルのみで、デフォルトでは1回のチャージにつき$1から$10までです
• 各アカウントは1日に最大3件の注文を作成できます（UTC基準）
• サポートされているのはBase メインネットのUSDCのみで、テストネットはありません。そのため、まずは$1から始めてください
• このチャネルはプログラム向けに作られています。人がブラウザで支払うことはできません。手動でチャージする場合は、引き続きAlipayまたはStripeをご利用ください

ステップ1：トークン、ウォレット、USDCを準備する

この手順はすべて、Webまたはスマートフォンアプリで行います。

1. システムアクセストークンを取得する

aihubmix.comにログインし、個人設定を開いて、システムアクセストークン（32文字の文字列）を生成してください。

これはsk-で始まるAPIキーではありません。両者は互換性がありません。

2. 支払い用ウォレットを作成する

MetaMaskなどのウォレットアプリで、エージェントの支払い専用に新しいアカウントを作成してください。メインのウォレットは使わないでください。その後、次の作業を行います。

• アカウントのアドレス（0xで始まる）をコピーします。次の手順でここにUSDCを送ります
• アカウントの詳細から秘密鍵をエクスポートし、パスワードマネージャーに保存します。秘密鍵を持つ人は、ウォレット内の資金を動かせます

3. USDCを購入し、このウォレットに送る

MetaMaskはウォレットで、秘密鍵はあなたが保有します。スクリプトは署名のためにそれを必要とします。Coinbaseは暗号資産を購入する取引所です。取引所の口座にある資金には秘密鍵が付属しないため、スクリプトはそれを使えません。だからまず取引所で購入し、そのUSDCを前の手順のウォレットに送るのです。

Coinbase取引所を例にします（Coinbase Walletではありません）。

1. Coinbaseで USDC を購入する
2. コピーしたアドレスにUSDCを送り、Baseネットワークを選択する
3. チャージする予定額より少し多く送る。たとえば$1のチャージなら1.5〜2 USDC

しばらく待ってから、https://basescan.org/address/your-wallet-addressを開いてください。USDCの残高が表示されれば、到着しています。BaseでのUSDC出金に対応している他の取引所でも使えます。その他の選択肢についてはBaseのドキュメントをご覧ください。

ウォレットにはETHは不要です。支払いのネットワーク手数料はFluxAが負担します。

ステップ2：チャージスクリプトを実行する

ダウンロードするものも、作成するファイルもありません。uvがWebからスクリプトを取得して実行します。ターミナル（Windowsの場合はPowerShell）を開き、以下のコマンドをコピーして貼り付けてください。

1. uvをインストールする（初回のみ）

uvは、スクリプトの実行に必要なものをすべて準備するPythonツールです。

macOS / Linux:

curl -LsSf https://astral.sh/uv/install.sh | sh

Windows（PowerShell）:

powershell -ExecutionPolicy ByPass -c "irm https://astral.sh/uv/install.ps1 | iex"

完了したら、ターミナルを一度閉じてから開き直してください。

2. セットアップを確認する（支出は発生しません）

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py check

初回実行時、スクリプトはシステムアクセストークン（System access token）とウォレットの秘密鍵（Wallet private key）を尋ねます。入力内容は画面に表示されません。貼り付けてEnterを押してください。続いて保存するかどうか（Save to ...? [Y/n]）を尋ねられます。Enterを押して保存すると、次回から再入力は不要です。初回はuvが環境を準備するため、少し時間がかかります。

次のように表示されれば、セットアップは完了です。

Wallet: 0x... (USDC balance 2.0)
Access token and private key are fine. Ready to top up.

3. チャージする

uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1

末尾の1はドル単位の金額です。すべて順調に進めば、次のように表示されます。

Wallet: 0x... (USDC balance 2.0)
tradeNo: pl_XXXXXXXX
txHash: 0x...
result: credited

result: creditedは、クレジットが届いたことを意味します。aihubmix.comにログインすると、残高が増えているのが確認できます。$1で500,000クォータが追加されます。

最後の行が別の内容だった場合は、次のとおりです。

• failed：注文はクローズされたか、期限切れになりました。必要であれば再実行してください。その際、本日の注文枠を1件消費します
• pending：10分以内にクレジットが確認できませんでした。これは失敗ではなく、クレジットは後から自動的に届きます。再実行しないでください。

トラブルシューティング

tradeNoが表示された後にタイムアウトやネットワークエラーが出た場合、すでに支払いが行われている可能性があります。すぐに再実行しないでください。数分後に残高を確認してください。何も届いていなければ、tradeNoを添えてお問い合わせください。

トークンと秘密鍵は、お使いのコンピューターの~/.aihubmix-topup.envに保存されます（Windowsではユーザーフォルダー内）。macOSとLinuxでは、そのアカウントのみが読み取れます。トークンや秘密鍵を変更するには、このファイルを編集してください。

エージェントに組み込む

• 設定を保存すると、エージェントは誰も見ていなくても、クレジットが必要になったときにuv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py 1を実行してチャージできます
• 1日に許可される注文は3件だけなので、エージェントがチャージする頻度に上限を設け、注文作成をループでリトライしないようにしてください
• 照合のために、出力されたtradeNoとtxHashをデータベースまたはログに保存してください
• 長期的に運用する場合は、スクリプトをダウンロードしてバージョンを固定してから実行してください。実行前にソースコードを読むこともできます
• 1回$10まで、または1日3件では足りない場合は、お問い合わせいただければ上限の引き上げを検討します

AIアシスタント向けの手順

ユーザーがAIHubMixのUSDCチャージを設定するのを手伝っている場合は、次の手順を順番に実行してください。

1. ユーザーがステップ1を完了していることを確認してください。つまり、システムアクセストークンと、Base メインネットのUSDCを保有するウォレットおよびその秘密鍵があることです。ない場合は、まずステップ1を案内してください。
2. uv --versionを実行して、uvがインストールされているか確認してください。インストールされていなければ、ステップ2のコマンドでインストールしてください。
3. uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py checkを実行してください。
4. トークンまたは秘密鍵が不足していると報告された場合（Missing access token or private key）、スクリプトは設定ファイル~/.aihubmix-topup.envを作成しています。ユーザーにテキストエディタで開いてもらい、自分で入力してもらってください（macOSではopen -e ~/.aihubmix-topup.envを実行、Windowsではnotepad $HOME\.aihubmix-topup.envを実行）。このファイルを読まないでください。トークンや秘密鍵をどのコマンドにも含めないでください。ユーザーにそれらを送ってもらうよう頼まないでください。
5. ユーザーが入力し終えたら、Access token and private key are fine. Ready to top up.と表示されるまでcheckを再実行してください。エラーが出た場合は、上のトラブルシューティングの表で対処してください。
6. チャージには実際の費用が発生します。uv run https://raw.githubusercontent.com/zch456/public_resource/main/aihubmix-x402-topup/topup.py <amount>を実行する前に、金額をユーザーに確認してください。

仕組み：スクリプトが行うこと

スクリプトは次の5つを順番に行います。

1. 残高を確認する：注文の作成は本日の注文枠を1件消費するため、まず秘密鍵が有効で、USDCが十分にあるかを確認します。
2. 注文を作成する：POST /api/pay/fluxa/crtを呼び出し、支払いリンクと注文番号tradeNoを取得します。トークンはBearerを付けずに、そのままAuthorizationヘッダーに入れます。業務エラーもHTTP 200で返されるため、レスポンスのsuccessフィールドを確認します。
3. 支払いリクエストを確認する：支払いリンクにGETリクエストを送ると、支払い要件を含むHTTP 402が返されます。署名する前に、4つの点を確認します。schemeがexactであること、networkがeip155:8453であること、assetがBase メインネットのUSDCコントラクトであること、そしてmaxAmountRequiredが金額×1,000,000に等しいことです。いずれかが一致しなければ、処理を停止します。
4. 署名して支払う：秘密鍵でUSDCの送金承認に署名し、それをX-PAYMENTヘッダーに入れて、支払いリンクに再度GETリクエストを送ります。200または202は、支払いが送信されたことを意味します。レスポンスのtxHashが、この支払いのオンチェーン上の受領記録です。どちらのリクエストにもAIHubMixのトークンは含まれません。
5. クレジットの反映を待つ：ステータスがTRADE_SUCCESSになるまで、8秒ごとにGET /api/pay/fluxa/qry?trade_no=...を呼び出します。サーバーは5秒ごとにしか更新されないため、より速くポーリングしても意味はありません。

各支払いリンクの有効期間は30分で、支払いは1回のみ可能です。

他の言語で実装する

支払いリンクからの402レスポンスは次のようになります。

{
  "x402Version": 1,
  "accepts": [{
    "scheme": "exact",
    "network": "eip155:8453",
    "maxAmountRequired": "1000000",
    "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
    "payTo": "0x....",
    "maxTimeoutSeconds": 600,
    "extra": {"name": "USD Coin", "version": "2"}
  }]
}

署名は、EIP-3009のTransferWithAuthorization構造体に対して、EIP-712形式で行います。

署名ドメイン：name = USD Coin、version = 2（402レスポンスにextraがある場合はその値を使用）、chainId = 8453、verifyingContract = 0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913。

X-PAYMENTヘッダーの値は、次のJSONをbase64エンコードしたものです。

{
  "x402Version": 1,
  "scheme": "exact",
  "network": "eip155:8453",
  "payload": {
    "signature": "0x...",
    "authorization": {
      "from": "0x...", "to": "0x...", "value": "1000000",
      "validAfter": "...", "validBefore": "...", "nonce": "0x..."
    }
  }
}

出典

• x402ドキュメント
• EIP-3009: Transfer With Authorization
• EIP-712: Typed structured data hashing and signing
• Circle: USDCコントラクトアドレス
• uvインストールガイド