three.ws Copy Trading

@three-ws/copy-mcp

通过任意 AI Agent 管理你的 three.ws 跟单交易——关注领袖、调整仓位和保护规则、处理跟单意向收件箱，并追踪应付费用。无头、非托管。

---

一个 Model Context Protocol 服务，可将 three.ws 的跟单交易控制界面——关注/取消关注领袖、调整保护规则、查看跟单意向收件箱和应付费用——转化为可通过 stdio 驱动 Agent 的工具。网站跟单仪表板的所有功能，都能以无头方式使用。

从设计上采用非托管模式。 three.ws 绝不会签署交易或持有你的资金。当你关注的领袖进行交易时，引擎会生成一个经过仓位计算和保护规则检查的跟单意向，由你（或你的 Agent）通过自己的钱包执行。每笔订单都会限制在你的单笔交易上限和剩余每日预算内，因此即使领袖失控，也无法耗尽你的资金。绩效费用以 $THREE 结算。

安装

npm install @three-ws/copy-mcp

也可以使用 npx 运行（无需安装）：

npx @three-ws/copy-mcp

快速开始

跟单交易按账户划分，因此请将 THREE_WS_API_KEY 设置为 three.ws API 密钥（sk_live_… / sk_test_…）或 OAuth 访问令牌。前往 three.ws/dashboard/developers 创建密钥。

Claude Code，一行命令：

claude mcp add copy --env THREE_WS_API_KEY=sk_live_xxx -- npx -y @three-ws/copy-mcp

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

{
	"mcpServers": {
		"copy": {
			"command": "npx",
			"args": ["-y", "@three-ws/copy-mcp"],
			"env": { "THREE_WS_API_KEY": "sk_live_xxx" }
		}
	}
}

使用 MCP Inspector 检查工具：

THREE_WS_API_KEY=sk_live_xxx npx -y @modelcontextprotocol/inspector npx @three-ws/copy-mcp

发现（要关注哪些领袖）由 @three-ws/intel-mcp 中的 copy_smart_wallets 提供。此服务负责管理你已确认关注的领袖。

工具

工具	类型	功能
list_subscriptions	只读	你关注的所有领袖——状态、仓位规则、完整保护规则集、绩效费用，以及实时待处理/已执行数量。
create_subscription	写入（幂等）	关注领袖 / 重新调整关注设置。定义其交易在你的钱包中的仓位大小。按领袖执行插入或更新。
update_subscription	写入（幂等）	暂停 / 恢复 / 停止关注，或更改仓位和保护规则。按 ID 更新——仅修改你传入的字段。
cancel_subscription	写入（破坏性）	停止关注：不再生成意向，保留历史记录。之后可通过 create_subscription 重新关注。
get_executions	只读	你的跟单意向收件箱和历史记录——币种、方向、计算后的订单规模、跳过原因、状态和记录的成交情况。
record_execution	写入	将待处理意向标记为已执行（可选提供你的成交签名）或已忽略。绝不会代你签署交易。
get_earnings	只读	你从所跟单的领袖处应得的费用——也可通过 agent_id 查看某位领袖公开的汇总收益。

所有读取都会返回实时数据（调用之间，数量、意向和累计费用都可能变化），因此这些操作都不是幂等的。

输入参数

list_subscriptions — 无。

create_subscription — leader_agent_id（必填，UUID）、copier_wallet（必填，base58）、network（mainnet | devnet，默认 mainnet）、sizing_rule（fixed | multiplier | pct_balance，默认 fixed）、fixed_sol（使用 fixed 仓位规则时必填）、multiplier（默认 0.1）、pct_balance（0–100）、per_trade_cap_sol（默认 0.5）、min_order_sol（默认 0.02）、daily_budget_sol（默认 1）、max_open_copies（1–100，默认 5）、mcap_floor_usd、mcap_ceiling_usd、copy_sells（默认 true）、require_safety_pass（默认 false）、min_oracle_score（0–100）、perf_fee_bps（0–3000，默认 1000）、telegram_chat_id。

update_subscription — id（必填，UUID），以及以下任意字段：status（active | paused | stopped），以及 create_subscription 中的仓位规则和保护字段（均为可选；传入 null 可清除 mcap_floor_usd / mcap_ceiling_usd / min_oracle_score / telegram_chat_id）。只有传入的字段会更改。此处无法更改 leader_agent_id 和 network：它们用于标识订阅，因此如需改为跟随其他对象，请使用 create_subscription 创建新的跟随订阅。

cancel_subscription — id（必填，UUID）。

