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

# Consulta de Saldo

> Saldo disponível e pendente da conta em centavos MXN

## Visão Geral

O endpoint `GET /api/balance` retorna o saldo da conta autenticada em **centavos MXN** (inteiros). Há dois campos:

* **`availableCentavos`** — saldo disponível para enviar cash-out SPEI
* **`pendingCentavos`** — saldo bloqueado (cash-out em processamento, cash-in confirmando)

## Endpoint

### GET /api/balance

#### Headers

```
Authorization: Bearer {token}
```

#### Request

```bash theme={"system"}
curl -X GET https://sandbox.mx.ntxpay.com/api/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9..."
```

#### Response (200)

```json theme={"system"}
{
  "availableCentavos": 4873490,
  "pendingCentavos": 0,
  "currency": "MXN"
}
```

`4873490` centavos = **\$48.734,90 MXN**.

## Estrutura da Resposta

<ResponseField name="availableCentavos" type="integer">
  Saldo disponível em centavos MXN. Use este valor para validar antes de um cash-out.
</ResponseField>

<ResponseField name="pendingCentavos" type="integer">
  Saldo pendente em centavos MXN. Inclui cash-out em processamento e cash-in aguardando a confirmação final da liquidação.
</ResponseField>

<ResponseField name="currency" type="string">
  Sempre `MXN` no escopo México.
</ResponseField>

## Exemplo em Node.js

```typescript theme={"system"}
import axios from 'axios';

async function getBalance(token: string) {
  const { data } = await axios.get('https://sandbox.mx.ntxpay.com/api/balance', {
    headers: { Authorization: `Bearer ${token}` },
  });

  const availableMXN = (data.availableCentavos / 100).toFixed(2);
  const pendingMXN = (data.pendingCentavos / 100).toFixed(2);

  console.log(`Available: $${availableMXN} MXN`);
  console.log(`Pending:   $${pendingMXN} MXN`);
  return data;
}
```

## Validação Antes do Cash-Out

```typescript theme={"system"}
async function safeSpeiCashOut(amountCentavos: number, token: string, dto: any) {
  const balance = await getBalance(token);

  if (balance.availableCentavos < amountCentavos) {
    throw new Error(
      `Insufficient balance: available ${balance.availableCentavos}, ` +
      `requested ${amountCentavos} (in centavos)`,
    );
  }

  return axios.post('https://sandbox.mx.ntxpay.com/api/spei/cash-out', dto, {
    headers: { Authorization: `Bearer ${token}` },
  });
}
```

<Info>
  Mesmo validando o saldo antes, o cash-out pode falhar com `400` se outro cash-out concorrente consumir o saldo. Trate o erro `400` como "saldo insuficiente" no momento da chamada.
</Info>

## Códigos de Resposta

| Código | Significado               |
| ------ | ------------------------- |
| `200`  | Saldo consultado          |
| `401`  | Token inválido ou ausente |
| `502`  | `account-ms` indisponível |

## Próximos Passos

<CardGroup cols={2}>
  <Card title="SPEI Cash-Out" href="/pt-br/guides/spei-cash-out">
    Envie uma transferência SPEI usando o saldo disponível
  </Card>
</CardGroup>