BTST Stock Screener

A command-line tool for identifying Buy Today, Sell Tomorrow (BTST) trading opportunities in the Indian NSE stock market. The screener analyzes stocks using technical indicators, volume patterns, delivery data, and market sentiment to generate actionable trading signals.

Features

• Real-time NSE Data: Fetches live stock data using the stock-nse-india package
• Multi-criteria Analysis: Evaluates stocks based on:
  • Liquidity and volume requirements
  • Delivery percentage (20-60% range)
  • Technical breakouts with volume confirmation
  • Bullish candlestick patterns (Marubozu, Bullish Engulfing)
  • RSI momentum (60-80 range)
  • EMA trend analysis (20/50 EMA crossover)
  • VWAP support levels
• Market Sentiment Monitoring: Tracks Nifty 50 movement and FII/DII activity
• Risk Management: Provides entry price, stop loss (2%), and target price (1.5%)
• Ranked Results: Signals sorted by number of criteria met
• JSON Export: Save results for further analysis

Installation

Prerequisites

• Node.js v18 or higher
• npm or yarn

Install from npm (when published)

npm install -g btst-stock-screener

Install from source

# Clone the repository
git clone <repository-url>
cd btst-stock-screener

# Install dependencies
npm install

# Build the project
npm run build

# Link globally (optional)
npm link

Usage

Basic Scan

Run a full scan of Nifty 50 and F&O stocks:

btst-screener scan

Export Results to JSON

Save scan results to a JSON file:

btst-screener scan --export results.json

Scan Specific Symbols

Analyze only specific stocks:

btst-screener scan --symbols RELIANCE,TCS,INFY

Verbose Mode

Enable detailed logging for debugging:

btst-screener scan --verbose

Development Mode

Run without building:

npm run dev scan

Configuration

The screener can be customized using a configuration file located at ~/.btst-screener/config.json.

Configuration File Structure

{
  "liquidity": {
    "minVolume": 100000,
    "allowedLists": ["NIFTY50", "FO"]
  },
  "delivery": {
    "minPercentage": 20,
    "maxPercentage": 60
  },
  "technical": {
    "rsi": {
      "period": 14,
      "minValue": 60,
      "maxValue": 80
    },
    "ema": {
      "shortPeriod": 20,
      "longPeriod": 50,
      "minSlope": 0.1
    },
    "breakout": {
      "resistancePeriod": 20,
      "volumeMultiplier": 1.5
    },
    "vwap": {
      "supportThreshold": 80,
      "startTime": "13:30",
      "endTime": "15:00"
    }
  },
  "risk": {
    "stopLossPercent": 2,
    "targetPercent": 1.5
  },
  "sentiment": {
    "niftyDeclineThreshold": -1,
    "fiiSellingThreshold": 1000
  },
  "retry": {
    "maxAttempts": 3,
    "delayMs": 2000
  },
  "timing": {
    "validEntryStart": "13:30",
    "validEntryEnd": "15:00",
    "exitWindowStart": "09:20",
    "exitWindowEnd": "09:45"
  }
}

Configuration Options

Liquidity Settings

• minVolume: Minimum average daily volume (default: 100,000 shares)
• allowedLists: Stock lists to scan (default: ["NIFTY50", "FO"])

Delivery Percentage

• minPercentage: Minimum delivery percentage (default: 20%)
• maxPercentage: Maximum delivery percentage (default: 60%)

Technical Indicators

• RSI: Period, minimum and maximum values
• EMA: Short/long periods, minimum slope for trend confirmation
• Breakout: Resistance calculation period, volume multiplier
• VWAP: Support threshold percentage, time window for analysis

Risk Management

• stopLossPercent: Stop loss percentage below entry (default: 2%)
• targetPercent: Target profit percentage above entry (default: 1.5%)

Market Sentiment

• niftyDeclineThreshold: Nifty decline percentage to trigger warning (default: -1%)
• fiiSellingThreshold: FII selling amount in crores to trigger warning (default: 1000)

Retry and Timing

• maxAttempts: Number of retry attempts for failed data fetches (default: 3)
• delayMs: Delay between retries in milliseconds (default: 2000)
• validEntryStart/End: Valid time window for entry signals
• exitWindowStart/End: Recommended exit time window next day

Output Format

Console Table

The screener displays results in a formatted table:

┌──────────┬─────────┬───────────┬─────────┬──────────────┬──────────────┬────────────────────────────────┐
│ Symbol   │ Entry   │ Stop Loss │ Target  │ Delivery %   │ Criteria Met │ Reasons                        │
├──────────┼─────────┼───────────┼─────────┼──────────────┼──────────────┼────────────────────────────────┤
│ RELIANCE │ 2500.00 │ 2450.00   │ 2537.50 │ 45.2%        │ 5            │ • Breakout above resistance    │
│          │         │           │         │              │              │ • RSI momentum above 60        │
│          │         │           │         │              │              │ • Bullish EMA crossover        │
│          │         │           │         │              │              │ • Strong VWAP support          │
│          │         │           │         │              │              │ • Bullish Engulfing pattern    │
└──────────┴─────────┴───────────┴─────────┴──────────────┴──────────────┴────────────────────────────────┘

