three.ws Agent Payments

@three-ws/agentcore-payments-mcp

用于 three.ws Agent Payment Sessions 的 MCP 服务——管理 Agent 的 x402 支出，无需暴露私钥。

概念

Agent 不持有钱包，只提出支出请求。治理机制负责执行策略。

Payment Session 是一个预算额度，你可以从 three.ws 额度中一次性充值。将会话承载令牌交给 Agent；Agent 通过此服务调用需要付费的 x402 端点。平台钱包会为每笔交易签名。会话的允许列表、单笔交易上限和总预算会在服务端以原子方式执行——Agent 永远不会超支。

快速开始

# Configure
export THREE_WS_SESSION="<the value of your __Host-sid cookie>"
export PAYMENT_SESSION_TOKEN="pss_<session-id>_<random>"

# Run
npx @three-ws/agentcore-payments-mcp

MCP 客户端配置（~/.cursor/mcp.json、Claude Desktop 等）：

{
  "mcpServers": {
    "three-ws-payments": {
      "command": "npx",
      "args": ["-y", "@three-ws/agentcore-payments-mcp"],
      "env": {
        "THREE_WS_SESSION": "<the value of your __Host-sid cookie>",
        "PAYMENT_SESSION_TOKEN": "pss_..."
      }
    }
  }
}

环境变量

变量	必需	说明
THREE_WS_SESSION	用于会话管理工具	你的 __Host-sid 浏览器 Cookie 的值（不要带 __Host-sid= 前缀；服务端会为你发送 Cookie），用于创建/列出/取消会话
PAYMENT_SESSION_TOKEN	用于 pay_with_session 默认值	创建会话时返回的承载令牌；未提供内联令牌时会将其作为默认值传入
THREE_WS_BASE	否	基础 URL（默认值：https://three.ws）
THREE_WS_TIMEOUT_MS	否	请求超时时间，单位为毫秒（默认值：30000）

工具

create_payment_session

创建一个从你的额度中充值的新会话。

{
  "budget_usd": 10.00,
  "label": "Research agent — June sprint",
  "expiry_seconds": 86400,
  "max_per_tx_usd": 0.50,
  "allowed_hosts": ["api.example.com", "data.provider.io"],
  "network": "solana"
}

返回 { session, token }。令牌只显示一次，请立即保存。

pay_with_session

使用会话令牌支付 x402 端点。平台钱包负责签名；会话策略会得到执行。

{
  "url": "https://api.example.com/data",
  "method": "GET",
  "session_token": "pss_...",
  "idempotency_key": "run-42-fetch-data"
}

返回 { ok, paid, result, payment, session }，其中包含交易哈希、区块浏览器链接和更新后的预算。

如果省略 session_token，则会使用 PAYMENT_SESSION_TOKEN 环境变量。

check_payment_session

查看会话预算、状态和近期付款记录。

{ "session_id": "...", "include_executions": true }

list_payment_sessions

列出已认证用户的所有会话，并提供汇总统计信息。

{ "status": "active", "limit": 20 }

cancel_payment_session

取消会话，并将未使用的预算退还至你的额度。

{ "session_id": "..." }

网络支持

会话 network	平台付款方	USDC 合约
solana（默认）	X402_AGENT_SOLANA_SECRET_BASE58	Solana 主网 USDC
base	X402_EVM_AGENT_PRIVATE_KEY	Base 主网 USDC（0x8335…）

与 @three-ws/x402-mcp 集成

@three-ws/x402-mcp 中现有的 pay_and_call 工具现在可以直接接受 session_token：

{
  "url": "https://api.example.com/endpoint",
  "session_token": "pss_...",
  "confirm": true
}

这会将付款路由至 /api/pay/execute，而不是在本地签名——会话治理策略将适用。

示例

可运行且无需付款的示例位于 examples/：

node examples/list-tools.mjs       # every tool with its schema and safety annotations
node examples/plan-a-session.mjs   # read live x402 prices, print the policy to authorize

这两个示例都不会持有钱包、读取凭据或调用 pay_with_session，因此不会进行签名或产生支出。plan-a-session.mjs 值得借鉴：在决定授权多少预算前，先查看端点实际收费情况。请参阅 examples/README.md。

会话生命周期

create (budget debited from credits)
  └─ active → pay_with_session calls spend against budget
       ├─ exhausted (budget fully consumed)
       ├─ expired (TTL elapsed — cron refunds remaining budget)
       └─ cancelled (manual — remaining budget refunded immediately)

编程方式使用

包入口导出 TOOLS（包含每个工具定义：name、title、description、inputSchema、annotations、handler）和 buildServer()，后者会返回一个已完整注册但未附加传输层的 McpServer。导入操作不会产生副作用，也不需要凭据，因此你可以在自己的宿主中挂载这些工具，或离线检查其接口；只有在实际运行处理器时才需要凭据。

// run with: THREE_WS_SESSION=<your __Host-sid value> node this-file.mjs
import { TOOLS, buildServer } from '@three-ws/agentcore-payments-mcp';

for (const tool of TOOLS) {
	const kind = tool.annotations.readOnlyHint ? 'read ' : 'write';
	console.log(`${kind} ${tool.name}`);
}

// A tool handler is a plain async function against the live API.
const list = TOOLS.find((t) => t.name === 'list_payment_sessions');
console.log(await list.handler({ limit: 3 }));

// Or hand the whole registered server to your own MCP transport.
buildServer();

安全属性

• 不暴露密钥：会话令牌是有时限的 HMAC 签名授权。即使令牌遭到泄露，攻击者也只能在允许的主机上用掉剩余预算，仅此而已。
• 原子预算控制：并发支付使用 SQL UPDATE … WHERE remaining >= amount RETURNING — 两个同时发起的请求绝不可能合计超出预算。
• 允许列表：如果设置了 allowed_hosts，governor 会在签名之前拒绝发往列表之外主机的任何请求。
• 单笔交易上限：max_per_tx_usd 可防止单笔大额支付耗尽全部预算。
• SSRF 防护：所有 x402 目标 URL 都会经过公有 IP 允许列表验证，并在服务端进行 DNS 解析，然后才会签署任何支付。