Polymarket whale intelligence,
sold per call to AI agents

Whale trades ≥ $10,000, wallet win rates and smart-money consensus from the pipeline behind @predge_alerts_bot — as plain HTTP endpoints your agent pays for with USDC over the x402 protocol. No API keys. No accounts. $0.005–$0.03 per call.

# 1. ask — costs nothing
curl -i "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5"
HTTP/2 402  ← PAYMENT-REQUIRED header: price, asset, payTo (base64 JSON)

# 2. pay — any x402 client signs USDC (EIP-3009) and retries for you
npx x402-proxy "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5"
HTTP/2 200  ← data + PAYMENT-RESPONSE header with on-chain settle tx

🐋 Scored whale flow

Every trade ≥ $10,000, tagged with the wallet's Predge score (0–100) and realized win rate — resolved markets only, no vibes.

⚡ Pay per call

402 → sign → 200. USDC on Base, settled on-chain by an x402 facilitator. Your wallet needs no ETH — the facilitator pays gas.

🤖 Agent-native

Machine-readable everything: self-describing GET /, discovery metadata in every 402, llms.txt, OpenAPI.

🧾 Honest data

15-min delay stated upfront. Young dataset says insufficient_data instead of pretending. Errors are never charged.

Quickstart

Three ways in

1 · Look first — free

Every paid route answers unpaid requests with 402 and a PAYMENT-REQUIRED header: base64 JSON carrying the exact price, USDC contract, pay-to address and an example response body. Window-shopping is free:

curl -si "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5" \
  | grep -i '^payment-required:' | cut -d' ' -f2 | base64 -d | jq .

2 · Pay from a shell or TypeScript

Generate a wallet and fund it with a little USDC on Base — $1 covers a lot of calls at these prices, and no ETH is ever needed (the facilitator pays gas). Then:

# zero-code: proxy pays and prints the JSON
npx x402-proxy "https://x402-api-production-266e.up.railway.app/v1/signals/daily"
// TypeScript — the same flow the API's own smoke tests use
import { privateKeyToAccount } from "viem/accounts";
import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
import { ExactEvmScheme } from "@x402/evm/exact/client";

const client = new x402Client();
client.register("eip155:*", new ExactEvmScheme(privateKeyToAccount(process.env.BUYER_PRIVATE_KEY)));
const fetchPaid = wrapFetchWithPayment(fetch, client);

const res = await fetchPaid("https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5");
console.log(res.status);                                  // 200
console.log(res.headers.get("payment-response"));         // base64 settle receipt (tx hash)
console.log(await res.json());                            // the trades

3 · Or just feed this to your agent

Paste the block below into your agent's system prompt / instructions. It contains everything an autonomous agent needs: endpoints, prices, the payment flow, and the honesty rules. Give the agent a funded key in BUYER_PRIVATE_KEY and it can shop on its own.

You can buy Polymarket whale-trade data over HTTP using the x402 payment
protocol. No API key — payment happens per request, in USDC.

SERVICE
Base URL: https://x402-api-production-266e.up.railway.app
Free:  GET /         (self-description — live source of truth for prices/network)
       GET /health   (service + db status)
Paid (price per call):
  GET /v1/whales/latest?limit=50           $0.005  latest whale trades >= $10,000 (limit 1-100)
  GET /v1/whales/market/{conditionId}      $0.01   7-day whale activity for one market
  GET /v1/bets/biggest?window=24h          $0.005  top-20 largest single trades, all markets (24h|7d)
  GET /v1/signals/daily                    $0.02   24h digest: top markets, net flow, largest bets
  GET /v1/signals/consensus                $0.03   smart-money (score>70) net flow + direction, 24h
  GET /v1/wallets/leaderboard?window=30d   $0.01   top wallets by realized win rate (7d|30d)
  GET /v1/wallets/{address}                $0.01   wallet profile: score, win rates, last 20 trades
  GET /v1/wallets/{address}/history        $0.02   trade history + win-rate & modeled-PnL curve
  GET /v1/wallets/compare?addresses=a,b    $0.02   side-by-side 2-10 wallets + market overlap
  GET /v1/markets/movers?window=6h         $0.005  largest YES-price moves (1h|6h|24h)
  GET /v1/markets/{conditionId}/history    $0.01   price/volume history for one market (7d|30d|all)

