[GUIDE]

API User Guide

The complete reference: authentication, tiers, rate limits, every endpoint, webhooks, error codes and code examples.

1. Getting Started

1.1 Base URL

https://frontend-theta-smoky-58.vercel.app/api/v1/...

All endpoints return JSON. Everything is read from HyperBasis infrastructure (ClickHouse/Postgres) — your requests never touch third-party quote APIs directly (read/write separation).

1.2 Authentication — wallet-bound API key

Every API key is bound to your wallet. Get yours on the Get API Key page (connect MetaMask / Rabby / Coinbase / Phantom, sign one message, done).

curl -H "X-API-Key: hb_live_..." https://frontend-theta-smoky-58.vercel.app/api/v1/deviation

1.3 Your first call

# latest deviation for every asset
curl -H "X-API-Key: hb_live_..." \
  https://frontend-theta-smoky-58.vercel.app/api/v1/deviation

# response (excerpt)
[
  {
    "name": "AAPL",
    "hl_price": 302.10,
    "tradfi_price": 305.48,
    "deviation_pct": -1.11,
    "deviation_percentile_90d": 4.2,
    "timestamp": "2026-08-18 11:19:03",
    "is_stale": false,
    "last_quote_at": "2026-08-18T12:18:40Z"
  }, ...
]

2. Tiers

Feature	FREE	PRO	ENTERPRISE
History window	90 days	2 years	2 years
Realtime deviation	5-minute delayed	90-second cycle	sub-second (WebSocket)
Daily API calls	100/day	10,000/day	unlimited
Per-minute calls	10/min	1,000/min	custom
Webhooks	—	✓	✓ + SLA
Credits (pay-per-use)	✓ buy with USDC	✓	✓

Upgrade: 29 USDC → PRO 30 days. Every response carries your tier + limits (see §5).

3. Every Endpoint

3.1 Market Data

	Endpoint	Description
GET	`/api/v1/deviation`	Latest deviation for all assets (HL vs TradFi) with `is_stale`/`last_quote_at`.
POST	`/api/v1/deviation/batch`	Up to 50 assets in ONE call. Body: `{"assets":["TSLA","NVDA","GOLD"]}`. Counts as 1 call.
GET	`/api/v1/yield`	Arbitrage yield per asset (funding + deviation − friction), 90d percentile.
GET	`/api/v1/leaderboard?view=actionable\|all\|micro\|stale\|warnings`	Signal leaderboard with hard Actionable filters (fresh data, liquidity, funding alignment).
GET	`/api/v1/microstructure?asset=TSLA`	Orderbook toxicity & microstructure snapshot for algos.
GET	`/api/v1/risk_flags/{asset}`	Market-halted / oracle-stale / corporate-action flags.
GET	`/api/v1/deviation/history?asset=TSLA&days=7&interval=1h\|1m`	Historical deviation series. 1m costs credits (~5/500 rows); window capped by tier.
GET	`/api/v1/assets`	Full asset universe metadata (98 instruments).
GET	`/api/v1/borrow-costs`	Borrow cost per asset (short-side friction).
GET	`/api/v1/macro-events`	Macro calendar events.

3.2 Funding, OI & Capacity

	Endpoint	Description
GET	`/api/v1/oi-funding/history?asset=TSLA&days=7`	Open interest + funding history.
GET	`/api/v1/capacity/history?asset=TSLA&days=7`	Capacity/depth history.
GET	`/api/v1/export/deviation.csv?asset=TSLA&days=30`	CSV export of deviation history.

3.3 Whale & Liquidation Intelligence

	Endpoint	Description
GET	`/api/v1/whale/positions`	Positions of the tracked whale pool (282 addresses).
GET	`/api/v1/whale/addresses`	Tracked whale addresses.
GET	`/api/v1/whale/flows`	Whale flow events.
GET	`/api/v1/liquidation/map?asset=TSLA`	Liquidation price map per asset.
GET	`/api/v1/liquidation/events`	Liquidation events (limited by HL API data availability).
GET	`/api/v1/liquidation/vulnerability?asset=TSLA`	Liq vulnerability score 0-100.
GET	`/api/v1/gap-risk?asset=TSLA&test_mode=true`	Weekend/close gap risk index.

3.4 Signals & Analytics

	Endpoint	Description
