🦄 Unicorn.Land Dashboard

Overview

A production-ready FastAPI dashboard for monitoring Unicorn.Land’s crypto arbitrage operations, providing real-time insights into system performance, trade execution, and market scanning activities.

Features

📊 Real-Time Monitoring

• Scan Performance: Track market discovery, pair matching, and execution timing
• Trade Metrics: Monitor spreads, slippage, fill probabilities, and P&L
• System Health: Database status, API connectivity, and operational metrics

📈 Visualizations

• Interactive Charts: Chart.js powered real-time graphs
• Scan Timeline: Duration, pairs found, threshold analysis
• Trade Analysis: Net spreads, slippage tracking, execution quality

🔧 Production Ready

• Railway Deployment: Automatic PORT detection and health checks
• Authentication: Token-based access control via DASH_AUTH_TOKEN
• Database: SQLite with WAL mode for concurrent access
• Monitoring: Prometheus metrics endpoint at /metrics

Quick Start

Local Development

# Install dependencies
pip install fastapi uvicorn jinja2 prometheus_client

# Start dashboard
python main.py dashboard

# Access at http://localhost:8080

Railway Deployment

# Set environment variables
DASH_AUTH_TOKEN=your-secure-token
UNICORN_DB_PATH=/data/unicorn.db

# Deploy with Procfile
web: python main.py dashboard

API Endpoints

Dashboard

• GET / - Main dashboard interface
• GET /healthz - Health check for Railway
• GET /status - System status JSON

Data APIs

• GET /api/scans?limit=50 - Recent scan metrics
• GET /api/trades?limit=50 - Recent trade data
• GET /api/stats - 24h system statistics

Monitoring

• GET /metrics - Prometheus metrics
• GET /ready - Readiness probe

Configuration

config.yaml

dashboard:
  enabled: true
  host: "0.0.0.0"
  port: 8080
  auth_token: ""   # set DASH_AUTH_TOKEN env for security

summaries:
  telegram_rollup_enabled: true
  rollup_hour_utc: 22

Environment Variables

# Required for Railway
PORT=8080                    # Auto-set by Railway
UNICORN_DB_PATH=/data/unicorn.db  # Persistent storage path
DASH_AUTH_TOKEN=secure-token      # Dashboard authentication

# Optional
LOG_LEVEL=INFO

Metrics Collection

Scan Metrics

• Markets: Polymarket/Kalshi market counts
• Discovery: Candidates found, pairs matched
• Performance: Duration, above-threshold opportunities
• Filtering: Thin liquidity, mismatched pairs

Trade Metrics

• Execution: Size, venues, success rates
• Pricing: Net spreads, basis penalties, slippage
• Quality: Fill probabilities, execution scores
• Risk: Hedge usage, position sizes

Database Schema

scan_metrics

CREATE TABLE scan_metrics(
  id INTEGER PRIMARY KEY,
  ts_utc INTEGER,
  pm_markets INT, ks_markets INT, candidates INT, pairs INT,
  above_threshold INT, auto INT, approve INT,
  skipped_thin INT, skipped_mismatch INT, duration_ms INT
);

trade_metrics

CREATE TABLE trade_metrics(
  id INTEGER PRIMARY KEY,
  ts_utc INTEGER, opp_id TEXT,
  venue_long TEXT, venue_short TEXT,
  size_usd REAL, net_spread_bps REAL, raw_net_spread_bps REAL,
  basis_penalty_bps REAL, fill_prob REAL, quality REAL,
  status TEXT, realized_slippage_bps REAL, hedge_used INT
);

Architecture

Components

• FastAPI Server: High-performance async web framework
• SQLite + WAL: Concurrent database access
• Jinja2 Templates: Server-side rendering
• Chart.js: Client-side visualizations
• Prometheus: Metrics collection

Integration Points

• CryptoArbitrageScanner: Collects scan performance data
• ArbitrageExecutor: Records trade execution metrics
• Storage Layer: Persistent metrics with WAL mode
• Metrics Collector: Centralized data collection

Deployment

Railway Setup

1. Connect Repository: Link your GitHub repo to Railway
2. Set Environment Variables: DASH_AUTH_TOKEN=your-secure-random-token UNICORN_DB_PATH=/data/unicorn.db
3. Add Volume: Mount persistent storage at /data
4. Deploy: Railway will auto-detect the Procfile

Health Checks

• Startup: /healthz validates database connectivity
• Readiness: /ready confirms service availability
• Liveness: Automatic via Railway infrastructure

Security

• Authentication: Token-based access control
• CORS: Configured for production use
• Rate Limiting: Built into FastAPI
• Input Validation: Automatic via Pydantic

Monitoring & Alerting

Prometheus Metrics

unicorn_scan_pairs_total - Total pairs found per scan
unicorn_scan_above_threshold_total - Pairs above threshold
unicorn_scan_duration_ms - Scan duration in milliseconds
unicorn_trade_volume_usd_total - Total trade volume
unicorn_trade_spread_bps - Average trade spread
unicorn_system_health - System health status

Dashboard Alerts

• System health indicators (green/yellow/red)
• Performance degradation warnings
• Trade execution failures
• Database connectivity issues

Troubleshooting

Common Issues

1. Database Lock: Ensure WAL mode is enabled
2. Port Conflicts: Railway sets PORT automatically
3. Template Errors: Check Jinja2 template syntax
4. Metrics Missing: Verify collector integration

Debug Mode

# Enable debug logging
LOG_LEVEL=DEBUG python main.py dashboard

# Check database
sqlite3 data/unicorn.db ".tables"

# Test metrics endpoint
curl http://localhost:8080/metrics

Development

Adding New Metrics

1. Update Schema: Add columns to metrics tables
2. Collector Integration: Record data in scanner/executor
3. Dashboard Display: Add to template and charts
4. API Endpoints: Expose via REST API

Custom Visualizations

1. Chart.js Config: Modify dashboard template
2. Data Processing: Update server.py queries
3. Styling: Enhance PicoCSS classes
4. Responsive Design: Mobile-friendly layouts

🚀 Production Checklist

• ✅ FastAPI server with async support
• ✅ SQLite database with WAL mode
• ✅ Token-based authentication
• ✅ Railway deployment ready
• ✅ Health checks and monitoring
• ✅ Prometheus metrics
• ✅ Real-time charts and visualizations
• ✅ Responsive UI design
• ✅ Error handling and logging
• ✅ Production configuration

Unicorn.Land Dashboard is ready for production deployment! 🦄