x402 Trinity

x402-trinity

AI エージェントが単独で支払いを行える、ドロップインの fetch 置き換えです。厳格な支出上限を設定でき、ホスト型ウォレットサービスは不要で、エージェント側のコード変更も必要ありません。

ランタイム依存関係はゼロです。gzip 圧縮で 7 KB です。TypeScript では購入側と販売側、Python では購入側に対応しています。

npm install x402-trinity

コピー＆ペーストでセットアップ

コーディングエージェント向けの、すぐに使えるブリーフです。貼り付けると、インストール、ウォレット、支出上限、価格確認、購入まで行います。あとは何を買うか、いくらまで支払ってよいかを伝えるだけです。

→ Standard Purchase Harness

有料 API、データセット、ファイル、他のエージェントのサービスなど、HTTP 402 を返すものなら何でも購入できます。

他のセットアップや、製品を販売して収益を得たり、マーケットプレイスから購入したりできるマーケットプレイスについては、x402trinity.com をご覧ください。

その理由

エージェントが有料リソースにアクセスすると、402 Payment Required が返されます。これを処理するものがなければ、リクエストは失敗します。

x402-trinity がその処理を担います。チャレンジを読み取り、設定した上限に照らして確認し、署名して再試行します。すべてローカルで行われます。ホスト型ウォレットサービスも、サードパーティ API も不要で、キーがプロセスの外に出ることもありません。

ガス代は発生しますが、支払うのは購入者ではありません。EIP-3009 ではファシリテーターが送金を実行するため、エージェントのウォレットに必要なのは USDC だけです。

---

購入（エージェントが支払います）

import { createX402Fetch } from 'x402-trinity';

const x402Fetch = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,   // never hardcode
  policy: {
    maxAmountPerRequest: '5000',              // 0.005 USDC max per call  (REQUIRED)
    totalBudget: '1000000',                   // 1.00 USDC lifetime       (REQUIRED)
    allowHosts: ['api.example.com'],
    allowPayTo: ['0x...'],
  },
});

const r = await x402Fetch('https://api.example.com/data');   // 402 handled, returns 200

または、グローバルをパッチして、変更していないコードでも自動的に支払えるようにします。

import { installX402 } from 'x402-trinity';
const uninstall = installX402(cfg);   // globalThis.fetch now pays 402s

資金を入金する前に、支払いに使うウォレットを確認してください。

X402_PRIVATE_KEY=0x... npx x402-trinity-whoami

アドレスと、各チェーンでの残高が表示されます。**キーは決して表示されません。**意図したウォレットのアドレスと異なる場合は、何も送金せずに中止してください。

販売（リソースに料金を設定して、支払いを受け取る）

import { createX402Seller } from 'x402-trinity/seller';
import { createFileNonceStore } from 'x402-trinity/budget-file';

const seller = createX402Seller({
  payTo: '0xYourWallet',      // 100% of every payment lands here
  price: '10000',             // 0.01 USDC, atomic units
  network: 'base',
  facilitator: 'https://your-facilitator.example',   // REQUIRED — no default exists
  nonceStore: createFileNonceStore('./.x402-nonces.json'),  // REQUIRED — see below
});

// in any fetch-style handler:
const gate = await seller.guard(request);
if (gate.response) return gate.response;          // unpaid or refused — hand back the 402
return new Response(yourData, { headers: seller.receiptHeader(gate.settlement) });

どちらの必須フィールドにも明確な理由があります。決済は実際のお金に関わるため、デフォルトのファシリテーターはなく、エンドポイントを推測してデフォルトにすることもありません。また、リプレイガードはプロセス終了後も保持される必要があります。メモリ内だけで管理すると、再起動時に決済済みの支払いがすべて忘れられるため、購入者が使用済みの承認を再提示して、無料でリソースを受け取れてしまいます。どちらも暗黙の設定にしないよう、コンストラクターは例外をスローします。

販売側が秘密鍵を保持したり、資金に触れたりすることはありません。価格を提示し、ファシリテーターに検証と決済を依頼します。資金はオンチェーンで購入者からお客様へ直接送金されます。

**このリリースでは Base と USDC のみを提供します。**他の EVM チェーンは customChains で利用できます。お客様のアドレスはすべてのチェーンで同じです。

---

機能

プロトコル	x402 v1 と v2 に対応し、レスポンスごとに検出します。不明なバージョンや MPP チャレンジは、推測せず明確な理由とともに拒否します
チェーン	Base メインネットと USDC をデフォルトで提供します。他の EVM チェーンは customChains で利用できます
ネットワーク	短縮名と CAIP-2（eip155:8453）に対応します
カストディ	privateKey、加算的な shards、または remoteSign（HSM/MPC）から選択できます。これはアーキテクチャ上の制約ではなく、お客様の選択です
速度	ウォーム時 3.2 µs／コールド時 1.0 ms（TypeScript）、1.2 µs／1.7 ms（Python）
ランタイム	Cloudflare Workers を自動検出して戦略を切り替えます。Node、Bun、Deno にも対応します
安全性	必須の上限、許可リスト、二重支払いを防ぐ照合、タイミング攻撃を考慮した署名

別のチェーンを使う

デフォルトは Base です。署名処理はチェーンに依存しないため、リハーサル用のテストネットも含め、必要なチェーンを追加できます。

const fetch2 = createX402Fetch({
  privateKey: process.env.X402_PRIVATE_KEY,
  maxAmountPerRequest: '10000',
  totalBudget: '100000',
  customChains: {
    'base-sepolia': { id: 84532, asset: '0x036cbd53842c5426634e7929541ec2318f3dcf7e', name: 'USDC', version: '2' },
  },
});

