Solution

Financial Sentinel - Hackathon Submission

Real-time Financial Institution Risk Monitoring powered by X API + Grok AI

Inspiration

The inspiration for Financial Sentinel came from the 2023 banking crisis when Silicon Valley Bank collapsed in just 48 hours. Social media, particularly X (Twitter), showed warning signs hours before mainstream news outlets reported the story. Retail investors and customers who weren't monitoring social media had no early warning system.

We realized that idiosyncratic risk (institution-specific threats) spreads on social media before it hits traditional financial news. Whether it's a crypto exchange freezing withdrawals, a trading app halting orders, or a bank experiencing unusual activity, these signals appear on X first.

The problem: No one has time to monitor dozens of financial institutions on social media 24/7.

Our solution: Financial Sentinel - an AI-powered early warning system that monitors 30+ financial institutions in real-time, analyzes sentiment using Grok AI, and alerts you to risks before they become crises.

What it does

Financial Sentinel is a real-time monitoring system that:

Core Features

Multi-Institution Monitoring
- Tracks 30+ institutions across 7 categories (User can provide any in chat):
  - Traditional banks (Chase, Wells Fargo, Bank of America)
  - Crypto exchanges (Coinbase, Binance, Kraken)
  - Crypto wallets (MetaMask, Phantom, Ledger)
  - Stock trading platforms (Robinhood, Fidelity, E*TRADE)
  - Robo-advisors (Wealthfront, Betterment)
  - Payment apps (Venmo, Cash App, PayPal)
  - Neobanks (Chime, SoFi, Revolut)
- This was to simulate a user portfolio
Real-time Risk Analysis
- Fetches live tweets from X API using multiple endpoints
- Analyzes sentiment with Grok 4.1 Fast
- Calculates viral risk scores (0-100) based on engagement velocity
- Detects volume spikes using trend analysis
- Weights signals by account verification status
Progressive Streaming Updates
- Server-Sent Events (SSE) for real-time progress
- See analysis stages as they happen:
  - "Fetching tweets from X API..."
  - "Fetched 87 tweets"
  - "Volume trend: +45.2%"
  - "Running Grok sentiment analysis..."
  - "Analysis complete: MEDIUM risk"
Automated Alerting
- Slack alerts for HIGH/MEDIUM risk findings
- Rich formatting with evidence tweets
- Direct links to source posts for verification
Full Traceability
- Every finding includes direct tweet URLs
- Evidence-based analysis with source attribution
- Confidence scores for all assessments

How we built it

Architecture Overview

Financial Sentinel uses a sophisticated tech stack designed for real-time responsiveness and robust API integration:

Backend Stack

FastAPI - REST + SSE streaming endpoints
Google ADK - AI agent orchestration
AG-UI Protocol - CopilotKit ↔ ADK communication bridge
X API v2 (xdk SDK) - Multi-endpoint integration:
- /tweets/search/recent - Primary tweet fetching
- /tweets/counts/recent - Volume trend detection
- /users/by - Author verification lookup
Grok 4.1 Fast - Sentiment analysis and risk assessment
LiteLLM - Unified LLM interface for Grok integration
Slack SDK - Alert notifications

Frontend Stack

Next.js 16 - React SSR framework
React 19 - Latest React with concurrent features
CopilotKit - AI chat interface with AG-UI client
Tailwind CSS v4 - Utility-first styling
Recharts - Data visualization for trends
Framer Motion - Smooth animations

Key Implementation Decisions

1. Multi-Endpoint X API Integration

Instead of using just one endpoint, we leverage three X API endpoints for comprehensive data:

# Endpoint 1: Rich tweet data with full metadata
tweets = client.posts.search_recent(
    query=f'"{institution}" (outage OR hack OR fraud) -is:retweet lang:en',
    max_results=100,
    tweet_fields=['created_at', 'public_metrics', 'author_id', 'text'],
    expansions=['author_id'],
    user_fields=['username', 'verified', 'verified_type', 'public_metrics']
)

# Endpoint 2: Volume analysis for spike detection
counts = client.posts.counts(
    query=query,
    granularity='hour',
    start_time=24_hours_ago
)
velocity = (recent_volume - older_volume) / older_volume * 100

# Endpoint 3: Author verification for credibility weighting
users = client.users.by_usernames(usernames=['CoinbaseSupport', 'binance'])

2. Circuit Breaker Pattern for Resilience

