gdex-hl-anomaly git:20260923.1182a9cA

Immutable. This exact content never changes and is served at /api/v1/blob/9a07489256091cc7.

---
name: gdex-hl-anomaly
description: Scored, time-stamped anomaly events for HyperLiquid perps (oracle divergence, funding extremity, liquidity shock) against per-market learned baselines, with coverage records
---

# GDEX: HyperLiquid Anomaly Events

Detects unusual behaviour on the HyperLiquid perpetual markets that GDEX trades, and emits it as
**events** (NDJSON, one record per event), not alerts. Each event says what was unusual, when it
happened, how unusual it was against that market's own recent history, and where to re-derive it.

Standard library only — no API key, no Gemach infrastructure. Reads the public HyperLiquid
`info` endpoint directly.

## When to Use

- Building a risk feed that needs market anomalies with a timestamp and a score
- Screening HyperLiquid markets for manipulation, oracle stress or liquidity shocks
- Backfilling anomaly history for a window (1h bars reach ~7 months back, 4h ~2 years)

## Run

```bash
python3 scripts/hl_anomaly.py                                   # last 24h, every active core market
python3 scripts/hl_anomaly.py --coins BTC ETH SOL --hours 72
python3 scripts/hl_anomaly.py --start 2025-03-20 --end 2025-03-27 --coins JELLY --interval 1h
```

Output is NDJSON: zero or more `signal_type: "anomaly"` records, then exactly **one**
`signal_type: "anomaly_coverage"` record.

## Categories

| `anomaly_category` | Fires when | Source |
|---|---|---|
| `oracle_divergence` | hourly mark-vs-oracle premium is far from the market's baseline | `fundingHistory` |
| `funding_extremity` | 8h mean funding is far from baseline **and** premium is outside HyperLiquid's clamp band (inside it funding is pinned to the interest rate and carries no information). Always carries the premium fields. | `fundingHistory` |
| `liquidity_shock` | bar volume or bar range spikes far above baseline (spikes only) | `candleSnapshot` |

`large_outflow`, `governance_concentration` and `security_flag_change` are part of the contract
enum but are not produced by this skill (they need on-chain or token-security sources).

## Event record

| Field | Meaning |
|---|---|
| `entity_id` | `hl-<coin>`, same key as the `hl_markets` feed |
| `detected_at` | when the anomaly **happened** (funding hour, or bar close) — not when the job ran |
| `z`, `z_threshold` | robust z against the learned baseline, and the threshold it crossed |
| `score` | 0 at the threshold, rising monotonically toward 1. A ranking, not a probability |
| `model_version` | changes whenever thresholds or features change |
| `evidence_ref` | public endpoint + coin + time + sha256 of the exact baseline used |
| feature fields | premium/funding and their baselines, or volume/range and their baselines |

## Coverage record — read this before trusting an empty result

Every run states `detector_window_start`, `detector_window_end`, `markets_scored` and `markets_not_scored`
(too little history, delisted, or no data). **No event for a scored market means nothing
crossed a threshold in that window; it does not mean the market was normal.** Markets in
`markets_not_scored` were not evaluated at all.

## Method and evidence

- `APPROACH.md` — the model, why each choice was made, and its known limits
- `backtest/RESULTS.md` — hit rate and false-alarm rate on three real events
- `backtest/calibrate.py`, `backtest/backtest.py` — reproduce both
- `sample/anomaly_sample.ndjson` — records for contract tests