# LiquidVision

> AI risk intelligence layer for crypto markets. Ask "Why did BTC drop 4%?"
> and get a grounded answer: $ liquidated, funding extremes, which venues hold
> the positions, next risk zone — computed from live derivatives data.
> Under the hood: real-time analytics across 9 exchanges (Binance, Bybit, OKX,
> Gate, Bitget, HTX, BingX, Aster, Kraken Futures) plus on-chain DEX data
> (Hyperliquid, GMX). Liquidations, open interest, funding rates, order-book
> heatmaps, modeled liquidation maps, top-trader positions, token unlocks.
> The website is a JavaScript SPA — do NOT scrape the HTML. Use the JSON API
> or the MCP endpoint below; they return everything the site shows.

## Data API (JSON over HTTPS, CORS enabled)

Base URL: https://liquidvision.app/api/v1
OpenAPI schema: https://liquidvision.app/api/v1/openapi.json
Interactive docs: https://liquidvision.app/api/v1/docs
Anonymous rate limit: 240 req/min per IP. Free API key (sign-up) raises it;
paid tiers (USDC on Arbitrum) raise it further. Auth: `Authorization: Bearer <key>`.

Key endpoints (all GET, no auth required):
- /coins — top-100 derivatives coins: price, 24h change, mcap, aggregate OI, 24h liquidations, funding, supply
- /funding — live funding rate + mark price per exchange/symbol
- /funding/history/{symbol}?minutes=1440 — bucketed funding history per exchange
- /oi — live open interest per exchange/symbol
- /oi/history/{symbol}?minutes=1440 — bucketed OI history
- /oiboard/{symbol} — per-venue OI ranking: share, 1h/4h/24h change, OI/volume
- /flows — net USD in/out of open positions per exchange (1h/4h/24h)
- /liquidations?minutes=60 — individual liquidation events (exchange, symbol, side, price, qty)
- /liquidations/summary?minutes=1440 — totals, per-symbol, per-exchange, time series
- /liqmap/{symbol}?exchange=all&range=1d — modeled liquidation clusters by price level
- /liqheat/{symbol}?range=1d — liquidation-cluster heatmap grid (price x time)
- /heatmap/{exchange}/{symbol} — order-book liquidity heatmap
- /klines/{symbol}?range=1d — OHLC candles
- /sparks — 24h sparkline closes for all pool coins
- /traders — top traders (OKX leads, Hyperliquid whales, GMX): PnL, live positions, recent closes
- /unlocks — upcoming token unlock events, nearest first
- /stocks — crypto equities and spot BTC/ETH ETF quotes
- /orderflow/footprint/{symbol}?minutes=240&step=15 — footprint: per candle x
  price bin, taker buy/sell USD volume + delta (core symbols; venues:
  binance, bybit, okx, bitget, gate or exchange=all)
- /orderflow/cvd/{symbol}?minutes=240 — CVD split by trade size (retail <$10K,
  mid <$100K, large <$1M, whale >$1M)
- /orderflow/spoof/{symbol}?exchange=binance&minutes=60 — order-book wall
  lifecycle: active_wall / absorbed / pulled_wall / suspected_spoof (heuristic)
- /brief/{symbol} — deterministic market brief (liquidations, funding extremes,
  OI by venue, flows, modeled risk zones, top-trader positioning) — one JSON,
  ideal input for your own LLM, free
- POST /ask {"question": "...", "symbol": "BTCUSDT"} — AI analyst answer
  grounded in the brief. Daily quota: 5 anon / 25 free key / 300 pro / 2000 bot

WebSocket (live pushes): wss://liquidvision.app/ws?topics=funding,liq

## MCP (Model Context Protocol) — for AI agents

Endpoint: https://liquidvision.app/mcp (streamable HTTP, stateless JSON)
13 tools mirroring the API: get_funding_rates, get_funding_history,
get_open_interest, get_open_interest_history, get_oi_board, get_cash_flows,
get_long_short_ratio, get_liquidations, get_liquidations_summary,
get_liquidation_map, get_liquidation_heatmap, get_orderbook_heatmap,
get_top_traders, get_token_unlocks, get_stocks, get_market_brief,
explain_market (the AI analyst).

Example (list tools):
POST https://liquidvision.app/mcp
Content-Type: application/json
Accept: application/json, text/event-stream
{"jsonrpc":"2.0","id":1,"method":"tools/list"}

## Notes for agents

- Symbols use the BASEUSDT convention (BTCUSDT, ETHUSDT, SOL...); /coins lists them all.
- Liquidation maps/heatmaps are MODELED from candles + OI deltas — estimates, not exchange feeds.
- OI/funding history depth grows daily (archive started 2026-07-18).
- Contact: https://t.me/oceanstorm666