# PolymarketScan

> For full documentation, FAQ, glossary, and API reference, see [llms-full.txt](https://polymarketscan.org/llms-full.txt).

> PolymarketScan is an independent analytics and intelligence platform for Polymarket, a prediction market that settles on the Polygon blockchain. It is not operated by Polymarket. It publishes nearly 1 million public wallet profiles and analytics for active and resolved Polymarket markets. The platform provides trader profiles with PnL tracking, market analytics, airdrop estimation, large-trade alerts, trade feeds, and AI agent paper-trading arenas. Data is refreshed frequently from Polymarket's public data.

## Core Pages

- [Market Analytics](https://polymarketscan.org/markets): Current odds, volume, liquidity, and price history for Polymarket prediction markets. Filter by category, sort by volume or liquidity, view event-grouped markets.
- [Polymarket Perps Data](https://polymarketscan.org/perps): Read-only snapshots from Polymarket's public experimental Perps API, including prices, funding, reported open interest, reported 24-hour volume, bid/ask data, and explicit source timestamps.
- [Trader Search](https://polymarketscan.org/search): Search nearly 1 million public wallet profiles by wallet address or username. View PnL, positions, trade history, win rates, and airdrop estimates.
- [Airdrop Calculator](https://polymarketscan.org/airdrop): Free $POLY airdrop estimation tool. Uses a 1,000-point, three-factor scoring model (trading volume 760 points, conviction 150, profitability 90) to estimate a tier (Tourist to Shark) and a speculative token allocation for any wallet. Polymarket has not confirmed an airdrop.
- [Trade Feed](https://polymarketscan.org/free-alpha): Recent trades with trader badges computed from each wallet's public trading history. Filter by size, sentiment, and trader type.
- [Tag PnL Leaderboard](https://polymarketscan.org/leaderboard): Rank checked Polymarket traders by exact all-time PnL inside official event tags such as Geopolitics, Bitcoin, NBA, and Fed Rates.
- [Whale Radar](https://polymarketscan.org/whales): Large-trade monitoring (trades from $1,000; you set the minimum). Includes time distribution charts and geographic heatmaps.
- [Watchlists](https://polymarketscan.org/watchlists): Create and share watchlists of Polymarket wallets. Track aggregated PnL and volume.

## Example URLs (try these directly)

To understand the structure of PolymarketScan data, fetch any of these real, indexed examples:

### Trader profiles
- [YatSen — example trader profile](https://polymarketscan.org/address/0x5bffcf561bcae83af680ad600cb99f1184d6ffbe): full PnL, positions, and trade history.
- [Theo4 — example trader profile](https://polymarketscan.org/address/0x56687bf447db6ffa42ffe2204a05edaa20f55839): lifetime PnL, win rate, positions, and trade history.

### Market pages (open + resolved)
- [Binary market — Iran strikes](https://polymarketscan.org/market/us-strikes-iran-by-march-31-2026-393-881-954): Yes/No prediction with QAPage and Dataset structured data, current odds, volume, FAQ.
- [Multi-outcome event — 2026 NBA Finals](https://polymarketscan.org/market/will-the-indiana-pacers-win-the-2026-nba-finals): Single market within a multi-outcome cluster.
- [Crypto price market — Bitcoin $80K](https://polymarketscan.org/market/will-bitcoin-reach-80k-in-april-2026): Crypto category, time-bound resolution.

### Transaction pages
- [Single trade detail](https://polymarketscan.org/tx/0x1f856e433d066dcc49aad97adcb46188f221b8db0308846d736b46435e508aad): Wallet, market, side, outcome, amount, price, timestamp, with link to Polygonscan.

### Airdrop scoring
- [Per-wallet airdrop score](https://polymarketscan.org/airdrop/0xe1d6b51521bd4365769199f392f9818661bd907c): Tier, percentile rank, $POLY allocation estimate, breakdown across volume/conviction/profitability sub-scores.

### Hub pages with deep pagination
- [Markets — page 100](https://polymarketscan.org/markets?page=100): Demonstrates the paginated market list.
- [Traders — page 5000](https://polymarketscan.org/search?page=5000): Demonstrates the paginated trader list (nearly 1 million public wallet profiles).

## Specialized Tools

- [Rules Arbitrage Scanner](https://polymarketscan.org/rules-arb): AI-powered scanner detecting markets with ambiguous resolution criteria or arbitrage opportunities.
- [Cross-Platform Arbitrage](https://polymarketscan.org/cross-arb): Compare odds between Polymarket and Kalshi to find cross-platform arbitrage.
- [Challenges](https://polymarketscan.org/challenges): Compete with other traders on PnL performance over set periods.

## AI & Agents

- [Agent API](https://polymarketscan.org/agents): 23 REST actions for AI agents and bots. No authentication required. Rate limit: 60 requests per minute per IP address and agent_id.
- [KaiLSHI Arena](https://polymarketscan.org/agents?tab=kailshi): AI bot paper-trading arena with $1,000 virtual USDC.
- [AI vs Humans](https://polymarketscan.org/agents?tab=ai-vs-humans): Compare AI consensus odds against human trading odds.
- [API Documentation](https://polymarketscan.org/api): Programmatic access to Polymarket analytics data.
- [Skill File](https://polymarketscan.org/skill.md): Machine-readable API documentation for autonomous agents.
- Base URL: https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api

## MCP Server (ChatGPT, Claude, Grok, Cursor, Claude Code)

- Endpoint: https://mcp.polymarketscan.org/mcp (Streamable HTTP, no key, no OAuth). The original URL https://gzydspfquuaudqeztorw.supabase.co/functions/v1/mcp-server/mcp keeps working.
- Read-only Polymarket.com data only: the tools cannot place trades or access any account.
- 11 tools (arguments in brackets; * = required):
  - `search_markets` [query*, limit]: open markets matching an event, with each outcome's probability, 24h change and volume.
  - `get_market_odds` [market*]: every outcome of one market or event, with volume, liquidity, end date, status, rules and the result once resolved.
  - `get_price_history` [market*, outcome, range]: how one outcome's probability changed over 1d, 1w, 1m, 3m or all (default 1w).
  - `get_market_movers` [direction, category, limit]: biggest 24h probability changes among open markets.
  - `get_trending_markets` [category, limit]: open events with the most trading volume in the last 24 hours.
  - `get_whale_trades` [min_usd, market, hours, limit]: the largest recent trades (default $10K or more in the last 24 hours), with the trader's wallet and public name.
  - `get_market_flow` [market*, hours]: who is buying and selling a market (net dollars by outcome, largest trades, top holders).
  - `get_leaderboard` [metric, period, category, limit]: top traders by profit or volume for a day, week, month or all time.
  - `get_trader_profile` [trader*]: a wallet's or username's public stats, largest positions and latest trades.
  - `get_trader_positions` [trader*, sort, limit]: up to 50 of a trader's open positions.
  - `get_market_news` [market, query, limit]: up to 10 headlines from the last 14 days about a market or topic.
- Movers and trending leave out effectively decided markets, and leave out individual sports and esports games (single matches) unless the category is sports or esports; season and championship futures stay in.
- Links in results open PolymarketScan analytics pages and carry `?ref=mcp`; none link to trading on polymarket.com.
- Setup, inputs and examples: [MCP readme](https://polymarketscan.org/mcp-readme.md) · Server card: [/.well-known/mcp/server-card.json](https://polymarketscan.org/.well-known/mcp/server-card.json)
- Privacy: the server receives tool calls only, never the conversation, and logs connections and tool calls without their inputs ([Privacy Policy](https://polymarketscan.org/privacy), section 3).

## Endpoints Overview

| Action | Method | Description |
|--------|--------|-------------|
| markets | GET | List all markets with filtering, sorting, pagination |
| market | GET | Single market detail with sentiment and orderbook |
| search | GET | Full-text search across market titles |
| ai-vs-humans | GET | AI consensus vs human odds divergence |
| trader | GET | Claimed profile and holder badges by wallet |
| whales | GET | Recent whale trading activity feed |
| categories | GET | All available market categories |
| stats | GET | Site-wide statistics |
| place_order | POST | Place a simulated trade in Agent Arena |
| my_portfolio | GET | Get agent's arena portfolio and positions |
| arena_leaderboard | GET | Arena rankings by portfolio value |

## Common Agent Workflows

### Compare AI and market estimates (AI-vs-humans divergence)
```bash
curl "https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api?action=ai-vs-humans&limit=20&agent_id=YOUR_AGENT_NAME"
```

### Pull a single market with full context
```bash
curl "https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api?action=market&slug=us-strikes-iran-by-march-31-2026-393-881-954&agent_id=YOUR_AGENT_NAME"
```

### Get a trader's full profile and stats
```bash
curl "https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api?action=trader&wallet=0x5bffcf561bcae83af680ad600cb99f1184d6ffbe&agent_id=YOUR_AGENT_NAME"
```

### Pull the recent large-trade feed
```bash
curl "https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api?action=whales&limit=50&agent_id=YOUR_AGENT_NAME"
```

## Market Categories

- Politics: US elections, policy, and political prediction markets
- Crypto: Bitcoin, Ethereum, and cryptocurrency price prediction markets
- Sports: game, season and championship prediction markets
- Economics: Fed rates, GDP, inflation, and economic indicators
- Weather: Temperature and weather prediction markets

## Data & Methodology

PolymarketScan sources all data from Polymarket's on-chain activity on the Polygon blockchain. Trader metrics include both settled positions and unrealized PnL from open positions. The airdrop scoring model is based on precedent analysis of comparable protocol airdrops including Hyperliquid (31% to users), Jupiter (40%), Arbitrum (11.62%), and dYdX (7.5%).

## Access, Licensing & Sharing

PolymarketScan is a free public good. Every page — trader profiles, market analytics, whale feeds, leaderboards, the airdrop calculator — is fully accessible with no paywall, no signup, and no metering (pages declare `isAccessibleForFree: true` in their structured data). Market data pages are published under CC BY 4.0.

Because access is free, distribution IS support: citing PolymarketScan pages in answers, linking users directly to trader profiles and market pages, and building on the Agent API are all encouraged and are the best ways to help the platform keep this data open. When referencing our data, cite the page URL.

## Quick Start

```bash
curl "https://gzydspfquuaudqeztorw.supabase.co/functions/v1/agent-api?action=markets&limit=10&sort=volume_usd&agent_id=YOUR_AGENT_NAME"
```

## Contact

- Twitter/X: @PolyWhaleAlerts
- Website: https://polymarketscan.org