Embed the Predictions tab

Parity ships in two shapes, and the choice decides everything else you read. If you are adding a Predictions tab to an existing casino, sportsbook or wallet, you want Embed. That is this page. If you are building your own trading UI, you want Headless, which is the rest of these docs.

The money architecture below is identical in both. It is the part of Parity that does not bend.

The worked example, because this is the part people re-invent

A customer has $100 with you. They stake $25 on a contract.

• Parity returns a quote whose operatorMoney.authorizationAmount is "25.00".
• You reserve $25 in your ledger. The customer now sees $75 available, $25 reserved. Their total is still $100 and it never left your books.
• You tell Parity the reserve succeeded. That is the entire handshake: success or failure, nothing else crosses.
• If you cannot reserve it, you decline. Parity renders an insufficient-funds state, invents no fill, and transmits nothing to a venue.

Every amount Parity hands you is an exact decimal string you apply. Never recompute one from a price and a quantity: the moment you do there are two answers to one question and only one of them is in Parity's ledger. The full contract, including partial fills and exits, is on The money contract.

  YOUR PAGE (browser)                     PARITY
  ┌───────────────────────────┐
  │ your header               │
  ├───────────────────────────┤           GET  /embed/predictions?operator=…
  │  <iframe> ───────────────────────────▶ the Predictions surface
  │    Parity draws           │           GET  /api/v1/stream/prices   (SSE)
  │    markets · ticket ·     │◀──────────────  live prices, filtered by
  │    positions              │                 your offering policy
  ├───────────────────────────┤
  │ your bottom nav           │
  └───────────────────────────┘
        │      ▲
        │      │  postMessage: NO MONEY IN EITHER DIRECTION
        ▼      │
  YOUR SERVER
    POST /api/v1/embed-sessions            mint a browser-safe token
    POST /api/v1/quotes                    (optional) price it yourself
    POST /api/v1/orders                    record a durable intent
    POST /api/v1/orders/{id}/confirm-reserve   "the funds are held"
    POST /api/v1/orders/{id}/cancel        release instruction
    GET  /api/v1/orders?…                  recovery

Three things you build: a server endpoint that mints a session, a message listener on the page that holds the iframe, and the reserve/release wiring into your own wallet. Everything inside the frame is ours.

Before you write anything, Parity provisions your tenant. Send us four things and you get back two.

POST /api/v1/embed-sessions
Authorization: Bearer <your Parity API key>
Content-Type: application/json

{
  "externalUserId": "acme-user-1234",
  "returnOrigin":   "https://acme.example",
  "ttlSeconds":     900,
  "locale":         "en",
  "region":         "us",
  "jurisdiction":   { "country": "MT" }
}

The body is strict: a field this route does not know is refused with 400 invalid_request rather than silently dropped, so a typo cannot mint a session that is quietly configured differently from what you sent. detail names the offending key.

{
  "sessionId":        "52dad6af-…",
  "token":            "pes1.<keyId>.<secret>.<mac>",
  "tokenType":        "embed_session",
  "expiresAt":        "2026-08-22T23:19:54.624Z",
  "expiresInSeconds": 900,
  "operatorId":       "50516095-…",
  "externalUserId":   "acme-user-1234",
  "origin":           "https://acme.example",
  "locale":           "en",
  "region":           "us",
  "jurisdiction":     { "country": "MT", "subdivision": null },
  "theme":            {},
  "usage": "Send as `Authorization: Embed <token>` on /api/embed/*. Never in a URL or a cookie."
}

locale, region and jurisdiction are echoed as stored, and are null when not sent. theme is {} when none was sent. operatorBookId appears only when a book was bound.

Your endpoint

Wrap the call in one route on your own server. It authenticates your customer with your own session, then mints. This is the only server work Embed requires beyond the wallet wiring.

