Technical Overview

Welcome. This guide walks you through integrating the ProphetX sports prediction-markets exchange into your product, server to server. Read it once cover-to-cover for the first integration; come back later to whatever topic you're working on.

There's no front-end story in this guide — only server-to-server. If you are looking for any frontend integration info you can find it in the Frontend Integrations Category. If you're also embedding the UI components, Embedded UI (tokens + /embed/v1) covers the thin slice your backend needs to do for that to work.

Where to start

These docs are roughly in the order you'll want them on a first integration:

Authentication — Ed25519 JWTs, body digests, the per-user subject signature. Get this working first; everything else depends on it.
User Onboarding (users, KYC, terms) — create users, run KYC, record terms acceptance.
Wallets — the money model. There are two flavors (STANDING and INDIVIDUAL); confirm which one ProphetX provisioned for you before you read.
Fixtures (browsing markets) — browse tournaments, events, and markets to find a contract to trade.
Market Orders (single-contract trades) — single-contract orders. Async fill, so submit then poll (or subscribe to webhooks).
Parlays (2–12 leg trades) — 2–12 leg combined orders. Quote, confirm, then poll.
Webhooks (push events) — register a receiver and let ProphetX push events to you instead of you polling.
Embedded UI (tokens + /embed/v1) — short-lived tokens for ProphetX-hosted UI components.
Errors, Limits, and Configuration Reference — the reference page you'll keep open in the other tab.

How the request path is shaped

Every public request hits a ProphetX gateway that validates your JWT, extracts who you are and who you're acting on behalf of, then forwards the request to the appropriate ProphetX service.

your backend ──► ProphetX API  ──►  trading, user, wallet, push, etc.
  (signs JWT)    (auth + routing)

your frontend ──► embedded UI ──► ProphetX API ──► same services
                  (ProphetX-hosted, holds the token your backend minted)

What lives where

Path prefix	Who calls it	How they authenticate
`/private/v1/*`	Your backend	Ed25519 JWT you mint per request
`/embed/v1/*`	Embedded UI in the user's browser	Token minted via `GET /private/v1/tokens`

OpenAPI specs

When this guide and the OpenAPI spec disagree, the spec wins. ProphetX publishes three:

The private API spec — every endpoint under /private/v1/*.
The embedded UI spec — every endpoint under /embed/v1/* (mostly informational for backend integrators; your frontend's component library calls these).
The webhook spec — what your receiver must implement when ProphetX pushes events to you.

Ask your ProphetX contact if you don't already have copies.

Glossary

Skim this once and come back when something doesn't make sense.

Term	What it means
ISV	You — the integrating partner. Identified by a UUID, holds an Ed25519 private key, and is either `STANDING` or `INDIVIDUAL` (see Wallets).
User	An end user created under your ISV. Each user gets a UUID and a per-user shared secret used to sign their JWTs.
Shared secret	A 32-byte HMAC key (base64url, no padding) returned exactly once when you create the user. Used as the HMAC key for the `subsig` JWT claim.
KYC	The asynchronous identity check. Statuses: `PENDING`, `SUCCESS`, `FAILURE`, `MORTALITY`, `PEP`, `OFAC`. Only `SUCCESS` lets the user trade.
Terms bundle	Five legal documents, each independently versioned, plus a `totalVersion` that bumps when any of them change. The user must accept the current `totalVersion`.
Wallet	The ledger row. INDIVIDUAL ISVs get one wallet per user. STANDING ISVs get a single ISV-level standing fund plus per-user tally rows.
Transaction	A single ledger entry against a wallet — orders, payouts, deposits, fees, etc. Cursor-paginated; see Wallets.
Tournament	The top of the fixtures hierarchy (e.g. `NBA`, `NFL`, `MLB`) and the only browse-level the API exposes — there is no `GET /sports`. Each tournament carries its sport (e.g. `Basketball`) inline as `tournament.sport`.
Tournament / Event / Market	The fixtures hierarchy. A tournament holds events, an event holds markets, a market holds selections (outcomes). Each outcome — including the "yes" side and the "no" side of a binary market — is its own contract with its own `contractId`.
Contract	What you actually trade — a unique combination of event, market, outcome, and strike. Identified by a `contractId` hash.
Market order	A single-contract order at the best available price. Filled asynchronously.
Parlay	A combined order across 2–12 legs that all need to settle as profit for the parlay to win. Quote → confirm → poll.
Push registration	Your webhook receiver. Once registered, ProphetX will POST contract, settlement, market-order, matched-order, parlay, and fixtures events to it.
Embed token	A short-lived JWT your backend mints and hands to the embedded UI in the user's browser.
Permission / Gate	Per-user capability checks (e.g. `market-order`, `parlay`) and onboarding gates (e.g. `kyc`, `terms`) returned by `GET /private/v1/users/USERID/permissions`. The gateway enforces them on annotated endpoints — a missing permission surfaces as `403 permission_denied`.

That's the whole vocabulary. Everything else is variations on these themes.