scanning-market-movers

# Scanning Market Movers

## Overview

Real-time detection and analysis of significant price movements and unusual volume patterns across cryptocurrency markets. This skill identifies top gainers, losers, and volume spikes, ranking them by a composite significance score.

**Key Features:**
- Scan 1,000+ cryptocurrencies for movers
- Configurable thresholds (change %, volume spike, market cap)
- Significance scoring for prioritization
- Category filtering (DeFi, L2, NFT, etc.)
- Multiple output formats (table, JSON, CSV)

**Dependency:**
This skill uses `tracking-crypto-prices` from `market-price-tracker` plugin for price data infrastructure.

## Prerequisites

Install required dependencies:

```bash
pip install requests pandas
```

**Dependency Setup:**
Ensure `market-price-tracker` plugin is installed with `tracking-crypto-prices` skill configured.

## Instructions

### Step 1: Quick Market Scan

Run a default scan for top gainers and losers:

```bash
python {baseDir}/scripts/scanner.py
```

This returns the top 20 gainers and top 20 losers by 24h change with volume confirmation.

### Step 2: Custom Thresholds

Scan with specific criteria:

```bash
# Only show moves > 10% with volume spike > 3x
python {baseDir}/scripts/scanner.py --min-change 10 --volume-spike 3

# Filter by market cap
python {baseDir}/scripts/scanner.py --min-cap 100000000 --max-cap 1000000000
```

### Step 3: Category Filtering

Focus on specific sectors:

```bash
# DeFi tokens only
python {baseDir}/scripts/scanner.py --category defi

# Layer 2 tokens
python {baseDir}/scripts/scanner.py --category layer2

# Available: defi, layer2, nft, gaming, meme
```

### Step 4: Different Timeframes

Scan across timeframes:

```bash
# 1-hour movers
python {baseDir}/scripts/scanner.py --timeframe 1h

# 7-day movers
python {baseDir}/scripts/scanner.py --timeframe 7d
```

### Step 5: Export Results

Save results for analysis:

```bash
# JSON export
python {baseDir}/scripts/scanner.py --format json --output movers.json

# CSV export
python {baseDir}/scripts/scanner.py --format csv --output movers.csv
```

## Output

### Default Table Output

```
================================================================================
  MARKET MOVERS                                    Updated: 2025-01-14 15:30:00
================================================================================

  TOP GAINERS (24h)
--------------------------------------------------------------------------------
  Rank  Symbol      Price         Change    Vol Ratio   Market Cap    Score
--------------------------------------------------------------------------------
    1   XYZ       $1.234        +45.67%        5.2x      $123.4M      89.3
    2   ABC       $0.567        +32.10%        3.8x       $45.6M      76.5
    3   DEF       $2.890        +28.45%        2.9x      $234.5M      71.2
--------------------------------------------------------------------------------

  TOP LOSERS (24h)
--------------------------------------------------------------------------------
  Rank  Symbol      Price         Change    Vol Ratio   Market Cap    Score
--------------------------------------------------------------------------------
    1   GHI       $3.456        -28.90%        4.1x       $89.1M      72.1
    2   JKL       $0.123        -22.34%        2.5x       $12.3M      58.9
--------------------------------------------------------------------------------

  Summary: 42 movers found | Scanned: 1000 assets
================================================================================
```

### JSON Output (--format json)

```json
{
  "gainers": [
    {
      "rank": 1,
      "symbol": "XYZ",
      "name": "Example Token",
      "price": 1.234,
      "change_24h": 45.67,
      "volume_ratio": 5.2,
      "market_cap": 123400000,
      "significance_score": 89.3,
      "category": "defi"
    }
  ],
  "losers": [...],
  "meta": {
    "scan_time": "2025-01-14T15:30:00Z",
    "thresholds": {
      "min_change": 5,
      "volume_spike": 2,
      "min_market_cap": 10000000
    },
    "total_scanned": 1000,
    "matches": 42
  }
}
```

