borro-live 0.1.0__py3-none-any.whl

borro_live/__init__.py

@@ -0,0 +1,16 @@
+"""borro-live: send a trading agent's decisions to Borro on Robinhood Chain.
+
+    from borro_live import Broker
+    broker = Broker.from_env()          # dry run unless BORRO_LIVE=1
+    broker.buy("NVDA", 5)               # 5 USDG
+
+Adapters: ``borro_live.tradingagents`` and ``borro_live.ai_hedge_fund``.
+"""
+
+from .broker import BorroLiveError, Broker, CapExceeded, Result, SimulationFailed, UnlistedTicker, Unsafe
+from .chain import Chain, ChainError
+from .mcp import McpClient, McpError, ToolRefused
+
+__version__ = "0.1.0"
+__all__ = ["Broker", "Result", "McpClient", "Chain", "BorroLiveError", "UnlistedTicker", "CapExceeded", "SimulationFailed", "Unsafe",
+           "ChainError", "McpError", "ToolRefused"]

borro_live/__main__.py

@@ -0,0 +1,56 @@
+"""borro-live on the command line: one order, or the wallet's positions, printed as JSON.
+
+    borro-live tickers
+    borro-live positions
+    borro-live buy NVDA 5            a dry run: Borro's simulation, nothing sent
+    borro-live buy NVDA 5 --live     sends, and only with BORRO_LIVE=1 in the environment as well
+    borro-live sell NVDA [percent] | short NVDA 5 | cover NVDA | lend USDG 5
+"""
+
+from __future__ import annotations
+
+import argparse
+import json
+import sys
+
+from .broker import BorroLiveError, Broker
+from .chain import ChainError
+from .mcp import McpClient, McpError
+
+
+def main(argv: list[str] | None = None) -> int:
+    ap = argparse.ArgumentParser(prog="borro-live", description="One order on Borro, dry run unless --live and BORRO_LIVE=1.")
+    ap.add_argument("action", choices=["tickers", "positions", "buy", "sell", "short", "cover", "lend"])
+    ap.add_argument("symbol", nargs="?")
+    ap.add_argument("amount", nargs="?", type=float, help="USDG for buy and short; percent for sell; units for lend")
+    ap.add_argument("--live", action="store_true", help="send for real (also needs BORRO_LIVE=1)")
+    ap.add_argument("--wallet", help="an address, for dry runs without a key")
+    ap.add_argument("--builder-code")
+    ap.add_argument("--max-order", type=float)
+    ap.add_argument("--max-day", type=float)
+    a = ap.parse_args(argv)
+    try:
+        if a.action == "tickers":   # a public read: no key and no wallet needed
+            print(json.dumps([s["symbol"] for s in McpClient().call("markets")["stocks"]], indent=1))
+            return 0
+        b = Broker(live=a.live, wallet=a.wallet, builder_code=a.builder_code, max_order_usdg=a.max_order, max_day_usdg=a.max_day)
+        if a.action == "positions":
+            out = {k: v for k, v in b.positions().items() if k != "raw"}
+        else:
+            if not a.symbol or (a.amount is None and a.action in ("buy", "short", "lend")):
+                ap.error(f"{a.action} needs a symbol" + (" and an amount" if a.action in ("buy", "short", "lend") else ""))
+            if a.action == "sell":
+                out = b.sell(a.symbol, a.amount if a.amount is not None else 100).to_dict()
+            elif a.action == "cover":
+                out = b.cover(a.symbol).to_dict()
+            else:
+                out = getattr(b, a.action)(a.symbol, a.amount).to_dict()
+    except (BorroLiveError, McpError, ChainError, ValueError) as e:
+        print(json.dumps({"ok": False, "error": str(e)}))
+        return 1
+    print(json.dumps(out, indent=1))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

borro_live/ai_hedge_fund.py

@@ -0,0 +1,164 @@
+"""ai-hedge-fund on Borro.
+
+Two shapes, because the project has two:
+
+* The portfolio manager's decisions, ``{ticker: {"action": "buy" | "sell" | "short" | "cover" | "hold",
+  "quantity": shares, ...}}`` (what ``run_hedge_fund`` returns under ``"decisions"``): ``execute_decisions``.
+* The v2 engine's ``Broker`` protocol (``positions()``, ``cash()``, ``place_order(order)`` with buy and sell orders
+  on signed share counts): ``BorroBroker``.
+
+ai-hedge-fund itself is never imported unless it is installed: plain dicts and objects work.
+"""
+
+from __future__ import annotations
+
+from dataclasses import dataclass
+
+from .broker import BorroLiveError, Broker, Result
+from .chain import ChainError
+from .mcp import McpError
+
+ACTIONS = ("buy", "sell", "short", "cover", "hold")
+
+
+def _get(obj, name, default=None):
+    return obj.get(name, default) if isinstance(obj, dict) else getattr(obj, name, default)
+
+
+def _long_shares(pos: dict, symbol: str) -> float:
+    if not any(p.get("symbol") == symbol for p in pos["longs"]):
+        return 0.0
+    row = next((s for s in pos["stocks"] if s.get("symbol") == symbol), {})
+    return float((row.get("usdg_loan") or {}).get("posted_stock") or 0)
+
+
+def _short_shares(pos: dict, symbol: str) -> float:
+    return float(next((s.get("owed_stock") or 0 for s in pos["shorts"] if s.get("symbol") == symbol), 0))
+
+
+def execute_decisions(broker: Broker, decisions, scale: float = 1.0) -> dict:
+    """Execute the portfolio manager's decisions, ticker by ticker.
+
+    ``decisions`` is the dict of decisions, the whole ``run_hedge_fund`` result, or the manager's output object.
+    ``scale`` multiplies every quantity (0.01 turns 10 shares into 0.1), since the model sizes for a paper
+    portfolio and the caps here are in USDG. Returns ``{ticker: Result}``; a ticker this kit or Borro refused maps
+    to the reason as a string, and a hold to None, so one refusal never stops the others.
+
+    buy     buy ``quantity`` shares' worth        sell    sell that share of the long
+    short   short ``quantity`` shares' worth      cover   close the short (Borro closes a short whole)
+    """
+    inner = _get(decisions, "decisions")
+    decisions = inner if inner is not None else decisions
+    if not isinstance(decisions, dict):
+        raise BorroLiveError("decisions must be a dict of ticker to {action, quantity}")
+    out: dict = {}
+    pos = None
+    for ticker, d in decisions.items():
+        symbol = str(ticker).strip().upper()
+        action = str(_get(d, "action", "hold")).strip().lower()
+        qty = float(_get(d, "quantity", 0) or 0) * scale
+        try:
+            if action not in ACTIONS:
+                raise BorroLiveError(f"unknown action {action}")
+            if action == "hold" or (qty <= 0 and action != "cover"):
+                out[symbol] = None
+            elif action == "buy":
+                out[symbol] = broker.buy(symbol, qty * broker.price(symbol))
+            elif action == "short":
+                out[symbol] = broker.short(symbol, qty * broker.price(symbol))
+            elif action == "cover":
+                out[symbol] = broker.cover(symbol)
+            else:
+                broker.price(symbol)
+                pos = pos or broker.positions()
+                held = _long_shares(pos, symbol)
+                if held <= 0:
+                    raise BorroLiveError(f"no long on {symbol} to sell")
+                out[symbol] = broker.sell(symbol, max(1.0, min(100.0, 100.0 * qty / held)))
+        except (BorroLiveError, McpError, ChainError) as e:
+            out[symbol] = f"refused: {e}"
+    return out
+
+
+@dataclass
+class _Position:
+    ticker: str
+    shares: int
+
+
+@dataclass
+class _Fill:
+    ticker: str
+    side: str
+    quantity: int
+    price: float
+
+
+def _models():
+    try:
+        from hedge_fund.brokers.models import Fill, Position  # the real ones when ai-hedge-fund is installed
+        return Position, Fill
+    except Exception:
+        return _Position, _Fill
+
+
+class DryRun(BorroLiveError):
+    """place_order on a broker that is not live: nothing was sent. ``result`` holds Borro's simulation."""
+
+    def __init__(self, result: Result):
+        super().__init__(f"dry run: {result.action} {result.symbol} was simulated ({'ok' if result.ok else 'it would fail'}) and not sent")
+        self.result = result
+
+
+class BorroBroker:
+    """ai-hedge-fund's v2 ``Broker`` protocol over a live ``borro_live.Broker``.
+
+    Orders there are whole shares on a signed book: a sell past zero is a short, a buy toward zero a cover. On Borro
+    a buy is a 1.01x long and its share count is what the swap gave, so ``positions()`` rounds to whole shares. An
+    order fills completely or raises: one that would cross zero, or cover part of a short, is refused (Borro closes
+    a short whole). A dry-run broker raises ``DryRun`` with the simulation, since nothing was filled.
+    """
+
+    def __init__(self, broker: Broker):
+        self.broker = broker
+        self.results: list[Result] = []
+
+    def positions(self) -> dict:
+        Position, _ = _models()
+        pos = self.broker.positions()
+        book = {}
+        for symbol in {p["symbol"] for p in pos["longs"]} | {p["symbol"] for p in pos["shorts"]}:
+            shares = round(_long_shares(pos, symbol) - _short_shares(pos, symbol))
+            if shares:
+                book[symbol] = Position(ticker=symbol, shares=shares)
+        return book
+
+    def cash(self) -> float:
+        return float(self.broker.positions()["usdg"] or 0)
+
+    def place_order(self, order):
+        _, Fill = _models()
+        symbol, side, qty, ref = str(_get(order, "ticker")).upper(), _get(order, "side"), int(_get(order, "quantity")), float(_get(order, "price"))
+        if side not in ("buy", "sell") or qty <= 0:
+            raise BorroLiveError("an order is buy or sell of at least one share")
+        pos = self.broker.positions()
+        long_, short_ = _long_shares(pos, symbol), _short_shares(pos, symbol)
+        price = self.broker.price(symbol)
+        if side == "buy" and short_ > 0:
+            if qty != round(short_):
+                raise BorroLiveError(f"Borro closes a short whole: buy {round(short_)} {symbol} to cover it, then buy more")
+            res = self.broker.cover(symbol)
+        elif side == "buy":
+            res = self.broker.buy(symbol, qty * price)
+        elif long_ > 0:
+            if qty > round(long_):
+                raise BorroLiveError(f"sell the {round(long_)} {symbol} held first, then short")
+            res = self.broker.sell(symbol, min(100.0, 100.0 * qty / long_))
+        else:
+            res = self.broker.short(symbol, qty * price)
+        self.results.append(res)
+        if not res.sent:
+            raise DryRun(res)
+        q = res.quote
+        filled = float(q["size_usdg"]) / float(q["stock"]) if q.get("size_usdg") and q.get("stock") else float(q.get("price_usd") or price or ref)
+        return Fill(ticker=symbol, side=side, quantity=qty, price=filled)

