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

# AML Pattern Detection

> In-house rules engine. Real-time check on withdrawals ≥ $10,000; async pattern detection on everything else.

Anti-money-laundering monitoring is run in-house — no third-party vendor. Real-time on big withdrawals; fire-and-forget for everything else, with pattern detection in the background and webhooks within 5 minutes.

<Warning>
  Never expose rule codes, descriptions, or risk scores to end users. **Tipping-off prohibitions apply.** Use generic language only ("Account under review").
</Warning>

## Hybrid model

| Path                                  | Trigger                  | Latency                                                            |
| ------------------------------------- | ------------------------ | ------------------------------------------------------------------ |
| **Real-time** — `POST /v1/aml/screen` | Withdrawals ≥ USD 10,000 | \< 200 ms — returns `allow` / `hold` / `reject`                    |
| **Async** — `POST /v1/aml/event`      | All other transactions   | 202 acknowledgement \< 50 ms; webhook within 5 min if a rule trips |

## Rule catalogue

| Code      | Pattern              | Trigger                                                                  | Mode      | Severity |
| --------- | -------------------- | ------------------------------------------------------------------------ | --------- | -------- |
| **R-001** | Large withdrawal     | Single withdrawal ≥ USD 10K                                              | real-time | 7        |
| **R-002** | Velocity             | 5+ deposits in 1 hour                                                    | async     | 6        |
| **R-003** | Structuring          | 10+ deposits within \$100 of a KYC tier in 7 days                        | async     | 9        |
| **R-004** | Minimal play         | Deposit > \$5K with \< 5% wagered in next 24h                            | async     | 7        |
| **R-005** | Round-tripping       | Deposit + withdrawal within 5% within 24h                                | async     | 8        |
| **R-006** | Multi-account        | Same `payment_method_fingerprint` on 3+ users                            | async     | 8        |
| **R-007** | Geographic anomaly   | Login country ≠ deposit country in same session                          | async     | 5        |
| **R-008** | Dormant reactivation | 90+ days idle then >\$5K activity in 24h                                 | async     | 6        |
| **R-009** | Aggregate threshold  | Deposit + withdrawal + wager ≥ USD 10K in a rolling window (default 24h) | async     | 7        |

`risk_score = min(sum(triggered_severities) × 10, 100)`.

R-009 complements R-001: where R-001 fires on a single large withdrawal, R-009 catches structured deposits and combined deposit/withdrawal/wager activity that crosses USD 10,000 in aggregate within the window.
Decision: `<50` allow · `50–79` hold · `80+` reject.

## Endpoints

| Method | Path             | Description                                                                  |
| ------ | ---------------- | ---------------------------------------------------------------------------- |
| `POST` | `/v1/aml/screen` | Real-time check for large withdrawals. **Mandatory ≥ \$10K.**                |
| `POST` | `/v1/aml/event`  | Fire-and-forget transaction event. Idempotent on `(tenant, transaction_id)`. |
| `GET`  | `/v1/aml/cases`  | Open and closed AML cases for a user.                                        |

### `POST /v1/aml/screen`

```bash theme={null}
curl https://sandbox.api.anunnakielite.com/v1/aml/screen \
  -H "Authorization: Bearer cur_sk_test_EXAMPLEKEY123456789012345678901234" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "rt_usr_8a2f1c",
    "withdrawal_id": "wd_99f02a",
    "amount_cents": 1500000,
    "currency": "USD",
    "payment_method": "wire",
    "destination_country": "FR"
  }'
```

Allow:

```json theme={null}
{
  "decision": "allow",
  "user_id": "rt_usr_8a2f1c",
  "withdrawal_id": "wd_99f02a",
  "rules_evaluated": ["R-001"],
  "rules_triggered": [],
  "risk_score": 12
}
```

Hold:

```json theme={null}
{
  "decision": "hold",
  "user_id": "rt_usr_8a2f1c",
  "withdrawal_id": "wd_99f02a",
  "case_id": "aml_case_42a1",
  "rules_triggered": ["R-001", "R-005"],
  "risk_score": 78,
  "user_message": "Withdrawal under review. We will contact you within 48 hours.",
  "estimated_review_time": "24-48h"
}
```

