External Game Aggregator API

Base URL

All API requests are made to your assigned base URL. Replace https://api.example.com with the host provided to you.

https://api.example.com

Authentication

Authenticate every request with your secret API key in the x-api-key header. Your key is unique to your account and must be kept private - never expose it in client-side code.

curl https://api.example.com/game/provider \
  -H "x-api-key: YOUR_API_KEY"

IP whitelist

For an extra layer of security your account can be locked to a list of allowed source IP addresses. When a whitelist is configured, requests from any other address are rejected with 403.

• Provide the public IPs (or CIDR ranges) of your servers to enable the whitelist.
• Both single addresses (203.0.113.10) and CIDR ranges (203.0.113.0/24) are supported.
• Leave it unset to allow any source IP (API key only).

Conventions

• Request bodies may be sent as JSON or form-encoded. Responses are always JSON.
• The user_agent is the unique identifier of a player, returned by Register (for example LAG1.0632094194).
• Monetary amounts are decimal numbers in your account currency.
• Timestamps are ISO-8601 strings in UTC.

Overview

In the seamless wallet model you hold the player balance. When a player bets or wins, our platform calls your wallet endpoints in real time and uses your response as the source of truth - no balance transfers are required.

You implement and host the five callback endpoints below under a single base URL (your wallet URL). Every request is signed with HMAC-SHA256 so you can verify it is authentic.

HMAC signature

Every callback body includes an hmac field. Verify it with your shared AGENT_SECRET before trusting the payload.

1. Remove the hmac field. The remaining fields are your payload.
2. Sort the payload keys alphabetically (A to Z).
3. Serialise to a compact JSON string (no extra whitespace).
4. Compute HMAC-SHA256 of that string with AGENT_SECRET and output hex.
5. Compare against the received hmac. If equal, the request is authentic.

const crypto = require('crypto');

function verifyCallbackSignature(reqBody, agentSecret) {
  const { hmac, ...payload } = reqBody;
  if (!hmac) return false;

  const sorted = Object.keys(payload).sort()
    .reduce((acc, k) => { acc[k] = payload[k]; return acc; }, {});

  const expected = crypto
    .createHmac('sha256', agentSecret)
    .update(JSON.stringify(sorted))
    .digest('hex');

  return hmac === expected;
}

// app.post('/bet', (req, res) => {
//   if (!verifyCallbackSignature(req.body, AGENT_SECRET))
//     return res.status(401).json({ error: 'invalid signature' });
//   ...
// });

Errors

The API uses standard HTTP status codes. Authentication and authorisation failures return a JSON body with an error message.

Integration flow

A typical end-to-end integration looks like this:

1. Register each of your players once with /create-user and store the returned user_agent.
2. Browse games with /game/provider and /game/list.
3. Launch a game with /game/open-game and redirect the player to the returned URL.
4. Settle play as it happens - implement the seamless wallet callbacks so we can read balance, debit bets, and credit wins against your wallet.
5. Reconcile using the /history feed and /bet-history/report/detail-bet.