OpenSpread

Open-source, local-first hub for stablecoin arbitrage and crypto trading. It runs on your own computer, reads the exchanges you choose, shows the real net spread after fees, and lets your own Claude or Codex read the data, record scored analyses and test simulated bots. No server of ours, no tracking. A bitcoin100treta project.

Website and live demo: https://bullroom.vercel.app Visual companion: Bullroom, your bots as an animated pixel-art office.

Current stage: public data, simulation and scored analyses. The core reads public market data only. No exchange API keys, no real orders, no custody. It only writes files next to its own settings. Educational project, not financial advice.

What works today

• core/: reads public tickers from Binance, OKX, Bybit, Kraken and Coinbase (via CCXT) for stablecoin pairs (exchanges and pairs are configurable, see below), computes the best cross-exchange net spread (after both taker fees; transfer costs not included) and serves it on 127.0.0.1:4848 (/v1/state, /v1/stream as SSE).
• Bullroom shows it live: one room per pair, one character per exchange.
• Built-in paper trading (off by default, nothing extra to install): arbitrage robots simulated on real public order books, with no keys and no real orders. See below.
• MCP server for your own Claude or Codex: read data, record analyses, start and stop simulated robots. No tool can place a real order. See below.

Run it

Requires Node 22.12+.

git clone https://github.com/JVMarks/OpenSpread.git
cd OpenSpread/core
npm install
npm start

Then, in another terminal, run Bullroom and open it with ?source=core:

git clone https://github.com/JVMarks/bullroom.git
cd bullroom
npm install
npm run dev:client

Open http://localhost:5173/?source=core. Tests: npm test in core/.

Choose exchanges and pairs

On first run the core creates ~/.openspread/config.json (or the path in OPENSPREAD_CONFIG):

{
  "exchanges": ["binance", "okx", "bybit", "kraken", "coinbaseexchange"],
  "pairs": ["USDC/USDT", "USDE/USDT", "DAI/USDT", "FDUSD/USDT"],
  "pollMs": 10000,
  "alerts": [{ "pair": "USDC/USDT", "abovePct": 0.05 }],
  "transfer": { "sizeUsd": 1000, "withdrawFees": { "binance": { "USDC": 1 } } }
}

• exchanges: CCXT ids, 2 to 20.
• pairs: up to 20, like BTC/USDT. An exchange that does not list a pair just stays out of that room.
• pollMs: 5000 to 300000 (5 s to 5 min).
• alerts (optional): one per pair, "tell me when the best net spread reaches abovePct %" (between -1 and 10). Each alert rings once and re-arms only after the spread falls 0.02 points below the level, so it does not flicker. Bullroom shows it as a notice on that pair's room. Idea from trader-skill's alerts (MIT), rewritten here.
• transfer (optional): the arbitrage buys the base coin on one exchange and has to withdraw it to the other. Give the trade size in US$ (10 to 10,000,000) and each exchange's withdrawal fee per coin, in units of that coin (the example values above are illustrative, not real fees). None of the five default exchanges publishes withdrawal fees without an API key, so copy them from each exchange's withdrawal fee page. Where the fee is known, the best spread also carries the net after the withdrawal, and Bullroom and the alerts use that number; where it is not, it says "not set". Not included: the transfer time (the price moves meanwhile) and moving the money back. The values can also be edited in Bullroom's Markets panel.

The core also keeps a small history of each pair's best net spread (one sample per minute, last 25 hours) in history.json, next to config.json, saved every 5 minutes and on exit. With it, every pair in /v1/state carries windows: how much the net spread changed over 5 min, 1 h and 24 h, plus the low and high in each window (null until there is enough history). Bullroom shows them in its Spreads panel and on each room card. Deleting the file just starts the history over.

Edit it and restart the core. A broken file is reported in the terminal and the defaults are used until it is fixed. To see what each exchange lists before saving: npm run check:exchanges -- BTC/USDT ETH/USDT.

Stablecoin pairs are where the number is honest. For volatile coins (BTC, ETH) the net spread only subtracts the two taker fees: moving coins between exchanges takes minutes and has withdrawal fees, and the price moves meanwhile.

The core also accepts the same settings over its local API, for tools on your own machine (Bullroom will use it):

Route	What it does
GET /v1/config	Current settings, limits and every exchange id CCXT knows
POST /v1/check	Checks a settings body without saving: listed or not, inverted, active, taker fee
PUT /v1/config	Validates, saves the file and applies it at once, without a restart

Only 127.0.0.1/localhost as Host, only Bullroom's origins from a browser, JSON bodies up to 16 KB. There is no field for API keys: unknown fields are rejected.

The website lives in docs/ (deployed on Vercel from this folder). To refresh its Bullroom demo, clone Bullroom next to this repository and run node scripts/sync-demo.mjs.

Principles

• Local-first. Your keys (in later stages) never leave your machine, and never with withdrawal permission.
• The AI proposes, the engine executes, inside a risk policy you set.
• Honest numbers. Negative net spread is shown as negative. Simulated data is always labeled.

Paper trading

Turn it on in Bullroom (Settings › Robots) or with an engine block in the config. It starts off, with no pair allowed.

For each robot (one pair, two exchanges), every reading works like this:

This is the beginning of the README. Read the rest at the original. Read the full README ↗