Quick Start

Get your integration up and running with this step-by-step guide.

Submit Your Configuration

To get started, submit your integration details through our onboarding form:

Submit Application

You'll need to provide the following for your staging environment:

Field	Description
Company Name	Your company or brand name
Base URL	The URL where 155.io will send requests (e.g., `https://your-api.com/v1`)
IP Addresses	Server IPs that will send requests to 155.io (for whitelisting)
Public Key	Your RSA public key in PEM format for payload signing
Max Liability Amount	Maximum amount a player can win with one bet (in USD)

Only staging configuration is required to start testing. You can provide production details later when you're ready to go live.

Once submitted, you'll receive:

Your operatorId - links to your operator configuration
Your partnerId - identifies your website/casino
155.io's public key - to verify our responses
155.io's IP addresses - to whitelist on your server

Implement Request Signing

All API requests must be signed using RSA-SHA256. Here's a quick implementation:

import { createSign } from 'node:crypto'

function signPayload(payload: string, privateKey: string): string {
  return createSign('RSA-SHA256')
    .update(payload)
    .sign(privateKey, 'base64')
}

// Usage
const signature = signPayload(JSON.stringify(requestBody), privateKey)
// Add to request: headers['X-Marbles-Signature'] = signature

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

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

# Usage
signature = sign_payload(json.dumps(request_body), private_key)
# Add to request: headers['X-Marbles-Signature'] = signature

function signPayload(string $payload, string $privateKey): string {
    openssl_sign($payload, $signature, $privateKey, OPENSSL_ALGO_SHA256);
    return base64_encode($signature);
}

// Usage
$signature = signPayload(json_encode($requestBody), $privateKey);
// Add to request: $headers['X-Marbles-Signature'] = $signature

See the full Security documentation for more details.

Implement Your Endpoints

You need to implement four endpoints on your server:

Endpoint	Purpose
`POST /balance`	Return player's current balance
`POST /bet`	Deduct bet amount from player balance
`POST /win`	Credit winnings to player balance
`POST /rollback`	Reverse a previous bet transaction

All amounts use 5-digit precision. Multiply by 100,000 when storing/displaying. Example: 1000000 = $10.00 USD

See Operator API for full endpoint specifications.

Fetch Available Games

Get the list of games using the /game/games endpoint:

curl -X POST https://api.marbles.xyz/game/games \
  -H "Content-Type: application/json" \
  -H "X-Marbles-Signature: <your-signature>" \
  -d '{"operatorId": "your-operator-id"}'

See Get Games for the full response format.

Generate Game URLs

Create a game session for a player:

curl -X POST https://api.marbles.xyz/game/game/url \
  -H "Content-Type: application/json" \
  -H "X-Marbles-Signature: <your-signature>" \
  -d '{
    "clientSessionId": "session-123",
    "clientPlayerId": "player-456",
    "operatorId": "your-operator-id",
    "partnerId": "your-partner-id",
    "gameId": "game-uuid-from-step-4",
    "username": "player_username",
    "currency": "USD",
    "platform": "DESKTOP"
  }'