Trading Bot — Signal-Driven Architecture

Build a trading bot that consumes live signals from SignalNGN via sn signals, executes trades via ledger trades add, and enforces risk management locally.

Architecture

sn signals --json  →  Bot Process  →  ledger trades add (trade recording)
     ↑                    ↓                    ↓
  NATS stream     Risk Management Loop    ledger positions (state queries)
                  (periodic price check)

The bot is a single long-running process with two concurrent concerns:

Signal loop — reads JSON lines from sn signals --json stdout, decides whether to act, executes trades
Risk loop — periodically checks open positions against SL/TP/trailing stop/max hold time, closes positions that hit limits

Prerequisites: sn and ledger CLIs installed and configured. See the sn and ledger skills for setup. No other dependencies needed — sn provides signals AND live prices, ledger provides trade recording AND position queries.

Core Loop

Spawn sn signals --json as a subprocess. Read stdout line by line. Each line is a complete JSON signal.

while true:
    proc = spawn("sn signals --json")
    for line in proc.stdout:
        signal = parse_json(line)
        handle_signal(signal)
        maybe_run_risk_check()   # every N seconds between signals
    # proc exited — wait, then restart
    sleep(10)
    refresh_config()

Key points:

sn signals maintains the NATS connection internally and handles auth
Signals have a 2-minute TTL in NATS headers — stale signals are never delivered
If the subprocess exits (network blip, server restart), restart it with backoff
On restart, refresh the trading config — it may have changed server-side

Signal Payload

Each JSON line from sn signals --json:

{
  "exchange": "coinbase",
  "product": "BTC-USD",
  "granularity": "FIVE_MINUTES",
  "strategy": "ml_xgboost",
  "action": "BUY",
  "confidence": 0.82,
  "price": 98500.50,
  "stop_loss": 97200.00,
  "take_profit": 100800.00,
  "risk_reasoning": "ATR-based stop 1.3% below entry",
  "reason": "Strong bullish signal across 38 features",
  "position_pct": 0.25,
  "market": "futures",
  "leverage": 2,
  "indicators": { "rsi": 58.3, "macd_hist": 0.0042, "sma50": 96800, "sma200": 91200 },
  "timestamp": 1740218400
}

Field	Use
`action`	`BUY` (open long), `SELL` (close long), `SHORT` (open short), `COVER` (close short)
`confidence`	0–1. Filter by threshold (e.g. only act on ≥ 0.72)
`price`	Candle close at signal time. Use as entry price
`stop_loss` / `take_profit`	Strategy-suggested levels. Validate before using (see Risk Management)
`position_pct`	Kelly-derived sizing (0 = no recommendation, use fixed sizing)
`risk_reasoning`	Human-readable explanation of SL/TP rationale
`market`	`"spot"` or `"futures"`

Trading Config

Fetch the server-side trading config to know which products and strategies are active.

sn trading list --enabled --json

Returns an array of config objects. Build a lookup map keyed by product_id:

{
  "BTC-USD": {
    "exchange": "coinbase",
    "granularity": "FIVE_MINUTES",
    "long_leverage": 2,
    "short_leverage": 2,
    "strategies_long": ["ml_xgboost"],
    "strategies_short": ["ml_xgboost"],
    "strategies_spot": []
  }
}

Product + Strategy Filtering

Critical: The signal stream contains signals for ALL tenants on the platform. The engine publishes signals from the union of all users' trading configs. Your bot must filter signals to only act on products and strategies in your own trading config. Without this filter, the bot will trade random products from other users' configs.

Two-layer filter (both required):

Product filter: Reject any signal whose product is not a key in your trading config map. This is the first check — if the product isn't in your config, drop the signal immediately.
Strategy filter: For products that pass the product filter, check that the signal's strategy matches one of the allowed strategies for that product.

# Layer 1: Product must be in our config
cfg = trading_config.get(signal.product)
if cfg is None:
    → reject (product not in our config)

# Layer 2: Strategy must be allowed for this product
allowed = cfg.strategies_long + cfg.strategies_short + cfg.strategies_spot
if not prefix_match(signal.strategy, allowed):
    → reject (strategy not allowed)

The engine appends direction suffixes to strategy names when publishing signals:

Config name	Signal `strategy` field
`ml_xgboost`	`ml_xgboost` (long) or `ml_xgboost+trend`
`ml_xgboost`	`ml_xgboost_short` or `ml_xgboost_short+bearish`
`user:bb_squeeze`	`user:bb_squeeze` or `user:bb_squeeze+trend`

Use prefix matching: a signal's strategy matches a config entry if it equals the entry OR starts with entry+ or entry_. This is critical — exact matching will miss most signals.

