API Documentation

Integrate real-time contagion detection into your trading systems.

Authentication

Include your API key in the Authorization header:

Authorization: Bearer YOUR_API_KEY

Rate Limits

Retail

1 req/min

60s polling

Pro

12 req/min

5s polling

Institutional

60 req/min

1s polling

Endpoints

GET/api/v1/contagion/status

Current contagion score, regime, and primary driver

View response

{
  "score": 49.3,
  "regime": "PRE_SHOCK",
  "timestamp": "2025-11-25T08:30:00Z",
  "primaryDriver": {
    "venue": "BINANCE",
    "instrument": "BTC/USDT",
    "metric": "liq_print_usd",
    "value": 0.49,
    "contribution": 0.49
  },
  "vectors": []
}

GET/api/v1/contagion/explain

Params: window=10m

AI-generated narrative explaining current market stress

View response

{
  "window": "10m",
  "summary": "Elevated contagion risk detected...",
  "top_drivers": [
    { "feature": "return_1s", "venue": "binance", "instrument": "ETH/USDT", "contribution": 4.43 }
  ],
  "timestamp": "2025-11-25T08:30:00Z"
}

GET/api/v1/contagion/history

Params: start=2025-11-24T00:00:00Z&end=2025-11-25T00:00:00Z

Historical contagion scores for charting

View response

{
  "start": "2025-11-24T00:00:00Z",
  "end": "2025-11-25T00:00:00Z",
  "points": [
    { "ts": "2025-11-24T00:00:00Z", "score": 42, "regime": "PRE_SHOCK" },
    ...
  ]
}

Code Examples

import requests

API_KEY = "your_api_key"
BASE_URL = "https://orochi.fly.dev"

headers = {"Authorization": f"Bearer {API_KEY}"}

# Get current status
resp = requests.get(f"{BASE_URL}/api/v1/contagion/status", headers=headers)
data = resp.json()

print(f"Score: {data['score']}")
print(f"Regime: {data['regime']}")

if data['score'] > 70:
    print("High contagion - consider reducing exposure")

Regime Classification

CALM(0-40)

Normal market conditions. Low stress propagation risk.

PRE_SHOCK(40-60)

Elevated stress. Consider tightening stops.

CASCADE_IMMINENT(60-80)

High stress. Reduce leverage and exposure.

EVENT(80+)

Active cascade. Avoid new positions.

Ready to integrate?

Get your API key and start detecting contagion in minutes.

Get API Access