# 查询账户余额总览

> 查询多币种账户余额汇总和可选的展示币种总金额。

```yaml
openapi: 3.1.0
info:
  title: 查询账户余额总览
  version: 1.0.0
  description: 查询多币种账户余额汇总和可选的展示币种总金额。
paths:
  /api/v2/account/balance/overview/query:
    post:
      summary: 查询账户余额总览
      description: 查询多币种账户余额汇总和可选的展示币种总金额。
      parameters:
        - name: apikey
          in: header
          required: true
          description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
          schema:
            type: string
            description: Onerway 分配的账户服务 API key 请求 Header；必须使用与请求域名相同环境的值。
        - name: x-timestamp
          in: header
          required: true
          description: 请求时间戳；网关使用该 Header 防止请求被重放。
          schema:
            type: string
            description: 请求时间戳；网关使用该 Header 防止请求被重放。
            x-onerway-constraints:
              - kind: rule
                text: 时间戳必须在服务端当前时间 10分钟以内；支持 10 位秒级或 13 位毫秒级时间戳。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                requestId:
                  type: string
                  description: 请求 ID，用于幂等控制和链路追踪。
                onBehalfOf:
                  type: string
                  description: 平台商户代子商户查询时使用的子商户号；调用方商户必须是子商户的父商户。
                displayCurrency:
                  type: string
                  description: 用于将多币种余额折算为同一展示币种；缺省值为 `USD`。使用 [ISO
                    4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                    三位字母货币代码。
              required:
                - requestId
            examples:
              query-balance-overview-in-usd:
                summary: 按 USD 查询余额总览
                value:
                  requestId: REQ-BAL-OV-20260423-0001
                  displayCurrency: USD
      responses:
        "200":
          description: 按 USD 展示的多币种余额总览
          content:
            application/json:
              schema:
                type: object
                properties:
                  respCode:
                    type: string
                    description: 标准化响应码；`20000` 表示成功。
                  respMsg:
                    type: string
                    description: 与 `respCode` 对应的可读响应信息。
                  data:
                    type: object
                    properties:
                      totalAmount:
                        type:
                          - string
                          - "null"
                        description: 按 `displayCurrency` 换算后的总余额；仅用于余额总览查阅，不建议用于对账。
                        x-onerway-value:
                          nullable: true
                          empty: true
                          when:
                            en: May be empty when the exchange rate is unavailable.
                            zh: 汇率不可用时可能为空。
                      displayCurrency:
                        type: string
                        description: 用于读取 `totalAmount` 的展示币种；按 [ISO
                          4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                          三位字母货币代码读取。
                      currencyBalances:
                        type: array
                        description: 各币种余额汇总列表。
                        items:
                          type: object
                          properties:
                            currency:
                              type: string
                              description: 余额币种，按 [ISO
                                4217](https://en.wikipedia.org/wiki/ISO_4217#List_of_ISO_4217_currency_codes)
                                三位字母货币代码读取。
                            paymentBalance:
                              type: string
                              description: Payment 账户可用余额。
                            fundingBalance:
                              type: string
                              description: Funding 账户余额。
                            pendingSettlementBalance:
                              type: string
                              description: 待结算余额。
                            onHoldBalance:
                              type: string
                              description: 冻结余额。
                            riskDepositAmount:
                              type: string
                              description: 风险保证金金额。
                            totalBalance:
                              type: string
                              description: 该币种下的总余额。
                            status:
                              type: string
                              description: 账户服务返回的账户状态。
                    description: 账户余额总览数据。
                  error:
                    type: object
                    properties:
                      code:
                        type: string
                        description: 对外业务错误码，与 `respCode` 对齐。
                      declineCode:
                        type: string
                        description: 兼容字段，与 `code` 保持一致。
                      message:
                        type: string
                        description: 可读错误信息。
                      type:
                        type: string
                        description: 标准化错误类型。
                      param:
                        type: string
                        description: 触发错误的请求参数名，可选。
                      requestId:
                        type: string
                        description: 调用方请求 ID，与 body `requestId` 保持一致。
                    description: 标准化错误对象；成功响应中该字段为 null，序列化时省略。
              examples:
                query-balance-overview-in-usd:
                  summary: 按 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 审批后开通。
```