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

# Consultar saldo

> Consulte o saldo disponível e o reservado da sua conta NyxPag com GET /balance e entenda o que cada valor significa antes de transferir.

`GET /balance` devolve quanto você tem na conta agora, separado em **disponível** e **reservado**. Exige a permissão `balance:read`.

```http theme={"dark"}
GET https://api.nyxpag.com.br/v1/balance
```

<CodeGroup>
  ```bash cURL theme={"dark"}
  curl https://api.nyxpag.com.br/v1/balance \
    -H "Authorization: Bearer $NYXPAG_API_KEY"
  ```

  ```javascript JavaScript theme={"dark"}
  const res = await fetch("https://api.nyxpag.com.br/v1/balance", {
    headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` },
  });
  const { data } = await res.json();
  console.log(`Disponível: R$ ${data.available}  Reservado: R$ ${data.reserved}`);
  ```

  ```python Python theme={"dark"}
  import os
  import requests

  res = requests.get(
      "https://api.nyxpag.com.br/v1/balance",
      headers={"Authorization": f"Bearer {os.environ['NYXPAG_API_KEY']}"},
      timeout=15,
  )
  data = res.json()["data"]
  print(f"Disponível: R$ {data['available']}  Reservado: R$ {data['reserved']}")
  ```

  ```php PHP theme={"dark"}
  <?php
  $ch = curl_init('https://api.nyxpag.com.br/v1/balance');
  curl_setopt_array($ch, [
      CURLOPT_RETURNTRANSFER => true,
      CURLOPT_HTTPHEADER => ['Authorization: Bearer ' . getenv('NYXPAG_API_KEY')],
  ]);
  $data = json_decode(curl_exec($ch), true)['data'];
  echo "Disponível: R$ {$data['available']}  Reservado: R$ {$data['reserved']}";
  ```
</CodeGroup>

## A resposta

```json theme={"dark"}
{
  "success": true,
  "data": {
    "currency": "BRL",
    "available": 1250.5,
    "reserved": 100
  },
  "requestId": "req_01H..."
}
```

| Campo | Tipo | Descrição |
| - | - | - |
| `data.currency` | string | Sempre `BRL` |
| `data.available` | number | Saldo que você pode usar agora, em reais |
| `data.reserved` | number | Saldo que é seu, mas ainda não está livre, em reais |
| `requestId` | string | Identificador da requisição, para o suporte |

Os valores são reais decimais: `1250.5` é R\$ 1.250,50. Uma conta nova responde com os dois campos em `0`.

## Disponível e reservado

| | O que é | Dá para transferir? |
| - | - | - |
| **`available`** | Saldo livre | Sim |
| **`reserved`** | Saldo que ainda não está livre | Não, por enquanto |

O saldo fica **reservado** em duas situações:

* **Transferência em andamento.** Quando você solicita uma transferência, o valor sai do disponível e fica reservado até a operação terminar. Se ela der `approved`, o valor é debitado de vez. Se der `failed`, ele volta para o disponível.
* **Reserva da conta.** Dependendo da configuração da sua conta, uma parte das vendas aprovadas fica retida por um prazo antes de virar disponível.

<Note>
  Reservado não é perdido. É seu e será liberado ou debitado quando a operação que o originou terminar.
</Note>

## Confira o saldo antes de transferir

Uma transferência acima do disponível é recusada com `422` (`operation_refused`, "Saldo insuficiente"). Evite a falha conferindo antes, lembrando que a tarifa também sai do saldo quando `coverFee` é `true` (o padrão das transferências).

```javascript JavaScript theme={"dark"}
async function canTransfer(amount, feeEstimate = 0) {
  const res = await fetch("https://api.nyxpag.com.br/v1/balance", {
    headers: { Authorization: `Bearer ${process.env.NYXPAG_API_KEY}` },
  });
  const { data } = await res.json();
  return data.available >= amount + feeEstimate;
}
```

<Warning>
  O saldo muda a cada Pix recebido e a cada transferência. A conferência acima reduz falhas, mas não elimina a corrida entre duas operações simultâneas. Sempre trate o `422` de saldo insuficiente.
</Warning>

<CardGroup cols={2}>
  <Card title="Transferir por Pix" icon="send" href="/guides/pix/transferir">
    Envie saldo por chave, Copia e Cola ou QR Code.
  </Card>

  <Card title="Consultar saldo" icon="code" href="/api-reference/saldo/consultar-saldo">
    Referência completa do endpoint.
  </Card>
</CardGroup>


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.