エントリーを使う前に、デプロイ済みコントラクトと照合してください。DOMAIN_SEPARATOR() を呼び出し、その値がこのライブラリの計算結果と一致することを確認します。name または version が誤っていると、一見有効な署名が生成されますが、コントラクトに拒否されます。

意図的に対応していないこと

チェーンへのブロードキャスト · 資金の保有 · ガス代や RPC の必要 · 支払いから手数料を取ること（EIP-3009 では受取人を 1 人しか指定できないため、構造上不可能） · ホスト型署名サービスの必須化 · 上限なしの支払い · 対応していないプロトコルの推測

---

安全性 — 実際のお金を使う前にお読みください

上限の設定は必須です。 maxAmountPerRequest と totalBudget にデフォルト値はありません。これらを指定しないと、ラッパーの構築は拒否されます。上限のない自動支払い機能は、サーバーの実行者が制御する資金流出につながります。

totalBudget だけではインスタンスごとの上限です。 これはメモリ内のカウンターで、再起動時、新しいクライアントの作成時、Cloudflare Worker の分離環境ごとにリセットされます。分離環境はリクエストごとに作成されます。メインネットでは、これにより生涯上限がリクエストごとの上限になってしまいます。そのため、メインネットでは永続的な budgetStore、または acknowledgeEphemeralBudget: true の明示的な指定が必要です。

import { createFileBudgetStore } from 'x402-trinity/budget-file';

createX402Fetch({
  ...,
  budgetStore: createFileBudgetStore('./.x402-budget.json'),   // survives restarts
});

秘密鍵はプロセス内にあります。 ホスト型の署名サービスを使わない代わりに、秘密鍵はプロセス内に保持されます。次の方法でリスクを制限してください。失っても許容できる金額だけを保有する専用ウォレットを使い、流出した秘密鍵がこのラッパー経由で知らない相手に支払えないよう allowPayTo を設定し、エンクレーブ級の鍵管理が必要な場合は remoteSign を使ってください。

タイミング攻撃への対策は、対策であって証明ではありません。 秘密スカラーにはブラインディングと、加算・倍加を常に行う方式を用いており、タイミングのばらつきは 99.6％ から 12％ に低減しています（Python では 99.9％ から 1.1％）。BigInt 演算自体が可変時間であるため、純粋な JavaScript の実装でそれを完全に取り除くことはできません。

---

MCP サーバー — エージェントにウォレットを提供する

アシスタントがツールを利用する仕組みが MCP です。ここでは次の 3 つを公開します。

ツール
check_price	リソースの価格を確認します。支払いは発生しません
pay_and_fetch	リソースを取得し、上限内であれば支払います
wallet_status	アドレス、残高、支出額、残額を確認します

{
  "mcpServers": {
    "x402-trinity": {
      "command": "npx",
      "args": ["-y", "x402-trinity-mcp"],
      "env": {
        "X402_PRIVATE_KEY": "0x...",
        "X402_MAX_PER_REQUEST": "50000",
        "X402_TOTAL_BUDGET": "1000000",
        "X402_BUDGET_FILE": "./.x402-budget.json",
        "X402_ALLOW_HOSTS": "api.example.com",
        "X402_NETWORKS": "base"
      }
    }
  }
}

これらをいつ実行するかはモデルが決定します。 予算についてモデルに判断を委ねることはできません。また、ペイウォールのあるページは、どんな価格でも提示できます。そのため、モデルが設定できるパラメーターに上限を含めることはできません。上限は環境から渡され、X402_PRIVATE_KEY、X402_MAX_PER_REQUEST、X402_TOTAL_BUDGET が設定されていない場合、サーバーは起動を拒否します。

X402_BUDGET_FILE も設定してください。設定しないと、生涯上限は再起動のたびにリセットされます。X402_ALLOW_HOSTS を設定すれば、チャレンジがどれほどもっともらしく見えても、それ以外への支払いはできません。失っても許容できる金額だけを保有するウォレットを使ってください。

---

Python

同じプロトコルを標準ライブラリのみで実装しています。購入者専用です。リソースに課金する場合は TypeScript の売り手側実装を使ってください。長時間稼働するプロセスを想定しています。オンボディエージェント、ロボットのコントローラー、収集スクリプトなどが対象です。

from x402_trinity import X402Client, Policy

client = X402Client(
    private_key=os.environ["X402_PRIVATE_KEY"],
    policy=Policy(max_amount_per_request=5000, total_budget=1_000_000,
                  allow_hosts=["api.example.com"]),
)
body = client.urlopen("https://api.example.com/data").read()

デコレーターとして使うこともできるため、支払いに対応していないコードでもそのまま動作します。

from x402_trinity import x402_telemetry

@x402_telemetry(private_key=KEY, policy=Policy(...))
def harvest():
    return urllib.request.urlopen("https://sensor.local/v1/lidar").read()

ウォーム状態での処理時間は 1.1 µs です。長時間稼働するコントローラーは、最初の支払い後にウォーム状態になります。

---

開発

npm install
npm run build        # dist/*.js + *.min.js + *.d.ts

esbuild、typescript、wrangler は、ビルドにのみ使う開発依存関係です。配布パッケージには実行時依存関係が一切ありません。

ライセンス

Business Source License 1.1。ソースコードは閲覧、変更、非商用利用が可能です。第三者に機能を提供するホスト型またはマネージドサービスとしての提供を除き、本番環境での使用も許可されています。2029-08-25 に MIT ライセンスへ移行します。LICENSE をご覧ください。

このソフトウェアは資金を動かします。追加の注意事項を確認し、支出上限を設定してください。

利便性手数料：取引ごとに 0.1％、100 件ごとに 1 セント。