for allowed in config_strategies:
    if signal.strategy == allowed
    or signal.strategy.startswith(allowed + "+")
    or signal.strategy.startswith(allowed + "_"):
        → match

Trade Execution

Opening a Position

Check for existing position: ledger positions <account> --json — skip if already have an open position for this symbol + side
Calculate size: Use position_pct (Kelly) if > 0, otherwise fixed percentage of portfolio
Calculate quantity: size_usd / price
Validate SL/TP: See Risk Management section
Record via ledger: ledger trades add <account> --symbol ... --side ... --quantity ... --price ...
Save position state: Persist SL/TP/trailing stop data locally for the risk loop

# Check existing position
ledger positions paper --json | jq '.[] | select(.symbol == "BTC-USD" and .side == "long" and .status == "open")'

# Record entry trade
ledger trades add paper \
  --symbol BTC-USD --side buy --quantity 0.015 --price 98500.50 \
  --fee 0.30 --market-type futures --leverage 2 --margin 750.00 \
  --strategy ml_xgboost --confidence 0.82 \
  --entry-reason "Strong bullish signal across 38 features" \
  --stop-loss 97200 --take-profit 100800

side: "buy" for long entry or short exit, "sell" for short entry or long exit
fee: Estimate — 0.02% for futures, 0.1% for spot
leverage and margin: Only for futures. margin = size_usd / leverage
Trade ID is auto-generated. Pass --trade-id to set a specific one (idempotent)

Closing a Position

Get position details: ledger portfolio <account> --json → find the position by symbol + side
Use the position's avg_entry_price and quantity for P&L calculation
Record the closing trade with the opposite side (sell to close long, buy to close short)
Include --exit-reason (e.g. "🛑 STOP LOSS", "🎯 TARGET HIT", "🔒 TRAILING STOP")
Clean up local position state

ledger trades add paper \
  --symbol BTC-USD --side sell --quantity 0.015 --price 97180.00 \
  --fee 0.30 --market-type futures \
  --exit-reason "🛑 STOP LOSS"

Position Sizing

if signal.position_pct > 0:
    base_size = portfolio_value × position_pct    # Kelly-derived
else:
    base_size = portfolio_value × fixed_pct       # e.g. 15%

size = clamp(base_size, min=150, max=2000)        # USD bounds
quantity = size / price

Kelly sizing (position_pct): The signal provides a fraction of capital to risk, derived from the strategy's historical win rate and payoff ratio
Fixed sizing: Fallback when no Kelly recommendation. 10–20% of portfolio per position is typical
Bounds: Enforce min/max to avoid micro-positions or overexposure

Risk Management

See references/risk-management.md for full implementation details.

Summary of the risk management stack:

Layer	Trigger	Default
Stop Loss	Price hits SL level	-3% post-leverage
Take Profit	Price hits TP level	+6% post-leverage
Trailing Stop	Activates at +2% P&L, trails 1.5% behind peak	—
Max Hold	Position held > N hours	72 hours

SL/TP Validation

Always validate the signal's SL/TP before using them:

sl_valid = stop_loss > 0 AND |stop_loss - price| / price > 0.001   # >0.1% from entry
tp_valid = take_profit > 0 AND |take_profit - price| / price > 0.001

if not sl_valid → use default SL (entry ± 3%/leverage)
if not tp_valid → use default TP (entry ± 6%/leverage)

This catches degenerate cases where SL/TP equal the entry price.

Risk Loop

Run every 5 minutes (or between signal processing). For each open position:

Fetch current price
Calculate P&L percentage (accounting for leverage and direction)
Update trailing stop if P&L exceeds activation threshold
Check all exit conditions (SL → trailing → TP → max hold)
Close position if any condition triggers

Cooldowns

Prevent duplicate trades from rapid-fire signals on the same product:

key = f"{product}:{strategy}:{action}"
if last_signal[key] was < 5 minutes ago → skip

5 minutes is a sensible default for 5-minute candle strategies.

Daemon Management

For production, run the bot as a managed process that auto-restarts on failure.

macOS (launchd):

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE plist PUBLIC "-//Apple//DTD PLIST 1.0//EN" "http://www.apple.com/DTDs/PropertyList-1.0.dtd">
<plist version="1.0">
<dict>
    <key>Label</key>
    <string>com.example.trading-bot</string>
    <key>ProgramArguments</key>
    <array>
        <string>/usr/bin/python3</string>
        <string>/path/to/trading_bot.py</string>
    </array>
    <key>EnvironmentVariables</key>
    <dict>
        <key>PATH</key>
        <string>/usr/local/bin:/usr/bin:/bin:~/go/bin</string>
    </dict>
    <key>KeepAlive</key>
    <true/>
    <key>StandardOutPath</key>
    <string>/path/to/bot.log</string>
    <key>StandardErrorPath</key>
    <string>/path/to/bot.log</string>
    <key>WorkingDirectory</key>
    <string>/path/to/workspace</string>
