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

# Saldo

> GET /v2/balance — retorna o saldo atual da sua conta dividido por moeda e sub-conta.

## Campos do response

| Campo                          | Tipo   | Descrição                                                                               |
| ------------------------------ | ------ | --------------------------------------------------------------------------------------- |
| `calculated_BRL_total_balance` | float  | Equivalente aproximado em BRL de todos os saldos somados                                |
| `balances`                     | object | Indexado por ticker (`USDT`, `USDC`, `BTC`, `BRL`), depois por moeda-e-rede abaixo dele |

### Buckets de sub-conta

Cada entrada de moeda é dividida em quatro buckets:

| Campo        | Descrição                                                |
| ------------ | -------------------------------------------------------- |
| `available`  | Disponível para saque imediato                           |
| `in_transit` | Em trânsito enquanto uma transação está sendo processada |
| `to_receive` | Previsto para chegar de uma transação em andamento       |
| `blocked`    | Bloqueado para chargebacks ou retenções de conformidade  |

`calculated_BRL_balance` no nível da moeda é a soma em equivalente BRL de todas as sub-contas para aquela moeda.

<Warning>
  **Os valores em BRL são uma aproximação, não uma cotação executável.** BRL converte a `1.0` e BTC pelo seu próprio preço de referência, mas todas as outras moedas são convertidas usando o preço de referência do USD. Use esses valores para exibição e conciliação, nunca para dimensionar uma operação — chame [Cotação de Referência](/pt/api-reference/conversions/ref-quote) para uma taxa real.
</Warning>

<Note>
  As chaves dentro de `balances` são rótulos de conta do ledger, não códigos de moeda. Elas variam com a configuração da conta e não são identificadores estáveis — não indexe seu próprio armazenamento por elas, e não tente extrair um código de moeda delas. Use o campo `account.currency` do [Extrato](/pt/api-reference/account/statement) quando precisar do código.
</Note>

## Códigos de retorno

| HTTP  | Quando                                                |
| ----- | ----------------------------------------------------- |
| `200` | Sucesso                                               |
| `401` | `api-key` ausente ou inválida                         |
| `500` | Erro interno, incluindo conta sem ledger provisionado |

Uma conta sem contas de ledger provisionadas devolve `500`, não `404` nem um saldo vazio.

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