**Decision handling:** `allow` → release; `hold` → keep funds blocked, await `aml.cleared` webhook; `reject` → return funds to player balance, log for SAR filing, do **not** process payout.

### `POST /v1/aml/event`

Stream every deposit, wager, withdrawal, settlement, login, and account update.

```bash theme={null}
curl https://sandbox.api.anunnakielite.com/v1/aml/event \
  -H "Authorization: Bearer cur_sk_test_EXAMPLEKEY123456789012345678901234" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "rt_usr_8a2f1c",
    "event_type": "deposit",
    "transaction_id": "tx_8a2f1c",
    "amount_cents": 250000,
    "currency": "USD",
    "payment_method": "card",
    "metadata": {
      "ip_country": "FR",
      "card_country": "FR",
      "session_id": "sess_a1b2c3"
    },
    "occurred_at": "2026-05-24T15:02:00Z"
  }'
```

Acknowledgement (always `202 Accepted`):

```json theme={null}
{
  "event_id": "aml_evt_99f02a",
  "transaction_id": "tx_8a2f1c",
  "received_at": "2026-05-24T15:02:00.234Z",
  "processing": "queued"
}
```

| Event type       | When to send                                            |
| ---------------- | ------------------------------------------------------- |
| `deposit`        | Every deposit attempt — success and failure.            |
| `withdrawal`     | Every withdrawal request, including under \$10K.        |
| `wager`          | Every bet placed (settled or pending).                  |
| `settlement`     | Every market settlement with player payouts.            |
| `login`          | Every player login (used for R-007 geographic anomaly). |
| `account_update` | Payment method or address change.                       |

A duplicate `transaction_id` returns `processing: "duplicate_already_queued"` without reprocessing.

### `GET /v1/aml/cases`

Returns case codes only — never rule descriptions or context data.

```json theme={null}
{
  "user_id": "rt_usr_8a2f1c",
  "open_cases": 1,
  "cases": [
    {
      "case_id": "aml_case_42a1",
      "opened_at": "2026-05-24T15:07:22Z",
      "status": "under_review",
      "rules_triggered": ["R-003", "R-005"],
      "risk_score": 65
    }
  ]
}
```

## Webhooks

| Event                | Fires when                                              |
| -------------------- | ------------------------------------------------------- |
| `aml.flagged`        | An async rule tripped — case opened.                    |
| `aml.held`           | Real-time hold confirmed by compliance — funds blocked. |
| `aml.cleared`        | Case reviewed and dismissed — release funds.            |
| `aml.escalated`      | Case requires SAR (Suspicious Activity Report) filing.  |
| `aml.account_frozen` | Account suspended pending investigation.                |

```json theme={null}
{
  "event": "aml.flagged",
  "event_id": "evt_aml_a1b2c3",
  "timestamp": "2026-05-24T15:07:22Z",
  "data": {
    "case_id": "aml_case_42a1",
    "user_id": "rt_usr_8a2f1c",
    "rules_triggered": ["R-003", "R-005"],
    "risk_score": 65,
    "recommended_action": "review_user_activity",
    "transactions_to_review": ["tx_8a2f1c", "tx_3d4e5f"]
  }
}
```

Webhook payloads include rule **codes only** — never descriptions or rule context.

## Operator policy

* **Vendor:** in-house (no third-party — cheaper, full control).
* **Hybrid:** real-time on USD 10K+, async on everything else.
* **Rule count:** 8 at launch; tuned monthly based on false-positive rates.
* **Review SLA:** 48 hours.
* **SAR filing:** Anunnaki files reports with the KGC where required.

## Error codes

| Status | Code                                      |
| ------ | ----------------------------------------- |
| 400    | `invalid_event`                           |
| 401    | `unauthorized`                            |
| 409    | `duplicate_event` (safe to ignore)        |
| 429    | `rate_limited` (1000/min on `/aml/event`) |
| 503    | `queue_unavailable` (retry with backoff)  |