Skip to content

Orderbook Watcher

The orderbook watcher aggregates maker offers from directory servers and exposes a web UI/API.

Install

With the recommended installer:

curl -sSL https://raw.githubusercontent.com/joinmarket-ng/joinmarket-ng/main/install.sh | bash
source ~/.joinmarket-ng/activate.sh

The orderbook watcher is part of the default complete profile. To install only the watcher and its core dependencies, pass --orderbook-watcher. Rerunning the installer repairs existing 0.35.0 installations that are missing the watcher entry point.

From a source checkout:

python -m pip install -e ./jmcore
python -m pip install -e ./jmwallet
python -m pip install -e ./orderbook_watcher

Run:

jm-orderbook-watcher

The former orderbook-watcher command still works but is deprecated and will be removed in a future release.

The reference JoinMarket implementation's ob-watcher.py is a separate program. Its presence does not install the JoinMarket NG console script.

Configuration

Use ~/.joinmarket-ng/config.toml and/or env vars.

Important settings:

  • NETWORK_CONFIG__NETWORK
  • NETWORK_CONFIG__DIRECTORY_SERVERS
  • DIRECTORY_NODES (optional comma-separated override)
  • TOR__SOCKS_HOST, TOR__SOCKS_PORT
  • ORDERBOOK_WATCHER__HTTP_HOST, ORDERBOOK_WATCHER__HTTP_PORT
  • ORDERBOOK_WATCHER__UPDATE_INTERVAL
  • ORDERBOOK_WATCHER__MEMPOOL_API_URL
  • ORDERBOOK_WATCHER__MEMPOOL_API_USE_TOR (defaults to true)

Mempool API lookups are disabled by default. When enabled, the watcher routes them through Tor by default. Set mempool_api_use_tor = false only when a direct endpoint is intentional, such as a local service. Direct access exposes the watcher's source IP and the bond transactions it queries; it also ignores HTTP_PROXY and HTTPS_PROXY inherited by the process.

Docker

orderbook_watcher/docker-compose.yml provides watcher + Tor.

From orderbook_watcher/:

mkdir -p tor/conf tor/data tor/run
cat > tor/conf/torrc << 'EOF'
SocksPort 0.0.0.0:9050
ControlPort 0.0.0.0:9051
CookieAuthentication 1
DataDirectory /var/lib/tor
Log notice stdout
EOF

docker compose up -d

UI is exposed on http://localhost:8000 by default. Set orderbook_watcher.http_host = "0.0.0.0" only when remote access is intentional and protected by an appropriate firewall or reverse proxy.

API Endpoints

  • GET / UI
  • GET /orderbook.json aggregated offers
  • GET /health healthcheck

Testing

Backend unit tests:

pytest orderbook_watcher

Frontend (web UI) tests run the real static files in a headless browser with fixture payloads; they need Node.js but no Docker stack:

cd tests/playwright
npm install && npx playwright install chromium
npm run test:obwatcher

They also run in CI (test-playwright job) and as part of scripts/run_parallel_tests.sh.