borro_live/broker.py

@@ -0,0 +1,403 @@
+"""The broker: buy, sell, short, cover, lend and positions on Borro, with the safety rules in one place.
+
+Nothing is sent unless the broker was made with ``live=True`` AND the environment has ``BORRO_LIVE=1``. Without
+both, every order is a dry run: it returns Borro's own simulation of each step and sends nothing.
+"""
+
+from __future__ import annotations
+
+import json
+import os
+import time
+from dataclasses import asdict, dataclass, field
+from decimal import ROUND_DOWN, Decimal
+from pathlib import Path
+
+from .chain import CHAIN_ID, Chain, ChainError, account_from_key, calldata
+from .mcp import BorroLiveError, McpClient, ToolRefused
+
+USDG = "0x5fc5360D0400a0Fd4f2af552ADD042D716F1d168"
+# BorroBuilders: deposits made through it with a registered code are credited to that code (Bookrunners).
+BORRO_BUILDERS = "0x082Ae609bdC7ccEec0C58B2361a21c49dc2aE291"
+APPROVE = "0x095ea7b3"
+
+DEFAULT_MAX_ORDER_USDG = 10.0
+DEFAULT_MAX_DAY_USDG = 25.0
+# buy() is a long at the lowest leverage that makes sense on Borro: the order's USDG plus 1% borrowed.
+DEFAULT_LEVERAGE = 1.01
+# short() deposits this much USDG for each USDG of stock sold, on top of the sale money Borro holds.
+DEFAULT_SHORT_DEPOSIT = 1.0
+
+
+class UnlistedTicker(BorroLiveError):
+    pass
+
+
+class CapExceeded(BorroLiveError):
+    pass
+
+
+class SimulationFailed(BorroLiveError):
+    pass
+
+
+class Unsafe(BorroLiveError):
+    """The prepared transactions are not what was asked for (wrong chain, wrong wallet, value, or an approval too big)."""
+
+
+@dataclass
+class Result:
+    """What one order did. ``sent`` is False for a dry run; ``ok`` is the simulation's verdict."""
+
+    action: str
+    symbol: str
+    usdg: float | None
+    live: bool
+    sent: bool
+    ok: bool
+    tool: str
+    quote: dict = field(default_factory=dict)
+    simulation: dict = field(default_factory=dict)
+    transactions: list = field(default_factory=list)
+    note: str | None = None
+
+    @property
+    def hashes(self) -> list[str]:
+        return [t["hash"] for t in self.transactions if t.get("hash")]
+
+    def to_dict(self) -> dict:
+        return asdict(self)
+
+
+def _dec(x, places: int) -> str:
+    """A decimal string in whole units, cut (never rounded up) to the token's places."""
+    d = Decimal(str(x)).quantize(Decimal(1).scaleb(-places), rounding=ROUND_DOWN)
+    return format(d.normalize(), "f") if d else "0"
+
+
+def _env_float(name: str, default: float) -> float:
+    raw = os.environ.get(name)
+    if raw is None or raw.strip() == "":
+        return default
+    try:
+        v = float(raw)
+    except ValueError:
+        raise BorroLiveError(f"{name} must be a number of USDG") from None
+    if not v > 0:
+        raise BorroLiveError(f"{name} must be more than 0")
+    return v
+
+
+class Broker:
+    """One wallet's desk on Borro.
+
+    key             the agent's private key (default: the BORRO_AGENT_KEY environment variable). Never printed,
+                    logged or stored. Without a key, give ``wallet`` (an address) for dry runs only.
+    rpc_url         your own Robinhood Chain RPC (default: BORRO_RPC_URL). There is no built-in one.
+    live            True to send. It also needs BORRO_LIVE=1 in the environment, or the broker refuses to start.
+    max_order_usdg  the most one order may be worth (default 10, or BORRO_MAX_ORDER_USDG).
+    max_day_usdg    the most all orders of one UTC day may be worth (default 25, or BORRO_MAX_DAY_USDG).
+    builder_code    a Bookrunner code. When set, the wallet is bound to it once and lends go through BorroBuilders,
+                    so the code's owner earns a share of Borro's fees. No default.
+    """
+
+    def __init__(self, key: str | None = None, rpc_url: str | None = None, *, live: bool = False, wallet: str | None = None,
+                 max_order_usdg: float | None = None, max_day_usdg: float | None = None, builder_code: str | None = None,
+                 leverage: float = DEFAULT_LEVERAGE, short_deposit: float = DEFAULT_SHORT_DEPOSIT,
+                 mcp: McpClient | None = None, chain: Chain | None = None, state_path: str | os.PathLike | None = None):
+        key = key or os.environ.get("BORRO_AGENT_KEY")
+        self._account = account_from_key(key) if key else None
+        wallet = wallet or os.environ.get("BORRO_WALLET") or None
+        if self._account is None and not wallet:
+            raise BorroLiveError("set BORRO_AGENT_KEY (the agent's own key), or for a dry run without a key set BORRO_WALLET (or give wallet=) to an address")
+        self.wallet = self._account.address if self._account else wallet
+        rpc_url = rpc_url or os.environ.get("BORRO_RPC_URL")
+        self.chain = chain or (Chain(rpc_url) if rpc_url else None)
+        if live:
+            if os.environ.get("BORRO_LIVE") != "1":
+                raise BorroLiveError("live=True also needs BORRO_LIVE=1 in the environment; without both, orders are dry runs")
+            if self._account is None:
+                raise BorroLiveError("live orders need the agent's key (BORRO_AGENT_KEY)")
+            if self.chain is None:
+                raise BorroLiveError("live orders need your own Robinhood Chain RPC (BORRO_RPC_URL)")
+        self.live = bool(live)
+        self.max_order_usdg = float(max_order_usdg) if max_order_usdg is not None else _env_float("BORRO_MAX_ORDER_USDG", DEFAULT_MAX_ORDER_USDG)
+        self.max_day_usdg = float(max_day_usdg) if max_day_usdg is not None else _env_float("BORRO_MAX_DAY_USDG", DEFAULT_MAX_DAY_USDG)
+        if not (self.max_order_usdg > 0 and self.max_day_usdg > 0):
+            raise BorroLiveError("the caps must be more than 0")
+        self.builder_code = (builder_code or "").strip().lower() or None
+        if self.builder_code and not (self.builder_code.isascii() and len(self.builder_code) <= 31 and self.builder_code.replace("-", "").replace("_", "").isalnum()):
+            raise BorroLiveError("a builder code is up to 31 letters, digits, - or _")
+        if not (1 < leverage <= 1.35):
+            raise BorroLiveError("leverage for buy() goes from just over 1 to 1.35")
+        if not short_deposit >= 0.5:
+            raise BorroLiveError("short_deposit must be at least 0.5 (USDG deposited for each USDG shorted)")
+        self.leverage = leverage
+        self.short_deposit = short_deposit
+        self.mcp = mcp or McpClient()
+        self._state_path = Path(state_path or os.environ.get("BORRO_LIVE_STATE") or Path.home() / ".borro-live" / "state.json")
+        self._markets: tuple[float, dict] | None = None
+
+    def __repr__(self) -> str:
+        return f"Broker(wallet={self.wallet}, live={self.live}, max_order_usdg={self.max_order_usdg}, max_day_usdg={self.max_day_usdg})"
+
+    @classmethod
+    def from_env(cls, **kw) -> "Broker":
+        """BORRO_AGENT_KEY (or BORRO_WALLET, an address, for a dry run without a key), BORRO_RPC_URL and BORRO_LIVE; live when BORRO_LIVE=1 unless live= says otherwise."""
+        kw.setdefault("live", os.environ.get("BORRO_LIVE") == "1")
+        kw.setdefault("builder_code", os.environ.get("BORRO_BUILDER_CODE") or None)
+        return cls(**kw)
+
+    # ---- reads -------------------------------------------------------------------------------------------------
+
+    def markets(self) -> dict:
+        """Borro's shelf, kept for a minute."""
+        if self._markets is None or time.time() - self._markets[0] > 60:
+            self._markets = (time.time(), self.mcp.call("markets"))
+        return self._markets[1]
+
+    def tickers(self) -> list[str]:
+        return [s["symbol"] for s in self.markets()["stocks"]]
+
+    def _stock(self, symbol: str) -> dict:
+        sym = str(symbol or "").strip().upper()
+        for s in self.markets()["stocks"]:
+            if s["symbol"] == sym:
+                return s
+        raise UnlistedTicker(f"{sym or 'that ticker'} is not on Borro; listed: {', '.join(self.tickers())}")
+
+    def price(self, symbol: str) -> float:
+        return float(self._stock(symbol)["price_usd"])
+
+    def positions(self) -> dict:
+        """What the wallet has on Borro, from the ``position`` tool: longs, shorts, what is lent, and its balances."""
+        p = self.mcp.call("position", {"wallet": self.wallet})
+        stocks = p.get("stocks") or []
+        return {
+            "wallet": p.get("wallet", self.wallet),
+            "eth": (p.get("wallet_balances") or {}).get("eth"),
+            "usdg": (p.get("wallet_balances") or {}).get("usdg"),
+            "longs": p.get("leveraged_longs") or [],
+            "shorts": [{"symbol": s["symbol"], **s["short"]} for s in stocks if s.get("short")],
+            "lent_usdg": (p.get("usdg_lent") or {}).get("usdg", 0),
+            "stocks": stocks,
+            "raw": p,
+        }
+
+    # ---- orders ------------------------------------------------------------------------------------------------
+
+    def buy(self, symbol: str, usdg: float) -> Result:
+        """Buy ``usdg`` worth of a stock token.
+
+        Borro's tools have no plain spot buy for USDG, so this is the nearest thing: a long at 1.01x (``open_long``).
+        The USDG buys the stock token, the token is lent (it earns lending fees) and posted, and 1% of the order is
+        borrowed against it. ``sell`` takes it back to USDG.
+        """
+        s = self._stock(symbol)
+        return self._order("buy", s["symbol"], usdg, "open_long", {"symbol": s["symbol"], "margin": _dec(usdg, 6), "leverage": self.leverage})
+
+    def sell(self, symbol: str, percent: float = 100) -> Result:
+        """Sell all or part of the long ``buy`` opened: the stock is sold, the small debt repaid, USDG comes back."""
+        s = self._stock(symbol)
+        if not (1 <= percent <= 100):
+            raise BorroLiveError("percent must be from 1 to 100")
+        return self._order("sell", s["symbol"], None, "close_long", {"symbol": s["symbol"], "percent": round(float(percent), 2)})
+
+    def short(self, symbol: str, usdg: float) -> Result:
+        """Short ``usdg`` worth of a stock: borrow it, sell it, hold the money plus a USDG deposit (``open_short``).
+
+        A short can be liquidated: if the stock rises far enough it is closed for you at a loss. The deposit is
+        ``short_deposit`` USDG per USDG shorted (default 1), never under the least Borro asks.
+        """
+        s = self._stock(symbol)
+        self._check_caps(usdg)
+        amount = _dec(Decimal(str(usdg)) / Decimal(str(s["price_usd"])), 18)
+        deposit = float(usdg) * self.short_deposit
+        args = {"symbol": s["symbol"], "amount": amount, "deposit": _dec(deposit, 2)}
+        try:
+            least = float(self.mcp.call("open_short", {"wallet": self.wallet, **args})["quote"]["deposit_at_least_usdg"])
+        except ToolRefused:
+            least = 0.0  # the order below gets the refusal and reports it
+        if least * 1.1 > deposit:
+            args["deposit"] = _dec(least * 1.1, 2)
+        return self._order("short", s["symbol"], usdg, "open_short", args, usdg_out=float(args["deposit"]))
+
+    def cover(self, symbol: str) -> Result:
+        """Close the wallet's short on a stock, all of it (``close_short``): Borro has one short per stock."""
+        s = self._stock(symbol)
+        return self._order("cover", s["symbol"], None, "close_short", {"symbol": s["symbol"]})
+
+    def lend(self, asset: str, amount: float) -> Result:
+        """Lend USDG (it earns interest) or a stock token the wallet holds (it earns lending fees): ``supply``.
+
+        ``amount`` is in the asset's own units: USDG, or shares of the stock. With a builder code, the deposit goes
+        through BorroBuilders instead, so the code is credited.
+        """
+        a = str(asset or "").strip().upper()
+        if a == "USDG":
+            value, stock = float(amount), None
+        else:
+            stock = self._stock(a)
+            value = float(amount) * float(stock["price_usd"])
+        if self.builder_code:
+            return self._lend_with_code(a, stock, amount, value)
+        asked = _dec(amount, 6 if stock is None else 18)
+        out = self._order("lend", a, value, "supply", {"asset": a, "amount": asked}, usdg_out=value if stock is None else 0)
+        if Decimal(str(out.quote.get("amount", asked))) < Decimal(asked):
+            out.note = f"Borro cut this lend to the {out.quote['amount']} {a} the wallet holds"
+        return out
+
+    def buy_spot_with_eth(self, symbol: str, shares: float) -> Result:
+        """A plain spot buy, paid in the wallet's ETH (``buy_with_eth``): the stock token lands in the wallet.
+
+        No Borro tool sells a token held in the wallet back, so what this buys can be lent with ``lend`` or sold
+        elsewhere; ``sell`` only closes longs opened by ``buy``.
+        """
+        s = self._stock(symbol)
+        return self._order("buy_spot_with_eth", s["symbol"], float(shares) * float(s["price_usd"]), "buy_with_eth",
+                           {"want": s["symbol"], "amount": _dec(shares, 18)}, pays_eth=True)
+
+    # ---- the one path every order takes ------------------------------------------------------------------------
+
+    def _order(self, action: str, symbol: str, usdg: float | None, tool: str, args: dict, *, usdg_out: float | None = None, pays_eth: bool = False) -> Result:
+        if usdg is not None:
+            self._check_caps(usdg)
+        note = self._bind() if usdg is not None and self.builder_code else None
+        prep = self.mcp.call(tool, {"wallet": self.wallet, **args})
+        if prep.get("live") is False:
+            raise BorroLiveError(prep.get("note") or f"{tool} is not live on Borro")
+        max_wei = int(Decimal(str((prep.get("quote") or {}).get("eth_at_most", "0"))).scaleb(18)) if pays_eth else 0
+        self._check_prepared(prep, usdg if usdg_out is None else usdg_out, max_wei)
+        return self._finish(action, symbol, usdg, tool, prep.get("quote") or {k: prep[k] for k in ("asset", "amount", "mode") if k in prep},
+                            prep.get("simulation") or {}, prep["transactions"], note)
+
+    def _finish(self, action, symbol, usdg, tool, quote, simulation, txs, note) -> Result:
+        steps = simulation.get("steps") or []
+        ok = simulation.get("ok") is True and len(steps) == len(txs) and all(s.get("ok") is True for s in steps)
+        out = Result(action=action, symbol=symbol, usdg=usdg, live=self.live, sent=False, ok=ok, tool=tool, quote=quote, simulation=simulation, note=note,
+                     transactions=[{"step": t.get("step", i + 1), "kind": t.get("kind"), "description": t.get("description"), "to": t["to"]} for i, t in enumerate(txs)])
+        if not self.live:
+            return out
+        if not ok:
+            why = "; ".join(f"step {s.get('step')}: {s.get('error', 'failed')}" for s in steps if s.get("ok") is not True) or simulation.get("error") or "no passing simulation"
+            raise SimulationFailed(f"{action} {symbol}: the simulation failed, nothing was sent ({why})")
+        if usdg is not None:
+            self._spend(usdg)
+        for row, t in zip(out.transactions, txs):
+            row.update(self.chain.send(self._account, t))
+        out.sent = True
+        return out
+
+    def _check_prepared(self, prep: dict, usdg_out: float | None, max_wei: int) -> None:
+        txs = prep.get("transactions")
+        if not isinstance(txs, list) or not txs:
+            raise Unsafe("the tool returned no transactions")
+        if prep.get("chainId") != CHAIN_ID or str(prep.get("from", "")).lower() != self.wallet.lower():
+            raise Unsafe("the transactions are not for this wallet on Robinhood Chain")
+        for t in txs:
+            if t.get("chainId") != CHAIN_ID or not str(t.get("to", "")).startswith("0x") or not str(t.get("data", "")).startswith("0x"):
+                raise Unsafe("a transaction is malformed or for another chain")
+            if int(t.get("value", 0)) > max_wei:
+                raise Unsafe("a transaction sends more ETH than this order's quote")
+            # A USDG approval may never be for more than the order itself (a little over, for rounding).
+            if usdg_out is not None and t["to"].lower() == USDG.lower() and t["data"].startswith(APPROVE):
+                if int(t["data"][74:138], 16) > int(usdg_out * 1.02 * 1e6) + 10_000:
+                    raise Unsafe("a USDG approval is for more than this order")
+
+    # ---- caps --------------------------------------------------------------------------------------------------
+
+    def _state(self) -> dict:
+        try:
+            return json.loads(self._state_path.read_text())
+        except (OSError, ValueError):
+            return {}
+
+    def _save(self, state: dict) -> None:
+        self._state_path.parent.mkdir(parents=True, exist_ok=True)
+        tmp = self._state_path.with_suffix(".tmp")
+        tmp.write_text(json.dumps(state, indent=1))
+        tmp.replace(self._state_path)
+
+    def spent_today(self) -> float:
+        day = (self._state().get("days") or {}).get(self.wallet.lower()) or {}
+        return float(day.get("usdg", 0)) if day.get("day") == time.strftime("%Y-%m-%d", time.gmtime()) else 0.0
+
+    def _check_caps(self, usdg: float) -> None:
+        usdg = float(usdg)
+        if not usdg > 0:
+            raise BorroLiveError("the order size must be more than 0 USDG")
+        if usdg > self.max_order_usdg + 1e-9:
+            raise CapExceeded(f"{usdg:g} USDG is over the per-order cap of {self.max_order_usdg:g} (max_order_usdg)")
+        if self.spent_today() + usdg > self.max_day_usdg + 1e-9:
+            raise CapExceeded(f"{usdg:g} USDG would pass today's cap of {self.max_day_usdg:g} ({self.spent_today():g} already sent; max_day_usdg, UTC day)")
+
+    def _spend(self, usdg: float) -> None:
+        """Counted before the first transaction goes out, so a crash mid-order never frees room under the cap."""
+        state = self._state()
+        state.setdefault("days", {})[self.wallet.lower()] = {"day": time.strftime("%Y-%m-%d", time.gmtime()), "usdg": round(self.spent_today() + float(usdg), 6)}
+        self._save(state)
+
+    # ---- builder code ------------------------------------------------------------------------------------------
+
+    def _bind(self) -> str:
+        """Bind the wallet to the builder code, once: one EIP-712 signature through ``bind_builder``, no transaction."""
+        code, me = self.builder_code, self.wallet
+        state = self._state()
+        if (state.get("bound") or {}).get(me.lower()):
+            return f"credited to builder code {state['bound'][me.lower()]}"
+        first = self.mcp.call("bind_builder", {"wallet": me, "code": code})
+        if not first.get("bound"):
+            if not self.live:
+                return f"a live order would first bind this wallet to builder code {code} (one signature, no gas)"
+            td = first.get("typed_data") or {}
+            msg, dom = td.get("message") or {}, td.get("domain") or {}
+            # Sign only the one statement this is for, whatever the server sent.
+            if not (td.get("primaryType") == "BuilderBinding" and dom == {"name": "Borro Builders", "version": "1", "chainId": CHAIN_ID}
+                    and str(msg.get("account", "")).lower() == me.lower() and msg.get("code") == code and msg.get("chainId") == CHAIN_ID
+                    and msg.get("statement") == f"Credit my Borro borrowing to builder code {code}" and set(msg) == {"statement", "account", "code", "chainId", "timestamp"}):
+                raise Unsafe("the binding to sign is not the builder binding for this wallet and code")
+            sig = self._account.sign_typed_data(full_message=td).signature.hex()
+            first = self.mcp.call("bind_builder", {"wallet": me, "code": code, "timestamp": msg["timestamp"], "signature": sig if sig.startswith("0x") else "0x" + sig})
+        bound = ((first.get("binding") or {}).get("code") or code) if first.get("bound") else None
+        if not bound:
+            raise BorroLiveError(f"the wallet could not be bound to builder code {code}")
+        state = self._state()
+        state.setdefault("bound", {})[me.lower()] = bound
+        self._save(state)
+        return f"credited to builder code {bound}" + ("" if bound == code else f" (the wallet was bound to it first; {code} is not credited)")
+
+    def _lend_with_code(self, asset: str, stock: dict | None, amount: float, value: float) -> Result:
+        """A lend through BorroBuilders.deposit(vault, assets, code, minShares): the wallet keeps the vault shares."""
+        if self.chain is None:
+            raise BorroLiveError("lending with a builder code reads the chain: set BORRO_RPC_URL")
+        self._check_caps(value)
+        token = USDG if stock is None else stock["contracts"]["token"]
+        vault = self.markets()["usdg"]["vault"] if stock is None else stock["contracts"]["vault"]
+        units = int(Decimal(_dec(amount, 6 if stock is None else 18)).scaleb(6 if stock is None else 18))
+        code32 = self.builder_code.encode().ljust(32, b"\0")
+        c, me = self.chain, self.wallet
+        if int.from_bytes(c.call(BORRO_BUILDERS, calldata("builders(bytes32)", ["bytes32"], [code32]))[-20:], "big") == 0:
+            raise BorroLiveError(f"no one has registered the builder code {self.builder_code}")
+        if not c.read(BORRO_BUILDERS, "vaults(address)", ["address"], [vault], ["bool"])[0]:
+            out = self._order("lend", asset, value, "supply", {"asset": asset, "amount": _dec(amount, 6 if stock is None else 18)}, usdg_out=value if stock is None else 0)
+            out.note = f"BorroBuilders does not list the {asset} vault yet, so this lend went straight to the vault and is not credited to {self.builder_code}"
+            return out
+        if c.read(token, "balanceOf(address)", ["address"], [me], ["uint256"])[0] < units:
+            raise BorroLiveError(f"the wallet holds less than {amount:g} {asset}")
+        note = self._bind()
+        txs = []
+        if c.read(token, "allowance(address,address)", ["address", "address"], [me, BORRO_BUILDERS], ["uint256"])[0] < units:
+            txs.append({"kind": "approve", "description": "Approve BorroBuilders to take exactly what this lends", "to": token,
+                        "data": calldata("approve(address,uint256)", ["address", "uint256"], [BORRO_BUILDERS, units]), "value": "0", "chainId": CHAIN_ID})
+        min_shares = c.read(vault, "previewDeposit(uint256)", ["uint256"], [units], ["uint256"])[0] * 995 // 1000
+        txs.append({"kind": "call", "description": f"Lend {amount:g} {asset} through BorroBuilders with the code {self.builder_code}", "to": BORRO_BUILDERS,
+                    "data": calldata("deposit(address,uint256,bytes32,uint256)", ["address", "uint256", "bytes32", "uint256"], [vault, units, code32, min_shares]), "value": "0", "chainId": CHAIN_ID})
+        for i, t in enumerate(txs):
+            t["step"] = i + 1
+        steps = c.simulate(me, txs)
+        sim = {"method": "eth_simulateV1", "ok": bool(steps) and all(s["ok"] for s in steps), "steps": steps or [],
+               **({} if steps is not None else {"error": "this RPC does not offer eth_simulateV1, so the steps could not be simulated together"})}
+        return self._finish("lend", asset, value, "BorroBuilders.deposit", {"asset": asset, "amount": _dec(amount, 6 if stock is None else 18), "builder_code": self.builder_code}, sim, txs, note)
+
+
+__all__ = ["Broker", "Result", "BorroLiveError", "UnlistedTicker", "CapExceeded", "SimulationFailed", "Unsafe", "ChainError", "BORRO_BUILDERS", "USDG"]

