---
title: "Oracle Edge Scanner"
description: "Multi-signal forecasting and edge detection across prediction markets."
icon: "crystal-ball"
---

<Warning>**Ultra Feature.** Requires an Ultra subscription. [Get started at api.mathematicalcompany.com](https://api.mathematicalcompany.com)</Warning>

Use the Oracle module to forecast market outcomes with a 6-signal decomposition, scan for mispriced markets, and inject edge signals into a live trading pipeline.

## Full Code

```python
"""Oracle: forecast markets and scan for edge."""

import horizon as hz

# ── Forecast a single market ──
forecast = hz.forecast_market(
    "0xcondition...",
    market_title="Will X happen?",
    market_price=0.65,
)

print("Market Forecast")
print(f"  Ensemble prob:    {forecast.ensemble_prob:.4f}")
print(f"  Market price:     {forecast.market_price:.4f}")
print(f"  Edge:             {forecast.edge_bps:.0f} bps")
print(f"  Confidence:       [{forecast.confidence_low:.2f}, {forecast.confidence_high:.2f}]")

print(f"\n  Signal Decomposition:")
for s in forecast.signals:
    print(f"    {s.name:20s} value={s.normalized_value:.4f} weight={s.weight:.2f}")

# ── Scan for edges across markets ──
edges = hz.scan_edges(
    min_edge_bps=300,   # only show edges > 300 bps (3 cents)
    max_markets=30,
)

print(f"\nEdge Scanner ({len(edges)} opportunities):")
for opp in edges:
    print(f"  {opp.market_title}: edge={opp.edge_bps:.0f}bps {opp.direction} conf={opp.confidence:.2f}")

# ── Full oracle report ──
report = hz.oracle_report(max_markets=20)

print(f"\nOracle Report:")
print(f"  Coverage:           {report.coverage} markets")
print(f"  Top edges:          {len(report.top_edges)}")
print(f"  Avg confidence:     {report.avg_confidence:.2f}")
print(f"  Calibration:        {report.model_calibration:.4f}")
```

## Pipeline Mode

Inject oracle edge forecasts into a live quoting strategy:

```python
"""Oracle pipeline: inject edge for downstream quoting."""

import horizon as hz
from horizon.context import FeedData

oracle_pipe = hz.oracle(
    config=hz.OracleConfig(
        edge_threshold_bps=200,
    ),
    forecast_interval_cycles=10,
)


def quoter(ctx: hz.Context, fair: float) -> list[hz.Quote]:
    """Quote only when oracle detects edge."""
    oracle_edge = ctx.params.get("oracle_edge", 0.0)
    oracle_conf = ctx.params.get("oracle_confidence", 0.0)

    if abs(oracle_edge) < 0.02 or oracle_conf < 0.5:
        return []   # no edge or low confidence

    # Tighter spread when oracle is confident
    spread = 0.02 + (1.0 - oracle_conf) * 0.04
    size = hz.kelly_size(fair, fair - oracle_edge, 5000.0, 0.25, 30.0)

    return hz.quotes(fair, spread, size=max(1.0, size))


hz.run(
    name="oracle_trader",
    markets=["election-winner"],
    feeds={
        "polymarket": hz.PolymarketBook("election-winner"),
    },
    pipeline=[oracle_pipe, quoter],
    risk=hz.Risk(max_position=100, max_drawdown_pct=5),
    interval=2.0,
    mode="paper",
)
```

## How It Works

1. **`forecast_market()`** decomposes the forecast into 6 signals:
  - Smart money flow, microstructure, momentum, volume profile, holder concentration, and temporal patterns
  - Each signal is weighted per `OracleConfig.signal_weights`
  - The ensemble probability is the weighted sum, clamped to [0.01, 0.99]
2. **`scan_edges()`** applies `forecast_market()` across multiple markets and filters by minimum edge
3. **`oracle()`** pipeline function re-forecasts every N cycles and injects `ctx.params["oracle_forecast"]` and `ctx.params["oracle_edge_bps"]`
4. **`oracle_report()`** forecasts multiple markets, computes model calibration via log-loss, and surfaces top edge opportunities

## Run It

```bash
python examples/oracle_edge_scanner.py
```

See [Oracle](/oracle) for the full reference.