HOW TO PAY (x402 v2)
1. GET the endpoint with no payment. You receive HTTP 402 with a
   PAYMENT-REQUIRED response header (base64 JSON). accepts[0] looks like:
   { "scheme": "exact", "network": "eip155:8453",
     "amount": "5000",            // atomic USDC, 6 decimals => $0.005
     "asset": "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913",
     "payTo": "0x9084f5000e07c7133d6da5ee4f271ab6d1821144",
     "maxTimeoutSeconds": 60 }
2. Sign an EIP-3009 transferWithAuthorization for exactly that
   amount/asset/payTo with the buyer key.
3. Retry the same request with the signed payload base64-encoded in the
   PAYMENT-SIGNATURE request header.
4. On 200, the PAYMENT-RESPONSE header holds the settle receipt with the
   on-chain tx hash. The facilitator pays gas — the wallet needs USDC only.
Use a library instead of hand-rolling:
  TS:    @x402/fetch + @x402/evm  →  wrapFetchWithPayment(fetch, client)
  shell: npx x402-proxy "<url>"
TS example:
  import { privateKeyToAccount } from "viem/accounts";
  import { wrapFetchWithPayment, x402Client } from "@x402/fetch";
  import { ExactEvmScheme } from "@x402/evm/exact/client";
  const client = new x402Client();
  client.register("eip155:*",
    new ExactEvmScheme(privateKeyToAccount(process.env.BUYER_PRIVATE_KEY)));
  const fetchPaid = wrapFetchWithPayment(fetch, client);
  const res = await fetchPaid(
    "https://x402-api-production-266e.up.railway.app/v1/whales/latest?limit=5");

WALLET
Network is Base mainnet (eip155:8453). Fund the buyer wallet with USDC on
Base — no ETH needed, the facilitator pays gas (EIP-3009). $1 of USDC
covers 30-200 calls at these prices; use a dedicated low-balance wallet
for agent spending. Always trust GET / and the live 402 headers over
cached docs.

RULES
- Data is delayed 15 minutes. Never present it as real-time.
- {"insufficient_data": true, "reason": ...} is a valid, charged answer —
  surface the reason, do not retry in a loop.
- Win rates count RESOLVED markets only; /v1/markets/movers prices come
  from trade prints, not orderbook quotes.
- 4xx/5xx are never charged. Unknown wallet profile → 404 (not charged).
- Budget: a full sweep of all 11 endpoints costs $0.145. The server caches
  60 s (whales, movers) to 5 min (aggregates) — re-buying sooner returns
  the same data, so cache on your side too.
- Rate limit: 10 requests/sec per IP.
Endpoints

Eleven routes, one wallet

All routes are GET, return JSON, and carry their own discovery metadata (description, input schema, example output) in the 402 header — what you read below is generated from exactly that. Paid data is delayed 15 minutes; real-time alerts remain exclusive to Predge Pro.

RoutePriceReturns
/v1/whales/latest$0.005Latest whale trades ≥ $10k
/v1/whales/market/{conditionId}$0.017-day whale activity for one market
/v1/bets/biggest$0.005Top-20 largest single trades, all markets
/v1/signals/daily$0.0224h digest: top markets, net flow, largest bets
/v1/signals/consensus$0.03Smart-money consensus (premium)
/v1/wallets/leaderboard$0.01Top wallets by realized win rate
/v1/wallets/{address}$0.01Full wallet profile
/v1/wallets/{address}/history$0.02Trade history + win-rate & modeled-PnL curve
/v1/wallets/compare$0.02Side-by-side 2–10 wallets + overlap
/v1/markets/movers$0.005Largest YES-price moves
/v1/markets/{conditionId}/history$0.01Price/volume history for one market
/ and /healthfreeSelf-description · status
GET /v1/whales/latest?limit=50 $0.005

Latest Polymarket whale trades (15 min delay). Trades ≥ $10,000 notional with market, side, size, price, wallet address and Predge wallet score (0–100, 30d win rate). Source: Predge whale-tracking pipeline.

