Issue a free bet

A free-bet grant gives a player wagers for a specific game instance without deducting those stakes from their own balance.

`POST /api/v0.2/free-bet/grant`

Grant one or more free bets to a player for a specific game instance.

Authentication

All requests require the following headers:

Header	Type	Required	Description
`X-Operator-Id`	string	Yes	Unique identifier for the operator
`X-Signature`	string	Yes	Base64 URL-safe encoded RSA signature of the request body

Signature Verification

For POST requests:

Sign the entire JSON request body as a string
The value is signed using RSA-SHA256 with the operator's private key
The signature is Base64 URL-safe encoded (no padding)
The server verifies the signature using the operator's registered public key

Request Body

{
  "player_id": "string",
  "instance_id": "string",
  "count": 1,
  "wager_amount_cents": 100,
  "expire_duration_millis": 86400000,
  "reference_id": "string"
}

Field Descriptions

Field	Type	Description	Validation
`player_id`	`string`	Unique identifier for the player	Required, non-empty, max 100 characters
`instance_id`	`string`	Game instance ID	Required
`count`	`number`	Number of free bets to grant	Required, 1-50
`wager_amount_cents`	`number`	Wager amount in cents	Required, 1-1000000 (max $10,000)
`expire_duration_millis`	`number`	Duration until expiry in milliseconds	Required, 1-2592000000 (max 30 days)
`reference_id`	`string`	Your unique reference for this free bet	Required, non-empty, max 100 characters, must be unique per instance

Response

Success Response (200 OK)

{
  "success": true,
  "free_bet_id": "66f8a1b2c3d4e5f6g7h8i9j0",
  "message": "Free bet granted successfully"
}

Error Response (400 Bad Request)

{
  "success": false,
  "message": "Count cannot exceed 50",
  "error_code": "COUNT_TOO_HIGH"
}

Error Codes

Error Code	Description	Message
`INVALID_COUNT`	Count is less than 1	"Count must be at least 1"
`COUNT_TOO_HIGH`	Count exceeds 50	"Count cannot exceed 50"
`INVALID_WAGER_AMOUNT`	Wager amount is 0 or negative	"Wager amount must be greater than 0"
`WAGER_AMOUNT_TOO_HIGH`	Wager amount exceeds $10,000	"Wager amount cannot exceed $10,000.00"
`INVALID_EXPIRE_DURATION`	Expire duration is 0 or negative	"Expire duration must be greater than 0"
`EXPIRE_DURATION_TOO_LONG`	Expire duration exceeds 30 days	"Expire duration cannot exceed 30 days"
`EMPTY_PLAYER_ID`	Player ID is empty or whitespace only	"Player ID cannot be empty"
`PLAYER_ID_TOO_LONG`	Player ID exceeds 100 characters	"Player ID cannot exceed 100 characters"
`EMPTY_REFERENCE_ID`	Reference ID is empty or whitespace only	"Reference ID cannot be empty"
`REFERENCE_ID_TOO_LONG`	Reference ID exceeds 100 characters	"Reference ID cannot exceed 100 characters"
`INVALID_INSTANCE_ID`	Instance ID format is invalid	"Invalid instance ID format"
`INSTANCE_NOT_FOUND`	Game instance not found	"Game instance not found"
`DUPLICATE_REFERENCE_ID`	Reference ID already used for this instance	"Free bet with this reference ID already exists for this instance"

Constraints

Wager Amount: 1-1000000 cents ($0.01-$10,000.00)
Count: 1-50 free bets per request
Expire Duration: 1-2592000000 milliseconds (max 30 days)
Player ID: Non-empty, max 100 characters
Reference ID: Non-empty, max 100 characters, unique per instance
Instance ID: Required

Status Codes

200 OK - Free bet granted successfully
400 Bad Request - Invalid request body or validation error
401 Unauthorized - Invalid operator or signature
403 Forbidden - Operator account is inactive

Use Cases

Promotional campaigns and bonuses
Player retention initiatives
Compensation for technical issues
Welcome bonuses for new players
Loyalty program rewards

On this page