get_executions — status（pending | acted | dismissed | skipped | expired | all，默认 pending）、limit（1–100，默认 50）。

record_execution — id（必填，UUID）、action（acted | dismissed）、tx_signature（可选，仅在 acted 时记录）。

get_earnings — agent_id（可选 UUID——提供后返回领队的公开汇总数据；省略则返回你自己的汇总数据）、network（mainnet | devnet，默认 mainnet）。

示例

// create_subscription — follow a leader, 0.05 SOL per copy, capped, safety-gated
> {
    "leader_agent_id": "8f3c…-uuid",
    "copier_wallet": "7Np…YourWallet",
    "sizing_rule": "fixed",
    "fixed_sol": 0.05,
    "per_trade_cap_sol": 0.1,
    "daily_budget_sol": 0.5,
    "mcap_floor_usd": 50000,
    "require_safety_pass": true
  }
{
  "ok": true,
  "subscription": {
    "id": "…",
    "status": "active",
    "network": "mainnet",
    // the create/update responses return the raw subscription row, so leader
    // name/image are null here; list_subscriptions joins the leader profile
    // and also adds pending_count / acted_count per row
    "leader": { "agent_id": "8f3c…", "name": null, "image": null, "wallet": null },
    "copier_wallet": "7Np…YourWallet",
    "sizing": { "rule": "fixed", "fixed_sol": 0.05, "multiplier": 0.1, "pct_balance": 0 },
    "guards": {
      "per_trade_cap_sol": 0.1, "min_order_sol": 0.02, "daily_budget_sol": 0.5,
      "max_open_copies": 5, "mcap_floor_usd": 50000, "mcap_ceiling_usd": null,
      "copy_sells": true, "require_safety_pass": true, "min_oracle_score": null
    },
    "perf_fee_bps": 1000
  }
}

// get_executions — the actionable inbox
> { "status": "pending", "limit": 5 }
{
  "ok": true,
  "status": "pending",
  "count": 1,
  "executions": [
    {
      "id": "…",
      "status": "pending",
      "leader": { "name": "…" },
      "coin": { "mint": "…", "symbol": "…", "name": "…" },
      "direction": "buy",
      "planned_sol": 0.05,
      "expires_at": "…"
    }
  ]
}

// record_execution — you bought it yourself; log the fill
> { "id": "…", "action": "acted", "tx_signature": "5xQ…" }
{ "ok": true, "execution": { "id": "…", "status": "acted", "tx_signature": "5xQ…" } }

要求

• Node.js >= 20。
• 需要在 THREE_WS_API_KEY 中提供 three.ws 账户凭据（领队的公开汇总收益工具除外）。
• 需要能够访问网络 https://three.ws（或你自己的 THREE_WS_BASE）。

环境变量

变量	必填	默认值	说明
THREE_WS_API_KEY	除使用 agent_id 的 get_earnings 外的所有工具	—	API 密钥（sk_live_…）或 OAuth 令牌。请妥善保管。
THREE_WS_BASE	否	https://three.ws	用于自托管 / 预览部署的覆盖值。
THREE_WS_TIMEOUT_MS	否	20000	每次请求的超时时间，单位为 ms。

错误

工具调用失败时会返回 MCP 错误结果（isError: true），其文本是一个 JSON 对象：{ "ok": false, "error": "<code>", "message": "…" }；上游拒绝请求时还会包含 status：

error	含义	恢复方法
missing_credential	工具需要身份验证，但未设置 THREE_WS_API_KEY。此错误会在发送任何请求前抛出。	设置密钥。
validation_error	客户端捕获到的参数错误，例如 sizing_rule: "fixed" 未提供正数 fixed_sol。	修正调用。
no_changes	调用 update_subscription 时只传入了 id。	至少传入一个要修改的字段。
not_found	为 update_subscription 提供的 id 不属于你的任何订阅。	检查 list_subscriptions。
upstream_error	API 拒绝了请求；status 包含 HTTP 状态码（400 表示字段错误，401 表示凭据错误或已过期，404 表示 cancel_subscription 找不到此订阅，409 表示 record_execution 找不到待处理的意图，429 表示请求过于频繁）。	根据消息和 status 采取相应措施。
timeout	在 THREE_WS_TIMEOUT_MS 指定的时间内未收到响应。	重试或延长超时时间。
network_error	请求未能到达 API（DNS、离线或 TLS 问题）。	检查网络连接和 THREE_WS_BASE。
bad_config	THREE_WS_TIMEOUT_MS 不是正数。此错误会在服务启动时（模块加载期间）抛出，因此进程会在提供服务前退出。	修正环境变量。

链接

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

---

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