borro_live/chain.py

@@ -0,0 +1,127 @@
+"""The chain side: reads through the user's own RPC, and signing and sending with the agent's own key."""
+
+from __future__ import annotations
+
+import time
+
+from eth_abi import decode, encode
+from eth_account import Account
+from eth_utils import keccak, to_checksum_address
+
+from .mcp import McpError, http_post
+
+CHAIN_ID = 4663  # Robinhood Chain
+
+
+class ChainError(Exception):
+    """The RPC refused a call, or a transaction did not go through."""
+
+
+class Reverted(ChainError):
+    """A call or a gas estimate reverted: the transaction would fail, so it is not sent."""
+
+
+def selector(signature: str) -> bytes:
+    return keccak(text=signature)[:4]
+
+
+def calldata(signature: str, types: list[str], values: list) -> str:
+    return "0x" + (selector(signature) + encode(types, values)).hex()
+
+
+class Chain:
+    """JSON-RPC to the user's own Robinhood Chain endpoint. The address is kept private and never printed."""
+
+    def __init__(self, rpc_url: str, timeout: float = 60, transport=None):
+        self.__url = rpc_url
+        self.timeout = timeout
+        self._transport = transport or (lambda payload: http_post(self.__url, payload, self.timeout, "the RPC"))
+        self._id = 0
+        self._checked = False
+
+    def __repr__(self) -> str:
+        return "Chain(<your RPC>)"
+
+    def rpc(self, method: str, params: list | None = None):
+        self._id += 1
+        try:
+            res = self._transport({"jsonrpc": "2.0", "id": self._id, "method": method, "params": params or []})
+        except McpError as e:
+            raise ChainError(str(e)) from None
+        if "error" in res:
+            msg = str((res["error"] or {}).get("message", "error"))[:300]
+            raise (Reverted if "revert" in msg.lower() else ChainError)(f"{method}: {msg}")
+        return res.get("result")
+
+    def check_chain(self) -> None:
+        if not self._checked:
+            got = int(self.rpc("eth_chainId"), 16)
+            if got != CHAIN_ID:
+                raise ChainError(f"the RPC is on chain {got}, not Robinhood Chain ({CHAIN_ID})")
+            self._checked = True
+
+    def call(self, to: str, data: str, sender: str | None = None, value: int = 0) -> bytes:
+        tx = {"to": to, "data": data}
+        if sender:
+            tx["from"] = sender
+        if value:
+            tx["value"] = hex(value)
+        return bytes.fromhex(self.rpc("eth_call", [tx, "latest"])[2:])
+
+    def read(self, to: str, signature: str, types: list[str], values: list, out: list[str]):
+        return decode(out, self.call(to, calldata(signature, types, values)))
+
+    def simulate(self, sender: str, txs: list[dict]) -> list[dict] | None:
+        """Every step in order from the sender (eth_simulateV1). None when the RPC does not offer it."""
+        calls = [{"from": sender, "to": t["to"], "data": t["data"], **({"value": hex(int(t["value"]))} if int(t.get("value", 0)) else {})} for t in txs]
+        try:
+            out = self.rpc("eth_simulateV1", [{"blockStateCalls": [{"calls": calls}], "validation": False}, "latest"])
+        except ChainError:
+            return None
+        steps = []
+        for i, c in enumerate(out[0]["calls"]):
+            ok = c.get("status") == "0x1"
+            steps.append({"step": i + 1, "ok": ok, **({} if ok else {"error": str((c.get("error") or {}).get("message", "reverted"))[:200]})})
+        return steps
+
+    def send(self, account, tx: dict, wait_seconds: float = 180) -> dict:
+        """Sign one transaction with the agent's key, send it, wait for its receipt and check it went through.
+
+        The call is run from the wallet first (eth_call, then the gas estimate): a transaction that would revert is
+        never sent. Returns {hash, status, gas_used, block}.
+        """
+        self.check_chain()
+        me = account.address
+        to, data, value = to_checksum_address(tx["to"]), tx["data"], int(tx.get("value", 0))
+        self.call(to, data, sender=me, value=value)
+        req = {"from": me, "to": to, "data": data, **({"value": hex(value)} if value else {})}
+        gas = int(self.rpc("eth_estimateGas", [req]), 16) * 13 // 10
+        base = int((self.rpc("eth_getBlockByNumber", ["latest", False]) or {}).get("baseFeePerGas", "0x0"), 16)
+        try:
+            tip = int(self.rpc("eth_maxPriorityFeePerGas"), 16)
+        except ChainError:
+            tip = 0
+        signed = account.sign_transaction({
+            "type": 2, "chainId": CHAIN_ID, "to": to, "data": data, "value": value, "gas": gas,
+            "nonce": int(self.rpc("eth_getTransactionCount", [me, "pending"]), 16),
+            "maxFeePerGas": base * 2 + tip + 1, "maxPriorityFeePerGas": tip,
+        })
+        tx_hash = self.rpc("eth_sendRawTransaction", ["0x" + signed.raw_transaction.hex()])
+        deadline = time.time() + wait_seconds
+        while time.time() < deadline:
+            rc = self.rpc("eth_getTransactionReceipt", [tx_hash])
+            if rc:
+                out = {"hash": tx_hash, "status": int(rc["status"], 16), "gas_used": int(rc["gasUsed"], 16), "block": int(rc["blockNumber"], 16)}
+                if out["status"] != 1:
+                    raise ChainError(f"transaction {tx_hash} was mined and failed")
+                return out
+            time.sleep(0.5)
+        raise ChainError(f"transaction {tx_hash} was sent and has no receipt after {int(wait_seconds)} seconds; check it before sending anything else")
+
+
+def account_from_key(key: str):
+    """The agent's signer. The key lives only inside this object: nothing here prints, logs or stores it."""
+    try:
+        return Account.from_key(key.strip())
+    except Exception:
+        raise ValueError("the agent key is not a private key (0x and 64 hex characters)") from None