</dict>
</plist>

Control:

launchctl load   ~/Library/LaunchAgents/com.example.trading-bot.plist   # start
launchctl unload ~/Library/LaunchAgents/com.example.trading-bot.plist   # stop
launchctl stop   com.example.trading-bot                                 # restart (KeepAlive relaunches)

Linux (systemd): Standard user service unit with Restart=always.

Notifications

Send trade notifications to Telegram (or any messaging channel) on:

Position opened — include entry price, size, SL/TP, strategy, indicators
Position closed — include exit price, P&L (% and USD), reason
Risk management closes — include which condition triggered (🛑 SL, 🎯 TP, 🔒 trailing, ⏰ max hold)

Use OpenClaw's message send for notifications, or direct Telegram Bot API.

Portfolio Value Tracking

Track the live portfolio value as:

portfolio_value = starting_capital + total_realized_pnl + total_unrealized_pnl

starting_capital: Initial deposit (e.g. $10,000)
total_realized_pnl: From ledger portfolio <account> → total_realized_pnl field (sum of all closed position P&L)
total_unrealized_pnl: Sum of (current_price - entry) / entry × leverage for each open position, multiplied by position cost basis

Display this on dashboards instead of a static starting balance. Color green when above starting capital, red when below.

State Files

The bot maintains local state files alongside the script:

File	Purpose
`.position_state.json`	SL/TP/trailing stop levels, peak P&L, open time per position
`.exit_reasons.json`	Why each position was closed (for dashboard display)

These are the bot's local runtime state — the ledger is the source of truth for actual positions and trades. If state files are lost, the bot reconstructs defaults from ledger positions on next risk check.

Backtests

Use sn backtest to run and review historical strategy performance before going live.

Running a Backtest

sn backtest run \
  --exchange binance --product BTC-USD \
  --strategy ml_xgboost --granularity FIVE_MINUTES \
  --mode spot \
  --start 2025-01-01 --end 2025-12-31

Options: --mode spot|futures-long|futures-short, --leverage N, --trend-filter, --no-wait.

Strategy Params

Use --params key=value (repeatable) to override strategy parameters. The result always records the full effective params used — including defaults for anything not specified — so results are self-describing and comparable.

sn backtest run \
  --exchange binance --product BTC-USD \
  --strategy ml_xgboost --granularity FIVE_MINUTES \
  --params confidence=0.80 \
  --params exit_confidence=0.40 \
  --params rr_ratio=2.5 \
  --params atr_stop_mult=1.5

Available params per strategy:

Strategy	Params
`ml_xgboost`	`confidence`, `exit_confidence`, `rr_ratio`, `atr_stop_mult`
`alpha_beast`	`rsi_buy_max`, `rsi_sell_min`, `vol_multiplier`, `atr_stop_mult`, `rr_ratio`
`zscore_mean_reversion`	`entry`, `exit`, `max_pos`, `dampening`
`rsi_mean_reversion`	`oversold`, `overbought`
`bollinger_rsi`	`rsi_oversold`, `rsi_overbought`
`macd_momentum`	`threshold`
`volume_momentum`	`multiplier`
`combined_rsi_macd`	`oversold`, `overbought`

Listing Results

sn backtest list                              # newest 20 results (default)
sn backtest list --limit 50                  # show 50 results
sn backtest list --limit 0                   # show all results
sn backtest list --sort winrate              # sort by win rate descending
sn backtest list --sort date                 # sort by date descending (default)
sn backtest list --sort winrate --limit 0    # all results, best win rate first
sn backtest list --product BTC-USD --limit 0 # filter by product, show all

--limit (default 20): number of results to return. 0 means all.
--sort (default date): date = newest first; winrate = highest win rate first.

Filters: --exchange, --product, --strategy.

Inspecting a Single Result

sn backtest get 113

Shows full metrics: total return, win rate, max drawdown, Sharpe ratio, profit factor, avg win/loss, max consecutive losses.

Interpreting Results

High win rate ≠ profitable. A strategy can show 77% win rate yet negative returns if winning trades are small and losing trades are large. Always check profit_factor (> 1.0 required) and avg_win / avg_loss ratio alongside win rate.

Key metrics to evaluate:

Metric	What it measures	Good threshold
`total_return`	Overall P&L % for the period	Positive
`win_rate`	% of trades that closed in profit	Context-dependent
`profit_factor`	Gross profit / gross loss	> 1.2
`max_drawdown`	Largest peak-to-trough loss	< 20%
`sharpe_ratio`	Risk-adjusted return	> 1.0
`avg_win / avg_loss`	Win size vs loss size	> 1.0

trading-bot