# Binance Leaderboard Scraper with Trading Signals (`brilliant_gum/binance-copy-trading-scraper`) Actor

Scrape Binance Copy Trading leaderboard and generate AI-ready trading signals. Track top traders' positions, ROI, PNL, and performance stats. Unique features: AI PREDICTIONS, Battle Score per symbol, Direction Bias, Copy Trading Coefficients. Export JSON/CSV/XLSX. No API rate limits.

- **URL**: https://apify.com/brilliant\_gum/binance-copy-trading-scraper.md
- **Developed by:** [Yuliia Kulakova](https://apify.com/brilliant_gum) (community)
- **Categories:** Automation, Developer tools, Other
- **Stats:** 70 total users, 1 monthly users, 100.0% runs succeeded, 3 bookmarks
- **User rating**: No ratings yet

## Pricing

from $25.00 / 1,000 position data

This Actor is paid per event. You are not charged for the Apify platform usage, but only a fixed price for specific events.

Learn more: https://docs.apify.com/actors/running/actors-in-store.md#pay-per-event

## What's an Apify Actor?

Actors are web data automations that power AI and operations. They run on the Apify platform to scrape websites, process data, connect APIs, and automate workflows.
In Batch mode, an Actor accepts a well-defined JSON input, performs an action which can take anything from a few seconds to a few hours,
and optionally produces a well-defined JSON output, datasets with results, or files in key-value store.
In Standby mode, an Actor provides a web server which can be used as a website, API, or an MCP server.
Actors are written with capital "A".

## How to integrate an Actor?

If asked about integration, you help developers integrate Actors into their projects.
You adapt to their stack and deliver integrations that are safe, well-documented, and production-ready.
The best way to integrate Actors is as follows.

- **AI agents and MCP clients** — the [Apify MCP server](https://docs.apify.com/integrations/mcp.md) at `https://mcp.apify.com` (remote, streamable HTTP, OAuth on first use).
- **Agentic workflows and local Actor development** — [Agent Skills](https://apify.com/.well-known/agent-skills/index.json) with the [Apify CLI](https://docs.apify.com/cli/docs.md): `npm install -g apify-cli`, then `apify login`.
- **JavaScript/TypeScript projects** — the official [JS/TS client](https://docs.apify.com/api/client/js/docs.md): `npm install apify-client`.
- **Python projects** — the official [Python client](https://docs.apify.com/api/client/python/docs.md): `pip install apify-client`.
- **Any other language** — the [REST API](https://docs.apify.com/api/v2.md).

For usage examples, see the [API](#api) section below.

For more details, see Apify documentation as [Markdown index](https://docs.apify.com/llms.txt) and [Markdown full-text](https://docs.apify.com/llms-full.txt).

# README

![Binance Copy Trading Scraper Banner](https://i.imgur.com/JOz5oMB.png)

## 🚀 Binance Copy Trading Scraper & Analytics Pro

The **ONLY working** Binance Copy Trading scraper with built-in analytics! Extract trader data, track whale positions, and generate AI-ready signals with Winners vs Losers divergence analysis.

While other scrapers use deprecated APIs that return 404 errors, this Actor uses **browser-based automation** with the official Copy Trading interface that actually works!

### ✨ Why Choose This Scraper?

| Feature | Other Scrapers | This Actor |
|---------|---------------|------------|
| Copy Trading Leaderboard | ❌ Not supported | ✅ Full support |
| Futures Leaderboard (deprecated) | ✅ (returns 404) | ⚠️ Deprecated |
| Current Positions | ✅ Basic | ✅ Full details |
| Winners vs Losers Analysis | ❌ | ✅ **UNIQUE** |
| Direction Bias Calculation | ❌ | ✅ **UNIQUE** |
| Battle Score per Symbol | ❌ | ✅ **UNIQUE** |
| TRUE LOSERS Mode | ❌ | ✅ **UNIQUE** |
| Copy Trading Coefficients | ❌ | ✅ **UNIQUE** |
| CSV/XLSX Export | ❌ | ✅ **INCLUDED** |

### 🎯 Three Operating Modes

#### Mode 1: Leaderboard Scraping

Scrape top traders from Binance Copy Trading leaderboard:

- ROI, PNL, Win Rate rankings
- Copier count and follower data
- Current open positions with leverage

#### Mode 2: Tracking Mode

Track specific traders by their Portfolio ID:

- Real-time position monitoring
- Performance snapshots
- Perfect for whale watching

> ⚠️ **Important: Batch Size Limits for Tracking Mode**
>
> Each portfolio requires a full browser page load (~10-15 sec) + position history fetch. Apify runs have a **1-hour timeout limit**. To avoid runs stopping midway:
>
> | Settings | Max portfolioIds per run |
> |----------|--------------------------|
> | `fetchHistory: false` | up to **200** |
> | `fetchHistory: true`, `maxHistoryPages: 5` | up to **150** |
> | `fetchHistory: true`, `maxHistoryPages: 10` | up to **80** |
> | `fetchHistory: true`, `maxHistoryPages: 20` | up to **50** |
>
> If you need to track more traders, **split your portfolioIds into multiple runs** of the sizes above and run them simultaneously.

#### Mode 3: Analytics Mode 🔥

**The killer feature!** Analyze Winners vs Losers divergence:

- Scrape top winners AND bottom losers separately
- Calculate Direction Bias per symbol
- Generate Battle Scores
- Output Copy Trading Coefficients
- AI-ready trading signals

### 📊 Understanding the Analytics

#### Direction Bias

Measures market sentiment based on winner/loser positioning:

- **BULLISH**: Winners are predominantly LONG (>60%)
- **BEARISH**: Winners are predominantly SHORT (<40%)
- **NEUTRAL**: Balanced positions

#### Battle Score

Per-symbol divergence analysis (-100 to +100):

- **+50 to +100**: STRONG\_LONG signal
- **+25 to +50**: LONG signal
- **-25 to +25**: NEUTRAL
- **-50 to -25**: SHORT signal
- **-100 to -50**: STRONG\_SHORT signal

#### Copy Trading Coefficients

Position sizing recommendations based on winner/loser divergence:

```json
{
    "longCoefficient": 1.0,
    "shortCoefficient": 0.1,
    "recommendation": "FAVOR_LONGS"
}
```

### 💰 Pricing

This Actor uses **Pay per Event** pricing:

| Event | Price |
|-------|-------|
| Actor Start | $0.05 |
| Trader data (per trader) | $0.025 |
| Position data (per position) | $0.025 |
| Analytics report 🔥 | $5.00 |
| Actor Completion | $0.05 |

**Example costs:**

- 100 traders without positions: ~$2.60
- 100 traders + 200 positions: ~$7.60
- Analytics mode (100 traders + 200 positions + report): ~$12.60

### 🔧 Input Parameters

| Parameter | Type | Default | Description |
|-----------|------|---------|-------------|
| `mode` | string | `analytics` | Operating mode: `leaderboard`, `tracking`, or `analytics` |
| `maxTraders` | number | `100` | Maximum traders to scrape (1-200) for leaderboard mode |
| `period` | string | `MONTHLY` | Performance period: `DAILY`, `WEEKLY`, `MONTHLY`, `ALL` |
| `sortBy` | string | `PNL` | Ranking: `PNL`, `ROI`, `WIN_RATE`, `COPIER_COUNT` |
| `withPositions` | boolean | `true` | Include current positions (required for analytics) |
| `portfolioIds` | array | `[]` | Portfolio IDs for tracking mode |
| `trueLosersMode` | boolean | `true` | Get actual losing traders from bottom of leaderboard |
| `winnersCount` | number | `50` | Number of top winners to analyze |
| `losersCount` | number | `50` | Number of bottom losers to analyze |
| `outputFormat` | string | `json` | Output format: `json`, `csv`, or `xlsx` |
| `requestDelay` | number | `500` | Delay between requests (ms) |
| `debugMode` | boolean | `false` | Enable verbose logging |

### 📤 Output Format

Each run produces multiple dataset items for flexible data processing:

#### Trader Item

```json
{
    "type": "trader",
    "scrapedAt": "2025-01-05T18:30:00.000Z",
    "portfolioId": "3958362104",
    "nickname": "TraderPro",
    "pnl": 452200.50,
    "roi": 156.78,
    "mdd": 12.5,
    "sharpe": 2.45,
    "winRate": 0.72,
    "copierCount": 1250,
    "group": "winners",
    "positionsCount": 5,
    "positions": [
        {
            "symbol": "BTCUSDT",
            "positionAmount": 0.5,
            "entryPrice": 94150.00,
            "markPrice": 95200.00,
            "unrealizedProfit": 525.00,
            "leverage": 10
        }
    ]
}
```

#### Analytics Item

```json
{
    "type": "analytics",
    "scrapedAt": "2025-01-05T18:30:00.000Z",
    "mode": "analytics",
    "directionBias": {
        "marketSentiment": "BULLISH",
        "winnersLongPercent": 87.5,
        "losersLongPercent": 35.2,
        "directionDivergence": "SIGNIFICANT"
    },
    "coefficients": {
        "longCoefficient": 1.0,
        "shortCoefficient": 0.1,
        "recommendation": "FAVOR_LONGS"
    },
    "divergenceData": [
        {
            "symbol": "BTC",
            "battleScore": 65.3,
            "signal": "STRONG_LONG",
            "winnersCount": 38,
            "losersCount": 12
        }
    ]
}
```

### 🚀 Quick Start Examples

#### Example 1: Full Analytics (Recommended) 🔥

```json
{
    "mode": "analytics",
    "winnersCount": 50,
    "losersCount": 50,
    "trueLosersMode": true,
    "withPositions": true
}
```

#### Example 2: Scrape Top 100 Traders by PNL

```json
{
    "mode": "leaderboard",
    "maxTraders": 100,
    "period": "MONTHLY",
    "sortBy": "PNL",
    "withPositions": true
}
```

#### Example 3: Track Specific Whales

```json
{
    "mode": "tracking",
    "portfolioIds": ["3958362104", "4012876543"],
    "withPositions": true
}
```

#### Example 4: Export to Excel

```json
{
    "mode": "analytics",
    "winnersCount": 50,
    "losersCount": 50,
    "outputFormat": "xlsx"
}
```

### ⚡ API Integration

Use the Apify API to integrate this scraper into your trading bot:

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_API_TOKEN")

run_input = {
    "mode": "analytics",
    "winnersCount": 50,
    "losersCount": 50,
    "trueLosersMode": True,
    "withPositions": True
}

run = client.actor("hlwhales/binance-copy-trading-scraper").call(run_input=run_input)

## Get all traders
traders = []
analytics = None

for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    if item["type"] == "trader":
        traders.append(item)
    elif item["type"] == "analytics":
        analytics = item

print(f"Fetched {len(traders)} traders")
print(f"Market Sentiment: {analytics['directionBias']['marketSentiment']}")
print(f"Recommendation: {analytics['coefficients']['recommendation']}")
```

### ❓ FAQ

**Q: Why do other Binance scrapers return 404 errors?**
A: They use the deprecated Futures Leaderboard API endpoints. This Actor uses browser automation with the current Copy Trading interface.

**Q: What is TRUE LOSERS mode?**
A: It fetches traders from the BOTTOM of the leaderboard (actual negative PNL) instead of just the lowest-ranked winners. This creates real divergence signals.

**Q: How often should I run analytics?**
A: For day trading: every 1-4 hours. For swing trading: once daily. For position trading: every few days.

**Q: Can I export to CSV/Excel?**
A: Yes! Set `outputFormat` to `csv` or `xlsx`. CSV creates two files (traders.csv, analytics.csv), XLSX creates one file with multiple sheets.

**Q: Why are positions required for analytics?**
A: Direction Bias and Battle Scores are calculated from actual position data. Without positions, analytics will show NEUTRAL values.

### 📊 Use Cases

- **Algorithmic Trading**: Feed signals directly into your trading bot
- **Market Research**: Understand what top traders are doing vs losing traders
- **Risk Management**: Adjust position sizes based on Copy Trading Coefficients
- **Sentiment Analysis**: Track market sentiment shifts over time
- **Whale Watching**: Monitor specific successful traders

### 📞 Support

Having issues or need custom features? Open an issue on the Actor page or contact through Apify.

***

#### 🐋 About the Developer

This Actor is developed and maintained by [WhaleHunt.io](https://whalehunt.io) — a professional crypto market data intelligence platform. We specialize in building advanced analytics tools for traders, quant researchers, and algorithmic trading systems.

**Our expertise includes:**

- Crypto exchange data extraction and analytics
- Whale wallet tracking and on-chain analysis
- Trading signal generation and market sentiment tools
- Custom data solutions for hedge funds and trading desks

Visit [whalehunt.io](https://whalehunt.io) for more crypto analytics tools and professional data intelligence solutions.

# Actor input Schema

## `mode` (type: `string`):

Select the scraping mode:
• **leaderboard** - Scrape top traders from Copy Trading Leaderboard
• **tracking** - Track specific traders by Portfolio ID
• **analytics** - Winners vs Losers divergence analysis with trading signals

## `maxTraders` (type: `integer`):

Number of traders to scrape from leaderboard (1-200). Used in Leaderboard mode.

## `period` (type: `string`):

Time period for trader performance ranking

## `sortBy` (type: `string`):

Ranking criteria for traders

## `withPositions` (type: `boolean`):

Fetch currently open positions for each trader. Required for Analytics mode to calculate Direction Bias and Battle Scores.

## `portfolioIds` (type: `array`):

List of specific Portfolio IDs to track (for Tracking mode only). Find Portfolio IDs in Binance Copy Trading URLs.

## `trueLosersMode` (type: `boolean`):

Get actual losing traders (negative PNL) from the BOTTOM of leaderboard instead of just bottom performers from TOP. This provides REAL Winners vs Losers divergence for maximum signal accuracy!

## `winnersCount` (type: `integer`):

Number of top performing traders to analyze as 'Winners' (Analytics mode)

## `losersCount` (type: `integer`):

Number of bottom performing/losing traders to analyze as 'Losers' (Analytics mode)

## `outputFormat` (type: `string`):

Format for the output data. JSON for API integration, CSV/XLSX for spreadsheets.

## `requestDelay` (type: `integer`):

Delay between requests to avoid rate limiting (in milliseconds). Lower = faster but higher risk of blocks.

## `debugMode` (type: `boolean`):

Enable verbose logging for debugging. Shows detailed information about each request.

## `fetchHistory` (type: `boolean`):

Fetch closed/historical positions for tracked traders (Tracking mode only). Shows past trades with entry/exit prices and PnL.

## `historyPageSize` (type: `integer`):

Number of historical positions per page (10-50)

## `maxHistoryPages` (type: `integer`):

Maximum number of history pages to fetch. Total records = pageSize x maxPages

## Actor input object example

```json
{
  "mode": "analytics",
  "maxTraders": 10,
  "period": "MONTHLY",
  "sortBy": "PNL",
  "withPositions": true,
  "portfolioIds": [],
  "trueLosersMode": true,
  "winnersCount": 5,
  "losersCount": 5,
  "outputFormat": "json",
  "requestDelay": 500,
  "debugMode": false,
  "fetchHistory": false,
  "historyPageSize": 20,
  "maxHistoryPages": 5
}
```

# Actor output Schema

## `tradingData` (type: `string`):

Dataset containing trader profiles, positions, market analytics, and trading signals

# API

You can run this Actor programmatically using our API. Below are code examples in JavaScript, Python, and CLI, as well as the OpenAPI specification and MCP server setup.

## JavaScript example

```javascript
import { ApifyClient } from 'apify-client';

// Initialize the ApifyClient with your Apify API token
// Replace the '<YOUR_API_TOKEN>' with your token
const client = new ApifyClient({
    token: '<YOUR_API_TOKEN>',
});

// Prepare Actor input
const input = {
    "mode": "analytics",
    "maxTraders": 10,
    "period": "MONTHLY",
    "sortBy": "PNL",
    "withPositions": false,
    "portfolioIds": [],
    "trueLosersMode": true,
    "winnersCount": 5,
    "losersCount": 5,
    "outputFormat": "json",
    "requestDelay": 500,
    "fetchHistory": false,
    "historyPageSize": 20,
    "maxHistoryPages": 5
};

// Run the Actor and wait for it to finish
const run = await client.actor("brilliant_gum/binance-copy-trading-scraper").call(input);

// Fetch and print Actor results from the run's dataset (if any)
console.log('Results from dataset');
console.log(`💾 Check your data here: https://console.apify.com/storage/datasets/${run.defaultDatasetId}`);
const { items } = await client.dataset(run.defaultDatasetId).listItems();
items.forEach((item) => {
    console.dir(item);
});

// 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/js/docs

```

## Python example

```python
from apify_client import ApifyClient

# Initialize the ApifyClient with your Apify API token
# Replace '<YOUR_API_TOKEN>' with your token.
client = ApifyClient("<YOUR_API_TOKEN>")

# Prepare the Actor input
run_input = {
    "mode": "analytics",
    "maxTraders": 10,
    "period": "MONTHLY",
    "sortBy": "PNL",
    "withPositions": False,
    "portfolioIds": [],
    "trueLosersMode": True,
    "winnersCount": 5,
    "losersCount": 5,
    "outputFormat": "json",
    "requestDelay": 500,
    "fetchHistory": False,
    "historyPageSize": 20,
    "maxHistoryPages": 5,
}

# Run the Actor and wait for it to finish
run = client.actor("brilliant_gum/binance-copy-trading-scraper").call(run_input=run_input)

# Fetch and print Actor results from the run's dataset (if there are any)
print(f"💾 Check your data here: https://console.apify.com/storage/datasets/{run.default_dataset_id}")
for item in client.dataset(run.default_dataset_id).iterate_items():
    print(item)

# 📚 Want to learn more 📖? Go to → https://docs.apify.com/api/client/python/docs/quick-start

```

## CLI example

```bash
echo '{
  "mode": "analytics",
  "maxTraders": 10,
  "period": "MONTHLY",
  "sortBy": "PNL",
  "withPositions": false,
  "portfolioIds": [],
  "trueLosersMode": true,
  "winnersCount": 5,
  "losersCount": 5,
  "outputFormat": "json",
  "requestDelay": 500,
  "fetchHistory": false,
  "historyPageSize": 20,
  "maxHistoryPages": 5
}' |
apify call brilliant_gum/binance-copy-trading-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "type": "http",
            "url": "https://mcp.apify.com/?tools=fetch-actor-details,brilliant_gum/binance-copy-trading-scraper"
        }
    }
}

```

The hosted server signs you in with OAuth on first connect, so no API token belongs in this config. Clients without OAuth support can send an `Authorization: Bearer <APIFY_API_TOKEN>` header instead, using a token from API & Integrations in Apify Console (https://console.apify.com/settings/integrations).

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/actors/MH1YIFcdC2wMM6y9i/builds/9db6oc0zfZCAW9oOn/openapi.json