# AlgoTick — Institutional Crypto Market Intelligence API
# https://algotick.dev
# Last updated: 2026-03-14

## Overview
AlgoTick provides real-time crypto market microstructure data and derived mathematical signals (Gamma Exposure, Orderbook Imbalance, Regime Detection).
This API is explicitly designed for quantitative trading algorithms, Delta-Neutral Agents, and AI tool-calling.

## Base URL
https://api.algotick.dev

## Authentication
Pass the API key via the HTTP header: `X-API-Key: <YOUR_KEY>`.
Query parameter `?api_key=YOUR_KEY` is also supported for backwards compatibility.

## Core Endpoints & AI Use Cases

### 1. Market Snapshot
`GET /v1/snapshot`
* **Returns:** 39 real-time metrics including prices, funding rates, and gas fees.
* **AI Use Case:** Call this first to get the current state of the global market before making any trading decisions.

### 2. Market Regime Classification
`GET /v1/signals/regime`
* **Returns:** HMM-based regime classification (trending, mean-reverting, high-volatility) with confidence scores and risk warnings.
* **AI Use Case:** Use this to determine which trading strategy to activate. Do not run mean-reversion bots during trending regimes.

### 3. Execution Safety Score
`GET /v1/signals/safety`
* **Returns:** Cross-signal coherence score (0-100), safety level, and execution recommendation.
* **AI Use Case:** The ultimate Go/No-Go check. ALWAYS call this endpoint before executing a live trade to ensure there is no adverse price movement underway.

### 4. Global Order Book Imbalance
`GET /v1/signals/imbalance?coin=BTC`
* **Returns:** Deep bid/ask imbalance scores within 1% of the mid-price.
* **AI Use Case:** Predict short-term microstructure momentum. Values > 0.60 indicate strong bid support (bullish). Values < 0.40 indicate ask suppression (bearish).

### 5. Cross-Venue Arbitrage & Spreads
`GET /v1/signals/arbitrage`
* **Returns:** Spot-perp basis spreads (in bps) and annualized delta-neutral yields.
* **AI Use Case:** Find the highest-yield carry trades between DEX spot and Hyperliquid Perps.

### 6. Squeeze Detection
`GET /v1/signals/squeeze`
* **Returns:** Squeeze probability (%), Open Interest velocity, direction, and liquidation levels.
* **AI Use Case:** Risk management. If squeeze probability is high, advise closing highly leveraged positions to avoid liquidation.

### 7. Dealer Gamma Exposure (GEX) & Volatility
`GET /v1/signals/gamma-exposure`
* **Returns:** Aggregate dealer gamma exposure, IV index, put/call ratio from Deribit options.
* **AI Use Case:** Forecast volatility regimes. Highly positive GEX means dampened volatility; negative GEX means high squeeze risk.

`GET /v1/signals/volatility?coin=BTC`
* **Returns:** Realized volatility and ATR at 5m/1h/4h/24h windows with regime classification.

### 8. Liquidation Alerts
`GET /v1/signals/liquidations`
* **Returns:** Active liquidation wick alerts and threshold levels across all coins.
* **AI Use Case:** Monitor for cascading liquidation events that cause rapid price moves.

### 9. Smart Money Flow
`GET /v1/signals/smart-money`
* **Returns:** Aggregate smart-money signal, net flow (24h), wallet PnL, and hottest coins.
* **AI Use Case:** Follow institutional and whale positioning to align with informed capital.

### 10. Oracle Price Dislocation
`GET /v1/signals/oracle-dislocation`
* **Returns:** Basis-point spread between Hyperliquid mark and Pyth oracle prices.
* **AI Use Case:** Detect oracle lag for MEV and arbitrage opportunities. Alert levels: watch/warning/critical.

### 11. Stablecoin Treasury Flows
`GET /v1/signals/stablecoin-flows`
* **Returns:** 24h rolling USDC/USDT mint and burn activity on Ethereum mainnet.
* **AI Use Case:** Macro liquidity forecasting. Large mint surges precede rallies; large burns signal risk-off.

