Developers
API Documentation
Everything on this site is available as JSON over REST. Anonymous requests work immediately at a low rate limit; a free API key raises that limit 4×.
curl https://mypolyscore.xyz/api/wallet/0x0a854897a06d4999e5b2dde5693609f1428ffe9d # Or from the dashboard: any passport page has an "API" tab with live links.
Authentication
Requests without a key are rate-limited by IP address. Get a free key — no email verification, so treat it as a convenience identifier rather than a proof of identity — and send it as the x-api-key header.
curl -X POST https://mypolyscore.xyz/api/keys \
-H "Content-Type: application/json" \
-d '{"email":"you@example.com","label":"my-lending-bot"}'
# → { "apiKey": "psk_live_...", "tier": "free", "limitPerMinute": 120 }
# Shown once — store it. Then:
curl https://mypolyscore.xyz/api/wallet/0x... -H "x-api-key: psk_live_..."Endpoints
/api/wallet/{address}Full wallet summary — the primary underwriting endpoint.
score, grade, rawGrade, confidence, integrityFlags[], riskLevel, portfolioHealth, traderDna, predictionAccuracy, maxDrawdown, totalPnl, roi, components[], summary
/api/wallet/{address}/reputationScore plus the ten weighted component scores with explanations.
score, grade, rawGrade, confidence, integrityFlags[], traderDna, components[]
/api/wallet/{address}/historyMonthly reputation timeline for trend analysis. Months you've queried before are the real recorded score, not a re-derived estimate.
timeline[{month, label, score}]
/api/wallet/{address}/metricsAdvanced quantitative metrics.
sharpeRatio, sortinoRatio, volatility, winRate, profitConsistency, capitalEfficiency, avgHoldDays, tradeFrequency, positionConcentration, successStreak, recoveryScore, behavioralConsistency, convictionScore, executionQuality
/api/wallet/{address}/riskRisk-focused view for margin and insurance systems.
riskLevel, portfolioHealth, confidence, integrityFlags[], maxDrawdown, volatility, positionConcentration, recoveryScore, riskComponents[]
/api/wallet/{address}/portfolioCurrent holdings and market-category exposure.
portfolioValue, portfolioHealth, totalPnl, roi, categories[], openPositions[]
/api/compare/{walletA}/{walletB}Two full profiles plus a verdict.
walletA{…}, walletB{…}, verdict
/api/leaderboardPolymarket's top traders by lifetime PnL.
rank, address, userName, volume, pnl
/api/keysIssue a free API key — no email verification, beta convenience only.
body: { "email": string, "label"?: string } → { apiKey, tier, limitPerMinute }
/api/healthLiveness/readiness probe for orchestrators — bypasses rate limiting.
status, checks{ database, polymarket }, uptimeSeconds
Scoring methodology
The PolyScore is 300 + 6.5 × Σ(componentScore × weight) where each component is scored 0–100 from live Polymarket data. The engine uses average-cost position accounting: buying moves cash into basis, exits realize PnL against that basis, and open positions are marked to market. Drawdown, Sharpe, and Sortino are computed on the realized-equity curve.
| Component key | Weight | Measures |
|---|---|---|
| accuracy | 20% | Resolved-market wins plus profitable round-trips, window-consistent |
| consistency | 15% | Active months over months since first trade |
| profitability | 15% | ROI and total PnL on deployed capital |
| riskMgmt | 12% | Bankroll exposure and monthly return volatility |
| positionMgmt | 10% | Holding-period discipline and sizing regularity |
| drawdown | 10% | Max decline of realized + marked equity vs peak capital |
| diversification | 8% | Category breadth and volume concentration (HHI) |
| participation | 5% | Distinct markets traded, log-scaled |
| walletAge | 3% | Years since first on-chain activity |
| liquidity | 2% | Active order flow vs pure buy-and-hold |
Grade thresholds: AAA ≥ 860 · AA ≥ 810 · A ≥ 750 · BBB ≥ 690 · BB ≥ 630 · B ≥ 560 · CCC ≥ 470 · D below. Thresholds are fixed and public so a grade means the same thing everywhere. The returned grade may be lower than rawGrade — see Integrity flags below.
Integrity flags
Polymarket's public API exposes no counterparty identity, so true wash-trade or Sybil detection between wallets one entity controls is not possible from this data source alone. What ships instead is a set of narrow, honest heuristics — thin track record, a wallet less than 30 days old, volume concentrated in one market with heavy trade count, suspiciously uniform bet sizes, and 20+ trades inside a 10-second window. Each is a signal, not proof.
Every wallet response includes integrityFlags (empty if none triggered), confidence (high/medium/low), and rawGrade (the grade before any flag capped it). A severe flag caps the returned grade — e.g. a wallet can't show AAA on ten days of history no matter how the math works out. Anything gating real capital should read confidence and the flag list, not just the numeric score.
Errors
| 400 | Invalid wallet address or request body |
| 404 | No Polymarket trading history for this wallet |
| 429 | Rate limit exceeded — see X-RateLimit-* response headers |
| 502 | Upstream Polymarket data temporarily unavailable |
Rate limits & freshness
Every response carries X-RateLimit-Limit, X-RateLimit-Remaining, and X-RateLimit-Reset headers on a rolling 60-second window.
| Tier | Limit | Notes |
|---|---|---|
| Anonymous | 30 req/min | No key — bucketed by IP address |
| Free (default key) | 120 req/min | Issued instantly via POST /api/keys |
| Pro | 600 req/min | Modeled in the schema; not yet purchasable |
Wallet profiles persist in a database and are considered fresh for five minutes. A stale profile is still served instantly while a background refresh runs — you never block on Polymarket at request time once a wallet has been scored once. A first-ever scan of a large wallet can take up to ~20 seconds while history is indexed.
Data sources & limitations
- All inputs come from Polymarket's public data API: activity history, current positions, portfolio value, and lifetime aggregates.
- Activity history is capped upstream at 3,500 events. For hyperactive wallets, behavioral metrics reflect the most recent window while headline PnL, volume, and markets-traded use authoritative lifetime aggregates.
- Win/loss detection requires an actual payout — losing positions flagged "redeemable" for $0 are counted as losses, and outcomes are measured over consistent time windows.
- Sybil resistance is not solved — see Integrity flags above for what is and isn't detectable from public data alone.
- Scores are informational and not financial advice.