borro_live/mcp.py

@@ -0,0 +1,84 @@
+"""A thin client for Borro's MCP server: JSON-RPC 2.0 over HTTP, no session, no key."""
+
+from __future__ import annotations
+
+import json
+import os
+import urllib.error
+import urllib.request
+
+MCP_URL = "https://borro.markets/mcp"
+PROTOCOL = "2025-03-26"
+
+
+class BorroLiveError(Exception):
+    """Every error this kit raises: an order it refuses before anything is signed, or an answer Borro gave in words."""
+
+
+class McpError(BorroLiveError):
+    """The server could not be reached or answered with a JSON-RPC error."""
+
+
+class ToolRefused(McpError):
+    """A tool answered in words instead of an answer: an unlisted ticker, too little money, no position."""
+
+
+def http_post(url: str, payload: dict, timeout: float, what: str) -> dict:
+    """POST JSON, return JSON. Errors never carry the address: an RPC address can hold a key."""
+    req = urllib.request.Request(
+        url, data=json.dumps(payload).encode(),
+        headers={"Content-Type": "application/json", "Accept": "application/json", "User-Agent": "borro-live"},
+    )
+    try:
+        with urllib.request.urlopen(req, timeout=timeout) as res:
+            return json.loads(res.read())
+    except urllib.error.HTTPError as e:
+        raise McpError(f"{what} answered HTTP {e.code}") from None
+    except (urllib.error.URLError, TimeoutError, OSError):
+        raise McpError(f"{what} could not be reached") from None
+    except ValueError:
+        raise McpError(f"{what} did not answer in JSON") from None
+
+
+class McpClient:
+    """initialize, tools/list and tools/call against Borro's MCP endpoint.
+
+    ``transport`` replaces the HTTP call (a function taking the JSON-RPC payload and returning the response),
+    which is how the tests replay recorded answers.
+    """
+
+    def __init__(self, url: str | None = None, timeout: float = 60, transport=None):
+        self.url = url or os.environ.get("BORRO_MCP_URL") or MCP_URL
+        self.timeout = timeout
+        self._transport = transport or (lambda payload: http_post(self.url, payload, self.timeout, "Borro's MCP server"))
+        self._id = 0
+
+    def _rpc(self, method: str, params: dict | None = None) -> dict:
+        self._id += 1
+        payload = {"jsonrpc": "2.0", "id": self._id, "method": method}
+        if params is not None:
+            payload["params"] = params
+        res = self._transport(payload)
+        if not isinstance(res, dict) or "result" not in res:
+            err = (res or {}).get("error") if isinstance(res, dict) else None
+            raise McpError(f"{method}: {(err or {}).get('message', 'no result')}")
+        return res["result"]
+
+    def initialize(self) -> dict:
+        return self._rpc("initialize", {"protocolVersion": PROTOCOL, "capabilities": {}, "clientInfo": {"name": "borro-live", "version": "0.1.0"}})
+
+    def tools_list(self) -> list[dict]:
+        return self._rpc("tools/list")["tools"]
+
+    def call(self, name: str, arguments: dict | None = None) -> dict:
+        """One tool call. Returns the tool's structured answer; a refusal in words raises ToolRefused."""
+        res = self._rpc("tools/call", {"name": name, "arguments": arguments or {}})
+        text = next((c.get("text", "") for c in res.get("content", []) if c.get("type") == "text"), "")
+        if res.get("isError"):
+            raise ToolRefused(text or f"{name} was refused")
+        if isinstance(res.get("structuredContent"), dict):
+            return res["structuredContent"]
+        try:
+            return json.loads(text)
+        except ValueError:
+            raise McpError(f"{name} did not answer in JSON") from None

