Trading Agent Design Spec

Date: 2026-03-14 Status: Draft Approach: Full Cloudflare Native (Approach A)

Overview

A full-scale autonomous trading agent that operates across Crypto.com and Coinbase exchanges. The system uses Cloudflare Workers + Durable Objects for the agent runtime, a Python ML inference service on Fly.io for signal generation, and the existing React dashboard on Cloudflare Pages for monitoring and control.

Goals

• Autonomous trading with ML-driven signals across two exchanges
• Smart order routing for best execution (price + fees)
• Mandatory risk guardrails with configurable thresholds
• Portfolio aggregation across both exchanges in a single dashboard
• Manual override capability (always subject to guardrails)
• MCP server for conversational trading via Claude
• Production-grade: globally distributed, auto-scaling, persistent state

Non-Goals

• High-frequency trading (sub-second execution)
• Margin/leverage trading
• Cross-exchange arbitrage as a primary strategy
• Fiat on/off ramp management
• Multi-user / multi-tenant support (single operator)

Architecture

┌─────────────────────────────────────────────────────────────┐
│                    CLOUDFLARE PAGES                          │
│  React Dashboard (Vite + Tailwind)                          │
│  - Portfolio view (aggregated across exchanges)              │
│  - Live signals & trade history                              │
│  - Guardrail configuration                                   │
│  - Manual trade override / kill switch                       │
│  - Pair whitelist management                                 │
└─────────────────────────┬───────────────────────────────────┘
                          │ REST + WebSocket
┌─────────────────────────┼───────────────────────────────────┐
│               CLOUDFLARE WORKERS                             │
│                                                              │
│  Trading Agent API (TypeScript)                              │
│  - /api/portfolio    - /api/trades                           │
│  - /api/signals      - /api/guardrails                       │
│  - /api/pairs        - /api/kill-switch                      │
│  - /api/trade        - /api/market/:pair                     │
│  - WebSocket /api/ws                                         │
│                                                              │
│  Durable Objects:                                            │
│  - AgentStateDO    (positions, balances, P&L, status)        │
│  - OrderManagerDO  (open orders, fill history)               │
│  - GuardrailsDO    (risk config, runtime state)              │
│  - MarketDataDO    (price cache, orderbook, candles)         │
│  - TradingPairsDO  (whitelist, exchange intersection)        │
│                                                              │
│  Exchange Adapters:                                          │
│  - CryptoComAdapter  (REST + WebSocket)                      │
│  - CoinbaseAdvancedAdapter (REST + WebSocket)                │
│                                                              │
│  Scheduled Triggers (Cron):                                  │
│  - Every 1m: fetch prices, check signals, execute            │
│  - Every 5m: rebalance check, guardrail audit                │
│  - Every 1h: pair discovery, portfolio sync                  │
│  - Every 24h: P&L report, model retrain trigger              │
└─────────────────────────┬───────────────────────────────────┘
                          │ HTTP
┌─────────────────────────┼───────────────────────────────────┐
│          ML INFERENCE SERVICE (Fly.io)                       │
│  FastAPI wrapper around existing trading engine               │
│  - POST /predict  → BUY/SELL/HOLD + confidence               │
│  - POST /retrain  → trigger model retraining                 │
│  - GET  /health   → model status                             │
│  XGBoost + LSTM + Logistic ensemble                          │
└─────────────────────────────────────────────────────────────┘
                          │
┌─────────────────────────┼───────────────────────────────────┐
│          MCP SERVER (TypeScript)                              │
│  Tools: get_portfolio, get_signals, execute_trade,           │
│  set_guardrails, manage_pairs, kill_switch,                  │
│  get_trade_history, get_pnl_report, get_market_data          │
└─────────────────────────────────────────────────────────────┘

Exchange Adapter Interface

Both Crypto.com and Coinbase implement a unified TypeScript interface. The agent logic is exchange-agnostic.

interface Exchange {
  readonly name: 'crypto.com' | 'coinbase';

