Documentation Index
Fetch the complete documentation index at: https://condor.hummingbot.org/llms.txt
Use this file to discover all available pages before exploring further.
Each Trading Agent is a folder-based entity with structured files that define its behavior, track state, and accumulate learnings.
System Architecture
┌──────────────────────────── Trading Agent ───────────────────────────┐
│ │
│ Strategy (agent.md) Journal (per session) Learnings.md │
│ ─────────────────── ──────────────────── ──────────── │
│ - system prompt - summary cross-session │
│ - default config - decisions lessons │
│ - skills/routines - tick-by-tick log │
│ - snapshot_N.md │
│ │
│ ┌──── TickEngine ────┐ │
│ │ every N seconds: │ │
│ Routines ───────────► │ 1. run providers │ ────► MCP Tools │
│ (deterministic │ 2. read journal │ - candles │
│ data prep) │ 3. build prompt │ - orderbook │
│ │ 4. ACP session │ - executors │
│ │ 5. capture tools │ - notify │
│ │ 6. write snapshot │ │
│ └────────────────────┘ │
│ │
└───────────────────────────────────────────────────────────────────────┘
│
▼
Hummingbot Executors
(filtered by controller_id == agent_id)
Directory Structure
Each Condor Trading Agent (CTA) is a directory containing structured files:
trading_agents/
my_strategy/
agent.md # Strategy definition (frontmatter + LLM instructions)
config.yml # Runtime configuration (editable)
learnings.md # Cross-session insights (max 20)
routines/ # Deterministic Python helpers
trading_sessions/
session_N/
journal.md # Summary, decisions, ticks, executors
snapshots/
snapshot_1.md # Full prompt + response for tick 1
snapshot_2.md
dry_runs/
experiment_1.md # One-shot dry-run results
Two Memory Files
| File | Scope | Purpose |
|---|
journal.md | Per-session | Short-term memory for the current trading session |
learnings.md | Cross-session | Long-term memory that persists across all sessions |
agent.md
The strategy definition uses YAML frontmatter for configuration and Markdown for instructions:
---
name: Grid Market Maker
tick_interval: 60
connectors:
- binance_perpetual
- jupiter
configs:
trading_pair: SOL-USDC
grid_levels: 5
spread_percentage: 0.3
limits:
max_position_size_quote: 500
max_single_order_quote: 100
max_daily_loss_quote: 50
max_open_executors: 10
max_drawdown_pct: 10
---
## Goal
Provide liquidity around the mid-price while managing inventory risk.
## Strategy Rules
1. Maintain symmetric grid unless inventory exceeds threshold
2. Widen spreads during high volatility (ATR > 2%)
3. Pause trading if funding rate exceeds 0.1% against position
Configs vs Limits
Configs
Agent-suggestible parameters that control trading behavior:
- The agent can suggest changes based on learnings
- User must approve before changes take effect
- Examples:
trading_pair, spread_percentage, tick_interval, grid_levels
Limits
User-only guardrails enforced by the Risk Engine:
- Safety boundaries the agent cannot exceed
- Only modifiable by the user, never by the agent
- Examples:
max_position_size_quote, max_daily_loss_quote, max_drawdown_pct
learnings.md
Persists across sessions, accumulating insights:
# Learnings
## Active Insights
- [2026-03-27 14:30] Wider spreads (0.5% vs 0.3%) reduced adverse selection during Asian session
- [2026-03-26 09:15] Grid rebalancing at 5% threshold outperforms 10% for SOL-USDC
- [2026-03-25 16:45] Funding rate spikes above 0.05% correlate with 2-hour reversals
Tick Loop
Each tick (TickEngine._tick) executes:
- Resolve API client for the configured server
- Run providers —
executors and positions, filtered by controller_id
- Read journal context — learnings, summary, last 3 decisions
- Get risk state — exposure, drawdown, open count. If blocked, skip LLM
- Build prompt — system prompt + strategy + provider summaries + journal
- Spawn ACP session with MCP servers (Hummingbot tools, market data)
- Persist — write snapshot, append tick to journal, update summary
Risk Engine
The Risk Engine (condor/trading_agent/risk.py) tracks state and enforces limits:
class RiskState:
daily_pnl: float # Today's realized P&L
total_exposure: float # Current open position value
executor_count: int # Number of active executors
drawdown_pct: float # Current drawdown percentage
daily_cost: float # LLM costs today
is_blocked: bool # Kill switch status
block_reason: str # Why blocked (if applicable)
Pre-tick Validation
Blocks the entire tick if:
daily_pnl < -max_daily_loss_quotedrawdown_pct > max_drawdown_pctdaily_cost > max_cost_per_day_usd
Per-executor Validation
Blocks executor creation if:
executor_count >= max_open_executorsorder_amount > max_single_order_quotetotal_exposure + new_amount > max_position_size_quote
Providers
Providers fetch deterministic data before each tick:
| Provider | Output |
|---|
executors | Active executors filtered by controller_id, with status and P&L |
positions | Held positions from closed executors, with breakeven and unrealized P&L |
data: Structured data for internal trackingsummary: Human-readable string included in the LLM prompt
Routines
Custom Python helpers in the routines/ directory:
# routines/process_candles.py
async def compute_vwap(candles):
"""Compute VWAP from candle data."""
total_volume = sum(c.volume for c in candles)
return sum(c.close * c.volume for c in candles) / total_volume
Inspecting Activity
| Location | Content |
|---|
sessions/session_N/journal.md | Chronological summary, decisions, tick log |
sessions/session_N/snapshots/snapshot_K.md | Full tick: prompt, response, tool calls |
learnings.md | Lessons the agent chose to keep |
dry_runs/experiment_N.md | Dry-run results |
learnings.md—the agent doesn’t know whether it wrote the entry or you did. Useful for:
- Pre-seeding knowledge before deployment
- Adding market context the agent can’t observe
- Correcting agent behavior
Via web dashboard: Trading Agents → Select agent → Learnings → Edit
Via file: Edit trading_agents/my_strategy/learnings.md directly