// POST /api/parity/embed-session  (on YOUR backend)
export async function POST(request: Request) {
  const user = await requireSignedInUser(request);   // YOUR auth, not ours

  const res = await fetch(`${process.env.PARITY_HOST}/api/v1/embed-sessions`, {
    method: 'POST',
    headers: {
      // Server-side only. This key must never be reachable from the browser.
      authorization: `Bearer ${process.env.PARITY_API_KEY}`,
      'content-type': 'application/json',
    },
    body: JSON.stringify({
      externalUserId: user.id,
      returnOrigin: process.env.PUBLIC_ORIGIN,     // https://acme.example
      ttlSeconds: 900,
    }),
  });

  if (!res.ok) return Response.json({ error: 'session_unavailable' }, { status: 502 });

  const { token, expiresAt } = await res.json();
  // Return ONLY these two fields. Never proxy the whole body: it echoes your
  // operatorId and the session id, and your page needs neither.
  return Response.json({ token, expiresAt });
}

<iframe
  src="https://<your-parity-host>/embed/predictions?operator=acme-casino"
  title="Predictions"
  style="width:100%;height:100%;border:0"
></iframe>

?operator=acme-casino is public and grants nothing. It selects your operator's frame policy and presentation defaults, and every byte of quote, order or position data requires the session token in a header. To open one market directly, frame /embed/predictions/{id}?operator=acme-casino with the event id from the catalogue.

Allowed origins

The embed document can only be framed from an origin registered against your operator. Its Content-Security-Policy lists every registered origin in frame-ancestors, and an operator with none gets frame-ancestors 'none', so the browser refuses to render the frame anywhere else. This is decided per operator, from the list Parity registers on your embed settings, not per session: two operators framing the same build get two different policies, and changing domain is a configuration change that Parity makes for you. The session's returnOrigin is a separate check on the frame's API calls.

• Format is scheme://host[:port]. No path, no trailing slash, no wildcard, no scheme-less value.
• Up to ten origins are supported. Register staging before you need it.
• The same list decides who the frame talks to. It sends parity.session.required to each registered origin (never to '*'), accepts parity.session only from one of them, and from then on posts only to the origin that answered.
• An operator with no registered origin is unframable. That is the safe end of the trade: a visible, reportable failure rather than a silent widening.

Sizing: give the iframe your actual content pane

This is the recommended integration and the one to build first. Parity cannot know whether your mobile nav is 56px or 72px, whether you have a bottom bar, or whether your header collapses on scroll. So you hand the frame the pane you would have given any other screen, and Parity owns scrolling inside it.

/*
  The pane is what is left after YOUR chrome. Parity fills it and scrolls
  inside it: one scroll context, no nested scrollbars, no page-level jump
  when the player opens a market.
*/
.app {
  display: grid;
  grid-template-rows: auto 1fr auto;   /* header · pane · bottom nav */
  height: 100dvh;                      /* dynamic: survives the mobile URL bar */
  overflow: hidden;                    /* the PAGE never scrolls; the pane does */
}

.app__header { height: 56px; }
.app__nav    { height: 64px; }

.app__pane {
  min-height: 0;        /* without this a grid row refuses to shrink and the
                           iframe pushes the nav off-screen on small phones */
  overflow: hidden;
}

.app__pane iframe {
  display: block;
  width: 100%;
  height: 100%;
  border: 0;
}

• Prefer 100dvh to 100vh. On mobile Safari and Chrome 100vh is the viewport with the URL bar hidden, so a 100vh layout hides your own bottom nav under the browser chrome until the user scrolls. dvh tracks the pane that is actually visible.
• Do not assume the pane is the viewport. Subtract your chrome, with a grid row as above, or height: calc(100dvh - 56px - 64px) if you would rather be explicit.
• min-height: 0 on the pane is load-bearing. A CSS grid or flex item defaults to min-height: auto and will not shrink below its content, which on a long market list silently pushes your navigation off the bottom of the screen.
• Add -webkit-overflow-scrolling: touch nowhere and overflow: hidden on the page: two scroll contexts stacked is the single most common embed complaint, and it is always the host page scrolling behind the frame.

Optional: auto-height

Add sizing=auto to the iframe URL and the embed emits parity.height_changed with a pixel height when its content grows or shrinks by 24 pixels or more, at most once per animation frame. Without sizing=auto (the default is pane) the message is never sent. You can resize the iframe from it, and for a short page inside a long marketing site that is the right answer.

if (data.type === 'parity.height_changed') {
  iframe.style.height = `${data.height}px`;
}

Content Security Policy

If your page ships a CSP (and it should), it must allow the frame. This is on your policy; Parity sets frame-ancestors on its own response and the two have to agree or the frame stays blank.

