# 155.io API Documentation

> Complete API reference for integrating 155.io games into your platform.

## Overview

155.io provides a betting game platform (marble racing, duck racing, coin flip, etc.). Integration consists of two parts:

1. **155.io API** — Endpoints we provide for fetching games and generating player URLs
2. **Operator API** — Endpoints you implement for balance, bets, rollbacks, and wins

You can also embed the game in an iframe and communicate with it over a `postMessage` API.

## Environments

| Environment | Base URL |
|-------------|----------|
| Staging | `https://api.stagingmarbles.io` |
| Production | `https://api.marbles.xyz` |

## Key Concepts

### Partner ID vs Operator ID

- `partnerId` — You choose this. It identifies your website or casino brand (e.g., `"my-casino"`, `"my-casino-asia"`). You can use different partner IDs to distinguish between platforms or regions under the same operator.
- `operatorId` — Provided by 155.io. Links to your operator configuration (liability limits, game settings, etc.).

### Currency Precision

Amounts are sent as integers in the currency's minor units. **Precision varies by currency** — most currencies use 5 digits, but several cryptocurrencies use more. Always divide by `10^precision` for the human-readable amount.

**Fiat, stablecoins (`USDT`/`USDC`/`DAI`) and special currencies use 5-digit precision** (the kilo variants `kIDR`/`kVND` use **8**):

```
$10.00 = 1000000
$1.00  =  100000
$0.01  =    1000
```

**Cryptocurrencies use 6, 8, 9, or 10-digit precision** (per-currency, see the Cryptocurrencies table):

```
1 BTC = 100000000   (8-digit precision, satoshi-style)
1 ETH = 100000000   (8-digit)
1 SOL = 1000000000  (9-digit)
1 ADA =    1000000  (6-digit)
1 XRP =    1000000  (6-digit)
```

Sending the wrong precision mis-renders amounts by orders of magnitude — e.g. sending `100000` for 1 BTC reads as `0.001 BTC` because BTC uses 8-digit precision.

Use a 64-bit integer type — `long` (Java) / `int64` (Go/Protobuf) / `bigint` (JS) — not `int` (32-bit), which overflows at ~$21,474 for a 5-digit-precision currency.

---

# Security

Two distinct mechanisms protect the integration depending on who is calling whom — don't mix them up.

## Direction matrix

| Direction | Endpoints | Authentication | What you do |
|---|---|---|---|
| **You → 155.io** (inbound) | `/game/game/url`, `/game/games`, `/game/round`, `/game/bets`, `/game/free-bets/rewards`, `/game/free-bets/rewards/cancel` | **IP whitelist.** Your server's outbound source IP must match the address(es) you registered during onboarding. | Make sure your outbound IP is the one we have on file. The `X-Marbles-Signature` header is **ignored** on these endpoints — you may send it, it will not be checked. |
| **155.io → you** (outbound callbacks) | `/balance`, `/bet`, `/win`, `/rollback` | **RSA-SHA256 signature** in `X-Marbles-Signature`, signed with 155.io's private key. | **Verify** the signature (recommended) using 155.io's public key (shared at onboarding) and reject requests that fail — *or* strictly **IP-allowlist 155.io's egress IPs**. Either is accepted for go-live; verifying is the stronger option. |

> Note: requests from you to 155.io are **not** signature-authenticated today — they are authenticated by source IP. Only 155.io's callbacks to your server are signed.

## Onboarding key exchange

Submit during onboarding:

1. **Server IP address(es)** that will make outbound calls to 155.io — these are the IPs we whitelist for your inbound traffic.
2. **Your RSA public key** (PEM) — kept on file in case inbound signature verification is enabled later (see Roadmap).

You receive:

- **155.io's public key** (PEM) — use this to verify our outbound callbacks.
- **155.io's outbound IP address(es)** — whitelist these on your firewall so our `/balance`, `/bet`, `/win`, `/rollback` calls reach your server.

## Generating your public key

An RSA key pair has two halves. The **private key stays on your server and is never shared** — not with 155.io, not over email or chat. The **public key** is the half you send us; it can verify a signature but cannot create one, so it is safe to share.

To generate one:

```bash
openssl genrsa -out marbles-private.pem 2048            # keep this, never send it
openssl rsa -in marbles-private.pem -pubout -out marbles-public.pem   # send this one
```

The file you send must begin with `-----BEGIN PUBLIC KEY-----`. Use at least 2048 bits.

Never send a private key. Files beginning `-----BEGIN PRIVATE KEY-----`, `-----BEGIN RSA PRIVATE KEY-----` or `-----BEGIN OPENSSH PRIVATE KEY-----` are the private half. If a private key has been shared, generate a fresh pair and send the new public key.

Already have a key in another format? Converting only re-encodes it — it stays the same key (the `ssh-keygen -l -f key.pub` fingerprint is unchanged):

| What you have | Starts with | Convert with |
|---|---|---|
| OpenSSH public key | `ssh-rsa AAAAB3Nza...` | `ssh-keygen -e -f key.pub -m PKCS8 > key.pem` |
| PKCS#1 public key | `-----BEGIN RSA PUBLIC KEY-----` | `openssl rsa -RSAPublicKey_in -in key.pem -pubout -out public.pem` |
| A private key | `-----BEGIN ... PRIVATE KEY-----` | `openssl rsa -in private.pem -pubout -out public.pem` |

The most common mix-up is sending an SSH key: `ssh-keygen` produces keys for server logins, in a different encoding to the PEM format required here.

## Verifying our outbound signature

Each callback we send to `/balance`, `/bet`, `/win`, `/rollback` includes `X-Marbles-Signature` — a base64-encoded RSA-SHA256 signature over the **raw request body bytes**. Compute the signature over the exact bytes you received (do not re-serialize, do not strip whitespace) and verify against 155.io's public key.

### Signature-Failure Response

If verification fails, reject the request with a **non-2xx status (e.g. 401)** and no `status` field — a failed signature is an authentication failure, not a business outcome, and this is the one case where a non-200 is correct. There is **no** signature-specific `status` value (do not invent one such as INVALID_SIGNATURE — any unrecognised status is treated as UNKNOWN_ERROR, and on `/bet` that triggers an automatic `/rollback`). Every business outcome is still an HTTP 200 with the result in `status`.

### TypeScript Example

```typescript
import { createSign, createVerify } from 'node:crypto'

// Verify an incoming 155.io callback (/balance, /bet, /win, /rollback)
function isValid(message: string, signature: string, publicKey: string): boolean {
  return createVerify('RSA-SHA256').update(message).verify(publicKey, signature, 'base64')
}

// Optional: sign your own responses (we don't currently verify, but it's forward-compatible)
function sign(message: string, privateKey: string): string {
  return createSign('RSA-SHA256').update(message).sign(privateKey, 'base64')
}
```

### Python Example

```python
from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64

def is_valid(message: str, signature: str, public_key_pem: str) -> bool:
    public_key = serialization.load_pem_public_key(public_key_pem.encode())
    try:
        public_key.verify(base64.b64decode(signature), message.encode(), padding.PKCS1v15(), hashes.SHA256())
        return True
    except Exception:
        return False

def sign(message: str, private_key_pem: str) -> str:
    private_key = serialization.load_pem_private_key(private_key_pem.encode(), password=None)
    return base64.b64encode(private_key.sign(message.encode(), padding.PKCS1v15(), hashes.SHA256())).decode()
```

### PHP Example

```php
function isValid(string $message, string $signature, string $publicKey): bool {
    return openssl_verify($message, base64_decode($signature), $publicKey, OPENSSL_ALGO_SHA256) === 1;
}

function sign(string $message, string $privateKey): string {
    openssl_sign($message, $signature, $privateKey, OPENSSL_ALGO_SHA256);
    return base64_encode($signature);
}
```

### Java Example

```java
// Verify
Signature verify = Signature.getInstance("SHA256withRSA");
verify.initVerify(publicKey);
verify.update(message.getBytes());
boolean valid = verify.verify(Base64.getDecoder().decode(signatureStr));

// Sign (optional)
Signature sig = Signature.getInstance("SHA256withRSA");
sig.initSign(privateKey);
sig.update(message.getBytes());
String signature = Base64.getEncoder().encodeToString(sig.sign());
```

### C# Example

```csharp
// Verify
byte[] data = Encoding.UTF8.GetBytes(message);
bool valid = publicKey.VerifyData(data, Convert.FromBase64String(signature), HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);

// Sign (optional)
byte[] signatureBytes = privateKey.SignData(data, HashAlgorithmName.SHA256, RSASignaturePadding.Pkcs1);
string signatureBase64 = Convert.ToBase64String(signatureBytes);
```

## What we send and expect

| Surface | `X-Marbles-Signature` header | Verified by recipient |
|---|---|---|
| Your request to 155.io (any inbound endpoint) | Optional. You may send one; we do not check it. | No |
| 155.io response to you (any inbound endpoint) | Not sent. | N/A |
| 155.io request to your `/balance`, `/bet`, `/win`, `/rollback` | Always sent, RSA-SHA256 over raw body bytes. | **Recommended** — verify it, or strictly IP-allowlist our egress IPs. |
| Your response to our `/balance`, `/bet`, `/win`, `/rollback` | Optional. Forward-compatible but not currently checked. | No (today) |

## Timeouts

The goal is **sub-second communication**, but each callback has a hard deadline: `/balance` 8s, `/bet` 8s, `/win` 30s, `/rollback` 30s. Exceeding the `/bet` deadline is treated as a rejection — an automatic `/rollback` is sent for that transaction, even if the wallet actually accepted the debit after the response was lost.