  // Market Data
  getTicker(pair: string): Promise<Ticker>;
  getOrderbook(pair: string, depth?: number): Promise<Orderbook>;
  getCandles(pair: string, interval: string, limit?: number): Promise<Candle[]>;
  getTrades(pair: string, limit?: number): Promise<Trade[]>;
  getAvailablePairs(): Promise<TradingPair[]>;

  // Account
  getBalances(): Promise<Balance[]>;
  getBalance(asset: string): Promise<Balance>;
  getFeeSchedule(): Promise<{ makerRate: number; takerRate: number }>;

  // Orders — clientOrderId is mandatory for idempotency
  placeLimitOrder(pair: string, side: 'buy'|'sell', price: number, qty: number, clientOrderId: string): Promise<Order>;
  placeMarketOrder(pair: string, side: 'buy'|'sell', qty: number, clientOrderId: string): Promise<Order>;
  cancelOrder(orderId: string): Promise<void>;
  getOrder(orderId: string): Promise<Order>;
  getOpenOrders(pair?: string): Promise<Order[]>;

  // WebSocket subscriptions
  subscribeToTicker(pair: string, callback: (ticker: Ticker) => void): void;
  subscribeToOrderUpdates(callback: (order: Order) => void): void;
  disconnect(): void;

  // Normalization
  normalizePair(pair: string): string;
}

Shared Types

interface Ticker {
  pair: string;       // Canonical format: "BTC-USDT"
  bid: number;
  ask: number;
  last: number;
  volume24h: number;
  timestamp: string;
}

interface Orderbook {
  pair: string;
  bids: [number, number][];  // [price, qty]
  asks: [number, number][];
  timestamp: string;
}

interface Candle {
  open: number;
  high: number;
  low: number;
  close: number;
  volume: number;
  timestamp: string;
}

interface Trade {
  id: string;
  pair: string;
  side: 'buy' | 'sell';
  price: number;
  qty: number;
  timestamp: string;
}

interface TradingPair {
  symbol: string;       // Canonical: "BTC-USDT"
  base: string;         // "BTC"
  quote: string;        // "USDT"
  minQty: number;
  maxQty: number;
  qtyStep: number;
  priceStep: number;    // Minimum price increment (tick size)
  minNotional: number;  // Min order value in quote currency
}

interface Balance {
  asset: string;
  available: number;
  locked: number;       // In open orders
  total: number;
}

interface Order {
  id: string;
  clientOrderId: string;      // Client-generated UUID for idempotency
  pair: string;
  side: 'buy' | 'sell';
  type: 'limit' | 'market';
  status: 'open' | 'filled' | 'partially_filled' | 'cancelled';
  price: number | null;       // null for market orders
  filledPrice: number | null;
  qty: number;
  filledQty: number;
  fee: number | null;         // Fee paid on fill
  feeAsset: string | null;    // Asset fee was charged in
  exchange: 'crypto.com' | 'coinbase';
  createdAt: string;
  updatedAt: string;
}

interface Signal {
  action: 'BUY' | 'SELL' | 'HOLD';
  confidence: number;         // 0-1
  pair: string;               // Canonical format
  timestamp: string;
}

interface AuditEvent {
  id: string;
  type: 'trade_executed' | 'trade_rejected' | 'guardrail_triggered' | 'kill_switch' |
        'config_changed' | 'pair_changed' | 'balance_sync' | 'agent_status_change';
  actor: 'system' | 'user' | 'mcp';
  details: Record<string, unknown>;
  timestamp: string;
}

Exchange-Specific Details

Crypto.com Exchange API v1:

• Base URL: https://api.crypto.com/exchange/v1
• Auth: API key + HMAC-SHA256 request signing
• Rate limits: 3 requests/100ms for order endpoints, 1 request/100ms for market data
• Pair format: BTC_USDT (underscore-separated)
• WebSocket: wss://stream.crypto.com/exchange/v1/market for market data

Coinbase Advanced Trade API:

• Base URL: https://api.coinbase.com/api/v3/brokerage
• Auth: API key + JWT signing (ES256)
• Rate limits: 30 requests/second
• Pair format: BTC-USDT (hyphen-separated)
• WebSocket: wss://advanced-trade-ws.coinbase.com for market data

Guardrails System

