# Outrun: Crypto State Machine

## System Overview
Outrun is a high-resolution crypto data engine designed for AI agents. It maintains a 10-day rolling history of spot prices and volume for 30 assets, aggregated from 6 major exchanges (Binance, Kraken, Coinbase, Bybit, Poloniex, OKX).

- **Resolution:** 20 seconds
- **Retention:** 10 days
- **Assets:** BTC, ETH, XRP, BNB, SOL, TRX, DOGE, ADA, BCH, LINK, XMR, LTC, AVAX, SUI, HBAR, ZEC, SHIB, TON, DOT, UNI, MNT, TAO, AAVE, XLM, HYPE, XAUT, TRUMP, ENA, ASTER, PEPE.

## API Reference
Base URL: `<host>/j`
Auth: `x-api-key` header required.

### 0. API Access & Pricing

**Option A: Free Endpoint**
Check connectivity and latest price without a key.
- **Endpoint:** `GET /j/price`
- **Limit:** 10 requests / minute / IP.

**Option B: Paid Tier (Pay-to-Mint)**
For heavy workloads and computed endpoints (`volatility`, `wick`, `weather`, etc.).
- **Cost:** 10 sats per query.
- **Validity:** Forever (until balance runs out).
- **Top-up:** Not yet supported (buy a new key).

**Purchase Flow:**
1.  **Order:** `POST /key/buy` with body `{ "amount": 1000 }` (Min 100 sats).
2.  **Pay:** Pay the returned Lightning Invoice (bolt11).
3.  **Claim:** `GET /key/claim/:orderId` -> Returns `{ "apiKey": "..." }`.

---

### 1. Threshold Duration
Checks if price maintained a condition for a duration.
`GET /j/threshold`

**Parameters:**
- `symbol` (string): e.g., "BTC"
- `price` (number): Target threshold.
- `window` (integer): Window size in **minutes** (e.g., `60`).
- `condition` (string): "gt" (Greater Than) or "lt" (Less Than).
- `time` (string, optional): ISO timestamp for historical checks.

**Response:**
```json
{ "result": true, "countChecked": 180 }
```

### 2. Volatility
Calculates standard deviation of price for a rolling window.
`GET /j/volatility`

**Parameters:**
- `symbol` (string): e.g., "ETH"
- `window` (integer): Window size in **minutes** (e.g., `60`).
- `time` (string, optional): ISO timestamp.

**Response:**
```json
{ "volatility": 120.5, "meanPrice": 3400.00, "sampleSize": 180 }
```

### 3. Wick Detection
Detects volatility range (High - Low) percentage.
`GET /j/wick`

**Parameters:**
- `symbol` (string): e.g., "SOL"
- `percent` (number): % diff to check (e.g., 5).
- `window` (integer): Window size in **minutes** (e.g., `1440`).
- `time` (string, optional): ISO timestamp.

**Response:**
```json
{ "result": true, "maxWickPercent": 7.5, "high": 150.00, "low": 138.75 }
```

### 4. Correlation
Calculates Pearson Correlation Coefficient between two assets.
`GET /j/correlation`

**Parameters:**
- `symbolA` (string): e.g., "BTC"
- `symbolB` (string): e.g., "ETH"
- `window` (integer): Window size in **minutes** (e.g., `1440`).

**Response:**
```json
{ 
  "symbolA": "BTC", 
  "symbolB": "ETH", 
  "correlation": 0.95, 
  "interpretation": "Strong Positive", 
  "window": "1440m", 
  "sampleSize": 4320 
}
```

### 5. Consensus Price
Returns sanitized multi-source average price.
`GET /j/price`

**Parameters:**
- `symbol` (string): e.g., "BTC"
- `time` (string, optional): ISO timestamp.

**Response:**
```json
{ "symbol": "BTC", "price": 98500.50, "timestamp": "...", "sources": 6 }
```

### 6. Volume Anomaly
Checks for unusual volume activity (1h vs 10-day baseline).
`GET /j/volume`

**Parameters:**
- `symbol` (string): e.g., "BTC"

**Response:**
```json
{ 
  "symbol": "BTC", 
  "volume24h": 1450000000.50,
  "volume1h": 25000000.00,
  "anomalyScore": 3.2, 
  "status": "Extreme" 
}
```
*Note: Status can be "Normal", "High" (>1.5x), or "Extreme" (>3.0x).*

### 7. Weather / Hashrate Risk
Monitors weather in 30 global mining hubs.
`GET /j/weather`

**Parameters:**
- `code` (string, optional): Location Code (e.g., "TX_RDL").

**Response (Global):**
```json
{ "globalRisk": "LOW", "highRiskLocations": [...] }
```

### 8. Real-Time Websocket
Stream the full market state (prices, volume, anomalies) every 20 seconds.
**URL:** `ws://<host>/j/stream`
**Cost:** 1 sat per minute (deducted from API Key balance).

**Protocol:**
1. Connect to WebSocket.
2. Send Auth: `{ "action": "auth", "key": "YOUR_API_KEY" }`
3. Receive Data:
```json
{
  "type": "update",
  "timestamp": "...",
  "data": [
    {
      "symbol": "BTC",
      "price": { "current": 98500.00, "volatility_1h": 150.00 },
      "volume": { 
         "24h": 500000000, 
         "1h": 25000000, 
         "anomaly_score": 1.2, 
         "anomaly_rating": "Normal" 
      },
      "meta": { "sources": 6, "resolution": "20s" },
      "status": "ok"
    },
    ...
  ]
}
```