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

# Fetch Agent Institution Wallet Balance

> Use this API to fetch the current available wallet balance for a given Agent Institution.
This balance reflects funds available for BBPS bill payment transactions.

<Note>
The balance can be positive or negative, depending on the Agent Institution's funding model:
- Prefunding model: the Agent Institution funds the wallet in advance, and bill payments are debited from it. The balance is the remaining prefunded amount and does not go below zero.
- Shortfall (postfunding) model: bill payments are drawn against the Agent Institution's shortfall wallet. A negative balance represents the current shortfall, that is, the amount the Agent Institution has drawn and must repay.
</Note>



## OpenAPI

````yaml openapi/bbps/bbps-cou.yaml get /bbps/cou/agent/{agentId}/wallet/balance
openapi: 3.0.3
info:
  title: BBPS for Customers (Customer Operating Unit)
  version: 1.0.0
  description: >
    APIs for Agent Institutions to integrate with the Bharat Bill Payment System
    (BBPS) as a Customer Operating Unit (COU). These APIs enable bill discovery,
    bill fetch, bill payment, ticket management, and wallet operations.
servers:
  - url: https://sandbox.cashfree.com
    description: Sandbox (Testing) environment.
  - url: https://api.cashfree.com
    description: Production environment.
security:
  - XClientID: []
    XClientSecret: []
paths:
  /bbps/cou/agent/{agentId}/wallet/balance:
    get:
      tags:
        - Wallet
      summary: Fetch Agent Institution Wallet Balance
      description: >-
        Use this API to fetch the current available wallet balance for a given
        Agent Institution.

        This balance reflects funds available for BBPS bill payment
        transactions.


        <Note>

        The balance can be positive or negative, depending on the Agent
        Institution's funding model:

        - Prefunding model: the Agent Institution funds the wallet in advance,
        and bill payments are debited from it. The balance is the remaining
        prefunded amount and does not go below zero.

        - Shortfall (postfunding) model: bill payments are drawn against the
        Agent Institution's shortfall wallet. A negative balance represents the
        current shortfall, that is, the amount the Agent Institution has drawn
        and must repay.

        </Note>
      operationId: fetchAgentWalletBalance
      parameters:
        - name: agentId
          in: path
          required: true
          description: >-
            The Agent Institution ID (bbpsAgentInstituteId) that owns the
            wallet. This is the parent institution identifier, not the
            channel-specific agent_id used in the Bill Fetch and Bill Payment
            APIs.
          schema:
            type: string
          example: AI15
        - in: header
          name: x-api-version
          required: false
          description: >
            API version to be used. Format is YYYY-MM-DD. The only supported
            version for this API is `2025-01-01`. If not specified, `2025-01-01`
            is used.
          schema:
            type: string
            default: '2025-01-01'
            enum:
              - '2025-01-01'
          example: '2025-01-01'
      responses:
        '200':
          description: >-
            Success response for fetching the current available wallet balance
            for a given Agent Institution.
          headers:
            x-api-version:
              $ref: '#/components/headers/x-api-version'
          content:
            application/json:
              schema:
                type: object
                properties:
                  balance:
                    type: number
                    format: decimal
                    description: >-
                      Current wallet balance in INR. Positive on the prefunding
                      model (remaining prefunded amount). On the shortfall
                      (postfunding) model this can be negative, where the
                      negative value is the current shortfall drawn against the
                      credit line.
                    example: 5000
              example:
                balance: 5000
        '400':
          description: Bad request error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              examples:
                wallet_not_found:
                  summary: No active wallet
                  value:
                    message: 'No active wallet found for agentInstitutionId: AI15'
                    code: wallet_not_found
                    type: invalid_request_error
        '401':
          description: Authentication Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/UnauthorizedResponse'
        '429':
          description: Rate Limit Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/RateLimitResponse'
        '500':
          description: Internal Server Error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InternalServerErrorResponse'
components:
  headers:
    x-api-version:
      schema:
        type: string
        format: YYYY-MM-DD
        enum:
          - '2025-01-01'
          - '2026-01-01'
      description: >-
        The API version used to process this request, echoed back in the
        response.
  schemas:
    ErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A description of the error explaining what went wrong.
        code:
          type: string
          description: >-
            An error code identifying the specific validation failure. Use this
            to handle errors programmatically.
        type:
          type: string
          description: The category of the error indicating the class of failure.
    UnauthorizedResponse:
      type: object
      properties:
        message:
          type: string
          description: A description of the error explaining what went wrong.
          example: authentication Failed
        code:
          type: string
          description: >-
            An error code identifying the specific failure. Use this to handle
            errors programmatically.
          example: request_failed
        type:
          type: string
          description: The category of the error indicating the class of failure.
          example: authentication_error
    RateLimitResponse:
      type: object
      properties:
        message:
          type: string
          description: A description of the error explaining what went wrong.
          example: Too many requests from IP. Check headers
        code:
          type: string
          description: >-
            An error code identifying the specific failure. Use this to handle
            errors programmatically.
          example: request_failed
        type:
          type: string
          description: The category of the error indicating the class of failure.
          example: rate_limit_error
    InternalServerErrorResponse:
      type: object
      properties:
        message:
          type: string
          description: A description of the error explaining what went wrong.
          example: internal Server Error
        code:
          type: string
          description: >-
            An error code identifying the specific failure. Use this to handle
            errors programmatically.
          example: internal_error
        type:
          type: string
          description: The category of the error indicating the class of failure.
          example: api_error
  securitySchemes:
    XClientID:
      type: apiKey
      in: header
      name: x-client-id
      description: >-
        Your unique client identifier issued by Cashfree. You can find this in
        your [Merchant
        Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).
    XClientSecret:
      type: apiKey
      in: header
      name: x-client-secret
      description: >-
        Your unique client secret issued by Cashfree. Keep this confidential and
        never expose it in client-side code. You can find this in your [Merchant
        Dashboard](https://merchant.cashfree.com/verificationsuite/developers/api-keys).

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.