> ## Documentation Index > Fetch the complete documentation index at: https://docs.tracefinance.com/llms.txt > Use this file to discover all available pages before exploring further. # Get account balance > Retrieves the multi-currency balance for the given account, grouped into fiat and crypto arrays. ## OpenAPI ````yaml apis/fx-account/openapi.yml GET /v1/accounts/{accountId}/balances openapi: 3.1.1 info: title: FX Account API version: 1.0.0 description: API for managing multi-currency accounts on the Trace Finance platform. servers: - url: https://api.sandbox.tracefinance.com description: Sandbox security: - bearerAuth: [] tags: - name: Accounts description: Create, list, and manage multi-currency accounts. - name: Beneficial owners description: Manage beneficial owners (UBOs) for company-owned accounts. - name: Funding instructions description: Retrieve funding instructions for depositing into an account. - name: Balances description: Retrieve fiat and crypto balances for an account. paths: /v1/accounts/{accountId}/balances: get: tags: - Balances summary: Get account balance description: > Retrieves the multi-currency balance for the given account, grouped into `fiat` and `crypto` arrays. When an upstream provider is unreachable for a given currency, the corresponding entry is returned with `synced: false` and `amount: null` instead of failing the entire request. See [Errors](/guides/principles/errors) for the standard error envelope. operationId: getAccountBalance parameters: - $ref: '#/components/parameters/AccountId' - $ref: '#/components/parameters/TraceVersion' responses: '200': description: Account balance. content: application/json: schema: $ref: '#/components/schemas/BalanceResponse' examples: mixed: $ref: '#/components/examples/BalanceMixed' unsyncedSource: $ref: '#/components/examples/BalanceUnsyncedSource' '400': description: Invalid account ID format. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidUuid: $ref: '#/components/examples/InvalidAccountIdUuid' '401': $ref: '#/components/responses/UnauthorizedError' '404': description: No balance found for the given account. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: balanceNotFound: $ref: '#/components/examples/BalanceNotFound' components: parameters: AccountId: name: accountId in: path required: true description: UUID of the account. schema: type: string format: uuid TraceVersion: name: X-Trace-Version in: header required: false description: API version. Omit to use the default version. schema: type: string example: '1' schemas: BalanceResponse: type: object description: Multi-currency balance grouped by asset class. properties: accountId: type: string format: uuid description: Identifier of the account these balances belong to. example: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c fiat: type: array description: Fiat balances, one entry per enabled fiat currency. items: $ref: '#/components/schemas/BalanceEntryResponse' crypto: type: array description: Crypto balances, one entry per enabled crypto currency. items: $ref: '#/components/schemas/BalanceEntryResponse' required: - accountId - fiat - crypto ErrorResponse: type: object description: >- Standard error envelope. The HTTP response also carries an `X-Request-Id` header — reference it when contacting Trace Finance support. See [Errors](/guides/principles/errors). properties: code: type: string description: Machine-readable error code. message: type: string description: Human-readable description. details: type: object additionalProperties: true required: - code - message BalanceEntryResponse: type: object description: > A single balance entry for one currency. When `synced` is `false`, the upstream provider was unreachable and `amount` is omitted; customers should retry or fall back to a previously cached value. properties: amount: oneOf: - $ref: '#/components/schemas/AmountResponse' - type: 'null' description: The available balance. Null when `synced` is `false`. synced: type: boolean description: >- Whether the balance was successfully retrieved from the underlying provider. example: true required: - synced AmountResponse: type: object description: > Monetary amount expressed as a decimal string in the asset's canonical scale. Use a decimal-precision library (`BigDecimal`, `Decimal`) for arithmetic — never JavaScript `Number`. properties: value: type: string pattern: ^-?\d+(\.\d+)?$ description: Decimal amount in the asset's canonical scale. example: '5000.00' asset: $ref: '#/components/schemas/Asset' decimals: type: integer description: Number of decimal places for the asset. example: 2 required: - value - asset - decimals Asset: type: string enum: - BRL - USDT - USDC description: > ISO 4217 currency code or stablecoin ticker. The maximum decimal scale of an `AmountValue` paired with this asset depends on the asset: | Asset | Decimals | |---|---| | BRL | 2 | | USDT | 6 | | USDC | 6 | example: BRL examples: BalanceMixed: summary: Account with fiat and crypto assets value: accountId: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c fiat: - amount: value: '5000.00' asset: BRL decimals: 2 synced: true crypto: - amount: value: '1.500000' asset: USDC decimals: 6 synced: true BalanceUnsyncedSource: summary: Upstream provider was unreachable for one currency value: accountId: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c fiat: - amount: value: '5000.00' asset: BRL decimals: 2 synced: true - amount: null synced: false crypto: [] InvalidAccountIdUuid: summary: accountId path parameter is not a valid UUID value: code: INVALID_DATA message: Object contains invalid data details: errors: - code: INVALID_UUID message: '''not-a-uuid'' cannot be converted to UUID' field: path:accountId params: {} BalanceNotFound: summary: No balance is tracked for the requested account value: code: RESOURCE_NOT_FOUND message: >- Balance with given parameters [Balance.accountId:5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c] not found details: resource: Balance parameters: Balance.accountId: 5b7c1f2a-3d4e-4f8a-9b1c-2d3e4f5a6b7c InvalidToken: summary: Bearer token is invalid or malformed value: code: INVALID_ACCESS_TOKEN message: Invalid access token details: {} ExpiredToken: summary: Bearer token has expired value: code: EXPIRED_ACCESS_TOKEN message: Expired access token details: {} responses: UnauthorizedError: description: Missing or invalid authentication token. headers: X-Request-Id: $ref: '#/components/headers/RequestId' content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: invalidToken: $ref: '#/components/examples/InvalidToken' expiredToken: $ref: '#/components/examples/ExpiredToken' headers: RequestId: description: >- Unique request identifier emitted on every response. Reference it when contacting Trace Finance support so we can trace the request end-to-end. See [Errors](/guides/principles/errors). schema: type: string format: uuid securitySchemes: bearerAuth: type: http scheme: bearer bearerFormat: JWT description: >- JWT bearer token. Include as `Authorization: Bearer `. See the [Authentication](/guides/authentication) guide for how to obtain one. ````