This project is an event-driven, agentic cryptocurrency trading simulation platform built for test networks.
The system executes simulated trading strategies against:
- Solana Devnet (via
solana-py) - Ethereum Sepolia (via
AgentKit/CDP) - Avalanche Fuji (via
AgentKit/CDP)
Real market data is used to generate trading signals, while all trade execution occurs on testnets using a three-wallet USDC strategy to avoid risking real capital.
- Evaluate AI-generated trading strategies safely
- Simulate multi-chain portfolio management
- Test autonomous trading workflows
- Support long-running blockchain operations
- Maintain reproducibility and auditability
- LangGraph
- LangChain
- Groq (via LangChain-Groq)
- LangSmith (for observability)
- Coinbase AgentKit (for EVM execution)
- Solana Python SDK (
solana-py) - Coinbase CDP SDK
- web3.py (for deterministic validations)
- Python 3.12+
- SQLite (aiosqlite) for persistent trade tracking
The system uses a decoupled LangGraph architecture to separate reasoning from execution. It utilizes a parallel fan-out structure where specialized subagents provide context to a central aggregator.
research_spawner: The entry point that fans out into parallel analysis nodes.- Analyst Nodes (
gas,news,trend,performance,liquidity,correlation,whale,volatility): Specialized subagents that run in parallel to analyze network fees, macro sentiment, technical indicators, portfolio PnL, pool liquidity, BTC correlations, on-chain whale movements, and market volatility, respectively. aggregator: Consumes reports from all specialized subagents to generate a final, high-convictionTradePlan.validator: A deterministic node that enforces balance constraints, maximum trade limits, and slippage guardrails.executor: Dispatches validated actions to chain-specific wallet adapters and records them in the database.
- Market Watcher (
src/services/market_watcher.py): Aggregates price snapshots and triggers the agent loop. - Transaction Monitor (
src/services/transaction_monitor.py): A parallel service that polls the blockchain to update the status ofPENDINGtrades in SQLite.
To handle flaky testnets, the agent loop completes immediately after submitting a transaction. The TransactionMonitor handles the asynchronous confirmation, allowing the agent to stay responsive to new signals.
The WalletManager is a singleton ensuring that wallet keys and initialized providers are shared across the application, preventing redundant initialization and race conditions.
Calls to loop-heavy SDKs (like Coinbase AgentKit) are offloaded to separate threads using asyncio.to_thread to prevent event loop conflicts.
All SQL queries are centralized in src/persistence/queries.py and use parameterized queries to prevent injection from LLM-generated rationale strings.
The system maintains three distinct wallets, one for each supported chain.
- Each wallet uses USDC as its base "bank" currency.
- Gas Requirements: Each wallet must be funded with a small amount of the chain's native testnet token (SOL, ETH, or AVAX) to cover gas fees for swaps.
- Trades are simulated by swapping USDC for the target asset and back.
- Stage 1: Funding Poll: The main script polls for native/USDC balances. It will wait indefinitely until at least one wallet is funded. Instructions are provided in
WALLETS.md. - Stage 2: Market Poll: Once funds are detected, the system enters its active loop, polling market data providers for signals to trigger the Aggregator Agent.
- Python 3.12+
- uv
libffi-dev(required forcffibuild)
# Install dependencies and setup virtual environment
make installGenerate a visual map of the trading graph:
make graphuv run python -m src.workflows.main# Formatter, Ruff, Pylint (10/10), Mypy, and Pytest
make check