# Polymarket Leaderboard Scraper (`khadinakbar/polymarket-leaderboard-scraper`) Actor

Scrape Polymarket top-trader leaderboards by volume and profit across 1d, 7d, 30d, and all-time windows. Wallet, PnL, profile URL + optional live portfolio value. MCP/API-ready.

- **URL**: https://apify.com/khadinakbar/polymarket-leaderboard-scraper.md
- **Developed by:** [Khadin Akbar](https://apify.com/khadinakbar) (community)
- **Categories:** MCP servers, AI, Automation
- **Stats:** 1 total users, 0 monthly users, 0.0% runs succeeded, 0 bookmarks
- **User rating**: No ratings yet

## Pricing

from $4.00 / 1,000 leaderboard entries

This Actor is paid per event and usage. You are charged both the fixed price for specific events and for Apify platform usage.

Learn more: https://docs.apify.com/platform/actors/running/actors-in-store#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

## Polymarket Leaderboard Scraper

Scrape **Polymarket's top-trader leaderboard** — ranked by **trading volume** and **profit (PnL)** across `1d`, `7d`, `30d`, and **all-time** windows. Each row gives you the trader's rank, name, on-chain wallet, USD amount, and profile link, with optional **live portfolio-value** enrichment. HTTP-only against Polymarket's public API — fast, cookieless, no login. MCP-ready for AI agents.

### What it does

Polymarket ranks its most active and most profitable traders on a public leaderboard. This actor pulls that leaderboard as clean, structured JSON so you can track smart money, build copy-trading watchlists, or research who is winning on the biggest prediction market in the world.

- **Two ranking metrics** — `volume` (total USD traded) and `profit` (realized PnL in USD).
- **Four time windows** — last 24 hours (`1d`), last 7 days (`7d`), last 30 days (`30d`), and `all`-time.
- **Top 50 per metric × window** — Polymarket's API caps the leaderboard at 50, so 50 is the ceiling for each combination (the actor tells you this and clamps automatically).
- **Specific-wallet lookup** — pass one or more `0x…` addresses to fetch their volume/profit directly, even outside the top 50.
- **Live portfolio-value enrichment (optional)** — add each trader's current open-position value in USD.

### When to use it

- Track "smart money" — find the wallets with the highest all-time or 7-day profit and follow their trades.
- Build a **copy-trading watchlist** and feed the wallets into a Polymarket position/whale tracker.
- Research prediction-market participants for a newsletter, dashboard, or trading model.
- Monitor how a specific wallet ranks over time by scheduling runs.

**Not for:** individual market odds, order books, or a single trader's full position history — this actor is the *leaderboard*, not market or position data.

### Output

One dataset row per trader per metric × window:

| Field | Type | Description |
|---|---|---|
| `rank` | integer | 1-based leaderboard position (null for direct wallet lookups) |
| `metric` | string | `volume` or `profit` |
| `window` | string | `1d`, `7d`, `30d`, or `all` |
| `displayName` | string | Best public name (pseudonym or wallet-derived label) |
| `pseudonym` | string | Polymarket pseudonym, if set |
| `proxyWallet` | string | On-chain proxy-wallet address (`0x…`) |
| `amountUsd` | number | Volume (USD) or profit (USD) depending on `metric` |
| `portfolioValueUsd` | number | Live open-position value (only when enrichment is on) |
| `bio` | string | Public profile bio, if set |
| `profileImage` | string | Profile image URL, if set |
| `profileUrl` | string | Link to the trader's Polymarket profile |
| `scrapedAt` | string | ISO 8601 UTC timestamp |

#### Example row

```json
{
  "rank": 1,
  "metric": "volume",
  "window": "all",
  "displayName": "swisstony",
  "pseudonym": "swisstony",
  "proxyWallet": "0x204f72f35326db932158cba6adff0b9a1da95e14",
  "amountUsd": 1348706088.83,
  "portfolioValueUsd": 1631434.05,
  "bio": "",
  "profileImage": "",
  "profileUrl": "https://polymarket.com/profile/0x204f72f35326db932158cba6adff0b9a1da95e14",
  "scrapedAt": "2026-07-01T00:00:00.000Z"
}
```

### Pricing (Pay Per Event)

| Event | Price |
|---|---|
| Actor start | $0.00005 |
| Leaderboard entry (per row) | $0.004 |
| Wallet enriched (per unique wallet, optional) | $0.002 |

Typical costs:

- Top 50 by profit, all-time (1 metric × 1 window): **~$0.20**.
- Both metrics × all 4 windows × 50 (400 rows): **~$1.60**.
- Add live portfolio value: **+$0.002 per unique wallet**.

The actor prints the maximum cost up front and the actual billed amount at the end. Use `maxResults` to hard-cap spend.

### Input

| Field | Default | Notes |
|---|---|---|
| `metrics` | `["volume","profit"]` | Which rankings to scrape |
| `windows` | `["all"]` | `1d` / `7d` / `30d` / `all`, one or more |
| `limit` | `50` | Rows per metric × window (1–50, clamped to 50) |
| `addresses` | `[]` | Optional `0x…` wallets to look up directly |
| `enrichPortfolioValue` | `false` | Add live portfolio value per wallet |
| `maxResults` | `0` | Optional total-row cap (0 = no extra cap) |
| `proxyConfiguration` | Apify datacenter | Public API — datacenter is enough |

#### Example input

```json
{
  "metrics": ["profit"],
  "windows": ["7d", "all"],
  "limit": 25,
  "enrichPortfolioValue": true
}
```

### Usage

#### Apify CLI

```bash
apify call khadinakbar/polymarket-leaderboard-scraper --input='{"metrics":["profit"],"windows":["all"],"limit":50}'
```

#### JavaScript (apify-client)

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

const client = new ApifyClient({ token: 'YOUR_TOKEN' });
const run = await client.actor('khadinakbar/polymarket-leaderboard-scraper').call({
  metrics: ['volume', 'profit'],
  windows: ['all'],
  limit: 50,
});
const { items } = await client.dataset(run.defaultDatasetId).listItems();
console.log(items);
```

#### Python (apify-client)

```python
from apify_client import ApifyClient

client = ApifyClient("YOUR_TOKEN")
run = client.actor("khadinakbar/polymarket-leaderboard-scraper").call(run_input={
    "metrics": ["profit"],
    "windows": ["7d", "all"],
    "limit": 50,
})
for item in client.dataset(run["defaultDatasetId"]).iterate_items():
    print(item)
```

#### AI agents / MCP

Exposed via Apify MCP as `khadinakbar/polymarket-leaderboard-scraper`. Give the agent a metric, window, and limit; it returns structured leaderboard rows. Ideal for "who are the top 20 most profitable Polymarket traders this week?" style questions.

### FAQ

**Why only 50 results?** Polymarket's leaderboard API hard-caps each metric × window at 50 traders. There is no pagination past that; the actor requests more windows/metrics to widen coverage instead.

**What is a proxy wallet?** Polymarket assigns each user an on-chain proxy wallet on Polygon. That address is the stable identifier and the key into position/value data.

**Can I get a specific trader who isn't in the top 50?** Yes — put their `0x…` address in `addresses`. The actor returns their volume/profit for the selected windows regardless of rank.

**How fresh is the data?** Live at request time. Schedule the actor to build a time series.

**Does it need login or cookies?** No. It reads Polymarket's public JSON API.

### Legal / disclaimer

This actor collects **publicly available** data from Polymarket's public API. It does not bypass authentication, access private data, or place trades. Use it in compliance with Polymarket's Terms of Service and all applicable laws. Data is provided as-is for research and informational purposes only and is **not financial advice**. You are responsible for how you use the output.

# Actor input Schema

## `metrics` (type: `array`):

Which leaderboard ranking(s) to scrape. 'volume' ranks traders by total USD traded; 'profit' ranks by realized PnL in USD. Select one or both (e.g. \["volume","profit"]). Defaults to both. This is NOT a market or event filter — it selects the ranking dimension of Polymarket's trader leaderboard.

## `windows` (type: `array`):

Time window(s) the leaderboard is computed over. Accepts 1d (last 24h), 7d, 30d, and all (all-time). Select one or more (e.g. \["7d","all"]). Defaults to all-time. Each metric x window combination is fetched separately and tagged in the output. NOT a calendar date range.

## `limit` (type: `integer`):

How many top traders to return per metric x window. Range 1-50. The Polymarket leaderboard API hard-caps at 50, so values above 50 are clamped to 50. Defaults to 50. Total rows = metrics x windows x limit (e.g. 2 metrics x 1 window x 50 = 100 rows).

## `addresses` (type: `array`):

Optional list of Polymarket proxy-wallet addresses (0x-prefixed) to look up directly instead of the top-N list (e.g. \["0x204f72f35326db932158cba6adff0b9a1da95e14"]). When set, the actor returns each wallet's volume/profit for the selected windows regardless of rank. Leave empty to scrape the top leaderboard. NOT usernames — must be on-chain wallet addresses.

## `enrichPortfolioValue` (type: `boolean`):

When true, each returned trader is enriched with their current live portfolio value in USD (open-position value) via Polymarket's data API. Adds one extra request per unique wallet and a small per-wallet charge. Defaults to false. Useful for spotting whales whose current holdings differ from historical volume.

## `maxResults` (type: `integer`):

Optional hard ceiling on the total number of dataset rows across all metric x window combinations, for cost control. 0 means no extra cap (natural limit is metrics x windows x 50). Example: set 100 to stop after the first 100 rows. Defaults to 0.

## `proxyConfiguration` (type: `object`):

Proxy settings. The Polymarket API is a public JSON endpoint, so the default Apify datacenter proxy is sufficient and cheapest. You normally do not need to change this. Residential is unnecessary here.

## Actor input object example

```json
{
  "metrics": [
    "volume",
    "profit"
  ],
  "windows": [
    "all"
  ],
  "limit": 50,
  "addresses": [],
  "enrichPortfolioValue": false,
  "maxResults": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}
```

# Actor output Schema

## `leaderboard` (type: `string`):

All scraped leaderboard rows (one per trader per metric x window).

## `summary` (type: `string`):

Counts and parameters for this run.

# 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 = {
    "metrics": [
        "volume",
        "profit"
    ],
    "windows": [
        "all"
    ],
    "limit": 50,
    "addresses": [],
    "enrichPortfolioValue": false,
    "maxResults": 0,
    "proxyConfiguration": {
        "useApifyProxy": true
    }
};

// Run the Actor and wait for it to finish
const run = await client.actor("khadinakbar/polymarket-leaderboard-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 = {
    "metrics": [
        "volume",
        "profit",
    ],
    "windows": ["all"],
    "limit": 50,
    "addresses": [],
    "enrichPortfolioValue": False,
    "maxResults": 0,
    "proxyConfiguration": { "useApifyProxy": True },
}

# Run the Actor and wait for it to finish
run = client.actor("khadinakbar/polymarket-leaderboard-scraper").call(run_input=run_input)

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

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

```

## CLI example

```bash
echo '{
  "metrics": [
    "volume",
    "profit"
  ],
  "windows": [
    "all"
  ],
  "limit": 50,
  "addresses": [],
  "enrichPortfolioValue": false,
  "maxResults": 0,
  "proxyConfiguration": {
    "useApifyProxy": true
  }
}' |
apify call khadinakbar/polymarket-leaderboard-scraper --silent --output-dataset

```

## MCP server setup

```json
{
    "mcpServers": {
        "apify": {
            "command": "npx",
            "args": [
                "mcp-remote",
                "https://mcp.apify.com/?tools=khadinakbar/polymarket-leaderboard-scraper",
                "--header",
                "Authorization: Bearer <YOUR_API_TOKEN>"
            ]
        }
    }
}

```

## OpenAPI specification

Download the OpenAPI definition: https://api.apify.com/v2/acts/CWJhJcwDKX7cdNJfm/builds/DKOHufcM6yMTTsvrJ/openapi.json