reins-client 0.1.0__tar.gz

reins_client-0.1.0/.gitignore

@@ -0,0 +1,31 @@
+node_modules/
+dist/
+.env
+.env.*
+!.env.example
+*.log
+.DS_Store
+
+# Demo agent runs: paper account, decision log, API spend.
+demo-data/
+
+# Packages made to copy the demo to a server.
+*.tar.gz
+
+# The MCP Registry publisher, if downloaded locally.
+mcp-publisher.exe
+mcp-publisher.tar.gz
+mcp-publisher
+
+# The site zipped up for uploading to the host.
+r2rlabs-site.zip
+
+# Working notes for Claude: local only, they are not part of the product.
+CLAUDE.md
+
+# Local-only tooling: the daily interest report and its history.
+local/
+
+# Python client build output.
+clients/python/dist/
+clients/python/**/__pycache__/

reins_client-0.1.0/PKG-INFO

@@ -0,0 +1,124 @@
+Metadata-Version: 2.5
+Name: reins-client
+Version: 0.1.0
+Summary: Risk limits and an audit log for Python trading bots on Hyperliquid, through a Reins server.
+Project-URL: Homepage, https://r2rlabs.com
+Project-URL: Documentation, https://r2rlabs.com/mcp/
+Project-URL: Source, https://github.com/R2Rlabs/reins
+Project-URL: Issues, https://github.com/R2Rlabs/reins/issues
+Author: R2R Labs
+License: MIT
+Keywords: agent,bot,hyperliquid,mcp,risk,trading
+Classifier: Development Status :: 4 - Beta
+Classifier: Intended Audience :: Developers
+Classifier: Intended Audience :: Financial and Insurance Industry
+Classifier: License :: OSI Approved :: MIT License
+Classifier: Programming Language :: Python :: 3
+Classifier: Topic :: Office/Business :: Financial :: Investment
+Requires-Python: >=3.9
+Description-Content-Type: text/markdown
+
+# reins-client
+
+Risk limits and an audit log around a Python trading bot on Hyperliquid.
+
+Your bot decides what to trade. Reins decides what it is allowed to send: a cap
+per position, leverage, a daily loss limit that halts trading, an allowlist, a
+rate limit, a required stop-loss, and a cap on what one trade may lose. The
+limits run in a separate process, so no prompt, bug or bad hour gets around
+them, and every attempt — including the refusals — is written to an append-only
+log.
+
+```bash
+pip install reins-client
+```
+
+Point it at a running Reins server:
+
+```bash
+npx @r2rlabs/reins init          # writes a paper-trading config
+npx @r2rlabs/reins http          # prints the URL and token
+```
+
+## Using it
+
+```python
+from reins import Reins, Refused
+
+reins = Reins.from_env()          # REINS_URL, REINS_HTTP_TOKEN
+
+book = reins.book("BTC")
+entry = book["bestBid"]
+stop = round(entry * 0.99, 1)
+
+try:
+    order = reins.place_order(
+        symbol="BTC",
+        side="buy",
+        size_usd=Reins.size_for_risk(entry, stop, risk_usd=25),
+        price=entry,
+        stop_loss=stop,
+        reason="range low held on the hourly",
+        tif="Alo",                # post-only: maker fees, no chasing
+    )
+except Refused as refusal:
+    print(refusal.code, refusal.reason)
+```
+
+A refusal is not an error in your code — it is Reins doing its job. It arrives
+as `Refused` with the code, so a bot can branch on it:
+
+`POSITION_TOO_LARGE`, `LEVERAGE_TOO_HIGH`, `HALTED_DAILY_LOSS`,
+`TRADE_RISK_TOO_LARGE`, `NO_STOP_LOSS`, `SYMBOL_NOT_ALLOWED`, `RATE_LIMITED`,
+`INVALID_ORDER`.
+
+### Sizing from the stop
+
+`Reins.size_for_risk(entry, stop, risk_usd)` is the same arithmetic the risk
+engine checks: size = risk ÷ (distance to the stop, as a fraction of entry).
+Size this way and a wider stop gives you a smaller position instead of a bigger
+loss — which is what keeps orders inside `TRADE_RISK_TOO_LARGE`.
+
+### Everything else
+
+```python
+reins.health()                    # paper or live — check before you trade
+reins.limits()                    # the limits in force, and what is left of them today
+reins.positions()                 # equity, open positions, anything without a stop
+reins.candles("ETH", interval="1h", count=50)
+reins.set_stop_loss(symbol="BTC", trigger_price=82000, reason="under the low")
+reins.cancel_order(symbol="BTC", order_id=2, reason="setup gone")
+reins.close_position(symbol="BTC", reason="target hit")
+reins.decisions(limit=20)         # the log: tried, refused, filled
+```
+
+`reason` is required on anything that changes a position. An order nobody
+explained is the one you cannot account for afterwards.
+
+## Paper first
+
+A Reins server in paper mode uses live Hyperliquid prices with simulated fills,
+the same limits and the same fees, and signs nothing. Point your bot at it and
+you can watch a week of its decisions before any money is involved. Paper is
+free; live trading pays a 2 basis point Hyperliquid builder fee, and there is no
+subscription.
+
+## Checked against the real thing
+
+`tests/` has 17 unit tests against a stub server (no network), plus `e2e.py`,
+which drives a real server:
+
+```bash
+python -m unittest discover -s tests            # unit
+node dist/bin/cli.js http --port 8799           # in the Reins repo, paper mode
+REINS_URL=http://127.0.0.1:8799 REINS_HTTP_TOKEN=... python tests/e2e.py
+```
+
+The end-to-end run places a real paper order with an attached stop, then
+deliberately breaches three limits and checks each refusal comes back with the
+right code and lands in the log.
+
+No dependencies: the client is one stdlib-only file, so it can be vendored if
+you would rather not add a package.
+
+MIT licensed. Source: https://github.com/R2Rlabs/reins

