Crypto Agent Fleet

Crypto Agent Fleet

A fleet of AI agents that manage a crypto portfolio autonomously on Base (Ethereum L2) and Polygon (Polymarket prediction markets). Built on Claude Code with Agent Teams, custom MCP servers, and Telegram for communication.

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

> ## ⚠️ Experimental — Read Before Running > > 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. > > - Not financial advice. Nothing here is a recommendation to trade, invest, or use any specific protocol. > - Not audited. The MCP servers, policy engine, and signing logic are reference code, not production-grade security software. > - Start tiny. Fund the wallet with an amount you can afford to lose entirely (≤ $50 USDC). Treat any positive return as a bonus. > - 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. > - Your jurisdiction's rules apply. Perpetuals (gTrade) and prediction markets (Polymarket) are restricted or illegal in some countries. > > By running this software you accept full responsibility for any losses. See [LICENSE](LICENSE) — provided AS-IS, no warranty.

What Does It Do?

The fleet runs 7 strategies automatically:

| Strategy | What It Does | Risk | |----------|-------------|------| | Yield Farming | Deposits your stablecoins (USDC) in lending protocols (Aave, Compound) to earn interest — like a savings account but on-chain | Low | | Technical Trading | Buys/sells crypto tokens based on technical indicators (RSI, MACD, Bollinger Bands) | Medium | | Cross-DEX Arbitrage | Finds price differences for the same token across exchanges (Uniswap, Aerodrome, Curve) and profits from the gap | Medium | | Perpetual Trading | Trades forex (EUR/USD, GBP/USD), stocks (AAPL, TSLA, NVDA), commodities (gold, silver), and crypto with leverage via gTrade on Base | Medium-High | | Prediction Markets | Bets on real-world outcomes on Polymarket when there's a mathematical edge (e.g., "Will ETH hit $5k?") | Medium | | Airdrop Farming | Interacts with new protocols that might reward early users with free tokens | Medium | | Staking | Holds cbETH (staked ETH) for passive staking yield, optionally compounded via Aave | Low |

How It Works

You (Telegram)  Overseer (Lead Agent, Opus)
                        |
              +---------+---------+
              v                   v
          Analyst              Trader
         (Sonnet)             (Sonnet)
      Monitors markets     Executes trades

1. Overseer (Opus) — The boss. Coordinates everything, evaluates risk, approves trades, and reports to you via Telegram
2. Analyst (Sonnet) — Watches markets, generates trading signals, scans for arbitrage opportunities and prediction market edge
3. Trader (Sonnet) — Executes approved trades on Base (DeFi) and Polygon (Polymarket). Never acts without Overseer approval

The decision flow: Analyst detects signal -> Overseer evaluates + risk-checker -> Trader executes (if approved)

Every trade goes through a policy engine that enforces spending limits, protocol allowlists, and requires your approval for anything above $10.

Safety Features

• Spending limits: Max $10/trade, $20/day, $50/week — all configurable in config/policy.json
• Allowlisted protocols only: Uniswap, Aerodrome, Aave, Compound, Curve, gTrade — anything else requires your approval
• Encrypted keystore: Your private key is AES-256 encrypted, password only held in memory at runtime
• Mandatory stop losses: Every leveraged position (gTrade perpetuals) requires a stop loss — no exceptions
• Auto-pause: Trading stops automatically if win rate drops below 30% or cumulative losses exceed thresholds
• Full audit log: Every transaction is logged to data/audit-log/ with timestamp, amount, tx hash, and result
• Human-in-the-loop: All trades above $10 and all new protocol interactions require your explicit Telegram approval

Prerequisites

• macOS (Apple Silicon recommended; the optional heartbeat uses launchd and is macOS-only — the fleet itself runs anywhere Bun + Claude Code do)
• Bun v1.3+ — JavaScript runtime
• Claude Code v2.1.32+ with a Claude Max subscription
• A crypto wallet (MetaMask or similar) funded with:
• USDC on Base — trading capital (start with as little as $50)
• ETH on Base — for gas fees (~$0.001 per tx, so $1 is plenty)
• A Telegram bot — free, takes 2 minutes to create

Costs

What you actually pay:

| Cost | Approx. | Notes | |---|---|---| | Claude Max subscription | $100–$200 / month | Required — the fleet runs on your Claude account | | Wallet seed capital | ≥ $50 USDC on Base | Start tiny. Money you can afford to lose | | Gas on Base | ~$0.001 per swap / lending tx | $1 of ETH lasts thousands of operations | | Bridge USDC → Polygon (optional, for Polymarket) | ~$0.50 | One-time via across.to | | Gas on Polygon (optional) | ~$0.10 in POL | One-time top-up | | Telegram bot | Free | — |

So the practical entry cost is a Claude Max plan plus $50–$100 of crypto. Everything else is rounding error.

Setup Guide

1. Clone and Install

git clone https://github.com//crypto-agent-fleet.git
cd crypto-agent-fleet

# Install MCP server dependencies
cd mcp-servers/blockchain && bun install && cd ../..
cd mcp-servers/prices && bun install && cd ../..
cd mcp-servers/signer && bun install && cd ../..
cd mcp-servers/polymarket && bun install && cd ../..

2. Set Up Your Wallet

Export your MetaMask private key (Account Details -> Export Private Key) and encrypt it:

read -s -p "Paste your private key: " PK
echo "$PK" | openssl enc -aes-256-cbc -pbkdf2 -out keystore/wallet.key.enc
chmod 600 keystore/wallet.key.enc
unset PK

It will ask for a password — remember it, you'll need it every time you start the fleet.

Update config/wallet.json with your wallet address.

3. Create a Telegram Bot

1. Open Telegram, search for @BotFather, send /newbot
2. Pick a name and username for your bot
3. Save the token BotFather gives you

Find your Telegram User ID:

1. Search for @userinfobot on Telegram, send /start
2. It replies with your user ID (a number like 1234567890)

Now update two files:

• CLAUDE.md — fill in your wallet address, Telegram chat ID, and bot username in the "Owner — Contact Info" section
• scripts/start-fleet.sh — replace `` with your bot token

4. Set Up Polymarket (Optional)

Skip this if you don't want prediction market trading.

1. Bridge USDC from Base to Polygon using across.to
2. Get POL for gas (~$0.10) via QuickSwap
3. Generate API credentials:

``bash read -s "SIGNER_PASSWORD?Password: " && export SIGNER_PASSWORD node --experimental-strip-types mcp-servers/polymarket/gen-creds.ts ``

1. Add the output to your shell profile (~/.zshrc):

``bash export POLYMARKET_API_KEY="..." export POLYMARKET_API_SECRET="..." export POLYMARKET_PASSPHRASE="..." ``

> Polymarket is geoblocked in some countries. Cloudflare WARP (free) works as a VPN.

5. Start the Fleet

./scripts/start-fleet.sh

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

What success looks like:

1. Terminal prints 🚀 Starting Crypto Agent Fleet... and then a Claude Code session header.
2. Within ~30 seconds, your Telegram bot sends a message like 🎯 Overseer online. Wallet 0x… has $… USDC on Base and $… on Polygon.
3. The agents read data/memory/, then send a "first scan" summary covering balances, current yields, and any pending signals.

If nothing arrives in Telegram after a minute, see Troubleshooting below.

6. Install the Heartbeat (recommended, macOS)

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.

# Edit scripts/heartbeat.sh — paste your TELEGRAM_BOT_TOKEN and CHAT_ID
# Copy the plist and edit it (replace  and ):
cp scripts/heartbeat.plist ~/Library/LaunchAgents/com.crypto-agent-fleet.heartbeat.plist
./scripts/install-heartbeat.sh
# Logs:      tail -f /tmp/crypto-agent-fleet-heartbeat.log
# Uninstall: ./scripts/uninstall-heartbeat.sh

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

7. Talk to Your Fleet

Send messages to your Telegram bot:

| Message | What Happens | |---------|-------------| | "What's my balance?" | Full portfolio overview across Base and Polygon | | "Swap $5 USDC to ETH" | Executes with policy check + your approval | | "Any arbitrage opportunities?" | Cross-DEX price scan | | "What are current yields?" | Aave/Compound APY comparison | | "Open a long on EUR/USD" | gTrade perpetual with stop loss (requires approval) | | "Scan Polymarket for crypto bets" | Prediction market edge analysis | | "How's my P&L today?" | Daily profit/loss breakdown by strategy |

Troubleshooting