ParamInTypeNotes
limitqueryintegerMax trades to return, 1–100, default 50
Example response
{
  "count": 1,
  "delay_minutes": 15,
  "whale_min_usd": 10000,
  "trades": [
    {
      "platform": "polymarket",
      "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39",
      "market_title": "Will the Fed cut rates in September?",
      "market_slug": "fed-rate-cut-september",
      "category": "economics",
      "side": "yes",
      "price": 0.62,
      "size_usd": 25400,
      "wallet": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8",
      "wallet_score": 81,
      "wallet_win_rate_30d": 0.67,
      "tx_hash": "0x6a7de5…",
      "block_timestamp": "2026-07-17T09:41:02.000Z"
    }
  ]
}
GET /v1/whales/market/{conditionId} $0.01

Whale activity for one Polymarket market over the last 7 days (15 min delay). Returns market info, aggregate whale volume, YES/NO split, net flow, unique whale wallets, and up to 200 trades.

ParamInTypeNotes
conditionIdpathstringPolymarket condition id (0x… 32-byte hex)
Example response
{
  "market": {
    "condition_id": "0x178a746e2b342c25b1d78d0f0d0ea77157c9b6d40b2e97ffbf827cd7f9994c39",
    "platform": "polymarket",
    "title": "Will the Fed cut rates in September?",
    "category": "economics",
    "yes_price": 0.62,
    "status": "active"
  },
  "window_days": 7,
  "summary": {
    "whale_trades": 14,
    "whale_volume_usd": 412000,
    "yes_volume_usd": 290000,
    "no_volume_usd": 122000,
    "net_flow_usd": 168000,
    "unique_wallets": 9
  },
  "trades": [ { "…": "same shape as /v1/whales/latest, up to 200" } ]
}
GET /v1/bets/biggest?window=24h $0.005

Largest single trades by notional across all Polymarket markets in the window (15 min delay). Same trade shape as /v1/whales/latest, sorted by size_usd descending, top-20. Live (unresolved) flow — outcome_verified: false.

ParamInTypeNotes
windowquerystring24h | 7d, default 24h
Example response
{
  "window": "24h",
  "outcome_verified": false,
  "bets": [
    {
      "condition_id": "0x178a…4c39",
      "market_title": "Will the Fed cut rates in September?",
      "side": "yes",
      "size_usd": 184000,
      "price": 0.62,
      "wallet": "0x8dab…69e8",
      "wallet_score": 81,
      "traded_at": "2026-07-22T04:11:00.000Z"
    }
  ]
}
GET /v1/signals/daily $0.02

Aggregated 24h whale digest (15 min delay): top-10 markets by whale volume with YES/NO net flow, top-10 largest single bets, and totals — whale trade count, volume, unique wallets. One call = the full daily picture.

Example response
{
  "window_hours": 24,
  "generated_at": "2026-07-17T10:00:00.000Z",
  "totals": {
    "whale_trades": 87,
    "whale_volume_usd": 2310000,
    "unique_wallets": 41,
    "markets_touched": 23
  },
  "top_markets": [
    {
      "condition_id": "0x178a…4c39",
      "title": "Will the Fed cut rates in September?",
      "category": "economics",
      "whale_trades": 14,
      "whale_volume_usd": 412000,
      "yes_volume_usd": 290000,
      "no_volume_usd": 122000,
      "net_flow_usd": 168000
    }
  ],
  "largest_bets": [ { "…": "trade objects with wallet_score / win_rate" } ]
}
GET /v1/wallets/leaderboard?window=30d&limit=50 $0.01

Top Polymarket wallets ranked by realized win rate: computed from RESOLVED markets only — a trade wins when its side matches the final resolution. Wallets need ≥ 10 trades in the window and at least one decided trade. Honest degradation via insufficient_data while the dataset is young.

ParamInTypeNotes
windowquerystring7d | 30d, default 30d
limitqueryinteger1–100, default 50
Example response
{
  "window": "30d",
  "min_trades": 10,
  "insufficient_data": false,
  "wallets": [
    {
      "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8",
      "score": 81,
      "win_rate": 0.71,
      "decided_trades": 17,
      "trades_count": 24,
      "total_volume_usd": 412000,
      "avg_position_usd": 17166.67
    }
  ]
}
GET /v1/wallets/{address} $0.01

