PxPredxyDocs

Predxy API documentation

Introduction

Predxy reads prediction markets on every venue it tracks — Polymarket, Kalshi, Limitless and the rest — and puts the same question from all of them in one place. The API serves what the site shows: each question with one price across its venues, every venue's own market beneath it, and the venues themselves.

Everything is read-only, served as JSON over HTTPS, and needs a key.

Host Production Staging
API https://api.predxy.com https://test-api.predxy.com
Tokens https://id.predxy.com https://test-id.predxy.com

What you can read:

  • The index — every open question, ranked, with its price, its movement, its volume and the venues that carry it. Ordered by weight, by the Top 100's published score, by movement, novelty, disagreement between venues and more.
  • Markets — each venue's own market, its outcomes and their prices, and its history.
  • The change feed — what moved since you last asked, so a copy of the index stays current without reading it all again.
  • The calendar — questions that settle in a window of days, and each day of a month or a year counted, with its biggest questions.
  • Venues — which are live, how fresh each one is, and how they rank.
  • Sentiment — the Predxy Fear & Greed index.
A question, trimmed
{
  "rank": 1,
  "clusterId": "0d6c7c1e-3a0f-4f5e-9a52-8f1f1b3e2c41",
  "slug": "fed-decision-in-october-hold",
  "question": "Will the Fed hold rates in October?",
  "outcome": "Yes",
  "price": 0.725,
  "basis": "volumeWeighted",
  "change": 0.031,
  "volume24h": 1840521.5,
  "venueCount": 4,
  "pricedVenueCount": 4,
  "venues": ["Polymarket", "Kalshi", "Gemini", "Limitless"],
  "resolvesAt": "2026-10-28T18:00:00Z",
  "settled": false
}

Quickstart

Three steps from nothing to a price.

1. Get a key

Sign in on predxy.com/developers, confirm your email, and ask for access: the name of your application, what it is for and a sentence on how you will use the data. The free plan is approved by hand; a paid plan applies as soon as its payment settles. Create a key on the Keys tab of your API usage page: it has a client id and a secret, and the secret is shown once.

2. Exchange it for a token

Post the client id and secret to the token endpoint with the scopes you need. The token lasts fifteen minutes; ask for a new one when it runs out.

3. Call the API

Send the token as a bearer token. The first page of the index is the questions with the most money at risk on them over the last day.

Call the API from your server. It sends no CORS headers, and a secret in a browser is a secret anyone can read.

Token
curl -X POST https://id.predxy.com/connect/token \
  -d grant_type=client_credentials \
  -d client_id=predxy-api-… \
  -d client_secret=… \
  -d scope=predxy.api.read
Response
{
  "access_token": "eyJhbGciOiJSUzI1NiIs…",
  "token_type": "Bearer",
  "expires_in": 900
}
The index
curl https://api.predxy.com/v1/index?take=10 \
  -H "Authorization: Bearer $TOKEN"

Authentication

The API takes OAuth 2.0 client credentials. Each key is a client: an id of the form predxy-api-… and a secret. An account holds up to two keys, so one can be rotated while the other carries traffic; both share the account's plan and its allowance.

Scopes

Ask for the scopes you need in the token request, separated by spaces. A token carries exactly those, and an endpoint that needs one the token does not have answers 403.

Scope Reads
predxy.api.read Everything, except the two below. Every token needs it.
predxy.api.detail A venue's own detail for one market: /v1/markets/{id}/detail.
predxy.api.history Recorded price history: /v1/markets/{id}/history and /v1/index/{slug}/history.

Your plan says which scopes you may ask for. Asking for one outside it is refused with invalid_scope.

Tokens

A token is valid for fifteen minutes (expires_in: 900) and there is no refresh token: ask for a new one before the old one runs out. The token endpoint takes up to 120 requests a minute from one address, so cache the token rather than asking for one per call.

Rotating and revoking

Rotate or revoke a key on the Keys tab of your API usage page. New secret keeps the client id and replaces the secret; Revoke retires the key. Either way, tokens issued with the old secret stop working within thirty seconds, and the other key is untouched.

Two scopes
curl -X POST https://id.predxy.com/connect/token \
  -d grant_type=client_credentials \
  -d client_id=$CLIENT_ID \
  -d client_secret=$CLIENT_SECRET \
  -d "scope=predxy.api.read predxy.api.history"
A scope outside your plan
{
  "error": "invalid_scope",
  "error_description": "The requested scope is not included in the approved plan."
}

Questions and markets

