Free bets

Free bets are optional promotional wagers with a fixed stake and game. The player’s wallet is not debited for the promotional stake; a prize is credited in full through your existing webhook, in the same currency as a normal bet. betAmount is used directly as the stake, without a USD conversion.

The game displays available free bets automatically. Implement the free-bet wallet events before issuing promotions. This page covers only grant management.

Issue a grant

Call this endpoint from your backend:


POST /freebets/issue
Content-Type: application/json
x-operator-secret: YOUR_WEBHOOK_SECRET


{
  "clientId": "your-client-id",
  "userId": "test-player",
  "game": "dice",
  "betAmount": 0.5,
  "quantity": 10,
  "idempotencyKey": "promotion-test-player-001"
}

Field	Required	Rules
`clientId`	Yes	Your client ID; string, 1–128 characters.
`userId`	Yes	Your player’s ID; string, 1–128 characters. The player need not have opened a Maktub game yet.
`game`	Yes	A supported event key, such as `dice` or `coin`.
`betAmount`	Yes	Numeric stake per wager in the player’s session currency, between 0.01 and 10,000, subject to the grant limits.
`quantity`	Yes	Integer from 1 to 1,000.
`idempotencyKey`	Yes	Your issuance key; string, 1–128 characters, unique within your account.
`expiresAt`	No	A future ISO 8601 timestamp. Omit for no expiry.

Every game supports free bets except Baccarat, Roulette and Futures.

Success returns HTTP 201, including on a matching retry:


{
  "freeBetId": "665f1c2e8b3a4d0012ab34cd",
  "game": "dice",
  "betAmount": 0.5,
  "quantity": 10,
  "remainingCount": 10,
  "expiresAt": null,
  "billable": true
}

remainingCount is the number still available. Operator-issued grants are billable; the request does not offer an option to disable billing.

Retry the same request with the same idempotencyKey. It returns the existing grant without adding free bets. Reusing the key with a different player, game, stake or quantity returns 409. Reusing a key does not edit a grant’s expiry.

Cancel unused free bets

Use the original issuance key to revoke the unused part of a grant:


POST /freebets/cancel
Content-Type: application/json
x-operator-secret: YOUR_WEBHOOK_SECRET


{
  "clientId": "your-client-id",
  "idempotencyKey": "promotion-test-player-001"
}

Success returns HTTP 200:


{
  "freeBetId": "665f1c2e8b3a4d0012ab34cd",
  "game": "dice",
  "cancelledCount": 7
}

Cancellation leaves already-played rounds and wallet movements unchanged. A repeat returns cancelledCount: 0. The grant record remains available for audit; its issuance key cannot be used to create another grant.

Errors

HTTP status	Meaning
`400`	Invalid fields, unsupported game, invalid stake/quantity or past expiry.
`401`	Invalid client ID or webhook secret.
`404`	No grant matches the client ID and cancellation key.
`409`	An issuance key was reused with conflicting grant details.
`429`	Too many requests or failed authentication attempts.
`500`	Grant creation failed; investigate before retrying with the same key.

Grant behavior

Multiple grants for one player and game are consumed oldest-first. Expired, empty or cancelled grants cannot be played. A player can use a grant with zero cash balance. Blackjack actions that require additional stakes are unavailable on free-bet rounds.