Authentication

API Key AuthenticationComing Soon

API access will be available for Pro and Whale tier subscribers. Each subscription includes a unique API key that must be sent with every request.

Request Header

Authorization: Bearer wp_live_k7x9m2...your_api_key

API keys can be generated and revoked from your account dashboard. Keep your key secret -- do not expose it in client-side code or public repositories.

Rate Limits

Rate limits are enforced per API key on a sliding 60-second window. Exceeding the limit returns a 429 status with a Retry-After header.

Tier	Requests / Minute	Burst	Price
Free	10	15	$0
Pro	100	150	$47/mo
Whale	1,000	1,500	$97/mo

Response Format

All responses are JSON with UTF-8 encoding. Successful responses return the data directly. Errors include a message field with a human-readable description.

Status Codes

200Success -- data returned in response body

400Bad request -- invalid parameters

401Unauthorized -- missing or invalid API key

429Rate limited -- too many requests

500Internal server error

Error Response

{
  "error": true,
  "message": "Rate limit exceeded. Retry after 42 seconds.",
  "retryAfter": 42
}

Endpoints

All endpoints return JSON. Timestamps use ISO 8601 format. Dollar amounts are in USD. Prices and probabilities are expressed as decimals between 0 and 1.

GET/api/statsDashboard statistics▼

Returns live platform statistics including trader counts, trade volume, signal accuracy, active signals with market data, top experts, and top traders. Data is cached for 60 seconds server-side.

Example Response

{
  "traderCount": 2347,
  "tradeCount": 184520,
  "volumeTracked": 42850000,
  "expertCount": 1423,
  "signalAccuracy7d": 0.73,
  "activeSignals": 18,
  "categories": ["politics", "sports", "crypto", "science", "culture"],
  "resolvingToday": [
    {
      "market_title": "Will Bitcoin exceed $100k by March 2026?",
      "outcome": "Yes",
      "category": "crypto",
      "expert_count": 12,
      "avg_price": 0.68,
      "signal_strength": 0.82,
      "confidence_tier": "A",
      "total_usd": 284500
    }
  ],
  "topExperts": [
    {
      "wallet": "0x1a2b...3c4d",
      "category": "politics",
      "expert_score": 94.2,
      "win_rate": 0.78,
      "trade_count": 312
    }
  ],
  "topTraders": [
    {
      "proxy_wallet": "0x5e6f...7a8b",
      "username": "WhaleAlpha",
      "pnl": 523400,
      "volume": 2150000
    }
  ]
}

GET/api/scoreboardSignal scoreboard with resolution data▼

Returns the 500 most recent consensus signals with resolution status. Each signal includes the original prediction, confidence tier, and whether the market has resolved (with the actual outcome). Used to power the accuracy scoreboard and track record pages.

Example Response

{
  "signals": [
    {
      "id": 1042,
      "condition_id": "0x8f3a...b2c1",
      "market_title": "Will the Fed cut rates in March 2026?",
      "outcome": "Yes",
      "category": "politics",
      "expert_count": 8,
      "avg_price": 0.72,
      "signal_strength": 0.85,
      "confidence_tier": "A",
      "total_usd": 195000,
      "created_at": "2026-03-10T14:30:00Z",
      "is_resolved": true,
      "actual_outcome": "Yes",
      "is_correct": true
    }
  ],
  "summary": {
    "total": 500,
    "resolved": 312,
    "correct": 228,
    "accuracy": 0.731,
    "tierBreakdown": {
      "A": { "total": 85, "correct": 71, "accuracy": 0.835 },
      "B": { "total": 112, "correct": 84, "accuracy": 0.750 },
      "C": { "total": 78, "correct": 51, "accuracy": 0.654 },
      "D": { "total": 37, "correct": 22, "accuracy": 0.595 }
    }
  }
}

GET/api/arbitrageCross-platform arbitrage opportunities▼

