Prediction Markets

---
name: prediction-markets
description: "Use when the user asks about event probabilities, prediction market odds, what people are betting on, Polymarket/Kalshi prices, sports markets — or about the things you CANNOT get from a public API: historical price/volume/orderbook time series, smart-money positioning, whale leaderboards, wallet P&L, wallet identity and on-chain clustering, and canonical IDs matching the same question across venues. 55 endpoints over Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, sports, and the UMA oracle. Pay-per-call in USDC via x402 — no Predexon account, no API key."
triggers:
  - "polymarket"
  - "kalshi"
  - "limitless"
  - "predict.fun"
  - "predexon"
  - "prediction market"
  - "event probability"
  - "betting odds"
  - "implied probability"
  - "what are people betting on"
  - "election odds"
  - "crypto market odds"
  - "binance futures"
  - "yes/no market"
  - "sports markets"
  - "smart money"
  - "smart wallet"
  - "whale"
  - "top traders"
  - "top holders"
  - "who is winning"
  - "best traders"
  - "copy trade"
  - "leaderboard"
  - "wallet pnl"
  - "wallet profit"
  - "trader performance"
  - "wallet identity"
  - "wallet cluster"
  - "price history"
  - "candles"
  - "candlestick"
  - "ohlcv"
  - "orderbook"
  - "order book history"
  - "open interest"
  - "volume history"
  - "trade history"
  - "cross-venue markets"
  - "arbitrage"
  - "uma oracle"
---

# Prediction Markets (Predexon)

55 endpoints across Polymarket, Kalshi, Limitless, Opinion, Predict.Fun, Binance Futures, sports, and the UMA oracle — one x402 gateway, no Predexon account or API key.

**What is worth paying for.** Current market lists are free from public APIs. These are not, and cannot be backfilled after the fact:

- **History** — candlesticks, orderbook snapshots, volume charts, open interest, trade history. Built from continuous ingestion; nobody can reconstruct it retroactively.
- **Smart money** — leaderboards, cohort stats, top holders, which wallets are positioned where, and which markets high-performing wallets just entered.
- **Wallet intelligence** — profiles, P&L time series, identity metadata, and on-chain clustering (find the other wallets behind one address).
- **Cross-venue canonical IDs** — one question, matched across five venues. The basis for arbitrage and consensus.

## How to Call from MCP

One tool, three params. Method auto-routes: POST when `body` is set, GET otherwise.

```ts
blockrun_markets({ path: "polymarket/events", params: { limit: "10" } })

blockrun_markets({ path: "polymarket/candlesticks/0xCONDITION_ID", params: { interval: "1440" } })

blockrun_markets({ path: "polymarket/wallet/identities", body: {
  addresses: ["0xabc...", "0xdef..."]
}})
```

Paths are relative — no `/api/v1/pm/` prefix. Use `agent_id` to bill a child agent's budget.

Paid calls can run in parallel **on Base**: each EIP-3009 authorization carries
its own random nonce, so concurrent calls from one wallet cannot collide.
The Solana payload has no nonce field — distinctness comes from the SDK
(`@blockrun/llm` >= 3.8.4), so keep that floor if you fan out on Solana.

Current parameter contracts that prevent paid 4xx responses:

- Discover with `markets/search` (its search term is `q`), then resolve the
  selected market with `polymarket/markets/keyset` + `condition_id`.
- On `polymarket/markets{,/keyset}` the free-text filter is `search`, **not**
  `q`. Use `status:"open"` rather than Gamma's `active`/`closed`, and `sort`
  rather than `order`/`ascending`. `end_after`/`end_before` are supported
  (Unix seconds).
- Candlestick `interval` is integer minutes (`1440`, not `1h`) and is
  **optional** — the server has a default. Which intervals a market can serve
  varies: `1440` may work where `60` returns a paid 400. Optional
  `start_time`/`end_time` are Unix seconds.
- `polymarket/orderbooks` requires `token_id`, `start_time`, and `end_time`; the
  times are Unix milliseconds.