Every trade passes through 10 mandatory checks before execution. The types of checks are hardcoded; only thresholds are configurable. All timestamps use UTC.

Check Pipeline

1. Kill switch — Is the agent halted? → REJECT
2. Max trade size — Does this trade exceed min($500, portfolio * 2%)? → REJECT
3. Daily loss limit — Has today’s realized P&L (UTC day) dropped > 5% from day-open? → REJECT + auto-halt
4. Rolling drawdown — Has portfolio value dropped > 10% from its trailing 7-day peak? → REJECT + auto-halt
5. Rate-of-loss — Has realized loss exceeded 2% in any rolling 30-minute window? → REJECT + 15-min pause
6. Pair whitelist — Is this pair in the active whitelist? → REJECT
7. Per-pair cooldown — Has 60s elapsed since last trade on this pair? → REJECT
8. Global rate limit — No more than 5 trades per 5-minute window across all pairs → REJECT
9. Portfolio concentration — Would this push any single asset > 25% of portfolio (excl. stablecoins: USDT, USDC, DAI, BUSD)? → REJECT
10. Sufficient balance — Does the chosen exchange have enough funds? → REJECT

Default Configuration

Kill Switch Behavior

• Manual trigger: Dashboard toggle or MCP tool. Immediate halt, all open orders cancelled.
• Auto-trigger: Agent self-halts on any of: daily loss limit hit, rolling drawdown limit hit, or balance desync > 5%. AuditLogDO records the trigger reason.
• Recovery: Manual re-enable only. No auto-resume after a halt.

Durable Object State

// GuardrailsDO
{
  config: {
    maxTradeUSD: 500,
    maxTradePercent: 0.02,
    dailyLossLimit: 0.05,
    rollingDrawdownLimit: 0.10,
    rollingDrawdownWindowDays: 7,
    rateOfLossLimit: 0.02,
    rateOfLossWindowMinutes: 30,
    rateOfLossPauseMinutes: 15,
    maxConcentration: 0.25,
    cooldownSeconds: 60,
    globalRateLimitTrades: 5,
    globalRateLimitWindowMinutes: 5,
    stablecoins: ['USDT', 'USDC', 'DAI', 'BUSD'],
    killSwitch: false
  },
  state: {
    todayDate: string,               // UTC date "2026-03-14"
    todayRealizedPnL: number,
    trailing7DayPeak: number,        // Highest portfolio value in last 7 days
    recentPnLWindow: Array<{ pnl: number; timestamp: string }>,  // Rolling 30-min loss tracking
    lastTradePerPair: Record<string, string>,  // pair → ISO timestamp
    recentTradeTimestamps: string[],  // Global rate limit tracking (last 5 min)
    pausedUntil: string | null,       // Rate-of-loss pause expiry
    haltReason: string | null
  }
}

Trading Agent Decision Loop

Runs on Cloudflare Cron Triggers, executing every 1 minute.

Flow

1. Fetch Market Data — Parallel requests to both exchanges for all active pairs. Cache in MarketDataDO.
2. Request ML Signal — POST to Fly.io inference service with candles, orderbook snapshot, volume. Returns { action: BUY|SELL|HOLD, confidence: 0-1, pair: string }.
3. Confidence Gate — If action is HOLD or confidence < 0.7 (configurable), skip. Dashboard shows “suggested” badge for 0.5-0.7 confidence signals.
4. Smart Order Router — Compare effective price (price + fees) across both exchanges. Pick best execution venue. Check balance availability on chosen exchange.
5. Guardrails Check — Run the 10-check pipeline. Any failure rejects the trade with a logged reason.
6. Execute Order — Place via chosen exchange adapter. Record in OrderManagerDO. Update AgentStateDO.
7. Post-Trade — Update P&L, check if guardrail thresholds changed, push real-time update to dashboard via WebSocket.

Smart Order Router

interface RouteResult {
  exchange: Exchange;
  effectivePrice: number;
  estimatedFee: number;
  hasLiquidity: boolean;
}

