Crypto Event & Catalyst Regime API: Unlocks, Macro Prints & Depegs

Why Continuous Regimes Miss the Token Unlock Three Days Out

Most of our regime endpoints read a state — funding is hot, breadth is thinning, RSI is stretched. They answer 'what is the market doing right now?' They are continuous, per-symbol, and computed off klines.

None of them can see the $80M token unlock that clears in three days. None of them knows FOMC prints on Wednesday. None of them flags that USDC just slipped 40bps off peg this morning. Those are discrete, dated catalysts — known in advance, sitting on a forward time axis — and a continuous regime is structurally blind to them.

The Event / Catalyst regime fills that gap. It's Regime #5 of 14 in our regime taxonomy and the only one whose primary payload is a forward calendar, not a snapshot. One call returns every dated catalyst in the next 30 days plus a market-wide event_risk_score from 0-100.

What the Event Regime Endpoint Returns

GET /api/v1/event/regime returns the forward calendar plus the composite. Each item is a dated catalyst carrying its event_type, days_until, directional bias, magnitude (0-1), and the affected symbols.

curl -H "X-API-Key: cdk_live_yourkey" \
  "https://cryptodataapi.com/api/v1/event/regime?window_days=7"

A trimmed response:

{
  "items": [
    {
      "event_type": "unlock",
      "title": "ARB token unlock (2.31% of FDV)",
      "date": "2026-06-14",
      "days_until": 3,
      "symbols": ["ARB"],
      "bias": "short",
      "magnitude": 0.46,
      "unlocked_value_usd": 81250000.0,
      "pct_of_fdv": 0.02310,
      "source": "defillama"
    },
    {
      "event_type": "macro_print",
      "title": "FOMC release",
      "date": "2026-06-17",
      "days_until": 6,
      "symbols": [],
      "bias": "risk_flag",
      "magnitude": 0.967,
      "macro_class": "FOMC",
      "source": "fred"
    }
  ],
  "count": 2,
  "window_days": 7,
  "event_risk_score": 41.8,
  "band": "elevated",
  "timestamp": "2026-06-11T08:00:00+00:00"
}

That payload tells an agent two tradeable things in one read: ARB faces a 2.31%-of-FDV supply cliff in 3 days (short bias), and FOMC lands in 6 days (a risk_flag that says de-risk, not pick a side).

The Three Catalyst Baskets, Decoded

Every catalyst belongs to one of three structured-data baskets. No news, no NLP — just dated, numeric inputs that replay cleanly. Each basket fixes its own bias rule:

• Token unlocks (event_type: unlock). Sourced from DefiLlama emissions. Vesting cliffs are supply overhang, so bias is short — unless the tranche is under 0.5% of FDV, where it flips neutral (not tradeable). magnitude is severity: a 5%-of-FDV unlock scores 1.0, with a USD fallback when FDV is unknown.
• Macro prints (event_type: macro_print). The FOMC / CPI / NFP / PCE / PPI calendar. Bias is always risk_flag pre-event — the surprise is unknown ahead of time, so proximity raises Event Risk without tilting direction. magnitude blends nearness with event-class weight.
• Stablecoin depegs (event_type: depeg). CoinGecko stable prices vs $1, dead-zoned below 25bps (noise) and saturating at 200bps. Major stables (USDT / USDC) bias short; minor / algo stables are discounted and read neutral. Carries deviation_bps.

Macro-class weights are fixed and load-bearing for the macro sub-score:

How Is the Event Risk Score Calculated?

The composite has a baseline of 0, not 50 — event risk is absence-by-default. No imminent catalysts means a genuinely quiet market, so the score should read near zero, and it does.

The formula is a weighted blend of three sub-scores, each 0-100:

event_risk_score = 0.40·unlock_subscore
                 + 0.25·macro_subscore
                 + 0.35·depeg_subscore

