---
title: "Get account balance"
method: GET
path: "/v1/balance"
tags: ["Balance"]
---

# Get account balance

`GET /v1/balance`

Return the current BRL balance for the company associated with the API key. The endpoint takes no parameters — the company is always derived from the API key. The three balance buckets are independent and additive: `available` (withdrawable now), `frozen` (reserved for in-flight withdrawals, refunds, or operational holds — not currently withdrawable), and `held` (confirmed but pending settlement). The total account balance is `available + frozen + held`. A sandbox API key always returns zeros, since sandbox transactions do not accumulate to a real balance.

## Response `200`

Balance retrieved.

- object
  - `balance` Balance, required — Account balance for the company associated with the API key. The four buckets `available`, `frozen`, and `held` are independent and additive — `total = available + frozen + held`.
    - `available` number, required — Amount available for immediate PIX withdrawal, in BRL.
    - `frozen` number, required — Funds reserved/frozen for in-flight withdrawals, refunds, or operational holds. Not currently withdrawable, but still part of the account balance until the underlying operation reaches a terminal state. Independent from `available`.
    - `held` number, required — Confirmed amount pending settlement (for example, card or boleto payments confirmed but not yet liquidated). Will move to `available` once settled.
    - `total` number, required — Total account balance: `available + frozen + held`.
    - `currency` 'BRL', required — Always `BRL`. Multi-currency is not yet supported on the public API.
    - `environment` 'SANDBOX' | 'PRODUCTION', required — Environment of the API key used to make this call. Sandbox keys always return zeros.
    - `updatedAt` string, date-time, nullable, required — When the balance row was last updated. `null` if the company has never had any balance activity.

## Other responses

- `401` — Missing or invalid authentication token.
- `403` — The API key is valid but does not have the required scope for this endpoint.
- `429` — Rate limit exceeded.

---

[API](https://skmtc.net/yuvexpay/apis/yuvexpay-api.md) · [All operations](https://skmtc.net/yuvexpay/apis/yuvexpay-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/yuvexpay/yuvexpay-api/versions/0d036504e049/schema)