borro_live/tradingagents.py

@@ -0,0 +1,84 @@
+"""TradingAgents on Borro: turn a run's rating into an order.
+
+    from borro_live import Broker
+    from borro_live.tradingagents import go_live
+
+    ta = go_live(TradingAgentsGraph(config=config), Broker.from_env(), usdg=5)
+    _, decision = ta.propagate("NVDA", "2026-09-01")      # the same answer as before; ta.borro_orders has the orders
+
+``TradingAgentsGraph.propagate(ticker, date)`` returns ``(final_state, signal)``; the signal is one of Buy,
+Overweight, Hold, Underweight, Sell, or REVIEW when the run reached no rating. Older versions answer BUY, SELL or
+HOLD. TradingAgents itself is never imported here: a plain string, the tuple or the final state all work.
+"""
+
+from __future__ import annotations
+
+import re
+import warnings
+
+from .broker import BorroLiveError, Broker, Result
+from .chain import ChainError
+from .mcp import McpError
+
+RATINGS = ("buy", "overweight", "hold", "underweight", "sell")
+
+
+def rating_of(decision) -> str | None:
+    """The rating in a decision, lower case, or None when there is none to act on (REVIEW included)."""
+    if isinstance(decision, (tuple, list)) and decision:
+        decision = decision[-1]
+    if isinstance(decision, dict):
+        decision = decision.get("final_rating") or decision.get("signal") or decision.get("decision") or ""
+    word = re.sub(r"[^a-z]", "", str(decision or "").lower())
+    return word if word in RATINGS else None
+
+
+def execute(broker: Broker, ticker: str, decision, usdg: float = 5.0, allow_short: bool = False) -> list[Result]:
+    """Act on one decision for one ticker. Returns the orders made (none for Hold, REVIEW or nothing to sell).
+
+    Buy          cover a short if there is one, then buy ``usdg`` worth
+    Overweight   the same, half the size
+    Hold         nothing
+    Underweight  sell half of the long, if there is one
+    Sell         sell all of the long; with ``allow_short`` and no long, short ``usdg`` worth instead
+    """
+    rating = rating_of(decision)
+    if rating in (None, "hold"):
+        return []
+    symbol = str(ticker).strip().upper()
+    broker.price(symbol)  # refuses a ticker Borro does not list, before anything else
+    pos = broker.positions()
+    has_long = any(p.get("symbol") == symbol for p in pos["longs"])
+    has_short = any(p.get("symbol") == symbol for p in pos["shorts"])
+    out: list[Result] = []
+    if rating in ("buy", "overweight"):
+        if has_short:
+            out.append(broker.cover(symbol))
+        out.append(broker.buy(symbol, usdg if rating == "buy" else usdg / 2))
+    elif has_long:
+        out.append(broker.sell(symbol, 100 if rating == "sell" else 50))
+    elif rating == "sell" and allow_short and not has_short:
+        out.append(broker.short(symbol, usdg))
+    return out
+
+
+def go_live(graph, broker: Broker, usdg: float = 5.0, allow_short: bool = False):
+    """Wrap ``graph.propagate`` so every run's decision is executed on Borro. Returns the same graph.
+
+    ``propagate`` answers exactly as before. The orders are in ``graph.borro_orders``; if Borro or this kit refused
+    (a cap, an unlisted ticker, a failed simulation), the reason is in ``graph.borro_error`` and a warning is raised.
+    """
+    inner = graph.propagate
+
+    def propagate(company_name, trade_date, *args, **kwargs):
+        result = inner(company_name, trade_date, *args, **kwargs)
+        graph.borro_orders, graph.borro_error = [], None
+        try:
+            graph.borro_orders = execute(broker, company_name, result, usdg=usdg, allow_short=allow_short)
+        except (BorroLiveError, McpError, ChainError) as e:
+            graph.borro_error = e
+            warnings.warn(f"borro-live did not complete the order for {company_name}: {e}", stacklevel=2)
+        return result
+
+    graph.propagate = propagate
+    return graph

