drain-mcp

DRAIN MCP 服务

面向 AI Agent 的支付 — 无需 API 密钥、信用卡或订阅。

用于 Handshake58 AI Marketplace 的 MCP 服务。Agent 可发现服务提供商、自动付款并调用任意服务——大模型推理、网页抓取、图像生成、搜索等。

支持两种支付协议：

• DRAIN — Polygon 上的支付通道。开通一次，即可发送多次请求，完成后关闭。
• MPP — 通过 Tempo 按请求付款。每个请求单独付款。无需通道。

	DRAIN	MPP
设置	开通通道（$0.02 gas）	无
每次请求	$0.0001–$0.01	因提供商而异
最适用于	高请求量会话	单次请求、REST API
支付方式	Polygon 上的 USDC	Tempo 链上的 USDC

何时使用

在以下情况使用 drain-mcp：

• 无需 API 密钥即可调用任意服务（大模型、搜索、抓取、图像生成等）
• 使用 USDC 按请求付款——无需订阅或信用卡
• 通过统一接口访问 30 多家提供商

在以下情况不要使用 drain-mcp：

• 你已经拥有所需服务的 API 密钥
• 任务不需要外部服务

---

TL;DR - 最简可行工作流

MPP 提供商（按请求付款，无需通道）

1. drain_providers(protocol: "mpp")  → Find MPP providers
2. drain_provider_info(id)           → Read docs (essential for REST APIs)
3. mpp_chat(provider, messages)      → LLM providers (auto-pay via Tempo)
   — OR —
   mpp_request(url, body)            → REST API providers (auto-pay via Tempo)
4. drain_feedback(providerId, outcome) → Optional: report success/failure

DRAIN 提供商（支付通道）

1. drain_providers(protocol: "drain") → Find DRAIN providers
2. drain_provider_info(id)            → Get provider details + usage docs
3. drain_balance()                    → Check USDC + POL
4. drain_approve()                    → Approve USDC spending (once)
5. drain_open_channel(...)            → Deposit USDC, get channelId
6. drain_chat(...)                    → Send requests (repeat as needed)
7. drain_cooperative_close(...)       → Close early, instant refund (when done)
   — OR after expiry —
8. drain_close_channel(...)           → Reclaim funds (after expiry)

---

何时关闭通道

• 任务完成了？ → 使用 drain_cooperative_close(channelId)。 未使用的存款会立即退还。完成后务必执行此操作。

• 很快还要发送更多请求？ → 保持通道开启。 无需关闭后重新开通——可节省 $0.04 的 gas 费用。

• 通道已过期？ → 使用 drain_close_channel(channelId)。 在过期时间戳之后取回未使用的 USDC。 资金不会自动退回。

经验法则： 任务完成后关闭。工作期间保持开启。

---

已遇到 402？

MPP 提供商： drain-mcp 通过 mppx/Tempo 自动处理 402。只需使用 mpp_chat 或 mpp_request——支付会自动完成。

DRAIN 提供商在未发送支付凭证时，会返回带有以下标头的 402 Payment Required：

标头	值
X-Payment-Protocol	drain-v2
X-Payment-Provider	提供商钱包地址（向此地址开通通道）
X-Payment-Contract	DRAIN 合约地址
X-Payment-Chain	137（Polygon Mainnet）
X-Payment-Signing	EIP-712 签名参数的 URL
X-Payment-Docs	提供商文档端点

DRAIN 流程：

1. 调用提供商端点（不带支付凭证）→ 获取带有标头的 402
2. 安装 drain-mcp，或使用 X-Payment-Signing URL 上的签名 API
3. 向 X-Payment-Provider 地址开通通道
4. 在请求中添加 X-DRAIN-Voucher 标头并重试

402 响应中包含所需的一切。无需预先注册。

---

工具参考

发现

drain_providers

查找服务提供商。按模型名称、类别或在线状态筛选。

{
  "model": "gpt-4o",
  "category": "scraping",
  "onlineOnly": true
}

类别：llm、image、audio、code、scraping、vpn、multi-modal、other

drain_provider_info

获取提供商的详细信息，包括使用说明（文档）。文档会说明如何为该提供商格式化请求。

{ "provider": "hs58-openai" }

钱包

drain_balance

检查钱包中的 USDC 余额、用于 gas 的 POL，以及 DRAIN 合约授权额度。

drain_approve

授权 DRAIN 合约使用 USDC。开通通道前需执行一次。

{ "amount": "100" }

通道

drain_open_channel

开通支付通道。锁定指定时长的 USDC。

{
  "provider": "hs58-openai",
  "amount": "5.00",
  "duration": "24h"
}

返回 channelId、过期时间和提供商使用文档。

drain_channel_status

