Keywords: binance binance-spot binance-api binance-bot npm package binance-trading-bot ccxt trading-bot supertrend ema rsi zod typescript nodejs node-20 esm modules market-order dry-run testnet spot-trading crypto btc eth usdt algo-trading automated-trading automated-crypto quantitative paper-trading open-source long-only binance-testnet scalp swing grid-bot dca day-trading market-making signal-bot volatility ohlcv candlestick rest-api rate-limit spot-only no-futures stablecoin quote-invest

Repository (clone / issues / PRs): github.com/pro-tech-killers/binance-trading-bot

Related: coinbase-trading-bot · bybit-trading-bot · ai-trading-agent

1. Disclaimer
2. What this bot does
3. Architecture
4. Stack
5. npm scripts
6. Strategies
7. Execution: orders, balance, bars
8. Configuration
9. Keys and security
10. Install and run
11. Operations and logs
12. Troubleshooting
13. Limitations
14. Performance and trade history
15. Project layout
16. License

• Not financial, legal, or tax advice. Spot crypto trading is high risk; you can lose your full position.
• Past results do not guarantee future results. Public strategies (e.g. SuperTrend) are widely used and may be crowded.
• You own API key safety, KYC, taxes, and compliance with laws and Binance terms.
• This software is provided as is, without warranty. Use at your own risk.

Before live trading: run on Binance Spot Testnet and keep DRY_RUN until you trust the logs and behavior.

For live use you still need monitoring, key hygiene, and position sizes that match your risk tolerance.

Tight poll loop: loadMarkets once, then every POLL_SEC fetch OHLCV, compute indicators, get buy / sell / hold, log, and optionally send orders. The open candle is dropped so signals use closed bars only (reduces repainting when polling faster than the timeframe).

flowchart LR
  subgraph config
    A[".env + Zod"]
  end
  subgraph loop["Main loop (TradingBot)"]
    B["fetchOHLCV"] --> C["indicators + strategy"]
    C --> D["log line"]
    D --> E{"DRY_RUN?"}
    E -->|yes| F["no exchange orders"]
    E -->|no| G["market buy / sell via CCXT"]
  end
  A --> B
  G --> B

• src/config.ts — one load at startup; bad env → process exits.
• src/strategy.ts, src/indicators.ts — SuperTrend, EMA/RSI.
• src/bot.ts — CCXT binance, enableRateLimit: true, testnet, balance, orders.

ATR-based trend following (typical ATR + multiplier bands, trend flips on band breaks). Signals on the last two closed bars: buy on trend down → up, sell on up → down. Tuning: ST_ATR_PERIOD, ST_MULTIPLIER.

Fast/slow EMA cross on close; buy on bullish cross if RSI ≤ RSI_MAX_BUY; sell on bearish cross. Same closed-bar data as above.

Widely used rules ≠ guaranteed edge.

• Bars: only completed candles feed indicators.
• De-dupe: lastActedOnBarOpen blocks repeat buy/sell on the same last closed bar after an action (including dry-run). Hold does not set it. If sell is signaled but there is no free base, the bar can still be marked so the loop does not spin on warnings.
• Buy: free quote × QUOTE_INVEST_PCT → market buy (createMarketOrderWithCost / quoteOrderQty / fallbacks in code).
• Sell: market all free base (precision-rounded).
• Testnet: BINANCE_TESTNET=true or 1 → CCXT sandbox.

This is a simple executor, not a full OMS: no built-in fill analytics or slippage model.

Copy .env.example to .env. Do not commit .env.

Invalid Zod config or EMA_FAST >= EMA_SLOW → exit on startup.

• Least privilege: dedicated API key, no withdrawal (if the venue allows), IP allowlist in production.
• Secrets via env or a secret manager — never in git.
• Testnet first: testnet.binance.vision.
• Host: dedicated OS user, lock down .env permissions.
• This repo does not encrypt keys on disk.

Requires: Node 20+, npm.

npm install

# Windows
copy .env.example .env
# macOS / Linux
cp .env.example .env

For first runs use DRY_RUN=true and BINANCE_TESTNET=true until behavior matches what you expect.

npm run dev

Production-style (compiled):

npm run build
npm start

Typecheck:

npm run typecheck

Stop: Ctrl+C or SIGTERM. There is no automatic cancel-all-orders on exit — use the exchange UI if needed.

• Logs: timestamp (bar time), close=…, strategy detail, BUY / SELL / HOLD, and whether action was already taken for that bar. Tick errors are logged; the loop continues.
• Monitoring: ship logs to your stack; alert on repeated tick error or process death.
• Network: transient failures show as errors; the bot does not implement custom reconnection beyond CCXT.
• What counts as “real” paper: DRY_RUN=true (engine runs, no orders) or testnet with small size — that is your operational record. Anything you export from the exchange (or testnet) is your authoritative trade history.

• No stop-loss / take-profit / trailing in the strategy layer.
• No on-disk position DB — restarts can re-touch the last closed bar on the first tick; be aware around bar boundaries.
• Fees and slippage not modeled in the bot.
• Single symbol, single thread.

This repository does not store or export fills. Your history comes from:

1. Binance (or testnet): Orders / Trade History / account Export (CSV) for the date range.
2. This bot’s logs: stdout lines with BUY/SELL/HOLD — redirect to a file and pair timestamps with exchange IDs from the app or API.
3. Spreadsheet or journal: sum realized P&L per week or per round-trip; subtract fees (Binance schedule applies).

DRY_RUN and testnet give you a realistic run of the same code paths without mainnet capital — still not a substitute for legal/tax recordkeeping; use exchange exports for that.

The tables below are synthetic numbers for layout — they are not from Binance, not from a linked account, and not produced by a built-in backtest in this repo. They show how you might present a weekly summary and a small blotter after you paste your data.

Run metadata (fill with your run)

Illustrative net over the sample window (table only): about +4.0 USDT — not a performance claim; replace with your exports.

Replace with your exchange order or trade IDs.

Bottom line: treat exchange and tax records as ground truth. Use this bot’s config and logs to explain what the automation did, and use the journal format above (or your own) to track real P&L over time.

This project is provided as is without warranty. Add a LICENSE file if you need explicit terms. Authors and contributors are not liable for trading losses, API issues, or incidents arising from your keys or environment.

For production suitability, do your own review, security review, and smallest-size live test after compliance sign-off.