async function routeOrder(
  pair: string,
  side: 'buy' | 'sell',
  qty: number,
  orderType: 'limit' | 'market',
  adapters: { cryptoCom: Exchange; coinbase: Exchange }
): Promise<RouteResult> {
  // Use allSettled so one exchange being down doesn't block the other
  const results = await Promise.allSettled([
    getExchangeQuote(adapters.cryptoCom, pair, side, qty, orderType),
    getExchangeQuote(adapters.coinbase, pair, side, qty, orderType),
  ]);

  const quotes = results
    .filter((r): r is PromiseFulfilledResult<RouteResult> => r.status === 'fulfilled')
    .map(r => r.value)
    .filter(q => q.hasLiquidity);

  if (quotes.length === 0) throw new Error(`No exchange available for ${pair}`);
  if (quotes.length === 1) return quotes[0];

  // For buys: lowest effective price wins. For sells: highest wins.
  return side === 'buy'
    ? quotes.reduce((a, b) => a.effectivePrice <= b.effectivePrice ? a : b)
    : quotes.reduce((a, b) => a.effectivePrice >= b.effectivePrice ? a : b);
}

async function getExchangeQuote(
  exchange: Exchange,
  pair: string,
  side: 'buy' | 'sell',
  qty: number,
  orderType: 'limit' | 'market'
): Promise<RouteResult> {
  const [ticker, orderbook, fees] = await Promise.all([
    exchange.getTicker(pair),
    exchange.getOrderbook(pair, 20),
    exchange.getFeeSchedule(),
  ]);

  // Use correct fee rate based on order type
  const feeRate = orderType === 'limit' ? fees.makerRate : fees.takerRate;

  // Check orderbook depth for slippage estimation
  const levels = side === 'buy' ? orderbook.asks : orderbook.bids;
  const { avgPrice, filled } = estimateSlippage(levels, qty);

  const price = side === 'buy' ? ticker.ask : ticker.bid;
  const effectivePrice = avgPrice * (1 + (side === 'buy' ? feeRate : -feeRate));

  return { exchange, effectivePrice, estimatedFee: avgPrice * qty * feeRate, hasLiquidity: filled };
}

Partial fill handling: When an order fills partially, the agent:

1. Records the partial fill in OrderManagerDO (status: partially_filled, filledQty updated)
2. Updates AgentStateDO position with the filled quantity
3. Leaves the remaining quantity as an open order (does not cancel automatically)
4. The partial fill does NOT consume the cooldown — only a full fill or cancellation resets it
5. P&L is calculated incrementally on the filled portion

Manual Override

Users can submit trades directly from the dashboard. Manual trades bypass the ML signal and confidence gate but still pass through all guardrails.

Durable Objects Data Model

Six singleton Durable Objects hold all persistent state. All DO state uses canonical pair format (“BTC-USDT”).

AgentStateDO

{
  // Positions keyed by pair, per-exchange tracking
  positions: Record<string, Record<'crypto.com' | 'coinbase', {
    qty: number;
    avgEntry: number;
  }>>;
  balances: Record<string, Record<string, number>>;  // exchange → asset → amount
  dailyPnL: { date: string; startBalance: number; current: number };  // UTC date
  totalPnL: { initialDeposit: number; allTimeUSD: number; percentReturn: number };
  lastSync: string;
  status: 'running' | 'halted';  // halted = kill switch, all orders cancelled
}

OrderManagerDO

{
  openOrders: Order[];
  history: Order[];  // Rolling 30-day window, older archived to KV (TRADE_HISTORY_KV)
}

GuardrailsDO

(See Guardrails section above for full state definition.)

MarketDataDO

{
  tickers: Record<string, Record<string, Ticker>>;  // pair → exchange → ticker
  candles: Record<string, Candle[]>;                 // "pair:interval" → max 200 candles per key
  lastUpdate: string;
}

Eviction: Candles capped at 200 per pair:interval key. Tickers older than 5 minutes are pruned on read. Data for pairs removed from whitelist is evicted on the next hourly pair discovery cycle.

TradingPairsDO

{
  whitelist: string[];                              // User-managed (canonical format)
  exchangePairs: Record<string, string[]>;          // exchange → raw pairs
  intersection: string[];                           // Available on both (canonical)
  activePairs: string[];                            // whitelist ∩ intersection
  pairMetadata: Record<string, Record<'crypto.com' | 'coinbase', TradingPair>>;
  lastDiscovery: string;
}

