market-price-tracker - Claude Code Plugin

Documentation

# Market Price Tracker Plugin

Real-time market price tracking across crypto, stocks, forex, and commodities with institutional-grade data feeds and advanced analytics.

## Features

###  Multi-Asset Support
- **Cryptocurrencies**: BTC, ETH, and 10,000+ altcoins
- **Stocks**: US equities, international markets
- **Forex**: Major and exotic currency pairs
- **Commodities**: Gold, silver, oil, agricultural products
- **Indices**: S&P 500, NASDAQ, international indices

###  Data Sources
- **Crypto Exchanges**: Binance, Coinbase, Kraken, FTX, Bitfinex
- **Stock Data**: Alpha Vantage, IEX Cloud, Polygon.io, Yahoo Finance
- **Forex Feeds**: OANDA, Forex Connect, Currency Layer
- **Alternative Data**: Messari, CoinGecko, Quandl

###  Real-Time Capabilities
- **WebSocket Streaming**: Sub-second price updates
- **Multi-Exchange Aggregation**: VWAP and median pricing
- **Latency Monitoring**: Track feed performance
- **Automatic Failover**: Redundant data sources
- **Smart Reconnection**: Exponential backoff strategies

###  Technical Analysis
- **Indicators**: RSI, MACD, Bollinger Bands, ATR, OBV
- **Moving Averages**: SMA, EMA, WMA, VWAP
- **Pattern Recognition**: Head & Shoulders, Triangles, Flags
- **Candlestick Patterns**: Doji, Hammer, Engulfing, Morning Star
- **Market Structure**: Support/Resistance, Liquidity Zones

###  Alert System
- **Price Alerts**: Above/below thresholds
- **Percentage Changes**: Volatility spikes
- **Volume Alerts**: Unusual activity detection
- **Pattern Alerts**: Chart pattern completion
- **Custom Conditions**: Complex alert logic

## Installation

```bash
/plugin install market-price-tracker@claude-code-plugins-plus
```

## FREE Data Sources Configuration

**Track all asset classes using 100% free data sources** - no Polygon.io, Messari, or premium subscriptions required.

### Quick Comparison

| Asset Class | Paid Sources | FREE Sources |
|-------------|-------------|--------------|
| **Crypto** | Messari Pro ($99/mo) | CoinGecko + Binance: **$0** |
| **Stocks** | Polygon.io ($49/mo) | Yahoo Finance + Alpha Vantage: **$0** |
| **Forex** | OANDA Pro ($25/mo) | Currency Layer free tier: **$0** |
| **Commodities** | Quandl ($50/mo) | Alpha Vantage: **$0** |

**Annual Savings: $2,676** with free-tier configuration.

### Free Data Source Matrix

| Asset | Free API | Rate Limit | Signup |
|-------|----------|-----------|--------|
| **Crypto** | CoinGecko | 50 req/min | No |
| **Crypto** | Binance | 1200 req/min | No |
| **Stocks** | Yahoo Finance | Unlimited | No |
| **Stocks** | Alpha Vantage | 500 req/day | Free key |
| **Forex** | Currency Layer | 250 req/mo | Free key |
| **Commodities** | Alpha Vantage | 500 req/day | Free key |

### Free Configuration Template

```json
{
  "dataSources": {
    "crypto": {
      "primary": "coingecko",      // FREE - 50 req/min
      "fallback": ["binance", "coinbase"],  // FREE - no limits
      "useWebSocket": false         // Use REST API (free tier)
    },
    "stocks": {
      "primary": "yfinance",        // FREE - unlimited
      "fallback": ["alphavantage"],  // FREE - 500 req/day
      "apiKeys": {
        "alphavantage": "YOUR_FREE_KEY"  // Get at alphavantage.co
      }
    },
    "forex": {
      "primary": "currencylayer",   // FREE - 250 req/month
      "apiKeys": {
        "currencylayer": "YOUR_FREE_KEY"  // Get at currencylayer.com
      }
    },
    "commodities": {
      "primary": "alphavantage"     // FREE - covers gold, silver, oil
    }
  },
  "updateIntervals": {
    "crypto": 300,      // 5 min (well under free limits)
    "stocks": 60,       // 1 min (Yahoo Finance allows this)
    "forex": 3600,      // 1 hour (free tier: 250 req/month)
    "commodities": 3600 // 1 hour (commodities update slowly anyway)
  }
}
```