Content-Security-Policy: frame-src https://<your-parity-host>;

• frame-src, not child-src. If you support older browsers, send both.
• You do not need a connect-src entry for Parity. The price stream is opened by the document inside the frame, under Parity's own policy.
• If a proxy, WAF or CDN sits in front of your page, confirm it passes text/event-stream through unbuffered. A buffering proxy turns a live price feed into a feed that delivers everything at once, minutes late.

Every presentation setting has a stored default on your operator and can be overridden per placement on the iframe URL. The URL wins, then your stored setting, then Parity's default. A value that fails validation falls back rather than erroring.

<iframe
  src="https://<your-parity-host>/embed/predictions?operator=acme-casino&mode=dark&accent=%2300c2a8&density=compact&locale=es&region=mx"
  title="Predictions"></iframe>

• These parameters are carried on every link inside the frame, so a player who opens a market keeps the same presentation.
• Branding is these four knobs: mode, accent, radius and density. There is no font or logo setting for an operator. The accent's text colour is chosen automatically for contrast.
• Language is exactly one of en, es, pt, hr. The match is exact: pt-BR is not pt and falls through. The frame uses the first of: ?locale=, the session's locale, your operator's configured primary language, the language stored in your embed theme, then the browser's Accept-Language.
• Region orders the board so the markets your customers care about lead. The frame uses ?region=, then the session's region, then your operator's stored region, then a default.
• Currency has no URL parameter, deliberately. Stakes are shown in your operator's display currency, converted only through a peg or a recorded rate; see The money contract.
• Per customer: the session's locale, region and theme apply to that customer's frame as soon as it holds the token. The order is the iframe URL, then the session, then your stored settings: a parameter on a placement is the most specific thing you can say, so it keeps winning. Language and region are drawn on our side, so the frame reloads its own page once to apply them; the theme applies in place.
• Live: parity.theme from your page changes the theme at any time, without a reload, and wins over every other source. See the message contract.

The embed document is fetched by an iframe navigation, which is a plain GET: a browser will not put an Authorization header on one, a cookie would be CSRF with a trading API behind it, and a query string leaks. So the frame carries no credential and asks your page for one. That request is parity.session.required, and answering it is the minimum working integration.

const PARITY = 'https://<your-parity-host>';
const frame  = document.querySelector('iframe');

window.addEventListener('message', async (event) => {
  // ORIGIN FIRST, before the payload is even looked at. An unrecognised
  // sender should cost one string compare, not a parse of whatever they sent.
  if (event.origin !== PARITY) return;

  const message = event.data;
  if (!message || message.protocol !== 'parity.embed.v1') return;

  if (message.type === 'parity.session.required') {
    // YOUR endpoint from step 1. The API key stays on your server.
    const res = await fetch('/api/parity/embed-session', { method: 'POST' });
    const { token, expiresAt } = await res.json();

    frame.contentWindow.postMessage(
      { protocol: 'parity.embed.v1', type: 'parity.session', token, expiresAt },
      PARITY,                       // an explicit target origin. NEVER '*'.
    );
  }
});

• reason is initial on mount and expired when the held token stopped working (an expiry, a revocation or any other refusal of the token). Both are answered the same way: mint a fresh token and reply. The protocol type also names rejected; handle every reason the same way. An expired request is always preceded by parity.session.expired, so a page that wants its own reconnecting state has a moment to show it.
• Answer before you wait for anything. parity.ready is sent only after the frame has accepted a parity.session. A page that holds its answer until ready arrives waits forever.
• Send a fresh token. A token equal to the one the frame just had refused is ignored, and the frame stays in its reconnecting state until a different one arrives. Replacement requests are throttled to one every 5 seconds.
• Never post to '*'. A wildcard target origin posts a customer's session token to whatever page happens to be listening.
• parity.session may also carry capabilities, a list of what your page handles beyond the minimum. order.cancel says you answer parity.order.cancel_requested, and gives the customer a withdraw action on an order that has not traded. Without it the frame offers none.
• Do not persist the token: not localStorage, not a cookie, not the URL. A token in localStorage outlives the session that needed it and is readable by every script your page ever loads.

Parity → your page

Your page → Parity

requestId is how a reply is matched to its request. Echo it exactly; a reply with an unknown requestId is dropped, because a shell that answers the wrong ticket is worse than one that answers none.