| Symptom | Likely cause | Fix | |---|---|---| | 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 | | 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 | | 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 | | Polymarket tools return 403 or geo-restricted | Polymarket geo-blocks several regions | Run Cloudflare WARP (free) or another VPN, then restart the fleet | | 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 | | Heartbeat installed but no messages | BOT_TOKEN / CHAT_ID not filled in scripts/heartbeat.sh, or the plist still has ` placeholders | Check tail -f /tmp/crypto-agent-fleet-heartbeat.log and re-edit | | 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 |

Project Structure

crypto-agent-fleet/
├── CLAUDE.md                      # Agent instructions (the brain)
├── .mcp.json                      # MCP server configuration
├── .claude/
│   ├── settings.json              # Claude Code permissions reference
│   ├── agents/                    # Agent role definitions
│   │   ├── analyst.md             #   Market analysis teammate
│   │   ├── trader.md              #   Trade execution teammate
│   │   ├── risk-checker.md        #   Pre-trade risk evaluation
│   │   └── portfolio-analyzer.md  #   Portfolio P&L analysis
│   └── skills/                    # Strategy implementations
│       ├── technical-analysis.md  #   RSI, MACD, Bollinger signals
│       ├── swap-tokens.md         #   DEX token swaps
│       ├── yield-monitor.md       #   Lending APY monitoring
│       ├── arbitrage-scanner.md   #   Cross-DEX price scanning
│       ├── polymarket-trading.md  #   Prediction market edge trading
│       ├── latency-arbitrage.md   #   Spot vs Polymarket gaps
│       ├── airdrop-farming.md     #   Pre-token protocol interactions
│       ├── staking.md             #   ETH/cbETH staking
│       ├── check-balance.md       #   Read wallet balances
│       ├── post-trade-review.md   #   Post-trade logging + learning
│       ├── weekly-review.md       #   Weekly performance review
│       └── memory.md              #   Agent memory management
├── config/
│   ├── wallet.json                # Wallet address, tokens, contract addresses
│   ├── policy.json                # Spending limits, allowed protocols, risk params
│   └── strategy-playbook.md       # Strategy triggers and position sizing
├── mcp-servers/                   # Backend services (TypeScript + Bun)
│   ├── blockchain/index.ts        #   On-chain reads + tx encoding (Base)
│   ├── prices/index.ts            #   CoinGecko market data
│   ├── signer/index.ts            #   Transaction signing + policy enforcement
│   └── polymarket/index.ts        #   Polymarket CLOB API (Polygon)
├── data/
│   ├── audit-log/                 # Every signed transaction (JSONL, by date)
│   └── memory/
│       ├── lessons.md             # Mistakes the fleet won't repeat
│       ├── strategy-stats.json    # Win rates and P&L by strategy
│       ├── market-patterns.md     # Observed market behavior
│       └── trade-journal/         # Individual trade logs
├── keystore/
│   └── wallet.key.enc            # Your encrypted private key (AES-256)
└── scripts/
    ├── start-fleet.sh             # Start the fleet (edit with your bot token)
    ├── init-prompt.txt            # Initial prompt that boots the Agent Team
    ├── heartbeat.sh               # Periodic Telegram prompt to the Overseer
    ├── heartbeat.plist            # macOS launchd job for the heartbeat
    ├── install-heartbeat.sh       # Install the heartbeat as a launchd job
    └── uninstall-heartbeat.sh     # Remove the heartbeat launchd job

Customizing

Spending limits — Edit config/policy.json to change per-transaction, daily, and weekly limits.

Allowed tokens — Add tokens to config/policy.json under allowed_tokens. The fleet only trades tokens on this list.

Strategy allocations — Edit target allocations in CLAUDE.md under "Active Strategies" and in config/strategy-playbook.md.

Language — The fleet defaults to English. Change the language instruction in CLAUDE.md to have it report in any language.

Leverage limits — gTrade perpetual leverage caps are in config/policy.json under perpetual_limits (default: crypto 10x, forex 25x, commodities 10x, stocks 5x).

How the Fleet Learns

The agents have a memory system — they learn from every trade and never repeat mistakes:

Trade executes -> post-trade-review logs result
              -> updates lessons.md (if error)
              -> updates strategy-stats.json (win/loss)
              -> writes to trade-journal/

Every Sunday -> weekly-review aggregates performance
            -> adjusts strategy parameters
            -> sends you a full report

If a strategy keeps losing, the fleet automatically pauses it and alerts you.

Netw

…

Source & license

This open-source MCP server is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: joshuamoreno1
• Source: joshuamoreno1/crypto-agent-fleet
• License: MIT

Install and usage instructions live in the source repository linked above.