API Reference

Production API for developers building on Polyanna analytics.

Quickstart#

Most read endpoints are available without authentication, including leaderboard discovery, 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.

Authenticated request

curl -H "X-API-Key: pa_live_your_key" \
  "https://polyanna.app/api/v1/trader/0x1234567890abcdef1234567890abcdef12345678/analytics"

Anonymous request

curl "https://polyanna.app/api/v1/leaderboard"

Authentication#

Public reads are available without authentication on GET /leaderboard, 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.

Whale Radar endpoints are tier-aware. Anonymous and free callers receive delayed, wallet-safe payloads; Pro callers receive real-time identity and filters, including full identity for notable-move rows. This public reference only lists endpoints available to API users.

Rate Limiting#

All requests go through a sliding-window rate limiter.

Anonymous5 req/s per IP

Authenticated (bearer)5 req/s per user

API key10 req/s per key

Rate limit headers

X-RateLimit-LimitMaximum requests in current window

X-RateLimit-RemainingRequests left in current window

X-RateLimit-ResetSeconds until window resets

Retry-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.

Errors#

All errors return a JSON body with a detail field.

401Authentication required or credentials invalid

404Resource not found

422Validation error (bad path/query parameters)

429Rate limit exceeded

503Service temporarily unavailable

Example error

{
  "detail": "Missing API key"
}

API Areas#

Shared setup lives here. Product-specific endpoint groups are split into their own pages.

General API

Authentication, rate limits, retries, errors, and shared API behavior.

Trader API

Search traders, fetch public profiles, and read authenticated trader analytics.

Leaderboards API

Discover leaderboard variants and fetch a specific leaderboard by tab and period.

Whale Radar API

Read Whale Radar alerts, showcase rows, alert details, and Pro notification config.

Smart-Money API

Fetch Smart-Money Signals, weekly highlights, historical snapshots, and market-level signal analysis.