Returns real-time cross-platform arbitrage opportunities between Polymarket and Kalshi. Includes live prices from both platforms, fee-adjusted ROI calculations (Polymarket 2% + Kalshi 7%), and strategy recommendations. Cached for 5 minutes.

Example Response

{
  "opportunities": [
    {
      "market_title": "Will Trump win the 2028 GOP nomination?",
      "polymarket_yes": 0.62,
      "polymarket_no": 0.38,
      "kalshi_yes": 0.55,
      "kalshi_no": 0.45,
      "spread": 0.07,
      "fee_adjusted_roi": 0.042,
      "strategy": "Buy YES on Kalshi ($0.55), Sell YES on Polymarket ($0.62)",
      "polymarket_url": "https://polymarket.com/event/...",
      "kalshi_url": "https://kalshi.com/markets/...",
      "kalshi_ticker": "TRUMPGOP-28",
      "last_updated": "2026-03-16T12:00:00Z",
      "confidence": "high"
    }
  ],
  "meta": {
    "total_opportunities": 14,
    "avg_spread": 0.045,
    "last_scan": "2026-03-16T12:00:00Z"
  }
}

GET/api/wallet/[address]Wallet profile and trade history▼

Returns detailed profile data for a specific wallet address, including trade history, P&L, win rate, expert scores by category, and recent positions. The address parameter is the Polymarket proxy wallet address.

Parameters

Name	Type	Required	Description
address	string	Required	Polymarket proxy wallet address (path parameter)

Example Response

{
  "wallet": "0x1a2b3c4d5e6f7a8b9c0d1e2f3a4b5c6d7e8f9a0b",
  "username": "CryptoWhale42",
  "pnl": 182400,
  "volume": 1540000,
  "trade_count": 847,
  "win_rate": 0.72,
  "categories": [
    {
      "category": "crypto",
      "expert_score": 91.3,
      "win_rate": 0.78,
      "trade_count": 234
    },
    {
      "category": "politics",
      "expert_score": 85.7,
      "win_rate": 0.69,
      "trade_count": 198
    }
  ],
  "recent_trades": [
    {
      "market_title": "Will ETH hit $5k by June 2026?",
      "outcome": "Yes",
      "price": 0.42,
      "amount_usd": 15000,
      "timestamp": "2026-03-15T09:22:00Z"
    }
  ]
}

POST/api/email-signupEmail list signup▼

Registers a new email address for the Whale Predictions mailing list. Sends a confirmation email to the provided address. Includes honeypot and duplicate detection.

Parameters

Name	Type	Required	Description
email	string	Required	Valid email address to register
ref	string	Optional	Referral code (if signing up via a referral link)

Request Body

{
  "email": "trader@example.com",
  "ref": "abc123"
}

Example Response

{
  "success": true,
  "message": "Confirmation email sent. Please check your inbox."
}

GET/api/email-signup/confirmEmail confirmation▼

Confirms an email signup using the token sent in the confirmation email. Marks the email as verified in the database and redirects to a success page.

Parameters

Name	Type	Required	Description
token	string	Required	Confirmation token from the verification email (query parameter)

Example Response

{
  "success": true,
  "message": "Email confirmed successfully.",
  "email": "trader@example.com"
}

Webhooks

Real-time push notifications for critical market events. Configure webhook URLs in your account dashboard.

Webhook AlertsComing Soon

Whale tier subscribers will be able to receive instant webhook notifications for the following events. Webhooks are delivered as POST requests with a JSON payload and include an HMAC signature for verification.

signal.newsignal.resolvedarb.detectedarb.closedwhale.large_tradewallet.activity

Example Webhook Payload

{
  "event": "signal.new",
  "timestamp": "2026-03-16T14:30:00Z",
  "data": {
    "signal_id": 1043,
    "market_title": "Will BTC hit $150k by Dec 2026?",
    "outcome": "Yes",
    "confidence_tier": "A",
    "expert_count": 11,
    "signal_strength": 0.88,
    "avg_price": 0.35
  }
}