We implemented a production-grade circuit breaker to handle API failures gracefully:

class CircuitBreaker:
    CLOSED -> OPEN (5 failures) -> HALF_OPEN (60s timeout) -> CLOSED (3 successes)

This prevents cascade failures and provides automatic recovery when APIs are temporarily unavailable.

3. Viral Risk Scoring Algorithm

We developed a sophisticated scoring system that weighs multiple factors:

engagement_score = (retweets × 3) + (quotes × 2) + (replies × 1.5) + likes
verification_weight = {
    'business': 2.0,  # @CoinbaseSupport
    'verified': 1.5,  # Blue checkmark
    'regular': 1.0    # Standard account
}
influence_score = min(log10(followers), 10)
viral_score = weighted_average(engagement, verification, influence) × 100

4. Server-Sent Events for Real-time UX

Instead of polling or WebSockets, we use SSE for one-way streaming from server to client:

const eventSource = new EventSource('/stream/analyze/Chase');

eventSource.addEventListener('status', (e) => {
  // "Fetching tweets from X API..."
});

eventSource.addEventListener('progress', (e) => {
  // "Fetched 87 tweets"
});

eventSource.addEventListener('result', (e) => {
  // Final analysis with risk level, viral score, evidence
});

This provides a superior UX where users see each analysis stage in real-time.

Challenges we ran into

1. X API Tweet Counts Endpoint

Problem: The official xdk SDK doesn't support the /tweets/counts/recent endpoint, which we needed for trend velocity calculation. Initially, our trend showed "0% (spiking volume)" - a contradiction.

Solution: We implemented a hybrid approach using the xdk SDK for tweet fetching but direct REST API calls for counts:

def get_tweet_counts(self, query: str, granularity: str = "hour") -> Dict:
    """Direct REST API call to /tweets/counts/recent"""
    url = "https://api.x.com/2/tweets/counts/recent"
    response = requests.get(url, headers=headers, params=params)

    # Calculate velocity from time series buckets
    midpoint = len(time_series) // 2
    recent_volume = sum(bucket['tweet_count'] for bucket in time_series[midpoint:])
    older_volume = sum(bucket['tweet_count'] for bucket in time_series[:midpoint])
    velocity = ((recent_volume - older_volume) / older_volume) * 100

2. Rate Limit Management

Problem: With 30+ institutions and real-time monitoring, we quickly hit X API rate limits (1500 requests per 15 minutes).

Solution: Three-tier approach:

Circuit Breaker - Prevents hammering failed endpoints
Exponential Backoff - Retry with jitter (1s → 60s max delay)
Grok Live Search Fallback - When rate limited, switch to Grok's built-in search

@with_retry(max_attempts=3, exceptions=(Exception,))
@sleep_and_retry
@limits(calls=1500, period=900)  # Pro tier limits
def search_recent_tweets(self, query: str):
    try:
        return self.client.posts.search_recent(query)
    except RateLimitException:
        # Fall back to Grok Live Search
        return self.grok_fallback_search(query)

3. Grok Analysis Grounding

Problem: Initial Grok responses were generic and didn't cite specific tweets as evidence.

Solution: We engineered a structured prompt that forces grounded, traceable analysis:

prompt = f"""Analyze these {len(tweets)} tweets for {institution} risk.

REQUIREMENTS:
1. Cite SPECIFIC tweets with URLs
2. Include engagement metrics (RTs, likes)
3. Weight by verification status
4. Return structured JSON with evidence

Tweets: {json.dumps(tweet_data)}

Return JSON:
{{
  "risk_level": "HIGH|MEDIUM|LOW",
  "top_concerning_tweets": [
    {{"text": "...", "url": "https://x.com/...", "why_concerning": "..."}}
  ]
}}
"""

4. Frontend Performance with Real-time Updates

Problem: SSE streaming caused UI jank when updating multiple institutions simultaneously.

Solution: Implemented optimistic updates with React 19's concurrent features and debounced rendering:

const [streamingResults, setStreamingResults] = useState<StreamingResult[]>([]);

eventSource.addEventListener("result", (event) => {
  const data = JSON.parse(event.data);

  // Batch updates to avoid re-renders
  setStreamingResults(prev => [...prev, {
    id: `result-${institution}-${Date.now()}`,
    institution,
    analysis: data.analysis,
    timestamp: new Date()
  }]);
});

5. Navigating Multiple Developer Portals