reins_client-0.1.0/README.md

@@ -0,0 +1,104 @@
+# reins-client
+
+Risk limits and an audit log around a Python trading bot on Hyperliquid.
+
+Your bot decides what to trade. Reins decides what it is allowed to send: a cap
+per position, leverage, a daily loss limit that halts trading, an allowlist, a
+rate limit, a required stop-loss, and a cap on what one trade may lose. The
+limits run in a separate process, so no prompt, bug or bad hour gets around
+them, and every attempt — including the refusals — is written to an append-only
+log.
+
+```bash
+pip install reins-client
+```
+
+Point it at a running Reins server:
+
+```bash
+npx @r2rlabs/reins init          # writes a paper-trading config
+npx @r2rlabs/reins http          # prints the URL and token
+```
+
+## Using it
+
+```python
+from reins import Reins, Refused
+
+reins = Reins.from_env()          # REINS_URL, REINS_HTTP_TOKEN
+
+book = reins.book("BTC")
+entry = book["bestBid"]
+stop = round(entry * 0.99, 1)
+
+try:
+    order = reins.place_order(
+        symbol="BTC",
+        side="buy",
+        size_usd=Reins.size_for_risk(entry, stop, risk_usd=25),
+        price=entry,
+        stop_loss=stop,
+        reason="range low held on the hourly",
+        tif="Alo",                # post-only: maker fees, no chasing
+    )
+except Refused as refusal:
+    print(refusal.code, refusal.reason)
+```
+
+A refusal is not an error in your code — it is Reins doing its job. It arrives
+as `Refused` with the code, so a bot can branch on it:
+
+`POSITION_TOO_LARGE`, `LEVERAGE_TOO_HIGH`, `HALTED_DAILY_LOSS`,
+`TRADE_RISK_TOO_LARGE`, `NO_STOP_LOSS`, `SYMBOL_NOT_ALLOWED`, `RATE_LIMITED`,
+`INVALID_ORDER`.
+
+### Sizing from the stop
+
+`Reins.size_for_risk(entry, stop, risk_usd)` is the same arithmetic the risk
+engine checks: size = risk ÷ (distance to the stop, as a fraction of entry).
+Size this way and a wider stop gives you a smaller position instead of a bigger
+loss — which is what keeps orders inside `TRADE_RISK_TOO_LARGE`.
+
+### Everything else
+
+```python
+reins.health()                    # paper or live — check before you trade
+reins.limits()                    # the limits in force, and what is left of them today
+reins.positions()                 # equity, open positions, anything without a stop
+reins.candles("ETH", interval="1h", count=50)
+reins.set_stop_loss(symbol="BTC", trigger_price=82000, reason="under the low")
+reins.cancel_order(symbol="BTC", order_id=2, reason="setup gone")
+reins.close_position(symbol="BTC", reason="target hit")
+reins.decisions(limit=20)         # the log: tried, refused, filled
+```
+
+`reason` is required on anything that changes a position. An order nobody
+explained is the one you cannot account for afterwards.
+
+## Paper first
+
+A Reins server in paper mode uses live Hyperliquid prices with simulated fills,
+the same limits and the same fees, and signs nothing. Point your bot at it and
+you can watch a week of its decisions before any money is involved. Paper is
+free; live trading pays a 2 basis point Hyperliquid builder fee, and there is no
+subscription.
+
+## Checked against the real thing
+
+`tests/` has 17 unit tests against a stub server (no network), plus `e2e.py`,
+which drives a real server:
+
+```bash
+python -m unittest discover -s tests            # unit
+node dist/bin/cli.js http --port 8799           # in the Reins repo, paper mode
+REINS_URL=http://127.0.0.1:8799 REINS_HTTP_TOKEN=... python tests/e2e.py
+```
+
+The end-to-end run places a real paper order with an attached stop, then
+deliberately breaches three limits and checks each refusal comes back with the
+right code and lands in the log.
+
+No dependencies: the client is one stdlib-only file, so it can be vendored if
+you would rather not add a package.
+
+MIT licensed. Source: https://github.com/R2Rlabs/reins

