Integration guide

This page is the whole integration in one place: the widget on your site, the calls that your server makes, the events that we send you, the order of the steps and the errors. It describes the contract that is live today. Each section links to the page of this portal that holds the full detail.

This page follows the widget way. If you build your own UI on the JSON data of the Market Feed instead, skip section 1 and step 3, and read the markets with the Market Feed guide. Your server then opens positions with POST /v1/positions, so we send no position.opened for them. User registration, balance sync, the webhooks for settled and voided positions, the errors and the go-live checklist are the same for both ways. Two ways to integrate compares them.

To keep a copy, print this page from the browser or save it as a PDF.

How the money moves

No real money moves through us. For each of your users we keep a virtual balance in our ledger, and that balance follows your wallet:

1. You register the user and report every balance change on your side with a balance sync. The virtual balance moves by the same amount.
2. The user opens a position in the widget. We take the stake from the virtual balance and send you position.opened.
3. The market resolves. We settle the position and send you position.settled with the payout. If the market is voided, we refund the stake and send position.voided. If the user closes the position before the market resolves, we pay the close amount into the virtual balance and send position.closed.
4. Reconciliation compares our balance with the balance that you report, and tells you when the two differ.

We never call your wallet and we never pull data from your system. You learn of every change to the virtual balance from the response to your own request or from a webhook.

1. Web widget integration

The widget shows the markets and the trading screens on your page. Your server opens a session for the user (step 3) and your page passes the session token to mount().

Once you have a token, this is the whole embed:

<script src="{{CDN_URL}}/widget/v1/widget.iife.js"></script>
<div id="prediction-market"></div>
<script>
  const widget = PredictionMarketWidget.mount({
    target: document.getElementById('prediction-market'),
    sessionToken: '{{SESSION_TOKEN}}',
    apiBaseUrl: '{{API_BASE_URL}}',
    onSessionExpired: () => {
      // ask your backend for a new session token, then call widget.setSession(token)
    },
    // optional
    locale: 'en',
    scheme: 'dark',
    theme: {
      accent: '#7c5cff',
    },
  });
</script>

{{SESSION_TOKEN}} is the token that your server minted for this page load. {{API_BASE_URL}} is the API address from the table on the Getting started page. Test keys and live keys use the same address.

mount() returns a handle with these methods:

When the player logs out of your site, call unmount(). When another player logs in, call unmount() and then mount() with that player’s token; setSession() is not for a different player. The one exception is the first login on a widget mounted with an anonymous token. After unmount(), every method does nothing, but navigate() and setSession() still throw on a malformed argument.

Do not paste your tenant API key (the pmk_ key) into sessionToken. The widget checks for that prefix on every mount. If it matches, or if any other option is malformed, mount() writes the reason to the browser console and throws a synchronous Error, and nothing renders. Code after the call stops running unless you wrap the call in a try/catch. This way your key does not reach every visitor of the page.

Theme

The widget uses a fixed set of theme tokens. You can set a value for each of them. You cannot add a token, and you cannot inject your own CSS.

font-size and spacing take a px or rem length, or 0. The widget ships no web font. It uses the system fonts by default, and a font-family value names a font that your page already loads.

Two places set the tokens, and the second wins:

1. The tenant default. Our team sets it in the admin panel, and you can edit all of the tokens in the card theme editor of the tenant portal. The widget reads it from GET /v1/widget/config before its first paint, and again every 15 minutes while its tab is visible. Call refreshConfig() to read it at once.
2. The theme option of mount(). It sets the values for one embed only, for example on a dark section of your page. A token that you leave out keeps the tenant default, and then the widget’s own default.

The scheme option follows the same rule. It is not a token, so it has its own option. Two embeds on one page can use two schemes.

The Widget guide also covers the bundle paths, the token refresh, the allowed origins, the locale and the phone layout.

Each entry gives a symptom, its cause and the fix. Open the browser console first. The widget writes the reason for a failed mount there, and the browser reports CORS and Content-Security-Policy blocks there too.

A CORS error in the console, and the widget stays empty

Cause: the origin of your page is not on your allowed list. Our API then sends no CORS headers for that origin, and the browser blocks every response.

Fix: open a support ticket with the exact origin, with its scheme and any port that is not the default. https://shop.example.com and http://shop.example.com are two origins, and so are http://localhost:3000 and http://localhost:5173. See Allowed origins.

If you leave out apiBaseUrl, the widget calls your own origin, and no CORS applies. Your page must then proxy /v1 and the realtime path /connection/websocket to our API.