AuditLogDO

A dedicated Durable Object for immutable event logging. Every state mutation is recorded.

{
  events: AuditEvent[];    // Rolling 7-day window in DO
  // Older events archived to KV (AUDIT_LOG_KV) daily
}

Events logged: trade executed, trade rejected (with guardrail reason), kill switch toggled, config changed, pair whitelist changed, balance sync discrepancy detected, agent status change. Each event includes an actor field: system, user, or mcp.

Dashboard API

REST Endpoints

Authentication

• Dashboard auth: POST /api/auth/login with { key: DASHBOARD_API_KEY }. Returns a JWT (HS256, signed with a Worker secret, 24h expiry). All subsequent requests include Authorization: Bearer <jwt>.
• JWT validation: The Worker validates the JWT on every request. No session state needed.
• MCP server auth: Uses the same DASHBOARD_API_KEY as a Bearer token directly (no JWT dance needed since it is machine-to-machine).
• CORS: The Worker sets Access-Control-Allow-Origin to the Cloudflare Pages dashboard URL (configured via DASHBOARD_ORIGIN environment variable). Credentials are allowed. Preflight requests are handled.

MCP Server

TypeScript MCP server exposing the agent’s capabilities to Claude.

ML Inference Service

Thin FastAPI wrapper deployed on Fly.io around the existing Python trading engine.

Authentication

All requests require Authorization: Bearer <ML_SERVICE_KEY> header.

Endpoints

POST /predict
  Body: {
    pair: string,
    candles: Candle[],        // Last 100 candles, 1h interval
    orderbook: {              // Top 10 levels
      bids: [number, number][],
      asks: [number, number][]
    },
    volume24h: number
  }
  Response: { action: "BUY"|"SELL"|"HOLD", confidence: number, pair: string }
  Timeout: 5 seconds. On timeout or error, the Worker treats the signal as HOLD.

POST /retrain
  Body: { pair: string }
  Response: { status: "started", estimatedTime: string }

GET /retrain/status
  Response: { status: "idle"|"training"|"completed"|"failed", lastCompleted: string, currentPair: string | null }

GET /health
  Response: { status: "healthy", modelsLoaded: string[], lastRetrain: string }

Model Ensemble

Existing pipeline: XGBoost + LSTM + Logistic regression ensemble. Each model votes, confidence is the weighted average agreement.

Cron Schedule

Secrets & Configuration

All secrets stored as Cloudflare Worker secrets, deployed via GitHub Actions from GitHub repository secrets.

Secrets

KV Namespaces

Durable Object Bindings

Environment Modes

The agent supports two modes configured via the TRADING_MODE environment variable:

• live — Real-money trading against production exchange APIs
• paper — Paper trading mode: all exchange calls are real (real prices, real orderbooks), but orders are simulated locally. P&L is tracked but no real money moves. Use this for validation before going live.

Paper mode uses the same code paths but wraps exchange adapters in a PaperTradingAdapter that intercepts order placement and simulates fills based on current market prices.

Project Structure

