---

TradeClaw generates BUY/SELL signals using multi-timeframe technical analysis (RSI, MACD, EMA, Bollinger Bands, Stochastic, ADX, Volume). Every signal is recorded in a Postgres database and published on the track record — wins and losses, no cherry-picking.

Status: pre-1.0 (0.1.0). The signal engine, dashboard, backtester, and self-host path are usable today; APIs and schema may still change between releases.

Free vs Pro

	Free	Pro ($29/mo)
Symbols	6 (BTC, ETH, XAU, EUR/USD, SPY, QQQ)	All pairs (forex, crypto, metals, commodities, US equities incl. NVDA/TSLA/AAPL/MSFT/GOOGL/AMZN/META)
Signal delay	30 min	Real-time
Take-profit levels	TP1 only	TP1 + TP2 + TP3
Indicators	RSI + EMA trend	RSI, MACD, BB, Stochastic, ADX
Signal history	7 days	Full archive
Confidence band	Standard (70–84)	Standard + Premium (85+)
Telegram alerts	Public channel (delayed)	Private channel (instant), bot-gated Pro group with auto-kick on tier expiry
Broker execution	—	Binance USDT-perp (testnet); RoboForex R StocksTrader bridge scaffolded (interface only, not implemented)
Track record	Full access	Full access
Self-host	Yes	Yes

Start free at tradeclaw.win/dashboard. Upgrade anytime at tradeclaw.win/pricing.

Self-hosting vs. TradeClaw Pro (hosted)

TradeClaw is MIT-licensed. You can fork, self-host, and run the entire signal framework for free — the free-tier signal engine (classic TA, RSI + EMA + MACD confluence), backtester, dashboard, paper trading, and public Telegram broadcaster are all in this repo.

The hosted version at tradeclaw.win adds features that activate only when the deploy holds the matching credentials:

Feature	Unlocked by env var	Who has it
Real-time premium signals (MTF confluence, curated)	PREMIUM_SIGNAL_SOURCE_URL + PREMIUM_SIGNAL_SOURCE_KEY	tradeclaw.win only
Stripe checkout + tier upgrade on webhook	STRIPE_SECRET_KEY, STRIPE_WEBHOOK_SECRET	Per-deploy
Private Pro Telegram group + invite on subscribe	TELEGRAM_PRO_GROUP_ID + Pro bot token	tradeclaw.win only
Telegram auto-broadcast of free symbols	TELEGRAM_CHANNEL_ID + bot token	Per-deploy

Without these, self-hosters get the free-tier experience — which is the same signal engine the founders trade against real capital. No code is withheld. What is withheld is the curated premium signal feed and the payment plumbing. Those are operational, not algorithmic.

If you want to run your own paid tier on top of this code: set your own Stripe keys, run your own premium signal generator, and point PREMIUM_SIGNAL_SOURCE_URL at it. The HTTP contract is minimal — GET <url> returning { signals: TradingSignal[] } with a Bearer Authorization header using PREMIUM_SIGNAL_SOURCE_KEY. Returns [] (and the hosted deploy keeps working with the DB-backed premium_signals table) if the remote is down.

Quick start (Docker)

One-liner (no clone required)

docker run -p 3000:3000 ghcr.io/naimkatiman/tradeclaw:latest

Open http://localhost:3000 — the dashboard loads, but the web app requires a PostgreSQL DATABASE_URL and throws on first DB access if it is unset. There is no bundled SQLite fallback. Point DATABASE_URL at a PostgreSQL instance:

docker run -p 3000:3000 \
  -e DATABASE_URL=postgres://user:pass@host:5432/tradeclaw \
  ghcr.io/naimkatiman/tradeclaw:latest

Docker Compose (recommended for production)

git clone https://github.com/naimkatiman/tradeclaw
cd tradeclaw
cp .env.example .env   # edit DATABASE_URL + Telegram tokens
docker compose up -d   # or: docker-compose up -d on the legacy CLI

Open http://localhost:3000. Requires PostgreSQL. Migrations live in apps/web/migrations/ and should be applied in filename order against your DATABASE_URL.

After the stack starts, run the self-host smoke checklist to verify Compose config, migrations, app health, websocket health, metrics, and optional monitoring before sharing the instance.

Image tags

Tag	What it tracks
ghcr.io/naimkatiman/tradeclaw:latest	Latest push to main (auto-built)
ghcr.io/naimkatiman/tradeclaw:edge	Same as latest — short-lived testing tag
ghcr.io/naimkatiman/tradeclaw:vX.Y.Z	A specific release tag
ghcr.io/naimkatiman/tradeclaw:sha-<git-sha>	A specific commit