Full profile of one wallet: Predge score (0–100), win rates (live-computed 7d/30d from resolved markets + scorer's 30d/90d), all-time totals (trades, avg position, and modeled_pnl_*), top-5 favorite categories, and the last 20 trades (15 min delay). Honesty flags via outcome_verified: win rate is verified on resolved markets (true), while modeled_pnl_* is a MODELED signed-volume proxy from the scorer — not realized/settled P&L (false). Unknown wallet → 404, not charged.

ParamInTypeNotes
addresspathstringProxy-wallet address, 0x… lowercase
Example response
{
  "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8",
  "found": true,
  "score": 81,
  "score_updated_at": "2026-07-18T00:00:04.000Z",
  "outcome_verified": { "win_rate": true, "pnl": false },
  "note": "modeled_pnl_* is a MODELED signed-volume proxy from the Predge scorer (+size on wins, −size on losses over resolved markets), NOT realized/settled P&L.",
  "win_rate": { "7d": 0.67, "30d": 0.71, "scorer_30d": 0.7, "scorer_90d": 0.64 },
  "totals": {
    "trades_all_time": 214,
    "modeled_pnl_30d_usd": 48100.5,
    "modeled_pnl_all_time_usd": 302400,
    "avg_position_usd": 12800,
    "first_seen_at": "2026-05-02T10:11:00.000Z"
  },
  "favorite_categories": [
    { "category": "economics", "trades": 88, "volume_usd": 1204000 }
  ],
  "recent_trades": [ { "…": "last 20 trade objects" } ]
}
GET /v1/wallets/{address}/history $0.02

Historical trades for one wallet plus a running win-rate & modeled_pnl curve, computed only from RESOLVED markets. Unresolved trades still appear (won: null, modeled_pnl_usd: null) but do not move the curve. Up to 500 trades, most-recent-first (15 min delay). Honesty flags via outcome_verified: win rate verified on resolved markets (true), while modeled_pnl_usd is a MODELED estimate (assumes a $1 binary payout per winning share) — not realized/settled P&L (false). Unknown wallet → 404, not charged.

ParamInTypeNotes
addresspathstringProxy-wallet address, 0x… lowercase
windowquerystring30d | 90d | all, default 30d (all bounded to 365 days)
Example response
{
  "address": "0x8dab6cf42d7e4d1cd6cca897b9e12a8cbe6d69e8",
  "found": true,
  "window": "30d",
  "outcome_verified": { "win_rate": true, "pnl": false },
  "note": "modeled_pnl_usd assumes a $1 binary payout per winning share (shares = size_usd ÷ entry price); NOT realized/settled P&L.",
  "summary": { "resolved_trades": 17, "win_rate": 0.71, "modeled_pnl_usd": 48100.5 },
  "trades": [
    { "condition_id": "0x178a…4c39", "side": "yes", "size_usd": 22000,
      "entry_price": 0.44, "won": true, "modeled_pnl_usd": 28000,
      "resolved_at": "2026-07-19T00:00:00.000Z" }
  ]
}
GET /v1/wallets/compare?addresses=0x…,0x… $0.02

Side-by-side comparison of 2–10 wallets. Each wallet: Predge score, live win_rate_7d/win_rate_30d (RESOLVED markets only — outcome_verified: {win_rate: true, pnl: false}), modeled_pnl_30d_usd/modeled_pnl_all_time_usd (a MODELED signed-volume proxy from the scorer, not realized/settled P&L), and top-5 favorite categories; plus market_overlap: markets traded by ≥ 2 of the compared wallets. Wallets unknown to the dataset return found: false rather than being dropped.

ParamInTypeNotes
addressesquerystringComma-separated 0x… addresses, 2–10 (deduplicated)
Example response
{
  "outcome_verified": { "win_rate": true, "pnl": false },
  "wallets": [
    { "address": "0x8dab…69e8", "found": true, "score": 81,
      "win_rate_30d": 0.71, "modeled_pnl_all_time_usd": 302400,
      "favorite_categories": ["economics", "politics"] },
    { "address": "0x1234…7890", "found": false }
  ],
  "market_overlap": [ { "condition_id": "0x178a…4c39", "wallets": 2 } ]
}
GET /v1/markets/movers?window=6h $0.005

Largest YES-price moves across active markets over a 1h/6h/24h window (15 min delay). Prices are derived from stored trade prints normalized to the YES side (NO prints count as 1 − price) — not orderbook quotes; markets need ≥ 2 prints in the window. Top-20 by |delta|.

ParamInTypeNotes
windowquerystring1h | 6h | 24h, default 6h
Example response
{
  "window": "6h",
  "insufficient_data": false,
  "note": "prices derived from trade prints normalized to the YES side, not orderbook quotes",
  "markets": [
    {
      "condition_id": "0x178a…4c39",
      "title": "Will the Fed cut rates in September?",
      "category": "economics",
      "price_before": 0.44,
      "price_now": 0.62,
      "delta": 0.18,
      "prints_in_window": 9,
      "volume_in_window_usd": 96400,
      "whale_volume_in_window_usd": 71000
    }
  ]
}
GET /v1/markets/{conditionId}/history $0.01

Price/volume history for one Polymarket market. Trade-print price series in daily buckets (price normalized to the YES side, not orderbook quotes — outcome_verified.flow: false) with per-bucket volume and whale volume, plus up to 200 individual prints. Includes resolution/resolved_at straight off the markets row when settled (outcome_verified.resolution: true). 15 min delay. Unknown market → 404, not charged.

ParamInTypeNotes
conditionIdpathstringPolymarket condition id (0x… 32-byte hex)
windowquerystring7d | 30d | all, default 30d (all bounded to 180 days)
Example response
{
  "market": {
    "condition_id": "0x178a…4c39",
    "title": "Will the Fed cut rates in September?",
    "category": "economics",
    "status": "active",
    "resolution": null,
    "resolved_at": null
  },
  "window": "30d",
  "outcome_verified": { "flow": false, "resolution": true },
  "buckets": [
    { "bucket_start": "2026-07-17T00:00:00.000Z", "trades": 9,
      "volume_usd": 96400, "whale_volume_usd": 71000, "avg_price": 0.58 }
  ],
  "trades": [ { "…": "same shape as /v1/whales/latest, up to 200" } ]
}
GET /v1/signals/consensus $0.03

Premium. Smart-money consensus: for every active market with whale trades in the last 24h by wallets with Predge score > 70 — their YES/NO volume split, net flow (USD), distinct smart-wallet count, and a direction verdict: "yes"/"no" when one side holds ≥ 55% of smart volume, else "split". Sorted by smart volume, top-50.

Example response
{
  "window_hours": 24,
  "smart_score_min": 70,
  "scored_wallets_total": 412,
  "insufficient_data": false,
  "markets": [
    {
      "condition_id": "0x178a…4c39",
      "title": "Will the Fed cut rates in September?",
      "category": "economics",
      "market_yes_price": 0.62,
      "smart_wallets": 6,
      "smart_yes_usd": 184000,
      "smart_no_usd": 41000,
      "net_flow_usd": 143000,
      "direction": "yes"
    }
  ]
}
Payment

How x402 settles a request

  1. Ask. GET any paid route with no payment → 402 with the PAYMENT-REQUIRED header: base64 JSON listing exact price (atomic USDC), asset contract, pay-to address and timeout. Free to call, includes an example response body.
  2. Sign. Your client signs an EIP-3009 transferWithAuthorization for that exact amount. No transaction is sent by you — the wallet needs zero ETH.
  3. Retry. Same request + PAYMENT-SIGNATURE header. The server verifies with the facilitator, runs the handler, settles on-chain, and only then answers.
  4. Receipt. 200 + PAYMENT-RESPONSE header: the settle receipt with the on-chain transaction hash — auditable on the block explorer.

Current network parameters

Protocolx402 v2, scheme exact
Networkeip155:8453 — Base mainnet
Asset (USDC)0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913
Pay to0x9084f5000e07c7133d6da5ee4f271ab6d1821144 · watch settlements
Facilitatorhttps://facilitator.payai.network
FundingUSDC on Base only — no ETH; the facilitator pays gas (EIP-3009)
Live on Base mainnet. Payment parameters are advertised in every 402 header and in GET / — x402 clients read them at request time, so integrations never go stale even if these docs lag. When docs and service disagree, the service wins.

Guarantees & limits

Errors cost nothing

Settlement happens only after a successful handler response. 4xx/5xx — including 404 for unknown wallets — are never charged.

Bounded spend

Each call's price is fixed in its 402 (maxTimeoutSeconds: 60). Full sweep of all 11 routes: $0.145.

Rate & cache

10 req/s per IP on /v1/*. Server cache: 60 s (whales, movers) to 5 min (aggregates) — re-buying sooner returns the same data.

Fresh enough, honestly

Paid data is delayed 15 min by design. Real-time stays with Predge Pro subscribers.

For agents & crawlers

Machine-readable surfaces