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.

Wallet callback response contract

{
  "code": "INSUFFICIENT_FUNDS",
  "error": "insufficient balance"
}

{
  "balance": 0
}

Wallet callback relationship

The money callback always happens first. /history is sent afterwards when the bet record is created or updated. Treat /history as reporting/reconciliation data only; do not change wallet balance from /history.

Debit then settle - one history row

Use this model when the provider first debits a stake and later settles the same round. The settle callback uses the same bet_id as the original bet, while txn_id changes for each wallet movement.

Debit then settle - separate history rows

Some providers store the bet and the settle as separate reporting rows. In that case each money callback gets its own bet_id, and each following /history uses the matching pair.

Immediate-result round

Use /bet-end only when one provider callback contains both the stake and final payout. The wallet should debit the stake and apply the payout in one idempotent operation.

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.