@usherlabs/cex-broker 0.2.18 → 0.2.19

package/README.md

@@ -78,6 +78,27 @@ OTEL_SERVICE_NAME=cex-broker
 
 **Note**: Only configure API keys for exchanges you plan to use. The system will automatically detect and initialize configured exchanges.
 
+### Research / Backtest (ClickHouse Path B)
+
+Archive subscribe streams (OHLCV, orderbook, trades, ticker) to ClickHouse via the **archive forwarder**, visualize candles in the browser, run Python backtests, and optionally feed Hummingbot from the same warehouse.
+
+- **Overview:** [research/README.md](research/README.md)
+- **Full guide:** [docs/research-backtest.md](docs/research-backtest.md)
+
+Quick start:
+
+```bash
+docker network create fiet-sandbox || true
+docker compose -f docker/clickhouse-research.compose.yml up -d
+bun run start-archive-forwarder   # if not using compose forwarder service
+SYMBOLS=BTC/USDT,BNB/USDT,DOGE/USDT bun run start-archive-watch
+CLICKHOUSE_PORT=8123 bun run start-candle-viewer   # http://localhost:8091
+```
+
+Dev watchers: `dev:candle-viewer`, `dev:archive-forwarder`, `dev:archive-watch` (see [research/README.md](research/README.md)).
+
+Key env vars: `CEX_BROKER_ARCHIVE_FORWARDER_URL`, `CEX_BROKER_MARKET_ARCHIVE_ENABLED=true`, `CEX_BROKER_DEPLOYMENT_ID`.
+
 #### Wallet-authenticated exchanges
 
 Some exchanges (for example Hyperliquid, Vertex, Paradex, and Derive) authenticate with an on-chain wallet instead of exchange-issued API keys. The broker keeps the same `API_KEY` / `API_SECRET` interface and maps credentials internally based on each exchange's CCXT `requiredCredentials`:
@@ -703,7 +724,7 @@ Every successful `CreateOrder` response, successful `GetOrderDetails` response,
 - Execution values: requested quantity/notional, executed base quantity, executed quote quantity/cost, average execution price, filled amount, remaining amount, fee amount, fee currency, fee rate
 - Timing: exchange timestamp when present and broker observed timestamp
 
-Use metrics for aggregations and alerts, and use structured logs/events for joins back to Maker actions. For ClickHouse-backed OTel pipelines, analysts can join Maker action rows to broker telemetry using `makerActionId`, `idempotencyId`, `clientOrderId`, or the exchange `orderId`, then compare Maker propAMM execution price against `averageExecutionPrice` and fees. The broker does not emit raw exchange payloads, API keys, secrets, or credentials in these telemetry fields.
+Use metrics for aggregations and alerts. For the durable execution audit trail, the broker archives every order lifecycle event to `broker_execution.order_events` (and pre-order top-of-book to `broker_execution.market_metadata_snapshots`) through the **archive forwarder** — the same HTTP `/archive` → ClickHouse path used for `market_data.*`. Setting `CEX_BROKER_ARCHIVE_OTEL_LOGS_ENABLED=true` additionally mirrors those execution rows to OTel logs for observability, but the forwarder is the sink of record; you do not need an OTLP collector with a ClickHouse exporter to capture execution rows. Analysts join Maker action rows to `broker_execution.order_events` using `maker_action_id`, `idempotency_id`, `client_order_id`, or the exchange `order_id`, then compare Maker propAMM execution price against `average_execution_price` and fees. The broker does not emit raw exchange payloads, API keys, secrets, or credentials in these telemetry fields.
 
 ### Telemetry Test Harness