Author: Manuela Schrittwieser
Co-Developer & Technical Co-Author: Gemini (Google DeepMind)
Repository: github.com/MANU-de/Cryptosentinator
Live Demo: Hugging Face Spaces: Cryptosentinator-v3

1. Abstract

Traditional cryptocurrency sentiment analysis pipelines predominantly rely on isolated natural language processing (NLP) of retail social media feeds. In volatile digital asset markets, these approaches exhibit severe blind spots: they routinely mistake retail FOMO for sustained institutional momentum, overlook leverage imbalances in derivatives markets, and fail to ground strategic hypotheses against verifiable on-chain capital movements.

This paper introduces CryptoSentinator v3, a significant evolution from the foundational multi-agent architecture published in v2. The updated system shifts from synthetic, isolated sentiment scoring to a multi-modal, stateful intelligence pipeline powered by LangGraph, Google Gemini, and Hugging Face serverless open-weight models. Key architectural contributions include:

1. Multi-Source Ingestion: Real-time perpetual swap funding rates, open market microstructure, and DefiLlama on-chain Total Value Locked (TVL) metrics alongside decentralized social signals.
2. Domain-Specific Narrative Clustering: Semantic classification of market data into distinct thematic regimes (Derivatives Leverage, DeFi Health, Institutional Flows, Retail Buzz, Price Momentum).
3. Decoupled Multi-Timeframe Strategy Formulation: Explicit generation of tactical 24-hour momentum hypotheses alongside strategic 7-day trend forecasts, paired with verifiable quantitative invalidation criteria.
4. Persistent Backtesting & Calibration Engine: An automated verification agent that logs historical hypotheses, evaluates directionality against both simulated shocks and live 24-hour market delta, and tracks rolling calibration win rates.
5. Resilient Serving Architecture: High-throughput disk-based caching, graceful fallback between commercial and open-source foundation models (Qwen/Qwen2.5-72B-Instruct), and real-time generator streaming in a Gradio 5+ visual analytics interface.

2. Motivation and Limitations of Preceding Paradigms

In our previous release (v2), CryptoSentinator established a modular 4-agent LangGraph workflow composed of a Scout, Analyst, Strategist, and Evaluator. While v2 validated the multi-agent design pattern for autonomous financial intelligence, practical deployments revealed three fundamental limitations:

• Siloed Semantic Signals: Evaluating retail social media (X/Reddit) in isolation creates false positives during range-bound distributions. Bullish social sentiment that coincides with positive funding rates and declining on-chain liquidity frequently signals a retail long trap rather than an institutional breakout.
• Lack of Temporal Granularity & Falsifiability: Prior hypothesis generation produced broad, non-falsifiable directional predictions (e.g., "Bitcoin exhibits bullish tendencies"). In quantitative asset management, an actionable thesis must explicitly identify the operative time horizon and specify the boundary conditions under which the thesis is invalidated.
• Transient Evaluation: Performance evaluations were ephemeral and executed against simulated outcomes without local persistence, preventing long-term calibration tracking, Brier scoring, or systematic error auditing.

CryptoSentinator v3 was engineered to address these challenges directly.

3. System Architecture & State Graph Design

The engine operates on a strictly typed, immutable acyclic state graph managed by LangGraph. State transitions are governed by an enriched schema defined in graph_state.py:

                 ┌──────────────────────────────────────────────┐
                 │                  Input Query                 │
                 │             (e.g., Target: "BTC")            │
                 └──────────────────────┬───────────────────────┘
                                        │
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │                1. SCOUT AGENT                │
                 │  - Binance Perpetual Funding Rates (8h)      │
                 │  - DefiLlama On-Chain TVL Delta              │
                 │  - Social & News Feeds                       │
                 │  - Local Disk Cache Layer (TTL: 300s)        │
                 └──────────────────────┬───────────────────────┘
                                        │ RawDocument[]
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │         2. INTELLIGENCE ANALYST AGENT         │
                 │  - Crypto Narrative Taxonomy Classification  │
                 │  - Source-Aware Dynamic Sentiment Scoring     │
                 │  - Retail vs. Leverage Polarization          │
                 └──────────────────────┬───────────────────────┘
                                        │ ProcessedDocument[]
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │             3. STRATEGIST AGENT              │
                 │  - Multi-Timeframe Decoupling                │
                 │    [24h Tactical] vs [7d Strategic]          │
                 │  - Quantitative Invalidation Criteria        │
                 │  - Model Router (Gemini 2.0 Flash / Qwen 72B)│
                 └──────────────────────┬───────────────────────┘
                                        │ StrategicSummary[]
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │             4. EVALUATOR AGENT               │
                 │  - Dual Benchmarking (Simulated + Live 24h)  │
                 │  - Timeframe-Aware Directional Matcher       │
                 │  - Persistent Logging (backtest_history.jsonl)│
                 │  - Rolling Win-Rate & Calibration Engine     │
                 └──────────────────────┬───────────────────────┘
                                        │
                                        ▼
                 ┌──────────────────────────────────────────────┐
                 │         Gradio 5+ Streaming Interface         │
                 │  - Plotly Dynamic Narrative Heatmap          │
                 │  - Markdown Intelligence Briefing Export     │
                 └──────────────────────────────────────────────┘