reins_client-0.1.0/pyproject.toml

@@ -0,0 +1,31 @@
+[build-system]
+requires = ["hatchling"]
+build-backend = "hatchling.build"
+
+[project]
+name = "reins-client"
+version = "0.1.0"
+description = "Risk limits and an audit log for Python trading bots on Hyperliquid, through a Reins server."
+readme = "README.md"
+requires-python = ">=3.9"
+license = { text = "MIT" }
+authors = [{ name = "R2R Labs" }]
+keywords = ["hyperliquid", "trading", "risk", "agent", "bot", "mcp"]
+classifiers = [
+  "Development Status :: 4 - Beta",
+  "Intended Audience :: Developers",
+  "Intended Audience :: Financial and Insurance Industry",
+  "License :: OSI Approved :: MIT License",
+  "Programming Language :: Python :: 3",
+  "Topic :: Office/Business :: Financial :: Investment",
+]
+dependencies = []
+
+[project.urls]
+Homepage = "https://r2rlabs.com"
+Documentation = "https://r2rlabs.com/mcp/"
+Source = "https://github.com/R2Rlabs/reins"
+Issues = "https://github.com/R2Rlabs/reins/issues"
+
+[tool.hatch.build.targets.wheel]
+packages = ["reins"]

reins_client-0.1.0/reins/__init__.py