### Significance Score

The significance score (0-100) combines:
- **Change %** (40%): Larger moves score higher
- **Volume Ratio** (40%): Higher volume confirmation scores higher
- **Market Cap** (20%): Larger caps score slightly higher

Higher scores indicate more significant, higher-conviction moves.

## Configuration

Edit `{baseDir}/config/settings.yaml`:

```yaml
# Default Thresholds
thresholds:
  min_change: 5           # Minimum % change to include
  volume_spike: 2         # Minimum volume ratio (current/avg)
  min_market_cap: 10000000  # $10M minimum
  max_market_cap: null    # No maximum by default

# Scoring Weights
scoring:
  change_weight: 0.40
  volume_weight: 0.40
  cap_weight: 0.20

# Display
display:
  top_n: 20               # Number of results per category
  sort_by: significance   # significance, change, volume, market_cap

# Categories (CoinGecko category IDs)
categories:
  defi:
    - decentralized-finance-defi
    - yield-farming
  layer2:
    - layer-2
    - polygon-ecosystem
    - arbitrum-ecosystem
  nft:
    - non-fungible-tokens-nft
  gaming:
    - gaming
  meme:
    - meme-token
```

### Named Presets

Create presets in `{baseDir}/config/presets/`:

**aggressive.yaml:**
```yaml
min_change: 3
volume_spike: 1.5
min_market_cap: 1000000
top_n: 50
```

**conservative.yaml:**
```yaml
min_change: 10
volume_spike: 3
min_market_cap: 100000000
top_n: 10
```

Use with:
```bash
python {baseDir}/scripts/scanner.py --preset aggressive
```

## Error Handling

See `{baseDir}/references/errors.md` for comprehensive error handling.

### Common Errors

| Error | Cause | Solution |
|-------|-------|----------|
| `Dependency not found` | tracking-crypto-prices unavailable | Install market-price-tracker plugin |
| `No movers found` | Thresholds too strict | Relax thresholds with lower values |
| `Rate limit exceeded` | Too many API calls | Wait or use cached data |
| `Partial results` | Some assets unavailable | Normal, proceed with available data |

## Examples

See `{baseDir}/references/examples.md` for detailed usage examples.

### Example 1: Daily Scan

```bash
python {baseDir}/scripts/scanner.py --timeframe 24h --top 20
```

### Example 2: Volume Spike Hunt

```bash
python {baseDir}/scripts/scanner.py --volume-spike 5 --min-volume 1000000
```

### Example 3: DeFi Movers Export

```bash
python {baseDir}/scripts/scanner.py --category defi --format csv --output defi_movers.csv
```

### Example 4: High-Cap Gainers

```bash
python {baseDir}/scripts/scanner.py --min-cap 1000000000 --gainers-only --top 10
```

## Integration with Other Skills

This skill can be combined with other crypto skills:

**With crypto-signal-generator:**
```bash
# Get movers, then generate signals for top gainers
python {baseDir}/scripts/scanner.py --format json | \
  python ../crypto-signal-generator/.../scanner.py --from-stdin
```

**With arbitrage-opportunity-finder:**
Volume spikes often precede arbitrage opportunities. Use movers as input for arbitrage scanning.

## Files

| File | Purpose |
|------|---------|
| `scripts/scanner.py` | Main CLI entry point |
| `scripts/analyzer.py` | Core analysis logic |
| `scripts/filters.py` | Threshold filtering |
| `scripts/scorers.py` | Significance scoring |
| `scripts/formatters.py` | Output formatting |
| `config/settings.yaml` | User configuration |
| `config/presets/` | Named preset configurations |

## Resources

- PRD.md - Product requirements
- ARD.md - Architecture documentation
- Depends on: tracking-crypto-prices skill
- CoinGecko API documentation: https://www.coingecko.com/en/api