Two things carry a price in the API, and the difference matters.

A market is one venue's market: Kalshi's contract on the October Fed decision, say, with its own outcomes and its own prices. Markets are read at /v1/markets, by an id that is a GUID.

A question is what Predxy makes of the markets that ask the same thing, on every venue that asks it. It has a clusterId and a slug, one price across its venues, and the ids of its markets in marketIds. Questions are read at /v1/index, by slug.

Event and outcome

Many venues list a question as one outcome of an event: "Fed decision in October?" and "Hike 25bps". Where they do, a question carries both as eventTitle and outcomeTitle, to be read as Event › Outcome. A list of movers folds an event's outcomes into one row, and foldedOutcomes says how many it stands for.

Kinds of market

Most markets are binary: each outcome's price is its probability. A scalar market settles to a value in a range — Anthropic's market cap when it lists, US unemployment in September — and its price is a position in that range, not a probability. A scalar market carries its range (lower, upper, prefix, suffix), its value is lower + price × (upper − lower), and it never enters the index.

Settled questions

The index lists questions that are still trading. A question leaves the lists when it settles, when it will settle within 48 hours, or when its price reaches 99 or 1; asked for by its slug, by search or through the calendar, it still answers, with settled: true.

Pascal, 1 October 2026, trimmed
{
  "venue": "Pascal",
  "question": "Anthropic IPO market cap: [$1T - $1.5T]",
  "kind": "Scalar",
  "range": { "lower": 1, "upper": 1.5, "prefix": "$", "suffix": "T" },
  "outcomes": [
    { "label": "Long", "price": 0.8745 }
  ]
}

A price of 0.8745 between $1T and $1.5T is a market cap of $1.44T: 1 + 0.8745 × (1.5 − 1).

Prices

Every price is a decimal from 0 to 1. For a binary market it is the probability of the outcome the row names: 0.725 is 72.5%. A change or a spread is in the same units, so 0.05 is five points.

One side for every venue

A question's price is the price of one side of it, the same side on every venue. A venue that lists only the other side of a two-sided contest — Under for Over, the other team — contributes its price turned round, 1 − p. A venue whose market cannot be placed on that side is left out of the price and still counted among the venues and in the volume, which is why pricedVenueCount can be less than venueCount.

How venues are combined

basis says how a question's price was made:

Basis Meaning
volumeWeighted Each venue's price weighted by what traded on it.
mean The venues' prices averaged, where volume cannot weigh them.
singleVenue One venue carries the question.

priceLow and priceHigh are the venues' extremes, and spread the distance between them: how much the venues disagree.

Change

change is the movement over the last day. A null change means there is not yet a day of history to compare with — never that nothing moved.

How fresh

Every response carries asOf. The index is a roll-up refreshed about once a minute, so its rows can be a minute behind the venues; a market's own detail carries the fetchedAt of its venue's last read. A venue that has not been read for fifteen minutes is carried but not priced.

Two venues on one side, trimmed
{
  "question": "Will the Fed hold rates in October?",
  "price": 0.725,
  "basis": "volumeWeighted",
  "priceLow": 0.71,
  "priceHigh": 0.74,
  "spread": 0.03,
  "change": 0.031,
  "venueCount": 4,
  "pricedVenueCount": 4
}

Venues

/v1/venues lists every venue Predxy reads, with its status and when it was last read. A venue is stale when it is more than two minutes behind, or has never been read; its markets keep their last prices, and after fifteen minutes it stops counting toward a question's price.

Venues are named by key in every response and filter: Polymarket, Kalshi, Limitless, Opinion, Gemini and the rest. /v1/markets?venue=Kalshi,Polymarket takes several, in any case.

/v1/venues/ranking is the leaderboard the site shows. Each venue is scored on what it reports — volume, liquidity, open markets, active traders — on what Predxy observes of it — uptime, how far behind its data runs, how sound that data is — and on what comparing it with the others shows: how far its prices sit from the consensus, and how much it carries that nobody else does.

/v1/venues/history is each venue over time, from what Predxy recorded on every sweep: marketCap, volume24h, openMarkets, events — open markets with each multi-outcome event counted once, the count that compares a venue listing a market per outcome with one listing a market per question — and liquidity. Name venues with venues=Kalshi,Polymarket, or leave it out for all of them; metrics= narrows the same way. window (default 30d, or all) and interval (default 1d) read as they do for prices. Each point is the last value recorded in its bucket, so a day's volume24h is that day's volume. A bucket the venue reported nothing in has no point, and a metric it does not publish has no points and a null recordedSince — never zeros. A market cap point carries coverage, the share of the venue's open markets its open interest counts.

