API Reference
Production API for developers building on Polyanna analytics.
Quickstart#
Most read endpoints are available without authentication, including leaderboard discovery, stats, trader search, and public trader profiles.
For authenticated reads such as trader analytics, auth-gated leaderboard variants, and authenticated full-profile reads, use either a Supabase bearer token or an API key from your account dashboard . External integrations should prefer the X-API-Key header.
curl -H "X-API-Key: pa_live_your_key" \ "https://polyanna.app/api/v1/trader/0x1234567890abcdef1234567890abcdef12345678/analytics"
curl "https://polyanna.app/api/v1/stats"
Authentication#
Public reads are available without authentication on GET /leaderboard, GET /stats, GET /trader, and GET /trader/{address}. Some leaderboard variants are auth-gated and redact or block entries until the caller is authenticated. Protected routes such as GET /trader/{address}/analytics accept either Authorization: Bearer <token> or an API key passed via the X-API-Key header.
Create API keys from your account dashboard. Keys use the pa_live_ prefix and grant higher rate limits than anonymous access.
Rate Limiting#
All requests go through a sliding-window rate limiter.
2 req/s per IP2 req/s per user10 req/s per keyRate limit headers
X-RateLimit-LimitMaximum requests in current windowX-RateLimit-RemainingRequests left in current windowX-RateLimit-ResetSeconds until window resetsRetry-AfterWait time before retry (on 429)Base URL#
https://polyanna.app/api
All endpoint paths below start with /v1.
Retries#
On 429, wait for the Retry-After value before retrying. Use exponential backoff for transient 5xx responses.
Endpoints#
List leaderboards#
https://polyanna.app/api/v1/leaderboardReturns metadata for all available leaderboard variants. Some leaderboard tabs are auth-gated and return redacted entries until the caller is authenticated. Use the id field to fetch a specific leaderboard via GET /leaderboard/{leaderboard_id}.
Parameters
No parameters.
Response
200Successful Response401Authentication required, or provided credentials are invalid422Validation Error429Rate limit exceeded503Service unavailableResponse body
itemsLeaderboardIndex[]Array of objects
Get leaderboard by ID#
https://polyanna.app/api/v1/leaderboard/{leaderboard_id}Returns a single leaderboard by its ID (e.g. volume-7d, roi-all). Auth-gated leaderboard tabs require authentication before their entries can be fetched. The ID format is {tab}-{period}. Call GET /leaderboard to discover available IDs.
Parameters
leaderboard_idstringrequiredpathlimitintegerqueryMax entries to return. Values above the default require Pro.
Response
200Successful Response401Authentication required, or provided credentials are invalid404Leaderboard not found422Validation Error429Rate limit exceeded503Service unavailableResponse body
entriesLeaderboardEntry[]generatedAtstringidstringperiodTimePeriodtabLeaderboardTabGet platform stats#
https://polyanna.app/api/v1/statsReturns high-level platform-wide trader and market stats.
Parameters
No parameters.
Response
200Successful Response401Authentication required, or provided credentials are invalid422Validation Error429Rate limit exceeded503Service unavailableResponse body
avgMarketsPerTradernumber | nulloptionalnullableavgWinRatenumber | nulloptionalnullablebotVolumeSharenumber | nulloptionalnullabledataCutoffstring | nulloptionalnullabledataPeriodstringdataQualityDataQualityStatus | nulloptionalnullableestimatedBotsstringloserCountinteger | nulloptionalnullablemarketsTrackedstringmedianPnlnumber | nulloptionalnullablemonthlyEventsMonthlyEventCount[]optionalmonthlyFillsMonthlyFillCount[]optionalordersFilledstringtopTraderPnlnumber | nulloptionalnullabletotalFeesPaidnumber | nulloptionalnullabletotalMoneyLostnumber | nulloptionalnullabletotalMoneyWonnumber | nulloptionalnullabletotalTradersstringtotalVolumenumber | nulloptionalnullablewinnerCountinteger | nulloptionalnullableworstTraderPnlnumber | nulloptionalnullableList traders#
https://polyanna.app/api/v1/traderReturns all traders that appear on any leaderboard.
Parameters
No parameters.
Response
200Successful Response401Authentication required, or provided credentials are invalid422Validation Error429Rate limit exceeded503Service unavailableResponse body
itemsSearchableTrader[]Array of objects
Get trader profile#
https://polyanna.app/api/v1/trader/{address}Returns a trader's public profile including PnL, win rate, volume, trade count, market count, bot probability score, percentile ranks, and PnL series. When authenticated (Tier 2+), the response also includes analytics. The address is case-insensitive (lowercased automatically).
Parameters
addressstringrequiredpathPattern: ^0x[0-9a-fA-F]{40}$
Response
200Successful Response401Authentication required, or provided credentials are invalid404Trader not found422Validation Error429Rate limit exceeded503Service unavailableResponse body
addressstringanalyticsTraderAnalytics | nullnullablebiostring | nulloptionalnullablebotComponentsBotScoreComponents | nulloptionalnullablebotProbabilitynumbermarketCountintegermaxDrawdownnumber | nulloptionalnullablememberSincestringpercentilesPercentileRanks | nulloptionalnullablepnlnumberpnlSeriesPnlDataPoint[]profileImagestring | nulloptionalnullableroinumber | nulloptionalnullableshareVolumenumbersharpeRationumber | nulloptionalnullabletotalBoughtnumber | nulloptionalnullabletradeCountintegerusdVolumenumberusernamestringverifiedBadgebooleanoptionalwinRatenumberxUsernamestring | nulloptionalnullableGet trader analytics#
https://polyanna.app/api/v1/trader/{address}/analyticsReturns deeper trader analytics including profile summary, risk metrics, and behavior breakdowns. The address is case-insensitive (lowercased automatically).
Parameters
addressstringrequiredpathPattern: ^0x[0-9a-fA-F]{40}$
Response
200Successful Response401Authentication required, or provided credentials are invalid403Authenticated caller does not have access to this route404Trader not found422Validation Error429Rate limit exceeded503Service unavailableResponse body
avgPositionSizenumberavgTradesPerMarketnumberbiggestLossTradeRecord | nulloptionalnullablebiggestWinTradeRecord | nulloptionalnullablecategoryBreakdownCategoryCount[]dominantMarketstring | nulloptionalnullablehourlyActivityHourlyActivity[]optionallossStreakintegermarketSignalsMarketSignalsSummary | nulloptionalnullablepnlConcentrationTop3SharenumberoptionaltopicEdgeTopicEdgeSummary | nulloptionalnullablewinStreakintegerErrors#
All errors return a JSON body with a detail field.
401Authentication required or credentials invalid404Resource not found422Validation error (bad path/query parameters)429Rate limit exceeded503Service temporarily unavailable{
"detail": "Missing API key"
}