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

# Balance

> GET /v2/balance — retrieve your current account balance broken down by currency and sub-account.

## Response `200 OK`

### Response fields

| Field                          | Type   | Description                                                                             |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------- |
| `calculated_BRL_total_balance` | float  | Approximate BRL-equivalent of every balance combined                                    |
| `balances`                     | object | Keyed by ticker (`USDT`, `USDC`, `BTC`, `BRL`), then by currency-and-network beneath it |

### Sub-account buckets

Each currency entry breaks down into four buckets:

| Field        | Description                                       |
| ------------ | ------------------------------------------------- |
| `available`  | Immediately withdrawable                          |
| `in_transit` | In transit while a transaction is being processed |
| `to_receive` | Expected to arrive from an ongoing transaction    |
| `blocked`    | Frozen for chargebacks or compliance holds        |

`calculated_BRL_balance` at the currency level is the BRL-equivalent sum of all sub-accounts for that currency.

<Warning>
  **The BRL figures are an approximation, not an executable quote.** BRL converts at `1.0` and BTC at its own reference price, but every other currency is converted using the USD reference price. Use these values for display and reconciliation, never to size a trade — call [Reference Quote](/api-reference/conversions/ref-quote) for a real rate.
</Warning>

<Note>
  The keys inside `balances` are ledger account labels, not currency codes. They vary with account configuration and are not stable identifiers — do not key your own storage on them, and do not parse a currency code out of them. Use [Statement](/api-reference/account/statement)'s `account.currency` when you need the code.
</Note>

## Status codes

| HTTP  | When                                                           |
| ----- | -------------------------------------------------------------- |
| `200` | Success                                                        |
| `401` | Missing or invalid `api-key`                                   |
| `500` | Internal error, including an account with no ledger set up yet |

An account that has no ledger accounts provisioned returns `500`, not `404` or an empty balance.

<RequestExample>
  ```bash cURL theme={null}
  curl https://checkout.noxpay.io/v2/balance \
    -H "api-key: <key>"
  ```

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

  response = requests.get(
      "https://checkout.noxpay.io/v2/balance",
      headers={"api-key": "<key>"},
  )
  print(response.json())
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://checkout.noxpay.io/v2/balance", {
    headers: { "api-key": "<key>" },
  });
  const data = await response.json();
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={null}
  {
    "calculated_BRL_total_balance": 1234.56,
    "balances": {
      "USDT": {
        "calculated_BRL_balance": 500.00,
        "USDT TRC20": {
          "calculated_BRL_balance": 500.00,
          "available": 100.00,
          "in_transit": 10.00,
          "to_receive": 5.00,
          "blocked": 0.00
        }
      },
      "BRL": {
        "calculated_BRL_balance": 734.56,
        "BRL": {
          "calculated_BRL_balance": 734.56,
          "available": 734.56,
          "in_transit": 0.00,
          "to_receive": 0.00,
          "blocked": 0.00
        }
      }
    }
  }
  ```
</ResponseExample>