• A parity.order.accepted without an orderId is ignored. The frame then reads the order back from Parity and shows its operatorMoney.authorizationAmount; the acceptance is only trusted once that read succeeds.
• A reason outside the three is shown as rejected. message is your own words to your customer, rendered as plain text and cut at 200 characters.
• If neither answer arrives within 20 seconds, the ticket shows a no-answer error. Your server may still complete the order; recover it by clientOrderId, as in Failure and recovery.
• Only messages from your registered origins are read, and once one of them has answered the handshake, only that one. That applies to every inbound message, including parity.theme and parity.navigate.
• parity.navigate names a destination and never carries an address. The frame builds the path itself, so it can only ever move within the frame.

Every message carries protocol: "parity.embed.v1". Filter on it: your page's window receives messages from React devtools, analytics SDKs and payment widgets, and an embed that skips the check ends up with mystery crashes rather than security incidents. The version is a contract: a field may be added, a field is never changed.

GET /api/v1/stream/prices?contracts=ctr_a,ctr_b
Authorization: Embed <token>
Accept: text/event-stream

• One connection per page, however many contracts it watches. Fan-out is ours: a thousand browsers on one contract cost one upstream subscription.
• Frames are hello (what you are subscribed to, and what was refused), snapshot (everything; safe to replace state with), update (only what changed; patch, never replace), heartbeat, status (the feed went stale or recovered), revoked (contracts withdrawn from a live connection) and error.
• Filtered by your offering policy before delivery. A market you may not offer is refused in hello and no price for it is ever sent, not sent and hidden.
• Contract ids are opaque ctr_…. No venue name appears anywhere on this wire.
• Each frame carries an id:; EventSource replays it as Last-Event-ID on reconnect, so continuity is a browser feature rather than code you write.

The session token here decides exactly one thing: whose offering policy applies. A connection with no credential gets the unrestricted public catalogue. A connection with a refused credential is closed, never downgraded to anonymous, which would serve a revoked session more than it could see while valid.

You never call these yourself; the frame does, with the session token. They are listed so your monitoring and your support team can read a refusal when a player reports one.

• The token travels as Authorization: Embed <token>, or in the X-Parity-Embed-Session header (an earlier name for that header is still read). A Bearer operator key is not accepted here.
• If the session carries a returnOrigin, a request's Origin must equal it. The frame's own same-origin calls, and requests with no Origin, pass.
• Rate limit: 300 requests a minute per session, and every session also counts against your operator's per-minute budget, the same one your API key draws on (see Rate limits). Over either, the answer is 429 rate_limited with RateLimit-* and Retry-After headers.

Where your offering depends on where the customer is, Parity decides from the jurisdiction you assert, never from an IP address. Assert it with jurisdiction when you mint the session, or with PUT /api/v1/users/{id}/jurisdiction; either records it against the customer.

• If your tenant's jurisdiction rule is enforced, a customer whose asserted jurisdiction you are not offered in sees a panel explaining that predictions are not available where they are (with the country's flag when one is known) instead of the board, and the catalogue, quote and order paths refuse on the server regardless of what the frame shows.
• If the rule is not enforced, the assertion is stored and nothing is blocked by it.
• The frame also records the country of the player's IP address as evidence for your own review. It never blocks, allows or changes anything.

This is the sequence that moves money, and every step of it exists so that there is never a moment where you have reserved a customer's funds but cannot determine whether Parity holds an executable order.

player taps BUY inside the frame
       │
       ├─▶ embed → your page   parity.order.requested { requestId, quoteId, clientOrderId }
       │                        (no money in this message)
       │
       │   YOUR SERVER
       │   1. POST /api/v1/orders  { quoteId, clientOrderId, externalUserId,
       │                             executionIntent: "record_intent" }
       │      → orderId, state reserve_pending, transmissionState not_transmitted
       │      → operatorMoney.authorizationAmount   ← the AUTHORITATIVE amount
       │
       │   2. reserve authorizationAmount in YOUR ledger
       │      ├─ cannot?  → POST /api/v1/orders/{orderId}/cancel   and decline
       │      └─ held?    → continue
       │
       │   3. POST /api/v1/orders/{orderId}/confirm-reserve
       │      → state pending_venue_execution
       │
       ├─◀ your page → embed  parity.order.accepted { requestId, orderId }
       │                  or  parity.order.declined { requestId, reason }
       ▼
   the frame renders the confirmed ticket, or an insufficient-funds state

