🖼️ NFT Floor Price Tracker

Monitor NFT collection floor prices & get real-time Telegram alerts on pumps/dumps — powered by OpenSea API v2 + CoinGecko.

---

🔍 What is NFT Floor Tracking?

NFT floor tracking monitors the lowest listed price of an NFT collection in real-time — helping traders catch early signals of pumps, dumps, and volume spikes before the market reacts.

This bot tracks collections using:

• 🌊 OpenSea API v2 — floor price, volume, sales & collection stats
• 💰 CoinGecko API — ETH/USD price conversion
• 🤖 Telegram Bot — real-time alerts & interactive commands

---

✨ Features

• 💎 Floor Price Tracking — real-time floor in ETH & USD
• 📈 Pump/Dump Alerts — notify when floor moves >10% or >20%
• 📊 Volume Spike Alerts — notify when 24h volume spikes >50%
• 🛒 Recent Sales — latest sales per collection
• 🏆 Top Collections — top NFTs by 24h volume
• 🔍 Collection Search — find collections by name
• 👀 Watchlist — monitor multiple collections simultaneously
• 📡 Auto Monitor — background polling every 5 minutes
• 🤖 Telegram Bot — 9 interactive commands

---

🚀 Quick Start

1. Install dependencies

pip install requests

2. Get OpenSea API Key

1. Go to opensea.io/developers
2. Sign up & generate free API key
3. Free tier: 4 req/sec

3. Set API keys

Open nft_floor_tracker.py and configure:

OPENSEA_API_KEY  = "your_opensea_api_key"
TELEGRAM_TOKEN   = "your_telegram_bot_token"
TELEGRAM_CHAT_ID = "your_chat_id"

4. Run as Telegram Bot

python nft_floor_tracker.py

5. Quick CLI check (one-time)

python nft_floor_tracker.py check pudgypenguins

---

🤖 Telegram Commands

Command	Description
/floor <slug>	Get current floor price
/add <slug>	Add collection to watchlist
/remove <slug>	Remove from watchlist
/list	Show tracked collections
/sales <slug>	Recent sales
/top	Top collections by 24h volume
/search <name>	Search collection by name
/monitor on/off	Toggle auto monitoring
/known	Show known collection slugs

---

📊 Sample Output

🖼️ CryptoPunks
━━━━━━━━━━━━━━━━━━━━━━
💎 Floor      : 30.4900 ETH (~$61,560.83)
📊 Vol 24h    : 0.00 ETH
📅 Vol 7d     : 0.00 ETH
🛒 Sales 24h  : 0
👥 Owners     : 3,847 / 0 (0% unique)

⏰ 2026-05-31T07:32:45

---

🚨 Alert System

Alert	Trigger	Severity
📉 Floor Drop	Floor decreases >10%	MEDIUM
📉 Floor Drop	Floor decreases >20%	HIGH 🔴
📈 Floor Pump	Floor increases >20%	MEDIUM
📈 Floor Pump	Floor increases >50%	HIGH 🟢
📊 Volume Spike	24h volume increases >50%	MEDIUM 🟡

---

🏗️ Architecture

nft_floor_tracker.py
├── OpenSeaClient       → OpenSea API v2 integration
│   ├── get_collection()      → floor price, volume, stats
│   ├── get_recent_sales()    → latest sales events
│   ├── get_top_collections() → top by 24h volume
│   ├── search_collection()   → find by name/slug
│   └── _get_eth_price()      → ETH/USD via CoinGecko
├── NFTFloorTracker     → Core tracking engine
│   ├── add_collection()      → add to watchlist
│   ├── remove_collection()   → remove from watchlist
│   ├── refresh()             → refresh + detect alerts
│   ├── refresh_all()         → scan all watchlist
│   └── get_price_change()    → session change %
└── NFTFloorBot         → Telegram bot with 9 commands
    └── _monitor_loop()       → background polling thread

---

📡 Data Sources

Source	Usage
OpenSea API v2	Floor price, volume, sales, collections
CoinGecko API	ETH/USD price conversion

---

📋 Known Collection Slugs

Collection	Slug
Bored Ape Yacht Club	boredapeyachtclub
CryptoPunks	cryptopunks
Mutant Ape Yacht Club	mutant-ape-yacht-club
Azuki	azuki
Pudgy Penguins	pudgypenguins
Clone X	clonex
Milady Maker	milady
DeGods	degods

---

⚙️ Configuration

Variable	Default	Description
FLOOR_DROP_ALERT	10%	Minimum drop % to trigger alert
FLOOR_PUMP_ALERT	20%	Minimum pump % to trigger alert
VOLUME_SPIKE_ALERT	50%	Minimum volume spike % to trigger alert
POLL_INTERVAL	300s	How often to check (5 minutes)

---

⚠️ Disclaimer

This tool is for informational purposes only. NFT markets are highly volatile. Always do your own research.

---

🔧 Requirements

requests>=2.28.0

No Web3.py required — uses REST APIs only!

---

👤 Author

Rizal — @rizalcodes

Building Web3 tools with Python 🐍⛓️

---

📄 License

MIT License — free to use, modify, and distribute.