PolyVision — Polymarket Wallet Analyzer

PolyVision analyzes Polymarket prediction market wallets and returns a comprehensive trading profile: copy trading score (1-10), P&L breakdown, win rate, risk metrics (Sharpe ratio, Sortino ratio, max drawdown), position sizing consistency, market category performance, recent performance windows (7d/30d/90d), streak analysis, red flags, and individual open positions with entry/current prices. It also provides a daily leaderboard of top-ranked traders, hot bets (most profitable open positions from top traders), and random elite wallet discovery. Use it to evaluate whether a trader is worth copy trading, compare multiple wallets, screen for elite performers, find today's best bets, or discover new traders to follow.

When to Use

• - User mentions a Polymarket wallet address (0x...)
• User asks about copy trading, trader evaluation, or wallet scoring
• User wants to compare prediction market traders or screen for elite performers
• User asks about a trader's risk profile, red flags, or trading patterns
• User asks what bets top traders are making, or wants today's best open positions
• User wants to discover or find new Polymarket traders to follow
• User asks about a daily leaderboard or top traders ranking
• User wants to see a trader's individual open positions with P&L details
• User asks about a trader's recent trades, trade history, or latest activity
• User asks for copy trading strategy recommendations or optimal settings
• User wants to know what risk profile or parameters to use for copy trading

When NOT to Use

• - General crypto price queries (not Polymarket-specific)
• Placing trades or executing orders (PolyVision is read-only analysis)
• Non-Polymarket wallet lookups (Ethereum DeFi, NFTs, etc.)

Setup: MCP Server (Recommended)

Add to your MCP client configuration (e.g. claude_desktop_config.json, Cursor, Windsurf):

CODEBLOCK0

Setup: Get an API Key

Get a free API key (no daily limits) from the Telegram bot:

1. 1. Open the PolyVision bot on Telegram
2. Run /apikey to generate your key
3. Copy the pv_live_... key (shown only once, store it securely)

Set it as an environment variable:

CODEBLOCK1

Full API docs: https://polyvisionx.com/docs

MCP Tools Reference

analyze_wallet

Run a comprehensive Polymarket wallet analysis.

Parameter	Type	Required	Default	Description
INLINECODE4	string	Yes	—	Ethereum address (42 chars, starts with 0x)
INLINECODE6

string | No | "quick" | "quick" (~5s) or "full" (~30-60s with timing data) |

Returns: Full analysis dict with P&L, win rate, risk metrics, categories, copy trading score (1-10), red flags, and usage info. Results are cached for 6 hours — cache hits are instant. See references/response-schemas.md for the complete field reference.

Timing: Quick mode ~5s, full mode ~30-60s. Cached responses are instant.

get_score

Get a compact copy-trading score for a wallet. Shares the same cache as analyze_wallet.

Parameter	Type	Required	Description
INLINECODE13	string	Yes	Ethereum address (42 chars, starts with 0x)

Returns: Score (1-10), recommendation, tier (green/yellow/orange/red), total P&L, win rate, trade count, Sharpe ratio, red flags, cache status, and usage info.

Timing: ~5s fresh, instant if cached.

get_hot_bets

Get today's hot bets from top traders. Returns the most profitable open positions from top-ranked Polymarket traders, sourced from the daily strategy report.

Parameter	Type	Required	Default	Description
INLINECODE16	integer	No	INLINECODE17	Maximum number of bets to return
INLINECODE18

string | No | "rank" | "rank" (default) or "pnl" |

Returns: Scan date, total count, and list of hot bets — each with trader info (wallet, username, score, win rate), market details (title, slug, outcome), pricing (entry price, current price, current value), P&L (unrealized P&L, percent), resolution info (end date, days until resolution), entry timing (entry date, days since entry, hold hours), and Polymarket URL. See references/response-schemas.md for the complete field reference.

get_leaderboard

Get the daily top-10 leaderboard of ranked Polymarket traders. Synced daily from the scan pipeline.

Parameter	Type	Required	Default	Description
INLINECODE24	string	No	INLINECODE25	INLINECODE26 (default), "score", or INLINECODE28

