langchain-liquidvision 0.1.0__tar.gz

langchain_liquidvision-0.1.0/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: langchain-liquidvision
+Version: 0.1.0
+Summary: LangChain tools for LiquidVision.app crypto derivatives data: open interest, funding and liquidations on 13 venues, liquidation cascades, positioning regime, measured Hyperliquid liquidation maps, funding dispersion, tokenized stocks. Read-only, no key needed.
+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/tree/main/integrations/langchain
+Keywords: langchain,langgraph,tools,crypto,derivatives,liquidations,open interest,funding rate,hyperliquid,trading,ai agent
+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
+Requires-Dist: langchain-core>=0.3
+
+# langchain-liquidvision
+
+Crypto derivatives tools for LangChain and LangGraph agents, from [LiquidVision.app](https://liquidvision.app).
+Read-only, no key needed.
+
+```bash
+pip install langchain-liquidvision
+```
+
+```python
+from langchain_liquidvision import LiquidVisionToolkit
+from langgraph.prebuilt import create_react_agent
+
+tools = LiquidVisionToolkit().get_tools()
+agent = create_react_agent("anthropic:claude-sonnet-5-5", tools)
+agent.invoke({"messages": [("user", "Is the ETH move new longs or short covering? Where are the liquidation levels?")]})
+```
+
+| Tool | Answers |
+|---|---|
+| `liquidvision_derivatives_brief` | One coin: price, open interest by venue, liquidations by side, funding per exchange, nearest liquidation zones |
+| `liquidvision_positioning_regime` | New longs, short covering, new shorts or long flush: price change crossed with OI change |
+| `liquidvision_liquidation_cascades` | Liquidation cascades as events: size, multiple of the coin's normal minute, price impact, reversion |
+| `liquidvision_liquidation_map` | Measured Hyperliquid liquidation levels below and above price (exchange-reported, not modeled) |
+| `liquidvision_funding_dispersion` | Cheapest venue to be long, richest to be short, across 13 exchanges |
+| `liquidvision_tokenized_stocks` | Tokenized stocks, indices, commodities and FX perps on DEXs |
+
+Each tool returns compact JSON. Errors come back as `{"error": ...}` so the agent keeps going.
+
+**Limits.** 60 requests a minute per IP without a key. Set `LIQUIDVISION_API_KEY` (or
+`LiquidVisionToolkit(api_key=...)`) with a Pro/Bot key for 600/1,200 a minute.
+
+**More.** Raw rows, history and Parquet: the [`liquidvision`](https://pypi.org/project/liquidvision/) client.
+MCP: `https://liquidvision.app/mcp/lite`. Docs: https://liquidvision.app/llms.txt
+
+Data, not financial advice.

langchain_liquidvision-0.1.0/README.md

@@ -0,0 +1,36 @@
+# langchain-liquidvision
+
+Crypto derivatives tools for LangChain and LangGraph agents, from [LiquidVision.app](https://liquidvision.app).
+Read-only, no key needed.
+
+```bash
+pip install langchain-liquidvision
+```
+
+```python
+from langchain_liquidvision import LiquidVisionToolkit
+from langgraph.prebuilt import create_react_agent
+
+tools = LiquidVisionToolkit().get_tools()
+agent = create_react_agent("anthropic:claude-sonnet-5-5", tools)
+agent.invoke({"messages": [("user", "Is the ETH move new longs or short covering? Where are the liquidation levels?")]})
+```
+
+| Tool | Answers |
+|---|---|
+| `liquidvision_derivatives_brief` | One coin: price, open interest by venue, liquidations by side, funding per exchange, nearest liquidation zones |
+| `liquidvision_positioning_regime` | New longs, short covering, new shorts or long flush: price change crossed with OI change |
+| `liquidvision_liquidation_cascades` | Liquidation cascades as events: size, multiple of the coin's normal minute, price impact, reversion |
+| `liquidvision_liquidation_map` | Measured Hyperliquid liquidation levels below and above price (exchange-reported, not modeled) |
+| `liquidvision_funding_dispersion` | Cheapest venue to be long, richest to be short, across 13 exchanges |
+| `liquidvision_tokenized_stocks` | Tokenized stocks, indices, commodities and FX perps on DEXs |
+
+Each tool returns compact JSON. Errors come back as `{"error": ...}` so the agent keeps going.
+
+**Limits.** 60 requests a minute per IP without a key. Set `LIQUIDVISION_API_KEY` (or
+`LiquidVisionToolkit(api_key=...)`) with a Pro/Bot key for 600/1,200 a minute.
+
+**More.** Raw rows, history and Parquet: the [`liquidvision`](https://pypi.org/project/liquidvision/) client.
+MCP: `https://liquidvision.app/mcp/lite`. Docs: https://liquidvision.app/llms.txt
+
+Data, not financial advice.

langchain_liquidvision-0.1.0/langchain_liquidvision/__init__.py

@@ -0,0 +1,67 @@
+"""
+langchain-liquidvision: crypto derivatives tools for LangChain / LangGraph agents.
+
+    from langchain_liquidvision import LiquidVisionToolkit
+    tools = LiquidVisionToolkit().get_tools()     # six read-only tools, no key needed
+
+Data from LiquidVision.app: open interest, funding and liquidations on 13
+venues, liquidation cascades, positioning regime, measured Hyperliquid
+liquidation maps, funding dispersion, tokenized stocks on DEXs.
+"""
+from __future__ import annotations
+
+from typing import List, Optional
+
+from langchain_core.tools import BaseTool, BaseToolkit, StructuredTool
+from pydantic import BaseModel, ConfigDict, Field
+
+from ._api import TOOL_SPECS, LiquidVisionAPI, __version__, norm_symbol, run
+
+__all__ = ["LiquidVisionToolkit", "LiquidVisionAPI", "get_tools", "norm_symbol", "__version__"]
+
+
+class _Symbol(BaseModel):
+    symbol: str = Field("BTCUSDT", description="Coin, e.g. BTC, ETH, SOLUSDT")
+
+
+class _OptSymbol(BaseModel):
+    symbol: Optional[str] = Field(None, description="Coin, e.g. BTC or ETHUSDT; omit for the whole market")
+
+
+class _Regime(_OptSymbol):
+    minutes: int = Field(240, description="Look-back window in minutes (15-1440)")
+
+
+class _Cascades(_OptSymbol):
+    hours: int = Field(24, description="Look-back window in hours (1-72)")
+
+
+class _Tokenized(BaseModel):
+    limit: int = Field(15, description="How many of the largest markets to return")
+
+
+_SCHEMAS = {
+    "brief": _Symbol, "positioning_regime": _Regime, "liquidation_cascades": _Cascades,
+    "liquidation_map": _Symbol, "funding_dispersion": _OptSymbol, "tokenized_stocks": _Tokenized,
+}
+
+
+def get_tools(api_key: Optional[str] = None, base_url: Optional[str] = None) -> List[BaseTool]:
+    api = LiquidVisionAPI(api_key=api_key, base_url=base_url)
+    tools: List[BaseTool] = []
+    for name, method, description in TOOL_SPECS:
+        tools.append(StructuredTool.from_function(
+            func=lambda _m=method, **kw: run(api, _m, **kw),
+            name=name, description=description, args_schema=_SCHEMAS[method]))
+    return tools
+
+
+class LiquidVisionToolkit(BaseToolkit):
+    """Six read-only LiquidVision.app tools. api_key is optional (raises the rate limit)."""
+
+    model_config = ConfigDict(arbitrary_types_allowed=True)
+    api_key: Optional[str] = None
+    base_url: Optional[str] = None
+
+    def get_tools(self) -> List[BaseTool]:
+        return get_tools(self.api_key, self.base_url)

langchain_liquidvision-0.1.0/langchain_liquidvision/_api.py

@@ -0,0 +1,187 @@
+"""
+Shared core for the LiquidVision.app agent-framework wrappers.
+
+Six read-only questions an agent asks about crypto derivatives, each answered
+from LiquidVision.app's free "conclusion" endpoints and trimmed to a compact
+JSON answer an LLM can read in one pass. No key needed (60 requests a minute
+per IP); LIQUIDVISION_API_KEY raises the limit. Standard library only.
+"""
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Dict, Optional
+
+__version__ = "0.1.0"
+DEFAULT_BASE = "https://liquidvision.app/api/v1"
+
+
+def norm_symbol(symbol: Optional[str]) -> Optional[str]:
+    """'btc', 'BTC/USDT', 'BTC-USDT-SWAP', '$BTC' -> 'BTCUSDT'."""
+    if not symbol:
+        return None
+    s = re.sub(r"[^A-Za-z0-9]", "", symbol.upper().replace("SWAP", ""))
+    if s.endswith("USDC"):
+        s = s[:-4]
+    return s if s.endswith("USDT") else s + "USDT"
+
+
+class LiquidVisionAPI:
+    def __init__(self, api_key: Optional[str] = None, base_url: Optional[str] = None, timeout: float = 15.0):
+        self.api_key = api_key or os.environ.get("LIQUIDVISION_API_KEY")
+        self.base = (base_url or os.environ.get("LIQUIDVISION_BASE_URL") or DEFAULT_BASE).rstrip("/")
+        self.timeout = timeout
+
+    def get(self, path: str, **params: Any) -> Any:
+        q = {k: v for k, v in params.items() if v is not None}
+        url = self.base + path + ("?" + urllib.parse.urlencode(q) if q else "")
+        headers = {"User-Agent": f"liquidvision-agent-tools/{__version__}", "Accept": "application/json"}
+        if self.api_key:
+            headers["X-API-Key"] = self.api_key
+        req = urllib.request.Request(url, headers=headers)
+        try:
+            with urllib.request.urlopen(req, timeout=self.timeout) as r:
+                return json.loads(r.read())
+        except urllib.error.HTTPError as e:
+            if e.code == 429:
+                raise RuntimeError("LiquidVision rate limit reached (60/min without a key); retry in a minute") from None
+            raise RuntimeError(f"LiquidVision returned HTTP {e.code} for {path}") from None
+
+    # ------------------------------------------------------------ the six tools
+
+    def brief(self, symbol: str = "BTCUSDT") -> Dict[str, Any]:
+        b = self.get(f"/brief/{norm_symbol(symbol) or 'BTCUSDT'}")
+        liq = b.get("liquidations") or {}
+        return {
+            "symbol": b.get("symbol"),
+            "asset": b.get("asset"),
+            "liquidations_this_symbol_24h": liq.get("this_symbol_24h"),
+            "liquidations_market_wide_usd": liq.get("windows_usd"),
+            "funding_pct_by_exchange": (b.get("funding") or {}).get("current_pct_by_exchange"),
+            "open_interest_by_venue": b.get("open_interest_by_venue"),
+            "position_flows_usd": b.get("position_flows_usd"),
+            "next_risk_zones": b.get("next_risk_zones"),
+            "top_traders_positioning": b.get("top_traders_positioning"),
+            "data_age_s": b.get("age_s"),
+        }
+
+    def positioning_regime(self, symbol: Optional[str] = None, minutes: int = 240, limit: int = 15) -> Dict[str, Any]:
+        r = self.get("/oi/regime", minutes=minutes)
+        rows = r.get("rows") or []
+        sym = norm_symbol(symbol)
+        if sym:
+            rows = [x for x in rows if x.get("symbol") == sym]
+        else:
+            rows = sorted(rows, key=lambda x: abs(x.get("oi_delta_usd") or 0), reverse=True)[:limit]
+        return {
+            "window_minutes": r.get("minutes"),
+            "meaning": "price up + OI up = new longs; price up + OI down = short covering; "
+                       "price down + OI up = new shorts; price down + OI down = long flush",
+            "market_summary": r.get("summary"),
+            "coins": rows,
+        }
+
+    def liquidation_cascades(self, symbol: Optional[str] = None, hours: int = 24, limit: int = 10) -> Dict[str, Any]:
+        c = self.get("/liquidations/cascades", hours=hours, limit=200)
+        ev = c.get("events") or []
+        sym = norm_symbol(symbol)
+        if sym:
+            ev = [e for e in ev if e.get("symbol") == sym]
+        ev = sorted(ev, key=lambda e: e.get("usd") or 0, reverse=True)[:limit]
+        keep = ("symbol", "side", "start", "minutes", "usd", "peak_usd", "x_normal", "impact_pct", "reversion_pct")
+        return {
+            "hours": c.get("hours"),
+            "events_total": c.get("events_total"),
+            "market_wide_minutes": len(c.get("market_wide") or []),
+            "largest": [{k: e.get(k) for k in keep} for e in ev],
+            "notes": "side = which side was liquidated; x_normal = multiples of the coin's own normal minute; "
+                     "start is epoch ms; reversion_pct = how much of the move came back in the next hour. "
+                     + ((c.get("detector") or {}).get("caveat") or ""),
+        }
+
+    def liquidation_map(self, symbol: str = "BTCUSDT", top: int = 5) -> Dict[str, Any]:
+        m = self.get(f"/liqmap/hl/{norm_symbol(symbol) or 'BTCUSDT'}", range="1d")
+        px = m.get("current_price") or 0
+        bins, lo, sh = m.get("bins") or [], m.get("long") or [], m.get("short") or []
+        below = sorted(((b, v) for b, v in zip(bins, lo) if b < px and v > 0), key=lambda t: -t[1])[:top]
+        above = sorted(((b, v) for b, v in zip(bins, sh) if b > px and v > 0), key=lambda t: -t[1])[:top]
+        fmt = lambda t: {"price": round(t[0], 6), "usd": round(t[1]), "dist_pct": round((t[0] / px - 1) * 100, 2) if px else None}
+        return {
+            "symbol": m.get("symbol"),
+            "source": "measured Hyperliquid positions, binned by the liquidation price the exchange reports (not a model)",
+            "current_price": px,
+            "long_liquidations_below": [fmt(t) for t in sorted(below, key=lambda t: -t[0])],
+            "short_liquidations_above": [fmt(t) for t in sorted(above, key=lambda t: t[0])],
+            "total_long_below_usd": m.get("total_long_below"),
+            "total_short_above_usd": m.get("total_short_above"),
+            "coverage": m.get("coverage"),
+            "positions": m.get("positions"),
+        }
+
+    def funding_dispersion(self, symbol: Optional[str] = None, limit: int = 10) -> Dict[str, Any]:
+        sym = norm_symbol(symbol)
+        d = self.get("/funding/dispersion", limit=200 if sym else None)
+        rows = d.get("rows") or []
+        if sym:
+            rows = [r for r in rows if r.get("symbol") == sym]
+        out = []
+        for r in rows[:limit]:
+            x = {k: r.get(k) for k in ("symbol", "venues", "spread_apr", "long_venue", "long_apr",
+                                       "short_venue", "short_apr", "median_apr")}
+            if sym:
+                x["legs"] = [{k: l.get(k) for k in ("exchange", "apr", "funding_hours")} for l in r.get("legs") or []]
+            out.append(x)
+        return {
+            "window_minutes": d.get("window_minutes"),
+            "meaning": "APR in percent, each leg annualized on its own settlement cycle. long_venue is the cheapest "
+                       "place to hold a long, short_venue the richest place to hold a short.",
+            "coins": out,
+        }
+
+    def tokenized_stocks(self, limit: int = 15) -> Dict[str, Any]:
+        t = self.get("/stocks/tokenized")
+        rows = sorted(t.get("rows") or [], key=lambda r: r.get("oi_usd") or 0, reverse=True)[:limit]
+        keep = ("id", "name", "class_label", "venues", "oi_usd", "volume_24h_usd", "change_24h_pct", "mark")
+        return {
+            "what": "tokenized stocks, indices, commodities and FX traded as perps on DEXs",
+            "underlyings": t.get("underlyings"),
+            "total_oi_usd": t.get("total_oi_usd"),
+            "total_volume_24h_usd": t.get("total_volume_24h_usd"),
+            "by_class": t.get("by_class"),
+            "largest": [{k: r.get(k) for k in keep} for r in rows],
+        }
+
+
+TOOL_SPECS = [
+    ("liquidvision_derivatives_brief", "brief",
+     "One-coin crypto derivatives snapshot: price, open interest by venue, liquidations by side, funding per "
+     "exchange, nearest liquidation zones, top-trader positioning. Input: symbol like BTC or ETHUSDT."),
+    ("liquidvision_positioning_regime", "positioning_regime",
+     "Is a move new money or positions closing? Per coin: price change crossed with open-interest change "
+     "(new longs, short covering, new shorts, long flush). Optional symbol; without it, the biggest OI movers."),
+    ("liquidvision_liquidation_cascades", "liquidation_cascades",
+     "Liquidation cascades as events over the last hours: coin, side liquidated, size, multiple of normal, "
+     "price impact and what price did after. Optional symbol."),
+    ("liquidvision_liquidation_map", "liquidation_map",
+     "Where leverage would break: measured Hyperliquid positions by exchange-reported liquidation price, the "
+     "densest long-liquidation levels below price and short-liquidation levels above. Input: symbol."),
+    ("liquidvision_funding_dispersion", "funding_dispersion",
+     "Where the same coin pays very different funding across 13 exchanges: cheapest venue to be long, richest "
+     "to be short, spread in APR. Optional symbol for per-venue legs."),
+    ("liquidvision_tokenized_stocks", "tokenized_stocks",
+     "Tokenized stocks, indices, commodities and FX traded as perps on DEXs (Hyperliquid, Lighter, Ostium, "
+     "gTrade): open interest, volume, 24h change, largest markets."),
+]
+
+
+def run(api: LiquidVisionAPI, method: str, **kwargs: Any) -> str:
+    """Call a tool and return JSON text; errors come back as text so the agent can carry on."""
+    try:
+        return json.dumps(getattr(api, method)(**{k: v for k, v in kwargs.items() if v is not None}),
+                          separators=(",", ":"), default=str)
+    except Exception as e:  # noqa: BLE001
+        return json.dumps({"error": str(e)})

langchain_liquidvision-0.1.0/langchain_liquidvision.egg-info/PKG-INFO

@@ -0,0 +1,53 @@
+Metadata-Version: 2.4
+Name: langchain-liquidvision
+Version: 0.1.0
+Summary: LangChain tools for LiquidVision.app crypto derivatives data: open interest, funding and liquidations on 13 venues, liquidation cascades, positioning regime, measured Hyperliquid liquidation maps, funding dispersion, tokenized stocks. Read-only, no key needed.
+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/tree/main/integrations/langchain
+Keywords: langchain,langgraph,tools,crypto,derivatives,liquidations,open interest,funding rate,hyperliquid,trading,ai agent
+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
+Requires-Dist: langchain-core>=0.3
+
+# langchain-liquidvision
+
+Crypto derivatives tools for LangChain and LangGraph agents, from [LiquidVision.app](https://liquidvision.app).
+Read-only, no key needed.
+
+```bash
+pip install langchain-liquidvision
+```
+
+```python
+from langchain_liquidvision import LiquidVisionToolkit
+from langgraph.prebuilt import create_react_agent
+
+tools = LiquidVisionToolkit().get_tools()
+agent = create_react_agent("anthropic:claude-sonnet-5-5", tools)
+agent.invoke({"messages": [("user", "Is the ETH move new longs or short covering? Where are the liquidation levels?")]})
+```
+
+| Tool | Answers |
+|---|---|
+| `liquidvision_derivatives_brief` | One coin: price, open interest by venue, liquidations by side, funding per exchange, nearest liquidation zones |
+| `liquidvision_positioning_regime` | New longs, short covering, new shorts or long flush: price change crossed with OI change |
+| `liquidvision_liquidation_cascades` | Liquidation cascades as events: size, multiple of the coin's normal minute, price impact, reversion |
+| `liquidvision_liquidation_map` | Measured Hyperliquid liquidation levels below and above price (exchange-reported, not modeled) |
+| `liquidvision_funding_dispersion` | Cheapest venue to be long, richest to be short, across 13 exchanges |
+| `liquidvision_tokenized_stocks` | Tokenized stocks, indices, commodities and FX perps on DEXs |
+
+Each tool returns compact JSON. Errors come back as `{"error": ...}` so the agent keeps going.
+
+**Limits.** 60 requests a minute per IP without a key. Set `LIQUIDVISION_API_KEY` (or
+`LiquidVisionToolkit(api_key=...)`) with a Pro/Bot key for 600/1,200 a minute.
+
+**More.** Raw rows, history and Parquet: the [`liquidvision`](https://pypi.org/project/liquidvision/) client.
+MCP: `https://liquidvision.app/mcp/lite`. Docs: https://liquidvision.app/llms.txt
+
+Data, not financial advice.

langchain_liquidvision-0.1.0/langchain_liquidvision.egg-info/SOURCES.txt

@@ -0,0 +1,9 @@
+README.md
+pyproject.toml
+langchain_liquidvision/__init__.py
+langchain_liquidvision/_api.py
+langchain_liquidvision.egg-info/PKG-INFO
+langchain_liquidvision.egg-info/SOURCES.txt
+langchain_liquidvision.egg-info/dependency_links.txt
+langchain_liquidvision.egg-info/requires.txt
+langchain_liquidvision.egg-info/top_level.txt

langchain_liquidvision-0.1.0/langchain_liquidvision.egg-info/dependency_links.txt

@@ -0,0 +1 @@
+

langchain_liquidvision-0.1.0/langchain_liquidvision.egg-info/requires.txt

@@ -0,0 +1 @@
+langchain-core>=0.3

langchain_liquidvision-0.1.0/langchain_liquidvision.egg-info/top_level.txt

@@ -0,0 +1 @@
+langchain_liquidvision

langchain_liquidvision-0.1.0/pyproject.toml

@@ -0,0 +1,27 @@
+[build-system]
+requires = ["setuptools>=68"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "langchain-liquidvision"
+version = "0.1.0"
+description = "LangChain tools for LiquidVision.app crypto derivatives data: open interest, funding and liquidations on 13 venues, liquidation cascades, positioning regime, measured Hyperliquid liquidation maps, funding dispersion, tokenized stocks. Read-only, no key needed."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+dependencies = ["langchain-core>=0.3"]
+keywords = ["langchain", "langgraph", "tools", "crypto", "derivatives", "liquidations", "open interest", "funding rate", "hyperliquid", "trading", "ai agent"]
+classifiers = [
+    "Programming Language :: Python :: 3",
+    "License :: OSI Approved :: MIT License",
+    "Topic :: Office/Business :: Financial",
+    "Intended Audience :: Developers",
+]
+
+[project.urls]
+Homepage = "https://liquidvision.app"
+Documentation = "https://liquidvision.app/llms.txt"
+Source = "https://github.com/lv-analytics/liquidvision-mcp/tree/main/integrations/langchain"
+
+[tool.setuptools]
+packages = ["langchain_liquidvision"]

langchain_liquidvision-0.1.0/setup.cfg

@@ -0,0 +1,4 @@
+[egg_info]
+tag_build = 
+tag_date = 0
+