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 also carries prediction market endpoints under /v1/marketplace/surf/prediction-market/*, at $0.00825/call. This Predexon service is a dedicated prediction-only provider with 50 endpoints and deeper data — orderbooks, candlesticks, leaderboards and per-market holder analytics — at $0.00935/call. Surf is marginally cheaper per read; this service goes deeper. Both figures measured against live 402 quotes.

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
Every endpoint on this page	$0.00935 per call

One flat rate, regardless of venue or method. Measured against the live gateway: /polymarket/markets, /markets/search, /polymarket/leaderboard and /polymarket/wallet/positions/:wallet each answer 402 quoting 9350 uUSDC.

Read the 402, not this table

Send the request without payment and read accepts[].amount — it is in micro-USDC, so 9350 is $0.00935. That figure is authoritative; costs re-sync from upstream, so any number written into a page goes stale by construction.

All Endpoints (50)

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 (1 endpoint)

Endpoint	Description
GET /markets/search	Keyword search across venues (`?q=bitcoin`)

Five cross-venue endpoints were removed

/matching-markets, /matching-markets/pairs, /markets, /markets/listings and /outcomes/:predexon_id are no longer served — the gateway answers 404. They were listed here while upstream had already stopped serving them, which is worse than an omission: the paths resolved to a price by prefix inheritance, so a call to one was billed before the upstream 404 came back. Use /markets/search for cross-venue lookup.

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 — withdrawn

All three dFlow endpoints were removed

/dflow/trades, /dflow/wallet/positions/:wallet and /dflow/wallet/pnl/:wallet are no longer served; the gateway answers 404. For wallet-level positions use /polymarket/wallet/positions/:wallet, which is live.

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. Like every endpoint here, it costs $0.00935.

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 /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.00935)
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.00935)
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.00935, the same on every endpoint.
# Read accepts[].amount from a 402 for the authoritative figure.
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},
)

# Wallet PnL — Polymarket wallets are 0x EVM addresses
pnl = client.call("prediction", "/polymarket/wallet/pnl/0x56687bf4...",
                  method="GET")

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

print(markets, smart, pnl, 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.00935)
	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 keyword search
	found, _ := mc.Call(ctx, "prediction", "/markets/search?q=bitcoin", nil)
	fmt.Println("Search:", found)
}

Limitations

Read-only — cannot place orders or execute trades
No WebSocket — poll the endpoints; there is no streaming interface
Addresses are 0x EVM — Polymarket and the wallet-identity endpoints take EVM addresses. ENS is not resolved.
Cross-venue lookup is keyword-based — /markets/search matches on text; there is no identifier-to-identifier matching endpoint
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 (50) ​

Polymarket (29 endpoints) ​

Sports (4 endpoints) ​

Cross-Venue (1 endpoint) ​

Kalshi (3 endpoints) ​

Binance (2 endpoints) ​

dFlow — withdrawn ​

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 /polymarket/leaderboard ​

Errors ​

Code Examples ​

Limitations ​

Prediction Markets API

Authentication

Pricing

All Endpoints (50)

Polymarket (29 endpoints)

Sports (4 endpoints)

Cross-Venue (1 endpoint)

Kalshi (3 endpoints)

Binance (2 endpoints)

dFlow — withdrawn

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 /polymarket/leaderboard

Errors

Code Examples

Limitations