A crypto-native multi-agent research and paper-trading framework where specialized agents analyze market structure, derivatives, sentiment, catalysts and market regime before a deterministic risk engine approves or rejects each trade.
Circuit Framework is a fork of TradingAgents (Apache 2.0). The internal Python package remains tradingagents for compatibility; user-facing branding, CLI help and crypto workflows are Circuit Framework.
Research only — not financial advice. LLM output can be incorrect. Paper results do not represent live execution. No real trades are placed. This software never calls the Hyperliquid Exchange endpoint and never requests wallet credentials.
flowchart TD
Start([crypto analyze SYMBOL]) --> Snap[Snapshot Builder]
Snap --> MS[Market Structure]
MS --> Der[Derivatives]
Der --> Sent[Sentiment]
Sent --> Cat[Catalyst]
Cat --> Reg[Regime]
Reg --> Bull[Bull Researcher]
Bull --> Bear[Bear Researcher]
Bear --> RM[Research Manager]
RM --> Trader[Trader / Trade Proposal]
Trader --> RiskDebate[Risk Debate]
RiskDebate --> PM[Portfolio Manager]
PM --> Gate[Deterministic Risk Gate]
Gate -->|approved + --paper| Paper[Paper Execution SQLite]
Gate --> Reports[Crypto Report Bundle]
All crypto analysts share one immutable CryptoMarketSnapshot built at the start of the run. Strategies differ by YAML profile (prompts + risk knobs), not by separate data paths.
| Analyst | Focus |
|---|---|
| Market Structure | OHLC, indicators, order book imbalance / spread |
| Derivatives | Funding, OI, premium (public Info API) |
| Sentiment | Social / news signals when available |
| Catalyst | Event / narrative catalysts |
| Regime | Trend, volatility, liquidity, risk-on/off |
After debate, the Trader emits a structured CryptoTradeProposal (LONG / SHORT / NO_TRADE). The Deterministic Risk Gate sizes, clamps, and may reject.
Market data uses only POST https://api.hyperliquid.xyz/info (candles, L2 book, meta/asset contexts, funding history). No authentication. Unit tests load fixtures from tests/fixtures/hyperliquid/ and must not hit the network.
Normalize inputs such as BTC, BTC-USD, BTC-USDT, BTC/USDC, BTC-PERP, ETH, SOL-PERP, HYPE. Hyperliquid perps use the base as venue_symbol (e.g. BTC).
Ship-in YAML under tradingagents/strategies/:
balanced, momentum, mean_reversion, derivatives, narrative, macro_regime, quant_systematic
Same snapshot, fees, risk engine and paper executor — only weights, overlays and risk limits differ.
Proposals include entry band, stop, take-profits, requested size/leverage, confidence, thesis and snapshot_id. Risk rules include stale-data rejection, stop / R:R checks, spread limits, leverage and position clamps, volatility and confidence scalars. NO_TRADE is preserved, never converted into a fill.
pip install -e ".[dev]"
tradingagents crypto analyze BTC
tradingagents crypto analyze ETH --strategy momentum
tradingagents crypto analyze SOL --interval 1h
tradingagents crypto analyze HYPE --strategy derivatives --paper
tradingagents crypto portfolio
tradingagents crypto positions
tradingagents crypto leaderboardPaper DB default: ~/.tradingagents/circuit/paper.db (TRADINGAGENTS_PAPER_DATABASE_PATH).
Programmatic crypto run:
from tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG
from tradingagents.graph.setup import CRYPTO_DEFAULT_ANALYSTS
config = DEFAULT_CONFIG.copy()
ta = TradingAgentsGraph(
selected_analysts=list(CRYPTO_DEFAULT_ANALYSTS),
config=config,
asset_type="crypto",
strategy_profile="balanced",
)
state, decision = ta.propagate(
"BTC",
"2026-07-14",
asset_type="crypto",
strategy_profile="balanced",
)Common overrides (see .env.example):
- LLM:
TRADINGAGENTS_LLM_PROVIDER,TRADINGAGENTS_DEEP_THINK_LLM,TRADINGAGENTS_QUICK_THINK_LLM, provider API keys - Crypto:
TRADINGAGENTS_CRYPTO_VENUE,TRADINGAGENTS_CRYPTO_DEFAULT_INTERVAL,TRADINGAGENTS_DEFAULT_CRYPTO_STRATEGY - Paper:
TRADINGAGENTS_PAPER_STARTING_BALANCE,TRADINGAGENTS_PAPER_FEE_BPS,TRADINGAGENTS_PAPER_SLIPPAGE_BPS,TRADINGAGENTS_PAPER_MAX_LEVERAGE,TRADINGAGENTS_PAPER_DATABASE_PATH
python3 -m pip install -e ".[dev]"
python3 -m pytest -q
python3 scripts/crypto_smoke.pyCrypto tests are offline (fixtures / mocks). No LLM API key required for the unit suite.
- On-chain data is not included until a verified provider is configured.
- Liquidation fields may be unavailable from public Info coverage.
- LLM analysts can be wrong; the risk gate is deterministic but cannot invent edge.
- Paper fills use mid ± slippage and configured fees — not exchange matching.
Built on TradingAgents by Tauric Research (arXiv:2412.20138), licensed under Apache License 2.0. See LICENSE and the upstream repository.
The original stock multi-agent pipeline remains available (asset_type="stock", interactive tradingagents analyze). Analysts: Fundamentals, Sentiment, News, Technical. Data vendors include Yahoo Finance / Alpha Vantage; optional FRED and Polymarket.
tradingagents # interactive stock CLI
python -m cli.main analyzefrom tradingagents.graph.trading_graph import TradingAgentsGraph
from tradingagents.default_config import DEFAULT_CONFIG
ta = TradingAgentsGraph(config=DEFAULT_CONFIG.copy())
state, decision = ta.propagate("AAPL", "2026-01-15")git clone <this-repo>
cd circuit-framework
python3 -m pip install -e ".[dev]"
cp .env.example .env # add LLM API keys for live analysisDocker: docker compose run --rm tradingagents (see upstream compose file).
OpenAI, Google, Anthropic, xAI, DeepSeek, Qwen, GLM, MiniMax, OpenRouter, Ollama, Azure, Bedrock (pip install ".[bedrock]"), and any OpenAI-compatible endpoint via openai_compatible.
- Decision log:
~/.tradingagents/memory/trading_memory.md(crypto entries can include aCRYPTO_METAblock for structured evaluation). - Optional LangGraph checkpoints:
--checkpoint/TRADINGAGENTS_CHECKPOINT_ENABLED.
@misc{xiao2025tradingagentsmultiagentsllmfinancial,
title={TradingAgents: Multi-Agents LLM Financial Trading Framework},
author={Yijia Xiao and Edward Sun and Di Luo and Wei Wang},
year={2025},
eprint={2412.20138},
archivePrefix={arXiv},
primaryClass={q-fin.TR},
url={https://arxiv.org/abs/2412.20138},
}