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

# Balance

> How the balance works, per-request charges, and alerts

Your **balance** is a credit in MXN. You top it up (or receive it as a signup bonus). Each call to the gateway deducts its cost from the balance.

## How the balance is computed

```
Balance = SUM(amount_mxn) across all your credit_transactions
```

Transactions have types:

| Type          | Sign | When                                  |
| ------------- | ---- | ------------------------------------- |
| `bonus`       | `+`  | At signup (\$50 MXN free)             |
| `recharge`    | `+`  | When you complete a Stripe recharge   |
| `consumption` | `-`  | For each successful gateway call      |
| `refund`      | `+`  | Manual refund (coming soon)           |
| `adjustment`  | `±`  | Manual adjustments by our team (rare) |

## Visibility

* **Real-time** in the dashboard ([app.geekhub.mx](https://app.geekhub.mx/dashboard))
* **API endpoint** *(coming soon)*: `GET /v1/credits` will return your current balance
* **Response headers** *(coming soon)*: each response will include `x-geekhub-balance-mxn`

## Threshold and alerts

| Balance          | Behavior                                                         |
| ---------------- | ---------------------------------------------------------------- |
| `> $20 MXN`      | Normal service                                                   |
| `> $0 and < $20` | Normal service + "Low balance" card in dashboard                 |
| `≤ $0`           | Gateway responds **`402 insufficient_balance`** until you top up |

<Tip>
  Set up a cron on your end that checks your balance (when we enable `GET /v1/credits`) and fires an alert when you're below 1 day of typical usage.
</Tip>

## Per-request detail

In [/dashboard/usage](https://app.geekhub.mx/dashboard/usage) you have the full log; each request shows:

* Model used
* Tokens (in / out) or images / seconds
* Exact MXN cost
* P95 latency
* Status (200 / 4xx / 5xx)
* Timestamp

And in [/dashboard/billing](https://app.geekhub.mx/dashboard/billing) you have the detail per movement (recharges, bonuses, aggregated consumption).

## Race conditions

The balance deduction is **atomic at the Postgres transaction level**: the `consume_credit_on_request()` trigger uses `pg_advisory_xact_lock` per org to serialize concurrent consumption. Even with 100 parallel requests, `balance_after` always reflects the correct order.

<Info>
  **Zero double-charging.** Each failed request with `cost_mxn > 0` does not generate a `consumption` (the trigger filters it).
</Info>