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"
}

{
  "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": null, "region": null, "theme": {},
  "usage": "Send as `Authorization: Embed <token>`. Never in a URL or a cookie."
}

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 exactly two things (the frame policy and the palette), and every byte of market, quote, order or position data requires the session token in a header.

Allowed origins

The embed document can only be framed from an origin registered against your operator. Anything else receives Content-Security-Policy: frame-ancestors 'none' and the browser refuses to render the frame. This is decided per session rather than per deployment, so two operators framing the same build get two different policies and changing domain is a provisioning change, not a Parity redeploy.

• Format is scheme://host[:port]. No path, no trailing slash, no wildcard, no scheme-less value.
• Several origins are supported. Register staging before you need it.
• 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

The embed emits parity.height_changed with a pixel height when its content grows or shrinks. 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.

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 or rejected when the held token stopped working. All three are answered the same way: mint a fresh token and reply.
• Never post to '*'. A wildcard target origin posts a customer's session token to whatever page happens to be listening.
• 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.

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.

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.

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 ceiling is an hour. Minutes, not days, because a browser-held credential is bounded by expiry rather than by secrecy.
• On expiry the embed emits parity.session.expired and then parity.session.required with reason: "expired". Mint and reply, with the same handler you already wrote.
• 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.
• Revoking a session takes effect on its next request, including on an open price stream.
• 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.

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 all three reasons, including rejected.
• 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.