README.md

---
title: MEXC Funding Rate Report API
emoji: 📈
colorFrom: green
colorTo: blue
sdk: docker
pinned: false
license: mit
app_port: 7860
---

# MEXC Funding Rate Report API

Real-time Funding Rate monitoring API for MEXC Futures.

## Features

- 📊 **Top 5 FR**: Positive, Negative, and Potential coins
- 👀 **Watchlist**: Track specific coins with historical data
- 📈 **FR History**: Hourly snapshots stored in MongoDB
- 🤖 **Telegram Bot**: Automated notifications
- ⏱️ **Per-coin Countdown**: Next funding settlement time

## API Endpoints

| Endpoint | Method | Description |
|----------|--------|-------------|
| `/` | GET | Health check |
| `/docs` | GET | Swagger documentation |
| `/api/v1/funding-rates/top-positive` | GET | Top 5 positive FR |
| `/api/v1/funding-rates/top-negative` | GET | Top 5 negative FR |
| `/api/v1/funding-rates/potential` | GET | Top 5 by opportunity |
| `/api/v1/watchlist` | GET/POST | Manage watchlist |
| `/api/v1/watchlist/{symbol}` | DELETE | Remove from watchlist |
| `/api/v1/watchlist/history/{symbol}` | GET | FR history for coin |

## Environment Variables

Set these in **Hugging Face Spaces Secrets**:

| Variable | Required | Description |
|----------|----------|-------------|
| `MONGODB_URL` | ✅ | MongoDB connection string |
| `TELEGRAM_BOT_TOKEN` | ❌ | Telegram bot token |
| `TELEGRAM_CHAT_ID` | ❌ | Your Telegram chat ID |

## Quick Start

### Deploy to Hugging Face Spaces

1. Create new Space with **Docker** SDK
2. Upload all files from this repository
3. Add secrets in Space Settings:
   - `MONGODB_URL`: Your MongoDB Atlas connection string
4. Space will build and deploy automatically

### Local Development

```bash
# Create virtual environment
python -m venv venv
source venv/bin/activate

# Install dependencies
pip install -r requirements.txt

# Set environment variables
cp .env.example .env
# Edit .env with your values

# Run server
uvicorn app.main:app --reload --port 8000
```

## Data Refresh

- **MEXC API**: Fetched every 5 minutes (scheduler)
- **FR Snapshots**: Recorded hourly for watchlist coins
- **Telegram**: Notifications sent hourly

## Tech Stack

- FastAPI
- MongoDB (Motor async driver)
- APScheduler
- python-telegram-bot