- Smart-money needs a smart-wallet **criterion**: `min_trades`, `min_volume`,
  `min_roi`, `min_realized_pnl`, `min_total_pnl`, `min_win_rate`, or
  `min_profit_factor`. `window` only scopes the time range and is **not**
  sufficient alone (verified: window-only returns a paid 400). Use
  `{ window: "30d", min_trades: "100" }`; narrower cohorts are fine.
- `markets/listings` is retired upstream (410 Gone) — the MCP blocks it before payment. The rest of the
  canonical layer went with it on 2026-08-04: bare `markets`, `outcomes/{predexon_id}`, `matching-markets`
  and `matching-markets/pairs` all return **404 Unknown Predexon endpoint before payment** (verified live
  2026-09-08). Only `markets/search` survived. No live `/v1/pm` route accepts a `league` param.

## Two Pricing Tiers

| Tier | Price | What |
|---|---|---|
| **All endpoints** | $0.0085 on Base ($0.0075 + the $0.001 network fee; Solana quotes $0.0075) | Market data, events, history, candles, orderbooks, trades, leaderboard, UMA, wallet analytics, smart money, identity + clustering, cross-venue search, Binance (`sports/*` is degraded upstream — see below; the gateway releases the payment on the upstream 500) |

Pass-through pricing, 0% BlockRun margin — settles straight to Predexon's Base treasury.

## Quick Decision Table — "User asks about X"

| User wants… | path | Tier |
|---|---|---|
| **Same question across venues / search every venue at once** | `markets/search` (`q`) | 2 |
| Active Polymarket events | `polymarket/events` | 1 |
| Polymarket markets | `polymarket/markets` | 1 |
| Large result sets (stable paging) | `polymarket/markets/keyset` | 1 |
| Crypto up/down markets | `polymarket/crypto-updown` | 1 |
| Current/historical price of a token | `polymarket/market-price/{token_id}` | 1 |
| **Price history (OHLCV)** | `polymarket/candlesticks/{condition_id}` | 1 |
| **OHLCV for one outcome** | `polymarket/candlesticks/token/{token_id}` | 1 |
| **Volume over time (YES/NO split)** | `polymarket/volume-chart/{condition_id}` | 1 |
| **Historical orderbook snapshots** | `polymarket/orderbooks` | 1 |
| **Historical trades** | `polymarket/trades` | 1 |
| Merges / splits / redeems for a user | `polymarket/activity` | 1 |
| Cumulative volume for a market | `polymarket/markets/{token_id}/volume` | 1 |
| **Open interest history** | `polymarket/markets/{condition_id}/open_interest` | 1 |
| Positions (filterable) | `polymarket/positions` | 1 |
| **Global smart-wallet leaderboard** | `polymarket/leaderboard` | 1 |
| **Leaderboard for one market** | `polymarket/leaderboard/market/{condition_id}` | 1 |
| **Cohort performance by trading style** | `polymarket/cohorts/stats` | 1 |
| **Top holders of a market** | `polymarket/market/{condition_id}/top-holders` | 1 |
| **Smart money on a market** | `polymarket/market/{condition_id}/smart-money` | 2 |
| **Markets smart wallets just entered** | `polymarket/markets/smart-activity` | 2 |
| **Full smart-wallet profile** | `polymarket/wallet/{wallet}` | 2 |
| Per-market breakdown for a wallet | `polymarket/wallet/{wallet}/markets` | 2 |
| **Wallets with similar portfolios** | `polymarket/wallet/{wallet}/similar` | 2 |
| **Wallet P&L + realized series** | `polymarket/wallet/pnl/{wallet}` | 2 |
| Wallet open/historical positions | `polymarket/wallet/positions/{wallet}` | 2 |
| Wallet volume by BUY/SELL side | `polymarket/wallet/volume-chart/{wallet}` | 2 |
| Batch wallet profiles | `polymarket/wallets/profiles` | 2 |
| Filter wallets by markets traded | `polymarket/wallets/filter` | 2 |
| **Wallet identity (ENS/Twitter/etc)** | `polymarket/wallet/identity/{wallet}` | 2 |
| **Bulk identity (≤200, POST)** | `polymarket/wallet/identities` | 2 |
| **On-chain cluster for a wallet** | `polymarket/wallet/{address}/cluster` | 2 |
| UMA oracle questions by state | `polymarket/uma/markets` | 1 |
| UMA status + timeline for a market | `polymarket/uma/market/{condition_id}` | 1 |
| Kalshi markets | `kalshi/markets` | 1 |
| Kalshi trades / orderbooks | `kalshi/trades`, `kalshi/orderbooks` | 1 |
| ⚠ Sports categories — **degraded upstream since 2026-08-04, do not call** | `sports/categories` | 1 |
| ⚠ Sports markets by league — degraded, use `markets/search` + `q=` or `polymarket/events` + `search=` | `sports/markets` | 1 |
| ⚠ One game, all venue outcomes — degraded | `sports/markets/{game_id}` | 1 |
| ⚠ Equivalent sports outcomes — degraded | `sports/outcomes/{predexon_id}` | 1 |
| Limitless / Opinion / Predict.Fun markets | `limitless/markets`, `opinion/markets`, `predictfun/markets` | 1 |
| Their historical orderbook snapshots | `limitless/orderbooks`, `opinion/orderbooks`, `predictfun/orderbooks` | 1 |
| Binance candles / ticks | `binance/candles/{symbol}`, `binance/ticks/{symbol}` | 2 |

