# gerskill/moondev-trading-ai-agents architecture

> Architecture diagram of the GitHub repository gerskill/moondev-trading-ai-agents, generated by GitDiagram from its file tree, README and a sample of source files (last updated 2026-08-01). It is an AI-made overview: check details against the source.

- Interactive diagram: https://gitdiagram.com/gerskill/moondev-trading-ai-agents
- Repository: https://github.com/gerskill/moondev-trading-ai-agents

## Overview

#### Purpose and Entry Points
This is an experimental Python research system for AI-assisted crypto trading analysis, monitoring, risk checks, strategy research, and optional trade-decision workflows. The primary runtime entry point is `src/main.py`, which enables or disables agents. Other operational surfaces include a bot-oriented runner at `src/ezbot.py`, an API module at `src/agents/api.py`, and a separate frontend application at `src/frontend/main.py`.

#### Agent Runtime and Shared Contract
Agents are organized as independently runnable domain workers under `src/agents/`, with common behavior likely centralized in `src/agents/base_agent.py`. This boundary allows market-monitoring, analysis, risk, and research capabilities to evolve separately while being orchestrated from the main runtime.
- `src/agents/base_agent.py`
- `src/agents/__init__.py`
- `src/main.py`

#### Trading, Strategy, and Risk Decision Chain
The core decision-oriented path combines token/trade analysis, strategy execution or approval, and portfolio safety controls. The trading agent produces basic trade decisions from token data; the strategy agent manages strategies placed in the strategies package; the risk agent enforces position and PnL/minimum-balance constraints. Risk is an important boundary before any execution-oriented behavior.
- `src/agents/trading_agent.py`
- `src/agents/strategy_agent.py`
- `src/agents/risk_agent.py`

Strategies implement a separate extension layer, anchored by a base type and examples/custom strategy location rather than being embedded in agents.
- `src/strategies/base_strategy.py`
- `src/strategies/custom/example_strategy.py`
- `src/strategies/example_strategy.py`

#### Market Intelligence and Data Collection
Monitoring agents ingest and interpret crypto market signals including funding, liquidations, open interest, whale activity, listings, and CoinGecko token information. They persist or consume local CSV histories, creating a file-backed state boundary rather than a dedicated database.
- `src/agents/funding_agent.py`
- `src/agents/liquidation_agent.py`
- `src/agents/whale_agent.py`
- `src/data/funding_history.csv`
- `src/data/liquidation_history.csv`
- `src/data/oi_history.csv`

The README identifies a Moon Dev API v2-style market-data integration for funding, liquidation, open-interest, and CopyBot data, plus CoinGecko and Hyperliquid/Solana-oriented workflows. Required secrets include Anthropic and other trading/API keys.

#### AI Analysis and Notification Agents
Several agents apply LLM analysis to distinct inputs: charts, Twitter sentiment, CopyBot activity, and token listings. Outputs include buy/sell/nothing recommendations, saved analyses, historical sentiment, and voice alerts. LLM-provider configuration is centralized at the application level.
- `src/agents/chartanalysis_agent.py`
- `src/agents/sentiment_agent.py`
- `src/agents/copybot_agent.py`
- `src/agents/listingarb_agent.py`
- `src/config.py`

Tweet generation and sentiment-related artifacts are persisted locally.
- `src/agents/tweet_agent.py`
- `src/data/sentiment_history.csv`
- `src/data/tweets/`

#### Arbitrage and Research Pipelines
Specialized agents target funding-rate arbitrage and RBI strategy research. The RBI flow takes a strategy description/video/PDF concept, uses DeepSeek for research, and produces or supports coded backtests. Research inputs, generated strategy descriptions, backtests, and packaged backtests live together under `data/rbi`.
- `src/agents/fundingarb_agent.py`
- `src/agents/rbi_agent.py`
- `src/data/rbi/research/`
- `src/data/rbi/backtests/`
- `src/data/rbi/backtests_package/`

#### User/API Boundary and Infrastructure
The frontend is a standalone Python-served UI with HTML, JavaScript, CSS, and static assets. Programmatic access is exposed separately through the agents API module. The repository is Python-based with dependencies declared in `requirements.txt`; operational data is primarily CSV and local files.
- `src/frontend/main.py`
- `src/frontend/templates/index.html`
- `src/frontend/static/js/main.js`
- `src/agents/api.py`
- `requirements.txt`

Main entry points: [`src/main.py`](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/main.py) (Main runtime), [`src/agents/trading_agent.py`](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/trading_agent.py) (Trade analysis), [`src/agents/base_agent.py`](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/base_agent.py) (Agent contract), [`src/agents/strategy_agent.py`](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/strategy_agent.py) (Strategy manager)

## Diagram (Mermaid)

