# x402Pulse

> Skill-ranked Polymarket trader data for AI agents. Pay per call in USDC with the x402 protocol. No API key or account.

## How to call
- Base URL: https://www.x402pulse.dev
- All endpoints are GET and return JSON: { data, cached }.
- Without payment, a paid endpoint returns 402 with a PAYMENT-REQUIRED header (base64 JSON: scheme, network, amount in USDC base units, asset, payTo).
- Sign the payment with an x402 client (e.g. @x402/fetch + @x402/evm), resend with a PAYMENT-SIGNATURE header, and receive 200 plus a PAYMENT-RESPONSE receipt.
- Network: Base mainnet (eip155:8453). Errors (4xx/5xx) are never charged.

## Endpoints
### GET /v1/whales ($0.02)
Recent large Polymarket trades, with 5- and 15-minute markets filtered out.
- param min: Minimum trade size in USD (default 1000)
- param limit: Number of trades, 1 to 50 (default 20)
- example: https://www.x402pulse.dev/v1/whales?min=1000&limit=20
- returns trades[] (list): Largest recent trades, biggest first.
- returns wallet, name (text): Trader's Polymarket wallet and display name (null if none).
- returns side, outcome, price (text, text, 0–1): BUY or SELL, which outcome, and the price paid (0.62 = 62¢).
- returns usd, shares (USD, number): Trade size in dollars and shares.
- returns market, slug, time, tx (text): Market question, its slug, trade time (ISO) and on-chain transaction.

### GET /v1/wallet ($0.05)
A wallet's track record: skill score, edge over the odds paid, win rate, return, specialty and largest open positions.
- param address: Polymarket wallet address (0x…)
- example: https://www.x402pulse.dev/v1/wallet?address=0x56687bf447db6ffa42ffe2204a05edaa20f55839
- returns address, name (text): The wallet and its display name (null if none).
- returns score (object): The scorecard. See score fields below.
- returns openPositions[] (list): Largest live positions: market, outcome, shares, avgPrice, currentPrice, valueUsd, unrealizedPnlUsd.

### GET /v1/top-traders ($0.05)
Top Polymarket traders re-ranked by skill (edge over the odds paid, return, consistency), not just total profit. Optionally within one category.
- param period: day, week, month or all (default month)
- param category: Optional: sports, politics, crypto, economy or other
- param limit: Number of traders, 1 to 25 (default 10)
- example: https://www.x402pulse.dev/v1/top-traders?period=month&limit=10
- returns traders[] (list): Traders ranked by skill. Each has the main score fields plus the ones below.
- returns profitRank (integer): Where they sat on Polymarket's profit leaderboard for the period.
- returns periodPnlUsd, periodVolumeUsd (USD): Profit and volume for the chosen period, from Polymarket.
- returns candidates (integer): How many leaderboard traders were scored to build the ranking.
- returns category (text or null): When set, scores use only each trader's bets in that category.

### GET /v1/smart-money ($0.20)
Which way skilled traders lean in a Polymarket market compared with its odds: the biggest holders, each scored for skill.
- param market: Market link, market slug or condition ID
- example: https://www.x402pulse.dev/v1/smart-money?market=https%3A%2F%2Fpolymarket.com%2Fevent%2Fexample-event%2Fexample-market
- returns question, slug, outcomes[] (text, list): The market, and each outcome with its current price (0.41 = 41% implied chance).
- returns lean (object or null): outcome, share of skill-weighted money, marketPrice, vsMarket (share − price) and stance: in line with, more confident than, or less confident than the market.
- returns summary (text): One-sentence answer, ready to show a user.
- returns sides[] (list): Per outcome: price, sharpHolders, skillWeightedUsd and holders[] (wallet, name, valueUsd, skill, label, edge, winRate, roi).

### GET /v1/skilled-whales ($0.05)
Recent large Polymarket trades by Solid or Sharp traders only, each tagged with the trader's skill score.
- param min: Minimum trade size in USD (default 1000)
- param limit: Number of trades, 1 to 50 (default 20)
- example: https://www.x402pulse.dev/v1/skilled-whales?min=1000&limit=20
- returns trades[] (list): Large recent trades by Solid or Sharp traders only, biggest first. Same trade fields as /v1/whales.
- returns skill, label, edge, roi, specialty (score): The trader's skill score and its main parts. See score fields below.
- returns tradersScored (integer): How many distinct traders were scored (up to 25 of the biggest).

