内容
<p align="center">
<a href="https://three.ws"><img src="https://three.ws/three-ws-mcp-icon.svg" alt="three.ws" width="88" height="88"></a>
</p>
<h1 align="center">@three-ws/x402-mcp</h1>
<p align="center"><strong>赋予任意 AI 代理一个自主托管的 x402 钱包 — 在 USDC 中发现、检查和支付任意付费服务，来自您的 Solana 私钥。</strong></p>
<p align="center">
<a href="https://www.npmjs.com/package/@three-ws/x402-mcp"><img alt="npm" src="https://img.shields.io/npm/v/@three-ws/x402-mcp?logo=npm&color=cb3837"></a>
<img alt="license" src="https://img.shields.io/npm/l/@three-ws/x402-mcp?color=3b82f6">
<img alt="node" src="https://img.shields.io/node/v/@three-ws/x402-mcp?color=339933&logo=node.js">
<a href="https://registry.modelcontextprotocol.io/?q=io.github.nirholas"><img alt="MCP Registry" src="https://img.shields.io/badge/MCP%20Registry-io.github.nirholas-0ea5e9"></a>
<a href="https://three.ws"><img alt="three.ws" src="https://img.shields.io/badge/built%20by-three.ws-000"></a>
</p>
---
> 一个 [模型上下文协议](https://modelcontextprotocol.io) 服务器，将任何 AI 助手转变为 x402 网络上的自主经济代理。在 live bazaar 中搜索付费服务，在提交资金前读取端点价格，并在 USDC 中 `pay_and_call` 任意 x402 服务 — 在 Solana 上使用 **您的私钥**结算，从不使用托管钱包。
这是 three.ws 代理经济的 **买方**。支付过程和 Solana `exact` 方案签名由实际的 `@x402/*` 库处理 — 没有模拟。
## 安装
```bash
npm install @three-ws/x402-mcp
```
或使用 `npx` 运行：
```bash
SOLANA_SECRET_KEY=<base58> npx @three-ws/x402-mcp
```
## 快速开始
**Claude Code**，一行：
```bash
claude mcp add x402 --env SOLANA_SECRET_KEY=<base58> -- npx -y @three-ws/x402-mcp
```
**Claude Desktop / Cursor**（`claude_desktop_config.json` 或 `mcp.json`）：
```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` | 只读 | 在 live x402 bazaar（PayAI + Coinbase CDP）中搜索带有价格的付费 HTTP/MCP 服务。 |
| `inspect_endpoint` | 只读 | 读取任意端点的 402 支付要求（方案、网络、资产、价格、支付至）**无需支付**。 |
| `pay_and_call` | **执行** | 使用 Solana 私钥在 USDC 中支付 x402 端点并返回其结果。受 `MAX_PAY_USD` 限制。 |
### 安全
`pay_and_call` 携带 `destructiveHint: true`，因此注解感知客户端（Claude Code、Claude Desktop、Cursor）在运行它之前会提示。除客户端提示外，每笔付款都在服务器端有界限：它 **首先探测 402**，如果价格超过 `max_usd` 或 `MAX_PAY_USD`（默认 $1），则拒绝 **在任何资金转移之前**，并且默认情况下 `REQUIRE_CONFIRM` 开启，调用在重新发出 `confirm: true` 之前拒绝。只有 Solana (`solana:*`) `exact` 方案要求得到解决 — 使用您控制的私钥。
### 输入参数
**`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`）。
## 示例
```jsonc
// inspect_endpoint — 费用是多少？（无需支付）
> { "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 默认情况下需要
> { "url": "https://three.ws/api/x402/vanity?prefix=ab", "confirm": true }
{ "ok": true, "paid": true, "payer": "Gx5E…", "price_usd": 0.05, "settlement": { … }, "result": { … } }
```
## 要求
- **Node.js >= 20.**
- Solana mainnet 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` |
## 链接
- 首页：https://three.ws
- MCP 目录：https://three.ws/docs/mcp
- 更新日志：https://three.ws/changelog
- 问题：https://github.com/nirholas/three.ws/issues
- 许可证：Apache-2.0 — 见 [LICENSE](./LICENSE)
---
<p align="center">
<sub>
three.ws SDK 套件的一部分 — 3D AI 代理、链上身份和代理支付。<br/>
<a href="https://three.ws">网站</a> · <a href="https://three.ws/changelog">更新日志</a> · <a href="https://github.com/nirholas/three.ws">GitHub</a>
</sub>
</p>
## 许可证
Copyright © 2026 nirholas. All rights reserved.
本软件为专有软件 — 见 [LICENSE](./LICENSE)。未经版权所有者的明确书面许可，不得授予任何权利。