检查通道的存款、支出、剩余余额和过期时间。

drain_channels

列出所有已知通道及其状态（active/expired/closed）。查找需要关闭的过期通道。

使用（DRAIN）

drain_chat

通过 DRAIN 通道发送付费请求。适用于所有 DRAIN 提供方类型：

• 大模型提供方： 标准聊天消息
• 非大模型提供方： 在用户消息内容中发送 JSON 载荷（请查阅提供方文档）

{
  "channelId": "0x...",
  "model": "gpt-4o",
  "messages": [{"role": "user", "content": "Hello"}]
}

用法（MPP）

mpp_chat

向 MPP 大模型提供方发送聊天请求。通过 Tempo 自动付款——无需通道，也无需设置。

{
  "provider": "provider-id-or-url",
  "messages": [{"role": "user", "content": "Hello"}],
  "model": "optional-model-id"
}

mpp_request

向 MPP REST API 服务（Tavily、Brave、Wolfram 等）发送请求。通过 Tempo 自动付款。

{
  "url": "https://tavily.mpp.paywithlocus.com/tavily/search",
  "body": {"query": "AI agents", "max_results": 5}
}

请先阅读提供方文档（drain_provider_info），以查找正确的端点路径和请求格式。

质量反馈

drain_feedback

使用任何提供方（DRAIN 或 MPP）后，报告成功或失败。反馈将用于市场质量评分系统。

{
  "providerId": "provider-id",
  "outcome": "success",
  "reason": "accurate_result"
}

结算

drain_cooperative_close

经提供方同意提前关闭通道。任务完成后请使用此工具——未花费的存款将立即退还。无需等待通道到期。

{ "channelId": "0x..." }

drain_close_channel

关闭已过期的通道并收回未花费的 USDC。在通道超过到期时间戳后使用。

{ "channelId": "0x..." }

---

经济示例

开启 GPT-4o 通道：

Gas to open channel:     $0.02   (one-time)
Deposit:                 $0.50   (refundable remainder)
Per request:            ~$0.001755
Requests possible:      ~285

Cost for 10 requests:    $0.02 gas + $0.01755 usage = $0.04
Refund after close:      $0.50 - $0.01755 = $0.48
Gas to close:            $0.02

• 协议费用：提供方请求金额的 2%（链上）
• 会话费用：无
• 实时定价：GET https://handshake58.com/api/mcp/providers

---

提供方类别

提供方并不限于大模型聊天。每个提供方都有一个 category 字段，以及一个说明请求格式的文档端点。

类别	描述	消息格式
llm	语言模型（GPT-4o、Claude、Grok、Gemini）	标准聊天消息
image	图像生成	用户内容中的 JSON（见文档）
audio	音频/TTS/STT	用户内容中的 JSON（见文档）
code	代码生成	标准聊天或 JSON（见文档）
scraping	网页抓取、数据提取	用户内容中的 JSON（见文档）
vpn	VPN 服务	用户内容中的 JSON（见文档）
multi-modal	多模态模型	标准聊天消息
other	其他所有类型	始终查阅文档

规则：对于 llm 以外的任何类别，请先调用 drain_provider_info 阅读文档。

---

决策树

选择协议

What provider do I want?
├── MPP provider (protocol="mpp")
│   ├── mppType="llm" → mpp_chat(provider, messages)
│   └── mppType="rest" → mpp_request(url, body)
│   └── Done. Payment was automatic.
│
└── DRAIN provider (protocol="drain")
    └── See DRAIN flow below

启动 DRAIN 会话

Do I have an active channel?
├── YES → Use drain_chat() with existing channelId
└── NO →
    ├── drain_balance() → Do I have USDC?
    │   ├── NO → Cannot proceed. Need USDC on Polygon.
    │   └── YES →
    │       ├── drain_providers() → Find provider
    │       │   ├── NO providers → Cannot proceed.
    │       │   └── Found provider →
    │       │       ├── drain_approve() → First time only
    │       │       └── drain_open_channel() → Get channelId
    │       │           └── drain_chat() → Send requests

结束 DRAIN 会话

Am I done with this task?
├── YES → drain_cooperative_close(channelId) → Instant refund
└── NO →
    ├── More requests soon? → Keep channel open
    └── Channel expired? → drain_close_channel(channelId) → Reclaim funds

选择金额和时长

用例	金额	时长
快速测试 / 单次查询	$0.50 - $1	1h
短任务（少量查询）	$2 - $5	4h
长时间会话	$5 - $20	24h
长期运行的 Agent	$20 - $100	7d

处理错误

"Insufficient balance"
→ Need more USDC. Check drain_balance().

"Insufficient allowance"
→ Run drain_approve().

"Channel not found"
→ channelId is wrong or channel was closed. Open new channel.

