DATA & API
Prediction-market data documentation
Review response shapes, field definitions, authentication boundaries and source limits for Predict Here's research data interfaces.
Choose a starting point
On this page
Public terminal sample API
This unauthenticated endpoint returns the same deterministic synthetic universe and history used by the public terminal. It is separate from the account-based Developer Sandbox and authenticated organization APIs. It never returns customer or venue observations.
curl -sS https://predicthere.com/api/terminal-sample?scenarioStep=0- mode
- Always SAMPLE. A cookie or query parameter cannot select organization data.
- scenarioTime
- Fixed scenario clock, October 9, 2026 at 16:00 UTC; not the time of a live quote.
- snapshotId
- Identifies the selected deterministic scenario snapshot.
- data
- The synthetic event universe, or contract history when contractId is supplied. Micro-unit quantities and prices use exact decimal integer strings.
- scenarioStep
- Optional integer 0, 1, 2 or 3. Omit it for the initial scenario.
- contractId
- Optional existing sample contract identity, for example sample:contract:02:1, to read its synthetic history.
Unsupported parameters, mode and orgId are rejected. Unknown contract identities return 404; invalid scenario steps return 400. Request limits can return 429 with Retry-After. Sample API access provides no access to private data routes.
Sandbox quickstart
Create a Developer Sandbox key in Account, then use it as a Bearer token with the synthetic sandbox index. Browser sessions and production keys are refused on this route.
curl -sS https://predicthere.com/api/intel/v1/sandbox \
-H "Authorization: Bearer phik_test_your_key"The index returns only synthetic fixture resources, including discoverable event identifiers and endpoint paths. It never grants real venue data; use the data dictionary and changelog to interpret the response contract and changes.
{
"data": {
"environment": "sandbox",
"endpoints": [
{
"method": "GET",
"path": "/api/intel/v1/sandbox",
"description": "This index."
}
],
"events": [
{
"id": "5eed0000-0000-4000-8000-000000000001",
"slug": "sample-northwind-meridian-accord-ratification",
"title": "Will the Northwind Federation ratify the Meridian Accord before 1 January 2027?"
}
]
},
"sourceStatus": "STALE"
}Common responses
- 401: the key is missing, inactive, the wrong environment, or lacks sandbox:read. The response deliberately does not reveal which.
- 404: an event identifier or slug is not in the synthetic fixture set.
- 404: the Developer Sandbox is unavailable while the Monitor platform is disabled.
Delivery modes
Monitor and authenticated organization session routes are implemented. The public sample terminal has a separate unauthenticated synthetic API and browser-local research exports. Those sample exports are not bulk historical market data, which remains planned.
- Workstation (Monitor)
- AvailablePredict Here Monitor — the event workstation, in the browser.
- Authenticated application APIs
- AvailableCanonical Monitor routes use a signed-in organization session and applicable rights. Developer Sandbox keys access synthetic sandbox routes only. Production API-key transport is not available for these canonical routes.
- Historical exports
- PlannedBulk history for research and backtesting. Designed and specified; not available yet.
Response envelope
Canonical Monitor and production API responses use the provenance envelope documented here, and the Developer Sandbox follows its documented response contract. The dedicated Polymarket US workspace endpoint has its own DTO; retained US records can also appear through shared canonical Monitor routes when all source, rights and rollout gates allow.
| Field | Type | Meaning |
|---|---|---|
| data | T — the requested DTO | The requested figure or record itself. |
| asOf | string (ISO 8601) | When this response was assembled. |
| sourceStatus | enum — LIVE | DEGRADED | DELAYED | STALE | The overall quality state behind this response — LIVE, DEGRADED, DELAYED, or STALE. |
| sources | ProvenanceSource[] — source, sourceAsOf, entitlementMode, qualityFlags | Each contributing venue, with its own as-of time and entitlement mode. |
| mappingVersion | string | null | Which semantic-verification mapping snapshot, if any, a PH Composite figure was computed under. null when the reference plane has not cut a version yet. |
| methodologyVersion | string | null | Which signal and consensus methodology produced the figure — the value stamped in the sample above. Not the execution and liquidity algorithm's identifier, which travels separately as algorithmVersion on a price-at-size ladder. |
{
"data": {
"id": "6f3a9d20-8b1e-4c77-9a2f-1d4e6b9c0a11",
"slug": "fed-rate-decision-january-2027",
"title": "Fed rate decision — January 2027",
"status": "active",
"primary": {
"probabilityMicro": "635000",
"source": "POLYMARKET",
"asOf": "2026-09-02T14:03:11.000Z",
"quality": "DELAYED"
}
},
"asOf": "2026-09-02T14:03:12.418Z",
"sourceStatus": "DELAYED",
"sources": [
{
"source": "POLYMARKET",
"sourceAsOf": "2026-09-02T14:03:11.000Z",
"entitlementMode": "BYO_CUSTOMER_LICENSE",
"qualityFlags": 0
}
],
"mappingVersion": "2026-08-28T12:00Z#1",
"methodologyVersion": "intel-methodology-r1@1+intel-consensus-v0.1.1"
}Data dictionary
Field-level reference for the DTOs behind the response envelope's data — the identifiers, prices, and execution figures an event, quote, or capacity response is actually built from. A field appears here only if it exists in a shipped response type today; every bigint field (anything ending in Micro, plus a few others) is serialized as a decimal integer string at the API boundary, never a raw number, so JSON never has to represent a value Postgres stores as an exact integer.
Field-level reference for the DTOs the envelope's data carries
Identity
| Field | Type | Description | Example |
|---|---|---|---|
| id · canonicalEventId | string (uuid) | The canonical event's identifier. A top-level event response names it id; every response that references the same event by relation — movers, signals, distributions, capacity — names it canonicalEventId instead. Same value, two field names. Always present, never a venue-native id. | "6f3a9d20-8b1e-4c77-9a2f-1d4e6b9c0a11" |
| slug | string | Stable, human-readable identifier for an event, used to build canonical URLs. Assigned by the reference plane, not copied from any single venue. | "fed-rate-decision-january-2027" |
| contractId | string | One venue's own contract identifier as surfaced through the reference plane — the mapped reference-plane outcome id once a contract has been reviewed into the ontology, or the venue's raw external outcome/token id before that review happens. Two venues covering the same real-world event carry two different contractId values. | "0x51a3f0...9c" |
| source · venue | enum — "POLYMARKET" | "KALSHI" | "POLYMARKET_US" | The source identity for a retained contract, quote or book observation: POLYMARKET, POLYMARKET_US or KALSHI. Shared canonical routes can return entitled retained US/Kalshi records with this source ID and provenance. The dedicated US on-demand workspace uses a separate DTO. Production US/Kalshi collection is currently disabled. | "POLYMARKET" |
| status | enum (two vocabularies share this name) | An event-level response's status is the canonical event lifecycle — active, closed, resolved, or archived. A contract-level response's status instead describes that one venue contract — active or inactive. Both are always present, never null. | "active" |
| rulesHash | string | null | Hash of a venue contract's rules text, captured whenever the collector observes it. There is no separate incrementing rule-version number on the wire — a new rulesHash value is what signals that a contract's rules changed. null when no rules document has been observed for that contract yet. | "a1c9e4de..." |
Quality and provenance
| Field | Type | Description | Example |
|---|---|---|---|
| quality | enum — LIVE | DEGRADED | DELAYED | STALE | INVALID | NOT_ENTITLED | The freshness/validity state behind one quote, book, or series point. DELAYED is the baseline for every polling-collector quote today — nothing is ever labeled live or real-time. A non-LIVE quality isn't decoration: treat it as "this figure may be wrong, absent, or delayed." | "DELAYED" |
| sourceTime | ISO 8601 string | null | The venue's own timestamp for an observation. null when the venue doesn't supply one — never backfilled from receivedTime. | "2026-08-29T14:03:11.000Z" |
| receivedTime | ISO 8601 string | When this server observed the quote or book. Always present, unlike sourceTime. | "2026-08-29T14:03:12.418Z" |
| entitlementMode | enum — NOT_PERMITTED | PUBLIC_NONCOMMERCIAL | PUBLIC_ALLOWED | PH_LICENSED | BYO_CUSTOMER_LICENSE | INTERNAL_RESEARCH_ONLY | The data-licensing mode governing one source's contribution to a response. NOT_PERMITTED is the default for a newly created organization — access is granted per source explicitly, never assumed. | "BYO_CUSTOMER_LICENSE" |
| mappingVersion | string | null | Which semantic-verification mapping snapshot, if any, a cross-venue figure was computed under. Append-only — a new version is cut whenever a relationship reaches or leaves VERIFIED — so re-running a historical figure against its own mappingVersion reproduces the same result even after later mapping changes. null when the reference plane hasn't cut a version yet. | "2026-08-28T12:00Z#1" |
Pricing
| Field | Type | Description | Example |
|---|---|---|---|
| probabilityMicro | integer string (wire) — bigint internally; micro-probability, 1,000,000 = 100% | Market-implied probability from a single source — the primary displayed number for an event, or a mover's own probability. Every Micro-suffixed field in this data plane follows the same convention: computed and persisted as an exact integer, never a floating-point number. | "635000" (63.5%) |
| bestBidMicro | integer string (wire) — bigint | null; micro-probability | Best bid price on a contract's book. null means no bid was observed — never 0, which would misrepresent an empty book as a certain no-bid price. | "620000" |
| bestAskMicro | integer string (wire) — bigint | null; micro-probability | Best ask price on a contract's book. Same null-vs-zero rule as bestBidMicro. | "640000" |
| midMicro | integer string (wire) — bigint | null; micro-probability | Midpoint of bestBidMicro and bestAskMicro. null whenever either side of the book is missing — never computed from one side alone. | "630000" |
| spreadMicro | integer string (wire) — bigint | null; micro-probability points | bestAskMicro minus bestBidMicro. null under the same missing-side condition as midMicro. | "20000" (2.0pp) |
Semantics
| Field | Type | Description | Example |
|---|---|---|---|
| relationships[].status | enum — SUGGESTED | REVIEW_REQUIRED | VERIFIED | REJECTED | RETIRED | Review-workflow state of one cross-venue or same-event relationship. Only a VERIFIED relationship backs a PH Composite figure or a MECE-verified distribution; anything unreviewed or rejected contributes nothing to either. This is a distinct vocabulary from the four-state semantic-equivalence display (VERIFIED/PARTIAL/NOT_EQUIVALENT/UNREVIEWED, described under Semantic verification on the methodology page) — SUGGESTED and REVIEW_REQUIRED both display as UNREVIEWED or PARTIAL depending on stage, and REJECTED/RETIRED both display as NOT_EQUIVALENT. | "VERIFIED" |
| relationships[].type | enum — 7 recognized schema values. The 4 currently implemented analytic relationship types are EXACT_COMPLEMENT, MUTUALLY_EXCLUSIVE, EXHAUSTIVE_SET and CROSS_VENUE_EQUIVALENT. NESTED_SUBSET, CONDITIONAL and CORRELATED_ONLY remain schema vocabulary without current analytic credit. | What kind of relationship a row asserts between two or more outcomes — for example a same-market YES/NO complement pair, or two venues' contracts verified equivalent. An event can carry more than one relationship row at once; this field describes one row, not the event as a whole. | "EXACT_COMPLEMENT" |
Execution
| Field | Type | Description | Example |
|---|---|---|---|
| direction | enum — BUY_YES | SELL_YES | Which side of the visible book an execution quote was walked against. BUY_YES consumes asks and SELL_YES consumes bids, so the same size answers a different question in each direction and the two are never interchangeable. Every price, slippage and fill field below is stated for this direction only. | "SELL_YES" |
| requestedNotionalMicro | integer string (wire) — bigint; micro-USD, 1,000,000 = $1 | The notional size an execution quote was computed for. Always one of the standard ladder sizes — $10,000, $50,000, $100,000, $250,000, $500,000, $1,000,000 — never an arbitrary caller-supplied amount. | "10000000000" ($10,000) |
| fillable | boolean | Whether the visible book could fill requestedNotionalMicro in full. Check this first — filledNotionalMicro and the price fields below are still the honest partial detail when this is false, never a fabricated zero standing in for "unavailable." | false |
| filledNotionalMicro | integer string (wire) — bigint; micro-USD | How much of requestedNotionalMicro the visible book actually covers. Equal to requestedNotionalMicro when fillable is true; a smaller honest partial otherwise. | "7400000000" |
| vwapPriceMicro | integer string (wire) — bigint | null; micro-probability | Volume-weighted average fill price across every book level the walk consumed. Rounded conservatively for the caller — up for a buy, down for a sell — never in the direction that would flatter the displayed fill. null when nothing filled. | "641200" |
| worstPriceMicro | integer string (wire) — bigint | null; micro-probability | Price of the worst (last-touched) level the walk consumed — copied verbatim from that level, no rounding. null when nothing filled. | "655000" |
| slippageMicro | integer string (wire) — bigint | null; signed micro-probability points | vwapPriceMicro versus the contract's own reference price, signed so positive always means worse for the caller than the reference price. null whenever either input is missing — no fill, or no usable reference price for that book. | "3200" |
| algorithmVersion | string | Versioned identifier for the execution/capacity math that produced a quote ladder — independent of the envelope's own methodologyVersion, which covers signal/consensus scoring instead. Bumped whenever the walk's math, rounding rule, or band definition changes. | "intel-execution-r1@1" |
Execution & capacity sample
One capacity response for one contract. The real quotes array interleaves BUY_YES and SELL_YES at each ladder size; the excerpt below shows the BUY_YES side of the six-size ladder. Note the last two sizes: fillable is false and filledNotionalMicro is the honest partial, never a fabricated zero.
{
"canonicalEventId": "6f3a9d20-8b1e-4c77-9a2f-1d4e6b9c0a11",
"algorithmVersion": "intel-execution-r1@1",
"ladderNotionalsMicro": [
"10000000000",
"50000000000",
"100000000000",
"250000000000",
"500000000000",
"1000000000000"
],
"contracts": [
{
"source": "POLYMARKET",
"contractId": "0x51a3f0...9c",
"referencePriceMicro": "630000",
"bookAsOf": "2026-09-02T14:03:11.000Z",
"quality": "DELAYED",
"quotes": [
{
"direction": "BUY_YES",
"requestedNotionalMicro": "10000000000",
"fillable": true,
"filledNotionalMicro": "10000000000",
"vwapPriceMicro": "631400",
"worstPriceMicro": "632000",
"slippageMicro": "1400",
"levelsConsumed": 2
},
{
"direction": "BUY_YES",
"requestedNotionalMicro": "50000000000",
"fillable": true,
"filledNotionalMicro": "50000000000",
"vwapPriceMicro": "633200",
"worstPriceMicro": "635000",
"slippageMicro": "3200",
"levelsConsumed": 5
},
{
"direction": "BUY_YES",
"requestedNotionalMicro": "100000000000",
"fillable": true,
"filledNotionalMicro": "100000000000",
"vwapPriceMicro": "635800",
"worstPriceMicro": "639000",
"slippageMicro": "5800",
"levelsConsumed": 9
},
{
"direction": "BUY_YES",
"requestedNotionalMicro": "250000000000",
"fillable": true,
"filledNotionalMicro": "250000000000",
"vwapPriceMicro": "641500",
"worstPriceMicro": "648000",
"slippageMicro": "11500",
"levelsConsumed": 18
},
{
"direction": "BUY_YES",
"requestedNotionalMicro": "500000000000",
"fillable": false,
"filledNotionalMicro": "412350000000",
"vwapPriceMicro": "646900",
"worstPriceMicro": "659000",
"slippageMicro": "16900",
"levelsConsumed": 31
},
{
"direction": "BUY_YES",
"requestedNotionalMicro": "1000000000000",
"fillable": false,
"filledNotionalMicro": "412350000000",
"vwapPriceMicro": "646900",
"worstPriceMicro": "659000",
"slippageMicro": "16900",
"levelsConsumed": 31
}
],
"capacity": {
"within1ppMicro": "68000000000",
"within2ppMicro": "154000000000",
"within5ppMicro": "389000000000"
}
}
]
}Resources
The synthetic sandbox index above publishes its routes and request shapes for the sandbox response contract. Canonical Monitor, retained source catalog and event-consensus routes require a signed-in organization session and current source rights; a production API key or Developer Sandbox key does not authenticate them. Polymarket US also has a separate authenticated-session workspace endpoint and DTO, described below. US/Kalshi production collection is currently disabled.
- Canonical events
- Venue contracts
- Quotes and books
- Relationships
- Execution and capacity
- Signals
- Alerts
- Watchlists
- Source health
- Retained source catalog (Polymarket US and Kalshi)
- Organization-scoped event consensus
Retained source catalog and event consensus
These read-only routes use the shared reference plane. The catalog is cursor-paginated by source and returns retained metadata with externalContractId, externalEventId, contentHash, capturedAt (local capture time), sourceAsOf (verified source time, or null) and effectiveAt. Metadata is limited by current organization rights. The event consensus route returns eligible or ineligible results with the reviewed relationshipId, mappingVersionId, proposition, outcomeKey, evaluatedAt, per-source observations and persistence ID.
GET /api/intel/v1/sources/catalog?source=POLYMARKET_US&limit=50
GET /api/intel/v1/sources/catalog?source=KALSHI&cursor={nextCursor}&limit=50
GET /api/intel/v1/events/{canonicalEventId}/consensusIn the consensus computation, eligible results include valueMicro, dispersionMicro, confidence and sources; ineligible results include reason and the excluded sources. Source records carry source, venueOutcomeId, status, optional reason, probabilityMicro and weight. Wire integers are decimal strings. Current consensus inputs use the shared maximum quote age of 10 minutes. A historical dispersion lookback does not extend current-input eligibility. Values depend on current source flags, organization rights, complete retained terms and reviewed mappings. These routes are not available through Developer Sandbox or production API-key authentication.
Auth, limits, versioning
A Developer Sandbox key is self-service and returns synthetic data. Canonical Monitor, source catalog, event consensus and the dedicated Polymarket US workspace are authenticated session APIs. A Developer Sandbox key or production API key does not authenticate these routes; production API-key transport is not currently implemented for this data plane.
Every request passes one per-organization entitlement check before any venue data is assembled. A source your organization is not entitled to is refused outright — never silently returned as an empty or zero value.
Shared canonical responses and the dedicated Polymarket US workspace have their respective documented DTOs and provenance fields. Breaking changes to canonical methodology are announced on the methodology changelog. We publish no production-API rate-limit numbers: limits are agreed with each organization rather than advertised.
Current availability
These tables show the maintained published release profile, not a live query of deployment flags, source licenses or your organization's rights. Runtime requests check current flags and rights independently; production activation and organization access can change without a documentation release.
Product capability
What exists and how finished it is, alongside what each plan includes. None of these rows is a venue question.
Workstation (Monitor)
AvailableLimitedIncludedThe per-event workstation. Limited on Explore means a curated, capped universe and a single ladder rung; the full universe and ladder otherwise.
Authenticated application APIs
AvailableNot includedIncludedCanonical Monitor routes require a signed-in organization session and applicable rights. Developer Sandbox keys access synthetic sandbox routes only. Production API-key transport is not available for these canonical routes.
Developer Sandbox
AvailableIncludedIncludedSynthetic example data on the exact response contract the live API uses. Self-serve at every tier — create a key from your account settings once you are signed in. Nothing it returns reflects any real market.
Portfolio & risk
Private betaNot includedIncludedPositions mapped into the canonical event graph, with exposure, stress and shadow initial margin computed against the same figures the intelligence layer publishes. Reached through the risk workspace rather than primary navigation.
Alerts
AvailableNot includedIncludedRule-based delivery of the eight signal types. Not included on Explore, since a standing alert rule carries real ongoing cost.
Historical exports
Planned——Planned. Not available at any tier.
| Capability | Status | Explore | Evaluation · Institutional | What it means |
|---|---|---|---|---|
| Workstation (Monitor) | Available | Limited | Included | The per-event workstation. Limited on Explore means a curated, capped universe and a single ladder rung; the full universe and ladder otherwise. |
| Authenticated application APIs | Available | Not included | Included | Canonical Monitor routes require a signed-in organization session and applicable rights. Developer Sandbox keys access synthetic sandbox routes only. Production API-key transport is not available for these canonical routes. |
| Developer Sandbox | Available | Included | Included | Synthetic example data on the exact response contract the live API uses. Self-serve at every tier — create a key from your account settings once you are signed in. Nothing it returns reflects any real market. |
| Portfolio & risk | Private beta | Not included | Included | Positions mapped into the canonical event graph, with exposure, stress and shadow initial margin computed against the same figures the intelligence layer publishes. Reached through the risk workspace rather than primary navigation. |
| Alerts | Available | Not included | Included | Rule-based delivery of the eight signal types. Not included on Explore, since a standing alert rule carries real ongoing cost. |
| Historical exports | Planned | — | — | Planned. Not available at any tier. |
Source and venue availability
This table separates implemented support, current production activation and additional organization/source rights. Polymarket US also has a dedicated on-demand read-only workspace. US and Kalshi production collection are currently disabled; customer access is not granted by implementation or a product plan.
| Source / venue | Implemented support | Production activation | Additional access requirements | What it means |
|---|---|---|---|---|
| Polymarket | Shared retained pipeline implemented | Enabled in current production configuration | Current organization rights are checked independently at delivery. | International Polymarket is collected into canonical Monitor records. Canonical figures sourced from it name the source; delivery to your organization is subject to its entitlement. |
| Polymarket US | Shared pipeline and on-demand workspace implemented | Disabled in current production configuration | Global source license, organization rights and current human-reviewed fixed-payout admission are required for US prices. | Shared retained collection and the dedicated on-demand workspace are implemented. Production collection is currently disabled. US prices require separate global source rights, organization rights and a current human-reviewed fixed-$1/$0 payout admission. |
| Kalshi | Shared retained pipeline implemented | Disabled in current production configuration | Global source licensing and current organization rights are both required. | Shared catalog, retained history and consensus support are implemented. Production source activation is currently disabled; source licensing and separate organization rights are required before collection or delivery. |
| Cross-venue comparison | Implemented | Disabled in current production configuration | Two distinct entitled sources, current human proposition/outcome review, complete terms and eligible observations are required. | Comparison support is implemented but conditional. It requires two distinct entitled sources, a current human-reviewed equivalent proposition/outcome mapping and fresh valid observations; no product plan or venue status grants these rights. |
The dedicated on-demand workspace and shared retained pipeline are implemented. Production collection is currently disabled; organization data rights and a current fixed-payout review are separate requirements. Polymarket US documentation
Polymarket US read-only integration
Polymarket US is a separate source from international Polymarket. Eligible licensed captures can enter scheduled canonical Monitor workflows when source and workspace gates allow; the dedicated workspace also provides on-demand catalog, original contract descriptions with a SHA-256 digest, and delayed binary YES books. Each book shows venue source time separately from server observation time.
GET /api/intel/v1/sources/polymarket-us?offset=0&limit=20
GET /api/intel/v1/sources/polymarket-us?slug=example-marketThe route requires a signed-in session, enabled Monitor platform and US workspace, an allowed organization with an active Evaluation or Institutional plan, a viewer-or-higher organization role, applicable MFA requirements, and current independent POLYMARKET_US rights for the organization. International Polymarket rights do not grant US access. Public documentation describes implemented support; it does not mean the route is globally enabled or that any particular organization is permitted.
This authenticated session endpoint has a dedicated DTO for on-demand catalog and contract reads; the shared canonical pipeline also supports retained US catalog, quote, history, conformance and reviewed-comparison workflows when their independent source, payout-admission and rollout gates allow. US production collection is currently disabled. These routes do not provide trading or account access. New shared catalog and consensus routes require a signed-in organization session; Developer Sandbox keys do not authenticate them. Bulk historical export remains planned.
Getting access
A self-service Developer Sandbox key returns synthetic fixture data. The canonical Monitor, source catalog and consensus routes documented here are authenticated session APIs; a Developer Sandbox key does not authenticate them, and production API-key transport is not available for these routes. Real source delivery also requires production rollout and current organization rights; historical exports are planned. Request access and we'll talk through the workflow you need.
WORKING SAMPLE · SYNTHETIC DATA
Follow the research from observation to evidence.
Open Monitor, screen the universe, inspect contract terms, compare eligible outcomes and retain a research brief. Watchlists, saved views and adjustable workspaces keep the same event in context.
No account required for the sample. Its fictional records, local alerts and research stay separate from organization data. Portfolio scenarios are a bounded private beta; organization access still requires sign-in, plan and source permissions.
Ready to integrate?
Request institutional access and tell us about your delivery preference.