Prediction Markets API

Real-time prediction market data via Predexon. 58 endpoints across 11 groups: Polymarket (29), Sports (4), Cross-Venue (6), Kalshi (3), Binance (2), dFlow (3), Wallet Identity (3), UMA Oracle (2), Limitless (2), Opinion (2), Predict.Fun (2).

Base URL: https://api.jarvisclaw.ai/v1/marketplace/prediction

https://api.jarvisclaw.ai/v1/prediction/… is an equivalent alias — the same paths, the same billing.

Surf also has prediction data

The Crypto Data (Surf) API includes 17 prediction market endpoints under /v1/marketplace/surf/prediction-market/* at $0.0095/call. This Predexon service is a dedicated prediction-only provider with more endpoints (58 vs 17), deeper data (orderbooks, candlesticks, leaderboards, cross-venue matching), and lower pricing on most reads ($0.001 vs $0.0095).

Authentication

Both methods are supported — all requests settle via x402 on-chain:

Method	Header	Description
API Key	`Authorization: Bearer sk-...`	Platform signs x402 from your HD wallet automatically
Private Key (x402)	Automatic via SDK	Agent signs x402 directly from its own wallet

See Agent Payments (x402) for full details on how both methods work.

Pricing

Prices below are reference rates per call. Read price.amount in each response for the exact charge.

Endpoint	Price
Most GET endpoints (Polymarket, Kalshi, Binance, sports, Limitless, Opinion, Predict.Fun, UMA)	$0.001
`GET /dflow/wallet/`, `GET /polymarket/wallet/`, `GET /binance/*`, `GET /pairs`, `GET /arbitrage`, `GET /correlation`, `GET /compare`	$0.005
`GET /dflow/trades`, `GET /matching-markets`, `GET /markets/search`	$0.0095
`POST /polymarket/wallet/identities`	$0.0095
Any other POST	$0.005

Four endpoints were repriced upward

/dflow/trades, /matching-markets, /markets/search, and POST /polymarket/wallet/identities were previously listed at $0.001–$0.005. They now settle at $0.0095. Older docs and cached price tables may still show the low figure.

All Endpoints (58)

Paths below are relative to the base URL. Three need specific market data to be present before they return anything; those are marked.

Polymarket (29 endpoints)

Endpoint	Description
GET /polymarket/markets	List markets (`?sort=volume&limit=50`)
GET /polymarket/markets/keyset	Keyset-paginated market list (`?pagination_key=`)
GET /polymarket/events	List events (`?status=open&limit=20`)
GET /polymarket/events/keyset	Keyset-paginated event list
GET /polymarket/crypto-updown	Crypto up/down markets
GET /polymarket/market-price/:token_id	Current price for a token
GET /polymarket/candlesticks/:condition_id	OHLC candlesticks by condition
GET /polymarket/candlesticks/token/:token_id	OHLC candlesticks by token (needs trade history)
GET /polymarket/volume-chart/:condition_id	Volume over time (`?start_time=&end_time=`)
GET /polymarket/orderbooks	Order book snapshots (`?token_id=&start_time=&end_time=`)
GET /polymarket/trades	Trade list (`?condition_id=`)
GET /polymarket/activity	Wallet activity feed (`?wallet=`)
GET /polymarket/markets/:token_id/volume	Volume for one token
GET /polymarket/markets/:condition_id/open_interest	Open interest for one market
GET /polymarket/positions	Open positions
GET /polymarket/leaderboard	Top traders (`?limit=100&sort_by=total_pnl`)
GET /polymarket/leaderboard/market/:condition_id	Per-market leaderboard
GET /polymarket/cohorts/stats	Trader cohort statistics
GET /polymarket/market/:condition_id/top-holders	Largest holders in a market
GET /polymarket/market/:condition_id/smart-money	Smart-money positions (`?min_total_pnl=`)
GET /polymarket/markets/smart-activity	Cross-market smart-money activity
GET /polymarket/wallet/:wallet	Wallet summary
GET /polymarket/wallet/:wallet/markets	Markets a wallet trades
GET /polymarket/wallet/:wallet/similar	Wallets with similar behaviour
GET /polymarket/wallet/pnl/:wallet	Wallet PnL (`?granularity=day`)
GET /polymarket/wallet/positions/:wallet	Wallet open positions
GET /polymarket/wallet/volume-chart/:wallet	Wallet volume over time
GET /polymarket/wallets/profiles	Wallet profile list
GET /polymarket/wallets/filter	Filter wallets by criteria

smart-money requires at least one criteria param above its floor: min_realized_pnl ≥ 1000, min_total_pnl ≥ 1000, min_roi ≥ 0.15, min_trades ≥ 100, min_volume ≥ 10000.

Sports (4 endpoints)

Endpoint	Description
GET /sports/categories	Supported sports categories
GET /sports/markets	Sports markets (`?category=baseball`)
GET /sports/markets/:game_id	Markets for one game (e.g. `mlb-ari-wsh-2026-06-06`)
GET /sports/outcomes/:predexon_id	Outcomes for a Predexon ID (e.g. `px-jdtq5b6...`)

Cross-Venue (6 endpoints)

Endpoint	Description
GET /matching-markets	Match one market across venues (only if already in the matching set)
GET /matching-markets/pairs	All known cross-venue pairs
GET /markets/search	Keyword search across venues (`?q=bitcoin`)
GET /markets	Unified market list
GET /markets/listings	Unified listings
GET /outcomes/:predexon_id	Outcomes by Predexon ID

matching-markets accepts exactly one identifier: polymarket_condition_id, polymarket_market_slug, polymarket_market_id, kalshi_market_ticker, limitless_slug, predict_market_id, predict_condition_id, predict_token_id, opinion_market_id, opinion_condition_id, or opinion_token_id.

Kalshi (3 endpoints)

Endpoint	Description
GET /kalshi/markets	List Kalshi markets
GET /kalshi/trades	Trades (`?ticker=KXBTC`)
GET /kalshi/orderbooks	Order books (`?ticker=&start_time=&end_time=`)

Binance (2 endpoints)

Endpoint	Description
GET /binance/candles/:symbol	Candles (`?interval=1h&start_time=&end_time=`)
GET /binance/ticks/:symbol	Tick data (`?start_time=&end_time=`)

interval=1m covers at most a 7-day range; interval=1h allows longer windows.

dFlow (3 endpoints)

Endpoint	Description
GET /dflow/trades	Trades for a wallet (`?wallet=`)
GET /dflow/wallet/positions/:wallet	Wallet positions
GET /dflow/wallet/pnl/:wallet	Wallet PnL (`?granularity=day`)

dFlow uses Solana base58 addresses, not 0x EVM addresses.

Wallet Identity (3 endpoints)

Endpoint	Description
GET /polymarket/wallet/identity/:wallet	Resolve one wallet to a known identity
POST /polymarket/wallet/identities	Batch resolve — body `{"addresses":["0x…","0x…"]}`
GET /polymarket/wallet/:wallet/cluster	Wallets clustered with this one

UMA Oracle (2 endpoints)

Endpoint	Description
GET /polymarket/uma/markets	Markets resolved by the UMA optimistic oracle
GET /polymarket/uma/market/:condition_id	One UMA market (UMA-resolved markets only)

Limitless (2 endpoints)

Endpoint	Description
GET /limitless/markets	List Limitless markets
GET /limitless/orderbooks	Order books (`?market_slug=&start_time=&end_time=`)

Opinion (2 endpoints)

Endpoint	Description
GET /opinion/markets	List Opinion markets
GET /opinion/orderbooks	Order books (`?market_id=&start_time=&end_time=`)

Predict.Fun (2 endpoints)

Endpoint	Description
GET /predictfun/markets	List Predict.Fun markets
GET /predictfun/orderbooks	Order books (`?market_id=&start_time=&end_time=`)

Detailed Endpoint Reference

GET /polymarket/markets

List active Polymarket prediction markets with filtering and pagination.

Parameters

Parameter	Type	Required	Description
`limit`	integer	No	Results per page. Default: `20`, Max: `100`
`offset`	integer	No	Pagination offset. Default: `0`
`category`	string	No	Filter: `politics`, `crypto`, `sports`, `science`, `culture`, `business`, `tech`
`status`	string	No	Filter: `open`, `closed`. Default: `open`
`sort`	string	No	Sort by: `volume`, `liquidity`, `newest`, `ending_soon`. Default: `volume`

Response

json

{
  "markets": [
    {
      "id": "0x1234abcd...",
      "question": "Will AI pass the Turing test by 2027?",
      "yes_price": 0.72,
      "no_price": 0.28,
      "volume": 1250000,
      "liquidity": 340000,
      "end_date": "2027-12-31",
      "category": "tech",
      "created_at": "2025-06-01T10:00:00Z"
    }
  ],
  "total": 1432
}

GET /polymarket/wallet/:wallet

Get a wallet summary for a Polymarket address. Positions and PnL are also available separately at /polymarket/wallet/positions/:wallet and /polymarket/wallet/pnl/:wallet.

Parameters

Parameter	Type	Required	Description
`wallet`	string	Yes	Ethereum wallet address (0x-prefixed, path parameter)

Response

json

{
  "address": "0xAbC123def456...",
  "positions": [
    {
      "market_id": "0x1234abcd...",
      "question": "Will AI pass the Turing test by 2027?",
      "side": "yes",
      "shares": 500,
      "avg_price": 0.65,
      "current_price": 0.72,
      "unrealized_pnl": 35.00
    }
  ],
  "total_value": 2450.00,
  "realized_pnl": 180.50,
  "open_positions": 3
}

GET /kalshi/markets

List Kalshi prediction markets. Query params are passed through to Predexon unchanged; the call works with no params at all. /kalshi/trades and /kalshi/orderbooks require ?ticker= (e.g. KXBTC), and orderbooks additionally require start_time + end_time as Unix seconds.

Response

json

{
  "markets": [
    {
      "ticker": "KXUSRECESSION-26",
      "title": "US recession in 2026?",
      "yes_price": 0.28,
      "no_price": 0.72,
      "volume": 4200000,
      "close_time": "2026-12-31T23:59:00Z",
      "category": "economics"
    }
  ],
  "total": 847
}

GET /markets/search

Search for markets across all providers by keyword or topic.

Parameters

Parameter	Type	Required	Description
`q`	string	Yes	Search query string (e.g. `bitcoin`)

Other params are forwarded to Predexon as-is. This endpoint costs $0.0095, not $0.001.

Response

json

{
  "results": [
    {
      "provider": "polymarket",
      "id": "0x5678efgh...",
      "question": "Will Bitcoin exceed $200K by end of 2026?",
      "yes_price": 0.41,
      "volume": 3800000
    },
    {
      "provider": "kalshi",
      "ticker": "KXBTC-200K-26",
      "title": "Bitcoin above $200K before 2027?",
      "yes_price": 0.38,
      "volume": 1200000
    }
  ],
  "total": 14
}

GET /matching-markets

Given one venue's identifier, return the equivalent market on the other venues. Pass exactly one of: polymarket_condition_id, polymarket_market_slug, polymarket_market_id, kalshi_market_ticker, limitless_slug, predict_market_id, predict_condition_id, predict_token_id, opinion_market_id, opinion_condition_id, opinion_token_id.

Returns empty unless that market has already been ingested into the matching set. Use /matching-markets/pairs (no params) to list every known pair. Both cost $0.0095 per call for /matching-markets; /pairs is $0.001.

GET /polymarket/leaderboard

Top traders. Verified params: limit and sort_by (e.g. sort_by=total_pnl). Per-market rankings live at /polymarket/leaderboard/market/:condition_id.

Smart-money screening is a separate endpoint — /polymarket/market/:condition_id/smart-money — and needs at least one criteria param above its floor: min_realized_pnl ≥ 1000, min_total_pnl ≥ 1000, min_roi ≥ 0.15, min_trades ≥ 100, min_volume ≥ 10000. Calls with no criteria, or below a floor, return an error.

Errors

Gateway-level errors use a flat shape — a single error string, no nested code:

json

{ "error": "service 'prediction' is at capacity, please retry in a moment" }

HTTP	Meaning	Resolution
401	Missing or invalid API key / x402 signature	Check `Authorization`, or let the SDK re-sign
402	Settlement failed — wallet could not pay upstream	Top up the wallet, then retry
403	Insufficient balance, or payment rejected	Top up, or check your spend limits
404	Service or path not found upstream	Verify the path against the endpoint tables above
429	Too many concurrent requests	Back off and retry
502	Upstream provider failed	Retry; if persistent the provider is down
503	Service temporarily unavailable	Retry later

Errors returned by Predexon itself (unknown market ID, malformed address, closed market) are passed through unchanged, so their shape is the upstream provider's, not JarvisClaw's.

Code Examples

bash

# List Polymarket markets, highest volume first
curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/polymarket/markets?sort=volume&limit=50" \
  -H "Authorization: Bearer sk-your-api-key"

# Wallet summary, then PnL
curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/polymarket/wallet/0xAbC123def456" \
  -H "Authorization: Bearer sk-your-api-key"

curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/polymarket/wallet/pnl/0xAbC123def456?granularity=day" \
  -H "Authorization: Bearer sk-your-api-key"

# List Kalshi markets
curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/kalshi/markets" \
  -H "Authorization: Bearer sk-your-api-key"

# Search markets across all venues ($0.0095)
curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/markets/search?q=bitcoin" \
  -H "Authorization: Bearer sk-your-api-key"

# Polymarket leaderboard by total PnL
curl "https://api.jarvisclaw.ai/v1/marketplace/prediction/polymarket/leaderboard?limit=100&sort_by=total_pnl" \
  -H "Authorization: Bearer sk-your-api-key"

python

from jarvisclaw import MarketplaceClient

client = MarketplaceClient(api_key="sk-your-api-key")

# List Polymarket markets, highest volume first
markets = client.call("prediction", "/polymarket/markets", method="GET", params={
    "sort": "volume",
    "limit": 50,
})

# Wallet summary and PnL
wallet = client.call("prediction", "/polymarket/wallet/0xAbC123def456", method="GET")
pnl = client.call("prediction", "/polymarket/wallet/pnl/0xAbC123def456", method="GET", params={
    "granularity": "day",
})

# List Kalshi markets
kalshi = client.call("prediction", "/kalshi/markets", method="GET")

# Cross-venue search ($0.0095)
results = client.call("prediction", "/markets/search", method="GET", params={"q": "bitcoin"})

# Response shapes come straight from Predexon and vary per endpoint — inspect
# before indexing into them.
print(markets, wallet, pnl, kalshi, results)

python

from jarvisclaw import MarketplaceClient

# Base chain (EVM) — pays per-call via USDC
client = MarketplaceClient(private_key="0x<evm-private-key>")

# Or Solana
# client = MarketplaceClient(private_key="<solana-bs58-keypair>")

# Each call settles its own x402 payment: $0.001 for most GETs,
# $0.0095 for /markets/search, /matching-markets and /dflow/trades.
markets = client.call("prediction", "/polymarket/markets", method="GET", params={
    "sort": "volume",
    "limit": 50,
})

# Smart money in one market — needs a criteria param above its floor
smart = client.call(
    "prediction",
    "/polymarket/market/0xdd22472e.../smart-money",
    method="GET",
    params={"min_total_pnl": 100000},
)

# dFlow uses Solana base58 wallets, not 0x addresses
dflow = client.call("prediction", "/dflow/wallet/pnl/4jaZ5McRcVCiRmz2Z8xd2BDCjWaAys2WD4K5Q1YHbcxP",
                    method="GET", params={"granularity": "day"})

# Batch wallet identity resolution (POST, $0.0095)
ids = client.call("prediction", "/polymarket/wallet/identities", method="POST", json={
    "addresses": ["0x56687bf4...", "0x1f2dd6d4..."],
})

print(markets, smart, dflow, ids)

package main

import (
	"context"
	"fmt"
	jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
	ctx := context.Background()
	mc, _ := jc.NewMarketplaceClient(jc.WithAPIKey("sk-your-api-key"))

	// List Polymarket markets, highest volume first
	markets, _ := mc.Call(ctx, "prediction", "/polymarket/markets", jc.WithParams(map[string]any{
		"sort":  "volume",
		"limit": 50,
	}))
	fmt.Println("Polymarket markets:", markets)

	// Wallet summary
	wallet, _ := mc.Call(ctx, "prediction", "/polymarket/wallet/0xAbC123def456", nil)
	fmt.Println("Wallet:", wallet)

	// List Kalshi markets
	kalshi, _ := mc.Call(ctx, "prediction", "/kalshi/markets", nil)
	fmt.Println("Kalshi markets:", kalshi)

	// Cross-venue search ($0.0095)
	results, _ := mc.Call(ctx, "prediction", "/markets/search", jc.WithParams(map[string]any{
		"q": "bitcoin",
	}))
	fmt.Println("Search results:", results)
}

package main

import (
	"context"
	"fmt"
	jc "github.com/api-jarvisclaw/go-sdk/v2"
)

func main() {
	ctx := context.Background()
	// x402 Agent wallet — pays per-call via USDC on Base
	mc, _ := jc.NewMarketplaceClient(jc.WithPrivateKey("0x<evm-private-key>"))

	// List Polymarket markets, highest volume first
	markets, _ := mc.Call(ctx, "prediction", "/polymarket/markets", jc.WithParams(map[string]any{
		"sort":  "volume",
		"limit": 50,
	}))
	fmt.Println("Polymarket markets:", markets)

	// Wallet positions
	wallet, _ := mc.Call(ctx, "prediction", "/polymarket/wallet/positions/0xAbC123def456", nil)
	fmt.Println("Positions:", wallet)

	// Cross-venue pairs (no params) — $0.001
	pairs, _ := mc.Call(ctx, "prediction", "/matching-markets/pairs", nil)
	fmt.Println("Pairs:", pairs)
}

Limitations

Read-only — cannot place orders or execute trades
No WebSocket — poll the endpoints; there is no streaming interface
Address format varies by venue — Polymarket and the wallet-identity endpoints take 0x EVM addresses; dFlow takes Solana base58. ENS is not resolved.
Cross-venue matching best-effort — /matching-markets returns nothing unless the market is already in the matching set
Price format differs by venue — Polymarket: decimals (0.00–1.00), Kalshi: cents (0–100)
Concurrency cap — heavy parallel use can return a 429; back off and retry
Time params are Unix seconds — start_time / end_time, not ISO strings. interval=1m on Binance candles covers at most 7 days.
Response shapes are upstream's — the gateway passes Predexon's JSON through unchanged, so fields differ per endpoint

Prediction Markets API ​

Authentication ​

Pricing ​

All Endpoints (58) ​

Polymarket (29 endpoints) ​

Sports (4 endpoints) ​

Cross-Venue (6 endpoints) ​

Kalshi (3 endpoints) ​

Binance (2 endpoints) ​

dFlow (3 endpoints) ​

Wallet Identity (3 endpoints) ​

UMA Oracle (2 endpoints) ​

Limitless (2 endpoints) ​

Opinion (2 endpoints) ​

Predict.Fun (2 endpoints) ​

Detailed Endpoint Reference ​

GET /polymarket/markets ​

Parameters ​

Response ​

GET /polymarket/wallet/:wallet ​

Parameters ​

Response ​

GET /kalshi/markets ​

Response ​

GET /markets/search ​

Parameters ​

Response ​

GET /matching-markets ​

GET /polymarket/leaderboard ​

Errors ​

Code Examples ​

Limitations ​

Prediction Markets API

Authentication

Pricing

All Endpoints (58)

Polymarket (29 endpoints)

Sports (4 endpoints)

Cross-Venue (6 endpoints)

Kalshi (3 endpoints)

Binance (2 endpoints)

dFlow (3 endpoints)

Wallet Identity (3 endpoints)

UMA Oracle (2 endpoints)

Limitless (2 endpoints)

Opinion (2 endpoints)

Predict.Fun (2 endpoints)

Detailed Endpoint Reference

GET /polymarket/markets

Parameters

Response

GET /polymarket/wallet/:wallet

Parameters

Response

GET /kalshi/markets

Response

GET /markets/search

Parameters

Response

GET /matching-markets

GET /polymarket/leaderboard

Errors

Code Examples

Limitations