## Worked Examples

### 1. "What are people betting on right now?"

```ts
blockrun_markets({ path: "polymarket/events", params: { limit: "10" } })
```

### 2. "What's the market saying about the 2028 election?"

Search every venue in one call — each hit carries its venue and IDs — then pull the chosen Polymarket market by `condition_id`.

```ts
blockrun_markets({ path: "markets/search", params: { q: "2028 presidential election", status: "open" } })
blockrun_markets({ path: "polymarket/markets/keyset", params: { condition_id: "0xCONDITION_ID" } })   // full market record
```

### 3. "Show me this market's price history" (impossible from a free API)

```ts
blockrun_markets({ path: "polymarket/candlesticks/0xCONDITION_ID", params: {
  interval: "1440", start_time: "<UNIX_SECONDS>", end_time: "<UNIX_SECONDS>"
} })
blockrun_markets({ path: "polymarket/volume-chart/0xCONDITION_ID" })
blockrun_markets({ path: "polymarket/markets/0xCONDITION_ID/open_interest" })
blockrun_markets({ path: "polymarket/orderbooks", params: {
  token_id: "<TOKEN_ID>", start_time: "<UNIX_MILLISECONDS>", end_time: "<UNIX_MILLISECONDS>"
} })
```

### 4. "Who's smart money betting on in this market?" ← compound

Positioning → then profile the wallets behind it.

```ts
// 1. Which high-performing wallets are in this market, and on which side
blockrun_markets({ path: "polymarket/market/0xCONDITION_ID/smart-money", params: {
  window: "30d", min_trades: "100"
} })

// 2. Profile the top wallet it returns — win rate, P&L, style
blockrun_markets({ path: "polymarket/wallet/0xWHALE" })

// 3. What else are they in right now?
blockrun_markets({ path: "polymarket/wallet/positions/0xWHALE" })
```

### 5. "This whale is up 400% — who are they really?" ← compound

Identity plus the on-chain cluster: one trader often runs many wallets.

```ts
blockrun_markets({ path: "polymarket/wallet/identity/0xWHALE" })        // ENS, socials, portfolio
blockrun_markets({ path: "polymarket/wallet/0xWHALE/cluster" })         // linked wallets + confidence
blockrun_markets({ path: "polymarket/wallet/pnl/0xWHALE" })             // realized P&L series
blockrun_markets({ path: "polymarket/wallet/0xWHALE/similar" })         // who trades like them
```

