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#

text

================================================================================
  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#

ErrorCauseSolutionDependency not foundtracking-crypto-prices unavailableInstall market-price-tracker pluginNo movers foundThresholds too strictRelax thresholds with lower valuesRate limit exceededToo many API callsWait or use cached dataPartial resultsSome assets unavailableNormal, 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#

FilePurposescripts/scanner.pyMain CLI entry pointscripts/analyzer.pyCore analysis logicscripts/filters.pyThreshold filteringscripts/scorers.pySignificance scoringscripts/formatters.pyOutput formattingconfig/settings.yamlUser configurationconfig/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