Freebets & Rewards

Direct integration operators can grant freebets to players via the 155.io API and receive freebet transactions through their operator API. Free bets are enabled by default — see Enablement above. For the authoritative grant → bet → win → rollback behaviour, see Contract rules.

Granting Freebets

Grant rewards with POST /game/free-bets/rewards — full request/response reference, error contract and prepaid templates on the endpoint page. Two things worth knowing up front:

• amount is an integer at the currency's wire precision (USD: 500000 = $5.00) — the same scale as the amount on the /bet callback. A free bet only covers a bet whose wire amount is ≤ the granted integer, so an under-scaled grant (e.g. cents) makes every free bet unusable.
• Each clientRewardId is tied to one player — a 100-player campaign is 100 grant calls. The clientRewardId comes back on bet transactions as rewardUuid, which is how you attribute a bet to a promotion.

Use startTime to schedule a grant for a future date: the reward is created immediately (status scheduled), but the free bets themselves are only generated — and become visible and claimable — at startTime. The reward can be cancelled before then (the cancel returns REWARD_NOT_STARTED; treat it as a successful cancellation).

Cancelling Freebets

Cancel the unused free bets of a reward with POST /game/free-bets/rewards/cancel — rules, statuses and the error contract are on the endpoint page. Only claimable/claimed free bets can be cancelled; once any free bet from the reward has been used, the reward can no longer be cancelled.

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)
• Fires only before the freebet's /win (win or loss) callback. To reverse a granted-but-unused reward, use Cancelling Freebets, not /rollback.

Example Flow

1. You grant a $5 freebet to player-123 via the API
2. Player launches a 155.io game — the freebet is claimed automatically and announced with a banner
3. Player places a bet — the freebet is applied automatically and the stake locks to $5
4. You receive a bet request with amount: 0, isFree: true
5. Round completes - player wins $15
6. You receive a win request with amount: 1500000, isFree: true
7. 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

Contact us to set up your freebet templates. We'll need:

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.