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

# Deposit Limits

> Player-set spending caps. Decreases apply instantly; increases enter a cooling-off period that scales with the increase.

KGC-mandated player-set deposit caps. Daily, weekly, or monthly rolling windows. **Limits are enforced, not advisory** — deposits over the limit are rejected at `/v1/limits/check`.

<Note>
  **Self-limitation changes are recorded for KGC s.229A reporting.** Every create, increase, decrease, and cancellation made through these endpoints is captured automatically. There is **no API-shape change for tenants** — keep calling the endpoints as documented; the regulatory reporting is handled on Anunnaki's side. See [KGC Compliance](/api-reference/kgc-compliance).
</Note>

## Limit types

| Limit type | API value       | Window           |
| ---------- | --------------- | ---------------- |
| Daily      | `limit_daily`   | Rolling 24 hours |
| Weekly     | `limit_weekly`  | Rolling 7 days   |
| Monthly    | `limit_monthly` | Rolling 30 days  |

## Cooling-off tiers (increases only)

| Scenario         | Cool-off | `cooloff_seconds` |
| ---------------- | -------- | ----------------- |
| First-time set   | Instant  | `0`               |
| Any decrease     | Instant  | `0`               |
| Increase ≤ 2×    | 24 hours | `86400`           |
| Increase 2× – 5× | 48 hours | `172800`          |
| Increase > 5×    | 7 days   | `604800`          |

Boundaries (exactly 2× and exactly 5×) land in the **lower** tier.

## Endpoints

| Method   | Path                | Description                                                |
| -------- | ------------------- | ---------------------------------------------------------- |
| `POST`   | `/v1/limits`        | Set or change a limit.                                     |
| `GET`    | `/v1/limits`        | List active limits for a user, with spend and reset times. |
| `POST`   | `/v1/limits/check`  | Pre-deposit gate — **call before every deposit.**          |
| `POST`   | `/v1/limits/commit` | Idempotent commit on `(tenant, transaction_id)`.           |
| `DELETE` | `/v1/limits/{id}`   | Cancel a pending increase.                                 |

### `POST /v1/limits`

```bash theme={null}
curl https://sandbox.api.anunnakielite.com/v1/limits \
  -H "Authorization: Bearer cur_sk_test_EXAMPLEKEY123456789012345678901234" \
  -H "Content-Type: application/json" \
  -d '{
    "user_id": "rt_usr_8a2f1c",
    "limit_type": "limit_daily",
    "amount_cents": 50000,
    "currency": "USD",
    "requested_at": "2026-05-24T14:32:00Z"
  }'
```

Increase response (cooling-off applied):

```json theme={null}
{
  "limit_id": "lim_7e3d99",
  "user_id": "rt_usr_8a2f1c",
  "limit_type": "limit_daily",
  "amount_cents": 50000,
  "currency": "USD",
  "current_limit_cents": 20000,
  "is_increase": true,
  "cooloff_seconds": 86400,
  "effective_from": "2026-05-25T14:32:00Z",
  "status": "pending"
}
```

### `POST /v1/limits/check`

```bash theme={null}
curl https://sandbox.api.anunnakielite.com/v1/limits/check \
  -H "Authorization: Bearer cur_sk_test_EXAMPLEKEY123456789012345678901234" \
  -H "Content-Type: application/json" \
  -d '{"user_id":"rt_usr_8a2f1c","amount_cents":15000,"currency":"USD"}'
```

Allowed:

```json theme={null}
{
  "allowed": true,
  "amount_cents": 15000,
  "would_remain_cents": 5000,
  "active_limits": ["limit_daily"]
}
```

Rejected:

```json theme={null}
{
  "allowed": false,
  "reason": "exceeds_limit",
  "breached_limit_type": "limit_daily",
  "limit_amount_cents": 20000,
  "already_spent_cents": 18000,
  "max_allowed_now_cents": 2000,
  "next_reset_at": "2026-05-25T00:00:00Z",
  "user_message": "This deposit would exceed your daily limit of USD 200.00."
}
```

<Warning>
  On `allowed:false`, display `user_message` verbatim and reject the deposit. Partial deposits are not permitted.
</Warning>

## Webhooks

| Event                  | Fires when                                                            |
| ---------------------- | --------------------------------------------------------------------- |
| `limit.created`        | First-time limit set.                                                 |
| `limit.activated`      | Pending increase has finished its cooling-off period and is now live. |
| `limit.decreased`      | A decrease (effective immediately).                                   |
| `limit.cancelled`      | User cancelled a pending increase.                                    |
| `limit.breach_attempt` | A deposit was rejected by `/check` (for monitoring).                  |

## Error codes

| Status | Code                                 |
| ------ | ------------------------------------ |
| 400    | `invalid_amount`, `unsupported_type` |
| 401    | `unauthorized`                       |
| 404    | `user_not_found`                     |
| 409    | `pending_change_exists`              |
| 422    | `below_minimum`                      |
| 429    | `rate_limited`                       |