GET	`/api/v1/alerts/extreme?threshold_high=90&threshold_low=10`	Extreme 90d-percentile alerts (drives webhooks).
GET	`/api/v1/backtest?asset=TSLA&days=30`	Mean-reversion backtest with equity curve.
GET	`/api/v1/analytics/correlation?days=30`	Cross-asset deviation correlation matrix (95×95, ~50s).
GET	`/api/v1/analytics/regime`	Market regime detection (~60s).

3.5 Webhooks (institutional)

	Endpoint	Description
POST	`/api/v1/webhooks`	Register. Body: `{"url":"https://your-callback","events":["extreme"]}`. Returns HMAC secret (shown once).
GET	`/api/v1/webhooks`	List your webhooks.
DELETE	`/api/v1/webhooks/{id}`	Delete.

Delivery format (when /alerts/extreme finds signals):

POST https://your-callback
X-HyperBasis-Signature: sha256=<HMAC-SHA256(secret, raw_body)>
X-HyperBasis-Event: extreme

{"generated_at":"2026-08-18T11:36:56Z","alerts":[{"asset":"SKHX","deviation_pct":-17.48,"percentile_90d":0,"flag":"EXTREME_LOW"},...]}

Verify the signature before trusting the payload (max 1 delivery per webhook per 5 minutes).

3.6 WebSocket (realtime stream)

wss://frontend-theta-smoky-58.vercel.app/ws/v1/stream?api_key=hb_live_...&assets=TSLA
# costs 10 credits/hour - requires credits balance

3.7 Billing & Credits

GET	`/api/v1/credits/balance`	Your credit balance.
GET	`/api/v1/credits/usage`	Credit consumption per day/endpoint.
GET	`/api/v1/billing/products`	Available products.
GET	`/api/v1/billing/usage`	API call usage metering.
POST	`/api/v1/billing/checkout`	Stripe checkout session.

Buy credits on-chain with USDC: API Credit page (10 USDC = 1,000 credits; 50 = 5,000; 100 = 10,000).

4. Data Quality Flags

Every pricing response includes:

is_stale — true when the TradFi quote is older than 90 seconds (the deviation cycle). Never trade a stale deviation.
last_quote_at — ISO-8601 UTC timestamp of when the quote was observed (market time, not fetch time).

5. Response Meta & Rate-Limit Headers

HTTP/1.1 200 OK
X-RateLimit-Limit: 10000
X-RateLimit-Remaining: 9998
X-RateLimit-Reset: 1787097600
X-RateLimit-Minute-Limit: 1000
X-RateLimit-Minute-Remaining: 997

{"asset":"TSLA", ..., "_meta":{"tier":"pro","generated_at":"2026-08-18T12:20:11Z"}}

6. Error Codes

Code	Meaning
401	Missing or invalid API key / wallet token.
402	Insufficient credits for a paid endpoint (minute history, WebSocket).
403	Key inactive or CORS origin rejected.
422	Missing/invalid parameters (e.g. `asset` required on liquidation endpoints).
429	Rate limit exceeded: `"Daily quota exceeded (free: 100/day)"` — upgrade to PRO.
500	Server error — retry with backoff; report with the Request ID.

7. Full Examples

# 1) batch deviation (1 call)
curl -X POST -H "X-API-Key: hb_live_..." -H "Content-Type: application/json" \
  -d '{"assets":["TSLA","NVDA","GOLD"]}' \
  https://frontend-theta-smoky-58.vercel.app/api/v1/deviation/batch

# 2) actionable signals
curl -H "X-API-Key: hb_live_..." \
  "https://frontend-theta-smoky-58.vercel.app/api/v1/leaderboard?view=actionable&sort_by=yield"

# 3) register a webhook (save the secret!)
curl -X POST -H "X-API-Key: hb_live_..." -H "Content-Type: application/json" \
  -d '{"url":"https://your-server/wh","events":["extreme"]}' \
  https://frontend-theta-smoky-58.vercel.app/api/v1/webhooks

# 4) verify a webhook delivery (Python)
import hmac, hashlib
expected = "sha256=" + hmac.new(secret.encode(), body, hashlib.sha256).hexdigest()
assert request.headers["X-HyperBasis-Signature"] == expected

Honest limitations: zero-volume HL assets (ALUMINIUM, VIX, DXY…) have no funding history; some assets have no TradFi quote (is_stale stays true); same-day US equity minute bars lag one trading day on the free data plan; liquidation events are limited by HL API availability.