Skip to main content

​
Overview

This example demonstrates a trading agent that monitors cryptocurrency markets, forms opinions based on data, and makes paper trading decisions. It shows how to build plugins that work together.

View Source

See the complete example agent implementation on GitHub

​
What It Does

  • Fetches real-time market data from CoinGecko
  • Makes paper trading decisions based on agent mood and market conditions
  • Tracks portfolio performance over time
  • Only trades when agent is expressive and healthy

​
Architecture

Market Data Plugin ──┐
                     ├──► Agent Tick ──► Trading Decision ──► Paper Portfolio
News Plugin ─────────┘
Two plugins work together:
  1. Markets Plugin — Fetches and caches price data
  2. Paper Trading Plugin — Manages portfolio, executes trades

​
Markets Plugin

Fetches cryptocurrency prices and detects significant moves. Key features:
  • Configurable symbol list
  • Automatic refresh on interval
  • Caches data between ticks
  • Actions: getMarkets(), getPrice(symbol)
export function createMarketsPlugin(config: {
  symbols: string[];
  refreshMinutes: number;
}): Plugin {
  // Fetch from CoinGecko API
  // Cache between refreshes
  // Log significant moves (>5%)
}
Reference: See src/services/market.ts in the example agent.

​
Paper Trading Plugin

Manages a simulated portfolio with position limits. Key features:
  • Initial cash balance
  • Max position size (% of portfolio)
  • Only trades when mood is expressive and health >50
  • Actions: buy(symbol, price), sell(symbol, price), getPortfolio()
export function createPaperTradingPlugin(config: {
  initialCash: number;
  maxPositionPercent: number;
}): Plugin {
  // Track positions and cash
  // Enforce position limits
  // Log trades and P&L
}
Reference: See the src/plugins directory for plugin patterns.

​
Plugin Dependencies

The trading plugin depends on the markets plugin: 
{
  name: "paper-trading",
  dependencies: ["markets"],
  // ...
}
This ensures markets data is available when making trading decisions.

​
Agent Setup

const agent = new Agent({
  backend: new ConvexBackend({ url: process.env.CONVEX_URL }),
  plugins: [
    createMarketsPlugin({
      symbols: ["bitcoin", "ethereum", "solana"],
      refreshMinutes: 5,
    }),
    createPaperTradingPlugin({
      initialCash: 10000,
      maxPositionPercent: 0.2,  // Max 20% per position
    }),
  ],
});

​
Risk Controls

This example includes several safeguards:
ControlDescription
Position limitsMax 20% of portfolio per trade
Mood gatingOnly trades when expressive
Health thresholdRequires health >50
Paper tradingNo real money at risk

​
Running

npm run dev

# Check portfolio
curl http://localhost:3001/actions/paper-trading/getPortfolio

# Manual trade (for testing)
curl -X POST http://localhost:3001/actions/paper-trading/buy \
  -H "Authorization: Bearer $TOKEN" \
  -d '{"symbol": "ETH", "price": 2000}'
This is for educational purposes only. Never trade real money based on AI agent decisions without proper risk management and human oversight.

​
Next Steps

Social Agent

Build an agent that posts content.

Custom Plugins

Learn plugin development patterns.