Binance Alpha Explorer

# Binance Alpha New Coin Launch Monitor

A real-time cryptocurrency listing monitor based on the Binance WebSocket API. It tracks the `!miniTicker@arr` stream to instantly detect and alert you when new trading pairs are listed.

## How It Works

1. **WebSocket Connection** - Connects to the Binance streaming API (`!miniTicker@arr`).
2. **Symbol Detection** - Maintains a `known_symbols` set to identify newly appearing trading pairs.
3. **Price Validation** - Verifies via REST API that the new pair has a valid opening price.
4. **Real-time Alerts** - Outputs new coin listing information immediately.

## Features

- ⚡ **Real-time Detection** - WebSocket streaming data with millisecond latency.
- 🎯 **Accurate Filtering** - Automatically filters out system symbols and invalid data.
- ✅ **Price Confirmation** - Dual verification ensures the pair is actually open for trading.
- 💾 **State Persistence** - Saves known pairs and historical alert records.
- 🔄 **Auto-Reconnect** - Automatically reconnects on drops to ensure uninterrupted monitoring.

## Prerequisites

### Install Dependencies

```bash
pip3 install websocket-client --user
```

## Usage

### Start Monitoring

```bash
python3 scripts/alpha.py monitor
```

Example Output:
```
🚀 Binance Alpha New Coin Monitor
==================================================
📂 Loaded 1847 known trading pairs
✅ WebSocket connected successfully
📊 Monitoring started... Known pairs: 1847
⏳ Waiting for new coin listings...

======================================================================
🚀🚀🚀 New Coin Listing Detected! 🚀🚀🚀
======================================================================
⏰ Time: 2024-02-03T15:42:18.123456
🪙 Pair: BTCUSDT
💰 Current Price: 43250.50
📊 Open Price: 43100.00
📈 24h Change: 150.50 (0.35%)
📦 24h Volume: 15234.56
💵 24h Quote Vol: 658923456.78
======================================================================
```

### View Alert History

```bash
# View last 20 alerts
python3 scripts/alpha.py history

# View last 50 alerts
python3 scripts/alpha.py history --limit 50
```

Example Output:
```
📜 Alert History (Last 3):

⏰ 2024-02-03T15:42:18.123456
🪙 BTCUSDT
💰 Price: 43250.50
📊 Change: 0.35%
--------------------------------------------------
⏰ 2024-02-03T14:30:22.654321
🪙 ETHUSDT
💰 Price: 2650.30
📊 Change: 1.20%
--------------------------------------------------
```

### Check Status

```bash
python3 scripts/alpha.py status
```

Output:
```
📊 Current Status:

  Known Pairs: 1847
  Total Alerts: 15
  State Directory: /Users/xxx/.config/alpha

  Latest Alert:
    Time: 2024-02-03T15:42:18.123456
    Pair: BTCUSDT
```

### Reset Data

If you need to restart monitoring from scratch (clears all history):

```bash
python3 scripts/alpha.py reset
```

⚠️ **Warning**: This will clear all known trading pairs and alert history!

## Technical Details

### WebSocket Data Source

**Endpoint**: `wss://stream.binance.com:9443/ws/!miniTicker@arr`

**Data Format**:
```json
[
  {
    "e": "24hrMiniTicker",
    "E": 1234567890123,
    "s": "BTCUSDT",
    "c": "43250.50",
    "o": "43100.00",
    "h": "43500.00",
    "l": "42800.00",
    "v": "15234.56",
    "q": "658923456.78"
  }
]
```

Field Descriptions:
- `s` - Symbol (Trading Pair)
- `c` - Latest Price
- `o` - Open Price
- `h` - High Price
- `l` - Low Price
- `v` - Base Volume
- `q` - Quote Volume

### Detection Logic

1. Receives all pair data from the `!miniTicker@arr` stream.
2. Extracts the `s` (symbol) field from each packet.
3. Checks if the symbol exists in the `known_symbols` set.
4. If not, verifies price validity via REST API.
5. Once confirmed, triggers an alert and adds the symbol to `known_symbols`.

### Price Verification

Double-checks via Binance REST API:
```
GET /api/v3/ticker/price?symbol=XXX
```

Ensures the trading pair has a valid opening price (price > 0).

## Configuration Files

State files are stored at: `~/.config/alpha/`

- `known_symbols.json` - Set of currently known trading pairs.
- `alerts_history.json` - Historical alert records (last 100).

## Command Reference

| Command | Function | Example |
|------|------|------|
| `monitor` | Start monitoring | `alpha.py monitor` |
| `history` | View history | `alpha.py history --limit 50` |
| `status` | View status | `alpha.py status` |
| `reset` | Reset data | `alpha.py reset` |

## Environment

- Python 3.7+
- Internet connection (access to Binance)
- No API Key required (uses public WebSocket streams)

## Use Cases

### Scenario 1: First to spot new listings
```bash
# Keep monitor running
python3 scripts/alpha.py monitor

# Get immediate terminal alerts when a new coin is listed
```

### Scenario 2: Tracking recent listings
```bash
# Review recently discovered coins
python3 scripts/alpha.py history --limit 10
```

### Scenario 3: Periodic resets
```bash
# Reset weekly to rebuild the baseline
python3 scripts/alpha.py reset
```

## Troubleshooting

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

**Connection Drops**
→ The program automatically reconnects. No manual intervention needed.

**False Positives (Existing coins show as new)**
→ Run `alpha.py reset` to flush and rebuild the known symbols data.

**No Alerts Triggering**
→ Confirm Binance actually listed a new coin. Check your network connection.

**How to integrate with a notification system?**
→ Modify the `alert_new_coin` function in the script to add email/SMS/Webhook logic.

## Notes

1. **Network** - Requires access to Binance WebSocket servers.
2. **Memory** - The symbol set consumes a few MBs of RAM.
3. **False Positives** - Occasional duplicate alerts may happen due to network instability.
4. **Spot Only** - Monitors spot trading pairs only, excluding futures/derivatives.

## References

- Binance WebSocket API: https://binance-docs.github.io/apidocs/spot/en/#websocket-market-streams
- miniTicker Docs: [references/binance_ws.md](references/binance_ws.md)