three.ws Copy Trading

@three-ws/copy-mcp

Drive your three.ws copy-trading from any AI agent — follow leaders, tune sizing & guard rules, work the copy-intent inbox, and track fees owed. Headless, non-custodial.

---

A Model Context Protocol server that turns the three.ws copy-trading control surface — follow/unfollow leaders, tune guard rules, read your copy-intent inbox, and see fees owed — into agent-drivable tools over stdio. Everything the website's copy dashboard does, headless.

Non-custodial by design. three.ws never signs a transaction or holds your funds. When a leader you follow trades, the engine produces a sized, guard-checked copy INTENT that you (or your agent) act on from your own wallet. Every order is clamped to your per-trade cap and your remaining daily budget, so a runaway leader can never drain you. Performance fees settle in $THREE.

Install

npm install @three-ws/copy-mcp

Or run with npx (no install):

npx @three-ws/copy-mcp

Quick start

Copy trading is account-scoped, so set THREE_WS_API_KEY to a three.ws API key (sk_live_… / sk_test_…) or OAuth access token. Mint one at three.ws/dashboard/developers.

Claude Code, one line:

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 or mcp.json):

{

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

Inspect the surface with the MCP Inspector:

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

Discovery (which leaders to follow) lives in @three-ws/intel-mcp → copy_smart_wallets. This server manages the follows you commit to.

Tools

All reads return live data (counts, intents, and accruals move between calls), so none are idempotent.

Input parameters

`list_subscriptions` — none.

`create_subscription` — leader_agent_id (required, UUID), copier_wallet (required, base58), network (mainnet | devnet, default mainnet), sizing_rule (fixed | multiplier | pct_balance, default fixed), fixed_sol (required for fixed sizing), multiplier (default 0.1), pct_balance (0–100), per_trade_cap_sol (default 0.5), min_order_sol (default 0.02), daily_budget_sol (default 1), max_open_copies (1–100, default 5), mcap_floor_usd, mcap_ceiling_usd, copy_sells (default true), require_safety_pass (default false), min_oracle_score (0–100), perf_fee_bps (0–3000, default 1000), telegram_chat_id.

`update_subscription` — id (required, UUID) plus any of: status (active | paused | stopped), and the sizing/guard fields from create_subscription (each optional; pass null to clear mcap_floor_usd / mcap_ceiling_usd / min_oracle_score / telegram_chat_id). Only the fields you pass change. leader_agent_id and network cannot be changed here: they identify the subscription, so re-pointing them means creating a new follow with create_subscription.

`cancel_subscription` — id (required, UUID).

`get_executions` — status (pending | acted | dismissed | skipped | expired | all, default pending), limit (1–100, default 50).

`record_execution` — id (required, UUID), action (acted | dismissed), tx_signature (optional, recorded only when acted).

`get_earnings` — agent_id (optional UUID — provide for a leader's public aggregate; omit for your own rollup), network (mainnet | devnet, default mainnet).

Example

// 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…" } }

Requirements

• Node.js >= 20.
• A three.ws account credential in THREE_WS_API_KEY (all tools except a leader's public aggregate earnings).
• Network access to https://three.ws (or your own THREE_WS_BASE).

Environment variables

Errors

A failed tool call returns an MCP error result (isError: true) whose text is a single JSON object: { "ok": false, "error": " ", "message": "…" }, plus status on upstream rejections:

Links

• Homepage: https://three.ws
• Changelog: https://three.ws/changelog
• Issues: https://github.com/nirholas/three.ws/issues
• License: Apache-2.0, see LICENSE

---

Part of the three.ws SDK suite — 3D AI agents, on-chain identity, and agent payments.

Website · Changelog · GitHub