Quick Start
Get started with the 155.io API integration in minutes
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:
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. We keep it on file for future use; signature verification on inbound traffic is currently disabled (see Security). |
| 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 (provided by 155.io) - 155.io's public key — use this to verify our
X-Marbles-Signatureheader on incoming/balance,/bet,/win,/rollbackrequests - 155.io's IP addresses — whitelist these on your firewall so our callbacks reach your server
You'll also need to choose your own partnerId — this is a string you define to identify 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.
Verify Our Signatures on Inbound Callbacks
Our requests to your /balance, /bet, /win, and /rollback endpoints are signed with X-Marbles-Signature (RSA-SHA256 over the raw body bytes, BASE64-encoded). You must verify every incoming request against the 155.io public key shared at onboarding.
import { createVerify } from 'node:crypto'
function isValidSignature(rawBody: string, signature: string, marblesPublicKey: string): boolean {
return createVerify('RSA-SHA256')
.update(rawBody)
.verify(marblesPublicKey, signature, 'base64')
}
// Usage in your /balance, /bet, /win, /rollback handlers
const signature = req.headers['x-marbles-signature'] as string
if (!isValidSignature(rawBody, signature, marblesPublicKey)) {
return res.status(200).json({ status: 'INVALID_SIGNATURE', requestId, clientPlayerId })
}from cryptography.hazmat.primitives import hashes, serialization
from cryptography.hazmat.primitives.asymmetric import padding
import base64
def is_valid_signature(raw_body: bytes, signature: str, marbles_public_key_pem: str) -> bool:
public_key = serialization.load_pem_public_key(marbles_public_key_pem.encode())
try:
public_key.verify(
base64.b64decode(signature),
raw_body,
padding.PKCS1v15(),
hashes.SHA256()
)
return True
except Exception:
return False
# Usage in your /balance, /bet, /win, /rollback handlers
signature = request.headers['X-Marbles-Signature']
if not is_valid_signature(raw_body, signature, marbles_public_key):
return jsonify({'status': 'INVALID_SIGNATURE', 'requestId': request_id, 'clientPlayerId': player_id}), 200function isValidSignature(string $rawBody, string $signature, string $marblesPublicKey): bool {
return openssl_verify(
$rawBody,
base64_decode($signature),
$marblesPublicKey,
OPENSSL_ALGO_SHA256
) === 1;
}
// Usage in your /balance, /bet, /win, /rollback handlers
$signature = $_SERVER['HTTP_X_MARBLES_SIGNATURE'];
$rawBody = file_get_contents('php://input');
if (!isValidSignature($rawBody, $signature, $marblesPublicKey)) {
http_response_code(200);
echo json_encode(['status' => 'INVALID_SIGNATURE', 'requestId' => $requestId, 'clientPlayerId' => $playerId]);
exit;
}What about requests you make to 155.io?
Your calls to 155.io (e.g. /game/games, /game/game/url) are authenticated by IP whitelist, not signatures. You don't need to sign them — see Security for the full picture.
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" \
-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" \
-d '{
"clientSessionId": "session-123",
"clientPlayerId": "player-456",
"operatorId": "your-operator-id",
"partnerId": "my-casino",
"gameId": "game-uuid-from-step-4",
"username": "player_username",
"currency": "USD",
"platform": "DESKTOP"
}'The response contains a URL you can use in an iframe or redirect to directly.
Test Your Integration
- Generate a game URL on staging and open it in a browser
- Place a test bet — verify your
/betendpoint receives the request - Complete the game — verify
/winor/rollbackis called correctly - Check that balances update correctly throughout
Use the staging environment for testing: https://api.stagingmarbles.io. Check status.155.io (select "Staging") to see which tracks are currently live — some tracks may be paused for internal testing.
See the full Testing guide for details on track availability, go-live readiness, and what to expect during the final verification.
Next Steps
Security
Deep dive into request signing and verification
155.io API
Full API reference for games and URLs
Operator API
Complete endpoint specifications
Error Codes
Handle errors correctly
Need Help?
Our integration team is also here to help. Contact us if you have any questions or need assistance.