# 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](docs/terminal-client.md)
- [Overview](docs/overview.md)
- [Multi-Asset Vol Suite](docs/multi-asset-vol-suite.md)
- [Options Surface](docs/options-surface.md)
- [Options Carry / VRP](docs/options-carry-vrp.md)
- [Options Skew](docs/options-skew.md)
- [Options Dislocations](docs/options-dislocations.md)
- [Options Relative Value](docs/options-relative-value.md)
- [Options Positioning](docs/options-positioning.md)
- [Options Vol Cone](docs/options-vol-cone.md)
- [Options Term Structure Momentum](docs/options-term-structure-momentum.md)
- [Options Gamma Exposure](docs/options-gamma-exposure.md)
- [Options Funding Context](docs/options-funding-context.md)
- [Options Straddle Breakeven](docs/options-straddle-breakeven.md)
- [Options Vol Regime Transitions](docs/options-vol-regime-transitions.md)
- [Options Signals](docs/options-signals.md)
- [Crypto Derivatives Alpha Canvas](docs/crypto-derivatives-alpha-canvas.md)
- [Options Surface Factor RV](docs/options-surface-factor-rv.md)
- [Options ML Carry Toxicity](docs/options-ml-carry-toxicity.md)
- [Options Expiry Flow Map](docs/options-expiry-flow-map.md)
- [Options Adaptive Hedging](docs/options-adaptive-hedging.md)
- [Options Sessionality Clocks](docs/options-sessionality-clocks.md)
- [Options BTC-ETH Dispersion](docs/options-btc-eth-dispersion.md)
- [Options Funding-Basis Skew Interactions](docs/options-funding-basis-skew-interactions.md)
- [Perps Funding-Basis Carry](docs/perps-funding-basis-carry.md)
- [Perps Liquidation Cascade](docs/perps-liquidation-cascade.md)
- [Perps Order Flow Toxicity](docs/perps-order-flow-toxicity.md)
- [Perps OI-Price Divergence](docs/perps-oi-price-divergence.md)
- [Perps Cross-Venue Price Discovery](docs/perps-cross-venue-price-discovery.md)
- [Perps Depth Resilience](docs/perps-depth-resilience.md)
- [Perps Volatility Microstructure](docs/perps-vol-microstructure.md)
- [Perps Cumulative Delta Momentum](docs/perps-cum-delta-momentum.md)
- [Composite Index](docs/composite-index.md)
- [Composite Methodology](docs/composite-methodology.md)
- [Composite Regimes](docs/composite-regimes.md)
- [Microstructure System](docs/microstructure-system.md)
- [Execution Layer](docs/execution-layer.md)
- [BTC VVIX Pipeline](docs/btc-vvix-pipeline.md)
- [Storage and Archiver](docs/storage-and-archiver.md)
- [UI Platform](docs/ui-platform.md)
- [Local Development](docs/local-development.md)
- [Mac Mini Setup](docs/mac-mini-setup.md)
- [Timescale Migration](docs/timescale-migration.md)

Quick start:

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

Optional local Timescale bootstrap:

```bash
./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:

```bash
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

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:

```bash
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:

```bash
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:

```bash
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:

```bash
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:

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