SeaTrader (tradebot)

Paper-first, long-only automation for US equities + crypto on Alpaca.

SeaTrader includes:

• Live/paper rebalance and risk-check commands
• Backtesting with per-asset controls (stocks vs crypto)
• Dashboard UI + Strategy Builder
• Safety guardrails and heartbeat monitoring

Educational/personal use only. Not financial advice.

---

Quick start

cd tradebot
python3 -m venv .venv
source .venv/bin/activate
pip install -U pip
pip install -e .

Create .env from .env.example and set Alpaca keys.

Run dashboard:

./scripts/start_dashboard.sh

Open: http://127.0.0.1:8008

---

Operator docs

• Step-by-step usage guide: docs/INSTRUCTIONS.md
• Autonomy policy: docs/autonomy_policy.md
• Multi-bot docs: docs/multibot.md
• Updated UI screenshots: docs/screenshots/
• Screenshot callouts were removed for clarity; instructions are text-first.

---

Unified multi-bot hub

SeaTrader includes a unified hub for Alpha..Iota bot dashboards.

Start the hub server:

python3 multibot/hub_server.py

Open:

• Hub: http://127.0.0.1:8099
• Individual dashboards: ports 8008..8016

From the Hub you can:

• Start/stop all dashboards
• Start/stop one bot dashboard
• Open each bot dashboard/API
• Run per-bot wipe (cancel open orders, request close-all positions, clear local bot data/logs)

Useful scripts (cross-platform preferred):

python multibot/scripts/dashboard_ctl.py start-all
python multibot/scripts/dashboard_ctl.py stop-all
python multibot/scripts/dashboard_ctl.py start <bot>
python multibot/scripts/dashboard_ctl.py stop <bot>
python multibot/scripts/sync_shared.py
python multibot/scripts/wipe_bot.py <bot>

Legacy bash wrappers (Linux/macOS):

multibot/scripts/start_dashboards.sh
multibot/scripts/stop_dashboards.sh
multibot/scripts/start_one.sh <bot>
multibot/scripts/stop_one.sh <bot>
multibot/scripts/wipe_bot.sh <bot>

---

Core safety model

• Long-only
• No margin/shorts
• Per-asset stop loss support
• Drawdown freeze controls
• Market-hours guard for equities (uses Alpaca clock/calendar + pre/post window checks)
• Order guardrails (max_orders_per_run, max_single_order_notional_usd, max_total_notional_usd)
• Paper-first workflow encouraged

---

Configuration

Primary config: config/config.yaml

Key blocks:

• allocation
• limits
• risk
• execution
• scheduling
• rebalance

Important risk setting

risk.execute_exit_liquidations

• false (default): risk-check is signal-only
• true: risk-check submits market sell orders for exit signals

For real order placement, also ensure:

• dry_run: false

---

Running from CLI

Rebalance (plan only)

tradebot rebalance --config config/config.yaml

Rebalance with orders

tradebot rebalance --config config/config.yaml --place-orders

Risk-check

tradebot risk-check --config config/config.yaml

---

Dashboard highlights

• Live/paper controls with per-asset settings
• Per-asset schedules (rebalance + risk-check)
• Market status panel (trading day, phase, next open/close, equity-order eligibility)
• Symbol exclusions manager (view excluded symbols with position/P&L context and remove from UI)
• Backtest runner + iteration sweeps
• Daily ledger, trade history, open positions at end
• Strategy Builder integration

UX note

Legacy/global fallback controls were removed from the dashboard.
Fallback behavior is configured per asset class only.

---

Backtesting

Backtests write artifacts to:

• data/backtests/<job_id>/status.json
• data/backtests/<job_id>/result.json

Useful runtime artifacts:

• data/last_rebalance.json
• data/last_risk_check.json
• data/last_placed_orders.json
• data/last_account.json
• data/state.json

Notes:

• last_rebalance / last_account include market_status and run_id
• last_placed_orders includes state (submitting/ok/error) and run_id

---

Heartbeat monitoring (SeaTrader-focused)

Heartbeat checks are defined in workspace HEARTBEAT.md and currently watch:

• New backtest completion/failure
• New risk-check liquidation/exit activity

State is tracked in:

• memory/heartbeat-state.json

---

Troubleshooting

Risk-check not liquidating

• Verify risk.execute_exit_liquidations: true
• Verify dry_run: false
• Check data/last_risk_check.json -> executed_liquidations

Alpaca SIP subscription error

Use IEX feed for equities (already defaulted in this project).

---

Repo layout

• src/tradebot/cli.py – CLI entrypoint
• src/tradebot/commands/ – rebalance, risk-check, dashboard actions
• src/tradebot/backtest/ – engine + jobs
• src/tradebot/dashboard/ – FastAPI app + frontend
• src/tradebot/strategies/ – built-in and user strategies
• config/ – config and presets
• data/ – runtime artifacts/cache/backtest outputs