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

# Consultando saldos

> Como consultar saldos, entries, taxas e liquidações.

A Astron Pay expõe consultas de leitura sobre o ledger. Use-as para reconciliar com seu sistema e monitorar fluxo.

## Saldo de um receiver

```bash theme={null}
curl https://api.astronpay.co/api/v1/ledger/receivers/$RECEIVER_ID/balance \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

Resposta:

```json theme={null}
{
  "receiverId": "rcv_01hxy...",
  "balances": [
    { "accountType": "RECEIVER_BRL", "currency": "BRL", "balance": "0.00" },
    { "accountType": "RECEIVER_CRYPTO", "currency": "USDC", "balance": "199.50" }
  ]
}
```

## Histórico de entries

```bash theme={null}
curl "https://api.astronpay.co/api/v1/ledger/receivers/$RECEIVER_ID/entries?limit=50" \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

Resposta:

```json theme={null}
{
  "data": [
    {
      "id": "entry_01hxy...",
      "type": "CREDIT",
      "amount": "1000.00",
      "balanceAfter": "1000.00",
      "referenceType": "ORDER",
      "referenceId": "ord_01hxy...",
      "description": "Payin PIX recebido",
      "createdAt": "2026-04-16T18:31:00Z"
    }
  ],
  "total": 42,
  "page": 1,
  "limit": 50
}
```

Use `page` e `limit` para paginar:

```bash theme={null}
curl "https://api.astronpay.co/api/v1/ledger/receivers/$RECEIVER_ID/entries?page=2&limit=50" \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

## Saldo de taxas do merchant

```bash theme={null}
curl https://api.astronpay.co/api/v1/ledger/fees/balance \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

Resposta:

```json theme={null}
{
  "merchantId": "mer_01hxy...",
  "balance": "1250.00",
  "currency": "BRL"
}
```

Retorna quanto há acumulado na conta `MERCHANT_FEE` ainda não liquidado.

## Liquidações

```bash theme={null}
curl https://api.astronpay.co/api/v1/ledger/settlements \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

Filtre por status:

```bash theme={null}
curl "https://api.astronpay.co/api/v1/ledger/settlements?status=PROCESSED" \
  -H "x-api-key: $API_KEY" -H "x-api-secret: $API_SECRET"
```

## Reconciliação

Use `idempotencyKey` para mapear entries aos seus eventos internos. O padrão é:

* `payin:pix_received:{orderId}`
* `payin:platform_fee:{orderId}`
* `payin:merchant_fee:{orderId}`
* `payin:conversion:{orderId}`
* `payin:transfer_out:{orderId}`
* `payout:deposit:{orderId}`
* `payout:conversion:{orderId}`
* `payout:platform_fee:{orderId}`
* `payout:merchant_fee:{orderId}`
* `payout:pix_out:{orderId}`

Entries com o mesmo `idempotencyKey` representam o mesmo evento lógico — nunca duplicam.

## Conceitos relacionados

* [Ledger e liquidações](/concepts/ledger-settlements) — modelo de partidas dobradas e tipos de conta.
* [Taxas](/concepts/fees) — como as taxas são contabilizadas.