### GET /v1/disagreements ($0.35)
Busy open Polymarket markets where skilled traders' money disagrees most with the market's odds, with a confidence rating.
- param category: Optional: sports, politics, crypto, economy or other
- param limit: Number of markets, 1 to 20 (default 5)
- example: https://www.x402pulse.dev/v1/disagreements?limit=5
- returns markets[] (list): Open yes/no markets, sorted by how far tempered skilled money is from the price, weighted by confidence.
- returns priceYes (0–1): The market's price for the first outcome (usually Yes).
- returns skilledYesShare (0–1): What skilled money implies for the first outcome, tempered toward the price so thin readings can't look extreme.
- returns rawSkilledYesShare (0–1): The untempered share of skill-weighted money on the first outcome.
- returns gap (−1 to 1): skilledYesShare − priceYes. Positive: skilled money more bullish on Yes than the market; negative: more bullish on No.
- returns confidence (text): high (5+ skilled holders, $150K+ skill-weighted), medium (3+, $50K+) or low.
- returns skilledHolders, skilledUsd (integer, USD): How many Solid+ holders and how much skill-weighted money the reading rests on.
- returns scannedAt, marketsScanned (time, integer): When the busiest open markets were last scanned (every 15 minutes) and how many.

## Score fields
- skill (0–100): Overall skill score from edge, return, history size and consistency.
- label (text): Sharp (70+), Solid (45+), Mixed (25+), Weak, or Too few bets (under 10 finished bets).
- edge (number): Win rate minus the win rate the prices paid implied. 0.08 = won 8 points more often than the odds said.
- winRate (0–1): Share of finished bets that made money.
- expectedWinRate (0–1): Average price paid, i.e. the win rate the odds implied.
- roi (number): Realized profit divided by money invested. 0.25 = +25%.
- bets (integer): Finished bets scored (latest 200, losses included).
- realizedPnlUsd (USD): Profit or loss across the scored bets.
- biggestWinShare (0–1): Share of all winnings from the single best bet. High means one lucky hit.
- shortTermShare (0–1): Share of bets on 5- and 15-minute crypto markets, which lowers the score.
- specialty (text): Category with the most profit: sports, politics, crypto, economy, other, or null.

## How the skill score works
- Uses a wallet's latest 200 finished bets, including unredeemed losses.
- edge = win rate − average price paid. Base score = 60% edge (−2 pts → 0, +10 pts → full) + 40% return (0% → 0, +30% → full).
- Multiplied by history size, consistency (one lucky bet halves it) and focus (5/15-minute coin-flip markets halve it). Capped at 35 if edge ≤ 0 or return ≤ 0.
- Smart money: skill-weighted dollars of Solid+ holders per outcome; lean compared with the outcome's price (±10 pts = in line).

## Errors
- 400 (free): Missing or invalid parameter. An ambiguous market link includes choices[] to pick from.
- 402 (free): Payment required: read the PAYMENT-REQUIRED header, pay, and retry.
- 404 (free): Wallet or market not found.
- 429 (free): Too many requests from you (60 per minute by default).
- 502 / 503 (free): Polymarket didn't respond or is busy. Retry after a short wait.

## Freshness
- Whales: refreshed every minute.
- Smart money: every 5 minutes.
- Wallet: every 10 minutes. A wallet's skill score: every 30 minutes.
- Top traders: every 15 minutes. Disagreements: rescanned in the background every 15 minutes. Skilled whales: every 3 minutes.
- Every response has cached: true or false, so you can tell whether it was just computed.

## Discovery
- https://www.x402pulse.dev/catalog and https://www.x402pulse.dev/.well-known/x402-listing: endpoints and prices as JSON.
- Human docs: https://www.x402pulse.dev/developers

## Usage notes
- Data and analytics from public Polymarket activity. Not financial or betting advice.
- Independent service, not affiliated with Polymarket or the x402 Foundation.