### 6. "Find me something to copy-trade" ← compound

```ts
blockrun_markets({ path: "polymarket/leaderboard", params: { limit: "20" } })   // best wallets
blockrun_markets({ path: "polymarket/markets/smart-activity" })                 // where they just moved
blockrun_markets({ path: "polymarket/cohorts/stats" })                          // which style is working
```

Then trade it with `blockrun_polymarket` (see `skills/polymarket-trading/SKILL.md`). **Real money — always dry-run first.**

### 7. "Is the same bet cheaper on another venue?" ← arbitrage

`matching-markets` and `matching-markets/pairs` were removed upstream (404 before payment). One search returns
the same question from every venue; compare the prices in the result.

```ts
blockrun_markets({ path: "markets/search", params: { q: "Fed cuts rates in December", status: "open" } })
// → Polymarket, Kalshi, Limitless, Opinion, Predict.Fun hits side by side; the spread is the arbitrage
```

### 8. "Who's ahead in tonight's NBA games?"

```ts
blockrun_markets({ path: "markets/search",    params: { q: "NBA", status: "open" } })      // every venue's NBA markets
blockrun_markets({ path: "polymarket/events", params: { search: "NBA", status: "open" } })  // Polymarket game events
blockrun_markets({ path: "kalshi/markets",    params: { search: "NBA" } })                  // Kalshi's
```

Do **not** route this to `sports/*`. All four `sports/*` paths have returned a Predexon 500 on every call since
2026-08-04 (re-verified 2026-09-08). The gateway still routes them but withdrew them from discovery, and it
releases the payment on that upstream 500 — the tool says "nothing was charged" when the gateway's own
"payment NOT charged" confirmation is in the response, and otherwise points at `blockrun_wallet action:"report"`.
Do not use `markets` with `league=` either: that route was removed on 2026-08-04 and 404s before payment, and no
live `/v1/pm` route accepts `league`. The sports routes come back here the day Predexon repairs them.

### 9. "Is this market about to resolve?"

```ts
blockrun_markets({ path: "polymarket/uma/markets", params: { state: "proposed" } })
blockrun_markets({ path: "polymarket/uma/market/0xCONDITION_ID" })   // dispute timeline
```

## Method Routing — When to Use `body`

Almost everything is GET → use `params`. Only bulk identity takes a body:

```ts
blockrun_markets({ path: "polymarket/wallet/identities", body: { addresses: ["0x1", "0x2"] } })
```

## Paging Large Result Sets

Prefer keyset over offset — stable across writes, faster on big tables.

```ts
const p1 = blockrun_markets({ path: "polymarket/markets/keyset", params: { limit: "100" } })
// then pass the returned pagination.next_key back in:
blockrun_markets({ path: "polymarket/markets/keyset", params: { limit: "100", pagination_key: "<next_key>" } })
```

`polymarket/events/keyset` works the same way.

## Notes on Response Shape

Predexon returns raw upstream responses; shape varies by venue.

- **Polymarket** — usually `{ data: [...] }` or `{ events: [...] }`
- **Kalshi** — usually `{ markets: [...] }` with `ticker`, `yes_bid`, `no_bid`. Tickers look like `KXBTC-25MAR14` (series + expiry).
- **Canonical v2** — `{ markets: [...] }` with `predexon_id` + `venue_listings`
- Print the raw response when exploring a path you have not used before.

Prices are probabilities 0–1. `0.62` means the market implies 62%.

## Python SDK (for non-MCP use)

Inside the MCP, use `blockrun_markets` above. For standalone scripts:

```python
from blockrun_llm import setup_agent_wallet   # setup_agent_solana_wallet() on Solana
client = setup_agent_wallet()

client.pm("polymarket/candlesticks/0xCONDITION_ID", interval="1440")
client.pm_query("polymarket/wallet/identities", {"addresses": ["0xabc"]})
```

Requires `pip install blockrun-llm` and a funded USDC wallet (`client.get_balance()`).