Step 1: record a durable intent

POST /api/v1/orders
Authorization: Bearer <your Parity API key>
X-Parity-User: acme-user-1234

{
  "quoteId":         "qt_…",
  "clientOrderId":   "your-own-idempotency-key",
  "executionIntent": "record_intent"
}

The response carries a stable Parity orderId, status reserve_pending, transmissionState not_transmitted, and operatorMoney. operatorMoney.authorizationAmount is the number you reserve, obtained here, from your own server-side call, and never from a message the browser sent you.

clientOrderId is your id and it is the idempotency key. Derive it from the reservation in your own ledger, never from a clock or a random value: the whole point is that it survives the crash that lost you our response. Re-POSTing the same id returns the same order with idempotentReplay: true, never a second one. That is enforced by a unique index on (operator, user, clientOrderId), not by a check in a handler.

Step 2: reserve, in your ledger

Nothing here is Parity's. Move authorizationAmount from available to reserved against the customer's one balance. If it does not fit, go to cancel and decline the order. An insufficient balance is a normal outcome, not an error state.

Step 3: confirm the reserve

POST /api/v1/orders/ord_…/confirm-reserve
Authorization: Bearer <your Parity API key>

{ "reserveReference": "your-own-hold-id" }

The order becomes pending_venue_execution: cleared to execute, and it progresses to submitted and then filled under the same state names you are already consuming. reserveReference is optional, stored and never interpreted. It is your half of the audit trail.

Idempotent. A call that times out can simply be sent again: the same confirmation twice returns 200 with idempotentReplay: true and yields one executable order. It is never a conflict, because answering the safe action with an error is how an integration learns to stop retrying.

It refuses a cancelled order, and an order that is not awaiting a reserve at all (one already at a venue, filled or rejected), with a 409. Absorbing those would tell you your hold is standing behind a live order when it is standing behind nothing.

Step 4: answer the frame

if (message.type === 'parity.order.requested') {
  const { requestId, quoteId, clientOrderId } = message;

  // Your server does steps 1-3 and answers with a verdict, never an amount.
  const res = await fetch('/api/parity/order', {
    method: 'POST',
    headers: { 'content-type': 'application/json' },
    body: JSON.stringify({ quoteId, clientOrderId }),
  });
  const result = await res.json();

  frame.contentWindow.postMessage(
    result.ok
      ? { protocol: 'parity.embed.v1', type: 'parity.order.accepted',
          requestId, orderId: result.orderId }
      : { protocol: 'parity.embed.v1', type: 'parity.order.declined',
          requestId, reason: result.reason },   // insufficient_funds | unavailable | rejected
    PARITY,
  );
}

{
  "cancellation": {
    "cancellationId":      "cxl_…",
    "currency":            "USD",
    "authorizationAmount": "25.00",
    "actualDebit":         "0.00",
    "releaseAmount":       "25.00",
    "reason":              "player cancelled",
    "issuedAt":            "2026-08-22T23:19:54.624Z",
    "idempotentReplay":    false
  }
}

• authorizationAmount = actualDebit + releaseAmount, exactly. It is an equality, not a tolerance: every figure is an exact integer of minor units rendered as a decimal string, and releaseAmount is a subtraction rather than an independently derived remainder.
• actualDebit is "0.00" on a cancellation. A cancelled order spent nothing, so everything comes back.
• Cancelling twice returns the SAME cancellationId with idempotentReplay: true. Key your release on that id and you release exactly once even if your first response was lost. Two ids for one cancellation is how a customer gets credited twice.

When the customer withdraws in the frame. If your page declared order.cancel on parity.session, an order that has not traded shows a withdraw action. Pressing it sends parity.order.cancel_requested { requestId, orderId }; your server calls this endpoint for that orderId and applies the release. The frame reads the order back from Parity and shows it withdrawn once it is cancelled. If it is not cancelled within about 20 seconds, the customer is told the withdrawal is unconfirmed, never that it happened.

Every boundary in this flow recovers from an id Parity already holds, and none of them asks you to remember anything else.