@@ -0,0 +1,289 @@
+"""Reins from Python: risk limits and an audit log around a trading agent.
+
+Most Hyperliquid bots are Python, and Reins speaks MCP or HTTP. This wraps the
+HTTP side so a bot does not hand-roll requests:
+
+    from reins import Reins, Refused
+
+    reins = Reins.from_env()                  # REINS_URL, REINS_HTTP_TOKEN
+    book = reins.book("BTC")
+    entry = book["bids"][0]["price"]
+    stop = entry * 0.99
+
+    try:
+        order = reins.place_order(
+            symbol="BTC",
+            side="buy",
+            size_usd=Reins.size_for_risk(entry, stop, risk_usd=25),
+            price=entry,
+            stop_loss=stop,
+            reason="range low held on the hourly",
+        )
+    except Refused as refusal:
+        print(refusal.code, refusal.reason)   # e.g. TRADE_RISK_TOO_LARGE
+
+A refusal is not a failure of the call: it is Reins doing its job, and it is
+raised as `Refused` with the code so a bot can branch on it. Everything the
+agent does, including what was refused, lands in the decision log.
+
+No dependencies: stdlib only, so this can be vendored as a single file.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import re
+import urllib.error
+import urllib.parse
+import urllib.request
+from typing import Any, Literal
+
+__all__ = [
+    "Reins",
+    "ReinsError",
+    "Refused",
+    "BadRequest",
+    "Unauthorized",
+    "ServerError",
+    "__version__",
+]
+
+__version__ = "0.1.0"
+
+Side = Literal["buy", "sell"]
+TimeInForce = Literal["Gtc", "Ioc", "Alo"]
+Interval = Literal["1m", "5m", "15m", "1h", "4h", "1d"]
+
+# Refusals arrive as "BLOCKED (CODE): reason".
+_BLOCKED = re.compile(r"^BLOCKED \(([A-Z_]+)\): (.*)$", re.S)
+
+
+class ReinsError(Exception):
+    """Anything that stopped a call from succeeding."""
+
+    def __init__(self, message: str, *, status: int | None = None) -> None:
+        super().__init__(message)
+        self.message = message
+        self.status = status
+
+
+class Refused(ReinsError):
+    """A risk limit said no. The order never reached the exchange.
+
+    `code` is one of POSITION_TOO_LARGE, LEVERAGE_TOO_HIGH, HALTED_DAILY_LOSS,
+    TRADE_RISK_TOO_LARGE, NO_STOP_LOSS, SYMBOL_NOT_ALLOWED, RATE_LIMITED or
+    INVALID_ORDER, and `reason` is the sentence explaining it.
+    """
+
+    def __init__(self, code: str, reason: str) -> None:
+        super().__init__(f"{code}: {reason}", status=400)
+        self.code = code
+        self.reason = reason
+
+
+class BadRequest(ReinsError):
+    """The request itself was wrong — a missing field, an unknown market."""
+
+
+class Unauthorized(ReinsError):
+    """No token, or the wrong one."""
+
+
+class ServerError(ReinsError):
+    """Reins or the exchange failed. Nothing can be assumed about the order."""
+
+
+class Reins:
+    """A client for one `reins http` server.
+
+    The server serialises requests, so two orders cannot race the same limit;
+    this class holds no state of its own beyond the address and token.
+    """
+
+    def __init__(self, base_url: str, token: str = "", *, timeout: float = 30.0) -> None:
+        self.base_url = base_url.rstrip("/")
+        self.token = token
+        self.timeout = timeout
+
+    @classmethod
+    def from_env(cls, **kwargs: Any) -> "Reins":
+        """Read the address and token from the environment.
+
+        REINS_URL (default http://127.0.0.1:8787) and REINS_HTTP_TOKEN, which
+        is what `reins http` prints when it starts.
+        """
+        return cls(
+            os.environ.get("REINS_URL", "http://127.0.0.1:8787"),
+            os.environ.get("REINS_HTTP_TOKEN", ""),
+            **kwargs,
+        )
+
+    # --- what the agent may know -------------------------------------------
+
+    def health(self) -> dict[str, Any]:
+        """Whether this server is paper or live, before anything is sent."""
+        return self._get("/health", authenticated=False)
+
+    def limits(self) -> dict[str, Any]:
+        """The limits in force, so a bot can size inside them rather than guess."""
+        return self._get("/limits")
+
+    def positions(self) -> dict[str, Any]:
+        """Open positions, equity, and the day's realised loss so far."""
+        return self._get("/positions")
+
+    def book(self, symbol: str, *, depth: int | None = None) -> dict[str, Any]:
+        params: dict[str, Any] = {"symbol": symbol}
+        if depth is not None:
+            params["depth"] = depth
+        return self._get("/book", params)
+
+    def candles(
+        self, symbol: str, *, interval: Interval | None = None, count: int | None = None
+    ) -> dict[str, Any]:
+        params: dict[str, Any] = {"symbol": symbol}
+        if interval is not None:
+            params["interval"] = interval
+        if count is not None:
+            params["count"] = count
+        return self._get("/candles", params)
+
+    def decisions(self, *, limit: int | None = None) -> dict[str, Any]:
+        """The log: what was tried, what was refused, what the exchange did."""
+        params: dict[str, Any] = {}
+        if limit is not None:
+            params["limit"] = limit
+        return self._get("/decisions", params)
+
+    # --- what the agent may do ---------------------------------------------
+
+    def place_order(
+        self,
+        *,
+        symbol: str,
+        side: Side,
+        size_usd: float,
+        reason: str,
+        price: float | None = None,
+        stop_loss: float | None = None,
+        reduce_only: bool | None = None,
+        tif: TimeInForce | None = None,
+    ) -> dict[str, Any]:
+        """Send an order, or raise `Refused` if a limit stops it.
+
+        `reason` is required, as it is for the agent: an order nobody explained
+        is the one you cannot account for afterwards. Pass `stop_loss` unless
+        the server was started without requiring one — it is attached to the
+        order, so a resting entry carries its stop from the moment it fills.
+        """
+        payload: dict[str, Any] = {
+            "symbol": symbol,
+            "side": side,
+            "sizeUsd": size_usd,
+            "reason": reason,
+        }
+        if price is not None:
+            payload["price"] = price
+        if stop_loss is not None:
+            payload["stopLoss"] = stop_loss
+        if reduce_only is not None:
+            payload["reduceOnly"] = reduce_only
+        if tif is not None:
+            payload["tif"] = tif
+        return self._post("/orders", payload)
+
+    def set_stop_loss(self, *, symbol: str, trigger_price: float, reason: str) -> dict[str, Any]:
+        """Put a stop on an open position, or move the one that is there."""
+        return self._post(
+            "/stops", {"symbol": symbol, "triggerPrice": trigger_price, "reason": reason}
+        )
+
+    def cancel_order(
+        self, *, symbol: str, order_id: int, reason: str | None = None
+    ) -> dict[str, Any]:
+        payload: dict[str, Any] = {"symbol": symbol, "orderId": order_id}
+        if reason is not None:
+            payload["reason"] = reason
+        return self._post("/cancel", payload)
+
+    def close_position(self, *, symbol: str, reason: str) -> dict[str, Any]:
+        """Close the whole position at market, whatever its exact size is."""
+        return self._post("/close", {"symbol": symbol, "reason": reason})
+
+    # --- sizing -------------------------------------------------------------
+
+    @staticmethod
+    def size_for_risk(entry: float, stop: float, risk_usd: float) -> float:
+        """The position size whose stop-out costs about `risk_usd`.
+
+        Reins refuses an order whose stop-out would cost more than the per-trade
+        limit (TRADE_RISK_TOO_LARGE), and this is the arithmetic it checks:
+        size = risk / (distance to the stop, as a fraction of entry). Sizing
+        this way is what makes a wider stop mean a smaller position rather than
+        a bigger loss.
+        """
+        if entry <= 0:
+            raise ValueError("entry must be positive")
+        if stop <= 0:
+            raise ValueError("stop must be positive")
+        if risk_usd <= 0:
+            raise ValueError("risk_usd must be positive")
+        distance = abs(entry - stop) / entry
+        if distance == 0:
+            raise ValueError("stop must differ from entry")
+        return risk_usd / distance
+
+    # --- plumbing -----------------------------------------------------------
+
+    def _get(
+        self, path: str, params: dict[str, Any] | None = None, *, authenticated: bool = True
+    ) -> dict[str, Any]:
+        url = self.base_url + path
+        if params:
+            url += "?" + urllib.parse.urlencode(params)
+        return self._send(url, None, authenticated)
+
+    def _post(self, path: str, payload: dict[str, Any]) -> dict[str, Any]:
+        return self._send(self.base_url + path, json.dumps(payload).encode(), True)
+
+    def _send(self, url: str, data: bytes | None, authenticated: bool) -> dict[str, Any]:
+        headers = {"Accept": "application/json"}
+        if data is not None:
+            headers["Content-Type"] = "application/json"
+        if authenticated and self.token:
+            headers["Authorization"] = f"Bearer {self.token}"
+
+        request = urllib.request.Request(
+            url, data=data, headers=headers, method="POST" if data is not None else "GET"
+        )
+        try:
+            with urllib.request.urlopen(request, timeout=self.timeout) as response:
+                return self._decode(response.read())
+        except urllib.error.HTTPError as error:
+            raise self._error(error.code, error.read()) from None
+        except urllib.error.URLError as error:
+            raise ReinsError(f"could not reach Reins at {self.base_url}: {error.reason}") from None
+
+    @staticmethod
+    def _decode(raw: bytes) -> dict[str, Any]:
+        text = raw.decode("utf-8", "replace")
+        if not text:
+            return {}
+        try:
+            parsed = json.loads(text)
+        except json.JSONDecodeError:
+            return {"result": text}
+        return parsed if isinstance(parsed, dict) else {"result": parsed}
+
+    @classmethod
+    def _error(cls, status: int, raw: bytes) -> ReinsError:
+        message = str(cls._decode(raw).get("error") or raw.decode("utf-8", "replace") or "")
+        if status == 401:
+            return Unauthorized(message or "no token", status=401)
+        if status == 400:
+            blocked = _BLOCKED.match(message)
+            if blocked:
+                return Refused(blocked.group(1), blocked.group(2).strip())
+            return BadRequest(message, status=400)
+        return ServerError(message or f"HTTP {status}", status=status)

reins_client-0.1.0/tests/e2e.py

@@ -0,0 +1,112 @@
+"""Drives a real `reins http` server through the client, end to end.
+
+Not part of the unit suite: it needs a server and the exchange's prices.
+
+    node dist/bin/cli.js http --port 8799     # paper mode
+    REINS_URL=http://127.0.0.1:8799 REINS_HTTP_TOKEN=... python tests/e2e.py
+"""
+
+from __future__ import annotations
+
+
+
+import sys
+from pathlib import Path
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from reins import Refused, Reins  # noqa: E402
+
+
+def main() -> int:
+    reins = Reins.from_env()
+
+    health = reins.health()
+    print(f"health        {health['mode']} on {health.get('network')}, {len(health['routes'])} routes")
+    if health["mode"] != "paper":
+        print("refusing to run against a live server")
+        return 1
+
+    limits = reins.limits()
+    print(f"limits        {limits}")
+
+    positions = reins.positions()
+    print(
+        f"positions     equity ${positions['accountValueUsd']:,}, "
+        f"{len(positions['positionsUsd'])} open, "
+        f"{len(positions['unprotected'])} without a stop"
+    )
+
+    book = reins.book("BTC", depth=3)
+    best_bid = book["bestBid"]
+    print(f"book          BTC {best_bid} / {book['bestAsk']}, spread {book['spread']}")
+
+    candles = reins.candles("BTC", interval="1h", count=5)
+    print(f"candles       {len(candles.get('candles', []))} hourly")
+
+    # An order sized so its stop-out costs about $20, inside the $50 per-trade cap.
+    entry = round(best_bid * 0.995, 1)
+    stop = round(entry * 0.99, 1)
+    size = Reins.size_for_risk(entry, stop, risk_usd=20)
+    order = reins.place_order(
+        symbol="BTC",
+        side="buy",
+        size_usd=size,
+        price=entry,
+        stop_loss=stop,
+        reason="end-to-end check of the Python client",
+        tif="Alo",
+    )
+    print(f"order         ${size:,.0f} at {entry}, stop {stop} -> {order}")
+
+    # The same order with a stop far enough away to breach the per-trade cap.
+    try:
+        reins.place_order(
+            symbol="BTC",
+            side="buy",
+            size_usd=5000,
+            price=entry,
+            stop_loss=round(entry * 0.90, 1),
+            reason="deliberately too much risk",
+        )
+        print("refusal       NOT REFUSED — the per-trade cap did not hold")
+        return 1
+    except Refused as refusal:
+        print(f"refusal       {refusal.code}: {refusal.reason}")
+
+    # A market Reins was not told to allow.
+    try:
+        reins.place_order(symbol="SOL", side="buy", size_usd=100, reason="not on the allowlist")
+        print("allowlist     NOT REFUSED")
+        return 1
+    except Refused as refusal:
+        print(f"allowlist     {refusal.code}")
+
+    # No stop, on a server that requires one.
+    try:
+        reins.place_order(symbol="ETH", side="buy", size_usd=100, reason="no stop attached")
+        print("stop rule     NOT REFUSED")
+        return 1
+    except Refused as refusal:
+        print(f"stop rule     {refusal.code}")
+
+    # A resting order reports its exchange id as "oid".
+    order_id = order.get("oid")
+    if order_id:
+        cancelled = reins.cancel_order(
+            symbol="BTC", order_id=order_id, reason="end of the check"
+        )
+        print(f"cancel        {cancelled}")
+
+    log = reins.decisions(limit=10)
+    records = log.get("decisions") or []
+    refused = [r for r in records if r.get("risk", {}).get("allowed") is False]
+    codes = ", ".join(sorted({r["risk"]["code"] for r in refused}))
+    print(f"decision log  {len(records)} records, {len(refused)} refused ({codes})")
+
+    print("\nOK — every route answered and every limit held.")
+    return 0
+
+
+if __name__ == "__main__":
+    raise SystemExit(main())

reins_client-0.1.0/tests/test_client.py

@@ -0,0 +1,218 @@
+"""What the client puts on the wire, and what it does with what comes back.
+
+A stub server stands in for `reins http` so these run with no network and no
+exchange. The end-to-end check against the real server is in README.md under
+"Checked against the real thing".
+"""
+
+from __future__ import annotations
+
+import json
+import sys
+import threading
+import unittest
+from http.server import BaseHTTPRequestHandler, HTTPServer
+from pathlib import Path
+from urllib.parse import parse_qs, urlparse
+
+sys.path.insert(0, str(Path(__file__).resolve().parents[1]))
+
+from reins import BadRequest, Refused, Reins, ReinsError, ServerError, Unauthorized  # noqa: E402
+
+
+class Stub(BaseHTTPRequestHandler):
+    """Records the last request and replies with whatever the test queued."""
+
+    seen: dict = {}
+    reply: tuple[int, dict] = (200, {})
+
+    def _respond(self) -> None:
+        parsed = urlparse(self.path)
+        length = int(self.headers.get("Content-Length") or 0)
+        raw = self.rfile.read(length) if length else b""
+        Stub.seen = {
+            "method": self.command,
+            "path": parsed.path,
+            "query": {k: v[0] for k, v in parse_qs(parsed.query).items()},
+            "auth": self.headers.get("Authorization"),
+            "content_type": self.headers.get("Content-Type"),
+            "body": json.loads(raw) if raw else None,
+        }
+        status, body = Stub.reply
+        payload = json.dumps(body).encode()
+        self.send_response(status)
+        self.send_header("Content-Type", "application/json")
+        self.send_header("Content-Length", str(len(payload)))
+        self.end_headers()
+        self.wfile.write(payload)
+
+    do_GET = _respond
+    do_POST = _respond
+
+    def log_message(self, *args) -> None:  # keep the test output clean
+        pass
+
+
+class ClientTest(unittest.TestCase):
+    server: HTTPServer
+    thread: threading.Thread
+
+    @classmethod
+    def setUpClass(cls) -> None:
+        cls.server = HTTPServer(("127.0.0.1", 0), Stub)
+        cls.thread = threading.Thread(target=cls.server.serve_forever, daemon=True)
+        cls.thread.start()
+        host, port = cls.server.server_address
+        cls.base = f"http://{host}:{port}"
+
+    @classmethod
+    def tearDownClass(cls) -> None:
+        cls.server.shutdown()
+        cls.server.server_close()
+
+    def client(self, token: str = "tok") -> Reins:
+        return Reins(self.base, token, timeout=5)
+
+    def reply(self, status: int, body: dict) -> None:
+        Stub.reply = (status, body)
+
+    # --- requests -----------------------------------------------------------
+
+    def test_get_sends_bearer_token(self):
+        self.reply(200, {"limits": {}})
+        self.client().limits()
+        self.assertEqual(Stub.seen["method"], "GET")
+        self.assertEqual(Stub.seen["path"], "/limits")
+        self.assertEqual(Stub.seen["auth"], "Bearer tok")
+
+    def test_health_needs_no_token(self):
+        self.reply(200, {"ok": True, "mode": "paper"})
+        Reins(self.base, "", timeout=5).health()
+        self.assertIsNone(Stub.seen["auth"])
+
+    def test_optional_query_parameters_are_left_out(self):
+        self.reply(200, {})
+        self.client().book("BTC")
+        self.assertEqual(Stub.seen["query"], {"symbol": "BTC"})
+        self.client().book("BTC", depth=5)
+        self.assertEqual(Stub.seen["query"], {"symbol": "BTC", "depth": "5"})
+
+    def test_candles_passes_interval_and_count(self):
+        self.reply(200, {})
+        self.client().candles("ETH", interval="1h", count=50)
+        self.assertEqual(Stub.seen["query"], {"symbol": "ETH", "interval": "1h", "count": "50"})
+
+    def test_order_uses_the_camel_case_the_server_expects(self):
+        self.reply(200, {"orderId": 7})
+        self.client().place_order(
+            symbol="BTC",
+            side="buy",
+            size_usd=500,
+            reason="range low held",
+            price=60000,
+            stop_loss=59400,
+            tif="Alo",
+        )
+        self.assertEqual(Stub.seen["method"], "POST")
+        self.assertEqual(Stub.seen["path"], "/orders")
+        self.assertEqual(Stub.seen["content_type"], "application/json")
+        self.assertEqual(
+            Stub.seen["body"],
+            {
+                "symbol": "BTC",
+                "side": "buy",
+                "sizeUsd": 500,
+                "reason": "range low held",
+                "price": 60000,
+                "stopLoss": 59400,
+                "tif": "Alo",
+            },
+        )
+
+    def test_order_omits_what_was_not_given(self):
+        self.reply(200, {})
+        self.client().place_order(symbol="BTC", side="sell", size_usd=100, reason="why")
+        self.assertEqual(
+            set(Stub.seen["body"]), {"symbol", "side", "sizeUsd", "reason"}
+        )
+
+    def test_reduce_only_false_is_still_sent(self):
+        self.reply(200, {})
+        self.client().place_order(
+            symbol="BTC", side="sell", size_usd=100, reason="why", reduce_only=False
+        )
+        self.assertIs(Stub.seen["body"]["reduceOnly"], False)
+
+    def test_stop_and_cancel_and_close(self):
+        self.reply(200, {})
+        self.client().set_stop_loss(symbol="BTC", trigger_price=59000, reason="under the low")
+        self.assertEqual(
+            Stub.seen["body"], {"symbol": "BTC", "triggerPrice": 59000, "reason": "under the low"}
+        )
+        self.client().cancel_order(symbol="BTC", order_id=42)
+        self.assertEqual(Stub.seen["body"], {"symbol": "BTC", "orderId": 42})
+        self.client().close_position(symbol="BTC", reason="done")
+        self.assertEqual(Stub.seen["path"], "/close")
+
+    # --- answers ------------------------------------------------------------
+
+    def test_refusal_becomes_refused_with_its_code(self):
+        self.reply(400, {"error": "BLOCKED (TRADE_RISK_TOO_LARGE): Stopping out would lose $120.00."})
+        with self.assertRaises(Refused) as caught:
+            self.client().place_order(symbol="BTC", side="buy", size_usd=9e9, reason="too big")
+        self.assertEqual(caught.exception.code, "TRADE_RISK_TOO_LARGE")
+        self.assertEqual(caught.exception.reason, "Stopping out would lose $120.00.")
+        self.assertIsInstance(caught.exception, ReinsError)
+
+    def test_a_plain_400_is_not_a_refusal(self):
+        self.reply(400, {"error": '"symbol" is required.'})
+        with self.assertRaises(BadRequest):
+            self.client().close_position(symbol="", reason="x")
+
+    def test_401_is_unauthorized(self):
+        self.reply(401, {"error": "Send the token as: Authorization: Bearer <token>."})
+        with self.assertRaises(Unauthorized):
+            self.client().positions()
+
+    def test_500_is_a_server_error(self):
+        self.reply(500, {"error": "exchange unreachable"})
+        with self.assertRaises(ServerError) as caught:
+            self.client().positions()
+        self.assertEqual(caught.exception.status, 500)
+
+    def test_unreachable_server_says_so(self):
+        with self.assertRaises(ReinsError) as caught:
+            Reins("http://127.0.0.1:9", "tok", timeout=2).limits()
+        self.assertIn("could not reach Reins", str(caught.exception))
+
+    def test_non_json_body_is_not_an_exception(self):
+        Stub.reply = (200, {})
+        self.assertEqual(self.client().limits(), {})
+
+    # --- sizing -------------------------------------------------------------
+
+    def test_size_for_risk_matches_the_engine(self):
+        # 1% away, $25 at risk -> $2,500 of notional.
+        self.assertAlmostEqual(Reins.size_for_risk(100, 99, 25), 2500)
+        # A wider stop means a smaller position, not a bigger loss.
+        self.assertAlmostEqual(Reins.size_for_risk(100, 98, 25), 1250)
+        # Direction does not matter.
+        self.assertAlmostEqual(Reins.size_for_risk(100, 101, 25), 2500)
+
+    def test_size_for_risk_rejects_nonsense(self):
+        for args in [(0, 99, 25), (100, 0, 25), (100, 99, 0), (100, 100, 25)]:
+            with self.assertRaises(ValueError):
+                Reins.size_for_risk(*args)
+
+    def test_from_env(self):
+        import os
+
+        os.environ["REINS_URL"] = "http://example.test:1234/"
+        os.environ["REINS_HTTP_TOKEN"] = "abc"
+        client = Reins.from_env()
+        self.assertEqual(client.base_url, "http://example.test:1234")
+        self.assertEqual(client.token, "abc")
+
+
+if __name__ == "__main__":
+    unittest.main()