## Idempotency

All money-moving callbacks must be processed idempotently — a retry must never move money twice. The dedupe key differs per callback: `/bet` and `/win` dedupe on `transactionId` (stable across retries; only `requestId` changes). `/rollback` dedupes on **`referenceTransactionId`** — the rollback's own `transactionId` is NOT stable between attempts and must never be the dedupe key (deduping rollbacks on it refunds the same stake once per attempt).

## Roadmap

We may enable signature verification on inbound endpoints in the future. If you already sign your outbound requests today, no change will be needed when that happens. We will give advance notice before enforcing.

---

# Provably Fair

Every game on 155.io is provably fair: the outcome of each round is fixed by a secret seed committed before betting closes and revealed after the round settles. Anyone — player, operator, or auditor — can reproduce the exact outcome from the revealed seed with no trust in 155.io. The verifier is open source and runs entirely in the player's browser. There is no operator integration: nothing to implement, nothing to compute on your side.

## How it works

- **Pre-committed hash chain.** Seeds form a chain where `seed[i] = SHA-256(seed[i+1] as its 64-char lowercase hex string, hashed as ASCII text)` — the hex TEXT is hashed, never the decoded bytes; the commitment uses the same encoding (`serverSeedHash = SHA-256(ASCII text of serverSeed)`). The chain's root hash is published up front. Round `j` uses `seed[j]`. A revealed seed hashes forward to the published root, but the root reveals nothing about future seeds. Seeds are consumed strictly in order, so a seed cannot be reordered or swapped in after the fact. Draws: `message = "<beacon>:<label>:<index>"` (beacon may be empty — the leading colon is kept, e.g. `:crash:0`); `draw = first 13 hex chars of HMAC-SHA256(key = hex-decoded server-seed bytes, message as UTF-8)`; `r = int(draw,16) / 2^52`.
- **Commit, then reveal.** At round open the round publishes `serverSeedHash = SHA-256(serverSeed)` — the commitment. The seed alone determines the outcome, so publishing its fingerprint locks the outcome in before any bet is placed. At settlement the round publishes the server seed, the chain root and index, and the game-specific result values.
- **Domain-separated draw.** `message = "<beacon>:<label>:<index>"` (beacon may be empty — the leading colon is kept, e.g. `:crash:0`); `draw = first 13 hex chars of HMAC-SHA256(key = hex-decoded server-seed bytes, message as UTF-8)`; `r = int(draw,16) / 2^52`. The label (`crash`, `outcome`, `order`, …) names which decision is drawn, so revealing one draw never leaks another.

## Game families

- **Crash** (Footfall): `r` maps to the crash multiplier via the published house-edge curve.
- **Counting / CCTV** (Rush Hour, Snow Run, Duck River): `r` picks the winning market (Under / Range / Over / Exact) against the published probabilities; boundaries are then placed around the camera-measured count.
- **Classic** (Plinko, Snake, Rolling Dunes, Coin Flip, Fast Lane, Stairpong, Survivor, Fish Tank): `r` picks the winner (a weighted pick for the weighted games) or the full finishing order (a uniform pick over the possible orderings for the podium games).

## What is and isn't proven

Provable fairness proves, per round: the outcome was fixed by a seed committed before betting closed and reproduces from it; the seed is a genuine in-order link in a chain whose root was published in advance; and for weighted games the draw used the **published** probabilities — so a "40% option" occupies 40% of the draw space and hits 40% of the time, verifiable per round and statistically over many. It does **not** by itself prove the payout side of RTP: RTP = probability × payout, and provable fairness covers the probability (cryptographically enforced), while the payout multiplier is a separate published figure in the odds table. In short: the odds are cryptographically enforced every round and independently checkable; the payout side is a published number anyone can read.

## Verify

- **In-game** — every past round opens a fairness panel with the commitment, the revealed seed, and a live re-computation.
- **Round lookup** — https://support.marbles.xyz looks up any round by ID and shows the same fairness card with a one-click hand-off to the verifier.
- **Standalone verifier** — https://marbles-io.github.io/155-fairness-verifier/verify.html recomputes a round entirely client-side, via a deep link or pasted values. It ships golden test vectors that lock the algorithm across every implementation. Source: https://github.com/marbles-io/155-fairness-verifier

Docs: https://docs.155.io/provably-fair

---

# 155.io API (Endpoints We Provide)

