hunterkiller 0.1.0__tar.gz

hunterkiller-0.1.0/PKG-INFO

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: hunterkiller
+Version: 0.1.0
+Summary: Hunter Killer Desk Read client: check where liquidation money is stacked before a leveraged trade, and watch for walls coming into range.
+License: MIT
+Project-URL: Homepage, https://hunterkiller.io/for-agents
+Keywords: crypto,liquidations,perpetuals,trading,agents,mcp
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# hunterkiller (Python)
+
+Client for the Hunter Killer Desk Read. Standard library only.
+
+```
+pip install hunterkiller
+```
+
+```python
+import hunterkiller as hk
+
+read = hk.desk_read("BTCUSDT", side="long", entry=81000, leverage=20)
+print(read["verdict"], read["text"])
+
+print(hk.symbols()["covered"])
+
+for event in hk.watch("BTCUSDT", threshold_pct=1.5):   # needs a key
+    print(event["reason"], event["text"])
+```
+
+`desk_read` works without a key (delayed data). `watch` needs a key: a free key (delayed, one
+stream) is returned as `api_key` when you sign up at https://hunterkiller.io/signup. Pass `key=`
+or set `HK_API_KEY`. A paid key is live and gets five streams. Errors raise `HunterKillerError`
+with `.status` and `.body`.
+
+`watch` yields the `desk_read` payload plus `event`, `reason` (`connect`, `wall_in_range:above`,
+`wall_in_range:below`, `pull_flip`) and `threshold_pct`. It reconnects on its own after the
+30 minute cap. Descriptive data, not a forecast. Docs: https://hunterkiller.io/for-agents

hunterkiller-0.1.0/README.md

@@ -0,0 +1,28 @@
+# hunterkiller (Python)
+
+Client for the Hunter Killer Desk Read. Standard library only.
+
+```
+pip install hunterkiller
+```
+
+```python
+import hunterkiller as hk
+
+read = hk.desk_read("BTCUSDT", side="long", entry=81000, leverage=20)
+print(read["verdict"], read["text"])
+
+print(hk.symbols()["covered"])
+
+for event in hk.watch("BTCUSDT", threshold_pct=1.5):   # needs a key
+    print(event["reason"], event["text"])
+```
+
+`desk_read` works without a key (delayed data). `watch` needs a key: a free key (delayed, one
+stream) is returned as `api_key` when you sign up at https://hunterkiller.io/signup. Pass `key=`
+or set `HK_API_KEY`. A paid key is live and gets five streams. Errors raise `HunterKillerError`
+with `.status` and `.body`.
+
+`watch` yields the `desk_read` payload plus `event`, `reason` (`connect`, `wall_in_range:above`,
+`wall_in_range:below`, `pull_flip`) and `threshold_pct`. It reconnects on its own after the
+30 minute cap. Descriptive data, not a forecast. Docs: https://hunterkiller.io/for-agents

hunterkiller-0.1.0/hunterkiller/__init__.py