### Cost Breakdown: Paid vs Free

#### Paid Approach (Premium APIs)

**Monthly Costs:**
- Polygon.io (stocks): $49/mo
- Messari Pro (crypto): $99/mo
- OANDA Pro (forex): $25/mo
- Quandl Premium (commodities): $50/mo
- **Total: $223/mo → $2,676/year**

#### Free Approach (This Configuration)

**Monthly Costs:**
- CoinGecko (crypto): $0
- Binance API (crypto): $0
- Yahoo Finance (stocks): $0
- Alpha Vantage (stocks/commodities): $0
- Currency Layer free tier (forex): $0
- **Total: $0/mo → $0/year**

**Savings: $2,676/year**

### Real Use Case Examples

#### Crypto Price Tracking (BTC/ETH)

**Free Configuration:**
```javascript
// CoinGecko API - FREE
const prices = await fetch(
  'https://api.coingecko.com/api/v3/simple/price?ids=bitcoin,ethereum&vs_currencies=usd'
);

// Result: { bitcoin: { usd: 45000 }, ethereum: { usd: 3000 } }
```

**Cost:** $0 (vs Messari Pro $99/mo)

#### Stock Price Tracking (AAPL, TSLA, MSFT)

**Free Configuration:**
```javascript
// Yahoo Finance - FREE (via yfinance Python library or direct API)
import yfinance as yf

tickers = yf.Tickers('AAPL TSLA MSFT')
prices = tickers.tickers['AAPL'].history(period='1d')
```

**Cost:** $0 (vs Polygon.io $49/mo)

#### Forex Pair Tracking (EUR/USD)

**Free Configuration:**
```javascript
// Currency Layer free tier - 250 req/month
const response = await fetch(
  `http://api.currencylayer.com/live?access_key=YOUR_FREE_KEY&currencies=EUR,USD`
);
```

**Cost:** $0 for 250 req/month (vs OANDA Pro $25/mo for unlimited)

### Data Quality Comparison

| Metric | Paid APIs | Free APIs |
|--------|----------|-----------|
| **Crypto Coverage** | 5,000+ | 10,000+ ✅ (CoinGecko) |
| **Stock Coverage** | US + International | US + Major International ✅ |
| **Update Frequency** | Real-time | 1-5 min delay ⚠️ |
| **Historical Data** | Full history ✅ | Full history ✅ |
| **Cost** | $2,676/year | $0/year ✅ |

**1-5 minute delay is acceptable for 99% of traders** (not HFT/day trading).

### Free API Key Setup

#### Alpha Vantage (Stocks + Commodities)

1. Visit [alphavantage.co/support/#api-key](https://www.alphavantage.co/support/#api-key)
2. Enter email (no credit card)
3. Get API key instantly
4. Limits: 500 calls/day (sufficient for tracking)

#### Currency Layer (Forex)

1. Visit [currencylayer.com/product](https://currencylayer.com/product)
2. Sign up for free plan
3. Get API key (no credit card)
4. Limits: 250 calls/month (sufficient for hourly updates)

### When Free APIs Are NOT Enough

**Use paid APIs if:**
- You need <100ms real-time updates (day trading)
- You require tick-by-tick data streams
- You need institutional-grade SLA
- Your trading strategy requires sub-second latency

**For 99% of price tracking:** Free APIs with 1-5 min updates are sufficient.

### Smart Rate Limit Management

```json
{
  "rateLimiting": {
    "crypto": {
      "maxCallsPerMinute": 40,  // Under CoinGecko's 50/min limit
      "backoffMultiplier": 2,    // Exponential backoff on errors
      "fallbackEnabled": true    // Auto-switch to Binance if rate limited
    },
    "stocks": {
      "maxCallsPerDay": 400,    // Under Alpha Vantage's 500/day
      "prioritySymbols": ["AAPL", "TSLA"],  // Track these first
      "cacheDuration": 60       // Cache for 1 min to reduce calls
    }
  }
}
```

### Resources

- **CoinGecko:** [coingecko.com/api](https://www.coingecko.com/api) - FREE crypto data
- **Yahoo Finance:** [finance.yahoo.com](https://finance.yahoo.com) - FREE stock data
- **Alpha Vantage:** [alphavantage.co](https://www.alphavantage.co) - FREE key for stocks/commodities
- **Currency Layer:** [currencylayer.com](https://currencylayer.com) - FREE tier for forex
- **Binance API:** [binance-docs.github.io](https://binance-docs.github.io/apidocs) - FREE crypto

**Bottom Line:** Configure this plugin to use 100% free data sources and save $2,676/year while tracking all major asset classes.

---

## Usage

### Track Real-Time Prices

```
/track-price

