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

# Account Balance

> Retrieve the live balance for a specific wallet and currency in your Niobi account. Returns total, available, on-hold, and unsettled balances. Each request must carry a freshly generated signature. See [Payout Best Practices](/making-payments/best-practices#1-merchant-wallet-balance-management-&-pre-check) for balance monitoring guidance.

<Note>
  Generate a fresh `signature` for every request — signatures cannot be reused.
</Note>


## OpenAPI

````yaml post /api/v3/get-unified-balance
openapi: 3.0.0
info:
  title: Niobi API
  description: >-
    REST API for collecting payments, sending payouts, and managing
    multi-currency wallets across Africa and global corridors. All requests
    require IP whitelisting and a unique per-request HMAC SHA-256 signature.
  version: 4.0.0
servers:
  - url: https://sandbox.users.niobi.co
    description: Sandbox, Development and Testing
security: []
tags:
  - name: Niobi
    description: API Endpoints of Niobi
paths:
  /api/v3/get-unified-balance:
    post:
      tags:
        - payment
      summary: Account Balance
      description: >-
        Retrieve the live balance for a specific wallet and currency in your
        Niobi account. Returns total, available, on-hold, and unsettled
        balances. Each request must carry a freshly generated signature. See
        [Payout Best
        Practices](/making-payments/best-practices#1-merchant-wallet-balance-management-&-pre-check)
        for balance monitoring guidance.
      operationId: v3/get-unified-balance
      requestBody:
        description: Signed payload to query a wallet balance.
        required: true
        content:
          application/json:
            schema:
              required:
                - client_id
                - params
                - salt
                - sender
                - timestamp
                - signature
              properties:
                client_id:
                  description: >-
                    Your Client ID from the Niobi Dashboard under Workspace >
                    Integrations.
                  type: string
                  example: K1PoY1WYricSpXh6Wm24twnk6ecPJOWrHGsqiKJr
                sender:
                  description: >-
                    The exact title of your integration as registered in the
                    Dashboard. Case-sensitive.
                  type: string
                timestamp:
                  description: >-
                    Unix timestamp in seconds at the time of signing. Must match
                    the value used to generate the signature.
                  type: integer
                salt:
                  description: >-
                    A unique random string you generate per request. Must be the
                    same value used when generating the signature.
                  type: string
                signature:
                  description: >-
                    SHA-256 signature computed from this payload. Generate via
                    the [Signature
                    endpoint](/api-reference/authentication/generate-signature)
                    or your own backend.
                  type: string
                params:
                  required:
                    - wallet_account
                    - currency
                  properties:
                    wallet_account:
                      description: Your wallet account identifier.
                      type: string
                      example: ACC847291
                    currency:
                      description: >-
                        Currency of the wallet to check the balance for (e.g.
                        KES, NGN, GHS).
                      type: string
                      example: KES
                  type: object
              type: object
      responses:
        '200':
          description: Ok.
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: 'true'
                  message:
                    type: string
                    example: Balance fetched successfully.
                  data:
                    type: object
                    properties:
                      currency:
                        type: string
                        example: KES
                        description: Currency of the queried wallet
                      total_balance:
                        type: number
                        example: 150000.5
                        description: Total ledger balance across all funds
                      on_hold_balance:
                        type: number
                        example: 5000
                        description: Balance locked for pending / in-flight transactions
                      available_balance:
                        type: number
                        example: 145000.5
                        description: Immediately spendable / disburseable float balance
                      unsettled_balance:
                        type: number
                        example: 0
                        description: Unsettled incoming collections balance
                type: object
              example:
                success: true
                message: Balance fetched successfully.
                data:
                  currency: KES
                  total_balance: 150000.5
                  on_hold_balance: 5000
                  available_balance: 145000.5
                  unsettled_balance: 0
        '400':
          description: User not found.
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: 'false'
                  message:
                    type: string
                    example: User not found.
                type: object
        '403':
          description: >-
            Entity integration record not found or Client id not matched or
            Request was not verified..
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: 'false'
                  message:
                    type: string
                    example: >-
                      Entity integration record not found or Client id not
                      matched or Request was not verified..
                type: object
        '404':
          description: User not found
          content:
            application/json:
              schema:
                properties:
                  success:
                    type: boolean
                    example: 'false'
                  message:
                    type: string
                    example: User not found.
                type: object

````