Graph State Schema Specifications

The state container enforces strict type safety across agent boundaries using Python TypedDict primitives:

class RawDocument(TypedDict):
    source: str
    content: str
    timestamp: str
    keyword: str

class ProcessedDocument(RawDocument):
    sentiment_score: Optional[float]
    sentiment_label: Optional[str]
    topic: Optional[str]
    entities: Optional[List[str]]

class StrategicSummary(TypedDict):
    cryptocurrency: str
    hypothesis: str
    confidence: str
    reasoning: str
    supporting_evidence: List[str]

class PerformanceEvaluation(TypedDict):
    cryptocurrency: str
    hypothesis_tested: str
    simulated_outcome: str
    evaluation_result: str
    evaluation_notes: str

class GraphState(TypedDict):
    keywords: List[str]
    raw_documents: List[RawDocument]
    processed_documents: List[ProcessedDocument]
    strategic_summaries: List[StrategicSummary]
    evaluation: Optional[PerformanceEvaluation]

4. Agent Implementations & Methodologies

4.1. Scout Agent: Multi-Source Microstructure & On-Chain Ingestion

Rather than relying purely on text search APIs, the updated Scout Agent queries live financial infrastructure without imposing mandatory paid third-party subscriptions:

• Perpetual Swap Funding Rates: By probing the public Binance Futures API (/fapi/v1/fundingRate), the Scout measures the periodic fee paid between long and short contract holders. A funding rate per 8-hour epoch indicates crowded long leverage vulnerable to cascading liquidations, whereas denotes aggressive short-positioning.
• On-Chain Fundamentals (TVL): The agent interfaces with the DefiLlama REST API (/v2/historicalChainTvl/) to compute 24-hour percentage variations in smart contract capital allocation (), establishing a quantitative baseline for organic adoption.
• Fault-Tolerant Cache: All external calls pass through a deterministic disk-backed hashing layer (@disk_cache(ttl_seconds=300)). If an upstream API returns an HTTP 429 rate-limiting status code, the Scout falls back to stale cache entries, protecting the host system from runtime failures.

4.2. Intelligence Analyst: Narrative Taxonomy & Source-Aware NLP

A central contribution of v3 is the move away from uniform sentiment scoring. The Analyst Agent implements a structured narrative taxonomy:

The agent evaluates sentiment contextually based on data provenance:

1. Derivatives Documents: The sentiment score is computed as a composite of funding rate posture and 24-hour spot price momentum:
   
2. On-Chain Documents: Scaled directly from network capital growth:
   
3. Unstructured Social Text: Analyzed via semantic polarity extraction over a domain-calibrated lexicon balancing retail exuberance against macro-economic risk.

Each ingested document is transformed into a ProcessedDocument with an explicit narrative category tag and normalized sentiment score.

4.3. Strategist Agent: Multi-Timeframe Decoupling & Invalidation Boundaries

The Strategist Agent synthesizes processed evidence into actionable intelligence using advanced foundation models. Rather than predicting a generic trajectory, the agent prompt enforces a rigorous, falsifiable hypothesis structure:

{
  "cryptocurrency": "BTC",
  "hypothesis": "[24h Tactical]: Expect range-bound consolidation with high volatility as retail sentiment remains fractured. [7d Strategic]: Bullish bias supported by resilient on-chain TVL growth suggesting institutional capital accumulation despite short-term social noise. [Invalidation Trigger]: A decisive breakdown below the $80,000 support level combined with a spike in perpetual swap funding rates to negative territory.",
  "confidence": "Medium",
  "reasoning": "Market sentiment is currently bifurcated...",
  "supporting_evidence": [...]
}

Falsification Mechanics

The inclusion of an explicit Invalidation Trigger converts LLM narrative outputs into testable strategies. If spot price action breaches support or leverage indicators flip sign, downstream algorithmic systems or human operators can reject the strategic thesis before significant capital degradation occurs.

4.4. Evaluator Agent: Persistent Backtesting Engine

The updated Evaluator Agent implements an empirical feedback loop:

1. Timeframe-Aware Directional Matcher: The evaluator parses the structured hypothesis string, isolating the [24h Tactical] clause using regular expressions to evaluate immediate market movement rather than misinterpreting longer-term strategic optimism as an immediate forecasting error.
2. Persistent State Storage: Every evaluation run is appended to backtest_history.jsonl, storing the timestamp, target asset, full hypothesis string, simulated stress outcome, actual Binance 24h market delta, result category (Correct, Partially Correct, Incorrect), and scalar accuracy score.
3. Cumulative Calibration Metrics: Upon each cycle, the evaluator ingests historical logs to calculate a rolling, weighted Win Rate:
   
   This value is integrated directly into the final analytical output to communicate historical reliability to the user.

5. Model-Agnostic LLM Routing & Infrastructure Hardening