Monitoring (Grafana + Prometheus)

TradeClaw exposes a Prometheus-compatible metrics endpoint at /api/metrics (signal direction, confidence, RSI, counts, freshness, outcomes). An opt-in monitoring stack ships with the compose file:

docker compose --profile monitoring up -d   # adds prometheus (:9090) + grafana (:3001)

Then open Grafana at http://localhost:3001 (default login admin/admin, override with GRAFANA_ADMIN_PASSWORD), add Prometheus (http://prometheus:9090) as a data source, and import grafana/tradeclaw-dashboard.json. The default docker compose up does not start these services. See grafana/README.md for the metrics reference and panel details.

Local development (from source)

TradeClaw is an npm-workspaces monorepo. You need Node.js 20+, npm, and a PostgreSQL instance. The web app requires DATABASE_URL and throws on first DB access if it is unset — there is no bundled SQLite fallback.

git clone https://github.com/naimkatiman/tradeclaw
cd tradeclaw
npm install            # installs all workspaces
cp .env.example .env   # set DATABASE_URL and any optional tokens

npm run dev            # start the Next.js web app (apps/web) on :3000

Common workspace scripts (all defined in the root package.json):

Command	What it does
npm run dev	Run the web app (apps/web) in dev mode
npm run build	Build packages/signals, packages/trading-agents, then the Next.js web app (bundle/static generation; TypeScript validation is a separate CI check)
npm run typecheck:web	Build the shared signal package, then run the web TypeScript check used by CI
npm run build:signals	Build the shared signal package only (also run by typecheck:web)
npm run build:all	Build signals + agent + web + ws-server
npm run start	Start the built web app
npm run lint	Lint apps/web
npm test	Run the Jest unit suite
npm run test:e2e	Run the Playwright e2e suite (apps/web)
npm run ws:dev / ws:build / ws:start / ws:test	Develop, build, run, or test the websocket server (apps/ws-server)
npm run agent	Run the trading-agent CLI (packages/agent)
npm run agent:start / agent:scan / agent:server	Start the agent loop, run a one-off scan, or run the agent HTTP server
npm run resolve:outcomes	Resolve real outcomes for recorded signals

For the long-form TypeScript command and why next build is not a typecheck, see docs/ai-improvement/build-typecheck-parity.md.

The Expo/React Native client in apps/mobile has its own package.json and is run with the Expo CLI from inside that workspace.

Repository layout

apps/
  web/                  Next.js app — dashboard, API routes, signal engine, broker execution
  web/lib/execution/    Broker bridges (Binance USDT-perp, RoboForex R StocksTrader)
  web/migrations/       Postgres migrations (apply in filename order)
  ws-server/            Websocket server for live updates
  mobile/               Expo / React Native client

packages/
  signals/              Signal types + build target consumed by apps/web
  agent/                Trading-agent runtime + CLI (npm run agent)
  strategies/           Backtest comparison framework (not in the live signal path)
  core/                 Shared core utilities
  cli/  tradeclaw-cli/  Command-line tooling
  create-tradeclaw/     Project scaffolder
  telegram-bot/         Telegram bot integration
  tradeclaw-mcp/        MCP server integration
  tradeclaw-js/  tradeclaw-extension/  tradeclaw-action/  tradeclaw-demo/  trading-agents/

scripts/
  launch-binance-testnet.sh   Binance testnet bootstrap

