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

# Balance Guide

> Check your merchant balance before initiating withdrawals

# Balance API

Use the Balance API to check your merchant account balance. This is especially important before initiating withdrawals to ensure sufficient funds.

<Info>
  API v1 Balance requests require the `balance.read` or `balance.view` scope on
  your API key. API v2 merchants use HMAC authentication with the same balance
  permissions.
</Info>

## Get Balance by Currency

Retrieve the balance for a specific currency.

```bash theme={null}
curl -X GET "https://api.lux-core.io/api/v1/balance?currency=ARS" \
  -H "X-API-Key: qp_test_sk_your_key"
```

API v2 merchants use the same response format through the HMAC-authenticated endpoint:

```bash theme={null}
curl -X GET "https://api.lux-core.io/api/v2/balance?currency=ARS" \
  -H "X-Merchant-Id: 123" \
  -H "X-Timestamp: <unix_timestamp_seconds>" \
  -H "X-Nonce: <unique_nonce>" \
  -H "X-Signature-Version: v1" \
  -H "X-Signature: hmac_sha256=<signature>"
```

### Query Parameters

| Parameter      | Required | Default | Description                                                           |
| -------------- | :------: | ------- | --------------------------------------------------------------------- |
| `currency`     |    No    | `MXN`   | ISO 4217 currency code (`ARS`, `AUD`, `LKR`, `MXN`, `TRY`, `UYU`)     |
| `balance_type` |    No    | `main`  | Balance type: `main`, `deposit`, `withdrawal`, `commission`, `frozen` |

### Response

```json theme={null}
{
  "success": true,
  "merchant_id": 123,
  "currency": "ARS",
  "balance_type": "main",
  "balance_amount": "1500000",
  "available_amount": "1200000",
  "frozen_amount": "300000",
  "new_balance": 1500000,
  "available_balance": 1200000
}
```

## Get All Balances

Retrieve balances for all currencies at once.

```bash theme={null}
curl -X GET "https://api.lux-core.io/api/v1/balance/all" \
  -H "X-API-Key: qp_test_sk_your_key"
```

API v2 merchants can request all balances with HMAC authentication:

```bash theme={null}
curl -X GET "https://api.lux-core.io/api/v2/balance/all" \
  -H "X-Merchant-Id: 123" \
  -H "X-Timestamp: <unix_timestamp_seconds>" \
  -H "X-Nonce: <unique_nonce>" \
  -H "X-Signature-Version: v1" \
  -H "X-Signature: hmac_sha256=<signature>"
```

### Response

```json theme={null}
{
  "success": true,
  "merchant_id": 123,
  "balances": [
    {
      "currency": "ARS",
      "balance_type": "main",
      "balance_amount": "1500000",
      "available_amount": "1200000",
      "frozen_amount": "300000"
    },
    {
      "currency": "MXN",
      "balance_type": "main",
      "balance_amount": "850000",
      "available_amount": "850000",
      "frozen_amount": "0"
    }
  ],
  "total_balances": 2
}
```

## Response Fields

| Field               | Type    | Description                                                              |
| ------------------- | ------- | ------------------------------------------------------------------------ |
| `balance_type`      | string  | Balance type: `main`, `deposit`, `withdrawal`, `commission`, or `frozen` |
| `balance_amount`    | string  | Total balance amount in **minor units** (centavos)                       |
| `available_amount`  | string  | Amount available for withdrawals, in **minor units** (centavos)          |
| `frozen_amount`     | string  | Amount frozen by pending withdrawals, in **minor units**                 |
| `new_balance`       | integer | Total balance as integer (same value as `balance_amount`)                |
| `available_balance` | integer | Available balance as integer (same value as `available_amount`)          |

<Warning>
  All monetary values are returned as **strings in minor units** (centavos). For
  example, `"1200000"` = 12,000.00 ARS. Use integer or decimal arithmetic to
  avoid floating-point precision issues.
</Warning>

## API v2 HMAC Signing

For `GET` balance requests, sign an empty raw body. The empty body SHA-256 hash is:

```text theme={null}
e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

Canonical string examples:

```text theme={null}
v1.<timestamp>.<nonce>.GET./api/v2/balance?currency=ARS&balance_type=main.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
v1.<timestamp>.<nonce>.GET./api/v2/balance/all.e3b0c44298fc1c149afbf4c8996fb92427ae41e4649b934ca495991b7852b855
```

See [Authentication](/authentication#api-v2-hmac-requests) for the complete HMAC header and signing rules.

<Info>
  **Available vs Frozen:**

  * **`available_amount`** — funds you can use right now for new withdrawals
  * **`frozen_amount`** — funds reserved by pending withdrawals that have not yet completed. These are temporarily locked and cannot be used for new operations

  When a withdrawal completes, frozen funds are released and debited. If a withdrawal fails, frozen funds return to `available_amount`.
</Info>

## Usage Example: Check Balance Before Withdrawal

<CodeGroup>
  ```javascript Node.js theme={null}
  const balance = await fetch(
    "https://api.lux-core.io/api/v1/balance?currency=ARS",
    {
      headers: { "X-API-Key": "qp_test_sk_your_key" },
    },
  ).then((r) => r.json());

  const availableMinor = parseInt(balance.available_amount, 10);
  const payoutAmountMinor = 250000; // 2,500.00 ARS

  if (availableMinor < payoutAmountMinor) {
    console.error(
      `Insufficient balance: ${availableMinor} < ${payoutAmountMinor}`,
    );
  } else {
    // Proceed with withdrawal
  }
  ```

  ```python Python theme={null}
  import requests

  balance = requests.get(
      "https://api.lux-core.io/api/v1/balance",
      headers={"X-API-Key": "qp_test_sk_your_key"},
      params={"currency": "ARS"}
  ).json()

  available = int(balance["available_amount"])
  payout_amount = 250000  # 2,500.00 ARS

  if available < payout_amount:
      print(f"Insufficient balance: {available} < {payout_amount}")
  else:
      # Proceed with withdrawal
      pass
  ```
</CodeGroup>

## How Balance Changes

| Event                | Effect                                                                     |
| -------------------- | -------------------------------------------------------------------------- |
| Deposit completed    | `available_amount` increases by `net_amount` (deposit amount minus fee)    |
| Withdrawal created   | `frozen_amount` increases, `available_amount` decreases by the same amount |
| Withdrawal completed | `frozen_amount` decreases (funds sent to recipient)                        |
| Withdrawal failed    | `frozen_amount` decreases, `available_amount` increases (funds unfrozen)   |
| Refund processed     | `available_amount` decreases by refund amount                              |