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.
{
"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.
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{
"access_token": "eyJhbGciOiJSUzI1NiIs…",
"token_type": "Bearer",
"expires_in": 900
}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.
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"{
"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.
{
"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.
{
"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.
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.
curl https://api.predxy.com/v1/markets/stats \
-H "Authorization: Bearer $TOKEN"Paging and search
Lists page by offset: skip rows from the start, take rows at a time, and a total to say how
many there are. skip stops at a million, and sooner on the market listing.
| Endpoint | take default |
take most |
|---|---|---|
/v1/index |
100 | 200 |
/v1/markets |
50 | 200 |
/v1/calendar |
50 | 200 |
/v1/calendar/days |
a day for each day of the window, up to 366 | |
/v1/markets/{id}/comments |
50 | 200 |
/v1/index/search |
20 | 50 |
The change feed pages by cursor instead; see the change feed.
The index
sort orders it: weight (the default: the money at risk on it over the last day), score,
movers, trending, new, resolvingSoon, hyped and disagreement, the questions whose venues
are at least five points apart. Narrow it with category, country (ISO 3166 alpha-2) and status
(open, the default, closed, settled or any). top=true is a window of up to the first
thousand questions of an ordering, paged with skip and take and counted in total.
score is the site's Top 100, and its arithmetic is published: 45% 24-hour volume, 25% open
interest, 15% the number of venues carrying the question and 15% the size of its 24-hour move. Each
is the question's rank among the open questions with $25K traded in 24 hours or $10K of open
interest, from 0 for the least to 1 for the most, so no one figure's scale outweighs another's; a
question no venue reports open interest for ranks with the least. The list keeps one question an
event (its best-scored outcome, counting the rest in foldedOutcomes). A category's questions past
its first thirty come after every category's first thirty, and no category holds more than three of
the first ten.
Questions on the score and trending orderings, and on any ordering with top=true, carry
image where a licensed photograph that shows the question was found. A model looks at the
archive's photographs and chooses one, and alt describes the one chosen. Show its credit,
linked to sourceUrl.
Markets
/v1/markets takes venue and status as comma-separated lists — any of a list, and all of the
lists — q for words in the question, and sort (recent, question, venue, volume,
liquidity, resolves, status) with dir (asc or desc).
A listing reaches its first 10,000 markets: skip past that is refused with a 400, and total is
counted no further — when more match, it reads 10,000 and totalIsCapped is true. Half a million
markets are open at once; to read past ten thousand, narrow by venue, status or words, or keep a
copy current from the change feed.
Search
/v1/index/search?q= matches the wording any venue gives a question, from two characters, in any
case. Questions still trading come first, then settled ones, each by weight.
The calendar
/v1/calendar lists questions settling in a window, soonest first: window is today (the
default), tomorrow, thisWeek, nextWeek or past — or give from and to. Days are yours:
pass tzOffsetMinutes (−840 to 840) and weeks start on Monday.
/v1/calendar/days counts a calendar instead of listing it: give from and to as dates
(YYYY-MM-DD, both included, at most 366 days apart) and each day with anything settling comes
back with questions (the length of that day's /v1/calendar list, with the same filters),
events (how many events those are, a question that is no outcome of an event counting as one) and
top, the biggest of them, one an event. top is 3 by default and up to 10, and must be 0 for a
window longer than 62 days. category and includeSettled filter as they do on the list. A day with
nothing settling is left out.
curl "https://api.predxy.com/v1/index?sort=movers&category=politics&take=20" \
-H "Authorization: Bearer $TOKEN"curl "https://api.predxy.com/v1/calendar?window=thisWeek&tzOffsetMinutes=180" \
-H "Authorization: Bearer $TOKEN"curl "https://api.predxy.com/v1/index?sort=score&top=true&take=50" \
-H "Authorization: Bearer $TOKEN"curl "https://api.predxy.com/v1/calendar/days?from=2026-10-26&to=2026-12-06&tzOffsetMinutes=120" \
-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.
{
"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 markedcarried, and the stretches with nothing at all are listed ingaps./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.
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. |
{
"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.
HTTP/2 200
content-type: application/json; charset=utf-8
ratelimit-limit: 500
ratelimit-remaining: 498
ratelimit-reset: 37HTTP/2 429
retry-after: 37AI 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.
{
"mcpServers": {
"predxy": { "url": "https://mcp.predxy.com/mcp" }
}
}claude mcp add --transport http predxy https://mcp.predxy.com/mcpTools
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.