"Channel expired"
→ For drain_chat: Open a new channel.
→ For drain_close_channel: Expected. Proceed with close.

"Insufficient channel balance"
→ Channel deposit used up. Open new channel with more funds.

"Provider offline"
→ Use drain_providers() to find alternative provider.

---

设置

1. 安装

npm install -g drain-mcp

2. 创建钱包（本地）

在自己的机器上生成密钥——不会通过网络发送任何内容：

node -e "const w=require('ethers').Wallet.createRandom();console.log('Address:', w.address, '\nKey:', w.privateKey)"

3. 为钱包充值

向你的钱包地址发送 $1–5 USDC，使用 Polygon 主网。 请使用专用的小额钱包，切勿使用主钱包。

无需 POL——如果钱包中有至少 $5 USDC，我们会提供免费 Gas：

curl -X POST https://handshake58.com/api/gas-station \
  -H "Content-Type: application/json" \
  -d '{"address": "0x_your_wallet_address"}'

返回 0.1 POL（约 10K 笔交易）。只会发送你的公开地址。

4. 配置 MCP 客户端

{
  "mcpServers": {
    "drain": {
      "command": "drain-mcp",
      "env": { "DRAIN_PRIVATE_KEY": "0x..." }
    }
  }
}

环境变量

变量	必需	默认值	描述
DRAIN_PRIVATE_KEY	是	—	Polygon 钱包私钥（也用于 MPP/Tempo）
DRAIN_CHAIN_ID	否	137	137（Polygon）或 80002（Amoy 测试网）
DRAIN_RPC_URL	否	公共 RPC	自定义 Polygon RPC 端点
DRAIN_MPP_MAX_DEPOSIT	否	1	每个 MPP 会话存款的 USDC 上限

---

安全与隐私

密钥处理

DRAIN_PRIVATE_KEY 会由本地 MCP 进程加载到内存中，用于：

1. 为 DRAIN 通道签署 EIP-712 代金券（链下操作，无需网络请求）
2. 签署链上交易（在本地签名，仅广播签名）
3. 为 MPP 请求签署 Tempo 付款（由 mppx 处理，在本地签名）

密钥绝不会传输到任何服务器。服务提供方会根据链上状态验证签名。

支出限额

DRAIN： 智能合约会限制风险敞口：

• 最高支出 = 通道存款（由你选择金额）
• 通道有固定期限（由你选择）
• 到期后，可通过 drain_close_channel 收回未使用的资金

MPP： 每个请求都按服务提供方公布的价格单独付款。无需预存款。

两种协议均无定期收费，也不存储付款方式。

离开你设备的数据

• 发往 handshake58.com 的公开 API 查询（服务提供方列表、配置、通道状态）
• 发往服务提供方的请求消息（发送到服务提供方的 apiUrl，而非 Handshake58）
• 已签名的付款代金券（包含加密签名，不包含密钥）
• 已签名的链上交易（广播到 Polygon RPC）

保留在本地的数据

• 私钥（绝不传输）
• 所有加密操作（签名在进程内完成）

外部端点

MCP 服务发起的每个网络请求：

端点	方法	发送的数据	是否传输密钥？
handshake58.com/api/mcp/providers	GET	无（公开目录）	否
handshake58.com/api/directory/config	GET	无（读取费用钱包）	否
handshake58.com/api/channels/status	GET	channelId（公开的链上数据）	否
handshake58.com/api/gas-station	POST	钱包地址	否
handshake58.com/api/telemetry	POST	服务提供方 ID、延迟、状态、费用	否
handshake58.com/api/feedback	POST	服务提供方 ID、结果	否
Provider apiUrl /v1/docs	GET	无（获取使用文档）	否
Provider apiUrl /v1/chat/completions	POST	请求消息 + 已签名代金券（DRAIN）	否
Provider apiUrl /v1/close-channel	POST	channelId + 关闭签名	否
MPP 服务提供方端点	POST	请求正文 + Tempo 付款（通过 mppx）	否
Polygon RPC（链上交易）	POST	已签名交易	否

安全措施

• 使用专用钱包，余额为 $1–5 USDC。切勿重复使用主钱包。
• 始终在本地生成密钥。密钥会保留在你的设备上。
• 开源：github.com/kimbo128/DRAIN（采用 MIT 许可证）
• 以小额存款开启通道。使用完毕后及时关闭。

---

链接

• NPM：https://www.npmjs.com/package/drain-mcp
• GitHub：https://github.com/kimbo128/DRAIN
• 市场：https://handshake58.com
• 服务提供方目录：https://handshake58.com/directory
• 合约：0x0C2B3aA1e80629D572b1f200e6DF3586B3946A8A（Polygon 主网）