Developer

The Developer Portal is where Quant subscribers manage their REST API access and outbound webhooks. It is for pulling Polywhaler data into your own systems, building bots and dashboards, or piping events into Slack, Discord, or your back office.

Quant tier

The Developer Portal is a Quant-tier feature. Pro subscriptions do not include API or webhook access.

What you get#

The Developer Portal Dashboard showing tab navigation (Dashboard, API keys, Webhooks, API reference, Webhook events, Quickstart), four stat cards (Requests today, Active keys, Active webhooks, Deliveries) and a recent webhook deliveries panel.
The Developer Portal dashboard. Tabs across the top, usage stats and recent deliveries below.
  • 10,000 API requests per day with a 100/min burst.
  • Whale trades from Polymarket and Kalshi, with insider scores on Polymarket buys, plus resolved outcomes for Polymarket trades, with P&L and ROI, from /v1/outcomes.
  • Real-time outbound webhooks across nine event types.
  • The Bitcoin forecast as data: the model's full probability distributions, every supporting market with its weight, and the past year of hourly runs for backtesting.
  • Bulk CSV, JSON, and Parquet exports up to 100,000 rows per job.

Get an API key#

  1. Click Developer in the sidebar.
  2. Open the API keys tab and create a new key. Give it a name (something like "production" or "laptop") so future-you can tell them apart.
  3. Copy the key right away. Polywhaler will not show it again. If you lose it, revoke and create a new one.

Set up a webhook#

Webhooks push events to a URL you control the moment they happen. Trade webhooks cover Polymarket activity (Kalshi trades do not fire webhooks); the Bitcoin forecast event draws on both platforms. The nine event types you can subscribe to are:

  • trade.high_insider: any whale trade with an insider score of 70 or higher.
  • trade.followed_wallet: any trade by a wallet on your watchlist.
  • trade.vindicated: a flagged suspicious trade just won when its market resolved.
  • black_swan.changed: the black-swan radar moved to a new bucket.
  • oracle.published: a new Prophet daily edition was published.
  • cluster.detected: a new coordinated wallet cluster was detected.
  • consensus.detected: several whales on your watchlist bought the same outcome in the same market.
  • export.completed: one of your bulk-export jobs finished, with the download link and its expiry time in the payload.
  • btc_forecast.updated: a new Bitcoin forecast run went live, with the compact horizon ladder and insights in the payload.
  1. Open the Webhooks tab.
  2. Add the URL Polywhaler should POST to. We sign every payload, so you can verify it came from us.
  3. Pick the events you want to receive. You can subscribe to more than one on the same URL.
  4. Use Test to fire a sample payload at your endpoint before going live.

The signature is in the X-Polywhaler-Signature header as sha256= followed by the hex HMAC-SHA256 of the raw request body, keyed with your signing secret. It covers the body only and carries no timestamp, so it proves who sent a delivery but does not stop a replay.

Answer with any 2xx within 10 seconds. Anything else is retried, five attempts in all, roughly 1 minute, 5 minutes, 25 minutes and 2 hours apart. A retry carries the same X-Polywhaler-Delivery ID, so use it to drop duplicates.

Calling the API#

Authentication#

Keys are bearer tokens and start with pwhk_. Send them as Authorization: Bearer pwhk_.... A key belonging to a free or Pro account is rejected: the API is Quant only, and the rejection says so rather than returning an empty result.

Base URL#

Everything lives under /api/v1.

Filters worth knowing#

  • venue on /v1/trades takes polymarket (the default), kalshi or all. See venues.
  • sports takes include, exclude or only, and defaults to include, so a default query returns sports and esports trades. Pass sports=exclude to match Home, which leaves them out. /v1/leaderboard works the other way: it leaves sports whales out unless you pass exclude_sports=false.
  • Trade size: Polymarket trades are stored from $2,000, and /v1/trades applies no floor above that unless you pass min_amount. Kalshi trades start at $5,000, or $10,000 for sports and for 15-minute and hourly markets.
  • min_smart_money, min_win_rate and max_rank filter by trader quality. See scores and badges.
  • /v1/outcomes?vindicated=true returns flagged trades that went on to win, and /v1/smart-money-flow returns net capital flow by category.

API changes#

September 25, 2026#

  • /v1/wallets/{addr}/positions: closed positions gain costUsd, what the position cost in dollars. totalBought is now shares on every row, as Polymarket reports it; positions reclassified from resolved-but-unclaimed used to report dollars there.
  • summary.avgRoiPercent on the same endpoint is now realized P&L over dollars invested. It was computed over shares, which read low by roughly the average entry price, so expect it to be around 1.8x higher for a typical wallet.
  • Categories: new trades on weather markets now arrive as science, and single-game markets that carry no tags ("Will Chelsea FC win on…", spreads, draws) as sports instead of other, so a /v1/trades query with sports=exclude now leaves them out. Trades already stored keep their category.

Tabs in the portal#

  • Dashboard: usage and quota overview, plus recent webhook delivery activity.
  • API keys: create, revoke, and manage your keys.
  • Webhooks: configure outbound subscriptions.
  • API reference: the endpoint reference, with request and response shapes.
  • Webhook events: the full schema of every webhook event Polywhaler emits.
  • Quickstart: copy-paste examples to get your first request out the door in under a minute.

When you outgrow this#

Quant covers most use cases: model training, backtests, dashboards, alerts into your own infra. If you need higher rate limits or a dedicated lane, reach out by email and we will figure it out.