Freebets & Rewards

Freebets allow operators to create promotional rewards that give players free bets on 155.io games. When a player uses a freebet, no real money is deducted from their balance, but any winnings are credited as real money.

Integration Options

Direct integration operators can grant freebets to players via the 155.io API and receive freebet transactions through their operator API.

Prerequisites

Before using freebets, contact us to enable the feature for your operator account. Once enabled, you can start granting freebets immediately.

Granting Freebets

Use the 155.io API to grant freebets to players:

POST /v1/free-bets/rewards

Request

{
  "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	The player's unique identifier in your system
`operatorId`	string	Yes	Your operator ID
`clientRewardId`	string	Yes	Your unique identifier for tracking this reward
`amount`	integer	Yes	Value per freebet with 5-digit precision (e.g., 500000 = $5.00)
`currency`	string	Yes	ISO 4217 currency code
`quantity`	integer	No	Number of freebets to grant (default: 1, max: 10)
`expiresAt`	string	Yes	ISO 8601 expiration datetime
`startTime`	string	No	ISO 8601 datetime when freebets become available (for scheduled campaigns)
`gameIds`	array	No	Restrict freebets to specific games (omit for all games)

Success Response

HTTP/1.1 200 OK

{
  "rewardId": "550e8400-e29b-41d4-a716-446655440000",
  "clientRewardId": "promo-winter-2025-001",
  "status": "active",
  "freeBets": [
    {
      "id": "fb-001",
      "amount": 500000,
      "currency": "USD",
      "status": "claimable",
      "expiresAt": "2025-12-31T23:59:59Z"
    },
    {
      "id": "fb-002",
      "amount": 500000,
      "currency": "USD",
      "status": "claimable",
      "expiresAt": "2025-12-31T23:59:59Z"
    },
    {
      "id": "fb-003",
      "amount": 500000,
      "currency": "USD",
      "status": "claimable",
      "expiresAt": "2025-12-31T23:59:59Z"
    }
  ]
}

Error Responses

HTTP Code	Error Code	Description
400	`VALIDATION_ERROR`	Invalid request (missing fields, invalid format)
400	`FREEBETS_NOT_ENABLED`	Freebets not enabled for your operator
404	`PLAYER_NOT_FOUND`	Player does not exist
409	`REWARD_ALREADY_EXISTS`	A reward with this `clientRewardId` already exists
500	`UNKNOWN_ERROR`	Internal server error

Client Reward ID

The clientRewardId is returned in bet transactions as rewardUuid, allowing you to track which promotion a freebet belongs to.

Important: Each clientRewardId is tied to one player. If you want to grant freebets to 100 players in a campaign, you make 100 API calls. You can use the same clientRewardId pattern (e.g., winter-promo-{playerId}) or unique IDs per grant.

Cancelling Freebets

Cancel unused freebets for a specific reward:

POST /v1/free-bets/rewards/cancel

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

Cancel Response

{
  "clientRewardId": "promo-winter-2025-001",
  "freeBets": [
    {
      "id": "fb-001",
      "status": "cancelled"
    },
    {
      "id": "fb-002",
      "status": "cancelled"
    }
  ]
}

Cancel 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

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

Scheduling Freebets

Use startTime to schedule freebets for a future date (e.g., for upcoming promotions):

{
  "clientPlayerId": "player-123",
  "operatorId": "your-operator-id",
  "clientRewardId": "new-years-2026-player123",
  "amount": 1000000,
  "currency": "USD",
  "quantity": 5,
  "startTime": "2026-01-01T00:00:00Z",
  "expiresAt": "2026-01-31T23:59:59Z"
}

Freebets are created immediately but only become claimable after startTime
Players won't see the freebets until startTime
You can cancel scheduled freebets before they become active

Receiving Freebet Transactions

When a player uses a freebet, you'll receive modified bet/win/rollback requests:

Bet Request (Freebet)

{
  "requestId": "8df0475e-5069-483a-8205-f6089997abc9",
  "transactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "clientPlayerId": "player-123",
  "roundId": "17cc81fd-df13-4ca4-857d-de0f766dc372",
  "gameId": "f1c0b104-f29d-44a9-ae93-e8afcbe3feb9",
  "amount": 0,
  "currency": "USD",
  "isFree": true,
  "rewardUuid": "promo-winter-2025-001",
  "meta": { ... }
}

Key differences for freebets:

amount is 0 (no real money deducted)
isFree is true
rewardUuid contains your clientRewardId for tracking

Win/Loss Request (Freebet)

{
  "requestId": "...",
  "transactionId": "...",
  "referenceTransactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "amount": 1500000,
  "currency": "USD",
  "isFree": true,
  "roundClosed": true
}

For wins: amount contains the winnings to credit (this is real money)
For losses: amount is 0 (nothing to credit or deduct)
isFree is true to indicate this was a freebet result

Rollback Request (Freebet)

{
  "requestId": "...",
  "transactionId": "...",
  "referenceTransactionId": "ea0240f5-483d-434b-a8d4-04dabf61cde3",
  "isFree": true,
  "roundClosed": true
}

isFree is true to indicate the original bet was a freebet
No amount to refund (freebet had amount: 0)

Example Flow

You grant a $5 freebet to player-123 via the API
Player launches a 155.io game and sees the freebet in their inventory
Player taps the freebet and selects "Use now" to activate it
Player places a bet (freebet is applied)
You receive a bet request with amount: 0, isFree: true
Round completes - player wins $15
You receive a win request with amount: 1500000, isFree: true
You credit $15 to the player's real balance

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

Step 1: Request Prepaid Templates

Information	Description
Operator ID	Your Hub88 `operator_id`
Bet value	Amount per free bet (e.g., $1, $5, $10)
Quantity	Number of free bets in the reward
Currency	Which currencies to support (e.g., USD, EUR)
Games	All 155.io games or specific games only

For example, a template with bet value: $2 and quantity: 5 gives the player 5 free bets worth $2 each.

Once configured, you'll receive prepaid_uuid(s) that you can use to create rewards.

Step 2: Create Rewards via Hub88

Use Hub88's Operator API to grant freebets to your players:

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

{
  "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"
}

See Hub88's Freebets API Documentation for full details.

Set Expiration Dates

Always set start_time and end_time when creating rewards. Otherwise, rewards will automatically expire after a few weeks.

How It Works

You create a reward for a player via the appropriate API
Player launches a 155.io game and sees the freebet in their inventory
Player taps the freebet and selects "Use now" to activate it
Player places a bet (the freebet is automatically applied, no real balance deducted)
Winnings are credited as real money to the player's balance

Manual Activation Required

Freebets are not automatically used. Players must manually select a freebet from their inventory before placing a bet. This gives players control over when to use their promotional rewards. Only one freebet can be active at a time.