I'll set up real-time price tracking. Please provide:
- Symbol: BTC/USDT
- Interval: 1s
- Exchanges: binance, coinbase, kraken
- Alerts: above 50000, below 45000
```

The tracker will:
1. Connect to multiple exchanges via WebSocket
2. Aggregate prices using VWAP
3. Display real-time updates
4. Monitor alert conditions
5. Show confidence levels

### Analyze Market Trends

```
/analyze-trends

I'll analyze market trends. Please specify:
- Symbol: AAPL
- Timeframe: 4h
- Period: 30 days
- Analysis type: technical
```

Analysis includes:
- Trend identification and strength
- Momentum indicators (RSI, MACD, Stochastic)
- Pattern detection (chart and candlestick)
- Support/resistance levels
- Trading signals with confidence scores

## Configuration

Create a `.market-tracker.json` configuration file:

```json
{
  "dataSources": {
    "primary": ["binance", "coinbase"],
    "fallback": ["kraken", "coingecko"],
    "aggregation": "VWAP"
  },
  "alerts": {
    "cooldown": 300000,
    "channels": ["console", "email", "webhook"],
    "webhook": "https://your-webhook-url.com"
  },
  "display": {
    "mode": "detailed",
    "updateFrequency": 1000,
    "showExchangePrices": true
  },
  "technical": {
    "indicators": ["RSI", "MACD", "BollingerBands"],
    "periods": {
      "rsi": 14,
      "macd": [12, 26, 9],
      "bollinger": [20, 2]
    }
  }
}
```

## Commands

### Price Tracking

| Command | Description | Shortcut |
|---------|-------------|----------|
| `/track-price` | Real-time price tracking | `tp` |
| `/stop-tracking` | Stop price tracking | `st` |
| `/price-history` | View historical prices | `ph` |

### Analysis

| Command | Description | Shortcut |
|---------|-------------|----------|
| `/analyze-trends` | Technical trend analysis | `at` |
| `/market-structure` | Analyze market structure | `ms` |
| `/find-patterns` | Detect chart patterns | `fp` |

### Alerts

| Command | Description | Shortcut |
|---------|-------------|----------|
| `/set-alert` | Configure price alerts | `sa` |
| `/view-alerts` | List active alerts | `va` |
| `/alert-history` | View triggered alerts | `ah` |

## Data Architecture

### WebSocket Management

```javascript
// Automatic connection management
const wsManager = new WebSocketManager({
  maxReconnectAttempts: 5,
  reconnectDelay: 1000,
  heartbeatInterval: 30000
});

