Fade The Crowd API (v1)

Programmatic access to contrarian trading signals and bad-wallet analytics from Polymarket.

Base URL

https://fadethecrowd.ai/api/v1

Authentication

All endpoints except /health require an API key. Pass it via the Authorization header:

Example request

curl -H "Authorization: Bearer ftc_YOUR_KEY" \
  https://fadethecrowd.ai/api/v1/signal

API keys are provisioned when you subscribe to an API plan. Manage your key on the Account page.

Rate Limits

Requests are rate-limited per API key on a per-minute sliding window.

Plan	Rate Limit
API Pro	120 requests/min
API Pro+	300 requests/min

Rate limit headers are included on every authenticated response:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 119
X-RateLimit-Reset: 1709000000

When rate-limited, the API returns 429 with a Retry-After header indicating when to retry (in seconds).

Response Format

All responses use a standard JSON envelope:

Success

{
  "ok": true,
  "data": { ... },
  "meta": {
    "timestamp": "2026-02-26T12:00:00.000Z"
  }
}

Error

{
  "ok": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Missing Authorization header"
  }
}

Caching

Authenticated responses include an ETag header. Send If-None-Match with the ETag value to receive a 304 Not Modified response when data hasn't changed, saving bandwidth and counting against your rate limit at a lower cost.

curl -H "Authorization: Bearer ftc_YOUR_KEY" \
  -H "If-None-Match: \"abc123\"" \
  https://fadethecrowd.ai/api/v1/signal

Errors

Status	Code	Meaning
401	`UNAUTHORIZED`	Missing or invalid API key
403	`FORBIDDEN`	Your plan doesn't include this endpoint
404	`NOT_FOUND`	Resource not found
429	`RATE_LIMITED`	Too many requests. Check `Retry-After` header.
500	`INTERNAL_ERROR`	Server error. Retry with backoff.

Endpoints

GET/healthPublic

API health check. No authentication required.

Response

{
  "ok": true,
  "version": "v1",
  "timestamp": "2026-02-26T12:00:00.000Z"
}

GET/Requires API key

API discovery. Returns available endpoints and your plan details.

Response