Note: the standalone tradeclaw-discord bot package (issue #38) remains early scaffolding. The web app's Discord webhook integration, however, is shipped and wired: when DISCORD_WEBHOOK_URL is set, the /api/cron/telegram broadcast job posts the same free-tier signals to a Discord channel (deduped via discord_posted_at), and per-user alert rules can target a Discord webhook channel.

How it works

Signal flow:

API request → getTrackedSignals() → generateSignalsFromTA()
  → ta-engine.ts (RSI, MACD, EMA, BB, Stoch, ADX, Volume)
  → recordSignalsAsync() → signal_history table
  → /track-record page

Signals are generated as a side effect of API requests — no external scheduler. The TA engine runs inside the Next.js process.

Market data:

/api/prices, OHLCV, SSE
  → market-data-hub (primary, MARKET_DATA_HUB_URL)
  → Binance (crypto fallback)
  → Stooq CSV (forex/metals fallback)
  → static last-known-good / synthetic (ultimate safety net)

The hub is the source of truth. The two fallbacks are thin survival paths — they kick in only if the hub returns empty or errors, and OHLCV results from fallbacks are not cached so a hub blip can't lock the dashboard into stale synthetic data.

Execution (Pro):

Pro signal → apps/web/lib/execution/executor.ts
  → Binance USDT-perp (testnet by default); RoboForex R StocksTrader bridge scaffolded (interface only, not implemented)
  → pg advisory lock (single client across full execution path)
  → kill-switch fail-closed if any precondition missing

Order placement maps the TradeClaw pair (BTC/USD) to the broker contract (BTCUSDT perp) before submission. Bootstrap a Binance testnet account with bash scripts/launch-binance-testnet.sh.

Strategy presets

Five entry strategies, comparable side-by-side in the backtest UI. In live signal generation, SIGNAL_ENGINE_PRESET (default hmm-top3) currently selects the preset only as a label on emitted signals — the live engine still generates with the classic profile regardless of preset. Per-preset live generation is not yet wired:

Preset	Logic
classic	RSI + MACD + EMA scoring — no regime filter
regime-aware	Classic filtered by HMM regime (backtest only; live signal path currently runs the classic profile)
hmm-top3	Regime-aware, top 3 by confidence — production default (the wired default for the executor and signal cron; live regime filtering applies in the backtest engine)
vwap-ema-bb	Mean-reversion at BB extremes with VWAP + EMA
full-risk	HMM top-3 with risk-weighted allocation

Compare presets in the backtest UI with side-by-side metrics and equity curves.

API

# Get current signals (free tier — 6 symbols, 30-min delay, 7-day history)
curl https://tradeclaw.win/api/signals

# Get track record stats
curl https://tradeclaw.win/api/strategy-breakdown

Pro subscribers get real-time access to all endpoints with full depth.

Notifications

TradeClaw can push signals over multiple channels, each enabled by env vars:

• Telegram — instant per-signal alerts (TELEGRAM_BOT_TOKEN + channel IDs).
• Email — instant per-signal alerts and a daily digest. Pick a provider with EMAIL_PROVIDER:
  • resend (default) — RESEND_API_KEY + RESEND_FROM_EMAIL
  • sendgrid — SENDGRID_API_KEY
  • smtp — SMTP_HOST / SMTP_PORT / SMTP_USER / SMTP_PASS (requires npm install nodemailer)
• Daily digest email — set EMAIL_TO (comma-separated) and the /api/cron/daily-digest job emails the day's top signals via the configured provider, independently of Telegram.
• Webhooks — see the webhook integration guide for the signal payload schema and polling/cron patterns, plus ready-to-run forwarders in examples/webhooks/ (Slack, Discord, n8n, Zapier, Google Sheets).

See .env.example for the full list of notification env vars.

Environment variables

Variable	Required	Description
DATABASE_URL	Required	PostgreSQL connection string. The web app throws on first DB access if it is unset — there is no SQLite fallback
MARKET_DATA_HUB_URL	Yes	Market data hub (primary quote/OHLCV/SSE source). Bare host accepted — https:// is added if missing
CRON_SECRET	Yes	Auth for /api/cron/* endpoints
SIGNAL_ENGINE_PRESET	No	Strategy preset (default: hmm-top3)
TELEGRAM_BOT_TOKEN	No	Telegram bot for alerts
TELEGRAM_CHANNEL_ID	No	Private channel (Pro alerts)
TELEGRAM_PUBLIC_CHANNEL_ID	No	Public channel (delayed free alerts)
TELEGRAM_PRO_GROUP_ID	No	Pro group chat ID — bot auto-kicks members without an active Pro tier
STRIPE_SECRET_KEY	No	Stripe for Pro subscriptions
STRIPE_WEBHOOK_SECRET	No	Stripe webhook signing secret
STRIPE_PRO_PRICE_ID	No	Stripe price ID for the Pro tier
PREMIUM_SIGNAL_SOURCE_URL	No	Hosted-only premium signal feed
PREMIUM_SIGNAL_SOURCE_KEY	No	Bearer token for the premium feed
BINANCE_API_KEY / BINANCE_API_SECRET	No	Binance USDT-perp execution (testnet by default)
ROBOFOREX_RST_*	No	RoboForex R StocksTrader bridge credentials

See .env.example for the full, commented list.

Contributing

See CONTRIBUTING.md and good first issues.

Before opening a PR: run npm install, make your change, then npm run lint, npm test, and (for web changes) npm run test:e2e.

Hacktoberfest-friendly: PRs against this repo qualify for the hacktoberfest-accepted label when they pass review.

Contributors

Thanks to everyone who has helped build TradeClaw — code, docs, bug reports, translations, or sharing the project.

This project follows the all-contributors specification — contributions of any kind welcome.

---