x402 Wallet

@three-ws/x402-mcp

为任何 AI Agent 配备自托管的 x402 钱包，通过你自己的 Solana 密钥，以 USDC 发现、查看并支付任何收费服务。

---

一个 Model Context Protocol 服务，可将任何 AI 助手转变为 x402 网络上的自主经济 Agent。在实时市场中搜索收费服务，在支付前查看端点价格，并以 USDC 使用 pay_and_call 调用任何 x402 服务——通过你自己的密钥在 Solana 上结算，绝不使用托管钱包。

这是 three.ws Agent 经济体系中面向买家的一侧。支付流程和 Solana exact 方案签名由真正的 @x402/* 库处理——并非模拟实现。

安装

npm install @three-ws/x402-mcp

也可以使用 npx 运行：

SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcp

快速开始

Claude Code，一行即可：

claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcp

Claude Desktop / Cursor（claude_desktop_config.json 或 mcp.json）：

{
	"mcpServers": {
		"x402": {
			"command": "npx",
			"args": ["-y", "@three-ws/x402-mcp"],
			"env": {
				"SOLANA_SECRET_KEY": "<base58 secret of the wallet that holds USDC>",
				"SOLANA_RPC_URL": "https://your-rpc-provider",
				"MAX_PAY_USD": "1"
			}
		}
	}
}

SOLANA_SECRET_KEY 仅在需要消费时才需要（pay_and_call，以及默认使用你的钱包的 x402_wallet）。find_services 和 inspect_endpoint 无需密钥即可使用。

工具

工具	类型	功能
x402_wallet	只读	钱包地址及实时 SOL/USDC 余额。默认使用你的签名者钱包 — 付款前请确认资金。
find_services	只读	搜索实时 x402 集市（PayAI + Coinbase CDP），查找带价格的付费 HTTP/MCP 服务。
inspect_endpoint	只读	读取任意端点的 402 付款要求（scheme、network、asset、pay-to），不会付款。
pay_and_call	执行	使用你的 Solana 密钥，以 USDC 支付 x402 端点费用并返回结果。受 MAX_PAY_USD 限制。
spending_report	只读	按商户和日期汇总 pay_and_call 及下方具名工具支付的所有费用。

此外还有 17 个具名工具，每个对应一个固定的 three.ws x402 服务；相比组合原始的 pay_and_call(url)，模型使用这些工具能更准确地发起调用：

工具	价格	端点
weather_forecast	$0.001	/api/x402/weather-guard-forecast
weather_go_no_go	$0.002	/api/x402/weather-guard-decision
carbon_now	$0.001	/api/x402/carbon-now
carbon_best_window	$0.002	/api/x402/carbon-best-window
domain_rdap_check	$0.001	/api/x402/domains-check
domain_rdap_check_bulk	$0.005	/api/x402/domains-bulk
research_search	$0.002	/api/x402/research-search
research_paper	$0.003	/api/x402/research-paper
research_bibliography	$0.005	/api/x402/research-bibliography
book_search	$0.001	/api/x402/books-search
book_read	$0.01	/api/x402/books-read
news_wire_search	$0.003	/api/x402/news-wire-query
news_wire_poll	$0.002	/api/x402/news-wire-pulse
transit_plan	$0.002	/api/x402/transit-plan
transit_delays	$0.001	/api/x402/transit-delays
places_search	$0.002	/api/x402/places-search
places_detail	$0.002	/api/x402/places-detail

每个工具的参数与对应端点相同（完整 schema 见 src/tools.json），付款时使用与 pay_and_call 相同的 SOLANA_SECRET_KEY / session_token 结算模式，并受同一 MAX_PAY_USD 上限和 REQUIRE_CONFIRM 标志控制。只要你需要的端点有对应的具名工具，就优先使用该具名工具，而不是 pay_and_call：固定的 schema 和明确标示的价格能大幅降低模型误拨调用的可能性。

安全性

pay_and_call 带有 destructiveHint: true，因此支持注解的客户端（Claude Code、Claude Desktop、Cursor）会在运行前提示确认。除客户端提示外，每笔付款还受服务端限制：它会先探测 402，如果价格超过 max_usd 或 MAX_PAY_USD（默认值为 $1），则会在任何资金转移前拒绝；启用 REQUIRE_CONFIRM（默认启用）时，调用也会被拒绝，直到重新发起并设置 confirm: true。只结算 Solana（solana:*）的 exact scheme 要求 — 使用你掌控的密钥。

输入参数

x402_wallet — address（可选的 base58；默认为签名者钱包）。

find_services — query（必填）、type（http | mcp，默认为 http）、network（CAIP-2 筛选条件）、max_price_usdc、limit（1–100）。

inspect_endpoint — url（必填）、method（GET | POST）、body（对象）。

pay_and_call：url（必填）、method（GET | POST）、body（对象）、max_usd（降低本次调用的上限）、secret（本次调用的签名者覆盖值）、confirm（启用 REQUIRE_CONFIRM 时必须为 true）、session_token、token、idempotency_key。

它有两种结算模式：

• 自托管（默认）。 使用 SOLANA_SECRET_KEY 或本次调用的 secret 签名。密钥由你持有。
• 会话治理。 传入 three.ws Payment Session 令牌，平台钱包会代表你签名，同时强制执行该会话的预算、主机允许列表和单笔交易上限。无需私钥。支持 Solana USDC 和 Base USDC 会话；此模式下会忽略 secret 和 token。

token 用于选择结算资产：usdc（默认），或者在端点公告支持时使用平台代币 $THREE（three）。idempotency_key 用于避免重复调用；建议与 session_token 搭配使用，以防重试导致重复扣款。

示例

// inspect_endpoint — what does it cost? (no payment)
> { "url": "https://three.ws/api/x402/vanity?prefix=ab" }
{
  "ok": true, "paid": true,
  "accepts": [
    { "scheme": "exact", "network": "solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp", "asset": "EPjFW…", "price": 50000 }
  ],
  "payable_with_this_wallet": true
}

// pay_and_call — confirm:true required by default
> { "url": "https://three.ws/api/x402/vanity?prefix=ab", "confirm": true }
{ "ok": true, "paid": true, "payer": "Gx5E…", "price_usd": 0.05, "settlement": { … }, "result": { … } }

示例

可运行的免付款示例位于 examples/：

node examples/list-tools.mjs      # every tool with its full input schema
node examples/inspect-price.mjs   # find_services + inspect_endpoint on live data

两个示例都会通过 stdio 启动此服务并访问真实的 bazaar。它们都不会读取密钥，也不会调用 pay_and_call，因此不会进行签名或产生任何支出。预期输出请参阅 examples/README.md。

协议版本

pay_and_call 使用同一个 Solana 密钥支持两种 x402 线路格式：v2（CAIP-2 网络字符串，例如 solana:5eykt4UsFv8P8NJdTREpY1vzqKqZKvdp）和 v1（扁平网络字符串，例如 solana）。大多数开源 x402 bazaar，以及基于原始 x402/x402-fetch 软件包构建的服务，仍使用 v1。当卖方同时公告支持两种格式时，始终优先使用 v2。无论使用哪种版本付款，结算回执的格式都相同（success、transaction、network、payer），因此下游无需了解实际使用的版本。

要求

• Node.js >= 20。
• Solana 主网 RPC 端点（必须使用 https；开发环境仅允许 http://localhost）。公共集群可用于读取；付款流量请使用你自己的端点。
• 付款所需：持有 USDC 的 Solana 钱包，以 base58 格式提供 SOLANA_SECRET_KEY（或本次调用的 secret）。

环境变量

变量	必填	默认值
SOLANA_SECRET_KEY	仅付款时需要	—
SOLANA_RPC_URL	否	https://api.mainnet-beta.solana.com
MAX_PAY_USD	否	1
REQUIRE_CONFIRM	否	true
THREE_WS_BASE	否	https://three.ws
X402_MCP_LEDGER_PATH	否	~/.three-ws/x402-mcp-ledger.jsonl

X402_MCP_LEDGER_PATH 指向一个仅追加的 JSON 行文件，记录每笔已结算付款（pay_and_call 和命名工具）；spending_report 会读取该文件。

链接

• 主页：https://three.ws
• MCP 目录：https://three.ws/docs/mcp
• 更新日志：https://three.ws/changelog
• 问题反馈：https://github.com/nirholas/three.ws/issues
• 许可证：Apache-2.0，参见 LICENSE

---

_{属于 three.ws SDK 套件的一部分 — 3D AI Agent、链上身份和 Agent 付款。
网站 · 更新日志 · GitHub}