### 12. Token Unlock Schedules
`GET /v1/signals/upcoming-unlocks`
* **Returns:** Token supply unlock events, locked percentage, and dilution risk.
* **AI Use Case:** Filter out tokens with impending supply inflation before taking long positions.

### 13. Mempool Congestion
`GET /v1/signals/mempool-congestion`
* **Returns:** Real-time Ethereum mempool congestion score (0-100) with congestion level.
* **AI Use Case:** Gas-optimal execution timing. Delay non-urgent transactions during high congestion.

### 14. Orderbook Liquidity Voids
`GET /v1/signals/liquidity-voids?coin=BTC`
* **Returns:** Thin liquidity bands in the L2 orderbook that could cause slippage cascades.
* **AI Use Case:** Pre-trade slippage assessment. Avoid large market orders near detected voids.

## Supporting Endpoints

### Whale Flow
`GET /v1/signals/whale-flow?coin=BTC`
Returns large orders (>$100K) with bid/ask breakdown.

### Composite Signal
`GET /v1/signals/composite`
Returns multi-factor directional score (-1 to +1) per coin combining imbalance, funding, basis, and gas.

### Correlation Matrix
`GET /v1/signals/correlation`
Returns rolling cross-asset correlation matrix (BTC/ETH/SOL/HYPE).

### Spreads & Funding
`GET /v1/signals/spreads?coin=BTC`
Returns cross-venue spread (bps), funding rate, funding Z-score, and regime.

### Gas Tracker
`GET /v1/signals/priority-gas`
Returns Ethereum gas prices: current basefee, p25/p50/p90, congestion level.

### Order Book Depth
`GET /v1/signals/depth?coin=BTC`
Returns depth bands with bid/ask depth at percentage levels from mid price.

## Market Data

### Metric Catalog
`GET /v1/catalog`
Full list of all available real-time metrics with descriptions, units, and update frequencies.

### Historical Data
`GET /v1/history?metric_id=eth_basefee_live&minutes=60`
Time-series data for any metric.

### OHLCV Candles
`GET /v1/history/ohlcv?metric_id=hlp_mark_price&interval=1h&minutes=240`
Standard OHLCV candle data at 1m/5m/15m/1h/4h intervals.

## Real-Time Streaming (WebSocket)

`wss://api.algotick.dev/v1/stream?api_key=YOUR_KEY`

Subscribe to live data:
```json
{{"action": "subscribe", "metrics": ["eth_basefee_live", "hlp_mark_price"]}}
```

Use `"metrics": ["*"]` to subscribe to all metrics.

## Smart Alerts (Webhooks)

`POST /v2/alerts/register`
Register compound conditions across multiple metrics. The server evaluates every second and POSTs to your webhook URL when triggered.

`GET /v2/alerts`
List active alerts with trigger stats and status.

## Example Python Usage

```python
import httpx

client = httpx.Client(
    base_url="https://api.algotick.dev",
    headers={{"X-API-Key": "YOUR_API_KEY"}}
)

# Always check safety before trading
safety = client.get("/v1/signals/safety").json()
if safety["safety_level"] == "HIGH":
    # Get current regime to select strategy
    regime = client.get("/v1/signals/regime").json()
    # Get imbalance for entry signal
    imb = client.get("/v1/signals/imbalance", params={{"coin": "BTC"}}).json()
    print(f"Regime: {{regime['regimes'][0]['regime_label']}}, Imbalance: {{imb['imbalance']}}")
```

## Data Schema
All data points use a dual-timestamped JSON schema:
- `time_chain`: when the event occurred on the blockchain/exchange
- `time_local`: when the Frankfurt server ingested it

## Rate Limits
600 requests per minute per API key. WebSocket: unlimited streaming once connected.
Response headers: `X-RateLimit-Limit`, `X-RateLimit-Remaining`, `X-RateLimit-Reset`.

## AI Agent Integration (MCP)
AlgoTick natively supports the Model Context Protocol. LLMs can directly consume structured JSON via tool-calling.
* Tool Manifest: `https://algotick.dev/.well-known/mcp.json`

## Machine-Readable Schema
* OpenAPI 3.1: `https://api.algotick.dev/openapi.json`