```mermaid
flowchart TD

subgraph group_runtime["Runtime"]
  node_main{{"Main runtime<br/>orchestrator<br/>[main.py]"}}
  node_base_agent["Agent contract<br/>agent base<br/>[base_agent.py]"]
  node_config["App configuration<br/>config module<br/>[config.py]"]
  node_requirements["Python dependencies<br/>dependency manifest<br/>[requirements.txt]"]
end

subgraph group_intelligence["Market intelligence"]
  node_market_agents["Market monitors<br/>agent set"]
  node_funding_agent["Funding monitor<br/>agent<br/>[funding_agent.py]"]
  node_liquidation_agent["Liquidation monitor<br/>agent"]
  node_whale_agent["Whale monitor<br/>agent<br/>[whale_agent.py]"]
  node_market_history[("Market CSV history<br/>file state")]
  node_ai_agents["LLM analysis agents<br/>agent set"]
  node_sentiment_agent["Sentiment analysis<br/>agent<br/>[sentiment_agent.py]"]
  node_sentiment_history[("Sentiment history<br/>file state")]
end

subgraph group_decisions["Trading decisions"]
  node_trading_agent["Trade analysis<br/>agent<br/>[trading_agent.py]"]
  node_strategy_agent["Strategy manager<br/>agent<br/>[strategy_agent.py]"]
  node_strategy_base["Strategy extension layer<br/>strategy base<br/>[base_strategy.py]"]
  node_risk_agent{{"Risk controls<br/>agent<br/>[risk_agent.py]"}}
end

subgraph group_research["Research pipelines"]
  node_fundingarb_agent["Funding arbitrage<br/>agent"]
  node_rbi_agent["RBI researcher<br/>agent<br/>[rbi_agent.py]"]
  node_rbi_artifacts["RBI artifacts<br/>research files"]
end

subgraph group_interfaces["Interfaces"]
  node_api["Programmatic API<br/>API module<br/>[api.py]"]
  node_frontend["Frontend UI<br/>Python UI<br/>[main.py]"]
end

node_main -->|"orchestrates"| node_base_agent
node_main -->|"runs"| node_market_agents
node_main -->|"runs"| node_ai_agents
node_main -->|"runs"| node_trading_agent
node_main -->|"runs"| node_strategy_agent
node_main -->|"runs"| node_risk_agent
node_base_agent -.->|"shared contract"| node_market_agents
node_base_agent -.->|"shared contract"| node_ai_agents
node_base_agent -.->|"shared contract"| node_trading_agent
node_market_agents -.->|"includes"| node_funding_agent
node_market_agents -.->|"includes"| node_liquidation_agent
node_market_agents -.->|"includes"| node_whale_agent
node_funding_agent -->|"persists history"| node_market_history
node_liquidation_agent -->|"persists history"| node_market_history
node_ai_agents -.->|"includes"| node_sentiment_agent
node_sentiment_agent -->|"persists history"| node_sentiment_history
node_config -->|"LLM settings"| node_ai_agents
node_market_agents -->|"market signals"| node_trading_agent
node_ai_agents -->|"recommendations"| node_trading_agent
node_trading_agent -->|"trade decisions"| node_strategy_agent
node_strategy_base -->|"strategy implementations"| node_strategy_agent
node_strategy_agent -->|"proposed actions"| node_risk_agent
node_market_history -->|"funding data"| node_fundingarb_agent
node_rbi_agent -->|"writes research and backtests"| node_rbi_artifacts
node_api -->|"programmatic access"| node_main
node_frontend -->|"user operations"| node_main
node_requirements -.->|"runtime dependencies"| node_main

click node_main "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/main.py"
click node_base_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/base_agent.py"
click node_config "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/config.py"
click node_funding_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/funding_agent.py"
click node_liquidation_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/liquidation_agent.py"
click node_whale_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/whale_agent.py"
click node_market_history "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/data/funding_history.csv"
click node_sentiment_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/sentiment_agent.py"
click node_sentiment_history "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/data/sentiment_history.csv"
click node_trading_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/trading_agent.py"
click node_strategy_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/strategy_agent.py"
click node_strategy_base "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/strategies/base_strategy.py"
click node_risk_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/risk_agent.py"
click node_fundingarb_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/fundingarb_agent.py"
click node_rbi_agent "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/rbi_agent.py"
click node_api "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/api.py"
click node_frontend "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/frontend/main.py"
click node_requirements "https://github.com/gerskill/moondev-trading-ai-agents/blob/main/requirements.txt"

classDef toneNeutral fill:#f8fafc,stroke:#334155,stroke-width:1.5px,color:#0f172a
classDef toneBlue fill:#dbeafe,stroke:#2563eb,stroke-width:1.5px,color:#172554
classDef toneAmber fill:#fef3c7,stroke:#d97706,stroke-width:1.5px,color:#78350f
classDef toneMint fill:#dcfce7,stroke:#16a34a,stroke-width:1.5px,color:#14532d
classDef toneRose fill:#ffe4e6,stroke:#e11d48,stroke-width:1.5px,color:#881337
classDef toneIndigo fill:#e0e7ff,stroke:#4f46e5,stroke-width:1.5px,color:#312e81
classDef toneTeal fill:#ccfbf1,stroke:#0f766e,stroke-width:1.5px,color:#134e4a
class node_main,node_base_agent,node_config,node_requirements toneBlue
class node_market_agents,node_funding_agent,node_liquidation_agent,node_whale_agent,node_market_history,node_ai_agents,node_sentiment_agent,node_sentiment_history toneAmber
class node_trading_agent,node_strategy_agent,node_strategy_base,node_risk_agent toneMint
class node_fundingarb_agent,node_rbi_agent,node_rbi_artifacts toneRose
class node_api,node_frontend toneIndigo
```

