> ## 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.

# Events Overview

> Understand how the Atlas event tracking system works — event types, domains, and the ingestion pipeline.

## What is Event Tracking?

Event tracking is how your platform communicates with Atlas. Every meaningful player action — placing a bet, making a deposit, creating an account — is an **event** that you send to Atlas in real-time.

Atlas processes these events to power your analytics, risk management, compliance monitoring, and behavioral insights.

## Event Domains

Atlas organizes events into four domains, each with a dedicated endpoint:

<CardGroup cols={2}>
  <Card title="Users" icon="user" href="/guides/events/tracking-users">
    `register` · `update`

    Player lifecycle events: account creation and profile changes.
  </Card>

  <Card title="Transactions" icon="arrow-right-arrow-left" href="/guides/events/tracking-transactions">
    `deposit` · `withdraw`

    Financial events: money in and money out.
  </Card>

  <Card title="Casino" icon="dice" href="/guides/events/tracking-casino">
    `open` · `win` · `lose`

    Casino game events: slots, table games, live casino rounds.
  </Card>

  <Card title="Sports" icon="trophy" href="/guides/events/tracking-sports">
    `open` · `win` · `lose` · `cashout`

    Sports betting lifecycle from placement to settlement.
  </Card>
</CardGroup>

## Generic vs Domain Events

You have two options for sending events:

|                 | Domain Events               | Generic Events              |
| --------------- | --------------------------- | --------------------------- |
| **Endpoint**    | `/api/v1/{domain}`          | `/v1/events`                |
| **Validation**  | Schema-validated per domain | Flexible — any JSON payload |
| **Analytics**   | Full, pre-built analytics   | Custom analytics only       |
| **Auth**        | API Key                     | JWT Bearer                  |
| **Recommended** | Yes, for known event types  | For custom/internal events  |

**Use domain events** whenever possible. They give you pre-built analytics, risk scoring, and compliance monitoring out of the box.

## How Events Flow

```
Your Backend
    │
    │  POST /api/v1/sport
    │  { event: "open", bet_id: "...", selections: [...] }
    ▼
Events API
    │ Validate + Enrich
    ▼
Kafka Topic
(atlas.events.raw.sportsbook)
    │
    ├──► Financial Engine ──► GGR / Revenue Reports
    ├──► Risk Engine      ──► Exposure / Alerts
    ├──► Player Profile   ──► Behavior Analytics
    └──► Compliance       ──► AML Monitoring
```

## Response Model

Every successful event ingestion returns `202 Accepted` — meaning the event was received and published to Kafka. Processing is asynchronous.

```json theme={null}
{
  "data": {
    "bet_id": "bet_abc_001"
  }
}
```

<Warning>
  `202 Accepted` means the event reached Kafka, not that it was fully processed.
  Keep your domain IDs (`bet_id`, `transaction_id`, `user_id`) in logs for easier traceability.
</Warning>

## Batch vs Single Events

For high-volume scenarios, always use batch endpoints:

| Mode   | Endpoint                   | Max Events | Best For                     |
| ------ | -------------------------- | ---------- | ---------------------------- |
| Single | `POST /api/v1/sport`       | 1          | Real-time, latency-sensitive |
| Batch  | `POST /api/v1/sport/batch` | 500        | High-volume, background jobs |

→ See the [Batch Ingestion Guide](/guides/events/batch-ingestion) for patterns and examples.

## Required Fields

All domain events share these required fields:

| Field      | Type   | Description                        |
| ---------- | ------ | ---------------------------------- |
| `org_id`   | string | Your organization ID               |
| `brand_id` | string | The brand where the event occurred |
| `event`    | string | The specific event (e.g., `open`)  |

## Timestamps

Always include event timestamps in the domain payload (`registered_at`, `transaction_dt`, `bet_dt`). Atlas uses them for:

* Accurate time-series analytics
* Correct ordering of events
* Compliance audit trails

Use ISO 8601 format in UTC, e.g. `"2026-03-11T14:30:00Z"`.

<Tip>
  If your system generates events in bulk (e.g., settling bets after a game), use the actual
  event time in fields like `bet_dt` / `transaction_dt` / `registered_at` rather than current time.
  This ensures analytics reflect reality, not ingestion time.
</Tip>