Crypto Market

# Cryptocurrency Market & Price Alerts

A cryptocurrency market data fetching and price monitoring tool based on the CCXT library. It supports multiple exchanges, real-time monitoring, and smart alerts.

## Features

- 🏢 **Multi-Exchange Support** - Defaults to Binance. Also supports OKX, Bybit, Gate.io, KuCoin, etc.
- 📊 **Real-time Market Data** - Get the latest prices, price changes, volumes, and more.
- 📈 **OHLCV Data (Candlesticks)** - Fetch historical price trends.
- 📖 **Order Book** - View market depth (bids and asks).
- 🔔 **Price Alerts** - Supports price thresholds and percentage change alerts.
- 👁️ **Live Monitoring** - Continuously monitor price movements.

## Prerequisites

### Install Dependencies

```bash
pip3 install ccxt --user
```

## Usage

### Check Real-Time Prices

```bash
# Default (Binance)
python3 scripts/crypto.py ticker BTC/USDT

# Use other exchanges
python3 scripts/crypto.py -e okx ticker ETH/USDT
python3 scripts/crypto.py -e bybit ticker BTC/USDT
```

**Supported Exchanges**:
- `binance` - Binance (Default)
- `okx` - OKX
- `bybit` - Bybit
- `gateio` - Gate.io
- `kucoin` - KuCoin
- `huobi` - Huobi
- `coinbase` - Coinbase
- `kraken` - Kraken
- `bitfinex` - Bitfinex

### Get OHLCV (Candlestick) Data

```bash
# Get 1-hour candles, last 24 periods
python3 scripts/crypto.py ohlcv BTC/USDT --timeframe 1h --limit 24

# Get daily candles, last 30 periods
python3 scripts/crypto.py ohlcv ETH/USDT --timeframe 1d --limit 30
```

**Timeframes**:
- `1m` - 1 minute
- `5m` - 5 minutes
- `15m` - 15 minutes
- `1h` - 1 hour
- `4h` - 4 hours
- `1d` - 1 day
- `1w` - 1 week
- `1M` - 1 month

### View Order Book

```bash
python3 scripts/crypto.py orderbook BTC/USDT --limit 10
```

### Live Price Monitoring

```bash
# Refresh every 10 seconds (default)
python3 scripts/crypto.py watch BTC/USDT

# Refresh every 5 seconds
python3 scripts/crypto.py watch ETH/USDT --interval 5
```

## Price Alerts

### Add Alerts

**Price Threshold Alerts:**
```bash
# Alert when BTC price breaks above 70000 USDT
python3 scripts/crypto.py alert-add BTC/USDT above 70000

# Alert when ETH price drops below 3000 USDT
python3 scripts/crypto.py alert-add ETH/USDT below 3000
```

**Percentage Change Alerts:**
```bash
# Alert when BTC rises more than 5%
python3 scripts/crypto.py alert-add BTC/USDT up_percent 5

# Alert when ETH drops more than 3%
python3 scripts/crypto.py alert-add ETH/USDT down_percent 3
```

### View Alert List

```bash
python3 scripts/crypto.py alert-list
```

Example Output:
```
🔔 Price Alerts (3):

ID                        Pair            Exchange     Condition                 Status
------------------------------------------------------------------------------------------
BTC/USDT_1706941200       BTC/USDT        binance      Price > 70000             ⏳Monitoring
ETH/USDT_1706941300       ETH/USDT        okx          Price < 3000              ⏳Monitoring
BTC/USDT_1706941400       BTC/USDT        binance      Rise > 5%                 ⏳Monitoring
```

### Check Alerts

```bash
# Manually check all alert conditions
python3 scripts/crypto.py alert-check
```

When a condition is triggered, it shows:
```
⚠️  Triggered 1 alert:

  🚀 BTC/USDT rose by 5.23%, current price: 71234.56
  Alert ID: BTC/USDT_1706941400
```

### Remove Alerts

```bash
python3 scripts/crypto.py alert-remove BTC/USDT_1706941200
```

## Command Reference

| Command | Function | Example |
|------|------|------|
| `ticker` | Real-time prices | `ticker BTC/USDT` |
| `ohlcv` | Candlestick data | `ohlcv BTC/USDT --timeframe 1h` |
| `orderbook` | Order book | `orderbook BTC/USDT` |
| `watch` | Live monitoring | `watch BTC/USDT --interval 5` |
| `alert-add` | Add an alert | `alert-add BTC/USDT above 70000` |
| `alert-remove` | Remove an alert | `alert-remove ID` |
| `alert-list` | List alerts | `alert-list` |
| `alert-check` | Check alerts | `alert-check` |

### Global Arguments

| Argument | Short | Description | Default |
|------|------|------|--------|
| `--exchange` | `-e` | Exchange name | `binance` |
| `--timeframe` | `-t` | Candlestick timeframe | `1h` |
| `--limit` | `-l` | Data limit (count) | `24` |
| `--interval` | `-i` | Refresh interval (sec) | `10` |

## Alert Conditions

| Condition | Description | Example |
|------|------|------|
| `above` | Price goes above threshold | `above 70000` |
| `below` | Price drops below threshold | `below 3000` |
| `up_percent` | Price rises by % | `up_percent 5` |
| `down_percent` | Price drops by % | `down_percent 3` |

## Use Cases

### Scenario 1: Tracking specific price targets
```bash
# Alert when BTC breaks previous high
python3 scripts/crypto.py alert-add BTC/USDT above 69000

# Regularly check
python3 scripts/crypto.py alert-check
```

### Scenario 2: Monitoring support/resistance levels
```bash
# ETH drops below key support
python3 scripts/crypto.py alert-add ETH/USDT below 2800

# BTC breaks resistance
python3 scripts/crypto.py alert-add BTC/USDT above 72000
```

### Scenario 3: Volatility monitoring
```bash
# Monitor massive volatility
python3 scripts/crypto.py alert-add BTC/USDT up_percent 8
python3 scripts/crypto.py alert-add BTC/USDT down_percent 8
```

### Scenario 4: Cross-exchange price comparison
```bash
# Check prices across different exchanges
python3 scripts/crypto.py -e binance ticker BTC/USDT
python3 scripts/crypto.py -e okx ticker BTC/USDT
python3 scripts/crypto.py -e bybit ticker BTC/USDT
```

## Troubleshooting

**Error: ccxt library not installed**
→ Run: `pip3 install ccxt --user`

**Error: Unsupported exchange**
→ Check exchange spelling. Refer to the supported exchanges list.

**Error: Trading pair does not exist**
→ Check trading pair format, e.g., `BTC/USDT`, `ETH/USDT`.

**Alert not triggering**
→ Confirm alert conditions are correct. Run `alert-check` to check manually.

**API Limits**
→ Some exchanges have strict rate limits. Use `--interval` to adjust the refresh frequency.

## Configuration File

Alert configurations are stored at: `~/.config/crypto/alerts.json`

You can manually edit this file to batch manage your alerts.

## References

- CCXT Documentation: https://docs.ccxt.com/
- Supported Exchanges List: [references/exchanges.md](references/exchanges.md)