three.ws Copy Trading

[three.ws]

@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.

[npm] [license] [node] [MCP Registry] [three.ws]

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": "<code>", "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}