Problem: The X/xAI ecosystem has multiple developer portals that created significant confusion:

x.ai console (console.x.ai) - For Grok API keys and billing
X Developer Portal (New) (console.x.com) - For X API v2 credentials
X Developer Portal (Old) (developer.x.com) - Legacy portal still referenced in some docs
API.x.com vs API.x.ai - Two completely different API endpoints

This split caused confusion when:

Setting up authentication (which API key goes where?)
Finding parameter documentation (scattered across portals)
Debugging errors (is this an X API issue or Grok API issue?)
Understanding rate limits (different limits for each service)

Solution: We created a clear separation in our codebase and documentation:

# tools.py - Clear separation of concerns

class XAPIClient:
    """Handles X API (api.x.com) - tweets, users, counts"""
    def __init__(self):
        self.bearer_token = os.getenv("X_BEARER_TOKEN")  # From developer.x.com
        self.base_url = "https://api.x.com/2"

class GrokClient:
    """Handles Grok AI (api.x.ai) - sentiment analysis"""
    def __init__(self):
        self.api_key = os.getenv("XAI_API_KEY")  # From console.x.ai
        self.base_url = "https://api.x.ai/v1"

Lessons learned:

Keep environment variables clearly named (X_BEARER_TOKEN vs XAI_API_KEY)
Document which portal each credential comes from
Bookmark the correct portal URLs in our team wiki
When in doubt, check the API base URL to know which service you're calling

6. Filtered Stream Silent Failures

Problem: The X API Filtered Stream (/tweets/search/stream) would hit rate limits and silently fail without returning any error response. The connection would:

Hang for 30+ seconds with no data
Eventually timeout without explanation
Not return a proper HTTP error code
Leave no clear indication of why it failed

This made debugging extremely difficult - was it a network issue? Authentication problem? Rate limit? We had no visibility.

Solution: Implemented a robust fallback system with timeout-based detection:

async def start_live_stream():
    """Try filtered stream with 30s timeout, fallback to polling"""
    try:
        # Attempt filtered stream (SSE)
        es = new EventSource("http://localhost:8000/monitor/stream")

        # Set a 30-second timeout
        timeout = setTimeout(() => {
            if (no_data_received) {
                console.log("No data from filtered stream, falling back to polling");
                es.close();
                startPollingFallback();  // Fall back to search API
            }
        }, 30000);

        es.addEventListener("tweet", (event) => {
            clearTimeout(timeout);  // Data received, stream is working
            // Process tweet...
        });

    } catch (e) {
        // Immediate fallback on connection error
        startPollingFallback();
    }
}

function startPollingFallback() {
    """Polling mode using /tweets/search/recent"""
    setInterval(async () => {
        const tweets = await fetch("/monitor/poll", {
            method: "POST",
            body: JSON.stringify({ institutions: selected })
        });
        // Process tweets...
    }, 15000);  // Poll every 15 seconds
}

Key improvements:

30-second timeout - If no data arrives, assume stream failure
Graceful degradation - Automatically switch to polling mode
User feedback - Show clear status: "Using search API polling (every 15s)"
No data loss - Polling mode provides same functionality, just different mechanism
Monitoring - Log stream failures for debugging

UI feedback implementation:

// Show users which mode is active
{liveStreamActive && (
  <div className="status-indicator">
    {usePolling ? (
      <span>📡 Polling mode (search API every 15s)</span>
    ) : (
      <span>🔴 Live stream active (filtered stream)</span>
    )}
  </div>
)}

This turned a silent failure into a transparent, self-healing system that users can understand and trust.

Accomplishments that we're proud of

1. Deep X API Integration Excellence

We didn't just use the X API - we mastered it with sophisticated multi-endpoint usage:

Combined search, counts, and users endpoints for comprehensive analysis
Implemented proper pagination handling for large result sets
Built a resilient circuit breaker pattern for production reliability
Achieved full traceability with tweet URLs in every finding

2. Real-time Responsiveness

Our SSE streaming implementation provides instant visibility into the analysis process:

Users see each stage as it happens (fetching → analyzing → complete)
Progressive updates keep the UI responsive
No black-box waiting - full transparency

3. Intelligent Viral Scoring

Our scoring algorithm goes beyond simple sentiment:

Engagement velocity (how fast tweets are spreading)
Verification weighting (official accounts matter more)
Influence scoring (follower count impact)
Time-series trend detection (is volume spiking?)

