borro-live 0.1.0__tar.gz

borro_live-0.1.0/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/PKG-INFO

@@ -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/README.md

@@ -0,0 +1,196 @@
+# 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/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-0.1.0/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-0.1.0/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)