n0brains-cli 1.0.0__py3-none-any.whl

n0brains_cli-1.0.0.dist-info/METADATA

@@ -0,0 +1,89 @@
+Metadata-Version: 2.4
+Name: n0brains-cli
+Version: 1.0.0
+Summary: Token-efficient CLI for the n0brains crypto intelligence API — built for trading agents.
+Author: n0brains
+License: MIT
+Project-URL: Homepage, https://n0brains.com
+Project-URL: API, https://api.n0brains.com
+Keywords: crypto,trading,signals,agent,intelligence,mcp
+Requires-Python: >=3.8
+Description-Content-Type: text/markdown
+Provides-Extra: stream
+Requires-Dist: websockets>=12.0; extra == "stream"
+
+# n0brains CLI
+
+Token-efficient command-line access to the [n0brains](https://n0brains.com) crypto
+intelligence API — built for trading agents, scripts, and humans. Every command
+prints raw JSON to stdout, so it composes with `jq`, pipes into an LLM, or feeds a
+bot directly. Zero third-party dependencies (Python 3.8+ stdlib only); the optional
+`stream` command needs `websockets`.
+
+## Why a CLI (vs the MCP server)
+
+n0brains also ships an [MCP server](https://api.n0brains.com/mcp) for Claude /
+Cursor / Cline. The CLI is the better fit when you're driving a **bot or shell
+pipeline**: plain JSON with no protocol envelope is more token-efficient, it
+composes with Unix tools, and it runs anywhere `curl` does. Same data, both
+surfaces.
+
+## Install
+
+```bash
+pip install n0brains-cli          # once published
+# or run the single file directly:
+python3 n0brains_cli.py --help
+```
+
+## Auth
+
+```bash
+export N0BRAINS_API_KEY=intel_sk_...   # get one at https://n0brains.com
+# or pass --api-key on any command. Public endpoints (proof) work without a key.
+```
+
+## Commands
+
+| Command | What it returns |
+|---|---|
+| `signals [--proven-only] [--asset BTC] [--type hack] [--limit N]` | Active classified signals |
+| `signal <id>` | One signal with full context |
+| `similar <query>` | Semantic similarity search (pro) |
+| `levels <coin>` | Support/resistance levels |
+| `liquidation-map <coin>` | Estimated liquidation-cluster zones |
+| `correlation [coin] [--vs BTC] [--coins BTC,ETH,SOL]` | Correlation matrix or one coin's corr+beta |
+| `rotation` | Altseason/rotation read (into_alts / into_btc / neutral) |
+| `macro` | Daily BTC/ETH macro bias |
+| `narrative <coin>` | Narrative context |
+| `trust <coin>` | Trust/rug score |
+| `manipulation <coin>` | Manipulation score |
+| `proof [--equity]` | Live forward-return proof per signal type (+ equity curve) |
+| `performance [--days 30] [--tier N]` | Backtest stats |
+| `stream` | Live signal stream over WebSocket (pro) |
+
+## Examples
+
+```bash
+# Only proven-edge signals, as JSON
+n0brains signals --proven-only --limit 10
+
+# Is it altseason? one-line answer
+n0brains rotation | jq -r .regime
+
+# Where are BTC liquidation magnets?
+n0brains liquidation-map BTC | jq '.densest_long_liq_zone, .densest_short_liq_zone'
+
+# Feed proven-edge signals into a bot loop
+while n0brains signals --tradeable-only --limit 5 | jq -c '.signals[]'; do sleep 60; done
+
+# Live stream (needs: pip install websockets)
+N0BRAINS_API_KEY=... n0brains stream | jq -c 'select(.conviction=="strong")'
+```
+
+Exit code is `2` on an API error (so scripts can detect failures), `0` on success.
+
+## For agent frameworks
+
+See [`SKILL.md`](SKILL.md) for a capability description you can drop into an agent
+framework (the same tools are also exposed via MCP and REST).

n0brains_cli-1.0.0.dist-info/RECORD

@@ -0,0 +1,6 @@
+n0brains_cli.py,sha256=8kvlU5PMLo06vZu9fCSwNv61z0dWj-fNGk5l9B4DVAA,8122
+n0brains_cli-1.0.0.dist-info/METADATA,sha256=VtzI4G_ZcFh2vmvJkYit-O8YC4cHvCCp9UJFvW3HtrI,3248
+n0brains_cli-1.0.0.dist-info/WHEEL,sha256=aeYiig01lYGDzBgS8HxWXOg3uV61G9ijOsup-k9o1sk,91
+n0brains_cli-1.0.0.dist-info/entry_points.txt,sha256=EG6sSNTexKofPdgk_ZAIFKEskkvELmVuug-A0Nuq3BY,47
+n0brains_cli-1.0.0.dist-info/top_level.txt,sha256=KP4ASdC3YmkI3H6M2ftoIQvQ7Qrpo6DnP-319S7iXXM,13
+n0brains_cli-1.0.0.dist-info/RECORD,,

n0brains_cli-1.0.0.dist-info/WHEEL

@@ -0,0 +1,5 @@
+Wheel-Version: 1.0
+Generator: setuptools (82.0.1)
+Root-Is-Purelib: true
+Tag: py3-none-any
+

n0brains_cli-1.0.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+n0brains = n0brains_cli:main

n0brains_cli-1.0.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+n0brains_cli

n0brains_cli.py

@@ -0,0 +1,218 @@
+#!/usr/bin/env python3
+"""n0brains CLI — token-efficient command-line access to the n0brains crypto
+intelligence API for trading agents, scripts, and humans.
+
+Every command prints raw JSON to stdout (pipe into jq, an LLM, or a bot). Zero
+third-party dependencies — Python 3.8+ stdlib only. Auth via the N0BRAINS_API_KEY
+env var or --api-key. Base URL overridable via N0BRAINS_BASE_URL (default the
+public API).
+
+Why a CLI when there's an MCP server: for bots and shell pipelines a CLI is more
+token-efficient than MCP (plain JSON, no protocol envelope, composes with Unix
+tools) and works anywhere curl does. Same data as the REST API + MCP tools.
+
+Examples:
+  N0BRAINS_API_KEY=intel_sk_... n0brains signals --proven-only --limit 10
+  n0brains rotation | jq .regime
+  n0brains liquidation-map BTC
+  n0brains proof
+  n0brains stream            # live signal stream (WebSocket, pro tier)
+"""
+import argparse
+import json
+import os
+import sys
+import urllib.parse
+import urllib.request
+import urllib.error
+
+DEFAULT_BASE = os.getenv("N0BRAINS_BASE_URL", "https://api.n0brains.com")
+__version__ = "1.0.0"
+
+
+def _key(args) -> str:
+    k = args.api_key or os.getenv("N0BRAINS_API_KEY", "")
+    return k
+
+
+def _get(path: str, params: dict, args) -> dict:
+    url = args.base.rstrip("/") + path
+    q = {k: v for k, v in (params or {}).items() if v is not None}
+    if q:
+        url += "?" + urllib.parse.urlencode(q)
+    req = urllib.request.Request(url, method="GET")
+    key = _key(args)
+    if key:
+        req.add_header("X-API-Key", key)
+    req.add_header("User-Agent", f"n0brains-cli/{__version__}")
+    try:
+        with urllib.request.urlopen(req, timeout=args.timeout) as resp:
+            return json.loads(resp.read().decode())
+    except urllib.error.HTTPError as e:
+        body = e.read().decode(errors="replace")
+        try:
+            detail = json.loads(body)
+        except Exception:
+            detail = {"detail": body[:300]}
+        return {"error": True, "status": e.code, **detail}
+    except Exception as e:
+        return {"error": True, "detail": str(e)}
+
+
+def _out(obj):
+    json.dump(obj, sys.stdout, indent=2, default=str)
+    sys.stdout.write("\n")
+    # non-zero exit on API error so scripts/bots can detect failure
+    if isinstance(obj, dict) and obj.get("error"):
+        sys.exit(2)
+
+
+# ── command handlers ───────────────────────────────────────────────────────────
+def cmd_signals(a):
+    _out(_get("/signals", {
+        "asset": a.asset, "signal_type": a.type, "direction": a.direction,
+        "urgency": a.urgency, "limit": a.limit, "min_confidence": a.min_confidence,
+        "min_score": a.min_score, "band": a.band,
+        "proven_only": "true" if a.proven_only else None,
+        "tradeable_only": "true" if a.tradeable_only else None,
+        "include_noise": "true" if a.include_noise else None,
+    }, a))
+
+
+def cmd_signal(a):
+    _out(_get(f"/signals/{a.id}", {}, a))
+
+
+def cmd_similar(a):
+    _out(_get("/signals/similar", {"query": a.query, "asset": a.asset, "limit": a.limit}, a))
+
+
+def cmd_levels(a):
+    _out(_get(f"/levels/{a.coin}", {}, a))
+
+
+def cmd_liqmap(a):
+    _out(_get(f"/liquidation-map/{a.coin}", {}, a))
+
+
+def cmd_correlation(a):
+    if a.coin:
+        _out(_get(f"/correlation/{a.coin}", {}, a))
+    else:
+        _out(_get("/correlation", {"vs": a.vs, "coins": a.coins}, a))
+
+
+def cmd_rotation(a):
+    _out(_get("/rotation", {}, a))
+
+
+def cmd_macro(a):
+    _out(_get("/macro", {}, a))
+
+
+def cmd_narrative(a):
+    _out(_get(f"/narrative/{a.coin}", {}, a))
+
+
+def cmd_trust(a):
+    _out(_get(f"/trust/{a.coin}", {}, a))
+
+
+def cmd_manipulation(a):
+    _out(_get(f"/manipulation/{a.coin}", {}, a))
+
+
+def cmd_proof(a):
+    _out(_get("/proof/equity" if a.equity else "/proof", {}, a))
+
+
+def cmd_performance(a):
+    _out(_get("/performance", {"days": a.days, "tier": a.tier}, a))
+
+
+def cmd_stream(a):
+    # Lazy import — only needed for streaming, keeps the base CLI dep-free.
+    try:
+        from websockets.sync.client import connect  # type: ignore
+    except Exception:
+        sys.stderr.write(
+            "stream needs the 'websockets' package: pip install websockets\n"
+            "Or poll instead: n0brains signals --limit 50\n")
+        sys.exit(1)
+    key = _key(a)
+    base = a.base.replace("https://", "wss://").replace("http://", "ws://").rstrip("/")
+    url = f"{base}/stream?api_key={urllib.parse.quote(key)}"
+    try:
+        with connect(url) as ws:
+            for msg in ws:
+                try:
+                    obj = json.loads(msg)
+                except Exception:
+                    continue
+                if obj.get("type") in ("ping", "pong"):
+                    continue
+                json.dump(obj, sys.stdout)
+                sys.stdout.write("\n")
+                sys.stdout.flush()
+    except KeyboardInterrupt:
+        pass
+    except Exception as e:
+        sys.stderr.write(f"stream error: {e}\n")
+        sys.exit(1)
+
+
+def build_parser() -> argparse.ArgumentParser:
+    p = argparse.ArgumentParser(prog="n0brains", description="n0brains crypto intelligence CLI")
+    p.add_argument("--api-key", help="API key (or set N0BRAINS_API_KEY)")
+    p.add_argument("--base", default=DEFAULT_BASE, help="API base URL")
+    p.add_argument("--timeout", type=float, default=20.0)
+    p.add_argument("--version", action="version", version=f"n0brains-cli {__version__}")
+    sub = p.add_subparsers(dest="cmd", required=True)
+
+    s = sub.add_parser("signals", help="List active signals")
+    s.add_argument("--asset"); s.add_argument("--type"); s.add_argument("--direction")
+    s.add_argument("--urgency"); s.add_argument("--limit", type=int, default=50)
+    s.add_argument("--min-confidence", type=float); s.add_argument("--min-score", type=float)
+    s.add_argument("--band"); s.add_argument("--proven-only", action="store_true")
+    s.add_argument("--tradeable-only", action="store_true")
+    s.add_argument("--include-noise", action="store_true")
+    s.set_defaults(fn=cmd_signals)
+
+    g = sub.add_parser("signal", help="Get one signal by id"); g.add_argument("id"); g.set_defaults(fn=cmd_signal)
+
+    sm = sub.add_parser("similar", help="Semantic similarity search (pro)")
+    sm.add_argument("query", nargs="?"); sm.add_argument("--asset"); sm.add_argument("--limit", type=int, default=10)
+    sm.set_defaults(fn=cmd_similar)
+
+    lv = sub.add_parser("levels", help="Support/resistance for a coin"); lv.add_argument("coin"); lv.set_defaults(fn=cmd_levels)
+    lm = sub.add_parser("liquidation-map", help="Estimated liquidation zones"); lm.add_argument("coin"); lm.set_defaults(fn=cmd_liqmap)
+
+    c = sub.add_parser("correlation", help="Correlation matrix or one coin's corr/beta")
+    c.add_argument("coin", nargs="?"); c.add_argument("--vs"); c.add_argument("--coins")
+    c.set_defaults(fn=cmd_correlation)
+
+    sub.add_parser("rotation", help="Altseason/rotation read").set_defaults(fn=cmd_rotation)
+    sub.add_parser("macro", help="Daily BTC/ETH macro bias").set_defaults(fn=cmd_macro)
+
+    nv = sub.add_parser("narrative", help="Narrative context for a coin"); nv.add_argument("coin"); nv.set_defaults(fn=cmd_narrative)
+    tr = sub.add_parser("trust", help="Trust/rug score for a coin"); tr.add_argument("coin"); tr.set_defaults(fn=cmd_trust)
+    mn = sub.add_parser("manipulation", help="Manipulation score for a coin"); mn.add_argument("coin"); mn.set_defaults(fn=cmd_manipulation)
+
+    pr = sub.add_parser("proof", help="Forward-return proof (--equity for the curve)")
+    pr.add_argument("--equity", action="store_true"); pr.set_defaults(fn=cmd_proof)
+
+    pf = sub.add_parser("performance", help="Backtest stats")
+    pf.add_argument("--days", type=int, default=30); pf.add_argument("--tier", type=int)
+    pf.set_defaults(fn=cmd_performance)
+
+    sub.add_parser("stream", help="Live signal stream over WebSocket (pro)").set_defaults(fn=cmd_stream)
+    return p
+
+
+def main(argv=None):
+    args = build_parser().parse_args(argv)
+    args.fn(args)
+
+
+if __name__ == "__main__":
+    main()