borro_live-0.1.0.dist-info/METADATA

@@ -0,0 +1,212 @@
+Metadata-Version: 2.4
+Name: borro-live
+Version: 0.1.0
+Summary: Send a trading agent's decisions to Borro on Robinhood Chain: buy, sell, short, cover and lend tokenized stocks against USDG. Adapters for TradingAgents and ai-hedge-fund.
+Author: Borro
+License: MIT
+Project-URL: Homepage, https://borro.markets/go-live
+Project-URL: Documentation, https://borro.markets/developers
+Project-URL: Repository, https://github.com/BorroMarkets/borro-live
+Keywords: borro,robinhood-chain,tradingagents,ai-hedge-fund,mcp,agents
+Requires-Python: >=3.10
+Description-Content-Type: text/markdown
+License-File: LICENSE
+Requires-Dist: eth-account>=0.13
+Dynamic: license-file
+
+# Go Live on Borro
+
+`borro-live` sends a trading agent's decisions to [Borro](https://borro.markets) for real: buy, sell, short, cover and
+lend tokenized stocks against USDG on Robinhood Chain. It comes with adapters for
+[TradingAgents](https://github.com/TauricResearch/TradingAgents) and
+[ai-hedge-fund](https://github.com/virattt/ai-hedge-fund), which decide and simulate but place no orders.
+
+It is a small Python package: one dependency (`eth-account`), no framework imported unless you have it. It talks to
+Borro's public MCP server (`https://borro.markets/mcp`, no key), which builds each transaction and simulates it; the
+package checks the simulation, signs with your agent's own key and sends through your own RPC.
+
+**Read this first.**
+
+- **Not advice.** This is plumbing. Nothing here tells you what to trade, and nothing here promises a return. You can
+  lose everything you send.
+- **What a stock token is.** A token on Robinhood Chain, issued by Robinhood Assets (Jersey) Limited, whose price
+  follows a stock or fund. It is not the share: no vote, no brokerage account, no investor protection scheme. Its price
+  on chain can sit away from the stock's, most of all while the stock market is shut.
+- **A short can be liquidated.** If the stock rises far enough, Borro closes the short for you at a loss, and the
+  deposit can be lost. A buy here is a long with a small loan against it, and it can be liquidated too if the token
+  falls nearly to zero.
+- **It starts as a dry run.** Nothing is sent until you ask for live mode twice: a flag in code and a variable in the
+  environment.
+
+## Five minutes
+
+```sh
+pip install borro-live                # or, from a clone: pip install -e .
+```
+
+Three environment variables:
+
+```sh
+export BORRO_AGENT_KEY=0x...          # the agent's own wallet key. Use a fresh wallet with little in it.
+export BORRO_RPC_URL=https://...      # your own Robinhood Chain RPC (chain id 4663). There is no built-in one.
+export BORRO_LIVE=1                   # leave this out until you mean it
+```
+
+To try it with no key at all, set `BORRO_WALLET=0x...` to any address in place of `BORRO_AGENT_KEY`: every order is
+then a dry run simulated from that address, and nothing can be sent. A simulation passes only if that address holds
+the USDG the order needs.
+
+Dry run (leave `BORRO_LIVE` out). It prints Borro's simulation of every step and sends nothing:
+
+```sh
+borro-live tickers
+borro-live buy NVDA 5                 # 5 USDG of NVDA
+borro-live positions
+```
+
+Live. The wallet needs USDG for the order and a little ETH for gas:
+
+```sh
+BORRO_LIVE=1 borro-live buy NVDA 5 --live
+BORRO_LIVE=1 borro-live sell NVDA --live
+```
+
+Each live order prints every transaction hash. A dry run needs no RPC and no key at all:
+`borro-live buy NVDA 5 --wallet 0xYourAddress`.
+
+## TradingAgents
+
+`TradingAgentsGraph.propagate(ticker, date)` returns `(final_state, signal)`, where the signal is Buy, Overweight, Hold,
+Underweight or Sell (or REVIEW when the run reached no rating). One line wraps it:
+
+```python
+from tradingagents.graph.trading_graph import TradingAgentsGraph
+from tradingagents.default_config import DEFAULT_CONFIG
+from borro_live import Broker
+from borro_live.tradingagents import go_live
+
+ta = go_live(TradingAgentsGraph(config=DEFAULT_CONFIG.copy()), Broker.from_env(), usdg=5)
+_, decision = ta.propagate("NVDA", "2026-09-01")
+print(decision, ta.borro_orders, ta.borro_error)
+```
+
+`propagate` answers exactly as before. What the adapter does with each rating:
+
+| Rating | Order |
+|---|---|
+| Buy | cover a short if there is one, then buy `usdg` worth |
+| Overweight | the same, half the size |
+| Hold, REVIEW | nothing |
+| Underweight | sell half of the long, if there is one |
+| Sell | sell all of the long. With `allow_short=True` and no long, short `usdg` worth instead |
+
+Without the graph: `borro_live.tradingagents.execute(broker, "NVDA", "Buy", usdg=5)`. Runnable:
+`python examples/tradingagents_example.py NVDA --decision Buy`.
+
+## ai-hedge-fund
+
+The portfolio manager's decisions (`{ticker: {"action": "buy" | "sell" | "short" | "cover" | "hold", "quantity":
+shares}}`, what `run_hedge_fund` returns under `"decisions"`) go straight in:
+
+```python
+from borro_live import Broker
+from borro_live.ai_hedge_fund import execute_decisions
+
+results = execute_decisions(Broker.from_env(), result["decisions"], scale=0.01)
+```
+
+`scale` multiplies every quantity, since the model sizes in whole shares for a paper portfolio and the caps here are
+in USDG. Pick it so the largest order lands under your per-order cap (10 USDG unless you raise it): an order over the
+cap is refused, not shrunk. Each ticker gets its own answer; one refusal never stops the others. Runnable:
+`python examples/ai_hedge_fund_example.py --buy NVDA 3`.
+
+The v2 engine (`hedge_fund/`, the `aihf` package) has a `Broker` protocol instead: `positions()`, `cash()` and
+`place_order(order)`. `borro_live.ai_hedge_fund.BorroBroker(Broker.from_env())` satisfies it. Whole shares on a signed
+book meet two limits on Borro: a short is closed whole, and an order may not cross zero in one step. Both are refused
+in words, never half done. Treat it as experimental, for three reasons. The engine orders whole shares, so with the
+default 10 USDG cap every order is refused: raise the caps to more than a share of what you trade. The engine expects
+`place_order` to fill or raise, so in a dry run it raises with Borro's simulation and the engine's session stops there.
+And the engine reconciles its ledger against whole shares, while a buy on Borro fills at the share count the swap
+gave. Its own data client also needs its own key.
+
+## What each order really is
+
+Worked out from the server's own `tools/list`:
+
+| `Broker` | Borro tool | What happens |
+|---|---|---|
+| `buy(symbol, usdg)` | `open_long` at 1.01x | Your USDG buys the stock token; it is lent (it earns lending fees) and posted; 1% of the order is borrowed against it. |
+| `sell(symbol, percent=100)` | `close_long` | The token is sold, the small loan repaid, USDG comes back. |
+| `short(symbol, usdg)` | `open_short` | The stock is borrowed and sold; the sale money and a USDG deposit are held. You pay a borrow fee while it is open. |
+| `cover(symbol)` | `close_short` | Buys back what is owed, returns it, pays out what is left. Borro has one short per stock: this closes all of it. |
+| `lend(asset, amount)` | `supply` | USDG earns interest; a stock token you hold earns lending fees. |
+| `positions()` | `position` | Longs, shorts, what is lent, wallet balances. |
+| `buy_spot_with_eth(symbol, shares)` | `buy_with_eth` | A plain spot buy paid in the wallet's ETH. The token lands in the wallet. |
+
+**Borro's MCP server has no tool for a plain spot buy or sell of a stock token for USDG.** `buy` is therefore the
+nearest thing that can also be sold back through Borro: a long at 1.01x. It behaves like holding the token, with two
+differences you should know: the token is lent out while you hold it, and there is a loan of 1% of the order against
+it, so the position can be liquidated if the token loses nearly all its value. `buy_spot_with_eth` is a true spot
+buy, but it pays in ETH and no Borro tool sells the token back; lend it, or sell it elsewhere.
+
+`short` deposits 1 USDG for each USDG shorted by default (`short_deposit=1.0`), and never less than a tenth over the
+least Borro asks. At that default a short is closed for you after a rise of roughly half; the quote in every answer
+gives the exact price (`closed_for_you_at_price`). A thinner deposit is closed sooner.
+
+## Safety
+
+- **Dry run by default.** Without `live=True` and `BORRO_LIVE=1` together, an order returns the tool's own simulation
+  and sends nothing. `live=True` without the variable refuses to start; the variable without the flag stays a dry run.
+- **Caps you set.** `max_order_usdg` (default 10) is the most one buy, short or lend may be worth; `max_day_usdg`
+  (default 25) is the most they may add up to in one UTC day, per wallet. Over either, the order is refused before
+  anything is signed. The day's total is kept in `~/.borro-live/state.json` (or `BORRO_LIVE_STATE`), counted before the
+  first transaction goes out. Selling and covering are never stopped by a cap. Set them in code or with
+  `BORRO_MAX_ORDER_USDG` and `BORRO_MAX_DAY_USDG`.
+- **Listed tickers only.** A ticker Borro does not list is refused before any trade tool is called.
+- **A failed simulation is never sent.** Every step must pass Borro's simulation, and each step is run again from the
+  wallet (`eth_call`, then a gas estimate) just before it is signed. Steps go in order; each receipt is checked before
+  the next.
+- **What is signed.** Only transactions for your wallet on chain 4663. No order sends ETH except
+  `buy_spot_with_eth`, and never more than its quote. A USDG approval is refused if it is for more than the order.
+- **The key.** Read from `BORRO_AGENT_KEY`, kept in memory, never printed, logged or written. Errors never carry your
+  RPC address.
+- **Trust.** Borro's server builds the transactions. Read a dry run's `transactions` before going live: each has the
+  contract it goes to and what it does. The `rules` tool lists Borro's contracts.
+
+## Builder codes: a fee share for whoever ships the integration
+
+Borro shares its own fees with whoever brings the business (the Bookrunners programme). Give the broker a code and
+installs that carry it pay the code's owner:
+
+```python
+Broker.from_env(builder_code="yourcode")      # or BORRO_BUILDER_CODE=yourcode
+```
+
+- The wallet is bound to the code once, with one free signature (`bind_builder`, no transaction). From then on the
+  code earns Borro's fee on the interest that wallet pays when it borrows (shorts and the loan under a buy).
+- Lends go through the `BorroBuilders` contract with the code, so the code earns Borro's fee on what those deposits
+  earn. The wallet keeps its vault shares.
+- The share is all of Borro's fee for 12 months, half after, paid monthly in USDG to the wallet that registered the
+  code. The user pays nothing extra. Fees float with demand: with no borrowing there is no fee to share.
+- Register a code with your own wallet at [borro.markets/bookrunners](https://borro.markets/bookrunners). First come,
+  first served; only that wallet can move it. One code per wallet: the first binding stands.
+
+There is no default code. If you ship this in a framework, set yours.
+
+## Tests
+
+```sh
+python -m unittest discover -s tests -p 'test_unit.py'        # 50 tests against recorded MCP answers, no network
+```
+
+Borro also runs the kit end to end on a local fork of Robinhood Chain in its own repository: a dry run, a live buy, lend,
+short, cover and sell, both adapters, the caps and a builder code. `BORRO_MCP_URL` points the client at another MCP
+address, which is how that test reaches its local server.
+
+`walk.sh` is the one real walk: one small live order per framework from a funded wallet. It asks before it sends.
+
+## Not here
+
+Options, perps and Borro's dark pool are not part of this kit.
+
+MIT licence.

borro_live-0.1.0.dist-info/RECORD

@@ -0,0 +1,13 @@
+borro_live/__init__.py,sha256=w7EGI8U3GUfsyU1CH1dyhSprb37LgRKqh10bZ1ZuqOo,712
+borro_live/__main__.py,sha256=4nIa5fZIuDsdbROWu3l222tzsOBKahxCUN36x6FHbEY,2594
+borro_live/ai_hedge_fund.py,sha256=A3mJSiYYcIW7yCtfUs51dS9tG8rKMwAFZ8fe1o_ZX4g,6950
+borro_live/broker.py,sha256=E5KKwa_4ZtRQPrNphgXdHI6gK2O-idC9hW4TciZTV5w,23364
+borro_live/chain.py,sha256=FB--XbmPM084RZv2K15ywA07g4RiQC6ivPlzzmSap7M,5688
+borro_live/mcp.py,sha256=ifxst_QIEWoNKk3I-UPd83G-E0vqnHwG1a7Yc3uQtnA,3565
+borro_live/tradingagents.py,sha256=ug-L91vtuaQAWHinNeaP-XrpbTPng1HWgT0RSL0_J8o,3769
+borro_live-0.1.0.dist-info/licenses/LICENSE,sha256=GJmFD0cz1TzbvIJBfoIZQqz9XLEGpcBKSpJZpOjmNKQ,1062
+borro_live-0.1.0.dist-info/METADATA,sha256=HQL3QHqXgSYZfywkEgZDIf20t2p4Rf4-cOiDJsSx5LY,11697
+borro_live-0.1.0.dist-info/WHEEL,sha256=mOdXR9C3wMVov7cSY8PY-XCzo3SmmWCHvGQr5csJoao,91
+borro_live-0.1.0.dist-info/entry_points.txt,sha256=jbZUsSDcH5aUzJ-jwXG5EwJ9DFKn4o8k-V-aZfOhwa0,56
+borro_live-0.1.0.dist-info/top_level.txt,sha256=kcTrbIBcLvB6i5_NgIBmaRHbEM_AWk7dB8wUNf66i4o,11
+borro_live-0.1.0.dist-info/RECORD,,

borro_live-0.1.0.dist-info/WHEEL

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

borro_live-0.1.0.dist-info/entry_points.txt

@@ -0,0 +1,2 @@
+[console_scripts]
+borro-live = borro_live.__main__:main

borro_live-0.1.0.dist-info/licenses/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Borro
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

borro_live-0.1.0.dist-info/top_level.txt

@@ -0,0 +1 @@
+borro_live