# Query account balance overview

> Query multi-currency account balance summaries and an optional display-currency total.

```yaml
openapi: 3.1.0
info:
  title: Query account balance overview
  version: 1.0.0
  description: Query multi-currency account balance summaries and an optional
    display-currency total.
paths:
  /api/v2/account/balance/overview/query:
    post:
      summary: Query account balance overview
      description: Query multi-currency account balance summaries and an optional
        display-currency total.
      parameters:
        - name: apikey
          in: header
          required: true
          description: Account service API key request header assigned by Onerway. Use the
            value for the same environment as the request base URL.
          schema:
            type: string
            description: Account service API key request header assigned by Onerway. Use the
              value for the same environment as the request base URL.
        - name: x-timestamp
          in: header
          required: true
          description: Request timestamp. The gateway uses it to identify replay attempts.
          schema:
            type: string
            description: Request timestamp. The gateway uses it to identify replay attempts.
            x-onerway-constraints:
              - kind: rule
                text: The timestamp must be within 10 minutes of the server time. Both 10-digit
                  seconds and 13-digit milliseconds are accepted.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: Request ID used for idempotency control and request tracing.
                onBehalfOf:
                  type: string
                  description: Sub-merchant number when a platform merchant queries on behalf of
                    its sub-merchant. The caller merchant from `apikey` must be
                    the parent merchant.
                displayCurrency:
                  type: string
                  description: Display currency used to convert multi-currency balances into one
                    display amount. Defaults to `USD` when omitted. Use a
                    three-letter [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    currency code.
              required:
                - requestId
            examples:
              query-balance-overview-in-usd:
                summary: Query the balance overview in USD
                value:
                  requestId: REQ-BAL-OV-20260423-0001
                  displayCurrency: USD
      responses:
        "200":
          description: Multi-currency balance overview in USD
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: Standardized response code. `20000` indicates a successful
                      response.
                  respMsg:
                    type: string
                    description: Human-readable response message aligned with `respCode`.
                  data:
                    type: object
                    properties:
                      totalAmount:
                        type:
                          - string
                          - "null"
                        description: Total balance converted into `displayCurrency`. Intended for
                          overview display, not reconciliation.
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: May be empty when the exchange rate is unavailable.
                            zh: 汇率不可用时可能为空。
                      displayCurrency:
                        type: string
                        description: Display currency used to read `totalAmount`. Read it as a
                          three-letter [ISO
                          4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                          currency code.
                      currencyBalances:
                        type: array
                        description: Per-currency balance summary list.
                        items:
                          type: object
                          properties:
                            currency:
                              type: string
                              description: Balance currency. Read it as a three-letter [ISO
                                4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                currency code.
                            paymentBalance:
                              type: string
                              description: Available Payment balance.
                            fundingBalance:
                              type: string
                              description: Funding balance.
                            pendingSettlementBalance:
                              type: string
                              description: Pending settlement balance.
                            onHoldBalance:
                              type: string
                              description: On-hold balance.
                            riskDepositAmount:
                              type: string
                              description: Risk deposit amount.
                            totalBalance:
                              type: string
                              description: Total balance for the currency.
                            status:
                              type: string
                              description: Account status returned by the account service.
                    description: Account balance overview payload.
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: External business error code aligned with `respCode`.
                      declineCode:
                        type: string
                        description: Compatibility field that mirrors `code` for current account APIs.
                      message:
                        type: string
                        description: Human-readable error message.
                      type:
                        type: string
                        description: Standardized error category.
                      param:
                        type: string
                        description: Request parameter that caused the error, when applicable.
                      requestId:
                        type: string
                        description: Caller request id copied from body `requestId`.
                    description: Standardized error object. It is null for successful responses and
                      omitted from the JSON body.
              examples:
                query-balance-overview-in-usd:
                  summary: Multi-currency balance overview in USD
                  value:
                    respCode: "20000"
                    respMsg: Success
                    data:
                      totalAmount: "5000.00"
                      displayCurrency: USD
                      currencyBalances:
                        - currency: USD
                          paymentBalance: "1500.00"
                          fundingBalance: "1000.00"
                          pendingSettlementBalance: "200.00"
                          onHoldBalance: "100.00"
                          riskDepositAmount: "200.00"
                          totalBalance: "3000.00"
                          status: Active
                        - currency: EUR
                          paymentBalance: "1500.00"
                          fundingBalance: "1000.00"
                          pendingSettlementBalance: "0.00"
                          onHoldBalance: "500.00"
                          riskDepositAmount: "0.00"
                          totalBalance: "2000.00"
                          status: Active
      x-onerway-lifecycle:
        phase: active
        access:
          description:
            en: Access to the Account service APIs is enabled by Onerway approval.
            zh: 账户服务 API 的访问权限需经 Onerway 审批后开通。
```