x402-trinity

**ドロップインの fetch 置き替えです。AI エージェントが自らでものの代金を支払いを可能にする。****厳しい支払い上限付き、ホスト型ウォレットサービス不要、エージェントのコース変更もし。

実行時依存ゼロ。gzip で 7 KB。バイヤー と セーラーが TypeScript に、バイヤーが Python に。

npm install x402-trinity

なぜ

エージェントが有料リソースに直面すると 402 Payment Required が返されます。その処理が他になければ、リクエストは単に失敗します。

x402-trinity はこれにが処理します。チャレンジを読み取り、設定した制限と照合し、署名し、再試行します。すべてローカルで行います — ホスト型ウォレットサービスは不要、サードパーティ API も不要。鍵がプロセス外へ持ち出されることはありません。

ガス代は存在しますが、支払い者はそれを支払いません — EIP-3009 ではファシリテータが送金を行うため、エージェントのウォレットは USDC だけで十分です。

Related MCP server: remit.md MCP Server

買う（エージェントが代金を支払う）

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) });

必須フィールドが2つあるのは、どちらも意図的です。ファシリテータのデフォルトは存在しません。決済は誰かの実際の資金に関わるため、エンドポイントの推測をデフォルトにすることはありません。また、リプレイ防止はプロセスより長生きする必要があります。インメメモリ実装では、再起動のたびに決済済みの支払いをすべて忘れてしまいので、買い手が使用済みの認可を再利用し、再びリソースをただ取りすることができます。よってコンストラクターは、どちらかを暗黙的にするのではなく、例外を投じます。

セラーは秘密鍵を保持せず、資金に触れることもません。価格を提示し、ファシリテータに検証と決済を依頼します。資金は、買い手 → あなたへ、on-chain で直接移動します。

このリリースは Base + USDC のみを対稽竹ています。 その他の EVM チェーンは customChains で利用できます。あなたのアドレスはどのチェーンでも同じです。

機能

他のチェーン

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 Workers の各 isolate（つまり各リクエスト）でリセットされます。それため、メインストットで待てば、全期間の上限が1リクエストの上限に変ります。したがって、メイン統ットには永続型の budgetStore が必要です。代替できるのは明示的な acknowledgeEphemeralBudget: true です:

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

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

秘密鍵はプロセスの中にあります。 それが、ホストされた署名器を置かないための代わりです。制かけなさい：自分が失わても許容できる額だけを保持する専用ウォレットを使う、漏え出た鍵をこのラッパーを通して他人に払えないよう allowPayTo を設定する、エンクレーブ相当の保管が必要なら remoteSign を使う。

タイミング耐性は「強化」であって「証明」ではありません。 秘密スカラーには、ブラインディングに加えて「常に加算と2倍算」を使います。これによりタイミングの打散布は99.6%から12%に減少します（Python: 99.9% → 1.1%）。BigInt の算術は自本的に可変時間です。純 JS の実装でそれを除取るものはありません。

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

MCP は、アシスタントに戦を与えるための仕組みです。ここでは次の3つを公開します:

{
  "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、wranler は dev依存 です。ビルドにのみ使われます。配植されるパッケージは ランタイム依存ゼロ.

ライセンス

MIT. 本ソフトウェアは資金を移動させます — LICENSE の追加の又特記事項を参照し、自日の支払い上限を設定してください。