> ## Documentation Index > Fetch the complete documentation index at: https://docs.brale.xyz/llms.txt > Use this file to discover all available pages before exploring further. # Get an address balance > Returns the balance of a custodial wallet address or a Plaid-linked bank address. Provide `transfer_type` and `value_type` as query parameters. Use the playground below to try this endpoint directly, or review the OpenAPI details in the right panel. ## Query parameters by address type Both `transfer_type` and `value_type` are required. | Address type | `transfer_type` | `value_type` | | - | - | - | | Custodial wallet (`type=internal`) | Blockchain network, such as `base` | Token ticker, such as `SBC` | | Plaid-linked bank address | `ach_debit` | `USD` | ## Plaid-linked bank balances ```bash theme={null} curl --request GET \ --url "https://api.brale.xyz/accounts/${ACCOUNT_ID}/addresses/${ADDRESS_ID}/balance?transfer_type=ach_debit&value_type=USD" \ --header "Authorization: Bearer ${AUTH_TOKEN}" ``` ```json Response theme={null} { "address": { "id": "34yknnMShvDbSW6tQg4HLlN41QO", "address": null, "account_number": "****1234" }, "balance": { "value": "1250.42", "currency": "USD" }, "value_type": "USD", "transfer_type": "ach_debit" } ``` * Brale uses Plaid's available balance when Plaid supplies it. Otherwise, Brale uses the current balance. * Successful reads may be cached for up to 30 seconds. * The balance is a point-in-time snapshot. It does not guarantee that an ACH debit will settle. * Brale never returns the full bank account number. `account_number` is masked. * Only Plaid-linked USD bank addresses support balance lookup. Bank addresses created through Direct bank entry do not. ## Errors | Status | `type` | Meaning | | - | - | - | | `400` | `invalid_address` | A bank balance request did not use `transfer_type=ach_debit`. | | `400` | `invalid_value_type` | A bank balance request did not use `value_type=USD`. | | `400` | `balance_not_supported_for_address` | The address is not Plaid-linked, or the currency is not supported. | | `400` | `plaid_error` (`code: plaid_item_login_required`) | The user must relink the bank account through Plaid. | | `503` | `service_unavailable` | Plaid returned an error or balance data is unavailable. | > [!NOTE] > > `service_unavailable` does not mean the balance is zero or insufficient. ## OpenAPI ````yaml GET /accounts/{account_id}/addresses/{address_id}/balance openapi: 3.0.3 info: title: Brale Issuance and Orchestration API version: 2.3.1 description: > Brale supports stablecoin issuance and orchestration, enabling businesses and ecosystems to create their own stablecoins and convert between fiat and stablecoins seamlessly. From stablecoin onramps, offramps, and swaps to custody and payouts, the Brale API makes it easy to build stablecoin-enabled products. NOTE: All resource IDs (including account_id, address_id, financial_institution_id, and automation_id) are KSUIDs—27-character alphanumeric strings that are sortable by time. Examples showing UUIDs are incorrect. **What's new in 2.3.1** - Unified **Addresses** model for on-chain and off-chain endpoints - `Transfers` now accepts **address_id only** (no financial_institution_id) - Optional `brand` object to control bank statement presentation (`branding` still accepted as legacy alias) - Added off-chain rails: `ach_credit`, `same_day_ach_credit`, `ach_debit`, `same_day_ach_debit`, `rtp-credit` - Plaid endpoints moved to `/accounts/{account_id}/plaid/*` - `Financial Institutions` marked **deprecated** (migration path to **Addresses**) - Create Account now uses `CreateManagedAccountRequest` with `beneficial_owners`, `business_controller`, and `EndUserTosAttestation`. - Transfers now accept `brand` (replaces `branding`, still aliased in docs). - Plaid endpoints updated to return `address_id` and accept `transfer_types`. - Off-chain Address creation uses `CreateExternalAddressRequest` oneOf with bank + blockchain variants. - FI endpoints kept but marked deprecated; use Addresses instead. - `rtp_credit` is the canonical RTP rail name. **FedNow** - Added the `fednow_credit` rail. Outbound: create a Transfer with `destination.transfer_type: fednow_credit` to a bank Address that lists `fednow_credit` in `transfer_types`. Inbound: payers send FedNow credits to an active Automation's `source.funding_instructions`; Brale creates the Transfer automatically with `source.transfer_type: fednow_credit`. - Simulate a testnet FedNow deposit with `transfer_type: fednow` on `POST /accounts/{account_id}/automations/{automation_id}/simulations/deposits`. - `bank_address` and `beneficiary_address` are required only when an external bank Address requests `wire`. - FedNow availability depends on account enablement. servers: - url: https://api.brale.xyz description: Production server security: - BearerAuth: [] tags: - name: Accounts description: Endpoints related to managing customer accounts (KYB, details, etc.) - name: Transfers description: >- Endpoints for creating and retrieving transfers (fiat to stablecoins, etc.) - name: Addresses description: >- On-chain and off-chain endpoints (custodial or external) represented by a single Addresses resource - name: Financial Institutions description: Legacy (deprecated) bank endpoints. Use Addresses instead. - name: Automations description: Automated deposit addresses or onramps - name: Plaid description: Bank linking and ACH debit via Plaid. - name: Orders description: Legacy tag used for transfers in older specs. paths: /accounts/{account_id}/addresses/{address_id}/balance: get: tags: - Addresses summary: Get an address balance description: > Returns the balance of one address for the requested `transfer_type` and `value_type`. Both query parameters are required. - **Custodial wallets** (`type=internal`): pass the blockchain network and token ticker, for example `transfer_type=base&value_type=SBC`. - **Plaid-linked bank addresses**: pass `transfer_type=ach_debit&value_type=USD`. Brale returns Plaid's available balance when Plaid supplies it, otherwise the current balance. Successful reads may be cached for up to 30 seconds. The balance is a point-in-time snapshot and does not guarantee that an ACH debit will settle. Brale never returns the full bank account number. Only Plaid-linked USD bank addresses support balance lookup. Bank addresses created through Direct bank entry do not. operationId: get_address_balance parameters: - name: account_id in: path required: true description: The ID of the account schema: $ref: '#/components/schemas/Ksuid' - name: address_id in: path required: true schema: $ref: '#/components/schemas/Ksuid' description: The ID of the address - name: transfer_type in: query required: true schema: type: string example: base description: >- Blockchain network for wallets (for example, `solana`, `base`, `ethereum`), or `ach_debit` for a Plaid-linked bank. - name: value_type in: query required: true schema: type: string example: SBC description: >- Token ticker for wallets (for example, `SBC`, `USDC`), or `USD` for a Plaid-linked bank. responses: '200': description: The address details and balance info content: '*/*': schema: $ref: '#/components/schemas/AddressBalanceResponse' examples: wallet: summary: Custodial wallet (transfer_type=solana, value_type=SBC) value: address: id: 2VcUIIsgARwVbEGlIYbhg6fGG57 address: 73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me balance: value: '100.00' currency: SBC transfer_type: solana value_type: SBC plaid_bank: summary: Plaid-linked bank (transfer_type=ach_debit, value_type=USD) value: address: id: 34yknnMShvDbSW6tQg4HLlN41QO address: null account_number: '****1234' balance: value: '1250.42' currency: USD value_type: USD transfer_type: ach_debit '400': description: | Bad request. Possible `type` values: - `invalid_address` — a bank balance request did not use `transfer_type=ach_debit`. - `invalid_value_type` — a bank balance request did not use `value_type=USD`. - `balance_not_supported_for_address` — the address is not Plaid-linked, or the currency is not supported. - `plaid_error` with `code: plaid_item_login_required` — the Plaid connection needs to be re-authenticated. Have the user relink the bank account through Plaid. content: application/json: schema: allOf: - $ref: '#/components/schemas/ErrorResponse' - type: object properties: code: type: string description: >- Provider-specific error code. Present on `plaid_error`. example: plaid_item_login_required examples: plaid_item_login_required: summary: Plaid relink required value: type: plaid_error code: plaid_item_login_required balance_not_supported_for_address: summary: Address does not support balance lookup value: type: balance_not_supported_for_address '503': description: > `service_unavailable` — Plaid returned an error or balance data is unavailable. This does not mean the balance is zero or insufficient. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: type: service_unavailable components: schemas: Ksuid: title: Kusid type: string format: ksuid pattern: ^[a-zA-Z0-9]{27}$ example: 2VcUIIsgARwVbEGlIYbhg6fGG57 AddressBalanceResponse: title: AddressBalance type: object additionalProperties: false description: >- Balance of **one** token on **one** chain for a custodial wallet, or the USD balance of a Plaid-linked bank address. properties: address: $ref: '#/components/schemas/AddressReference' balance: $ref: '#/components/schemas/Amount' transfer_type: type: string description: >- Blockchain network for wallets (for example, `solana` or `base`), or `ach_debit` for a Plaid-linked bank. example: solana value_type: type: string description: >- Token ticker for wallets (for example, `SBC`), or `USD` for a Plaid-linked bank. example: SBC required: - address - balance - value_type - transfer_type example: address: id: 2VcUIIsgARwVbEGlIYbhg6fGG57 address: 73uyt9HkEqx9bThYXWaUBP67sWsiJEsyJ5rSCieDx5me balance: value: '100.00' currency: SBC transfer_type: solana value_type: SBC ErrorResponse: type: object title: ErrorResponse description: Standard Brale error envelope. required: - type properties: type: type: string description: Machine-readable error type identifier. example: unsupported_account_combination message: type: string description: Human-readable explanation of the error. example: >- The combination of entity_type, account_type, and verification_mode is not supported. AddressReference: title: AddressReference type: object additionalProperties: false properties: id: $ref: '#/components/schemas/Ksuid' address: type: string nullable: true description: On-chain address for wallets. `null` for bank addresses. example: '0xb518d4d6221d9a41d23d71cbce8e106e7aab8f9b' account_number: type: string nullable: true description: >- Masked bank account number for bank addresses, for example `****1234`. Brale never returns the full account number. `null` or omitted for wallets. example: '****1234' required: - id Amount: title: Amount type: object description: Monetary value with explicit currency additionalProperties: false properties: value: type: string example: '11234.88' currency: type: string example: USD required: - value - currency securitySchemes: BearerAuth: type: http scheme: bearer description: > Use the Bearer token returned from the Auth endpoint via OAuth2 client_credentials flow. Include the token in the "Authorization: Bearer " header. ````