The widget stays empty in a native app

Cause: the WebView loads the page from a local file or from an app-specific scheme such as capacitor://localhost. We register only http and https origins, so the browser blocks the calls.

Fix: let the WebView open a page of yours over https, and register the origin of that page.

A Content-Security-Policy violation in the console

Cause: your page sends a Content-Security-Policy that does not allow a source the widget uses. A page without a policy needs none of the changes below.

Fix: add these sources to your policy. The widget needs no other source.

The widget needs no 'unsafe-eval', no blob: or data: source, no frame-src and no font-src. It runs no eval, creates no frame and loads no font file. The widget is not an iframe, so your frame-ancestors and X-Frame-Options settings do not affect it.

The widget shows English text instead of your locale

Cause: the locale file did not load. The widget loads it with import(), which your script-src must allow, and which needs a CORS header from our CDN. The widget then falls back to English and writes one error to the console.

Fix: check that script-src allows the origin of {{CDN_URL}}. If the console shows a CORS error for a file under /widget/v1/locales/, open a support ticket, because the fix is on our CDN.

mount() throws, and nothing renders

Cause: an option failed the check at boot. Common cases are a tenant API key (a pmk_ value) in sessionToken, a callback that is not a function, and an apiBaseUrl with a path, a query or a hash. The widget shows nothing to the end user. This state is widget_config_invalid.

Fix: read the reason in the console, and correct the option. Pass the token that your server minted for this page load.

The widget draws as a narrow strip

Cause: the target element has no width of its own, for example an inline-block, a float, or a flex item with no width set.

Fix: give the target element a width, or use a plain block <div>. See Width and phones.

The player sees “Your session has expired” after some time

Cause: the token expired, and the automatic refresh failed. A refresh answers 401 invalid_session_token when the session is past its 24-hour cap, when the token already expired, or when we suspended your tenant. This state is widget_session_expired.

Fix: in onSessionExpired, mint a new token for the same player on your server and pass it to widget.setSession(token). The widget opens again where the player was. If a different player logs in, call unmount() and then mount() with that player’s token instead. See Refresh and expiry.

Error codes the widget shows

These codes are states of the widget in the browser. Four of them never appear in an HTTP response. The error-code registry lists every code.

2. Operator API integration

Your server calls our API over HTTPS. Every request carries your tenant API key in an Authorization: Bearer header. Use the key from your server only, never in a browser or in the widget. The key format, test and live mode and the scope of each key are on the Getting started page.

Endpoints

These are the endpoints that your server calls. We generate the table from the same OpenAPI document as the API reference, which has every request and response schema.

The examples below come from our contract test fixtures, the same ones that we run against the API. A value in double braces, such as {{api_key}}, is a placeholder.

Step 1: register the user

Register a user before any other call for that user. external_user_id is your own id for the user. Do not use an email address or other personal data as the id. The call needs the write:sync scope, and it is safe to repeat.

PUT /v1/users/{{external_user_id}}
Authorization: Bearer {{api_key}}
Content-Type: application/json
 
{
  "status": "active"
}

HTTP 200
 
{
  "external_user_id": "player-1",
  "status": "active"
}

The rules for the id and the status are in Getting started.

Step 2: sync the balance

Each time the balance of a user changes on your side, send us the change. direction is credit or debit, amount is positive, and amounts are JSON strings. Send resulting_balance, the balance that your system shows after the change: reconciliation compares against it. The example leaves it out to show the smallest valid body. The call needs the write:sync scope and an Idempotency-Key.

POST /v1/balance-sync
Authorization: Bearer {{api_key}}
Content-Type: application/json
Idempotency-Key: {{idempotency_key}}
 
{
  "external_user_id": "{{external_user_id}}",
  "direction": "credit",
  "amount": "100.00"
}

HTTP 200
 
{
  "transaction_id": "0192a0b1-7c2e-7d3f-8a4b-5c6d7e8f9a0c",
  "balance": "142.500000"
}

Compare the balance in each response with your own record. To send up to 500 changes in one request, use POST /v1/balance-sync/batch. The replay rules of Idempotency-Key are in Getting started.

Step 3: open a widget session

When the user loads your page, your server opens a session for that user and passes the token to your page for mount(). Open a new session on every page load. The call needs the write:positions scope, and the user must be registered.

POST /v1/widget/sessions
Authorization: Bearer {{api_key}}
Content-Type: application/json
 
