API Methods

The platform provides a REST API for working with games. All requests must be signed as described in Authorization.

Base URL

The API base URL will be provided by the platform manager.

Common request format

Method

All requests use the POST method.

Headers

All requests must include the following headers:

• Content-Type: application/json
• X-Signature: {request_signature}: request signature generated according to Authorization

Request body format

All data is sent as JSON in the request body. Required fields for all requests:

• agent_id (integer): agent ID
• timestamp (integer): Unix timestamp of the request

Response format

All successful responses follow a unified structure and are returned with HTTP status 200 OK:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "unique-request-id",
  "content": {
    // Response data
  }
}

Error responses are returned with the corresponding HTTP status codes (4xx, 5xx):

{
  "status": "error",
  "error": "error_code",
  "message": "Error description",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "unique-request-id"
}

Important

Treat all HTTP responses other than 200 OK as errors. Even if the response body contains data, any non-200 status should be handled as an unsuccessful request.

API endpoints

Get a game link

Generates a unique link to launch a game with the specified parameters.

Endpoint: POST /api/games/get_game_link

Request parameters:

Parameter	Type	Required	Description
agent_id	integer	Yes	Agent ID
timestamp	integer	Yes	Unix timestamp of the request
game_id	integer	Yes	Game ID
player_id	string	Yes	Unique player ID in the agent’s system. Must be unique per player
player_username	string	Yes	Player username. May be non-unique
language	string	Yes	Language code (ru, en, etc.)
currency	string	Yes	Currency code (RUB, USD, EUR, etc.)
home_url	string	Yes	Return URL for the player. Used by some games for the “Home” button
agent_session_id	string	Yes	Agent session ID
ip	string	Yes	Player IP address

Example request:

{
  "agent_id": 1,
  "timestamp": 1640995200,
  "game_id": 123,
  "player_id": "player_123",
  "player_username": "john_doe",
  "language": "ru",
  "currency": "RUB",
  "home_url": "https://example.com",
  "agent_session_id": "session_abc123",
  "ip": "192.168.1.1"
}

Example success response:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "url": "https://game.example.com/play?token=abc123&gameId=123&playerId=player_123"
  }
}

Possible errors:

• invalid_signature (403) - invalid request signature
• agent_not_found (404) - agent not found
• game_not_found (404) - game not found
• game_not_available (403) - game is not available for this agent
• validation_error (422) - parameter validation error

Example error response:

{
  "status": "error",
  "error": "game_not_found",
  "message": "Game not found",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da"
}

Get a demo game link

Generates a link to launch a demo version of a game without creating a game session. Demo mode allows the player to try a game without using real money.

Endpoint: POST /api/games/get_game_link_demo

Request parameters:

Parameter	Type	Required	Description
agent_id	integer	Yes	Agent ID
timestamp	integer	Yes	Unix timestamp of the request
game_id	integer	Да	ID игры
player_id	string	Да	Уникальный ID игрока в системе агента. Должен быть уникальным для каждого игрока
player_username	string	Да	Имя пользователя игрока. Может быть неуникальным
language	string	Да	Код языка (ru, en, и т.д.)
currency	string	Да	Код валюты (RUB, USD, EUR, и т.д.)
home_url	string	Да	URL возврата для игрока. Используется в некоторых играх для кнопки "Home"
ip	string	Да	IP адрес игрока

Differences from a regular link

• The agent_session_id parameter is not required (no session is created)
• The player receives a virtual balance for the demo game
• Game results are not saved

Example request:

{
  "agent_id": 1,
  "timestamp": 1640995200,
  "game_id": 123,
  "player_id": "player_123",
  "player_username": "john_doe",
  "language": "ru",
  "currency": "RUB",
  "home_url": "https://example.com",
  "ip": "192.168.1.1"
}

Example success response:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "url": "https://game.example.com/demo?token=abc123&gameId=123&playerId=player_123"
  }
}

Possible errors:

• invalid_signature (403) - invalid request signature
• agent_not_found (404) - agent not found
• game_not_found (404) - game not found
• game_not_available (403) - game is not available for this agent
• game_provider_not_found (404) - no provider with demo support for this game
• validation_error (422) - parameter validation error

Get the list of games

Returns the list of all games available to the agent.

Endpoint: POST /api/games/list

Request parameters:

Параметр	Тип	Обязательный	Описание
agent_id	integer	Да	ID агента
timestamp	integer	Да	Unix timestamp запроса

Example request:

{
  "agent_id": 1,
  "timestamp": 1640995200
}

Example success response:

{
  "status": "success",
  "timestamp": "2024-01-01T00:00:00.000Z",
  "request_id": "ba9d4445-779f-4b04-8bcb-6d17bc8dc3da",
  "content": {
    "games": [
      {
        "id": 1,
        "title": "Champagne Party",
        "brand": "Mega",
        "image_url": "https://cdn.example.com/images/games/champagne_party.jpg",
        "demo": true
      },
      {
        "id": 2,
        "title": "Book of Fortune",
        "brand": "Mega",
        "image_url": "https://cdn.example.com/images/games/book_of_fortune.jpg",
        "demo": false
      }
    ],
    "total": 2
  }
}

Response fields:

Field	Type	Description
games	array	List of game objects
games[].id	integer	Unique game ID
games[].title	string	Display title of the game
games[].brand	string	Game brand
games[].image_url	string	Game image URL
games[].demo	boolean	Demo availability (true if demo is available, false if not)
total	integer	Total number of games in the list

Possible errors:

• invalid_signature (403) - invalid request signature
• agent_not_found (404) - agent not found
• validation_error (422) - parameter validation error

Error handling

The platform uses HTTP status codes to indicate request results:

• 200 OK: request processed successfully
• 4xx: client errors (invalid request, unauthorized, not found, etc.)
• 5xx: server errors (internal platform errors)

Important

Treat all HTTP responses other than 200 OK as errors. For any status other than 200, handle the request as unsuccessful even if the response body contains data.

Error codes

Error code	HTTP status	Description
signature_required	401	Missing X-Signature header
invalid_signature	403	Invalid request signature
agent_not_found	404	Agent with the specified ID was not found
api_token_not_found	404	The agent has no API token configured
game_not_found	404	Game with the specified ID was not found
game_not_available	403	Game is not available for this agent
method_not_allowed	405	Unsupported HTTP method used
validation_error	422	Input validation error
request_expired	400	Request expired (timestamp too old)

Recommendations

Caching the game list

• The game list does not change often; caching on the agent side is recommended
• Refresh the cache every few hours or as needed

Handling errors

• Always check the HTTP status code. Treat all responses other than 200 OK as errors
• If you get invalid_signature, verify your signature generation
• If you get request_expired, make sure you are using accurate server time