> ## Documentation Index
> Fetch the complete documentation index at: https://lifters.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# Tracking Casino Events

> Send casino events to Atlas for game analytics, RTP monitoring, and player behavior insights.

<Snippet file="snippets/api-key-auth.mdx" />

## Event Types

Casino events follow a three-phase lifecycle, all sent to the same endpoint. The Kafka topic is fixed: `atlas.events.raw.casino`.

| Event  | When to Send                   | Description                                     |
| ------ | ------------------------------ | ----------------------------------------------- |
| `open` | Immediately when bet is placed | Round started, bet amount deducted from balance |
| `win`  | When round resolves with a win | Includes win amount credited to player          |
| `lose` | When round resolves as a loss  | win\_amount = 0 or omitted                      |

<Info>
  All three events are linked by the same `bet_id`. Send `open` first, then `win` or `lose` when the round settles.
</Info>

## Track Casino Open

<CodeGroup>
  ```bash cURL theme={null}
  curl -X POST https://events.atlas.io/api/v1/casino \
    -H "X-API-Key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "org_id": "org_abc123",
      "brand_id": "brand_xyz",
      "event": "open",
      "bet_status": "open",
      "user_id": "user_12345",
      "casino_session_id": "session_20260311_001",
      "bet_id": "round_20260311_001",
      "bet_dt": "2026-03-11T14:30:00Z",
      "game_ext_id": "pragmatic_gates_olympus",
      "game_name": "Gates of Olympus",
      "game_provider": "Pragmatic Play",
      "game_type": "slot",
      "bet_amount": 5.00,
      "bet_amount_bonus": 0.00,
      "currency": "BRL",
      "before_balance": 150.00,
      "is_free_bet": false
    }'
  ```

  ```javascript JavaScript theme={null}
  await fetch('https://events.atlas.io/api/v1/casino', {
    method: 'POST',
    headers: {
      'X-API-Key': process.env.ATLAS_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      org_id: 'org_abc123',
      brand_id: 'brand_xyz',
      event: 'open',
      bet_status: 'open',
      user_id: 'user_12345',
      casino_session_id: 'session_20260311_001',
      bet_id: 'round_20260311_001',
      bet_dt: new Date().toISOString(),
      game_ext_id: 'pragmatic_gates_olympus',
      game_name: 'Gates of Olympus',
      game_provider: 'Pragmatic Play',
      game_type: 'slot',
      bet_amount: 5.00,
      currency: 'BRL',
      before_balance: 150.00,
      is_free_bet: false,
    }),
  });
  ```
</CodeGroup>

## Track Casino Win

```bash theme={null}
curl -X POST https://events.atlas.io/api/v1/casino \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "win",
    "bet_status": "win",
    "user_id": "user_12345",
    "casino_session_id": "session_20260311_001",
    "bet_id": "round_20260311_001",
    "bet_dt": "2026-03-11T14:30:05Z",
    "game_ext_id": "pragmatic_gates_olympus",
    "game_name": "Gates of Olympus",
    "game_provider": "Pragmatic Play",
    "game_type": "slot",
    "bet_amount": 5.00,
    "win_amount": 12.50,
    "win_amount_bonus": 0.00,
    "currency": "BRL",
    "before_balance": 145.00,
    "after_balance": 157.50,
    "is_free_bet": false
  }'
```

## Track Casino Lose

```bash theme={null}
curl -X POST https://events.atlas.io/api/v1/casino \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "org_id": "org_abc123",
    "brand_id": "brand_xyz",
    "event": "lose",
    "bet_status": "lose",
    "user_id": "user_12345",
    "casino_session_id": "session_20260311_001",
    "bet_id": "round_20260311_002",
    "bet_dt": "2026-03-11T14:31:00Z",
    "game_ext_id": "pragmatic_gates_olympus",
    "game_name": "Gates of Olympus",
    "game_provider": "Pragmatic Play",
    "game_type": "slot",
    "bet_amount": 5.00,
    "win_amount": 0.00,
    "currency": "BRL",
    "before_balance": 157.50,
    "after_balance": 152.50,
    "is_free_bet": false
  }'
```

## Request Fields

### Envelope Fields (all events)

<ParamField body="org_id" type="string" required>
  Organization identifier.
</ParamField>

<ParamField body="brand_id" type="string" required>
  Brand identifier.
</ParamField>

<ParamField body="event" type="string" required>
  Event type: `open`, `win`, or `lose`.
</ParamField>

<ParamField body="ip" type="string">
  Player IP address at round time.
</ParamField>

<ParamField body="geolocation_lat" type="number">
  Player latitude at round time.
</ParamField>

<ParamField body="geolocation_long" type="number">
  Player longitude at round time.
