[Exchange/Atlas] Live market liquidity heatmap (mechanism x bond-tier x age) done

← Live Dashboard Artifact Framework
Heatmap of trades-per-day across mechanism x bond-tier x age buckets; zero-volume cells offer Seed-liquidity CTA.

Completion Notes

Auto-completed by supervisor after successful deploy to main

Git Commits (2)

Squash merge: orchestra/task/a4c450f7-biomni-analysis-parity-port-15-use-cases (87 commits) (#717)2026-04-27
[Exchange/Atlas] Live market liquidity heatmap — api.py, dashboard_engine.py [task:dfdd7c68-2ccc-4ea6-87d7-97f0412b0c5d] (#690)2026-04-27
Spec File

Goal

SciDEX runs prediction markets with bounties from $5K to $960K. Operators
need to see which mechanism bands are illiquid, which bonded tiers are
under-served, and which markets have aged without a trade — so liquidity
calibration runs (calibrate_market_liquidity_bands.py, seed_zero_vol_30.py) can be triggered surgically rather than blindly.
Build a live dashboard that renders this as a heatmap, refreshes every
10 minutes, and snapshots on-demand for governance reviews.

Acceptance Criteria

☐ Dashboard slug market-liquidity-heatmap via register_dashboard.
☐ view_spec_json with three data_sources (safe-query validated):
1. liquidity_grid — markets joined to price_history and
bonds, grouped by mechanism_band × bond_tier × age_bucket
(0-7d, 7-30d, 30-90d, >90d).
2. zero_volume_markets — markets WHERE total_volume_usd=0 AND
created_at < NOW() - INTERVAL '30 days'
.
3. recent_trades — last 50 trades for the trades-per-day overlay.
☐ render.template = the existing metric_grid.html won't suffice;
add liquidity_heatmap.html (cell color by inverse trades/day).
☐ Cells link to /markets?mechanism=<x>&tier=<y> so an operator can
drill down. Zero-volume cells show a "Seed liquidity" CTA that POSTs
to the existing seed_liquidity_review_* workflow if the operator
has the liquidity_admin role.
☐ cache_ttl_seconds=600. Snapshot endpoint emits a child artifact
whose materialized_data is the full grid for governance audit.
☐ Pytest covers grid bucketing, zero-volume detection, and the
snapshot child artifact's parent linkage.
☐ Lives at /dashboard/market-liquidity-heatmap; appears on
/dashboards index.

Approach

  • Read exchange.py and calibrate_market_liquidity_bands.py to learn
  • mechanism_band/bond_tier conventions and the age-bucket logic already
    in use.
  • Reuse the existing seed_liquidity_review task-spawn flow for the
  • "Seed liquidity" CTA — call the existing endpoint, don't reinvent.
  • Heatmap cell rendering: small inline <svg> per row to keep payload
  • ≤30KB even at 6×4×4 = 96 cells.

    Dependencies

    • e352460b-2d76 — view_spec_json DSL
    • 12b77c9e-5e9e — snapshot endpoint
    • existing liquidity calibration scripts (consumers of this dashboard)

    Work Log

    2026-04-27 — Implementation (task dfdd7c68)

    Implemented by: claude-auto slot 47

    Files changed:

    • scidex/senate/dashboard_engine.py — added markets and price_history to ALLOWED_TABLES; added liquidity_heatmap.html Jinja template (JS-pivot heatmap, SVG-free, ≤25KB rendered)
    • scripts/seed_liquidity_heatmap_dashboard.py — seeds artifact dashboard-market-liquidity-heatmap with view_spec_json containing three data sources (liquidity_grid, zero_volume_markets, recent_trades), cache_ttl_seconds=600
    • api.py — added POST /api/dashboard/{dashboard_id}/snapshot endpoint that renders fresh data and writes a child dashboard_snapshot artifact with materialized_data and parent_artifact_id
    • tests/test_market_liquidity_heatmap.py — 12 tests (11 pass, 1 skipped due to pre-existing event_bus.py syntax error in test env): grid bucketing, zero-volume detection, view_spec validation, render correctness, cache TTL, snapshot parent linkage
    Notes:
    • No bonds table exists; bond_tier maps to metadata->>'liquidity_band' (calibrated values: high, medium, watchlist, gap-high, etc.)
    • Zero-volume CTA links to /markets?mechanism=<x>&tier=<y> drill-down (no dedicated POST endpoint exists for seed_liquidity_review)
    • Age bucket 30-90d empty in current data (all markets are 0–30d or >90d); heatmap handles gracefully
    • Dashboard live at /dashboard/dashboard-market-liquidity-heatmap

    Sibling Tasks in Quest (Live Dashboard Artifact Framework) ↗