Metadata-Version: 2.4
Name: liquidvision
Version: 0.2.0
Summary: Client for LiquidVision.app, exchange-exact crypto derivatives data for bots and AI agents: open interest, funding, liquidations, measured Hyperliquid and Lighter liquidation maps, cascades, tokenized stocks on DEXs, history exports and Parquet packages, x402 pay-per-call
License: MIT
Project-URL: Homepage, https://liquidvision.app
Project-URL: Documentation, https://liquidvision.app/llms.txt
Project-URL: Source, https://github.com/lv-analytics/liquidvision-mcp
Project-URL: MCP, https://liquidvision.app/mcp/lite
Keywords: crypto,derivatives,liquidations,open interest,funding rate,hyperliquid,lighter,trading bot,ai agent,mcp,x402
Classifier: Programming Language :: Python :: 3
Classifier: License :: OSI Approved :: MIT License
Classifier: Topic :: Office/Business :: Financial
Classifier: Intended Audience :: Developers
Requires-Python: >=3.9
Description-Content-Type: text/markdown
Provides-Extra: x402
Requires-Dist: eth-account>=0.10; extra == "x402"

# liquidvision (Python)

Client for [LiquidVision.app](https://liquidvision.app): exchange-exact crypto derivatives
data for bots and AI agents. Standard library only, Python 3.9+. Pay-per-call needs one
optional extra.

```bash
pip install liquidvision            # live data, history with a key
pip install "liquidvision[x402]"    # + pay per call in USDC without an account (eth-account)
```

## Start here

```python
from liquidvision import LiquidVision

lv = LiquidVision()                       # no key: the conclusions (brief, regime, cascades, maps, carry...), 60/min per IP
# lv = LiquidVision(api_key="lv_...")     # free key: 120/min on the conclusions; Pro/Bot keys: raw rows, history, alerts

lv.brief("BTCUSDT")          # one coin, one JSON: liquidations by window, funding extremes, OI by venue, risk zones
lv.regime(240)               # who is driving the move: new_longs / short_covering / new_shorts / long_flush per coin
lv.cascades(hours=24)        # liquidation cascades as events, with what price did in the hour after
lv.funding_dispersion()      # where the same coin pays very different funding (each leg on its own cycle)
lv.funding_arbitrage()       # what the carry pair actually earned over 7 and 30 days
lv.microstructure()          # spread, executable depth, cross-venue gap on Binance, Bybit, OKX, Aster
lv.tokenized_stocks()        # stocks / indices / commodities / FX as perps on DEXs, one row per underlying
```

Measured, not modeled:

```python
lv.hl_liqmap("BTCUSDT")                        # real Hyperliquid positions binned by exchange-reported liquidation price
lv.lighter_liqmap("BTCUSDT")                   # the same for Lighter
lv.hl_whales(coin="BTC", max_dist_pct=5)       # positions within 5% of liquidation
```

Modeled, and scored: `lv.liqmap("BTCUSDT")` is the CEX liquidation map (a model);
`lv.accuracy()["liqmap_validation"]` is how it did against realized liquidations.

Every dict answer carries `age_s` (seconds since the data was read from the exchange); rows
of `oi()`, `funding()`, `long_short()` carry `age_s` each and `stale=True` when a venue feed is
behind. Check it before acting on a number.

## History

```python
# free: last 24 h; Pro key: any 31-day window; Bot key: everything
rows = lv.export("liquidations", symbol="BTCUSDT", start="2026-09-01", end="2026-09-08")
lv.packages()                                   # monthly Parquet files: rows, bytes, sha256
lv.package("liquidations", "2026-08", "liq_2026-08.parquet")   # Pro: this and last month; Bot: all
```

## Pay per call without an account (x402)

An agent with a wallet can buy one file for one signed USDC payment on Arbitrum One. The key
never leaves your process: the server receives a signed `transferWithAuthorization` for exactly
the asked amount, to the server's address, valid for a short window; a public facilitator
submits it on-chain.

```python
from liquidvision import LiquidVision, X402Payer

lv = LiquidVision(payer=X402Payer(private_key="0x...", max_usd_per_call=2))
lv.package("liquidations", "2026-08", "liq_2026-08.parquet")             # $1.00
rows = lv.export("funding_hourly", start="2026-09-01", end="2026-09-30", pay=True)   # $0.10, Pro terms
print(lv.last_payment)        # {"success": true, "transaction": "0x...", "network": "arbitrum", "payer": "0x..."}
```

Without a payer the same calls raise `PaymentRequired` with `.requirements` (price, network,
address) so you can decide. Terms: `lv.x402_info()`.

## Webhook alerts (Pro and Bot keys)

```python
sub = lv.create_alert("cascade", "https://your.host/hook", symbol="BTCUSDT", min_usd=2_000_000)
secret = sub["secret"]    # shown once

# in your handler
from liquidvision import verify_signature
ok = verify_signature(secret, raw_body, request.headers["X-LiquidVision-Signature"])
```

Alert types: `cascade` (a liquidation cascade just ended), `hl_near_liq` (a Hyperliquid whale
near its liquidation price), `cluster_sweep` (price reached a large modeled cluster).

## What to know about the data

- Open interest is counted on one side on every venue; an aggregator showing Bybit, Gate or
  HTX at twice the figure is showing both sides.
- Liquidation events from Binance and Bitget are throttled by the exchanges to one order per
  contract per second, so totals are a floor.
- Funding is annualized with each contract's own settlement cycle (1h / 4h / 8h).
- Errors raise `LiquidVisionError` with `.status` and `.detail`; `PaymentRequired` for 402.

For agents: MCP at `https://liquidvision.app/mcp/lite` (13 tools) and `/mcp` (42).
Endpoint list: https://liquidvision.app/llms.txt · plans: https://liquidvision.app/pricing
