How to Build a Whale Tracking Bot with CoinMarketCap API

Introduction

In crypto markets, whales move price.

Large transactions often:

• trigger breakouts
• signal accumulation or distribution
• front-run major market moves

The challenge is not execution.

It is detecting meaningful activity early and filtering noise.

CoinMarketCap’s DEX API provides exactly what you need:

• real transaction flow
• pool-level liquidity
• activity signals
• risk checks

• CoinMarketCap API → signal layer
• Your system → detects and filters whale activity
• Other bots → consume whale signals

System Architecture

CoinMarketCap DEX API

├─ Spot Pairs Discovery

├─ Transaction Flow

├─ Liquidity Data

├─ Security Signals
↓
Whale Detection Engine
↓
Alerts / Signals / Storage

Project Setup

import os
import time
import requests
import pandas as pd

CMC_API_KEY = os.getenv("CMC_API_KEY")
BASE_URL = "https://pro-api.coinmarketcap.com"

HEADERS = {

"Accept": "application/json",
"Content-Type": "application/json",
"X-CMC_PRO_API_KEY": CMC_API_KEY,

}

Step 1: Discover Active Tokens

Endpoint:

/v4/dex/spot-pairs/latest

This endpoint requires a network identifier and a DEX selector.

For example, on Solana you can pass network_slug="solana" and a DEX filter such as dex_slug="raydium".

def discover_pairs(network="solana", dex_slug="raydium"):
url = f"{BASE_URL}/v4/dex/spot-pairs/latest"

params = {
"network_slug": network,
"dex_slug": dex_slug,
"sort": "volume_24h",
"sort_dir": "desc",
"limit": 50
}

r = requests.get(url, headers=HEADERS, params=params, timeout=15)

r.raise_for_status()

return r.json()["data"]

Step 2: Track Whale Transactions

Endpoint:

/v1/dex/tokens/transactions

def fetch_whale_transactions(platform, address, min_volume=10000):
url = f"{BASE_URL}/v1/dex/tokens/transactions"

params = {
"platform": platform,
"address": address,
"minVolume": min_volume,
"limit": 50,
"sortBy": "time",
"sortType": "desc"
}

r = requests.get(url, headers=HEADERS, params=params, timeout=15)
r.raise_for_status()

return r.json()["data"]

Step 3: Normalize Transaction Data

The transaction endpoint uses compressed field names to reduce payload size.

def normalize_transactions(data):
rows = []

for tx in data:
rows.append({
"tx_hash": tx.get("tx"),        # transaction hash
"wallet": tx.get("ma"),        # maker address
"volume_usd": tx.get("v"),     # USD value
"price": tx.get("t0pu"),       # token price in USD when available
"amount": tx.get("a0"),        # base token amount
"side": tx.get("tp"),          # buy / sell type
"timestamp": tx.get("ts"),
"dex": tx.get("en"),           # DEX name
})

return pd.DataFrame(rows)

Step 4: Detect Whale Activity

def detect_whales(df, threshold=50000):
return df[df["volume_usd"] >= threshold]

Step 5: Validate Liquidity

Endpoint:

/v1/dex/token/pools

def fetch_liquidity(platform, address):
url = f"{BASE_URL}/v1/dex/token/pools"

params = {
"platform": platform,
"address": address
}

r = requests.get(url, headers=HEADERS, params=params)
r.raise_for_status()

return r.json()["data"]

Step 6: Filter Risky Tokens

Endpoint:

/v1/dex/security/detail

def fetch_security(platform, address):
url = f"{BASE_URL}/v1/dex/security/detail"

params = {
"platformName": platform,
"address": address
}

try:
r = requests.get(url, headers=HEADERS, params=params, timeout=15)
r.raise_for_status()
return r.json()

except requests.HTTPError as e:
if e.response is not None and e.response.status_code in (400, 403):
return None
raise

except requests.RequestException:
return None

Step 7: Detect Liquidity Events

Endpoint:

/v1/dex/liquidity-change/list

def fetch_liquidity_events(platform, address):
url = f"{BASE_URL}/v1/dex/liquidity-change/list"

params = {
"platform": platform,
"address": address,
"limit": 20
}

r = requests.get(url, headers=HEADERS, params=params)
r.raise_for_status()

return r.json()["data"]

Step 8: Build Whale Signal

def build_signal(tx_df):
if tx_df.empty:
return None

return {
"total_whale_volume": tx_df["volume_usd"].sum(),
"avg_trade_size": tx_df["volume_usd"].mean(),
"num_trades": len(tx_df),
}

Optional Historical Fallback

Historical endpoints can be useful for validating whether whale activity usually leads to continuation or reversal.

Some historical endpoints may be plan-restricted or unavailable for specific pairs.

If historical data fails, keep the whale monitor running with:

• /v4/dex/spot-pairs/latest
• /v1/dex/tokens/transactions
• /v1/dex/token/pools

Treat historical enrichment as optional.

Paid Endpoint Warning

Some advanced endpoints may require paid access.

HTTP 403 Forbidden

Error 1006: Plan Not Authorized

Historical endpoints may also be limited by plan and data availability.

Rate Limit Strategy

• Poll every 30–60 seconds
• Use exponential backoff
• Cache responses

Common Mistakes

• Not filtering volume
• Ignoring liquidity
• Not handling null fields
• Mixing platform formats (v1 vs v4)

Final Thoughts

Whale tracking transforms raw blockchain data into usable trading signals.

CoinMarketCap API provides a structured way to:

• detect large transactions
• validate liquidity
• filter risk

With the right filters, you turn noise into signal.

Next Steps

• track wallet behavior
• combine with momentum
• build alerts
• integrate with trading bots

Better signals lead to better decisions.