## Components

### Runtime

- [Main runtime](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/main.py): orchestrator · Enables and disables domain agents. · `src/main.py`
- [Agent contract](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/base_agent.py): agent base · Shared behavior for independently runnable agents. · `src/agents/base_agent.py`
- [App configuration](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/config.py): config module · Centralizes LLM-provider configuration. · `src/config.py`
- [Python dependencies](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/requirements.txt): dependency manifest · `requirements.txt`

### Market intelligence

- **Market monitors**: agent set · Funding, liquidation, and whale signal workers.
- [Funding monitor](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/funding_agent.py): agent · `src/agents/funding_agent.py`
- [Liquidation monitor](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/liquidation_agent.py): agent · `src/agents/liquidation_agent.py`
- [Whale monitor](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/whale_agent.py): agent · `src/agents/whale_agent.py`
- [Market CSV history](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/data/funding_history.csv): file state · Funding, liquidation, and open-interest histories. · `src/data/funding_history.csv`
- **LLM analysis agents**: agent set · Chart, sentiment, CopyBot, and listing analysis.
- [Sentiment analysis](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/sentiment_agent.py): agent · `src/agents/sentiment_agent.py`
- [Sentiment history](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/data/sentiment_history.csv): file state · `src/data/sentiment_history.csv`

### Trading decisions

- [Trade analysis](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/trading_agent.py): agent · Produces basic trade decisions from token data. · `src/agents/trading_agent.py`
- [Strategy manager](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/strategy_agent.py): agent · Executes or approves strategy workflows. · `src/agents/strategy_agent.py`
- [Strategy extension layer](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/strategies/base_strategy.py): strategy base · Base type for built-in and custom strategies. · `src/strategies/base_strategy.py`
- [Risk controls](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/risk_agent.py): agent · Enforces position, PnL, and minimum-balance constraints. · `src/agents/risk_agent.py`

### Research pipelines

- [Funding arbitrage](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/fundingarb_agent.py): agent · `src/agents/fundingarb_agent.py`
- [RBI researcher](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/rbi_agent.py): agent · Uses DeepSeek research to support coded backtests. · `src/agents/rbi_agent.py`
- **RBI artifacts**: research files · Research inputs, strategy descriptions, and backtests.

### Interfaces

- [Programmatic API](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/agents/api.py): API module · `src/agents/api.py`
- [Frontend UI](https://github.com/gerskill/moondev-trading-ai-agents/blob/main/src/frontend/main.py): Python UI · Standalone Python-served interface. · `src/frontend/main.py`

## Connections

- Main runtime → Agent contract: orchestrates
- Main runtime → Market monitors: runs
- Main runtime → LLM analysis agents: runs
- Main runtime → Trade analysis: runs
- Main runtime → Strategy manager: runs
- Main runtime → Risk controls: runs
- Agent contract → Market monitors: shared contract
- Agent contract → LLM analysis agents: shared contract
- Agent contract → Trade analysis: shared contract
- Market monitors → Funding monitor: includes
- Market monitors → Liquidation monitor: includes
- Market monitors → Whale monitor: includes
- Funding monitor → Market CSV history: persists history
- Liquidation monitor → Market CSV history: persists history
- LLM analysis agents → Sentiment analysis: includes
- Sentiment analysis → Sentiment history: persists history
- App configuration → LLM analysis agents: LLM settings
- Market monitors → Trade analysis: market signals
- LLM analysis agents → Trade analysis: recommendations
- Trade analysis → Strategy manager: trade decisions
- Strategy extension layer → Strategy manager: strategy implementations
- Strategy manager → Risk controls: proposed actions
- Market CSV history → Funding arbitrage: funding data
- RBI researcher → RBI artifacts: writes research and backtests
- Programmatic API → Main runtime: programmatic access
- Frontend UI → Main runtime: user operations
- Python dependencies → Main runtime: runtime dependencies