The agent harness performance optimization system. Skills, instincts, memory, security, and research-first development for Claude Code, Codex, Opencode, Cursor and beyond.
fix(skills): enforce budget against the server's challenge, refresh to 2.22.0
Notorious D.E.Vb78ea7293505
diff --git a/docs/ja-JP/skills/agent-payment-x402/SKILL.md b/docs/ja-JP/skills/agent-payment-x402/SKILL.mdindex 902dbd5bd..ea069053d 100644--- a/docs/ja-JP/skills/agent-payment-x402/SKILL.md+++ b/docs/ja-JP/skills/agent-payment-x402/SKILL.md@@ -32,7 +32,7 @@ origin: community- `agentwallet-sdk`: 本番使用前に現在のネットワークカバレッジをパッケージドキュメントで確認。Base Sepolia が最も安全な開発デフォルト;Base メインネットがオリジナルスキルで説明されている本番パス。- OKX Payments / X Layer: 現在のセラードキュメントは X Layer(`eip155:196`)と USDT0 決済を対象。決済パッケージとファシリテーターの動作が迅速に変わる可能性があるため、本番コードを生成する前に現在の SDK ドキュメントを取得すること。-- アップストリーム x402 パッケージ: 設計上マルチネットワーク — 1 つのルートで Base と Solana を同時に提示し、買い手に選ばせることができる。パッケージのデフォルトは `x402.org` ファシリテーターで、テストネット専用(Base Sepolia `eip155:84532`、Solana デブネット `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`、加えて Stellar、Aptos、Hedera、XRPL の各テストネット)であり、メインネットルート向けではない。本番はアップストリームドキュメントのファシリテーターリストから選ぶ — PayAI ファシリテーターは Solana メインネット(`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)ほか複数ネットワークで API キー不要の妥当なデフォルト;CDP ファシリテーターは全トランザクションに KYT/OFAC スクリーニングを行う Coinbase ホスト型。本番前にここにハードコードするのではなく、各ファシリテーターの `/supported` エンドポイントでライブカバレッジを確認すること。+- アップストリーム x402 パッケージ: 設計上マルチネットワーク — 1 つのルートで Base と Solana を同時に提示し、買い手に選ばせることができる。パッケージのデフォルトは `x402.org` ファシリテーターで、テストネット専用(Base Sepolia `eip155:84532`、Solana デブネット `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`、加えて Stellar、Aptos、Hedera、XRPL の各テストネット)であり、メインネットルート向けではない。メインネット(Solana は `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)では、自己ファシリテートするか、自前のファシリテーターを運用するか、アップストリームのファシリテーターリストからホスト型を選ぶ — オプション C のファシリテーター比較を参照。本番前にここにハードコードするのではなく、ファシリテーターの `/supported` エンドポイントでライブカバレッジを確認すること。## 仕組み@@ -109,8 +109,8 @@ X Layer x402、マルチパーティ決済(MPP)、セッション決済、1. 古いドキュメントのスニペットをコピーするのではなく、メンテナンスされている [`examples/typescript/clients`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/clients)(fetch、axios、MCP)の例から始める。2. オプション B が OKX フローに要求するのとまったく同様に、最初の有料リクエストの署名または送信の前に明示的なユーザー確認を求める。汎用ツール呼び出しの背後に決済実行を隠さない。-3. パッケージバージョンを固定する(例:`@x402/[email protected]`);アップストリームの全パッケージはロックステップでバージョニングされる。-4. すべての有料呼び出しを、呼び出しの直前にバジェットポリシーでフェイルクローズドにゲートする — クライアント構築時に一度だけではない。+3. パッケージバージョンを固定する(例:`@x402/[email protected]`);アップストリームの全パッケージはロックステップでバージョニングされる。+4. バジェットはクライアントに登録した `PaymentPolicy` で強制し、毎回サーバーの実際のチャレンジに対して検査が走るようにする。自分で渡した数値と突き合わせるバジェットは何も証明しない — 金額・アセット・ネットワークはすべてサーバー由来なので、署名が生成される前に 3 つとも検証すること。```typescriptimport { x402Client, wrapFetchWithPayment } from "@x402/fetch";@@ -120,45 +120,76 @@ import { privateKeyToAccount } from "viem/accounts";import { createKeyPairSignerFromBytes } from "@solana/kit";import { base58 } from "@scure/base";-// 署名者のキーはオーケストレーターの env に属する — ハードコードせず、エージェントが書き込めないようにする。+// Signer keys belong to the ORCHESTRATOR's env — never hardcoded, never agent-writable.const evmKey = process.env.EVM_PRIVATE_KEY as `0x${string}`;const svmKey = process.env.SVM_PRIVATE_KEY;if (!evmKey || !svmKey) {throw new Error("Signer keys are not set — refusing to start payment client");}-// 1 つのクライアントで両方のネットワークファミリーに対応:買い手は 402 が提示するチェーンで支払う。+// One client, both network families: the buyer pays whichever chain the 402 offers.const client = new x402Client();client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(evmKey)));client.register("solana:*", new ExactSvmScheme(await createKeyPairSignerFromBytes(base58.decode(svmKey))));-const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// 最小限のフェイルクローズドゲート。バジェット追跡を備えた完全な MCP バックの-// バージョンは、下の Examples セクションの preToolCheck を再利用する。-const ALLOWED_HOSTS = new Set(["api.example.com"]);-let sessionSpend = 0;-function assertPaymentAllowed(url: string, maxCost: number, sessionCap = 5.0): void {- if (!ALLOWED_HOSTS.has(new URL(url).host)) throw new Error("Host not allowlisted — blocked");- if (!Number.isFinite(maxCost) || maxCost < 0) throw new Error("Invalid cost — blocked");- if (sessionSpend + maxCost > sessionCap) throw new Error("Session budget exceeded — blocked");- sessionSpend += maxCost;-}+// A PaymentPolicy filters the SERVER's payment requirements before any+// signature is created. Returning an empty array means "nothing here is+// acceptable" and the client refuses to pay rather than falling back.+const ALLOWED_NETWORKS = new Set([+ "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", // Solana mainnet+ "eip155:8453", // Base+]);+const MAX_AMOUNT = 10_000n; // atomic units — 6-decimal USDC, so $0.01++// EVM addresses are case-insensitive, so compare them lowercased. Solana+// addresses are base58 and ARE case-sensitive — never lowercase those, or a+// different account could slip through.+const normalizeAsset = (a: string) => (a.startsWith("0x") ? a.toLowerCase() : a);+const ALLOWED_ASSETS = new Set(+ [+ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC, Solana mainnet+ "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC, Base+ ].map(normalizeAsset),+);++client.registerPolicy((_x402Version, requirements) =>+ requirements.filter(r => {+ if (!ALLOWED_NETWORKS.has(r.network)) return false; // wrong chain+ if (!ALLOWED_ASSETS.has(normalizeAsset(r.asset))) return false; // wrong token+ try {+ const amount = BigInt(r.amount);+ return amount >= 0n && amount <= MAX_AMOUNT; // over budget / negative+ } catch {+ return false; // unparseable amount+ }+ }),+);++const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// すべての有料呼び出しの直前にゲートする — 構築時に一度だけチェックされたラップ-// クライアントは、以降のすべての呼び出しを無計量のままにしてしまう。-assertPaymentAllowed("https://api.example.com/data", 0.01);const res = await fetchWithPayment("https://api.example.com/data", { method: "GET" });```-ラップされたクライアントは、`network` が登録済みスキームに一致するチャレンジのみに支払います。署名前にチャレンジの `asset` も検証すること:Solana では USDC はメインネットが `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`、デブネットが `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`。不一致はフェイルクローズドとして扱う:署名せず、リトライしない。exact-SVM スキームではファシリテーターがトランザクション手数料支払者となるため、買い手のウォレットは USDC のみを保有すればよい — ガス用の SOL は不要。+ポリシーを登録すると、予算超過の金額、想定外のトークン、未登録のチェーンはすべてフェイルクローズドになる — 候補がすべて除外されるため、`createPaymentPayload` は署名せずに例外を投げる。デブネット USDC は `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`;開発時のみ `ALLOWED_ASSETS` に追加すること。ポリシーは敵対的にテストする — `5000000` アトミック単位を要求するチャレンジ、別のミントを提示するチャレンジ、登録していないチェーンのチャレンジを与え、いずれも署名が生成されないことを確認する。exact-SVM スキームではファシリテーターがトランザクション手数料支払者となるため、買い手のウォレットは USDC のみを保有すればよい — ガス用の SOL は不要。++**ファシリテーターの選択。** ファシリテーターはリソースサーバーに代わって検証と決済を行うため、これは買い手ではなくリソースサーバーの判断である。委ねる信頼が小さい順に:++| 選択肢 | 適する場面 |+|--------|--------------|+| [インプロセスで自己ファシリテート](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation) | 決済経路に第三者を入れたくなく、鍵と RPC アクセスを自前で保持できる |+| 自前のファシリテーターを運用 | 同じ制御を複数サービスで共有したい |+| [`x402.org` ファシリテーター](https://x402.org/facilitator) | 開発・テストネット向け — パッケージのデフォルトでセットアップ不要。アップストリームはメインネットルート向けではないと明記している |+| ホスト型の本番ファシリテーター | インフラを運用せずにメインネット対応が欲しい |++ホスト型を選ぶ場合は、ここに書かれた名前ではなくアップストリームドキュメントの[ファシリテーターリスト](https://docs.x402.org/dev-tools/facilitators)から選ぶこと — メンテナンスされており、網羅的ではなく、カバレッジも変わる。執筆時点では Coinbase の CDP(全トランザクションに KYT/OFAC スクリーニング)、PayAI、Corbits、Dexter、Solvador などが掲載され、複数が EVM に加えて Solana メインネットをカバーしている。どれを選ぶ場合も、本番前に `/supported` エンドポイントでライブカバレッジを確認し、ネットワークを追加したときは再確認すること。-**ファシリテーターの選択。** パッケージのデフォルトは [`x402.org` ファシリテーター](https://x402.org/facilitator) — テストネット専用(Base Sepolia、Solana デブネットほか)、セットアップ不要で開発に最適。メインネットはアップストリームドキュメントの[ファシリテーターリスト](https://docs.x402.org/dev-tools/facilitators)から選ぶ:[PayAI ファシリテーター](https://facilitator.payai.network) は妥当な本番デフォルト(Solana メインネットを含むマルチネットワーク、API キー不要)で、CDP ファシリテーターは全トランザクションに KYT/OFAC スクリーニングを行う Coinbase ホスト型。自前のファシリテーター運用やセルフファシリテーションも可能。+> **開示**: このセクションは、掲載されているファシリテーターの 1 つである PayAI に関わる者が寄稿した。複数ある選択肢の 1 つとして記載しており、上記の自己ホストおよびアップストリームデフォルトのパスを意図的に先に挙げている。**セラー側(API がエージェントに課金する)。** アップストリームのミドルウェアを使用する;1 つのルートで Base と Solana を同時に提示できる(実行可能なバージョンは [`examples/typescript/servers`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers) を参照):| ランタイム | パッケージ ||---------|---------|-| Express / Hono / Next.js / Fastify | `@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]` |+| Express / Hono / Next.js / Fastify | `@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]` || Python(FastAPI、Flask) | PyPI の `x402` || Go(Gin、Echo、`net/http`) | `github.com/x402-foundation/x402/go/v2` |@@ -309,5 +340,5 @@ main().catch((err) => {- **アップストリーム x402 モノレポ**: [`x402-foundation/x402`](https://github.com/x402-foundation/x402) — TypeScript、Python、Go の実装と、メンテナンスされているクライアント・サーバー例- **x402 ドキュメント**: [docs.x402.org](https://docs.x402.org);本番ファシリテーターリストは [docs.x402.org/dev-tools/facilitators](https://docs.x402.org/dev-tools/facilitators)- **`@x402` パッケージ**: [npmjs.com/org/x402](https://www.npmjs.com/org/x402) — `@x402/fetch`、`@x402/axios`、`@x402/express`、`@x402/hono`、`@x402/next`、`@x402/fastify`、`@x402/evm`、`@x402/svm`-- **ファシリテーター**: [x402.org ファシリテーター](https://x402.org/facilitator)(テストネットデフォルト)、[PayAI](https://facilitator.payai.network)(マルチネットワーク本番、API キー不要)、[CDP](https://docs.cdp.coinbase.com/x402/docs/quickstart-sellers)(Coinbase ホスト型、KYT/OFAC)+- **ファシリテーター**: [自己ファシリテーションの例](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation)(第三者なし)、[x402.org ファシリテーター](https://x402.org/facilitator)(テストネットデフォルト)、メンテナンスされている[本番リスト](https://docs.x402.org/dev-tools/facilitators)- **発見**: CDP と PayAI のバザールは `/discovery/resources`;Solana で支払い可能なサービスは [pay.sh](https://pay.sh)diff --git a/docs/zh-CN/skills/agent-payment-x402/SKILL.md b/docs/zh-CN/skills/agent-payment-x402/SKILL.mdindex d1183b9ed..dca78ad01 100644--- a/docs/zh-CN/skills/agent-payment-x402/SKILL.md+++ b/docs/zh-CN/skills/agent-payment-x402/SKILL.md@@ -32,7 +32,7 @@ origin: community- `agentwallet-sdk`:在生产使用前,通过包文档确认当前网络覆盖范围。Base Sepolia 是最安全的开发默认值;Base 主网是原始技能所述的生产路径。- OKX Payments / X Layer:当前卖家文档面向 X Layer(`eip155:196`)和 USDT0 结算。由于支付包和结算器行为可能快速变化,生成生产代码前请获取当前 SDK 文档。-- 上游 x402 包:设计上即多网络 —— 一条路由可以同时提供 Base 和 Solana,由买方选择。包默认使用 `x402.org` 结算器,它仅限测试网(Base Sepolia `eip155:84532`、Solana 开发网 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`,以及 Stellar、Aptos、Hedera、XRPL 测试网),不适用于主网路由。生产环境请从上游文档的结算器列表中选择 —— PayAI 结算器是 Solana 主网(`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)及其他网络的合理默认选择,无需 API 密钥;CDP 结算器由 Coinbase 托管,对每笔交易执行 KYT/OFAC 筛查。生产前请在各结算器的 `/supported` 端点确认实时覆盖范围,而不要在此硬编码。+- 上游 x402 包:设计上即多网络 —— 一条路由可以同时提供 Base 和 Solana,由买方选择。包默认使用 `x402.org` 结算器,它仅限测试网(Base Sepolia `eip155:84532`、Solana 开发网 `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`,以及 Stellar、Aptos、Hedera、XRPL 测试网),不适用于主网路由。主网(Solana 为 `solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`)请选择自结算、自行运行结算器,或从上游结算器列表中挑选托管方案——参见选项 C 中的结算器对比。生产前请在结算器的 `/supported` 端点确认实时覆盖范围,而不要在此硬编码。## 工作原理@@ -109,8 +109,8 @@ x402 将 HTTP 402(需要付款)扩展为机器可协商的流程。当服务1. 从维护中的 [`examples/typescript/clients`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/clients) 示例(fetch、axios、MCP)开始,而不是复制旧文档中的片段。2. 在签署或提交第一笔付费请求之前要求明确的用户确认,与选项 B 对 OKX 流程的要求完全一致。不要将支付执行隐藏在通用工具调用之后。-3. 锁定包版本(例如 `@x402/[email protected]`);上游所有包以相同步调发布版本。-4. 在每次付费调用之前立即用预算策略进行故障关闭门控——而不是在客户端构建时只做一次。+3. 锁定包版本(例如 `@x402/[email protected]`);上游所有包以相同步调发布版本。+4. 用注册到客户端的 `PaymentPolicy` 强制预算,使检查在每次调用时都针对服务器的真实挑战运行。与你自己传入的数字比较的预算不能证明任何事——金额、资产和网络都来自服务器,因此必须在签名产生之前全部验证。```typescriptimport { x402Client, wrapFetchWithPayment } from "@x402/fetch";@@ -131,34 +131,65 @@ if (!evmKey || !svmKey) {const client = new x402Client();client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(evmKey)));client.register("solana:*", new ExactSvmScheme(await createKeyPairSignerFromBytes(base58.decode(svmKey))));-const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// Minimal fail-closed gate. For the full MCP-backed version with budget-// tracking, reuse preToolCheck from the Examples section below.-const ALLOWED_HOSTS = new Set(["api.example.com"]);-let sessionSpend = 0;-function assertPaymentAllowed(url: string, maxCost: number, sessionCap = 5.0): void {- if (!ALLOWED_HOSTS.has(new URL(url).host)) throw new Error("Host not allowlisted — blocked");- if (!Number.isFinite(maxCost) || maxCost < 0) throw new Error("Invalid cost — blocked");- if (sessionSpend + maxCost > sessionCap) throw new Error("Session budget exceeded — blocked");- sessionSpend += maxCost;-}+// A PaymentPolicy filters the SERVER's payment requirements before any+// signature is created. Returning an empty array means "nothing here is+// acceptable" and the client refuses to pay rather than falling back.+const ALLOWED_NETWORKS = new Set([+ "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", // Solana mainnet+ "eip155:8453", // Base+]);+const MAX_AMOUNT = 10_000n; // atomic units — 6-decimal USDC, so $0.01++// EVM addresses are case-insensitive, so compare them lowercased. Solana+// addresses are base58 and ARE case-sensitive — never lowercase those, or a+// different account could slip through.+const normalizeAsset = (a: string) => (a.startsWith("0x") ? a.toLowerCase() : a);+const ALLOWED_ASSETS = new Set(+ [+ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC, Solana mainnet+ "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC, Base+ ].map(normalizeAsset),+);++client.registerPolicy((_x402Version, requirements) =>+ requirements.filter(r => {+ if (!ALLOWED_NETWORKS.has(r.network)) return false; // wrong chain+ if (!ALLOWED_ASSETS.has(normalizeAsset(r.asset))) return false; // wrong token+ try {+ const amount = BigInt(r.amount);+ return amount >= 0n && amount <= MAX_AMOUNT; // over budget / negative+ } catch {+ return false; // unparseable amount+ }+ }),+);++const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// Gate immediately before EVERY paid call — a wrapped client checked only once-// at construction leaves every later call unmetered.-assertPaymentAllowed("https://api.example.com/data", 0.01);const res = await fetchWithPayment("https://api.example.com/data", { method: "GET" });```-包装后的客户端只会支付 `network` 与已注册方案匹配的挑战。签署前还应验证挑战的 `asset`:在 Solana 上,USDC 主网为 `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v`,开发网为 `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`。任何不匹配都按故障关闭处理:不签署,不重试。在 exact-SVM 方案中,结算器是交易费用支付方,因此买方钱包只需持有 USDC——无需 SOL 支付 gas。+注册该策略后,超预算金额、非预期代币或未注册的链都会故障关闭——所有候选项都被过滤掉,`createPaymentPayload` 会抛出异常而不是签名。开发网 USDC 是 `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`;仅在开发时把它加入 `ALLOWED_ASSETS`。对策略做对抗性测试——分别喂入要求 `5000000` 原子单位的挑战、报价另一种铸币地址的挑战,以及你从未注册的链上的挑战,并断言它们都不会产生签名。在 exact-SVM 方案中,结算器是交易费用支付方,因此买方钱包只需持有 USDC——无需 SOL 支付 gas。++**结算器选择。** 结算器代表资源服务器执行验证和结算,因此这是资源服务器的决定,而非买方的决定。按委托信任由少到多排列:++| 选项 | 适用场景 |+|--------|--------------|+| [进程内自结算](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation) | 你不希望结算路径中有第三方,且能自行持有密钥和 RPC 访问 |+| 自行运行结算器 | 你想要同样的控制力,但在多个服务间共享 |+| [`x402.org` 结算器](https://x402.org/facilitator) | 开发与测试网——它是包的默认值,无需配置,上游明确说明它不适用于主网路由 |+| 托管的生产结算器 | 你希望获得主网覆盖而不必自己运维基础设施 |++选择托管方案时,请从上游文档的[结算器列表](https://docs.x402.org/dev-tools/facilitators)中挑选,而不是照搬这里的名字——该列表有人维护、并不详尽,且覆盖范围会变化。撰写时它包含 Coinbase 的 CDP(对每笔交易执行 KYT/OFAC 筛查)、PayAI、Corbits、Dexter、Solvador 等,其中若干同时覆盖 EVM 与 Solana 主网。无论选择哪一个,上线前都要在其 `/supported` 端点确认实时覆盖范围,并在新增网络时重新确认。-**结算器选择。** 包默认使用 [`x402.org` 结算器](https://x402.org/facilitator)——仅限测试网(Base Sepolia、Solana 开发网等),零配置,适合开发。主网请从上游文档的[结算器列表](https://docs.x402.org/dev-tools/facilitators)中选择:[PayAI 结算器](https://facilitator.payai.network) 是合理的生产默认选择(包括 Solana 主网在内的多网络,无需 API 密钥),CDP 结算器由 Coinbase 托管并对每笔交易执行 KYT/OFAC 筛查。也可以自行运行结算器或自结算。+> **披露**:本节由参与 PayAI(所列结算器之一)的人贡献。它只是若干选项之一,上面的自托管与上游默认路径是有意排在前面的。**卖方侧(API 向代理收费)。** 使用上游中间件;一条路由可以同时提供 Base 和 Solana(可运行版本参见 [`examples/typescript/servers`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers)):| 运行时 | 包 ||---------|---------|-| Express / Hono / Next.js / Fastify | `@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]` |+| Express / Hono / Next.js / Fastify | `@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]`、`@x402/[email protected]` || Python(FastAPI、Flask) | PyPI 上的 `x402` || Go(Gin、Echo、`net/http`) | `github.com/x402-foundation/x402/go/v2` |@@ -309,5 +340,5 @@ main().catch((err) => {- **上游 x402 monorepo**:[`x402-foundation/x402`](https://github.com/x402-foundation/x402) — TypeScript、Python 和 Go 实现,以及维护中的客户端和服务器示例- **x402 文档**:[docs.x402.org](https://docs.x402.org);生产结算器列表位于 [docs.x402.org/dev-tools/facilitators](https://docs.x402.org/dev-tools/facilitators)- **`@x402` 包**:[npmjs.com/org/x402](https://www.npmjs.com/org/x402) — `@x402/fetch`、`@x402/axios`、`@x402/express`、`@x402/hono`、`@x402/next`、`@x402/fastify`、`@x402/evm`、`@x402/svm`-- **结算器**:[x402.org 结算器](https://x402.org/facilitator)(测试网默认)、[PayAI](https://facilitator.payai.network)(多网络生产,无需 API 密钥)、[CDP](https://docs.cdp.coinbase.com/x402/docs/quickstart-sellers)(Coinbase 托管,KYT/OFAC)+- **结算器**:[自结算示例](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation)(无第三方)、[x402.org 结算器](https://x402.org/facilitator)(测试网默认)、以及有人维护的[生产列表](https://docs.x402.org/dev-tools/facilitators)- **发现**:CDP 与 PayAI 集市位于 `/discovery/resources`;Solana 可付费服务见 [pay.sh](https://pay.sh)diff --git a/skills/agent-payment-x402/SKILL.md b/skills/agent-payment-x402/SKILL.mdindex af634673a..5ab39951f 100644--- a/skills/agent-payment-x402/SKILL.md+++ b/skills/agent-payment-x402/SKILL.md@@ -33,7 +33,7 @@ Choose the integration path based on whether your agent is buying access to a pa- `agentwallet-sdk`: use the package docs to confirm current network coverage before production. Base Sepolia is the safest development default; Base mainnet is the production path called out by the original skill.- OKX Payments / X Layer: current seller docs target X Layer (`eip155:196`) and USDT0 settlement. Fetch current SDK docs before generating production code because payment packages and facilitator behavior can change quickly.-- Upstream x402 packages: multi-network by design — one route can advertise Base and Solana simultaneously and let the buyer pick. The packages default to the `x402.org` facilitator, which is testnet-only (Base Sepolia `eip155:84532`, Solana devnet `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`, plus Stellar, Aptos, Hedera, and XRPL testnets) and is not intended for mainnet routes. For production, choose from the facilitator list in the upstream docs — the PayAI facilitator is a reasonable default for Solana mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp`) and other networks with no API keys required; the CDP facilitator is Coinbase-hosted with KYT/OFAC screening. Confirm live coverage at each facilitator's `/supported` endpoint before production rather than hardcoding it here.+- Upstream x402 packages: multi-network by design — one route can advertise Base and Solana simultaneously and let the buyer pick. The packages default to the `x402.org` facilitator, which is testnet-only (Base Sepolia `eip155:84532`, Solana devnet `solana:EtWTRABZaYq6iMfeYKouRu166VU2xqa1`, plus Stellar, Aptos, Hedera, and XRPL testnets) and is not intended for mainnet routes. For mainnet (`solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp` for Solana), either self-facilitate, run your own facilitator, or pick a hosted one from the upstream facilitator list — see the facilitator comparison under Option C. Confirm live coverage at the facilitator's `/supported` endpoint before production rather than hardcoding it here.## How It Works@@ -110,8 +110,8 @@ For buyer-side agent flows:1. Start from the maintained examples in [`examples/typescript/clients`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/clients) (fetch, axios, MCP) rather than copying snippets from older docs.2. Require explicit user confirmation before signing or submitting the first paid request, exactly as Option B requires for OKX flows. Do not hide payment execution behind a generic tool call.-3. Pin package versions (for example `@x402/[email protected]`); all upstream packages version in lockstep.-4. Gate every paid call fail-closed with your budget policy immediately before the call — not once at client construction.+3. Pin package versions (for example `@x402/[email protected]`); all upstream packages version in lockstep.+4. Enforce your budget with a `PaymentPolicy` registered on the client, so the check runs against the server's actual challenge on every call. A budget compared against a number you passed in yourself proves nothing — the amount, asset, and network all come from the server, so all three must be validated before a signature exists.```typescriptimport { x402Client, wrapFetchWithPayment } from "@x402/fetch";@@ -132,34 +132,65 @@ if (!evmKey || !svmKey) {const client = new x402Client();client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(evmKey)));client.register("solana:*", new ExactSvmScheme(await createKeyPairSignerFromBytes(base58.decode(svmKey))));-const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// Minimal fail-closed gate. For the full MCP-backed version with budget-// tracking, reuse preToolCheck from the Examples section below.-const ALLOWED_HOSTS = new Set(["api.example.com"]);-let sessionSpend = 0;-function assertPaymentAllowed(url: string, maxCost: number, sessionCap = 5.0): void {- if (!ALLOWED_HOSTS.has(new URL(url).host)) throw new Error("Host not allowlisted — blocked");- if (!Number.isFinite(maxCost) || maxCost < 0) throw new Error("Invalid cost — blocked");- if (sessionSpend + maxCost > sessionCap) throw new Error("Session budget exceeded — blocked");- sessionSpend += maxCost;-}+// A PaymentPolicy filters the SERVER's payment requirements before any+// signature is created. Returning an empty array means "nothing here is+// acceptable" and the client refuses to pay rather than falling back.+const ALLOWED_NETWORKS = new Set([+ "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", // Solana mainnet+ "eip155:8453", // Base+]);+const MAX_AMOUNT = 10_000n; // atomic units — 6-decimal USDC, so $0.01++// EVM addresses are case-insensitive, so compare them lowercased. Solana+// addresses are base58 and ARE case-sensitive — never lowercase those, or a+// different account could slip through.+const normalizeAsset = (a: string) => (a.startsWith("0x") ? a.toLowerCase() : a);+const ALLOWED_ASSETS = new Set(+ [+ "EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v", // USDC, Solana mainnet+ "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913", // USDC, Base+ ].map(normalizeAsset),+);++client.registerPolicy((_x402Version, requirements) =>+ requirements.filter(r => {+ if (!ALLOWED_NETWORKS.has(r.network)) return false; // wrong chain+ if (!ALLOWED_ASSETS.has(normalizeAsset(r.asset))) return false; // wrong token+ try {+ const amount = BigInt(r.amount);+ return amount >= 0n && amount <= MAX_AMOUNT; // over budget / negative+ } catch {+ return false; // unparseable amount+ }+ }),+);++const fetchWithPayment = wrapFetchWithPayment(fetch, client);-// Gate immediately before EVERY paid call — a wrapped client checked only once-// at construction leaves every later call unmetered.-assertPaymentAllowed("https://api.example.com/data", 0.01);const res = await fetchWithPayment("https://api.example.com/data", { method: "GET" });```-The wrapped client only pays challenges whose `network` matches a scheme you registered. Before signing, also verify the challenge's `asset`: on Solana, USDC is `EPjFWdd5AufqSSqeM2qN1xzybapC8G4wEGGkZwyTDt1v` (mainnet) and `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU` (devnet). Treat any mismatch as fail-closed: do not sign, do not retry. In the exact-SVM scheme the facilitator is the transaction fee payer, so the buyer wallet holds USDC only — no SOL for gas.+With the policy registered, an over-budget amount, an unexpected token, or an unregistered chain all fail closed — `createPaymentPayload` throws instead of signing, because every candidate was filtered out. Devnet USDC is `4zMMC9srt5Ri5X14GAgXhaHii3GnPAEERYPJgZJDncDU`; add it to `ALLOWED_ASSETS` only for development. Test the policy adversarially — feed it a challenge demanding `5000000` atomic units, one quoting a different mint, and one on a chain you never registered, and assert that none of them produce a signature. In the exact-SVM scheme the facilitator is the transaction fee payer, so the buyer wallet holds USDC only — no SOL for gas.++**Facilitator choice.** A facilitator verifies and settles on the resource server's behalf, so this is the resource server's decision, not the buyer's. In rough order of least to most trust delegated:++| Option | When it fits |+|--------|--------------|+| [Self-facilitate in-process](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation) | You want no third party in the settlement path and can hold keys and RPC access yourself |+| Run your own facilitator | You want that same control but shared across several services |+| [`x402.org` facilitator](https://x402.org/facilitator) | Development and testnets — it is the package default, requires no setup, and upstream documents it as not intended for mainnet routes |+| A hosted production facilitator | You want mainnet coverage without operating infrastructure |++For the hosted option, choose from the [facilitator list](https://docs.x402.org/dev-tools/facilitators) in the upstream docs rather than a name copied from here — it is maintained, it is not exhaustive, and coverage changes. As of writing it includes Coinbase's CDP (KYT/OFAC screening on every transaction), PayAI, Corbits, Dexter, Solvador, and others; several cover Solana mainnet alongside EVM. Whichever you pick, confirm live coverage at its `/supported` endpoint before production and re-check when you add a network.-**Facilitator choice.** The packages default to the [`x402.org` facilitator](https://x402.org/facilitator) — testnet-only (Base Sepolia, Solana devnet, and other testnets), zero setup, right for development. For mainnet, pick from the [facilitator list](https://docs.x402.org/dev-tools/facilitators) in the upstream docs: the [PayAI facilitator](https://facilitator.payai.network) is a reasonable production default (multi-network including Solana mainnet, no API keys required), and the CDP facilitator is Coinbase-hosted with KYT/OFAC screening on every transaction. Anyone can also run their own facilitator or self-facilitate.+> **Disclosure**: this section was contributed by someone who works on PayAI, one of the listed facilitators. It is included as one option among several, and the self-hosted and upstream-default paths above are deliberately listed first.**Seller side (API charges agents).** Use the upstream middleware; one route can advertise Base and Solana simultaneously (see [`examples/typescript/servers`](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers) for runnable versions):| Runtime | Package ||---------|---------|-| Express / Hono / Next.js / Fastify | `@x402/[email protected]`, `@x402/[email protected]`, `@x402/[email protected]`, `@x402/[email protected]` |+| Express / Hono / Next.js / Fastify | `@x402/[email protected]`, `@x402/[email protected]`, `@x402/[email protected]`, `@x402/[email protected]` || Python (FastAPI, Flask) | `x402` on PyPI || Go (Gin, Echo, `net/http`) | `github.com/x402-foundation/x402/go/v2` |@@ -310,5 +341,5 @@ main().catch((err) => {- **Upstream x402 monorepo**: [`x402-foundation/x402`](https://github.com/x402-foundation/x402) — TypeScript, Python, and Go implementations plus maintained client and server examples- **x402 docs**: [docs.x402.org](https://docs.x402.org); production facilitator list at [docs.x402.org/dev-tools/facilitators](https://docs.x402.org/dev-tools/facilitators)- **`@x402` packages**: [npmjs.com/org/x402](https://www.npmjs.com/org/x402) — `@x402/fetch`, `@x402/axios`, `@x402/express`, `@x402/hono`, `@x402/next`, `@x402/fastify`, `@x402/evm`, `@x402/svm`-- **Facilitators**: [x402.org facilitator](https://x402.org/facilitator) (testnet default), [PayAI](https://facilitator.payai.network) (multi-network production, no API keys), [CDP](https://docs.cdp.coinbase.com/x402/docs/quickstart-sellers) (Coinbase-hosted, KYT/OFAC)+- **Facilitators**: [self-facilitation example](https://github.com/x402-foundation/x402/tree/main/examples/typescript/servers/self-facilitation) (no third party), [x402.org facilitator](https://x402.org/facilitator) (testnet default), and the maintained [production list](https://docs.x402.org/dev-tools/facilitators)- **Discovery**: CDP and PayAI bazaars at `/discovery/resources`; [pay.sh](https://pay.sh) for Solana-payable services