Polychads Alerts API

Real-time Polymarket insider trading alerts delivered to your application. Detect fresh wallets, accumulators, and coordinated clusters before the market moves.

Authentication

All API requests require an API key passed in the Authorization header using Bearer token format.

Authorization: Bearer YOUR_API_KEY

curl -H "Authorization: Bearer pc_your_key_here" \
  https://polychadsbot.xyz/api/v1/me

Pricing & Tiers

Choose the tier that fits your needs. All tiers include full REST API access.

Quick Start

Get your first alert in 30 seconds.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/me

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/alerts/latest?limit=5

const ws = new WebSocket(
  "wss://polychadsbot.xyz/ws/alerts?api_key=YOUR_KEY"
);
ws.onmessage = (e) => {
  const msg = JSON.parse(e.data);
  if (msg.type === "alert") {
    console.log("🔔 New alert:", msg.data);
  }
};

GET /alerts/latest

Get the most recent alerts. Returns an array of alert objects, newest first.

Parameters

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://polychadsbot.xyz/api/v1/alerts/latest?limit=2"

[
  {
    "id": 2220,
    "alert_type": "fresh_accumulator",
    "wallet_address": "0x9B3b...6BC3",
    "event_title": "US strikes Iran by Feb 28?",
    "side": "BUY",
    "outcome": "Yes",
    "entry_price": 0.19,
    "usdc_value": 1900.0,
    "signal_score": 80,
    "category": "world",
    "created_at": "2026-02-27 11:35:26",
    "details": { ... }
  }
]

GET /alerts

Paginated alert history with filtering. Returns alerts wrapped in a pagination object.

Parameters

curl -H "Authorization: Bearer YOUR_KEY" \
  "https://polychadsbot.xyz/api/v1/alerts?\
category=crypto&side=BUY&min_signal=60&page=1"

{
  "alerts": [ ... ],
  "total": 581,
  "page": 1,
  "page_size": 50,
  "has_more": true
}

GET /alerts/:id

Get a single alert by its ID.

Path Parameters

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/alerts/2220

GET /stats

Get aggregate bot statistics.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/stats

{
  "total_alerts": 2226,
  "alerts_today": 183,
  "avg_signal_today": 59.2,
  "clusters_today": 0,
  "win_rate": 0.0,
  "total_resolved": 0,
  "total_won": 0
}

GET /me

Get info about your API key — tier, rate limits, and today's usage.

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/me

{
  "name": "MyApp",
  "tier": "pro",
  "rate_limit": "300/min",
  "websocket": true,
  "webhooks": false,
  "realtime": true,
  "max_page_size": 50,
  "requests_today": 142
}

WebSocket Stream

Connect for real-time alert push. Alerts are delivered the instant they're detected — no polling required.

const ws = new WebSocket(
  "wss://polychadsbot.xyz/ws/alerts?api_key=YOUR_KEY"
);

ws.onmessage = (event) => {
  const msg = JSON.parse(event.data);

  switch (msg.type) {
    case "connected":
      console.log("✅ Connected:", msg.message);
      break;
    case "alert":
      console.log("🔔 New alert:", msg.data);
      console.log(`  ${msg.data.side} ${msg.data.outcome} @ ${msg.data.entry_price}`);
      console.log(`  $${msg.data.usdc_value} | Signal: ${msg.data.signal_score}`);
      break;
    case "pong":
      break; // heartbeat response
  }
};

// Keep-alive heartbeat
setInterval(() => {
  if (ws.readyState === WebSocket.OPEN) {
    ws.send("ping");
  }
}, 25000);

Message Types

Webhooks

Register a URL to receive alerts automatically via HTTP POST. Filter by category and minimum signal score.

curl -X POST \
  -H "Authorization: Bearer YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "url": "https://your-app.com/webhook/polychads",
    "categories": "crypto,world",
    "min_signal": 40
  }' \
  https://polychadsbot.xyz/api/v1/webhooks

Your endpoint will receive POST requests with the alert JSON body whenever a matching alert fires.

Manage Webhooks

curl -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/webhooks

curl -X DELETE -H "Authorization: Bearer YOUR_KEY" \
  https://polychadsbot.xyz/api/v1/webhooks/1

Alert Object

Full schema of an alert returned by all endpoints.

Signal Score

Each alert is scored for insider likelihood. Higher scores indicate stronger signals.

Categories

Alerts are automatically categorized based on the Polymarket event.

Errors

The API returns standard HTTP status codes with JSON error details.

{
  "detail": "Rate limit exceeded. pro tier: 300 req/min."
}

Rate Limits

Rate limits use a 1-minute sliding window per API key.