{
  "external_user_id": "{{external_user_id}}"
}

HTTP 200
 
{
  "token": "eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.example.signature"
}

The widget refreshes the token by itself. When it can no longer do so, it calls onSessionExpired (Widget guide).

Step 4: read positions

Read the positions of a user with GET /v1/positions, or one position by its id. The calls need the write:positions scope.

GET /v1/positions/{{position_id}}
Authorization: Bearer {{api_key}}

HTTP 200
 
{
  "id": "0192a0b1-7c2e-7d3f-8a4b-5c6d7e8f9a0c",
  "external_user_id": "player-1",
  "market_slug": "will-it-rain-tomorrow",
  "outcome_id": "0192a0b1-7c2e-7d3f-8a4b-5c6d7e8f9a0d",
  "state": "open",
  "stake": "30.000000",
  "price": "0.400000",
  "payout": null,
  "open_transaction_id": "0192a0b1-7c2e-7d3f-8a4b-5c6d7e8f9a0e",
  "settlement_transaction_id": null,
  "created_at": "2026-09-01T12:00:00Z",
  "settled_at": null
}

Your server can also open and close positions itself, with POST /v1/positions and POST /v1/positions/{id}/close. For a position that your server opens or closes, we send no position.opened or position.closed webhook, because you already hold the response.

Rate limits

Each endpoint belongs to a limit tier. Over the limit, we answer 429 rate_limited with a Retry-After header and apply nothing. The limits are per minute:

The Rate limits page explains the tenant and end-user limits.

3. Webhooks

We send each event as an HTTPS POST to the webhook_url of your tenant. Every delivery carries three headers:

• X-Webhook-Signature: sha256= followed by the hex HMAC-SHA256 of the raw body, keyed with your webhook_secret.
• X-Webhook-Event: the event type.
• X-Webhook-Delivery: the id of the delivery, also in the id field of the body.

Handle each delivery in this order:

1. Compute the HMAC over the raw body bytes and compare it with X-Webhook-Signature in constant time. On a mismatch, reject the request.
2. Delivery is at least once. If you already processed the X-Webhook-Delivery id, answer 2xx and stop.
3. Record the event and answer 2xx. We retry any other answer five times. The last retry comes between about 3 hours 36 minutes and 10 hours 49 minutes after the first attempt.

Events arrive in no fixed order. For an event type that you do not know, answer 2xx and ignore the body. Code samples for the signature check in Node.js and Python are in the Webhook guide.

Body

Every body is one JSON object with these fields:

Events

The fields of each event and a sample body are in the Webhook guide.

4. Integration flow

The order of the calls and the events, from user registration to reconciliation:

5. Errors

Every error response has the same JSON envelope. This one comes from a balance sync that used an Idempotency-Key again with a different body:

POST /v1/balance-sync
Authorization: Bearer {{api_key}}
Content-Type: application/json
Idempotency-Key: {{idempotency_key}}
 
{
  "external_user_id": "{{external_user_id}}",
  "direction": "credit",
  "amount": "50.00"
}

HTTP 422
 
{
  "error": "idempotency_key_reused",
  "message": "Idempotency-Key was already used with a different request body",
  "details": null,
  "request_id": "0192a0b1-7c2e-7d3f-8a4b-5c6d7e8f9a0b",
  "ts": "2026-09-27T10:00:00.000000Z",
  "source": "lg"
}

Branch on the error code, never on the message text. In a support request, quote request_id and source; request_id is also in the X-Request-Id response header. These are the codes that you can receive:

The FAQ explains the codes that operators meet most often.

Before you go live

Before we approve live access and you get your live key, your test traffic must show each item below. The Go-live checklist page explains the approval.

1. User-sync round-trip: user upserted via PUT /v1/users/{external_user_id} and read back via GET with the expected status and balance.
2. Idempotency replay test passed: a balance-sync replayed with the same Idempotency-Key and body returns the stored response byte-identical; the same key with a different body is rejected 422 with nothing applied.
3. Position lifecycle exercised: a position opened in test mode against a seeded market and observed through settlement or void to its terminal state.
4. Webhook receipt and signature verification confirmed: at least one signed event received at the operator's webhook_url and its X-Webhook-Signature HMAC verified before processing.
5. Reconciliation cycle clean: at least one full scheduled reconciliation run over the operator's test-mode activity with zero discrepancies.
6. Rate-limit behavior understood: the operator's client has observed a 429 rate_limited response and demonstrably honors Retry-After instead of blind-retrying.