@@ -0,0 +1,127 @@
+"""hunterkiller: Python client for the Hunter Killer Desk Read. Standard library only.
+
+    import hunterkiller as hk
+    read = hk.desk_read("BTCUSDT", side="long", entry=81000, leverage=20, key="hk_live_...")
+    print(read["verdict"], read["text"])
+
+    for event in hk.watch("BTCUSDT", threshold_pct=1.5, key="hk_live_..."):
+        print(event["reason"], event["text"])
+
+A key is optional for desk_read (keyless calls get the delayed tier) and required for watch.
+Get a free key (delayed data) at https://hunterkiller.io/signup. The key can also come from the
+HK_API_KEY environment variable. Descriptive data, not a forecast."""
+from __future__ import annotations
+
+import json
+import os
+import time
+import urllib.error
+import urllib.parse
+import urllib.request
+
+__all__ = ["desk_read", "watch", "symbols", "HunterKillerError", "BASE_URL"]
+__version__ = "0.1.0"
+
+BASE_URL = os.environ.get("HK_BASE_URL", "https://hunterkiller.io")
+_UA = "hunterkiller-python/" + __version__
+
+
+class HunterKillerError(Exception):
+    """An HTTP error from the API. .status is the code, .body the parsed JSON error body."""
+
+    def __init__(self, status, body):
+        self.status, self.body = status, body
+        msg = body.get("message") or body.get("error") if isinstance(body, dict) else None
+        super().__init__(f"HTTP {status}: {msg or body}")
+
+
+def _headers(key):
+    key = key or os.environ.get("HK_API_KEY")
+    h = {"User-Agent": _UA, "Accept": "application/json"}
+    if key:
+        h["Authorization"] = "Bearer " + key
+    return h
+
+
+def _open(url, headers, timeout):
+    req = urllib.request.Request(url, headers=headers)
+    try:
+        return urllib.request.urlopen(req, timeout=timeout)
+    except urllib.error.HTTPError as e:
+        raw = e.read().decode("utf-8", "replace")
+        try:
+            body = json.loads(raw)
+        except ValueError:
+            body = {"error": raw[:200]}
+        raise HunterKillerError(e.code, body) from None
+
+
+def _get_json(path, params, key, base_url, timeout=15):
+    q = urllib.parse.urlencode({k: v for k, v in params.items() if v is not None})
+    with _open(f"{base_url or BASE_URL}{path}" + (f"?{q}" if q else ""), _headers(key), timeout) as r:
+        return json.load(r)
+
+
+def desk_read(symbol, side=None, entry=None, leverage=None, key=None, base_url=None):
+    """The Desk Read for one perp pair: pull, hurt, cascade, crowd, plan, verdict, lines, text.
+    side, entry and leverage together add where your liquidation sits and a verdict."""
+    return _get_json("/api/desk_read", {"symbol": symbol, "side": side, "entry": entry,
+                                        "leverage": leverage, "ref": "hunterkiller-python"},
+                     key, base_url)
+
+
+def symbols(base_url=None):
+    """Covered symbols per tier and the free-tier delay."""
+    return _get_json("/api/desk_read/symbols", {}, None, base_url)
+
+
+def _sse(lines):
+    """Yield (event, data) from an iterable of decoded SSE lines. Comments are skipped."""
+    event, data = "message", []
+    for raw in lines:
+        line = raw.rstrip("\r\n")
+        if line == "":
+            if data:
+                yield event, "\n".join(data)
+            event, data = "message", []
+        elif line.startswith(":"):
+            continue
+        elif line.startswith("event:"):
+            event = line[6:].strip()
+        elif line.startswith("data:"):
+            data.append(line[5:].lstrip())
+
+
+def watch(symbol, threshold_pct=1.5, key=None, base_url=None, reconnect=True, max_events=None):
+    """Generator of desk_read events: one on connect, then whenever the nearest wall on either
+    side comes within threshold_pct of price or the pull direction flips. Reconnects on the
+    server's 30-minute reconnect event and on dropped connections (back off up to 30 s).
+    Auth and limit errors raise HunterKillerError (a keyless call is 401). max_events stops
+    the generator after that many events (handy in tests)."""
+    q = urllib.parse.urlencode({"symbol": symbol, "threshold_pct": threshold_pct,
+                                "ref": "hunterkiller-python"})
+    url = f"{base_url or BASE_URL}/api/desk_read/watch?{q}"
+    headers = dict(_headers(key), Accept="text/event-stream")
+    sent, delay = 0, 1.0
+    while True:
+        try:
+            with _open(url, headers, 90) as resp:
+                delay = 1.0
+                for event, data in _sse(line.decode("utf-8", "replace") for line in resp):
+                    if event == "desk_read":
+                        yield json.loads(data)
+                        sent += 1
+                        if max_events and sent >= max_events:
+                            return
+                    elif event == "reconnect":
+                        break
+        except HunterKillerError as e:
+            if e.status != 429 or not reconnect:
+                raise
+        except OSError:
+            if not reconnect:
+                return
+        if not reconnect:
+            return
+        time.sleep(delay)
+        delay = min(delay * 2, 30.0)

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

@@ -0,0 +1,38 @@
+Metadata-Version: 2.4
+Name: hunterkiller
+Version: 0.1.0
+Summary: Hunter Killer Desk Read client: check where liquidation money is stacked before a leveraged trade, and watch for walls coming into range.
+License: MIT
+Project-URL: Homepage, https://hunterkiller.io/for-agents
+Keywords: crypto,liquidations,perpetuals,trading,agents,mcp
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+
+# hunterkiller (Python)
+
+Client for the Hunter Killer Desk Read. Standard library only.
+
+```
+pip install hunterkiller
+```
+
+```python
+import hunterkiller as hk
+
+read = hk.desk_read("BTCUSDT", side="long", entry=81000, leverage=20)
+print(read["verdict"], read["text"])
+
+print(hk.symbols()["covered"])
+
+for event in hk.watch("BTCUSDT", threshold_pct=1.5):   # needs a key
+    print(event["reason"], event["text"])
+```
+
+`desk_read` works without a key (delayed data). `watch` needs a key: a free key (delayed, one
+stream) is returned as `api_key` when you sign up at https://hunterkiller.io/signup. Pass `key=`
+or set `HK_API_KEY`. A paid key is live and gets five streams. Errors raise `HunterKillerError`
+with `.status` and `.body`.
+
+`watch` yields the `desk_read` payload plus `event`, `reason` (`connect`, `wall_in_range:above`,
+`wall_in_range:below`, `pull_flip`) and `threshold_pct`. It reconnects on its own after the
+30 minute cap. Descriptive data, not a forecast. Docs: https://hunterkiller.io/for-agents

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

@@ -0,0 +1,7 @@
+README.md
+pyproject.toml
+hunterkiller/__init__.py
+hunterkiller.egg-info/PKG-INFO
+hunterkiller.egg-info/SOURCES.txt
+hunterkiller.egg-info/dependency_links.txt
+hunterkiller.egg-info/top_level.txt

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

@@ -0,0 +1 @@
+

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

@@ -0,0 +1 @@
+hunterkiller

hunterkiller-0.1.0/pyproject.toml

@@ -0,0 +1,19 @@
+[build-system]
+requires = ["setuptools>=61"]
+build-backend = "setuptools.build_meta"
+
+[project]
+name = "hunterkiller"
+version = "0.1.0"
+description = "Hunter Killer Desk Read client: check where liquidation money is stacked before a leveraged trade, and watch for walls coming into range."
+readme = "README.md"
+requires-python = ">=3.8"
+license = { text = "MIT" }
+dependencies = []
+keywords = ["crypto", "liquidations", "perpetuals", "trading", "agents", "mcp"]
+
+[project.urls]
+Homepage = "https://hunterkiller.io/for-agents"
+
+[tool.setuptools]
+packages = ["hunterkiller"]

hunterkiller-0.1.0/setup.cfg

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