</ParamField>

<ParamField body="is_test" type="boolean">
  Marks the event as operator test traffic. When `true`, the event is accepted
  (202) but rerouted to an audit-only store — it never appears in analytics,
  dashboards or risk scoring. Defaults to `false` when omitted.
</ParamField>

### Casino Fields

<ParamField body="user_id" type="string" required>
  Your internal user identifier. Must be consistent across all events for the same player.
</ParamField>

<ParamField body="casino_session_id" type="string" required>
  Session identifier used to correlate multiple rounds within the same casino session.
</ParamField>

<ParamField body="bet_id" type="string" required>
  Unique identifier for this game round. Must be the same across `open`, `win`, and `lose` events for the same round.
</ParamField>

<ParamField body="bet_dt" type="string" required>
  ISO 8601 timestamp of when the round happened.
</ParamField>

<ParamField body="bet_status" type="string">
  Status of the bet round. Mirrors the `event` field: `open`, `win`, or `lose`. Optional but recommended for downstream ClickHouse consumers.
</ParamField>

<ParamField body="game_ext_id" type="string" required>
  Your internal game identifier, or the provider's game ID. Used for per-game analytics.
</ParamField>

<ParamField body="game_provider_ext_id" type="string">
  Optional provider-side game identifier when different from `game_ext_id`.
</ParamField>

<ParamField body="game_name" type="string" required>
  Human-readable game name (e.g., `"Gates of Olympus"`, `"Lightning Roulette"`).
</ParamField>

<ParamField body="game_provider" type="string" required>
  Game provider name (e.g., `"Pragmatic Play"`, `"Evolution"`, `"NetEnt"`).
</ParamField>

<ParamField body="game_type" type="string" required>
  Game category: `slot`, `roulette`, `blackjack`, `baccarat`, `poker`, `live`, `virtual`, `crash`.
</ParamField>

<ParamField body="platform" type="string">
  Allowed values: `WEB`, `MOBILE`, `APP`.
</ParamField>

<ParamField body="bet_amount" type="number" required>
  Real-money bet amount. Excludes bonus amounts.
</ParamField>

<ParamField body="bet_amount_bonus" type="number">
  Bonus/free-spin bet amount. Tracked separately from real money for GGR calculation.
</ParamField>

<ParamField body="win_amount" type="number">
  Real-money win amount. `0` for a losing round. Omit for `open` events.
</ParamField>

<ParamField body="win_amount_bonus" type="number">
  Bonus win amount (wins from bonus bets).
</ParamField>

<ParamField body="currency" type="string" required>
  ISO 4217 currency code (e.g. `BRL`).
</ParamField>

<ParamField body="before_balance" type="number">
  Player balance before this round. Used for balance reconciliation.
</ParamField>

<ParamField body="after_balance" type="number">
  Player balance after this round.
</ParamField>

<ParamField body="is_free_bet" type="boolean">
  Indicates whether this bet was a free bet.
</ParamField>

## GGR Calculation

Atlas calculates GGR from casino events automatically:

```
GGR = sum(bet_amount) - sum(win_amount)
```

Bonus GGR is tracked separately:

```
Bonus GGR = sum(bet_amount_bonus) - sum(win_amount_bonus)
```

<Tip>
  For accurate GGR reporting, always separate real-money and bonus amounts.
  Mixing them inflates GGR and breaks bonus liability tracking.
</Tip>

## Batch Casino Events

```bash theme={null}
curl -X POST https://events.atlas.io/api/v1/casino/batch \
  -H "X-API-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "events": [
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "open",
        "bet_status": "open",
        "user_id": "user_001",
        "casino_session_id": "session_20260311_002",
        "bet_id": "round_001",
        "bet_dt": "2026-03-11T14:30:00Z",
        "game_ext_id": "pragmatic_gates_olympus",
        "game_name": "Gates of Olympus",
        "game_provider": "Pragmatic Play",
        "game_type": "slot",
        "bet_amount": 2.00,
        "currency": "BRL",
        "before_balance": 100.00
      },
      {
        "org_id": "org_abc123",
        "brand_id": "brand_xyz",
        "event": "lose",
        "bet_status": "lose",
        "user_id": "user_001",
        "casino_session_id": "session_20260311_002",
        "bet_id": "round_001",
        "bet_dt": "2026-03-11T14:30:02Z",
        "game_ext_id": "pragmatic_gates_olympus",
        "game_name": "Gates of Olympus",
        "game_provider": "Pragmatic Play",
        "game_type": "slot",
        "bet_amount": 2.00,
        "win_amount": 0.00,
        "currency": "BRL",
        "before_balance": 98.00,
        "after_balance": 98.00
      }
    ]
  }'
```