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

# Consultar saldo da conta

> Recupere o saldo disponível e a moeda da conta da YCloud.

## O que é

A Balance API retorna o saldo disponível para a conta autenticada da
YCloud. Use-a para monitoramento operacional, alertas de faturamento e verificações
de autenticação.

## Antes de começar

* Armazene sua chave de API da YCloud com segurança.
* Decida com que frequência seu aplicativo precisa das informações de saldo.
* Defina um limite de alerta que reflita o volume de envio esperado.

## Como funciona

O endpoint é somente leitura e sempre se aplica à conta identificada pela
chave de API. Ele não aceita um ID de conta no caminho ou no corpo da requisição.

Use-o em tarefas de monitoramento, e não antes de cada envio de mensagem. Verificações
frequentes de saldo por mensagem aumentam a latência e não reservam fundos.

## Requisição

`GET /balance`

```bash theme={"theme":{"light":"github-light","dark":"github-dark"}}
curl https://api.ycloud.com/v2/balance \
  --header "X-API-Key: $YCLOUD_API_KEY" \
  --header "Accept: application/json"
```

## Resposta

```json theme={"theme":{"light":"github-light","dark":"github-dark"}}
{
  "amount": 190.0765,
  "currency": "USD"
}
```

| Campo | Descrição |
| - | - |
| `amount` | Saldo disponível da conta. |
| `currency` | Moeda utilizada pela conta. |

## Orientações de monitoramento

* Emita alertas antes que o saldo atinja um nível que possa interromper o tráfego
  de produção.
* Inclua a moeda nos painéis e alertas.
* Use um alerta separado para falhas de API, evitando que uma verificação indisponível seja confundida
  com um saldo zerado.
* Restrinja o acesso aos dados de saldo como informações financeiras.

## Limites e solução de problemas

* Uma resposta de saldo bem-sucedida verifica a chave de API e a URL base.
* Um saldo baixo pode afetar produtos de mensagens faturáveis, mesmo quando a autenticação
  da API for bem-sucedida.
* Não presuma que o valor esteja em USD; leia `currency`.
* Evite registrar a chave de API nos logs de saída do monitoramento.

<Card title="Referência da Balance API" icon="wallet" href="/api-reference/balance/retrieve-balance">
  Inspecione o esquema completo de resposta e teste a requisição somente leitura.
</Card>


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