trading-agent/
├── wrangler.toml                  # Cloudflare Workers config (DO bindings, KV, cron, secrets)
├── package.json
├── tsconfig.json
├── src/
│   ├── index.ts                   # Worker entry point + cron handler
│   ├── router.ts                  # API route definitions
│   ├── auth.ts                    # JWT creation, validation, CORS middleware
│   ├── exchanges/
│   │   ├── interface.ts           # Exchange interface + all shared types
│   │   ├── crypto-com.ts          # Crypto.com adapter
│   │   ├── coinbase.ts            # Coinbase adapter
│   │   ├── paper-trading.ts       # PaperTradingAdapter wrapper
│   │   └── router.ts              # Smart order router
│   ├── durable-objects/
│   │   ├── agent-state.ts         # AgentStateDO
│   │   ├── order-manager.ts       # OrderManagerDO
│   │   ├── guardrails.ts          # GuardrailsDO
│   │   ├── market-data.ts         # MarketDataDO
│   │   ├── trading-pairs.ts       # TradingPairsDO
│   │   └── audit-log.ts           # AuditLogDO
│   ├── agent/
│   │   ├── decision-loop.ts       # Main trading loop
│   │   ├── signal-client.ts       # ML inference service client (5s timeout)
│   │   └── scheduler.ts           # Cron trigger handlers
│   ├── api/
│   │   ├── portfolio.ts           # Portfolio endpoints
│   │   ├── trades.ts              # Trade endpoints
│   │   ├── orders.ts              # Open orders + cancel
│   │   ├── signals.ts             # Signal endpoints
│   │   ├── guardrails.ts          # Guardrail endpoints
│   │   ├── pairs.ts               # Pair management endpoints
│   │   ├── events.ts              # Audit event log endpoint
│   │   ├── status.ts              # Agent status + health check
│   │   └── websocket.ts           # WebSocket handler
│   └── mcp/
│       └── server.ts              # MCP server tool definitions
├── ml-service/
│   ├── Dockerfile
│   ├── fly.toml
│   ├── requirements.txt
│   ├── main.py                    # FastAPI app
│   ├── predict.py                 # Prediction endpoint logic
│   └── models/                    # Trained model artifacts
└── tests/
    ├── exchanges/
    ├── durable-objects/
    ├── agent/
    └── api/

Risk Considerations

Exchange Connectivity

• Single exchange down: The Smart Order Router uses Promise.allSettled — if one exchange is unreachable, trades route to the healthy exchange automatically. No manual intervention needed.
• Both exchanges down: The cron cycle skips entirely. Agent status remains “running” but no trades execute. AuditLogDO records the connectivity failure. Dashboard shows a warning.

Double Execution Prevention

• Cron overlap: Each cron invocation acquires a lock via the AgentStateDO Durable Object before proceeding. Since DO requests are serialized, only one trading loop runs at a time. If a previous cycle is still in-flight, the new invocation waits (DO queues the request).
• Order idempotency: All orders use a client-generated clientOrderId (UUID). Both Crypto.com and Coinbase support idempotent order creation — retrying with the same clientOrderId returns the existing order instead of creating a duplicate.

Balance Desynchronization

• Detection: The 5-minute rebalance check compares AgentStateDO balances against live exchange balances. If discrepancy > 1%, an AuditEvent is logged with type balance_sync.
• Resolution: The agent trusts the exchange as the source of truth and overwrites local state. If the discrepancy is > 5%, the agent auto-halts and alerts the user (possible unauthorized activity or manual trades placed directly on the exchange).

ML Service

• Timeout: 5-second timeout on /predict calls. On timeout, the signal is treated as HOLD.
• Downtime: If inference is unavailable, the agent holds all positions. Dashboard shows a warning. No retry — fail fast, try again next cycle.
• Bad predictions: The guardrails system is the safety net. Even if the ML model goes haywire, the max trade size, daily loss limit, rolling drawdown, and rate-of-loss guardrails prevent catastrophic losses.

Data Integrity

• Stale prices: MarketDataDO timestamps are checked. If data is older than 2 minutes, the agent skips that pair for the current cycle.
• DO serialization: Guardrail check + order placement happen within a single Durable Object request chain, guaranteeing consistency.
• Canonical format: All internal state uses canonical pair format (“BTC-USDT”). Exchange adapters handle conversion at the boundary.

Operational

• Key rotation: Rotate keys in GitHub secrets, redeploy via CI/CD. Note: ensure no open orders exist before rotating exchange keys, or the agent may be unable to cancel them. The recommended procedure: toggle kill switch → wait for open orders to fill/cancel → rotate keys → redeploy → re-enable.
• Monitoring: Health check endpoint at GET /api/status for external monitoring (Uptime Robot, Cloudflare Health Checks). Alerts on: kill switch activation, daily loss limit hit, exchange API errors, ML service downtime. Alert channel: AuditLogDO events are available via the /api/events endpoint and MCP get_events tool.
• Paper trading: Always validate changes in paper mode before deploying to live. Paper mode uses real market data but simulated order fills.