Crucially, the weights re-normalize over whichever feeds are live. If the depeg feed is down, the composite divides over the remaining 0.40 + 0.25 weight instead — a dead feed must never read as 'no event risk'. The partial flag and inputs_available list tell you exactly which feeds contributed.

GET /api/v1/event/regime/score returns the composite plus all three sub-scores. Bands map the score to a label:

The score field carries unlock_subscore, macro_subscore, depeg_subscore, plus events_7d and events_30d counts so you can size urgency at a glance.

The Live-Only Sector-Rotation Sidecar

The /event/regime/score payload carries one extra block that sits outside the composite by design: sector_rotation.

The sector_rotation sidecar ranks CoinGecko category leaders and laggards by 24h market-cap change. It is live-only: it lands null on backfilled days because it has no clean historical snapshot.

Keeping it out of the composite is deliberate. It means the live and replayed event_risk_score are computed by the same formula and can't silently diverge — the same discipline we apply to the meme regime's fresh-issuance feed.

How Do I Query Just the Catalysts I Care About?

GET /api/v1/event/calendar is the query surface. It looks up to 30 days out and filters by type, symbol, bias, min_magnitude, and window_days.

An AI agent typically wires two reads: the score for a gate, then the calendar for the actionable list.

import httpx

HDR = {"X-API-Key": "cdk_live_yourkey"}
BASE = "https://cryptodataapi.com/api/v1/event"

# 1. Gate on market-wide event risk
score = httpx.get(f"{BASE}/regime/score", headers=HDR).json()
if score["band"] in ("heavy", "critical"):
    print("Event risk", score["event_risk_score"],
          "unlock", score["unlock_subscore"],
          "depeg", score["depeg_subscore"])

# 2. Pull the imminent short-bias unlocks to size hedges
cal = httpx.get(
    f"{BASE}/calendar", headers=HDR,
    params={"type": "unlock", "bias": "short",
            "min_magnitude": 0.3, "window_days": 7},
).json()
for e in cal["items"]:
    print(e["symbols"], e["days_until"], "days", e["magnitude"])

Per-Symbol Overlay and Backtest Replay

For a single coin, GET /api/v1/event/regime/{symbol} (Pro+) returns the pending catalysts in the next 7 days, a net_bias, a signed net_magnitude, and nearest_event_days. It also carries hl_symbol — the exact Hyperliquid perp join key — so consumers don't have to guess at the k/1000 strip.

curl -H "X-API-Key: cdk_live_yourkey" \
  "https://cryptodataapi.com/api/v1/event/regime/ARB"

Need to force the cache forward after a feed update? POST /api/v1/event/regime/refresh (Pro+) recomputes immediately. The regime is otherwise on a 30-minute TTL behind independently-cached feeds.

The unlock, macro, and depeg baskets are all backfillable — they replay from schedule plus price history — so the composite is attached to every archived daily snapshot under event_regime. The two live-only sidecars land null on replayed days and the day carries backfilled: true. Pair the unlock track with longer cycle context from the BTC cycle indicators guide.

When to Reach for the Event / Catalyst Regime

This is the regime you read on a schedule, not a tick. Three concrete uses:

• Pre-position around supply cliffs. Poll /event/calendar?type=unlock&min_magnitude=0.3 daily. A 2%+ of-FDV unlock 3 days out is a known short-bias catalyst — hedge or stand aside before the cliff, not after.
• De-risk into macro prints. When macro_subscore spikes and the nearest macro_class is FOMC or CPI, the risk_flag bias says cut size, not pick a direction — the surprise is unknowable until it prints.
• Stablecoin tripwire. A non-null depeg item on a major stable, or a critical band driven by depeg_subscore, is your fastest systemic-risk alert — faster than waiting for price to cascade.

What it isn't: a directional alpha signal you trade in isolation. It tells you when a known catalyst lands and which way it biases — pair it with the continuous regimes in the 14-regime framework for the full picture. Event risk gates; the other regimes time the trade.