All four endpoints below are authenticated by **IP whitelist** (your server's outbound IP), not by signature. The `X-Marbles-Signature` header is ignored on these requests.

## Get Games

Fetch available games for your catalogue. We recommend fetching at least once a day. Some operators prefer a single lobby game entry — we also provide a lobby game item for flexibility.

```
POST /game/games
```

### Request

```json
POST /game/games HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{ "operatorId": "abc123" }
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `operatorId` | string | Yes | Your operator identifier (provided by 155.io) |

### Success Response

```json
HTTP/1.1 200 OK
Content-Type: application/json

[
  {
    "id": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
    "type": "Game",
    "name": "Marble Plinko - Classic",
    "enabled": true,
    "assets": [
      { "type": "background", "extension": "webp", "url": "https://..." },
      { "type": "thumbnail", "extension": "webp", "url": "https://..." }
    ],
    "blockedCountries": ["AU", "AE", "GB", "US"],
    "items": ["uuid-1", "uuid-2"],
    "allowedBetTypes": ["PickWinner", "StraightForecast", "ReverseForecast"],
    "createdAt": "2024-12-13T04:39:03.306865Z",
    "updatedAt": "2025-01-29T13:52:47.42136175Z"
  }
]
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Unique game identifier (UUID). Use this when launching games. |
| `type` | string | Always `"Game"` |
| `name` | string | Display name of the game |
| `enabled` | boolean | Whether the game is currently available. Only show games where `enabled: true`. |
| `assets` | array | Game assets (`background`, `thumbnail`) for your catalogue |
| `blockedCountries` | array | ISO 3166-1 alpha-2 country codes where the game is blocked |
| `items` | array | UUIDs of selectable betting options in this game (marbles, ducks, outcomes, etc.) |
| `allowedBetTypes` | array | Bet types available for this game |
| `createdAt` | string | ISO 8601 creation timestamp |
| `updatedAt` | string | ISO 8601 last modified timestamp |

### Error Response

```json
HTTP/1.1 400 Bad Request

{ "error": "Invalid operator id", "details": "OperatorConfig with ID your-operator-id not found" }
```

| Status | HTTP | Description |
|--------|------|-------------|
| `Invalid operator id` | 400 | No operator exists for the provided `operatorId` |
| `Validation error` | 400 | Missing or invalid request fields |
| `Bad request` | 400 | Malformed JSON body |

## Get Game URL

Generate a game URL with a one-time login code for a player. Use in an iframe or redirect mobile players directly.

```
POST /game/game/url
```

### Request

```json
POST /game/game/url HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{
  "clientSessionId": "some-session-id",
  "clientPlayerId": "some-player-id",
  "operatorId": "your-operator-id",
  "partnerId": "my-casino",
  "gameId": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
  "username": "unique-username",
  "currency": "USD",
  "platform": "MOBILE",
  "displayName": "Player Display Name",
  "lobbyUrl": "https://mylobby.url",
  "depositUrl": "https://mydeposit.url",
  "language": "en",
  "country": "US"
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `clientSessionId` | string | Yes | Your session identifier for this player |
| `clientPlayerId` | string | Yes | Your unique player identifier |
| `operatorId` | string | Yes | Your operator identifier (provided by 155.io) |
| `partnerId` | string | Yes | Your chosen identifier for the website/casino (you define this) |
| `gameId` | string | Yes | Game UUID from `/game/games`, or the reserved lobby code `33d7ad7d-0d36-42cb-b818-79865aa73010` (same in test and production) to open the multi-game lobby. Never blank. |
| `username` | string | Yes | Unique username for the player |
| `currency` | string | Yes | ISO 4217 currency code |
| `platform` | string | No | `"DESKTOP"`, `"MOBILE"` or `"TABLET"` — case-sensitive; any other value rejects the launch with 400 {"error":"Validation error","details":"ValidationError: Platform 'X' does not exist"}; omitting the field is allowed |
| `displayName` | string | No | Non-unique display name shown in game |
| `lobbyUrl` | string | No | **Your** lobby — where the player is sent when they exit our games. Absolute URL including `https://`; blank or malformed values are dropped and no return link is shown. |
| `depositUrl` | string | No | URL for player to make deposits |
| `language` | string | No | ISO 639-1 language code (default: `en`) |
| `country` | string | No | ISO 3166-1 alpha-2 country code |

### Success Response

```json
HTTP/1.1 200 OK

{ "url": "https://game.marbles.xyz?otl=ABCDE...XYZ&country=US&language=en" }
```

### Fun Money Mode

Generate a demo link with fun money by omitting `clientSessionId` and `clientPlayerId` and setting `currency` to `XXX`. No callbacks will be sent to your server.

```json
{
  "operatorId": "your-operator-id",
  "partnerId": "my-casino",
  "gameId": "game-uuid",
  "username": "demo-player",
  "currency": "XXX",
  "platform": "DESKTOP"
}
```

## Get Round Details

Look up round details, outcome, race recording clip, and optionally a specific bet. Useful for resolving player support requests. Round data may take a few seconds to become available after settlement — if you get "round not found", retry after a short delay.

```
POST /game/round
```

### Request

```json
POST /game/round HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{
  "operatorID": "abc123",
  "gameID": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
  "roundID": "949223e9-2238-59f8-a16b-936ffc7fe3c5",
  "betID": "8a275342-bc24-5acd-b1f0-4bb9331ce010"
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `operatorID` | string | Yes | Your operator identifier (provided by 155.io) |
| `gameID` | string | Yes | Game UUID from `/game/games` |
| `roundID` | string | Yes | The round UUID to look up |
| `betID` | string | No | If provided, includes the specific bet details. Must belong to your integration and the specified round. |

### Success Response

```json
HTTP/1.1 200 OK

{
  "status": 200,
  "data": {
    "round": {
      "id": "949223e9-2238-59f8-a16b-936ffc7fe3c5",
      "gameId": "2469f711-2da6-46b7-8648-3313dfdc5bb5",
      "gameName": "Fish Tank",
      "outcomeFirstPlace": "item-uuid-1",
      "outcomeSecondPlace": "item-uuid-2",
      "outcomeThirdPlace": "item-uuid-3",
      "createdAt": "2026-03-20T12:00:00Z",
      "updatedAt": "2026-03-20T12:00:10Z"
    },
    "clipUrl": "https://clips.millicast.com/race-949223e9.mp4",
    "bet": {
      "id": "8a275342-bc24-5acd-b1f0-4bb9331ce010",
      "status": "won",
      "amount": 500,
      "payout": 2500,
      "currency": "USD",
      "betType": "PickWinner",
      "selection": "item-uuid-1",
      "externalPlayerID": "22893236",
      "username": "JohnDoe",
      "createdAt": "2026-03-20T11:59:50Z",
      "updatedAt": "2026-03-20T12:00:10Z"
    }
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `round.id` | string | Round UUID |
| `round.gameId` | string | Game UUID |
| `round.gameName` | string | Display name of the game |
| `round.outcomeFirstPlace` | string | Item UUID that finished first |
| `round.outcomeSecondPlace` | string | Item UUID that finished second |
| `round.outcomeThirdPlace` | string | Item UUID that finished third |
| `round.createdAt` | string | ISO 8601 timestamp when the round was created |
| `round.updatedAt` | string | ISO 8601 timestamp when the round was last updated |
| `clipUrl` | string | Direct link to race recording (may be empty if not yet available) |
| `bet.id` | string | Bet UUID (only if `betID` was provided) |
| `bet.status` | string | `pending`, `won`, `lost`, `voided`, or `cashed_out` (Footfall cash-outs only) |
| `bet.amount` | int64 | Integer at the currency's wire precision — the same scale as the `/bet` and `/win` callbacks (USD: $5.00 = 500000) |
| `bet.payout` | int64 | Actual payout: won → full winning payout; cashed_out → realised cash-out amount; pending/lost/voided → 0 |
| `bet.currency` | string | ISO 4217 currency code |
| `bet.betType` | string | Bet type |
| `bet.selection` | string | Comma-separated item UUIDs selected |
| `bet.externalPlayerID` | string | Your player identifier |
| `bet.username` | string | Player username |
| `bet.createdAt` | string | ISO 8601 timestamp when the bet was placed |
| `bet.updatedAt` | string | ISO 8601 timestamp when the bet was last updated |

You can only view bets belonging to your integration.

### Error Responses

```json
HTTP/1.1 404 Not Found

{ "error": "Round not found", "details": "round with ID 949223e9-... not found" }
```

| Status | HTTP | Description |
|--------|------|-------------|
| Round not found | 404 | No round exists for the given ID and game, or the round is still processing |
| Bet not found | 404 | No bet exists for the given ID, or the bet does not belong to your integration |
| Invalid Integration IP | 400 | Request originated from an unrecognized IP address |
| Validation error | 400 | Missing or invalid request parameters |

## Get Player Bets

Look up bet history for a specific player. Results are scoped to your integration.

```
POST /game/bets
```

### Request

```json
POST /game/bets HTTP/1.1
Host: api.marbles.xyz
Content-Type: application/json

{
  "operatorID": "abc123",
  "externalPlayerID": "22893236",
  "from": "2026-03-19T00:00:00Z",
  "to": "2026-03-20T00:00:00Z",
  "limit": 25
}
```

| Parameter | Type | Required | Description |
|-----------|------|----------|-------------|
| `operatorID` | string | Yes | Your operator identifier (provided by 155.io) |
| `externalPlayerID` | string | Yes | Your player identifier (`clientPlayerId` used when launching the game) |
| `from` | string | No | ISO 8601 timestamp — only return bets after this time |
| `to` | string | No | ISO 8601 timestamp — only return bets before this time |
| `limit` | integer | No | Max bets to return. Default: 25, max: 100 |

### Success Response

```json
HTTP/1.1 200 OK

{
  "status": 200,
  "data": {
    "bets": [
      {
        "id": "8a275342-bc24-5acd-b1f0-4bb9331ce010",
        "status": "won",
        "amount": 500,
        "payout": 2500,
        "currency": "USD",
        "betType": "PickWinner",
        "gameName": "Fish Tank",
        "roundId": "949223e9-2238-59f8-a16b-936ffc7fe3c5",
        "createdAt": "2026-03-20T11:59:50Z",
        "updatedAt": "2026-03-20T12:00:10Z"
      }
    ]
  }
}
```

| Field | Type | Description |
|-------|------|-------------|
| `id` | string | Bet UUID |
| `status` | string | `pending`, `won`, `lost`, `voided`, or `cashed_out` (Footfall cash-outs only) |
| `amount` | int64 | Integer at the currency's wire precision — the same scale as the `/bet` and `/win` callbacks (USD: $5.00 = 500000) |
| `payout` | int64 | Actual payout: won → full winning payout; cashed_out → realised cash-out amount; pending/lost/voided → 0 |
| `currency` | string | ISO 4217 currency code |
| `betType` | string | Bet type |
| `gameName` | string | Display name of the game |
| `roundId` | string | Round UUID — use with `/game/round` for full details and race clip |
| `createdAt` | string | ISO 8601 timestamp when the bet was placed |
| `updatedAt` | string | ISO 8601 timestamp when the bet was last updated |

Results are sorted by `createdAt` descending (newest first).

### Error Responses

```json
HTTP/1.1 400 Bad Request

{ "error": "Validation error", "details": "Property 'externalPlayerID' is required" }
```

| Status | HTTP | Description |
|--------|------|-------------|
| Invalid Integration IP | 400 | Request originated from an unrecognized IP address |
| Validation error | 400 | Missing or invalid request parameters |
| Invalid date format | 400 | `from` or `to` is not a valid RFC3339 timestamp |

---

## Round Lookup Page

A shareable web page for viewing round details, race recordings, and bet information. Useful for support — look up a round or share the link directly with the player.

**Interactive form:** https://support.marbles.xyz — select a game, enter round ID, or use a Bet Round ID from your aggregator (e.g. Hub88).

**Direct URL:**
```
https://support.marbles.xyz/lookup?gameId={gameId}&roundId={roundId}&betId={betId}
```

**Bet Round ID lookup** (for aggregators like Hub88 — resolves internal round automatically):
```
https://support.marbles.xyz/lookup?betRoundId={betRoundId}
```

| Parameter | Required | Description |
|-----------|----------|-------------|
| `gameId` | Yes* | Game UUID |
| `roundId` | Yes* | Internal round UUID |
| `betId` | No | Shows bet details alongside the round |
| `betRoundId` | No | Round ID from aggregator (e.g. Hub88). Resolves gameId/roundId/betId automatically. |

*Not required when using `betRoundId`.

Shows: race recording video, outcome with marble names/images, round metadata, and (if bet included) bet ID, bet round ID, timestamp, status, currency, amount, payout, bet type, and selection. Publicly accessible — secured by requiring UUIDs. Race recordings available for ~7 days.

---

# Iframe Events (postMessage API)

When embedding the game widget in an iframe, you can communicate with it using `postMessage`.

## Message Format

```typescript
interface PostMessageEnvelope {
  source: 'marbles-game-widget' | 'marbles-operator'
  type: string
  version: 1
  payload: Record<string, unknown>
  timestamp: number
  requestId?: string
}
```

Messages from the game widget use `source: 'marbles-game-widget'`; messages you send must use `source: 'marbles-operator'`.

## Sending Commands

```javascript
function sendCommand(iframe, type, payload = {}) {
  iframe.contentWindow?.postMessage({
    source: 'marbles-operator',
    type,
    version: 1,
    payload,
    timestamp: Date.now()
  }, '*')
}

// Example: refresh balance after deposit
sendCommand(iframe, 'refresh-balance')
```

### Available Commands

| Command | Payload | Description |
|---------|---------|-------------|
| `refresh-balance` | `{}` | Force re-fetch of player balance (debounced to max once per 2s) |
| `mute-audio` | `{ muted: boolean }` | Mute or unmute game audio |
| `set-audio-volume` | `{ volume: number }` | Set master volume (0.0 to 1.0) |
| `open-game-history` | `{}` | Open the bet history sidebar |
| `close-panels` | `{}` | Close all open panels and sidebars |
| `get-state` | `{}` | Request game state snapshot (responds with `state-snapshot` event) |

All commands are rate-limited to **30 per second per command type** (and `refresh-balance` is additionally debounced to once per 2s).

## Listening for Events

```javascript
window.addEventListener('message', (event) => {
  if (event.data?.source !== 'marbles-game-widget') return
  const { type, payload } = event.data
  // Handle events...
})
```

### Game Lifecycle Events

| Event | Payload | When |
|-------|---------|------|
| `game:loaded` | `{ gameId, gameType, playerId }` | Game widget is ready |
| `game:ready` | `{ gameId, roundId }` | First round available for betting |
| `game:error` | `{ code, message }` | Fatal error occurred |
| `session:expired` | `{}` | Player session expired |

### Round Lifecycle Events

| Event | Payload | When |
|-------|---------|------|
| `round:betting-open` | `{ roundId, gameId }` | Betting window open |
| `round:betting-closed` | `{ roundId, gameId }` | Betting closed, race starting |
| `round:started` | `{ roundId, gameId, totalBetAmount?, currency? }` | Race animation begun. Includes player's total bet if active |
| `round:ended` | `{ roundId, gameId, totalBetAmount?, totalWinAmount?, currency?, crashMultiplier? }` | Race finished. Includes bet/win totals |

### Bet Events

| Event | Payload | When |
|-------|---------|------|
| `bet:placed` | `{ betId, amount, currency, betType }` | Bet accepted |
| `bet:rejected` | `{ reason, amount, currency }` | Bet rejected |
| `bet:result` | `{ betId, status, payout?, currency, multiplier? }` | Bet outcome determined |
| `cashout:completed` | `{ betId, multiplier, payout, currency }` | Player cashed out (crash games) |

### Balance Events

| Event | Payload | When |
|-------|---------|------|
| `balance:changed` | `{ amount, currency }` | Balance updated |
| `balance:insufficient` | `{ requiredAmount?, currentBalance, currency }` | Insufficient balance for bet |

### Player State Events

| Event | Payload | When |
|-------|---------|------|
| `player:idle-warning` | `{ gameId }` | Idle warning shown |
| `player:idle-paused` | `{ gameId }` | Game stream paused due to inactivity |
| `state-snapshot` | `{ isLoaded, playerId?, gameId?, balance?, isMuted, hasActiveBet }` | Response to `get-state` |

Notes:
- The `bet:result` `status` field is one of: `won`, `lost`, `cashed_out`, or `voided`.
- All `amount` and `payout` values in events are decimal numbers in the player's currency (e.g. `5.00` for $5).
- Messages with an unrecognized `type` are silently ignored (forward compatible). The `version` field allows future protocol changes.
- The widget works without postMessage — these events are optional enhancements.

---

# Operator API (Endpoints You Implement)

These endpoints must be implemented on your server. 155.io calls them to manage player balances and transactions.

**Important rules:**
- All responses must use **HTTP 200**, including error responses. Non-200 HTTP status codes trigger retries or rollbacks on our side.
- All callbacks are signed with `X-Marbles-Signature` — **verify** them against 155.io's public key. Sign your own responses too (forward-compatible; not currently verified).
- All endpoints must be idempotent.
- Currently, it's always 1 bet per round per player.
- All fields listed below are always present in our requests, except freebet fields (`isFree`, `rewardUuid`) which are only included for freebet transactions.

## POST /balance

Called to retrieve the player's current balance. We never store player balances. The balance must be in the correct currency for the player's session (identified by `clientSessionId`).

### Request

```json
POST /balance HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "clientSessionId": "06mnrpyv2qd9jbwhoniyimxsy",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "requestId": "4ec4a295-cd84-46df-b225-4b72bd84892c",
  "timestamp": "2025-06-15T14:30:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `clientSessionId` | string | The player's session identifier |
| `clientPlayerId` | string | The player's unique identifier |
| `requestId` | string | Unique request identifier (UUID) |
| `timestamp` | string | ISO 8601 UTC timestamp of when the request was created |

### Success Response

```json
HTTP/1.1 200 OK
X-Marbles-Signature: <signature>

{
  "status": "SUCCESS",
  "requestId": "4ec4a295-cd84-46df-b225-4b72bd84892c",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}
```

| Field | Type | Description |
|-------|------|-------------|
| `status` | string | `"SUCCESS"` |
| `requestId` | string | Echo back the request ID |
| `clientPlayerId` | string | Echo back the player ID |
| `currency` | string | ISO 4217 currency code |
| `balance` | int64 | Balance with the currency's precision ($10.00 = 1000000 at 5-digit) |

### Error Statuses

| Status | Description |
|--------|-------------|
| `UNKNOWN_ERROR` | Any operator-side failure — including an expired/invalid session or an unknown player. 155 has no dedicated session-state status on the wallet callbacks; any non-`SUCCESS` value is treated as `UNKNOWN_ERROR`. |

## POST /bet

Called when a player places a bet. Deduct the bet amount from the player's balance.

### Request

```json
POST /bet HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "transactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "clientSessionId": "0k3cz83bb3h2vn53ocnc7pxw9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "roundId": "17cc81fd-df13-4ca4-857d-de0f766dc372",
  "gameId": "f1c0b104-f29d-44a9-ae93-e8afcbe3feb9",
  "amount": 1000000,
  "currency": "USD",
  "meta": {
    "betType": "PickWinner",
    "selection": ["item-uuid-1", "item-uuid-2"]
  },
  "timestamp": "2025-06-15T14:30:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `requestId` | string | Unique request identifier (UUID) |
| `transactionId` | string | Unique transaction identifier for this bet |
| `clientSessionId` | string | The player's session identifier |
| `clientPlayerId` | string | The player's unique identifier |
| `roundId` | string | Per-bet round reference — unique for each bet, even when several bets belong to the same game round. Grouping by it groups BETS, not rounds |
| `gameId` | string | The game identifier |
| `amount` | int64 | Bet amount with the currency's precision |
| `currency` | string | ISO 4217 currency code |
| `isFree` | boolean | Only present for freebets. `true` if this is a freebet. |
| `rewardUuid` | string | Only present for freebets. Your `clientRewardId` from the grant. |
| `meta` | object | Bet metadata |
| `meta.betType` | string | Type of bet placed |
| `meta.selection` | array | Selected items for the bet |
| `timestamp` | string | ISO 8601 UTC timestamp of when the request was created |

### Freebet Request

For freebets, `amount` is `0`, `isFree` is `true`, and `rewardUuid` identifies the promotion. Do not deduct any balance.

```json
{
  "amount": 0,
  "currency": "USD",
  "isFree": true,
  "rewardUuid": "promo-winter-2025-001"
}
```

### Success Response

```json
HTTP/1.1 200 OK
X-Marbles-Signature: <signature>

{
  "status": "SUCCESS",
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}
```

### Error Statuses

| Status | Description |
|--------|-------------|
| `INSUFFICIENT_BALANCE_ERROR` | Player does not have enough balance |
| `DUPLICATE_TRANSACTION_ERROR` | Transaction ID already exists with different payload |
| `BONUS_ERROR` | Bet does not pass bonus rules |
| `BET_LIMIT_REACHED_ERROR` | Player has reached their betting limit |
| `UNKNOWN_ERROR` | Bet could not be registered |

**NOT status values:** `ROUND_CLOSED` is a 155-side internal error (code 4006), never returned by your wallet. `BET_LIMIT_REACHED` is a common typo — the real value is `BET_LIMIT_REACHED_ERROR` (the `_ERROR` suffix is required). Aggregator integrations (Hub88) use a different status set (`RS_OK`, …); the enum above is for direct integrations only.

## POST /win

Called to register the result of a bet. For wins, add the amount to the player's balance. For losses, the amount is `0`.

### Request

```json
POST /win HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "transactionId": "9ea48131-3a0f-4067-94d0-3212e7e25abb",
  "referenceTransactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "clientSessionId": "0k3cz83bb3h2vn53ocnc7pxw9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "roundId": "17cc81fd-df13-4ca4-857d-de0f766dc372",
  "gameId": "f1c0b104-f29d-44a9-ae93-e8afcbe3feb9",
  "amount": 1000000,
  "currency": "USD",
  "roundClosed": true,
  "timestamp": "2025-06-15T14:30:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `requestId` | string | Unique request identifier (UUID) |
| `transactionId` | string | Unique transaction identifier for this win |
| `referenceTransactionId` | string | The original bet transaction ID |
| `clientSessionId` | string | The player's session identifier |
| `clientPlayerId` | string | The player's unique identifier |
| `roundId` | string | Per-bet round reference — unique for each bet, even when several bets belong to the same game round. Grouping by it groups BETS, not rounds |
| `gameId` | string | The game identifier |
| `amount` | int64 | Win amount (0 for losses) with the currency's precision |
| `currency` | string | ISO 4217 currency code |
| `isFree` | boolean | Only present for freebets. `true` if the original bet was a freebet. |
| `rewardUuid` | string | Only present for freebets. The `clientRewardId` from the original grant. |
| `roundClosed` | boolean | `true` if this is the final transaction for the round |
| `timestamp` | string | ISO 8601 UTC timestamp of when the request was created |

### Win vs Loss

- **Win**: `amount > 0` — Add this amount to the player's balance
- **Loss**: `amount = 0` — No balance change needed (bet was already deducted)

### Freebet Wins

When `isFree: true` and `amount > 0`, credit the amount as real money. Freebet winnings are real money.

### Round Lifecycle

- `roundClosed: true` — This is the final transaction. No more transactions for this round.
- `roundClosed: false` — More transactions may follow (rare, for future multi-bet support).

**`/win` is terminal:** no `/rollback` will be sent for a bet after its `/win` callback (including the `amount: 0` loss form).

### Success Response

```json
HTTP/1.1 200 OK
X-Marbles-Signature: <signature>

{
  "status": "SUCCESS",
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}
```

### Error Statuses

| Status | Description |
|--------|-------------|
| `DUPLICATE_TRANSACTION_ERROR` | Transaction ID already exists with different payload |
| `UNKNOWN_ERROR` | Win could not be registered |

## POST /rollback

Called when a bet should be voided (round cancelled). Refund the bet amount to the player's balance. We only send bet rollbacks — there are no win rollbacks.

### When This Fires

`/rollback` only fires **before** `/win` has been sent for a given bet. Once `/win` is delivered (any `amount`, including the `amount: 0` loss form), the round is terminal — no `/rollback` will follow.

Triggers:
- The round was cancelled before settlement
- The player's bet timed out during chip placement
- `/bet` was acknowledged, but a downstream error required reversing the debit before the round settled

To reverse a granted-but-unused freebet, use `POST /game/free-bets/rewards/cancel` — **not** `/rollback`.

### Request

```json
POST /rollback HTTP/1.1
Host: your.game.api
X-Marbles-Signature: <signature>
Content-Type: application/json

{
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "transactionId": "9ea48131-3a0f-4067-94d0-3212e7e25abb",
  "referenceTransactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "clientSessionId": "0k3cz83bb3h2vn53ocnc7pxw9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "roundId": "17cc81fd-df13-4ca4-857d-de0f766dc372",
  "gameId": "f1c0b104-f29d-44a9-ae93-e8afcbe3feb9",
  "roundClosed": true,
  "timestamp": "2025-06-15T14:30:00.000Z"
}
```

| Field | Type | Description |
|-------|------|-------------|
| `requestId` | string | Unique request identifier (UUID) |
| `transactionId` | string | Unique transaction identifier for this rollback |
| `referenceTransactionId` | string | The original bet transaction ID being rolled back |
| `clientSessionId` | string | The player's session identifier |
| `clientPlayerId` | string | The player's unique identifier |
| `roundId` | string | Per-bet round reference — unique for each bet, even when several bets belong to the same game round. Grouping by it groups BETS, not rounds |
| `gameId` | string | The game identifier |
| `isFree` | boolean | Only present for freebets. `true` if the original bet was a freebet. |
| `rewardUuid` | string | Only present for freebets. The `clientRewardId` from the original grant. |
| `roundClosed` | boolean | `true` if this is the final transaction for the round |
| `timestamp` | string | ISO 8601 UTC timestamp of when the request was created |

### Freebet Rollbacks

When `isFree: true`, no balance refund is needed (the original freebet had `amount: 0`). Mark the freebet as cancelled in your records.

### Success Response

```json
HTTP/1.1 200 OK
X-Marbles-Signature: <signature>

{
  "status": "SUCCESS",
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "clientPlayerId": "02mnrpyv2qd9jbwhoniyimxsy",
  "currency": "USD",
  "balance": 1000000
}
```

### Error Statuses

| Status | Description |
|--------|-------------|
| `DUPLICATE_TRANSACTION_ERROR` | Transaction ID already exists with different payload |
| `UNKNOWN_ERROR` | Rollback could not be processed |

---

# Idempotency Details

Our system can send idempotent retries for `/bet`, `/win` and `/rollback`. On `/bet` and `/win` the `transactionId` stays the same across retries (only `requestId` changes) and is your dedupe key. On `/rollback` the `transactionId` is NOT stable between attempts — dedupe rollbacks on **`referenceTransactionId`** (the bet being refunded, constant across every attempt); deduping rollbacks on `transactionId` refunds the same stake once per attempt.

Expected behavior (note the asymmetry between `/bet` and `/win` / `/rollback`):
- **`/bet` replay** (same `transactionId`) — return **`DUPLICATE_TRANSACTION_ERROR`** with **no balance change** (do not debit the stake again). A replayed `/bet` is a duplicate, not a new bet.
- **`/win` replay** (same `transactionId`) and **`/rollback` replay** (same `referenceTransactionId`) — return the original **`SUCCESS`** result with the current balance (idempotent no-op; don't credit/rollback again). `DUPLICATE_TRANSACTION_ERROR` is also accepted as applied on both — but only for a transaction you genuinely already applied.

---

# Transaction Flow

## Normal Round

1. Player places a bet → 155.io calls `POST /bet`
2. Round completes → 155.io calls `POST /win` (amount > 0 for win, amount = 0 for loss)
3. `roundClosed: true` on the final transaction

## Cancelled Round

1. Player places a bet → 155.io calls `POST /bet`
2. Round is cancelled → 155.io calls `POST /rollback` (refund the original bet)
3. `roundClosed: true` on the rollback

## Freebet Round

1. Player uses a freebet → 155.io calls `POST /bet` with `amount: 0`, `isFree: true`
2. Round completes → 155.io calls `POST /win` with `isFree: true` (if won, `amount` is real money to credit)

---

# Bet Types

| Bet Type | Description | Selection Size |
|----------|-------------|----------------|
| `PickWinner` | Pick one or more items — win if any comes first | 1+ items |
| `StraightForecast` | Pick 2 items to finish 1st and 2nd in exact order | 2 items |
| `ReverseForecast` | Pick 2 items to finish 1st and 2nd in any order | 2 items |
| `Tricast` | Pick 3 items to finish 1st, 2nd, 3rd in exact order | 3 items |
| `CombinationTricast` | Pick 3 items to finish in top 3 in any order | 3 items |

Not all games support all bet types. Check the `allowedBetTypes` field in the Get Games response. The chosen type goes in `meta.betType` and the picks in `meta.selection` on `/bet`.

---

# Liability

Bet limits are calculated dynamically, not configured per-currency. A base min/max is defined in USD, then multiplied by the currency's exchange rate. For example: USD min $1.00 / max $10,000; BRL min R$7.00 / max R$70,000 (multiplier ~7.0). Crypto units (mBTC, mETH, mLTC) shift the decimal accordingly. Limits adjust automatically as exchange rates change.

The liability amount further caps the maximum bet per transaction:

```
Max Bet = Liability Amount / Payout Multiplier × Currency Multiplier
```

Example with $1,000,000 liability:

| Bet Type | Multiplier | Max Bet |
|----------|------------|---------|
| Pick 1 of 8 marbles | 7.55x | ~$132,450 |
| Pick 3 exact order | 316.98x | ~$3,155 |

The actual max bet a player sees is the lower of the currency-based max and the liability-based max.

---

# Game Payouts & RTP

Max-payout multipliers and RTP for every game, pulled from the live production game configuration. **Max Payout** is the multiplier per selection. **RTP** is the base return; **Effective RTP** additionally includes the average Lightning Round contribution, quoted at player level 0 — Streak Multipliers, Player Levels and Daily Check-in add further on top where a game offers them (Streak Multipliers are not currently enabled on any live game). A legendary Lightning Round multiplies the win by **5×**, so the true ceiling is the **Max (⚡ Lightning)** column.

Use the **Game code** (race configuration ID) as the `gameId` when calling Get Game URL. Each game has a separate production and staging code; staging mirrors production for pricing. Full CSV: https://docs.155.io/games-payouts.csv

## Game codes

| Game | Production code | Staging code |
|---|---|---|
| Coin Flip | `e4c85f24-3703-46bc-933a-b9e54d3aaecb` | `d20ba3f9-4569-498a-8c00-0c9912bc9390` |
| Duck River | `76be9102-f4d5-499e-adef-7a6f6848ccf2` | `3a4b54ae-7571-4211-bda2-9eb5f5df36c3` |
| Fast Lane | `3f5d6fa5-346b-4783-be3c-8e40ef288759` | `d67ac242-f94c-451a-a724-558c1d609325` |
| Fish Tank | `a8c81652-cbd4-4b5d-94cd-5585715a6133` | `27e2135b-75ee-4872-8b29-7f96f310d239` |
| Footfall | `f42795eb-a884-448f-bb42-6bf5a2fb3e33` | `f42795eb-a884-448f-bb42-6bf5a2fb3e33` |
| Marble Plinko | `2469f711-2da6-46b7-8648-3313dfdc5bb5` | `64f65d3b-3c9b-4a57-96de-6bed459ab518` |
| Rolling Dunes | `27948be8-eae7-4276-823f-24c79247a002` | `0e4b84e0-13aa-4782-b80e-d539d65fd91f` |
| Rush Hour | `e30b58a2-653f-492a-81f1-8f1769c4d31c` | `3d80d6ab-0825-4e3a-8b1d-91ff0631e3fe` |
| Snake | `e1b186ee-b609-40e9-9949-ee20b65ffdaf` | `ad3cfb94-180e-4669-bc85-e2a29753f490` |
| Snow Run | `584b1f3d-8338-4f73-af6b-0b9ac74275eb` | `7f074d19-cfa9-4e94-96bb-b3d53a5dea67` |
| Stairpong | `f38c69e6-f784-4b2d-8791-309432b0eb39` | `023f1d90-746c-4d10-b7e3-39d579f59a1f` |
| Survivor | `b07d5391-09c7-403d-9695-3702503f9f0c` | `6011911c-8f07-44c5-80d8-d109b015b1e8` |

### Game lobby

Opening our lobby instead of a single game is a launch like any other — pass the reserved lobby code as `gameId`. Unlike the games above it is the **same code in production and staging**, and like every launch it can never be left blank.

| Entry | Code (production & staging) |
|---|---|
| Lobby | `33d7ad7d-0d36-42cb-b818-79865aa73010` |

The player lands in our multi-game lobby and picks a game from there. The lobby has no rounds, bets or RTP of its own, so it is not listed in the tables above — the game the player picks is what carries the pricing.

### Retired game IDs

If you have an older game ID cached, check here — retired IDs are disabled (`Enabled: false`) and launching one returns no game. Update your library to the replacement.

| Retired game | Retired ID | Use instead | New ID |
|---|---|---|---|
| Duck Racing | `e47714d3-2cb3-409c-acdd-56b22dad9f51` | Duck River | `76be9102-f4d5-499e-adef-7a6f6848ccf2` |

## RTP & max payouts

| Game | Base RTP | Effective RTP | Max | Max (⚡ Lightning) |
|---|---|---|---|---|
| Coin Flip | 90.91% | 90.91% | 1.82x | — |
| Duck River | 90% | 90–92.16% | 36x | 90x |
| Fast Lane | 91.74% | 92.95% | 9.17x | 45.85x |
| Fish Tank | 90.09% | 91.1–92.12% | 50x | 250x |
| Footfall | 94% | 94% | Uncapped | — |
| Marble Plinko | 85–91.74% | 87.81–93.25% | 285.6x | 1428x |
| Rolling Dunes | 86–94.34% | 90.26–95.9% | 288.96x | 1444.8x |
| Rush Hour | 90% | 90–92.16% | 36x | 90x |
| Snake | 88–94.34% | 91.87–96.42% | 26.4x | 132x |
| Snow Run | 90% | 90–92.16% | 36x | 90x |
| Stairpong | 89.62% | 90.62–91.64% | 95x | 475x |
| Survivor | 94.34% | 95.39–96.47% | 15.09x | 75.45x |

## Per-game selection payouts

### Coin Flip
| Selection | Max Payout | RTP |
|---|---|---|
| Tail | 1.82x | 90.91% |
| Head | 1.82x | 90.91% |

### Duck River
**Race Winner:** Range 2.25x · Under 3x · Over 3.6x · Exact 18x (all 90% RTP)
**Exact Boundary:** Exact Low 36x · Exact High 36x (90%)

### Fast Lane
All 10 cars (Honda CR-X, Shelby Cobra, HW Wrap Speeder, Honda Civic, Mad Splash, Corvette Gasser, Time Attaxi, Audi R8 Spyder, The Nash, The Haulinator): 9.17x at 91.74% RTP.

### Fish Tank
| Selection | Max Payout | RTP |
|---|---|---|
| Right | 2.26x | 90.09% |
| Left | 2.26x | 90.09% |
| Chest | 8x | 90.09% |
| White | 12.36x | 90.09% |
| Red | 50x | 90.09% |

### Footfall
Crash-style cash-out game — no fixed selections. The multiplier climbs from 1.00x with no ceiling; cash out before a pedestrian walks into frame to win stake × the cash-out multiplier. 94% RTP (base and effective). No Lightning Rounds, streak multipliers or free bets.

### Marble Plinko
Colours (Orange, Black, Blue, White, Red, Green, Yellow, Sky): 7.34x at 91.74% RTP.
**Side bets:** Straight Forecast 47.6x · Reverse Forecast 23.8x · Tricast 285.6x · Combination Tricast 47.6x (all 85% RTP)

### Rolling Dunes
Colours (Tiger, Jade, Beachball, Ocean, Midnight, Inferno, Neptune, Bee): 7.55x at 94.34% RTP.
**Side bets:** Straight Forecast 49.28x (88%) · Reverse Forecast 25.2x (90%) · Tricast 288.96x (86%) · Combination Tricast 49.28x (88%)

### Rush Hour
**Race Winner:** Range 2.25x · Under 3x · Over 3.6x · Exact 18x (90%)
**Exact Boundary:** Exact Low 36x · Exact High 36x (90%)

### Snake
Colours (Capri, Inferno, White, Blue, Bee, Green): 5.66x at 94.34% RTP.
**Side bets:** Straight Forecast 26.4x (88%) · Reverse Forecast 13.5x (90%)

### Snow Run
**Race Winner:** Range 2.25x · Under 3x · Over 3.6x · Exact 18x (90%)
**Exact Boundary:** Exact Low 36x · Exact High 36x (90%)

### Stairpong
| Selection | Max Payout | RTP |
|---|---|---|
| White | 1.9x | 89.62% |
| Orange | 2.38x | 89.62% |
| Green | 9.5x | 89.62% |
| Blue | 19x | 89.62% |
| Pink | 95x | 89.62% |

### Survivor
| Selection | Max Payout | RTP |
|---|---|---|
| Neptune | 2.52x | 94.34% |
| Bee | 3.77x | 94.34% |
| Inferno | 5.03x | 94.34% |
| Green | 7.55x | 94.34% |
| White | 15.09x | 94.34% |

---

# Freebets & Rewards

Freebets let operators grant promotional free bets. When a player uses a freebet, no real money is deducted, but any winnings are credited as real money. Two integration paths: **Direct Integration** (155.io API) and **Hub88** (Hub88's native freebet API).

## Direct Integration — Granting Freebets

Prerequisites: free bets are enabled by default for new operators. The player must have launched at least one game first — the grant endpoint does not create players; granting to an unknown player returns `404` `{"error": "Player not found"}`.

```
POST /game/free-bets/rewards
```

```json
{
  "clientPlayerId": "player-123",
  "operatorId": "your-operator-id",
  "clientRewardId": "promo-winter-2025-001",
  "amount": 500000,
  "currency": "USD",
  "quantity": 3,
  "expiresAt": "2025-12-31T23:59:59Z",
  "gameIds": ["game-uuid-1", "game-uuid-2"]
}
```

| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `clientPlayerId` | string | Yes | Player's unique identifier |
| `operatorId` | string | Yes | Your operator ID |
| `clientRewardId` | string | Yes | Your unique identifier for tracking this reward |
| `amount` | integer | Yes | Value per freebet as an integer at the currency's wire precision (USD: 500000 = $5.00) — the same scale as the `/bet` callback `amount`; an under-scaled grant (e.g. cents) makes every free bet unusable |
| `currency` | string | Yes | ISO 4217 currency code |
| `quantity` | integer | No | Number of freebets (default: 1, max: 100) |
| `expiresAt` | string | No | ISO 8601 expiration datetime |
| `startTime` | string | No | ISO 8601 datetime when freebets become available (scheduled campaigns) |
| `gameIds` | array | No | Restrict to specific games (omit for all games) |

Authentication: same `X-Marbles-Signature` / IP-whitelist model as other inbound endpoints. Each `clientRewardId` is tied to one player — for 100 players, make 100 API calls. The `clientRewardId` is returned in bet/win/rollback transactions as `rewardUuid`.

### Grant Success Response

```json
HTTP/1.1 201 Created

{
  "reward": {
    "type": "Reward",
    "clientRewardId": "promo-winter-2025-001",
    "clientPlayerId": "player-123",
    "operatorId": "your-operator-id",
    "amount": 500000,
    "currency": "USD",
    "quantity": 3,
    "applicableGames": ["game-uuid-1", "game-uuid-2"],
    "meta": {},
    "startTime": null,
    "endTime": "2025-12-31T23:59:59Z",
    "status": "granted",
    "createdAt": "2025-06-15T14:30:00Z"
  },
  "freeBets": [
    { "id": "fb-001", "amount": 500000, "currency": "USD", "status": "claimable", "createdAt": "...", "expiresAt": "...", "applicableGames": ["game-uuid-1"] }
  ]
}
```

The reward `status` is `"granted"` when immediately available, or `"scheduled"` if `startTime` is in the future.

### Grant Error Responses

| HTTP | Error Code | Description |
|------|------------|-------------|
| 400 | `Validation error` | Missing or invalid request fields |
| 400 | `Bad request` | Malformed JSON body |
| 400 | `Invalid operator id` | Unknown operatorId |
| 404 | `Player not found` | Player does not exist (never launched a game) |
| 409 | `REWARD_ALREADY_EXISTS` | A reward with this `clientRewardId` already exists (code 9003) |
| 500 | `Internal server error` | Unexpected failure. `details` reading `free bets are not enabled for operator <id>` means the feature is toggled off — contact 155.io |

### Freebet Statuses

| Status | Description |
|--------|-------------|
| `claimable` | Available for the player to use |
| `claimed` | Player has selected but not yet placed a bet |
| `used` | Freebet was used to place a bet |
| `expired` | Freebet expired before being used |
| `cancelled` | Freebet was cancelled by operator |

### Cancelling Freebets

```
POST /game/free-bets/rewards/cancel
```

```json
{
  "clientRewardId": "promo-winter-2025-001",
  "operatorId": "your-operator-id",
  "reason": "Player requested cancellation"
}
```

Returns the reward (`status: "cancelled"`, with `cancelledAt`) and the cancelled `freeBets`.

Rules:
- Only freebets with status `claimable` or `claimed` can be cancelled
- If **any** freebet from the reward has been `used`, the entire reward cannot be cancelled
- Cancellation is per-reward (per-player), not campaign-wide
- Scheduled rewards (future `startTime`) can be cancelled before freebets are generated — the reward is transitioned to `cancelled` and a `REWARD_NOT_STARTED` response is returned with no `freeBets` payload

#### Cancel Error Responses

| HTTP | Error Code | Code | Description |
|------|------------|------|-------------|
| 404 | `REWARD_NOT_FOUND` | 9001 | No reward exists for the provided `clientRewardId` |
| 409 | `REWARD_CANNOT_BE_CANCELLED` | 9006 | At least one freebet has been `used` — reward cannot be cancelled |
| 409 | `REWARD_NOT_STARTED` | 9007 | Scheduled reward; freebets not yet generated. Transitioned to `cancelled` — treat as a successful cancellation |
| 500 | `Internal server error` | — | Unexpected failure |

### Scheduling Freebets

Use `startTime` to schedule freebets for a future date. Freebets are created immediately but only become `claimable` after `startTime`; players won't see them until then. You can cancel scheduled freebets before they become active.

### Receiving Freebet Transactions

You receive modified bet/win/rollback callbacks:
- **Bet:** `amount: 0`, `isFree: true`, `rewardUuid: "<your clientRewardId>"`
- **Win/Loss:** `isFree: true`; win `amount` is real money to credit, loss `amount` is `0`
- **Rollback:** `isFree: true`, no amount to refund. Fires **only before** the freebet's `/win` (win or loss) callback. To reverse a granted-but-unused reward, use the cancel endpoint, not `/rollback`.

### Direct Integration Flow

1. You grant a freebet via the API
2. Player launches a game — freebets are claimed automatically and announced with a banner
3. Player places a bet — the oldest unused freebet applies automatically and the stake locks to its amount (no manual activation; in chip-placement games each staked option takes the next freebet, so several can be in play in one round; Coin Flip uses one at a time)
4. You receive `/bet` with `isFree: true`, `amount: 0`
5. Round completes — if player wins, you receive `/win` with `isFree: true`, `amount: <winnings>`
6. Credit winnings as real money

A freebet is only usable if its value falls within the operator's min/max bet limits and matches the player's currency.

## Hub88 Integration

Hub88 operators use Hub88's native freebet API and receive transactions through Hub88's standard integration.

1. **Request prepaid templates** — contact 155.io with your Hub88 `operator_id`, bet value, quantity, currencies, and game scope. You receive `prepaid_uuid`(s). (E.g. bet value $2 × quantity 5 = 5 free bets worth $2 each.)
2. **Create rewards via Hub88:**

```
POST /operator/generic/v2/freebet/rewards/create
```

```json
{
  "operator_id": "your-operator-id",
  "user": "player-123",
  "prepaid_uuid": "uuid-from-step-1",
  "start_time": "2025-01-01T00:00:00Z",
  "end_time": "2025-12-31T23:59:59Z"
}
```

Always set `start_time` and `end_time` — otherwise rewards auto-expire after a few weeks. See Hub88's Freebets API docs for full details.

---

# Supported Currencies

(As of August 2026.) Send the `Code` value as the `currency` parameter; units are display labels only.

## Fiat (5-digit precision)

AED, ALL, ARS, AUD, AZN, BAM, BDT, BHD, BOB, BRL, BYN, CAD, CHF, CLP, CNY, COP, CRC, CUP, CZK, DKK, DOP, DZD, EGP, ETB, EUR, GBP, GEL, GHS, GTQ, HKD, HNL, HTG, HUF, IDR, ILS, INR, IQD, IRR, ISK, JPY, KES, KGS, KRW, KWD, KZT, LKR, MAD, MKD, MMK, MXN, MYR, MZN, NGN, NIO, NOK, NPR, NZD, OMR, PAB, PEN, PHP, PKR, PLN, PYG, QAR, RON, RSD, RUB, RWF, SAR, SEK, SGD, SYP, THB, TJS, TND, TRY, TWD, TZS, UAH, UGX, USD, UYU, UZS, VES, VND, XOF, ZAR, ZMW

## Crypto (per-currency precision)

| Code | Currency | Precision | Units |
|------|----------|-----------|-------|
| BTC | Bitcoin | 8 | BTC, mBTC, sat |
| BCH | Bitcoin Cash | 8 | BCH |
| ETH | Ethereum | 8 | ETH, mETH, Gwei |
| LTC | Litecoin | 8 | LTC, mLTC, litoshi |
| DASH | Dash | 8 | DASH |
| DOT | Polkadot | 10 | DOT |
| POL | Polygon | 8 | POL |
| USDT | Tether (stablecoin) | 5 | USDT |
| USDC | USD Coin (stablecoin) | 5 | USDC |
| DAI | Dai (stablecoin) | 5 | DAI |
| XRP | Ripple | 6 | XRP, mXRP |
| TRX | Tron | 8 | TRX, mTRX |
| DOGE | Dogecoin | 6 | DOGE, mDOGE |
| ADA | Cardano | 6 | ADA, mADA |
| SOL | Solana | 9 | SOL, mSOL |
| BNB | Binance Coin | 8 | BNB, mBNB |
| TON | Toncoin | 9 | TON, mTON |
| SHIB | Shiba Inu | 8 | SHIB |
| EOS | EOS | 6 | EOS |
| PYUSD | PayPal USD (stablecoin) | 6 | PYUSD |

## Special (5-digit precision)

| Code | Description |
|------|-------------|
| XXX | Fun money / demo mode |
| GLD | GoldCoin (virtual currency, 10,000 coins = 1 USD) |
| SS1 | SweepCoin (sweepstakes currency, 1:1 with USD) |
| BC1 | BlitzCoin (sweepstakes currency, 1:1 with USD; parallels SS1, displays as BC) |
| UFC | Alternative fun currency |
| USD1 | USD-denominated fun currency |
| CVD | Coverd Cash (sweepstakes cash, 1:1 with USD) |
| WOW | GoldCoin (sweepstakes gold coin, 100 coins = 1 USD) |
| GC | GoldCoin (sweepstakes gold coin, 100 coins = 1 USD) |
| PGSC | Sweepstake Coin (sweepstakes currency, 1:1 with USD; parallels SS1) |
| PGGC | Gold Coin (sweepstakes gold coin, 10,000 coins = 1 USD; parallels GLD) |

## Kilo Variants (8-digit precision)

kIDR (IDR in thousands), kVND (VND in thousands)

---

# Supported Languages

| Code | Language |
|------|----------|
| en | English |
| da | Danish |
| tr | Turkish |
| th | Thai |
| fr | French |
| ru | Russian |
| ja | Japanese |
| es | Spanish |
| pt | Portuguese |
| de | German |
| zh | Chinese |
| ko | Korean |
| vi | Vietnamese |
| ar | Arabic |
| hi | Hindi |
| en-soc | English (SweepStakes) |

Default: `en` (English). Pass via the `language` parameter on Get Game URL (ISO 639-1).

---

# Error Codes Reference

## Signature failures

There is **no** `INVALID_SIGNATURE` status. If our outbound `/balance`, `/bet`, `/win`, or `/rollback` request fails signature verification on your end, reject it with a **non-2xx status (e.g. 401)** and no `status` field. Inbound requests to 155.io are authenticated by IP whitelist, not signatures.

## System Errors

| Status | Description |
|--------|-------------|
| `EXTERNAL_SERVICE_TIMEOUT_ERROR` | Request to external service timed out. Retry the request. |

## 155.io API Errors

### /game/games

| Status | HTTP | Description |
|--------|------|-------------|
| `Invalid operator id` | 400 | No operator for the provided `operatorId` |

### /game/free-bets/rewards

| Status | HTTP | Description |
|--------|------|-------------|
| `Validation error` | 400 | Missing or invalid request fields |
| `Invalid operator id` | 400 | Unknown operatorId |
| `Player not found` | 404 | Player does not exist (never launched a game) |
| `REWARD_ALREADY_EXISTS` | 409 | Reward with this `clientRewardId` already exists (code 9003) |
| `Internal server error` | 500 | Unexpected failure; `details` = `free bets are not enabled for operator <id>` means the feature is off — contact 155.io |

### /game/free-bets/rewards/cancel

| Status | HTTP | Code | Description |
|--------|------|------|-------------|
| `REWARD_NOT_FOUND` | 404 | 9001 | No reward exists for the provided `clientRewardId` |
| `REWARD_CANNOT_BE_CANCELLED` | 409 | 9006 | At least one freebet has been `used` — reward cannot be cancelled |
| `REWARD_NOT_STARTED` | 409 | 9007 | Scheduled reward, freebets not yet generated — transitioned to `cancelled` (treat as success) |
| `Internal server error` | 500 | — | Unexpected failure |

### Get Round Details / Get Player Bets

| Status | HTTP | Description |
|--------|------|-------------|
| Round not found | 404 | No round exists for the given ID/game, or still processing (round lookup) |
| Bet not found | 404 | No bet exists, or the bet doesn't belong to your integration (round lookup) |
| Invalid Integration IP | 400 | Request originated from an unrecognized IP address |
| Validation error | 400 | Missing or invalid request parameters |
| Invalid date format | 400 | `from` or `to` is not a valid RFC3339 timestamp (player bets) |

## Operator API Error Statuses

All operator API responses use HTTP 200 with the outcome in `status` — the one exception is a failed `X-Marbles-Signature` verification, which is rejected with a non-2xx (e.g. 401) and no `status` field. These are statuses you return in the JSON body. Any unrecognized status is treated as `UNKNOWN_ERROR`.

### /balance

`SUCCESS`, `UNKNOWN_ERROR` — any non-`SUCCESS` status (including an expired/invalid session) is treated as `UNKNOWN_ERROR`.

### /bet

`INSUFFICIENT_BALANCE_ERROR`, `DUPLICATE_TRANSACTION_ERROR`, `BONUS_ERROR`, `BET_LIMIT_REACHED_ERROR`, `UNKNOWN_ERROR`

### /win

`DUPLICATE_TRANSACTION_ERROR`, `UNKNOWN_ERROR`

### /rollback

`DUPLICATE_TRANSACTION_ERROR`, `UNKNOWN_ERROR`

## Freebet Usage Errors

Internal errors that may occur when a player attempts to use a freebet. Handled by 155.io; the player sees an appropriate message.

| Code | Error | Description |
|------|-------|-------------|
| 16010 | `FREEBET_INSUFFICIENT_AMOUNT` | Freebet amount is less than the minimum bet requirement |
| 16011 | `FREEBET_NOT_APPLICABLE_FOR_GAME` | Freebet is restricted to specific games and cannot be used on this game |
| 16012 | `FREEBET_CURRENCY_MISMATCH` | Freebet currency does not match the game/bet currency |
| 16013 | `FREEBETS_NOT_ENABLED` | Freebets are not enabled for this operator |

### Error Response Format

```json
{
  "status": "ERROR_CODE_HERE",
  "requestId": "original-request-id",
  "clientPlayerId": "player-id"
}
```

---

# Testing

## Staging Environment

| | URL |
|---|---|
| API | `https://api.stagingmarbles.io` |
| Game Status | https://status.155.io (select "Staging") |

## Track Availability

Not all tracks run continuously on staging. Some are reserved for internal testing (rollback scenarios, edge cases). Check https://status.155.io to see which tracks are live. If a track appears offline, this is intentional.

## Testing Steps

1. Generate a game URL on staging, open in browser
2. Place a test bet — verify `/bet` is received
3. Complete the game — verify `/win` or `/rollback` is called
4. Verify balances update correctly (watch for double-deducting on retries, crediting freebet wins, refunding on rollback)

## Acceptance Testing (self-serve certification)

Self-certify your wallet integration on staging in one call, before go-live. It replays the real signed wallet callbacks against your staging wallet and returns a per-check pass/fail report.

```
POST https://acceptance.stagingmarbles.io/acceptance/run
Content-Type: application/json

{
  "operatorId": "<your operatorId>",
  "partnerId": "<your partnerId>",
  "testPlayer": {
    "clientPlayerId": "<a funded staging test player>",
    "clientSessionId": "<a session id for that player>",
    "currency": "USD",
    "gameId": "<a whitelisted gameId>"
  },
  "checks": ["all"]
}
```

- **Staging only** (`acceptance.stagingmarbles.io`). Authentication is by **source IP** — call from one of the IPs you whitelisted with us (no token).
- The request IDs are the same ones you send in `/game/game/url`: `clientPlayerId`, `clientSessionId`, `gameId` (a whitelisted game — list via `POST /game/games`), `operatorId`, `partnerId`. The test player must be **FUNDED** — money-moving checks place small real bets/wins/rollbacks on your staging wallet.
- For a first, no-risk run, pass only the read-only checks: `["signature_accepted","signature_rejected","unknown_player","balance_read"]`.

Returns HTTP 200 even when a check fails — the verdict is in `status`. Response envelope includes `runId`, `integrationId`, `environment`, `status`, and a `checks` array; each check carries `id`, `phase`, `title`, `status`, `reason`, `description` (what it validates and how to fix), and `evidence` (balances before/after, HTTP status).

Run `status`: `passed` | `passed_with_warnings` | `failed` | `blocked`. Per-check `status`: `pass` | `fail` | `warn` | `blocked`.

Checks:
- `signature_accepted` — reachable + accepts our signed request
- `signature_rejected` — rejects a wrong-key signature (advisory; IP-allowlisting instead is fine)
- `game_whitelisted` — the gameId is in your allowed games / launchable (needs `partnerId`)
- `unknown_player` — unknown player handled gracefully (advisory)
- `balance_read` — we can read the test player's balance
- `bet_debit` — a `/bet` debits exactly the stake
- `insufficient_funds` — an over-balance bet is rejected with no debit
- `win_credit` — a `/win` credits exactly the payout
- `loss` — a loss leaves only the stake debited
- `rollback_zero` — a `/rollback` returns the balance to where it started (catches re-debit bugs)
- `free_bet` — a free bet (`isFree`) is accepted with zero debit
- `precision` — amounts reconcile exactly at the currency's full wire precision
- `idempotency` — duplicate `/win` and `/bet` transactions are deduplicated

### Acceptance endpoint error statuses

| HTTP | Reason |
|------|--------|
| 400 | Missing `testPlayer.gameId`, or invalid JSON body |
| 401 | Calling IP is not whitelisted for any integration |
| 403 | Self-cert attempted against the production endpoint (staging only) |

## Go-Live Readiness

Run the acceptance test until it passes, then contact our team to schedule final verification. We need:
- A staging URL and login credentials to access your platform
- We run test rounds covering win, loss, and rollback
- We verify callbacks against internal logs

## Fun Money Mode

Test the game UI without implementing any endpoints: generate a game URL with `currency: "XXX"` and omit `clientSessionId`/`clientPlayerId` — no callbacks are sent.

---

# Features

Beyond the core betting API, 155.io offers engagement features. All multiplier boosts **stack additively** and are applied server-side — the `amount` in your `/win` callbacks already includes them; you never calculate multipliers yourself. Feature availability may vary by integration type and agreement.

## How Boosters Affect RTP

Published **Effective RTP** figures are quoted at player level 0 and cover **Lightning Rounds only** — the average Lightning contribution is multiplicative on the base figure and differs per selection (each tier boosts only the options inside its own eligible pool). Streak Multipliers, Player Levels and Daily Check-in add further on top where a game offers them (Streak Multipliers are not currently enabled on any live game). Games with no Lightning Rounds configured — Coin Flip and Footfall — have an effective RTP equal to their base RTP.

## Lightning Rounds

Random rounds boost exactly one betting option. The boost MULTIPLIES the payout — it is not a percentage added to it. Each tier draws its factor from a weighted set.

| Tier | Boost factor (weighted draw) | Average | Options boosted |
|------|------------------------------|---------|-----------------|
| Common ⚡ | 1.1x (60%), 1.2x (30%), 1.5x (10%) | 1.17x | 1 |
| Rare ⚡⚡ | 1.5x (50%), 2x (30%), 3x (20%) | 1.95x | 1 |
| Epic ⚡⚡⚡ | 2x (50%), 3x (30%), 4x (20%) | 2.7x | 1 |
| Legendary ⚡⚡⚡⚡ | 3x (50%), 4x (30%), 5x (20%) | 3.7x | 1 |

Trigger chance is per game. Marble Plinko / Rolling Dunes / Snake / Fast Lane: common 1 in 3, rare 1 in 25, epic 1 in 60, legendary 1 in 200. Stairpong / Survivor / Fish Tank: 1 in 3, 1 in 120, 1 in 200, 1 in 600. Rush Hour / Duck River / Snow Run: 1 in 3, 1 in 60, 1 in 400, 1 in 1,000. Only one tier fires per round (checked rarest-first).

Most games restrict which options the three rarer tiers may boost, so effective RTP differs PER SELECTION. In Rush Hour, Duck River and Snow Run, Exact Low and Exact High are in no pool at all and receive no boost — which is why their lightning ceiling is 90x (5 x Exact at 18x) and not 5 x their 36x maximum. Coin Flip and Footfall have no Lightning Rounds.

## Streak Multipliers

Tracked per player per game; displayed live in the bet panel. Built-in anti-abuse protection prevents gaming the system with small bets.

**Win streaks** (a loss resets to zero):

| Streak | Win Multiplier |
|--------|----------------|
| 2 wins | +0.25% |
| 3 wins | +0.5% |
| 4 wins | +0.75% |
| 5+ wins | +1.0% (max) |

**Comeback boost / loss streaks** (a win resets):

| Streak | Comeback Bonus |
|--------|----------------|
| 2 losses | +0.5% |
| 3 losses | +1.0% |
| 4 losses | +1.5% |
| 5 losses | +2.0% |
| 6+ losses | +3.0% (max) |

## Player Levels

XP-based progression with **permanent** win-multiplier boosts. Players earn XP on every bet regardless of outcome: **1 XP = $0.01 USD wagered**.

| Level | XP Required | USD Wagered | Boost |
|-------|-------------|-------------|-------|
| 1 | 50K | $500 | +0.1% |
| 2 | 250K | $2,500 | +0.2% |
| 3 | 750K | $7,500 | +0.3% |
| 4 | 2M | $20,000 | +0.4% |
| 5 | 5M | $50,000 | +0.5% |
| 6 | 12.5M | $125,000 | +0.6% |
| 7 | 30M | $300,000 | +0.7% |
| 8 | 60M | $600,000 | +0.8% |
| 9 | 100M | $1,000,000 | +0.9% |
| 10 | 150M | $1,500,000 | +1.0% |

## Daily Check-in

Streak-based rewards for consecutive daily engagement. Reward types: **Win Multiplier** (percentage boost) or **Fixed Bonus** (fixed amount). Activation types: `auto` (applied when claimed) or `manual` (player chooses when). Default streak rewards:

| Day | Win Multiplier |
|-----|----------------|
| 1 | +1% |
| 2 | +2% |
| 3 | +3% |
| 4 | +4% |
| 5 | +5% |
| 6+ | +6% (max) |

Streak mechanics: players must log in within a window (some configs require placing a bet) to advance; missing a day resets to Day 1. Boosters are single-use, apply to one bet, auto-apply to the next bet, and only one can be active at a time; they appear in the player's items inventory.

(All feature boost values are examples and subject to change.)