This produces a 0-100 viral risk score that's more actionable than simple positive/negative sentiment.

4. Production-Grade Resilience

We built enterprise-quality error handling:

Circuit breaker prevents cascade failures
Exponential backoff with jitter for retries
Graceful fallback to Grok Live Search when rate limited
Per-institution error isolation (one failure doesn't affect others)

5. Full Evidence Traceability

Every finding is backed by verifiable evidence:

Direct tweet URLs for manual verification
Author information with verification status
Engagement metrics (RTs, likes, replies)
Confidence scores for all assessments

This makes Financial Sentinel trustworthy - you can always verify claims.

What we learned

Technical Learnings

Multi-Endpoint API Design
- Using multiple endpoints synergistically is more powerful than any single endpoint
- The counts endpoint (/tweets/counts/recent) is essential for trend detection
- Combining structured data (search) with aggregate data (counts) provides richer insights
Circuit Breaker Pattern in Production
- Essential for any production system calling external APIs
- Three states (CLOSED → OPEN → HALF_OPEN) provide automatic recovery
- Prevents cascade failures and resource exhaustion
Grok Prompt Engineering
- Grok performs best with structured output requirements (JSON schemas)
- Grounding requires explicit instructions to cite evidence
- Live Search mode is a powerful fallback when rate limited
SSE vs WebSockets
- SSE is simpler for one-way server→client streaming
- Built-in reconnection logic in browsers
- More efficient than polling, easier to implement than WebSockets
React 19 Concurrent Features
- useTransition is powerful for non-blocking state updates
- Concurrent rendering prevents UI jank during rapid updates
- Suspense boundaries improve loading states

Product Learnings

Social Media as Early Warning System
- Twitter/X consistently shows crisis signals 2-12 hours before mainstream news
- Official accounts (@CoinbaseSupport) often acknowledge issues on X first
- Verified accounts and high-engagement posts are reliable risk indicators
Context-Aware Analysis
- Different institution types have different risk patterns:
  - Banks: "FDIC", "bank run", "withdrawal freeze"
  - Crypto: "rug pull", "withdrawal paused", "funds locked"
  - Trading: "order stuck", "margin call", "trading halted"
- Generic sentiment analysis isn't enough - need category-specific signals
Viral Velocity Matters
- Not just what's being said, but how fast it's spreading
- A post going viral (high RT/like velocity) indicates broader concern
- Spike detection (>50% volume increase) is a strong risk signal

What's next for Financial Sentinel

Short-term Enhancements (Next 2 weeks)

Historical Trend Analysis
- Store analysis results in a time-series database (InfluxDB)
- Build interactive charts showing risk evolution over time
- Alert when institutions shift from LOW → MEDIUM → HIGH risk
Mobile Alerts
- iOS/Android push notifications for HIGH risk alerts
- WhatsApp integration for instant notifications
- SMS fallback for critical alerts
Portfolio Tracking
- User accounts with saved institution lists
- Custom watchlists (e.g., "My Crypto Portfolio", "My Trading Accounts")
- Daily digest emails with risk summaries

Medium-term Features (Next 2 months)

Advanced AI Analysis
- Multi-agent system with specialized agents per institution type
- Cross-institution correlation detection (e.g., contagion risk)
- Predictive risk modeling using historical patterns
Enhanced X API Integration
- Full filtered stream implementation (real-time firehose)
- Conversation thread analysis (replies/quote tweets)
- Media analysis (screenshots of app errors)
Compliance & Reporting
- Automated regulatory filing monitoring (SEC, FDIC alerts)
- Risk reports exportable to PDF
- Audit trail for all alerts and findings

Long-term Vision (6+ months)

Institutional Product
- Dedicated alerting for compliance teams at banks/exchanges
- API access for integration with risk management systems
- White-label solution for financial institutions
Multi-Platform Monitoring
- Reddit integration (r/CryptoCurrency, r/wallstreetbets)
- Discord monitoring for crypto communities
- Telegram group analysis
Predictive Models
- Machine learning models trained on historical crisis patterns
- Anomaly detection using baseline vs. current metrics
- Early warning scores (12-24 hours before crisis)

Infrastructure Scaling

Production Deployment
- Kubernetes deployment for horizontal scaling
- Redis caching layer for API responses
- PostgreSQL + TimescaleDB for time-series data
- Grafana dashboards for system monitoring