{"id":"1426d524-b556-44d9-a48b-eb6556d3b6cd","slug":"crypto-agent-fleet","kind":"mcp","name":"crypto-agent-fleet","summary":"Autonomous crypto portfolio management using Claude Code Agent Teams — yield farming, technical trading, arbitrage, perpetuals, and prediction markets on Base & Polygon","owner":"joshuamoreno1","repoUrl":"https://github.com/joshuamoreno1/crypto-agent-fleet","license":"MIT","licenseTier":"permissive","trust":"community","stars":1,"match":null,"fewStars":true,"format":"mcp","createdAt":"2026-04-17T03:50:50.000Z","addedAt":"2026-10-21T04:29:04.299Z","logoUrl":"https://avatars.githubusercontent.com/u/1558591?u=85709a790e5e10042e3f93e327e989074bdd1054&v=4","linkOnly":false,"collection":null,"skillPath":null,"categories":["communication","developer-tools","data-analytics"],"tags":["agent-teams","ai-agents","anthropic","arbitrage","autonomous-agents","base","bun","claude-code"],"runtime":"binary","local":true,"cloudCapable":false,"cloudCapability":"unknown","cloudReadyOnPlatform":false,"needsApiKey":false,"reviewed":false,"syncedAt":"2026-10-23T03:33:03.919Z","sample":false,"url":"https://conduits.dev/tools/crypto-agent-fleet","language":"TypeScript","transports":["stdio"],"install":{},"requirements":{"env":[],"upstreamMayCharge":false},"tools":null,"readme":"# Crypto Agent Fleet\n\nA fleet of AI agents that manage a crypto portfolio autonomously on **Base** (Ethereum L2) and **Polygon** (Polymarket prediction markets). Built on [Claude Code](https://claude.ai/code) with Agent Teams, custom MCP servers, and Telegram for communication.\n\nThink of it as hiring a team of AI employees for your wallet: one analyzes markets, one manages risk, and one executes trades — all coordinated by a lead agent that reports to you via Telegram.\n\n> ## ⚠️ Experimental — Read Before Running\n>\n> This software signs real on-chain transactions with your real private key. **You can lose all the funds in the wallet.** Bugs, model errors, oracle failures, MEV, geo-blocks, hot wallet compromise, smart-contract exploits in the protocols listed below — any of these can wipe the wallet.\n>\n> - **Not financial advice.** Nothing here is a recommendation to trade, invest, or use any specific protocol.\n> - **Not audited.** The MCP servers, policy engine, and signing logic are reference code, not production-grade security software.\n> - **Start tiny.** Fund the wallet with an amount you can afford to lose entirely (≤ $50 USDC). Treat any positive return as a bonus.\n> - **You are the human-in-the-loop.** The policy engine raises trades over $10 to you for approval — if you reflexively approve everything via Telegram, you are the bug.\n> - **Your jurisdiction's rules apply.** Perpetuals (gTrade) and prediction markets (Polymarket) are restricted or illegal in some countries.\n>\n> By running this software you accept full responsibility for any losses. See [`LICENSE`](LICENSE) — provided AS-IS, no warranty.\n\n## What Does It Do?\n\nThe fleet runs 7 strategies automatically:\n\n| Strategy | What It Does | Risk |\n|----------|-------------|------|\n| **Yield Farming** | Deposits your stablecoins (USDC) in lending protocols (Aave, Compound) to earn interest — like a savings account but on-chain | Low |\n| **Technical Trading** | Buys/sells crypto tokens based on technical indicators (RSI, MACD, Bollinger Bands) | Medium |\n| **Cross-DEX Arbitrage** | Finds price differences for the same token across exchanges (Uniswap, Aerodrome, Curve) and profits from the gap | Medium |\n| **Perpetual Trading** | Trades forex (EUR/USD, GBP/USD), stocks (AAPL, TSLA, NVDA), commodities (gold, silver), and crypto with leverage via [gTrade](https://gains.trade) on Base | Medium-High |\n| **Prediction Markets** | Bets on real-world outcomes on [Polymarket](https://polymarket.com) when there's a mathematical edge (e.g., \"Will ETH hit $5k?\") | Medium |\n| **Airdrop Farming** | Interacts with new protocols that might reward early users with free tokens | Medium |\n| **Staking** | Holds cbETH (staked ETH) for passive staking yield, optionally compounded via Aave | Low |\n\n## How It Works\n\n```\nYou (Telegram) <--> Overseer (Lead Agent, Opus)\n                        |\n              +---------+---------+\n              v                   v\n          Analyst              Trader\n         (Sonnet)             (Sonnet)\n      Monitors markets     Executes trades\n```\n\n1. **Overseer** (Opus) — The boss. Coordinates everything, evaluates risk, approves trades, and reports to you via Telegram\n2. **Analyst** (Sonnet) — Watches markets, generates trading signals, scans for arbitrage opportunities and prediction market edge\n3. **Trader** (Sonnet) — Executes approved trades on Base (DeFi) and Polygon (Polymarket). Never acts without Overseer approval\n\nThe decision flow: **Analyst detects signal -> Overseer evaluates + risk-checker -> Trader executes (if approved)**\n\nEvery trade goes through a **policy engine** that enforces spending limits, protocol allowlists, and requires your approval for anything above $10.\n\n## Safety Features\n\n- **Spending limits**: Max $10/trade, $20/day, $50/week — all configurable in `config/policy.json`\n- **Allowlisted protocols only**: Uniswap, Aerodrome, Aave, Compound, Curve, gTrade — anything else requires your approval\n- **Encrypted keystore**: Your private key is AES-256 encrypted, password only held in memory at runtime\n- **Mandatory stop losses**: Every leveraged position (gTrade perpetuals) requires a stop loss — no exceptions\n- **Auto-pause**: Trading stops automatically if win rate drops below 30% or cumulative losses exceed thresholds\n- **Full audit log**: Every transaction is logged to `data/audit-log/` with timestamp, amount, tx hash, and result\n- **Human-in-the-loop**: All trades above $10 and all new protocol interactions require your explicit Telegram approval\n\n## Prerequisites\n\n- **macOS** (Apple Silicon recommended; the optional heartbeat uses launchd and is macOS-only — the fleet itself runs anywhere Bun + Claude Code do)\n- **[Bun](https://bun.sh/)** v1.3+ — JavaScript runtime\n- **[Claude Code](https://claude.ai/code)** v2.1.32+ with a Claude Max subscription\n- **A crypto wallet** (MetaMask or similar) funded with:\n  - **USDC** on Base — trading capital (start with as little as $50)\n  - **ETH** on Base — for gas fees (~$0.001 per tx, so $1 is plenty)\n- **A Telegram bot** — free, takes 2 minutes to create\n\n## Costs\n\nWhat you actually pay:\n\n| Cost | Approx. | Notes |\n|---|---|---|\n| Claude Max subscription | $100–$200 / month | Required — the fleet runs on your Claude account |\n| Wallet seed capital | ≥ $50 USDC on Base | Start tiny. Money you can afford to lose |\n| Gas on Base | ~$0.001 per swap / lending tx | $1 of ETH lasts thousands of operations |\n| Bridge USDC → Polygon (optional, for Polymarket) | ~$0.50 | One-time via [across.to](https://across.to) |\n| Gas on Polygon (optional) | ~$0.10 in POL | One-time top-up |\n| Telegram bot | Free | — |\n\nSo the practical entry cost is **a Claude Max plan plus $50–$100 of crypto**. Everything else is rounding error.\n\n## Setup Guide\n\n### 1. Clone and Install\n\n```bash\ngit clone https://github.com/<YOUR_GITHUB_USERNAME>/crypto-agent-fleet.git\ncd crypto-agent-fleet\n\n# Install MCP server dependencies\ncd mcp-servers/blockchain && bun install && cd ../..\ncd mcp-servers/prices && bun install && cd ../..\ncd mcp-servers/signer && bun install && cd ../..\ncd mcp-servers/polymarket && bun install && cd ../..\n```\n\n### 2. Set Up Your Wallet\n\nExport your MetaMask private key (Account Details -> Export Private Key) and encrypt it:\n\n```bash\nread -s -p \"Paste your private key: \" PK\necho \"$PK\" | openssl enc -aes-256-cbc -pbkdf2 -out keystore/wallet.key.enc\nchmod 600 keystore/wallet.key.enc\nunset PK\n```\n\nIt will ask for a password — **remember it**, you'll need it every time you start the fleet.\n\nUpdate `config/wallet.json` with your wallet address.\n\n### 3. Create a Telegram Bot\n\n1. Open Telegram, search for **@BotFather**, send `/newbot`\n2. Pick a name and username for your bot\n3. Save the **token** BotFather gives you\n\nFind your **Telegram User ID**:\n1. Search for **@userinfobot** on Telegram, send `/start`\n2. It replies with your user ID (a number like `1234567890`)\n\nNow update two files:\n- `CLAUDE.md` — fill in your wallet address, Telegram chat ID, and bot username in the \"Owner — Contact Info\" section\n- `scripts/start-fleet.sh` — replace `<YOUR_TELEGRAM_BOT_TOKEN>` with your bot token\n\n### 4. Set Up Polymarket (Optional)\n\nSkip this if you don't want prediction market trading.\n\n1. **Bridge USDC** from Base to Polygon using [across.to](https://across.to)\n2. **Get POL** for gas (~$0.10) via [QuickSwap](https://quickswap.exchange)\n3. **Generate API credentials**:\n   ```bash\n   read -s \"SIGNER_PASSWORD?Password: \" && export SIGNER_PASSWORD\n   node --experimental-strip-types mcp-servers/polymarket/gen-creds.ts\n   ```\n4. Add the output to your shell profile (`~/.zshrc`):\n   ```bash\n   export POLYMARKET_API_KEY=\"...\"\n   export POLYMARKET_API_SECRET=\"...\"\n   export POLYMARKET_PASSPHRASE=\"...\"\n   ```\n\n> Polymarket is geoblocked in some countries. [Cloudflare WARP](https://1.1.1.1/) (free) works as a VPN.\n\n### 5. Start the Fleet\n\n```bash\n./scripts/start-fleet.sh\n```\n\nIt will ask for your keystore password, start Claude Code with the Telegram channel, create the Agent Team, run an initial portfolio scan, and start reporting to you via Telegram.\n\n**What success looks like:**\n1. Terminal prints `🚀 Starting Crypto Agent Fleet...` and then a Claude Code session header.\n2. Within ~30 seconds, your Telegram bot sends a message like `🎯 Overseer online. Wallet 0x… has $… USDC on Base and $… on Polygon.`\n3. The agents read `data/memory/`, then send a \"first scan\" summary covering balances, current yields, and any pending signals.\n\nIf nothing arrives in Telegram after a minute, see **Troubleshooting** below.\n\n### 6. Install the Heartbeat (recommended, macOS)\n\n`scripts/heartbeat.sh` pings the Overseer through your Telegram bot every 30 minutes so the fleet keeps scanning even when you're not actively chatting. Different prompts fire at morning briefing (08:00), daily close (20:00), Sunday weekly review (10:00), and a quick check at all other times.\n\n```bash\n# Edit scripts/heartbeat.sh — paste your TELEGRAM_BOT_TOKEN and CHAT_ID\n# Copy the plist and edit it (replace <ABSOLUTE_PATH_TO_REPO> and <YOUR_HOME>):\ncp scripts/heartbeat.plist ~/Library/LaunchAgents/com.crypto-agent-fleet.heartbeat.plist\n./scripts/install-heartbeat.sh\n# Logs:      tail -f /tmp/crypto-agent-fleet-heartbeat.log\n# Uninstall: ./scripts/uninstall-heartbeat.sh\n```\n\nOn non-macOS systems you can recreate this with `cron`, `systemd --user`, or any scheduler — the script itself is a plain shell + `curl` POST to the Telegram Bot API.\n\n### 7. Talk to Your Fleet\n\nSend messages to your Telegram bot:\n\n| Message | What Happens |\n|---------|-------------|\n| \"What's my balance?\" | Full portfolio overview across Base and Polygon |\n| \"Swap $5 USDC to ETH\" | Executes with policy check + your approval |\n| \"Any arbitrage opportunities?\" | Cross-DEX price scan |\n| \"What are current yields?\" | Aave/Compound APY comparison |\n| \"Open a long on EUR/USD\" | gTrade perpetual with stop loss (requires approval) |\n| \"Scan Polymarket for crypto bets\" | Prediction market edge analysis |\n| \"How's my P&L today?\" | Daily profit/loss breakdown by strategy |\n\n## Troubleshooting\n\n| Symptom | Likely cause | Fix |\n|---|---|---|\n| Telegram bot shows \"typing…\" forever, never replies | Stale `telegram` plugin process from a previous run holding the long-poll connection (Telegram returns 409 Conflict to the new one) | `start-fleet.sh` already runs `pkill -9 -f \"plugin:telegram\"` before launching — if it still happens, run those `pkill` lines manually, wait 3 s, retry |\n| `Could not decrypt keystore. Wrong password?` | Typo'd the keystore password, or the encrypted file was created with different OpenSSL defaults | Re-export the private key and re-run the `openssl enc` step from §2 |\n| Trader replies \"policy violation: target address … not in allowed protocols list\" | The destination contract isn't in `config/policy.json` → `allowed_protocols` | Either it's a legit new protocol (add it via Telegram approval flow and update the file), or it's a hallucinated/wrong address — investigate before allowlisting |\n| Polymarket tools return `403` or `geo-restricted` | Polymarket geo-blocks several regions | Run [Cloudflare WARP](https://1.1.1.1/) (free) or another VPN, then restart the fleet |\n| `SIGNER_PASSWORD is not set` from `gen-creds.ts` | You ran the Polymarket creds generator without exporting the keystore password in this shell | `read -s \"SIGNER_PASSWORD?Password: \" && export SIGNER_PASSWORD` first |\n| Heartbeat installed but no messages | `BOT_TOKEN` / `CHAT_ID` not filled in `scripts/heartbeat.sh`, or the plist still has `<ABSOLUTE_PATH_TO_REPO>` placeholders | Check `tail -f /tmp/crypto-agent-fleet-heartbeat.log` and re-edit |\n| Overseer keeps saying \"I need owner approval\" for everything | Working as designed — every trade > $10 and every new protocol needs your Telegram OK. Resist the urge to auto-approve everything | Tune limits in `config/policy.json` if (and only if) you've thought through the risk |\n\n## Project Structure\n\n```\ncrypto-agent-fleet/\n├── CLAUDE.md                      # Agent instructions (the brain)\n├── .mcp.json                      # MCP server configuration\n├── .claude/\n│   ├── settings.json              # Claude Code permissions reference\n│   ├── agents/                    # Agent role definitions\n│   │   ├── analyst.md             #   Market analysis teammate\n│   │   ├── trader.md              #   Trade execution teammate\n│   │   ├── risk-checker.md        #   Pre-trade risk evaluation\n│   │   └── portfolio-analyzer.md  #   Portfolio P&L analysis\n│   └── skills/                    # Strategy implementations\n│       ├── technical-analysis.md  #   RSI, MACD, Bollinger signals\n│       ├── swap-tokens.md         #   DEX token swaps\n│       ├── yield-monitor.md       #   Lending APY monitoring\n│       ├── arbitrage-scanner.md   #   Cross-DEX price scanning\n│       ├── polymarket-trading.md  #   Prediction market edge trading\n│       ├── latency-arbitrage.md   #   Spot vs Polymarket gaps\n│       ├── airdrop-farming.md     #   Pre-token protocol interactions\n│       ├── staking.md             #   ETH/cbETH staking\n│       ├── check-balance.md       #   Read wallet balances\n│       ├── post-trade-review.md   #   Post-trade logging + learning\n│       ├── weekly-review.md       #   Weekly performance review\n│       └── memory.md              #   Agent memory management\n├── config/\n│   ├── wallet.json                # Wallet address, tokens, contract addresses\n│   ├── policy.json                # Spending limits, allowed protocols, risk params\n│   └── strategy-playbook.md       # Strategy triggers and position sizing\n├── mcp-servers/                   # Backend services (TypeScript + Bun)\n│   ├── blockchain/index.ts        #   On-chain reads + tx encoding (Base)\n│   ├── prices/index.ts            #   CoinGecko market data\n│   ├── signer/index.ts            #   Transaction signing + policy enforcement\n│   └── polymarket/index.ts        #   Polymarket CLOB API (Polygon)\n├── data/\n│   ├── audit-log/                 # Every signed transaction (JSONL, by date)\n│   └── memory/\n│       ├── lessons.md             # Mistakes the fleet won't repeat\n│       ├── strategy-stats.json    # Win rates and P&L by strategy\n│       ├── market-patterns.md     # Observed market behavior\n│       └── trade-journal/         # Individual trade logs\n├── keystore/\n│   └── wallet.key.enc            # Your encrypted private key (AES-256)\n└── scripts/\n    ├── start-fleet.sh             # Start the fleet (edit with your bot token)\n    ├── init-prompt.txt            # Initial prompt that boots the Agent Team\n    ├── heartbeat.sh               # Periodic Telegram prompt to the Overseer\n    ├── heartbeat.plist            # macOS launchd job for the heartbeat\n    ├── install-heartbeat.sh       # Install the heartbeat as a launchd job\n    └── uninstall-heartbeat.sh     # Remove the heartbeat launchd job\n```\n\n## Customizing\n\n**Spending limits** — Edit `config/policy.json` to change per-transaction, daily, and weekly limits.\n\n**Allowed tokens** — Add tokens to `config/policy.json` under `allowed_tokens`. The fleet only trades tokens on this list.\n\n**Strategy allocations** — Edit target allocations in `CLAUDE.md` under \"Active Strategies\" and in `config/strategy-playbook.md`.\n\n**Language** — The fleet defaults to English. Change the language instruction in `CLAUDE.md` to have it report in any language.\n\n**Leverage limits** — gTrade perpetual leverage caps are in `config/policy.json` under `perpetual_limits` (default: crypto 10x, forex 25x, commodities 10x, stocks 5x).\n\n## How the Fleet Learns\n\nThe agents have a memory system — they learn from every trade and never repeat mistakes:\n\n```\nTrade executes -> post-trade-review logs result\n              -> updates lessons.md (if error)\n              -> updates strategy-stats.json (win/loss)\n              -> writes to trade-journal/\n\nEvery Sunday -> weekly-review aggregates performance\n            -> adjusts strategy parameters\n            -> sends you a full report\n```\n\nIf a strategy keeps losing, the fleet **automatically pauses it** and alerts you.\n\n## Networks\n\n| Network | Chain ID | Used For |\n|---------|----------|----------|\n| **Base** | 8453 | DeFi (yield, swaps, arbitrage, gTrade perpetuals) |\n| **Polygon** | 137 | Prediction markets (Polymarket) |\n\n## License\n\nMIT\n"}