polyvision

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, and red flags. Use it to evaluate whether a trader is worth copy trading, compare multiple wallets, or screen for elite performers.

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

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):

{
  "mcpServers": {
    "polyvision": {
      "type": "streamable-http",
      "url": "https://api.polyvisionx.com/mcp",
      "headers": {
        "Authorization": "Bearer ${POLYVISION_API_KEY}"
      }
    }
  }
}

Setup: Get an API Key

Register for a free API key (no daily limits):

curl -X POST https://api.polyvisionx.com/v1/auth/register \
  -H "Content-Type: application/json" \
  -d '{"email": "you@example.com", "name": "My App"}'

Response:

{
  "api_key": "pv_live_abc123...",
  "key_prefix": "pv_live_abc12345",
  "tier": "api"
}

Store the key — it is shown only once and cannot be retrieved later. Set it as an environment variable:

export POLYVISION_API_KEY="pv_live_abc123..."

MCP Tools Reference

analyze_wallet

Run a comprehensive Polymarket wallet analysis.

Parameter	Type	Required	Default	Description
wallet_address	string	Yes	—	Ethereum address (42 chars, starts with 0x)
mode	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
wallet_address	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.

check_quota

Check your usage statistics. Does not consume quota.

Parameters: None

Returns: { "used_today": <int>, "tier": "api" }

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

health

Check system health.

Parameters: None

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

regenerate_key

Regenerate your API key. The old key is immediately invalidated.

Parameters: None

Returns: { "api_key": "pv_live_...", "key_prefix": "pv_live_...", "message": "..." }

The new key is shown only once. Update your configuration immediately.

deactivate_key

Permanently deactivate your API key. This is irreversible — use regenerate_key instead if you need a replacement.

Parameters: None

Returns: { "success": true, "message": "API key deactivated. All future requests with this key will be rejected." }

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?"	get_score	—	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
"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
"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: https://api.polyvisionx.com/docs
• OpenAPI JSON: https://api.polyvisionx.com/openapi.json

Endpoint	Method	Description
POST /v1/auth/register	POST	Register and get an API key (no auth required)
GET /v1/auth/me	GET	Get current user info and usage stats
POST /v1/auth/regenerate	POST	Regenerate API key
POST /v1/auth/deactivate	POST	Deactivate API key
GET /v1/analyze/{wallet_address}?mode=quick	GET	Full wallet analysis
GET /v1/score/{wallet_address}	GET	Compact copy-trading score
GET /health	GET	Health check (no auth required)

Example: Analyze a wallet

curl -s https://api.polyvisionx.com/v1/analyze/0x1234...abcd?mode=quick \
  -H "Authorization: Bearer $POLYVISION_API_KEY" | jq .

Example: Get a score

curl -s https://api.polyvisionx.com/v1/score/0x1234...abcd \
  -H "Authorization: Bearer $POLYVISION_API_KEY" | jq .

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	Check your POLYVISION_API_KEY or register a new one
409	Email already registered (registration only)	Use existing key or register with a different email
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
504	Analysis timed out	Retry — the wallet may have extensive history