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

# Saldo

> Leia o saldo da sua conta TroqPay direto pela API.

# Saldo

`GET /v1/balance` te devolve o saldo agregado da sua conta — quanto entrou, quanto foi cobrado em taxas, quanto está disponível para saque e quanto está retido.

Tudo em BRL, como string decimal.

## Quando usar

<CardGroup cols={2}>
  <Card title="Para mostrar saldo no seu painel">
    Se o seu produto tem uma área `meu saldo`, leia direto da API em vez de manter um espelho local.
  </Card>

  <Card title="Antes de fazer um saque">
    Confira `availableAmount` antes de pedir um saque pelo app ou pela API para garantir que o valor está disponível.
  </Card>
</CardGroup>

## Como funciona

<Steps>
  <Step title="Faça uma chamada autenticada">
    `GET https://api.troqpay.com/v1/balance` com `Authorization: Bearer trq_test_...` ou `trq_live_...`.
  </Step>

  <Step title="Leia os campos">
    A resposta traz oito valores, todos em BRL como string decimal.
  </Step>

  <Step title="Use availableAmount como referência de saque">
    `availableAmount` é o que está realmente liberado para você sacar agora.
  </Step>
</Steps>

## Exemplo

```bash theme={null}
curl https://api.troqpay.com/v1/balance \
  -H "Authorization: Bearer trq_test_xxx"
```

```json theme={null}
{
  "livemode": false,
  "currency": "BRL",
  "grossAmount": "5430.00",
  "feeAmount": "54.30",
  "pendingAmount": "129.90",
  "availableAmount": "5245.80",
  "reservedAmount": "0.00",
  "blockedAmount": "0.00"
}
```

## Como ler cada campo

| Campo             | O que significa                                                                                                                         |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `livemode`        | `true` para chaves `trq_live_`, `false` para `trq_test_`                                                                                |
| `currency`        | Sempre `BRL`                                                                                                                            |
| `grossAmount`     | Total bruto recebido (antes das taxas)                                                                                                  |
| `feeAmount`       | Total de taxas cobradas pela TroqPay. A taxa é 1% por checkout, com piso de R\$0,99 — em valores baixos a taxa efetiva fica acima de 1% |
| `pendingAmount`   | Valores ainda em liquidação                                                                                                             |
| `availableAmount` | Disponível para saque agora                                                                                                             |
| `reservedAmount`  | Reservado para saques já solicitados                                                                                                    |
| `blockedAmount`   | Retido (por exemplo, valores em disputa ou bloqueio operacional)                                                                        |

<Warning>
  Os valores são **strings decimais**, não números. Em JavaScript, evite `Number(balance.availableAmount)` — você pode perder precisão. Use uma biblioteca decimal (`bignumber.js`, `decimal.js`) ou `BigInt` em centavos.
</Warning>

## O que esperar em cenários diferentes

| Cenário                          | Comportamento                                                |
| -------------------------------- | ------------------------------------------------------------ |
| Conta em produção sem `APPROVED` | `403 forbidden`                                              |
| Chave sem `BALANCE:READ`         | `403 api_key_scope_forbidden`                                |
| Sem checkouts ainda              | Todos os campos em `"0.00"`                                  |
| Saque solicitado, ainda não pago | O valor sai de `availableAmount` e entra em `reservedAmount` |
| Saque concluído                  | O valor sai de `reservedAmount` e some do saldo              |

## Próximos passos

<CardGroup cols={3}>
  <Card title="Solicitar saque" href="/flows/saques">
    Solicite saques (Pix ou carteira USDT) com o destino aprovado na conta.
  </Card>

  <Card title="Boas práticas" href="/flows/boas-praticas-checkout">
    Veja o que vale a pena salvar em logs ao operar saldo e checkouts.
  </Card>

  <Card title="API Reference" href="/api-reference">
    Consulte o schema completo de `GET /v1/balance` na referência.
  </Card>
</CardGroup>

## Precisa de ajuda para seguir?

<CardGroup cols={3}>
  <Card title="Revisar autenticação" href="/authentication">
    Confira chaves, ambiente e o gate de produção antes de chamar saldo em LIVE.
  </Card>

  <Card title="Revisar erros" href="/flows/errors">
    Veja o que `403 forbidden` ou `401 unauthorized` querem dizer.
  </Card>

  <Card title="Abrir o app" href="https://app.troqpay.com">
    Confira o saldo no app para comparar com o que a API devolve.
  </Card>
</CardGroup>