To guarantee accessibility across both commercial cloud endpoints and the open-source community, CryptoSentinator v3 replaces hardcoded API calls with a dynamic routing abstraction layer (tools/llm_client.py):

                      ┌────────────────────────────┐
                      │    Input Strategy Prompt   │
                      └─────────────┬──────────────┘
                                    │
                                    ▼
                      ┌────────────────────────────┐
                      │    Check GEMINI_API_KEY?   │
                      └──────┬──────────────┬──────┘
                             │ Yes          │ No / Error (429)
                             ▼              │
                  ┌──────────────────────┐  │
                  │ Google Gemini API    │  │
                  │ (gemini-2.0-flash)   │  │
                  └──────────┬───────────┘  │
                             │              │
                             ▼ Fail         ▼
                  ┌────────────────────────────────────────┐
                  │ Hugging Face Serverless Inference API  │
                  │ Model: Qwen/Qwen2.5-72B-Instruct       │
                  │ Token: Injected HF_TOKEN (Zero-Cost)   │
                  └──────────────────┬─────────────────────┘
                                     │
                                     ▼
                      ┌────────────────────────────┐
                      │    Validated Output JSON   │
                      └────────────────────────────┘

1. Primary Provider (Gemini): Leverages gemini-2.0-flash-lite-preview for high-throughput, low-latency synthesis.
2. Autonomous Community Fallback (Hugging Face Serverless): If GEMINI_API_KEY is absent, or if quota limits are exceeded, the router automatically dispatches the prompt via huggingface_hub.InferenceClient to Qwen/Qwen2.5-72B-Instruct or meta-llama/Llama-3.3-70B-Instruct. This allows the Hugging Face Space to operate out-of-the-box without requiring visitors to provide personal API credentials.
3. ZeroGPU Lifecycle Optimization: To resolve container startup scans and prevent worker thread deadlocks in Hugging Face ZeroGPU environments, we isolate GPU decorators to non-blocking worker stubs while allowing the core event loop to stream asynchronously on host CPUs.

6. User Interface & Observability Engine

The Gradio 5+ visual interface was rebuilt to prioritize execution transparency and data density:

• Progressive Generator Streaming: Implementing a Python generator (yield) pipeline enables the UI to provide real-time status notifications as each agent begins and completes its task, displaying intermediate states instead of freezing during execution.
• Interactive Narrative Heatmap: Using Plotly, the interface renders a dual-panel analytical chart displaying:
  1. Horizontal divergence bar chart illustrating relative sentiment across the 5 core market narratives.
  2. Evaluator calibration score gauge visualizing ground-truth alignment.
• Exportable Intelligence Briefing: A gr.DownloadButton dynamically packages the multi-agent findings, narrative distributions, supporting microstructure citations, and cumulative backtest stats into an executive Markdown briefing (.md).

7. Comparative Evaluation: v2 vs. v3

8. Reproducibility & Deployment

The codebase is structured as a standard, self-contained Python package designed for containerized or virtual environment execution:

# Clone the v3.0.0 release
git clone -b v3.0.0 https://github.com/MANU-de/Cryptosentinator.git
cd Cryptosentinator

# Initialize isolated environment
python3 -m venv .venv
source .venv/bin/activate

# Install dependencies (strictly pinning Pydantic for schema stability)
pip install -r requirements.txt

# Run CLI verification suite
python main.py

# Launch interactive visual analytics terminal
python app.py

9. Conclusion, Authorship & Acknowledgments

CryptoSentinator v3 demonstrates that autonomous financial agents become substantially more reliable when conversational LLMs are bound to verifiable market microstructure data, explicit temporal scopes, and continuous, persistent backtesting. By transitioning from isolated social sentiment to a unified multi-modal state graph, the system bridges the gap between natural language processing and quantitative digital asset research.

Authorship & Contributions

• Manuela Schrittwieser (Lead Architect & Developer): Conceptualized the multi-agent architecture, authored system specifications, implemented graph schemas, integrated market data providers, and orchestrated deployment across GitHub and Hugging Face.
• Gemini by Google DeepMind (Co-Developer & Technical Co-Author): Actively co-engineered the algorithmic pipeline, designed the domain-specific narrative taxonomy, authored the fault-tolerant caching and model-agnostic routing infrastructure, resolved containerized ZeroGPU synchronization bottlenecks, and contributed to technical documentation.

Future Work

Future iterations will explore the integration of high-frequency order book imbalance metrics (via WebSocket L2 feeds), automated Bayesian prompt optimization driven by evaluator backtest regressions, and on-chain trade execution hooks via decentralized smart contract routers.

References & Data Providers

1. Binance Developer Documentation — Futures Funding Rate & Microstructure Endpoints.
2. DefiLlama Open API Documentation — Historical Chain and Protocol TVL Metrics.
3. LangGraph & LangChain Documentation — StateGraph and Cyclic Multi-Agent Systems.
4. Hugging Face Spaces Documentation — ZeroGPU Integration and Serverless Inference API.
5. Qwen 2.5 Technical Report — Foundation Models for Code, Mathematics, and Analytical Reasoning.