---
title: "BRL balance (custody) — available, on hold, next releases"
method: GET
path: "/saldo"
tags: ["Conta"]
---

# BRL balance (custody) — available, on hold, next releases

`GET /saldo`

## Request

- Base URL: `https://api.luniumpay.com`
- URL: `https://api.luniumpay.com/saldo`
- Auth: API key in header `X-API-Key`

Saldo BRL da casa ou da subconta customer_ref. Retorna disponível, bloqueado, próximas liberações e condições efetivas de custódia. Taxas e carência dependem da chave. Retenção local da cobrança, retenção do provedor e carência do saldo são regras distintas. Somente disponivel_cents financia saques; GET /saldo/consolidado soma casa e clientes. Sandbox retorna saldo ficticio persistente; aceita depositos simulados, saques e transferencias.

## Query parameters

- `customer_ref` string

## Response `200`

OK

- object
  - `customer_ref` string, nullable
  - `disponivel_cents` integer, required
  - `bloqueado_cents` integer, required
  - `total_cents` integer, required
  - `movimentos` integer
  - `proximas_liberacoes` object[]: Próximas liberações do escopo pedido (casa ou customer_ref). Pode trazer até 200 itens (antes da 1.44.1, no máximo 20): não presuma um teto menor.
    - `disponivel_em` string, date-time
    - `valor_cents` integer
  - `custodia_ativa` boolean: false = this key cannot hold BRL (destino "saldo" is refused).
  - `carencia_horas` integer: Carência configurada para esta chave; zero quando o crédito entra no saldo sem carência. Retenções da cobrança e créditos bloqueados continuam independentes.
  - `deposito_fee_bps` integer: Sempre 0 para novos depósitos em saldo.
  - `saque_taxa_estimada_cents` integer: Tarifa fixa ou piso estimado do provedor. Para percentual, aplique saque_taxa_provedor_formula; não é preço total de todo saque.
  - `saque_fee_bps` integer: Taxa Lunium do saque Pix do saldo; padrão 150 bps, mais comissão do parceiro. Processamento informado separadamente.
  - `saque_cripto_fee_bps` integer: Sobretaxa no débito de cripto: 0. A taxa Lunium é aplicada uma única vez na conversão.
  - `primeiro_deposito_em` string, date-time, nullable: When the first deposit of this sub-account was credited (null = never deposited).
  - `carencia_ate` string, date-time, nullable: Fim da carência do primeiro depósito, quando em curso; null caso contrário. Leia também bloqueado_cents e proximas_liberacoes.
  - `retencao_acima_cents` integer: Limiar de política para primeiro pagamento elegível em custódia. Não significa retenção de todo depósito acima deste valor; a régua e a chave também decidem.
  - `deposito_fee_fixed_cents` integer: Sempre 100 centavos por novo depósito em saldo.
  - `saque_taxa_provedor_formula` string, nullable: Fórmula vigente: fixa (piso_cents) ou percentual com piso. Não fixe um provedor como sempre ativo.
  - `saque_taxa_provedor_tipo` 'fixo' | 'percentual': Tipo vigente de tarifa do provedor de payout.
  - `saque_taxa_provedor_piso_cents` integer: Tarifa fixa ou piso da tarifa percentual, em centavos.
  - `sandbox` boolean: true na resposta reduzida de teste.
  - `saque_partner_fee_bps` integer: Sub fee do parceiro na saida (PIX e cripto), por cima da taxa da Lunium.
  - `saque_fee_total_bps` integer: Single service rate for customer display: house fee plus partner markup, in bps (250 = 2.5%). Display with the fixed tariff, without a separate partner commission. Use actual quoted/stored monetary fee amounts; internal components round to cents independently. Production and sandbox.
  - `saque_cripto_conversao_fee_bps` integer: Percentual Lunium na conversão do saldo em cripto, sobre a cotação Binance sem ágio; padrão 330 bps.
  - `saque_cripto_conversao_fee_fixed_cents` integer: Zero: o custo de entrada já foi cobrado no depósito.
  - `deposito_partner_fee_bps` integer: Subfee exclusiva do depósito Pix em saldo BRL, em basis points (100 = 1%). Padrão 0, máximo 1000. Aplicada ao valor recebido após a taxa fixa Lunium, descontada antes do crédito no saldo. Independente de compra, venda e saque. Congelada na criação; comissão creditada somente após liberação e crédito concluído (paid/sent).
  - `partner_deposito_fee_bps` integer: Subfee exclusiva do depósito Pix em saldo BRL, em basis points (100 = 1%). Padrão 0, máximo 1000. Aplicada ao valor recebido após a taxa fixa Lunium, descontada antes do crédito no saldo. Independente de compra, venda e saque. Congelada na criação; comissão creditada somente após liberação e crédito concluído (paid/sent).

## Other responses

- `401`: Missing or invalid key

## Changes

- **2026-10-19** `fc06c3b824b1`: 2 info
  - added the optional property `partner_deposito_fee_bps` to the response with the `200` status
  - the `deposito_partner_fee_bps` response's property default value `0` was added for the status `200`

[Operation history](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/changes/saldo/get.md)

---

[API](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil.md) · [All operations](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/llms.txt) · [OpenAPI document](https://skmtc.dev/luniumpay/apis/lunium-crypto-pix-settlement-brazil/revisions/0b5a340fa9dd?raw)