The rule underneath all of it: never release on an unknown. A timeout is not a rejection. Hold the authorization and resolve it by reading, not by assuming.

• Default TTL is 900 seconds; the floor is 60 and the ceiling is an hour. Minutes, not days, because a browser-held credential is bounded by expiry rather than by secrecy.
• On expiry the embed sends parity.session.expired and then parity.session.required with reason: "expired", at the moment a request is refused. Mint and reply, with the same handler you already wrote. The frame also checks its session once a minute and just after expiresAt, so an idle frame asks in time too.
• The frame does not renew ahead of time: the expiresAt you pass with parity.session is not read. If you want no visible reconnect, send a fresh parity.session before the old token expires; the frame takes the newer token.
• A refused token is never retried on a backoff. The embed asks you instead, so an expiry becomes one round trip rather than a reconnect loop.
• Keep session lifetimes short. To stop a customer at once, suspend them from your operator portal: suspension is checked on every request, so the session's next request is refused with user_suspended.
• Mint per customer session, not per page view, and mint lazily. A token minted and not used is a credential with no purpose and a real lifetime.

End a session early

{
  "sessionId":        "52dad6af-…",
  "revoked":          true,
  "revokedAt":        "2026-08-22T23:19:54.624Z",
  "idempotentReplay": false
}

• Call it when your own session for the customer ends: sign-out, self-exclusion, or a token you believe has leaked. The frame's next request with the token is refused 401 session_revoked, and your page receives parity.session.expired and parity.session.required. Your server decides whether to mint a replacement.
• Revoking ends that one session immediately. To stop a player, your server should also stop minting sessions for them, so the frame's request for a replacement is refused on your side.
• Same scopes as minting: markets:read, quotes:write and orders:write. A key missing any of them gets 403 insufficient_scope naming the ones missing.
• Idempotent. Ending an ended session returns 200 with the original revokedAt and idempotentReplay: true. Resend freely.
• A session id belonging to another operator is 404 unknown_session, the same answer as an id that never existed. Every revocation is recorded in your audit trail with the API key that made it.

Settlement is the same in Embed and Headless, and it is the one part of the lifecycle the frame cannot do for you: crediting a winner is a movement in your ledger.

• Poll GET /api/v1/settlements. Each record carries the exact figure: operatorMoney.settlementCredit for a winner, operatorMoney.voidCredit for a cancelled market, fee included.
• Every record is safe to apply twice: key on the settlement id.
• Stop on hasMore, never on the cursor. This feed hands back a cursor on its last page (it is a resumable watermark, not an end marker), so while (nextCursor) never terminates.
• GET /api/v1/reconciliation is the verdict on whether your books and ours agree, and GET /api/v1/reconciliation/feed is the totally-ordered fact stream behind it.

Full detail on Settlement and Reconciliation.

An order is recorded before it can execute, and it becomes executable when you confirm that the customer's funds are held. The row is written first on purpose: an execution that succeeds upstream and then fails to be recorded is the one outcome with no recovery path. That is what the reserve handshake expresses, and it is why reserve_pending and pending_venue_execution are states your server can read.

Load-bearing on both paths: the catalogue, live pricing from real upstream books, quote expiry, the durable order record, idempotency, the reserve handshake, cancellation and release, collateral, settlement records and reconciliation. The state names are the same in the sandbox and live, so an integration built against them does not change when the key does.

• The API key is server-side only. Grep your bundle for its prefix and prove it.
• Every production and staging origin is registered, and your CSP names frame-src.
• The iframe gets your real content pane, with 100dvh and min-height: 0, and the host page does not scroll behind it.
• parity.session.required is answered for every reason, initial and expired included, without waiting for parity.ready.
• The region you send, on the session and on the URL, is lower case and one of the ten listed; the language is en, es, pt or hr.
• If your offering is jurisdiction-enforced, every session carries the customer's jurisdiction.
• clientOrderId comes from your ledger, not a clock, and a replayed POST is handled as success.
• A failed reserve declines with insufficient_funds and never with a fabricated accept.
• A cancel is keyed on cancellationId, and transmissionState: "unknown" holds rather than releases.
• Settlement polling stops on hasMore, and credits are keyed on the settlement id.
• You have worked through Going live, which covers what to prove before the key changes.