Market Warnings:
⚠ Heavy FII selling detected

Scan Statistics:
• Total stocks scanned: 200
• Signals generated: 12
• Errors encountered: 3
• Execution time: 45.2s

JSON Export

When using the --export flag, results are saved in the following format:

{
  "timestamp": "2025-11-07T14:30:00.000Z",
  "signals": [
    {
      "symbol": "RELIANCE",
      "entryPrice": 2500.00,
      "stopLoss": 2450.00,
      "targetPrice": 2537.50,
      "deliveryPercentage": 45.2,
      "reasons": [
        "Breakout above resistance with high volume",
        "RSI momentum above 60",
        "Bullish EMA crossover with upward trend",
        "Strong VWAP support indicating institutional buying",
        "Bullish Engulfing pattern"
      ],
      "criteriaCount": 5,
      "timestamp": "2025-11-07T14:30:00.000Z"
    }
  ],
  "warnings": [
    "Heavy FII selling detected"
  ],
  "stats": {
    "totalScanned": 200,
    "signalsGenerated": 12,
    "errors": 3,
    "executionTime": 45.2
  }
}

Understanding the Signals

Entry Criteria

A stock generates a BTST signal when it meets the following base requirements:

1. Liquidity: Part of Nifty 50 or F&O list with volume > 100,000 shares
2. Delivery: Delivery percentage between 20-60%
3. At least one technical criterion:
   • Breakout above 20-day resistance with 1.5x volume
   • Bullish candlestick pattern (Marubozu or Bullish Engulfing)
   • RSI between 60-80
   • 20 EMA > 50 EMA with both trending up
   • Price above VWAP for 80%+ of time (1:30-3:00 PM)

Signal Ranking

Signals are ranked by the number of criteria met. Stocks meeting more criteria are considered stronger candidates.

Risk Parameters

• Entry Price: Current market price at scan time
• Stop Loss: 2% below entry price (configurable)
• Target: 1.5% above entry price (configurable)
• Exit Window: 9:20 AM - 9:45 AM next trading day

Market Warnings

The screener monitors overall market conditions and displays warnings for:

• Nifty 50 decline > 1% during the day
• FII net selling > 1000 crores

Signals are still generated when warnings are present, allowing you to make the final trading decision.

Troubleshooting

Common Issues

1. "Failed to fetch data for multiple stocks"

Cause: Network connectivity issues or NSE API rate limiting

Solution:

• Check your internet connection
• Wait a few minutes and retry
• The screener will automatically retry failed requests 3 times
• If > 50% of stocks fail, the scan will abort

2. "Insufficient data available"

Cause: More than 50% of stocks failed to fetch data

Solution:

• Check if NSE services are operational
• Try running the scan during market hours (9:15 AM - 3:30 PM IST)
• Verify the stock-nse-india package is properly installed

3. "No signals generated"

Cause: No stocks met the screening criteria

Solution:

• This is normal during bearish market conditions
• Try adjusting configuration thresholds (e.g., lower RSI minimum)
• Run the scan closer to market close (2:00-3:00 PM) for better signals

4. Configuration file not loading

Cause: Invalid JSON syntax or incorrect file location

Solution:

• Verify the config file is at ~/.btst-screener/config.json
• Validate JSON syntax using a JSON validator
• Check file permissions
• Run with --verbose flag to see configuration loading details

5. "Module not found" errors

Cause: Dependencies not installed or build not completed

Solution:

# Reinstall dependencies
npm install

# Rebuild the project
npm run build

# If globally installed, relink
npm link

Best Practices

1. Timing: Run scans between 1:30 PM - 3:00 PM IST for best results
2. Market Conditions: Avoid BTST trades during high market volatility or negative sentiment
3. Position Sizing: Never risk more than 1-2% of capital per trade
4. Stop Loss: Always honor the stop loss - exit if price falls 2% below entry
5. Exit Discipline: Exit during the recommended window (9:20-9:45 AM) next day
6. Verification: Always verify signals manually before placing trades

Debug Mode

Enable verbose logging to troubleshoot issues:

btst-screener scan --verbose

This will show:

• Data fetch operations for each stock
• Filter evaluation results
• Technical indicator calculations
• Error details with stack traces

Limitations

• Data Dependency: Relies on stock-nse-india package availability
• Market Hours: Best results during active trading hours
• Historical Data: Requires sufficient historical data (50+ days)
• Intraday Data: VWAP analysis requires intraday price data
• No Guarantee: Past performance and technical patterns don't guarantee future results

Disclaimer

This tool is for educational and informational purposes only. It does not constitute financial advice. Trading in stocks involves risk, and you should conduct your own research and consult with a financial advisor before making any investment decisions. The authors and contributors are not responsible for any financial losses incurred from using this tool.

Contributing

Contributions are welcome! Please feel free to submit issues or pull requests.

License

ISC

Support

For issues, questions, or feature requests, please open an issue on the GitHub repository.