// Multi-exchange connections
wsManager.connect([
  'wss://stream.binance.com:9443/ws',
  'wss://ws-feed.exchange.coinbase.com',
  'wss://ws.kraken.com'
]);
```

### Price Aggregation

```javascript
// VWAP calculation across exchanges
function calculateVWAP(prices) {
  let totalValue = 0;
  let totalVolume = 0;

  for (const price of prices) {
    totalValue += price.price * price.volume;
    totalVolume += price.volume;
  }

  return totalVolume > 0 ? totalValue / totalVolume : 0;
}
```

### Pattern Detection

```javascript
// Head and Shoulders pattern detection
function detectHeadAndShoulders(prices) {
  const peaks = findPeaks(prices);

  if (peaks.length >= 3) {
    const [left, head, right] = peaks.slice(-3);

    if (head.value > left.value &&
        head.value > right.value &&
        Math.abs(left.value - right.value) < 0.03) {
      return {
        detected: true,
        confidence: 85,
        neckline: calculateNeckline(left, head, right)
      };
    }
  }

  return { detected: false };
}
```

## Technical Indicators

### Momentum Indicators
- **RSI (Relative Strength Index)**: Overbought/oversold conditions
- **MACD**: Trend changes and momentum
- **Stochastic Oscillator**: Momentum comparison
- **Williams %R**: Overbought/oversold levels
- **CCI (Commodity Channel Index)**: Trend identification

### Trend Indicators
- **Moving Averages**: SMA, EMA, WMA
- **ADX**: Trend strength measurement
- **Parabolic SAR**: Stop and reverse points
- **Ichimoku Cloud**: Multiple trend components

### Volatility Indicators
- **Bollinger Bands**: Price channels
- **ATR (Average True Range)**: Volatility measurement
- **Standard Deviation**: Price dispersion
- **Keltner Channels**: Volatility-based bands

### Volume Indicators
- **OBV (On-Balance Volume)**: Volume flow
- **Volume Profile**: Price level activity
- **ADL (Accumulation/Distribution)**: Money flow
- **MFI (Money Flow Index)**: Volume-weighted RSI

## Alert Types

### Price-Based Alerts
- Crosses above/below specific price
- Percentage change from reference
- Breaking support/resistance levels
- New daily/weekly/monthly highs/lows

### Technical Alerts
- RSI entering overbought/oversold
- MACD crossovers
- Moving average crossovers
- Bollinger Band squeezes

### Pattern Alerts
- Chart pattern completion
- Candlestick pattern formation
- Trendline breaks
- Fibonacci retracement levels

### Volume Alerts
- Unusual volume spikes
- Volume divergence
- Accumulation/distribution signals

## Performance Optimization

### Caching Strategy
- Price data: 5-second cache
- Technical indicators: 1-minute cache
- Historical data: 24-hour cache
- Pattern detection: 5-minute cache

### Connection Management
- Connection pooling for REST APIs
- WebSocket multiplexing
- Automatic failover to backup sources
- Load balancing across data feeds

### Data Processing
- Streaming data pipeline
- Incremental indicator calculations
- Parallel pattern detection
- Optimized memory usage

## Error Handling

### Connection Errors
- Automatic reconnection with exponential backoff
- Fallback to alternative data sources
- Queue messages during disconnection
- Alert on prolonged outages

### Data Validation
- Sanity checks on price data
- Outlier detection and filtering
- Cross-validation between sources
- Missing data interpolation

### Rate Limiting
- Request throttling per API
- Token bucket algorithm
- Prioritized request queue
- Graceful degradation

## Security Considerations

### API Key Management
- Environment variables for credentials
- Encrypted storage for sensitive data
- Read-only API keys where possible
- Regular key rotation

### Data Integrity
- HMAC signature verification
- TLS/SSL for all connections
- Input sanitization
- Output encoding

## Advanced Features

### Machine Learning Integration
- Price prediction models
- Anomaly detection
- Pattern recognition enhancement
- Sentiment analysis correlation

### Backtesting Support
- Historical data replay
- Strategy testing framework
- Performance metrics calculation
- Risk assessment tools

### Multi-Timeframe Analysis
- Synchronized timeframe views
- Higher timeframe confirmation
- Fractal pattern detection
- Time-based correlations

## Troubleshooting

### Common Issues

**No price updates**
- Check API key configuration
- Verify network connectivity
- Confirm symbol format
- Check exchange status

**Delayed data**
- Review connection latency
- Check cache settings
- Verify time synchronization
- Monitor rate limits

**Incorrect calculations**
- Validate input data
- Check indicator parameters
- Review aggregation method
- Verify timezone settings

## Performance Metrics

- WebSocket latency: < 50ms average
- Price aggregation: < 10ms
- Pattern detection: < 100ms
- Alert processing: < 5ms
- Data throughput: 10,000+ updates/second

## Contributing

This plugin is part of the Claude Code Plugins marketplace. Contributions welcome!

1. Fork the repository
2. Create feature branch
3. Add comprehensive tests
4. Submit pull request

## License

MIT License - See LICENSE file for details

## Support

- GitHub Issues: [Report bugs](https://github.com/jeremylongshore/claude-code-plugins/issues)
- Discord: Claude Code community
- Documentation: [API Reference](https://docs.claude-code-plugins.com)

## Changelog

### v1.0.0 (2024-10-11)
- Initial release
- Multi-exchange real-time tracking
- Technical analysis suite
- Advanced alert system
- Pattern recognition
- WebSocket streaming

---

*Built with ️ for traders by Intent Solutions IO*