uforia

Research-first trading platform scaffold with:

• BTC/ETH VVIX ingestion, storage, and analytics
• BTC/ETH Razor signal construction
• BTC/ETH options analytics dashboards and composite options signals
• BTC/ETH perps analytics dashboards and composite perps signals
• medium-horizon microstructure import, training, prediction, and UI family
• DEX execution control-plane family for Derive, Hyperliquid, Lighter, and Bebop
• native Rust microstructure live-feed collection and book reconstruction
• DB-first storage: Postgres for runtime and retention
• Deribit options archiver
• Python read-only API
• Next.js internal research UI

Documentation:

• Terminal Client
• Overview
• Multi-Asset Vol Suite
• Options Surface
• Options Carry / VRP
• Options Skew
• Options Dislocations
• Options Relative Value
• Options Positioning
• Options Vol Cone
• Options Term Structure Momentum
• Options Gamma Exposure
• Options Funding Context
• Options Straddle Breakeven
• Options Vol Regime Transitions
• Options Signals
• Crypto Derivatives Alpha Canvas
• Options Surface Factor RV
• Options ML Carry Toxicity
• Options Expiry Flow Map
• Options Adaptive Hedging
• Options Sessionality Clocks
• Options BTC-ETH Dispersion
• Options Funding-Basis Skew Interactions
• Perps Funding-Basis Carry
• Perps Liquidation Cascade
• Perps Order Flow Toxicity
• Perps OI-Price Divergence
• Perps Cross-Venue Price Discovery
• Perps Depth Resilience
• Perps Volatility Microstructure
• Perps Cumulative Delta Momentum
• Composite Index
• Composite Methodology
• Composite Regimes
• Microstructure System
• Execution Layer
• BTC VVIX Pipeline
• Storage and Archiver
• UI Platform
• Local Development
• Mac Mini Setup
• Timescale Migration

Quick start:

uv sync --extra dev
npm install
cp apps/web/.env.local.example apps/web/.env.local
npm run dev

Optional local Timescale bootstrap:

./ops/run-db.sh
export UFORIA_DB_ENABLED=true
export UFORIA_DB_DSN=postgresql://uforia:uforia@127.0.0.1:5432/uforia
uv run uforia-admin db init

Terminal client:

uv run uforia --help
uv run uforia overview show --asset BTC
uv run uforia --json signals show btc_vvix

Note:

• global output flags such as --json, --ndjson, and --compact go before the command path
• the public client defaults to https://uforia.polynomial.fi
• the default terminal timeout is 20s

Public client defaults:

• console script: uforia
• env vars:
  • UFORIA_API_BASE_URL
  • UFORIA_TIMEOUT_SECONDS
  • UFORIA_OUTPUT
• output modes:
  • rich
  • --json
  • --ndjson
  • --compact for tighter agent-oriented summaries

Deployment docs:

• GCP deployment
• Mac Mini setup

Production deployment defaults:

• UFORIA_DB_ENABLED=true
• UFORIA_DB_READ_MODE=db
• UFORIA_DB_WRITE_MODE=db
• production images and ArgoCD config target polynomial-uforia
• auto-deploy is driven by .github/workflows/prod-deploy.yml

UI families:

• Signals: VVIX, Razor, and individual microstructure prediction signals
• Composite: BTC, ETH, and market-wide sentiment, direction, and fragility indices
• Options: the full options analytics dashboard family
• Perps: perp-market structure, carry, liquidation, flow, and fragility dashboards
• Microstructure: overview, predictions, regime, features, calibration, backtests, and engine health
• Execution: venue capabilities, markets, order entry, orders, fills, positions, balances, and venue health

Execution mode notes:

• dry_run and paper are safe-by-default operator modes
• live is implemented for Hyperliquid, Lighter, and Derive through the Python execution adapters
• Bebop supports live quote requests and quote-driven execution via self-broadcast or gasless submission metadata

Operational assets:

• repo-managed runners in ops/
• checked-in macOS service templates in launchd/

Build the current multi-asset vol suite locally:

for UNDERLYING in BTC ETH; do
  uv run uforia-admin ingest deribit-dvol --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin ingest deribit-funding --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-index --underlying "$UNDERLYING" --source dvol --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build rvvix --underlying "$UNDERLYING" --source dvol --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build qvvix --underlying "$UNDERLYING" --source dvol --ts 2026-03-08T23:00:00Z
  uv run uforia-admin build razor --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-surface --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-carry --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-skew --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-dislocations --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-positioning --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-cone --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build term-structure-momentum --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build gamma-exposure --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build funding-context --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build straddle-breakeven --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build surface-factor-rv --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build ml-carry-toxicity --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build expiry-flow-map --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build adaptive-hedging --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build sessionality-clocks --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build funding-basis-skew --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build options-signals --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build vol-regime-transitions --underlying "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-signals --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-composites --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build perps-transitions --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite-components --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin build composite-transitions --asset "$UNDERLYING" --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
done
uv run uforia-admin build options-rv --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z
uv run uforia-admin build btc-eth-dispersion --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z

Or run the full research stack in one command:

uv run uforia-admin build alpha-canvas --start 2026-03-01T00:00:00Z --end 2026-03-09T00:00:00Z --underlyings BTC,ETH

Build the TCN-Boost microstructure stack from data already loaded into Postgres:

uv run uforia-admin microstructure build-features --asset BTC --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
uv run uforia-admin microstructure build-labels --asset BTC --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z --horizons 30s,1m,2m,5m
uv run uforia-admin microstructure build-regime --asset BTC --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
uv run uforia-admin microstructure train --asset BTC --horizon 1m
uv run uforia-admin microstructure evaluate --asset BTC --horizon 1m
uv run uforia-admin microstructure generate-signals --asset BTC --horizon 1m

To train both assets and all default horizons on a populated database:

for ASSET in BTC ETH; do
  uv run uforia-admin microstructure build-features --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  uv run uforia-admin microstructure build-labels --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z --horizons 30s,1m,2m,5m
  uv run uforia-admin microstructure build-regime --asset "$ASSET" --start 2026-01-01T00:00:00Z --end 2026-03-09T00:00:00Z
  for HORIZON in 1m 2m 5m 30s; do
    uv run uforia-admin microstructure train --asset "$ASSET" --horizon "$HORIZON"
    uv run uforia-admin microstructure evaluate --asset "$ASSET" --horizon "$HORIZON"
    uv run uforia-admin microstructure generate-signals --asset "$ASSET" --horizon "$HORIZON"
  done
done

Run the live feed engine and live inference:

./ops/run-microstructure-live.sh
./ops/run-microstructure-inference.sh