Returns: Scan date, total count, and list of leaderboard entries — each with wallet address, username, total P&L, volume, ROI%, win rate, risk metrics (Sharpe ratio, max drawdown, profit factor), copy score (1-10), recommendation, tier (green/yellow/orange/red), red flags, track record days, last trade date, and category percentages (politics, crypto, sports). See references/response-schemas.md for the complete field reference.

get_strategy

Get pre-computed copy trading strategy profiles. Returns 3 risk profiles (conservative, moderate, aggressive) with backtested parameters and expected metrics, updated daily.

Parameters: None

Returns: Scan date, total count, and list of strategy profiles — each with parameters (price range, min score, max trades/day, min trade size, position sizing method), backtest results (win rate, ROI, Sharpe ratio, max drawdown, profit factor, EV/trade, total P&L), cost-adjusted results, and a plain-English description. See references/response-schemas.md for the complete field reference.

get_recent_trades

Get recent trades for a Polymarket wallet. Returns trade history with side, size, price, market title, and timestamps.

Parameter	Type	Required	Default	Description
INLINECODE33	string	Yes	—	Ethereum address (42 chars, starts with 0x)
INLINECODE35

integer | No | — | Unix timestamp — only return trades after this time |
| limit | integer | No | 50 | Max trades to return (1-100) |

Returns: Dict with wallet_address, since, count, and trades list — each trade with side (BUY/SELL), size, price, timestamp, market title, outcome, slug, and transaction hash. See references/response-schemas.md for the complete field reference.

discover_wallet

Discover a random elite trader from the curated wallet pool (250+). Returns a random wallet address each call — use analyze_wallet or get_score to investigate it.

Parameters: None

Returns: INLINECODE46

check_quota

Check your usage statistics. Does not consume quota.

Parameters: None

Returns: INLINECODE48

API/MCP access has no daily limits — usage is tracked for analytics only.

get_portfolio

Get the user's tracked wallet portfolio with scores and nicknames.

Parameter	Type	Required	Default	Description
INLINECODE50	integer	No	INLINECODE51	Page number (0-indexed)
INLINECODE52

integer | No | 10 | Results per page (1-50) |

Returns: Dict with total_count, page, limit, and wallets list — each with wallet address, nickname, score, last analyzed date, and notifications status. See references/response-schemas.md for the complete field reference.

add_to_portfolio

Add a wallet to the user's portfolio for tracking.

Parameter	Type	Required	Default	Description
INLINECODE60	string	Yes	—	Ethereum address (42 chars, starts with 0x)
INLINECODE62

string | No | — | Display name (defaults to first 10 chars of address) |

Returns: Dict with wallet_address, nickname, and message on success, or dict with error key on failure (duplicate, limit reached).

Limits: Free users: 3 wallets. Premium users: 20 wallets.

remove_from_portfolio

Remove a wallet from the user's portfolio.

Parameter	Type	Required	Description
INLINECODE68	string	Yes	Ethereum address to remove

Returns: Dict with wallet_address and message on success, or dict with error key if wallet not found.

health

Check system health.

Parameters: None

Returns: { "status": "ok" } or INLINECODE74

Score Tiers

Tier	Score Range	Recommendation	Meaning
Green	8.0 – 10.0	Strong Copy	Consistently profitable, good risk management, strong track record
Yellow

6.0 – 7.9 | Moderate Copy | Decent performance with some concerns, proceed with caution | | Orange | 4.0 – 5.9 | Risky Copy | Mixed results, significant red flags, high risk | | Red | 0.0 – 3.9 | Don't Copy | Poor performance, major red flags, likely to lose money |

Decision Table

User Intent	Tool	Mode	Why
"Should I copy this trader?"	INLINECODE75	—	Quick yes/no with score + red flags
"Deep dive on this wallet"