A venue is listed here once Predxy reads it. Some venues allow their prices to be shown only with their permission, and are switched on when it is given.

Kalshi and Polymarket, by volume
curl "https://api.predxy.com/v1/markets?venue=Kalshi,Polymarket&sort=volume&take=20" \
  -H "Authorization: Bearer $TOKEN"

Market cap and volume

Market cap

The site calls it market cap; the API calls it what it is, open interest: the collateral behind contracts still outstanding on open markets — the money at stake right now. It is a stock, not a flow, so it adds up across questions and venues.

Venues publish it differently. Where a venue reports it per event rather than per market, it is counted once per event, not once per outcome. Where a venue does not publish it, its figure is null: no data, never zero. /v1/markets/stats gives the total and each venue's figure, and says which venues the total covers.

Volume

Volume is what traded: volume24h over the last day and volumeTotal over the market's life. It is a market's own figure. Some venues publish volume only for a whole event — every outcome of a golf tournament together — and their markets carry no volume of their own; the venue's total in /v1/markets/stats counts each such event once.

Holders

holderCount adds up the accounts venues report holding a market, which is not the number of people: one person can hold on several venues. holderReportingMarkets out of holderTotalMarkets says how much of the question the figure covers, and null means no venue reports it.

Totals, overall and per venue
curl https://api.predxy.com/v1/markets/stats \
  -H "Authorization: Bearer $TOKEN"

The change feed

/v1/changes keeps a copy of the index current without reading all of it again. It lists questions in the order they last changed, each once, as it stands now: a question that changed twice appears once, where it last changed.

Start without a cursor and the feed lists every question once — that is your copy. Each response ends with a cursor; pass it back to read what changed since. While hasMore is true, ask again at once; when it is false you are up to date, and a minute is a good wait before asking again.

Each change has a kind:

Kind Meaning
created A question appeared.
updated Something about it changed; question is the whole of it now.
removed It is gone; question is null. Two questions merged read as one removed and the other updated.

A change is anything about the question itself: its wording, filing or countries, a price moving by a hundredth of a point, its total volume, its venues, its dates, whether it trades or has settled. The rolling 24-hour figures — change, volume24h — are not changes; read the index for those.

Removals are kept for ninety days. A cursor older than that answers 410 Gone: start again without one and rebuild the copy. Treat the cursor as opaque.

A page of changes, trimmed
{
  "asOf": "2026-10-02T09:41:00Z",
  "cursor": "c2VxOjE4NDQ2NzQ0",
  "hasMore": false,
  "changes": [
    {
      "seq": 18446744,
      "kind": "updated",
      "clusterId": "0d6c7c1e-3a0f-4f5e-9a52-8f1f1b3e2c41",
      "slug": "fed-decision-in-october-hold",
      "question": { "price": 0.725, "settled": false }
    },
    {
      "seq": 18446745,
      "kind": "removed",
      "clusterId": "6a1e9b0c-77d2-4c1e-8b0e-2f3c5d9a1b77",
      "slug": "will-it-rain-in-london-on-october-1",
      "question": null
    }
  ]
}

History

Three endpoints read recorded history, and all need the predxy.api.history scope.

  • /v1/markets/{id}/history — one market's outcomes over time. Points the venue did not report are carried forward and marked carried, and the stretches with nothing at all are listed in gaps.
  • /v1/index/{slug}/history — a question over time: the index line, the mean of its venues, and each venue's own series beside it.
  • /v1/venues/history — venues over time: market cap, 24h volume, open markets, open events and liquidity. See Venues.

window is how far back (default 7d), interval the spacing of points (default 1h), both as a number and a unit: m, h, d or w — 15m, 24h, 2w. A market also takes window=all. A series holds at most a thousand points; when the window and interval would make more, the interval doubles until they fit, and the response says which interval it used.

Prices older than ninety days are kept as one close a day, so a long window reads at a day's resolution however fine the interval asked for.

A month, daily
curl "https://api.predxy.com/v1/index/fed-decision-in-october-hold/history?window=30d&interval=1d" \
  -H "Authorization: Bearer $TOKEN"

Errors

The API answers with the usual statuses. An error it explains comes as application/problem+json, its detail saying what to change.

