Trading Agent

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:

Markets Plugin — Fetches and caches price data
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:

Control	Description
Position limits	Max 20% of portfolio per trade
Mood gating	Only trades when expressive
Health threshold	Requires health >50
Paper trading	No 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.

Templates

Overview

View Source

What It Does

Architecture

Markets Plugin

Paper Trading Plugin

Plugin Dependencies

Agent Setup

Risk Controls

Running

Next Steps

Social Agent

Custom Plugins

​Overview

View Source

​What It Does

​Architecture

​Markets Plugin

​Paper Trading Plugin

​Plugin Dependencies

​Agent Setup

​Risk Controls

​Running

​Next Steps

Social Agent

Custom Plugins

Overview

What It Does

Architecture

Markets Plugin

Paper Trading Plugin

Plugin Dependencies

Agent Setup

Risk Controls

Running

Next Steps