Developers
Build on the whale flow.
The Polywhaler API serves the whale trades, wallet scores and market signals behind the app, as JSON over REST, with webhooks and bulk exports.
curl -G "https://polywhaler.com/api/v1/trades" \
-d min_amount=50000 \
-d min_insider_score=60 \
-d limit=1 \
-H "Authorization: Bearer pwhk_your_api_key"{
"data": [
{
"venue": "polymarket",
"title": "Fed Decision in October?",
"outcome": "Yes",
"side": "BUY",
"amount": 72500,
"price": 0.18,
"timestamp": 1791418020,
"proxyWallet": "0x93fb…3e4a",
"category": "economy",
"insiderScore": 74,
"insiderBreakdown": { "conviction": 32, "timing": 10, … }
}
],
"pagination": { "limit": 1, "count": 1, "nextCursor": "1791418019" }
}The data behind the app.
The same trades, scores and rankings as Polywhaler itself, so what you build matches what you see. Every endpoint is in the OpenAPI spec.
Whale trades
Polymarket and Kalshi whale trades, filtered by size, side, category and insider score, newest first.
Wallets
Any wallet's profile, rank, open positions, trade history and the clusters it trades in.
Leaderboard
The Smart Money ranking, with the score, win rate and P&L behind each wallet.
Insider signals
Insider scores and their factors on Polymarket buys, suspicious events and coordinated clusters.
Markets and flow
Whale volume by event, smart-money flow by category, and the positions your whales agree on.
Research
The Bitcoin forecast and its markets, The Prophet's editions and the black swan radar.
Webhooks
Push, don't poll.
Register an https endpoint and Polywhaler posts each event as it happens, signed with HMAC SHA-256 so you can check it came from us. Trade events can be narrowed by size, category and insider score, and failed deliveries are retried with backoff.
- trade.high_insider
- trade.followed_wallet
- trade.vindicated
- cluster.detected
- consensus.detected
- black_swan.changed
- oracle.published
- btc_forecast.updated
- export.completed
import crypto from "node:crypto"
// X-Polywhaler-Signature: sha256=<hex HMAC of the raw body>
export function verify(rawBody, header, secret) {
const expected = "sha256=" +
crypto.createHmac("sha256", secret).update(rawBody).digest("hex")
return header.length === expected.length &&
crypto.timingSafeEqual(Buffer.from(header), Buffer.from(expected))
}Bulk exports
Export it for your backtests.
Ask for up to 100,000 Polymarket whale trades or resolved outcomes at a time, as CSV, JSON or Parquet. The file is usually ready within minutes, and an export.completed webhook tells you when it is.
curl -X POST "https://polywhaler.com/api/v1/exports" \
-H "Authorization: Bearer pwhk_your_api_key" \
-H "Content-Type: application/json" \
-d '{ "dataset": "outcomes", "format": "parquet" }'Part of Quant.
The API comes with the Quant plan, $99 a month, or $599 a year, along with everything in Pro.
- requests a day
- 10,000
- requests a day
- requests a minute per key
- 100
- requests a minute per key
- webhook events
- 9
- webhook events
FAQs
Common questions about the Polywhaler API.
Which plan includes the API?
Quant. API keys, webhooks and bulk exports are part of the Quant plan, $99 a month, or $599 a year. Pro does not include API access.
How do I authenticate?
Create a key on the Developer page and send it as a Bearer token in the Authorization header. Keys start with pwhk_, are shown once, and you can have up to five.
What are the rate limits?
10,000 requests a day, reset at midnight UTC, and up to 100 requests a minute per key. Every response carries X-RateLimit headers, and a 429 says when to retry.
Does the API cover Kalshi?
The trades endpoint covers Polymarket and Kalshi (venue=kalshi or venue=all). The other endpoints, webhooks and exports cover Polymarket.
Is there an SDK?
Not yet. The API is JSON over HTTPS with an OpenAPI 3.1 spec, so any HTTP client works, and you can generate a typed client from the spec.
How fresh is the data?
Whale trades sync every minute. The leaderboard refreshes every 15 minutes and the Bitcoin forecast every hour.