Status Meaning
400 A parameter is out of range or not one the endpoint takes: an unknown sort or category, a bad cursor, skip past a million.
401 No token, or one that is expired, malformed or issued to a key since rotated or revoked.
403 The token is valid and lacks the scope this endpoint needs.
404 Nothing has that id or slug. A market id is a GUID; anything else is a 404.
410 A change-feed cursor older than ninety days. Start again without one.
429 The plan's allowance for this minute is spent. Wait for Retry-After.
503 Predxy could not confirm your key just now. Retry shortly.
400 Bad Request
{
  "type": "https://tools.ietf.org/html/rfc9110#section-15.5.1",
  "title": "Bad Request",
  "status": 400,
  "detail": "Unknown sort 'popular'. Use weight, score, movers, trending, new, resolvingSoon, hyped or disagreement."
}

Limits

Each plan allows a number of requests a minute, counted per account over the calendar minute in UTC and shared by both of its keys. There is no daily or monthly quota. Your plan's allowance is on your API usage page, with thirty days of what your keys have used.

Every response says where you stand:

Header Meaning
RateLimit-Limit Requests allowed this minute.
RateLimit-Remaining Requests left this minute.
RateLimit-Reset Seconds until the next minute begins.

Past the allowance the API answers 429 with Retry-After, in seconds. A refused request still counts, so wait rather than retry at once.

Caching

Responses may be cached for five seconds (Cache-Control: private, max-age=5), and the API keeps its own copies for longer: the index, the change feed, the calendar and Fear & Greed for thirty seconds, the stats for fifteen, the ranking and a market's detail for a minute. Asking more often than that reads the same answer again, and spends your allowance on it.

Versions

Paths carry the version, /v1. Fields are added to responses as the data grows, so read the ones you need and ignore the rest.

Headers
HTTP/2 200
content-type: application/json; charset=utf-8
ratelimit-limit: 500
ratelimit-remaining: 498
ratelimit-reset: 37
Spent
HTTP/2 429
retry-after: 37

AI assistants (MCP)

Predxy runs a Model Context Protocol server, so an assistant such as Claude, ChatGPT, Cursor or VS Code can read the same index the API serves, with no key and no code. It is free, read-only and anonymous.

Production Staging
MCP server https://mcp.predxy.com/mcp https://test-mcp.predxy.com/mcp

The transport is Streamable HTTP, stateless. There is no sign-in: a request needs no header.

Adding it

  • Claude (web, desktop, mobile): Settings, Connectors, Add custom connector, and paste the address.
  • Claude Code: claude mcp add --transport http predxy https://mcp.predxy.com/mcp.
  • Cursor: .cursor/mcp.json, as in the example.
  • VS Code: .vscode/mcp.json, with "type": "http".
  • Anything else that speaks MCP over HTTP: the address alone.
Cursor
{
  "mcpServers": {
    "predxy": { "url": "https://mcp.predxy.com/mcp" }
  }
}
Claude Code
claude mcp add --transport http predxy https://mcp.predxy.com/mcp

Tools

Every tool only reads, and is annotated so.

Tool Reads
search_questions Questions by words, with price and 24-hour change.
get_question One question: combined price, each venue's price, volume, the event's other outcomes.
compare_venues Each venue's market for one question, with its wording and resolution rules.
get_price_history A question's price over 1d, 7d, 30d, 90d or all, at most 60 points.
list_movers The biggest moves of the last 24 hours. Sport and unfiled questions are left out unless asked for.
list_top_questions The Top 100, trending or new.
list_venue_disagreements Where the venues' prices are furthest apart.
list_resolving_soon What settles today, tomorrow, this week or next week, largest first. Sport and unfiled questions are left out unless asked for.
compare_venue_stats The venues, ranked, with volume, open interest and where each is open.
get_event An event page's questions, such as an election.

A question is named by its slug, which every list returns, or by its predxy.com/q/… address. Each tool answers in Markdown for the reader and as structured content for the client, and says what time its prices are from. Each question in an answer links to its page on predxy.com.

There are three resources: predxy://guide/methodology, predxy://venues and predxy://categories. There are also three prompts: market_brief, compare_across_venues and weekly_movers.

Limits

A list returns at most 25 rows and a history at most 60 points. Calls are limited per minute and per address. A call over the limit is answered with a tool error that says when to try again, never with an HTTP error. The server is for answering questions, not for copying the index. A copy kept current is what the API and its change feed are for.

What it keeps

For each call, the server counts the tool, the kind of client and the outcome. Like every Predxy service, it writes each request's address to the security log, and that address is what the limits are applied to. It does not store the arguments or the words searched for. It holds no account and needs none.