analyze_wallet | full | Complete analysis with timing data | | "Quick check on a wallet" | analyze_wallet | quick | Full analysis without activity timing | | "What are this trader's open positions?" | analyze_wallet | quick | open_positions_detail in analysis response | | "Compare two traders" | get_score x2 | — | Side-by-side scores for fast comparison | | "What categories does this trader focus on?" | analyze_wallet | quick | Category breakdown in analysis | | "What are the best bets right now?" | get_hot_bets | — | Today's most profitable open positions from top traders | | "What bets are top traders making?" | get_hot_bets | sort=pnl | Hot bets sorted by P&L | | "Who are the top traders today?" | get_leaderboard | — | Daily top-10 ranked traders | | "Find me a good trader to follow" | discover_wallet | — | Random elite wallet, then get_score or analyze_wallet | | "What trades has this wallet made recently?" | get_recent_trades | — | Recent trade history for a wallet | | "What strategy should I use for copy trading?" | get_strategy | — | 3 risk profiles with backtested parameters | | "What's the safest way to copy trade?" | get_strategy | — | Conservative profile with low drawdown | | "Discover new traders" | discover_wallet x3 | — | Multiple random picks to explore | | "Show my tracked wallets" | get_portfolio | — | View portfolio with scores and nicknames | | "Add this wallet to my portfolio" | add_to_portfolio | — | Track a wallet with optional nickname | | "Remove wallet from portfolio" | remove_from_portfolio | — | Stop tracking a wallet | | "Is the system up?" | health | — | System status check | | "How many analyses have I run?" | check_quota | — | Usage stats (no limits enforced) |

Red Flag Reference

Red flags are returned as a list of strings. Here's what each one means:

Red Flag	Trigger	Severity
Low win rate	Win rate below 40%	High
Large single loss

Single worst trade exceeds 50% of total P&L | Medium |
| Overall unprofitable | Net P&L is negative | High |
| Limited track record | Fewer than 10 closed positions | Medium |
| Inactive | No trades in 30+ days | Low |
| BOT ALERT | Median trade duration under 5 minutes | High |
| Very fast trading | Median trade duration under 30 minutes | Medium |
| LOSS HIDING | 70%+ of open positions underwater (5+ open) | High |
| Open positions losing | 50%+ of open positions underwater (3+ open) | Medium |
| No major red flags detected | No concerning patterns found | None |

REST API (Alternative)

For agents that cannot use MCP, all tools are available as REST endpoints at https://api.polyvisionx.com. Most endpoints require Bearer token authentication (exceptions noted below).

Interactive docs and the OpenAPI spec are available at:

• - Swagger UI: INLINECODE103
• OpenAPI JSON: INLINECODE104

Endpoint	Method	Description
INLINECODE105	GET	Get current user info and usage stats
INLINECODE106

GET | Full wallet analysis (includes open_positions_detail) |
| GET /v1/score/{wallet_address} | GET | Compact copy-trading score |
| GET /v1/hot-bets?page=0&limit=20&sort_by=rank | GET | Today's hot bets from top traders |
| GET /v1/leaderboard?sort_by=rank | GET | Daily top-10 leaderboard |
| GET /v1/strategy | GET | Pre-computed copy trading strategy profiles (3 risk levels) |
| GET /v1/trades/{wallet_address}?since=&limit=50 | GET | Recent trades for a wallet |
| GET /v1/discover | GET | Discover a random elite trader |
| GET /v1/portfolio?page=0&limit=10 | GET | Get your tracked wallet portfolio |
| POST /v1/portfolio | POST | Add a wallet to your portfolio (JSON body: wallet_address, nickname) |
| DELETE /v1/portfolio/{wallet_address} | DELETE | Remove a wallet from your portfolio |
| GET /health | GET | Health check (no auth required) |

Example: Analyze a wallet

CODEBLOCK2

Example: Get a score

CODEBLOCK3

Example: Get hot bets

CODEBLOCK4

Example: Get leaderboard

CODEBLOCK5

Example: Get strategy profiles

CODEBLOCK6

Example: Discover a random trader

CODEBLOCK7

Error Codes

Code	Meaning	Recovery
400	Invalid wallet address (must be 42-char hex starting with 0x)	Fix the address format
401

Invalid or inactive API key | Get a key from the PolyVision Telegram bot via /apikey | | 429 | Rate limited | Wait and retry — Polymarket API has upstream limits | | 503 | System at capacity (all analysis slots in use) | Retry in 30-60 seconds | | 502 | Upstream Polymarket API error | Retry — the upstream data API may be temporarily unavailable | | 504 | Analysis timed out | Retry — the wallet may have extensive history |