{
  "ok": true,
  "data": {
    "name": "Fade the Crowd API",
    "version": "v1",
    "tier": "pro",
    "rateLimit": "120/min",
    "endpoints": [
      { "path": "/api/v1/signal", "method": "GET", "description": "Current contrarian signal" },
      { "path": "/api/v1/leaderboard", "method": "GET", "description": "Worst wallets leaderboard" },
      ...
    ]
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

GET/signalRequires API key

Current contrarian signal derived from bad-wallet trading activity.

Response

{
  "ok": true,
  "data": {
    "windowMinutes": 60,
    "level": "STRONG",
    "icon": "🔴",
    "headline": "STRONG FADE SIGNAL",
    "summary": "Historically dumb money wallets are piling into this market",
    "direction": "BUY",
    "confidence": 85,
    "tradeCount": 28625,
    "volumeUsd": 1085496.51,
    "updatedAt": "2026-02-26T12:00:00.000Z",
    "fireCount24h": 518,
    "isStale": false,
    "staleMinutes": 1
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

GET/leaderboardRequires API key

Worst-performing wallets ranked by net cashflow, ROI, or trade count.

Query parameters

sort — "cashflow" | "roi" | "trades" (default: "cashflow")
limit — Number of results. Pro: max 50, Pro+: max 50.

Response

{
  "ok": true,
  "data": {
    "sort": "cashflow",
    "entries": [
      {
        "walletAddress": "0x1a2b...3c4d",
        "netCashflowUsd": -12345.67,
        "volumeUsd": 98765.43,
        "tradeCount": 23,
        "winRate": 0.35,
        "resolvedTradesCount": 15,
        "roi": -0.125,
        "roiResolved": -0.089
      }
    ]
  },
  "meta": { "timestamp": "...", "period": "24h" }
}

GET/feedRequires API key

Recent trades from bad-performing wallets.

Query parameters

limit — Number of trades. Pro: max 100, Pro+: max 100.
buys_only — "true" to filter to buy trades only.
category — "sports" | "crypto" | "politics" | "weather" | "stocks"

Response

{
  "ok": true,
  "data": {
    "trades": [
      {
        "id": "cm...",
        "timestamp": "2026-02-26T12:00:00.000Z",
        "walletAddress": "0x1a2b...3c4d",
        "side": "BUY",
        "outcomeToken": "YES",
        "size": 100.5,
        "price": 0.65,
        "usdcSize": 65.33,
        "marketQuestion": "Will BTC reach $100k by March?",
        "marketSlug": "will-btc-reach-100k",
        "marketStatus": "OPEN",
        "polymarketUrl": "https://polymarket.com/event/...",
        "walletRoi": -0.25,
        "walletNetCashflow": -5000.25
      }
    ]
  },
  "meta": { "timestamp": "...", "period": "24h" }
}

GET/wallets/:addressRequires API key

Detailed metrics for a specific wallet. Pro and Pro+ plans only.

Query parameters

include_trades — "true" to include recent trade history.

Response

{
  "ok": true,
  "data": {
    "walletAddress": "0x1a2b3c4d5e6f...",
    "netCashflowUsd": -12345.67,
    "volumeUsd": 98765.43,
    "tradeCount": 50,
    "winRate": 0.40,
    "resolvedTradesCount": 25,
    "roi": -0.125,
    "roiResolved": -0.089,
    "trades": null
  },
  "meta": { "timestamp": "...", "period": "24h" }
}

Set include_trades=true for trade history.

GET/proofRequires API key

Best current "fade" opportunity based on bad-wallet clustering.

Response

{
  "ok": true,
  "data": {
    "available": true,
    "fadeRoiPercent": 45.5,
    "marketQuestion": "Will ETH flip BTC by 2027?",
    "outcomeToken": "YES",
    "avgPrice": 0.42,
    "tradeSizeUsd": 5000.00,
    "walletRoiPercent": -25.3,
    "walletAddress": "0x..."
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

walletAddress is only included for Pro/Pro+ plans. Returns "available": false when no candidate exists.

GET/indexRequires API key

Bad Trader Index time series — daily aggregate metrics for bad wallets.

Query parameters

days — Number of days. Pro: max 90, Pro+: max 90.

Response

{
  "ok": true,
  "data": {
    "days": 7,
    "entries": [
      {
        "date": "2026-02-26",
        "totalBadWallets": 456,
        "combinedNetCashflow": -234567.89,
        "combinedVolume": 5678901.23,
        "averageRoi": -0.125,
        "totalTrades": 12345,
        "buyVolume": 3456789.01,
        "sellVolume": 2222112.22
      }
    ]
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

GET/statusRequires API key

System health and data freshness metrics.

Response

{
  "ok": true,
  "data": {
    "healthy": true,
    "tradeCount": 1234567,
    "walletCount": 45678,
    "marketCount": 9876,
    "badWalletCount": 456,
    "oldestTrade": "2024-06-15T00:00:00.000Z",
    "newestTrade": "2026-02-26T12:00:00.000Z",
    "dataSpanHours": 14400,
    "sampleSizeLabel": "20+ months",
    "isStale": false,
    "staleMinutes": 3
  },
  "meta": { "timestamp": "2026-02-26T12:00:00.000Z" }
}

isStale is true when the newest trade is older than 15 minutes.

Get API Access

Subscribe to an API plan to get your key instantly. Manage your key on the Account page after checkout.

Plan Comparison

Feature	Pro	Pro+
Rate limit	120/min	300/min
Leaderboard results	50	50
Feed results	100	100
Index history	90 days	90 days
Full wallet addresses	Yes	Yes
Wallet detail	Yes	Yes
Full signal details	Yes	Yes

MONITORING

Fade The Crowd API (v1)

Base URL

Authentication

Rate Limits

Response Format

Caching

Errors

Endpoints

Get API Access

Plan Comparison