TOMO Agent Architecture Whitepaper

Technical architecture of TOMO - the autonomous spot trading agent. Core invariants, state machine design, pure domain logic, emergent learning, and self-healing mechanisms.

Last updated: January 15, 2026

“A disciplined, principle-driven spot trading system that learns, adapts, and never compromises on safety.”

What We’re Building

TOMO is not just a trading bot—she’s an emergent trading intelligence that:

• Thinks before acting (pure domain logic, no impulsive IO)
• Learns from every trade (feedback loops, fitness tracking)
• Adapts to market conditions (homeostasis, parameter evolution)
• Never compromises on safety (invariants are law, not suggestions)
• Explains herself (full audit trail, reasoning transparency)

Core Invariants (Sacred Laws)

These are non-negotiable and must survive every refactor:

State Machine

TOMO operates as an explicit finite state machine:

States: idle → active_trading → evaluating → executing → monitoring_positions → paused → stopped
Events: START_TRADING, EVALUATE_TICK, TRADE_SIGNAL, EXECUTE_TRADE, CAPITAL_DEPLETED, etc.

Transition Table

Current Capabilities

Safety Guards Implemented

• Never sell at loss (hard block in executeTrade)
• Trade lock prevents concurrent execution
• Fresh balance check before buys
• Rate limiting (5s between trades)
• Reserve for fees (0.01 SOL)
• Monitoring mode when capital depleted

Price System

• Jupiter Data API for position prices
• 10-second refresh loop
• SOL-denominated P&L calculation

Strategy Framework

• Take-profit strategy (15% target)
• Momentum entry strategy
• Mean reversion entry strategy
• Risk-off disabled (diamond hands)

Architecture Principles

Pure Domain Core (Algebraic Effects)

Trading decisions are pure functions that return effect descriptions:

type TradeEffect = 
  | { type: 'CHECK_BALANCE' }
  | { type: 'GET_QUOTE'; input: string; output: string; amount: number }
  | { type: 'EXECUTE_SWAP'; quote: Quote }
  | { type: 'LOG'; level: string; message: string };

const decideTradeEffects = (state: TradingState, signal: TradeSignal): TradeEffect[] => {
  // Pure logic - no IO, fully testable
  if (signal.direction === 'sell' && state.position.pnlPercent < 0) {
    return [{ type: 'LOG', level: 'warn', message: 'Blocked sell at loss' }];
  }
  // ... returns effect descriptions, not executions
};

The domain never performs IO directly. It describes what should happen; the infrastructure layer interprets those descriptions.

Emergence & Learning

TOMO tracks fitness metrics per strategy:

interface StrategyFitness {
  strategyId: string;
  totalTrades: number;
  winRate: number;           // % trades that were profitable
  avgPnlPercent: number;     // Average P&L per trade
  avgHoldTime: number;       // Average time in position
  sharpeRatio: number;       // Risk-adjusted returns
  maxDrawdown: number;       // Worst peak-to-trough
}

Over time, TOMO adjusts strategy weights based on performance, evolving toward more profitable behavior.

Living System Features

Self-Healing Watchdog

• Detects stuck states (generating too long, tooling timeout)
• Automatically recovers by forcing transitions
• Logs recovery events for analysis

Health Ledger

• Tracks system health across dimensions
• Triggers alerts when thresholds exceeded
• Enables self-assertions (“I am healthy because…”)

Circuit Breakers

• Trip after repeated failures
• Require deliberate reset
• Protect against cascade failures

Guiding Documents