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

# 查询待结算余额

> 查询当前 API Key 所属商户按币种汇总的待结算账面余额。无需 merchant_id；响应仅包含 balances 和 as_of，不返回 merchant_id。

币种金额字段为 `amount`。这是商户维度的独立汇总，不关联 `account_no`，不能加到每个账户的 `total_amount` 上。当前版本按内部待结算账户总余额汇总，包含其中的冻结部分；不能解释为“已扣除冻结或预留的可用待结算金额”。

认证方式沿用[公共认证规范](/zh/api/getting-started)。无需传入 `merchant_id` 或 `X-Merchant-Id`，服务端只查询当前 API Key 所属商户的数据。无请求体。金额示例为虚构数据，使用账本最小单位。



## OpenAPI

````yaml /zh/api/global-accounts.openapi.json get /api/v1/pending_settlement_balance
openapi: 3.1.0
info:
  title: StablePay 全球账户查询 API
  version: '2026-09-29'
  summary: 全球账户列表、单账户及商户待结算余额查询。
  description: 全球账户与待结算余额只读查询。认证方式沿用 StablePay 公共认证规范。本文按当前生产实现描述，示例为虚构数据。
servers:
  - url: https://api.stablepay.co
    description: 生产环境
security:
  - bearerAuth: []
    stablepayTimestamp: []
    stablepayNonce: []
    stablepaySignature: []
tags:
  - name: 全球账户
    description: 只读账户和余额查询，不提供资金操作。
paths:
  /api/v1/pending_settlement_balance:
    get:
      tags:
        - 全球账户
      summary: 查询待结算余额
      description: >-
        查询当前 API Key 所属商户按币种汇总的待结算账面余额。无需 merchant_id；响应仅包含 balances 和 as_of，不返回
        merchant_id。


        币种金额字段为 `amount`。这是商户维度的独立汇总，不关联 `account_no`，不能加到每个账户的 `total_amount`
        上。当前版本按内部待结算账户总余额汇总，包含其中的冻结部分；不能解释为“已扣除冻结或预留的可用待结算金额”。


        认证方式沿用[公共认证规范](/zh/api/getting-started)。无需传入 `merchant_id` 或
        `X-Merchant-Id`，服务端只查询当前 API Key 所属商户的数据。无请求体。金额示例为虚构数据，使用账本最小单位。
      operationId: getPendingSettlementBalance
      parameters:
        - $ref: '#/components/parameters/XStablePayTimestamp'
        - $ref: '#/components/parameters/XStablePayNonce'
        - $ref: '#/components/parameters/XStablePaySignature'
      responses:
        '200':
          description: 查询成功。
          headers:
            Cache-Control:
              schema:
                type: string
                enum:
                  - no-store
              description: 余额响应不应被缓存。
            X-Request-ID:
              schema:
                type: string
              description: 排障时提供此追踪 ID。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PendingBalanceResponse'
              example:
                balances:
                  - currency: USDT
                    amount: 2500
                  - currency: USDC
                    amount: -100
                as_of: 1789084800
        '500':
          description: 服务内部错误。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: internal_error
                  message: 服务内部错误。
                request_id: example-request-id
                timestamp: 1789084800
        '503':
          description: 余额查询服务暂时不可用，请稍后使用新的时间戳、nonce 和签名重试。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'
              example:
                error:
                  code: service_unavailable
                  message: 余额查询服务暂时不可用，请稍后使用新的时间戳、nonce 和签名重试。
                request_id: example-request-id
                timestamp: 1789084800
components:
  parameters:
    XStablePayTimestamp:
      name: X-StablePay-Timestamp
      in: header
      required: true
      description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
      schema:
        type: string
      example: '1791878400'
    XStablePayNonce:
      name: X-StablePay-Nonce
      in: header
      required: true
      description: 防重放随机字符串，长度 16-64 个字符，建议每次请求使用新的 UUID。
      schema:
        type: string
        minLength: 16
        maxLength: 64
      example: 550e8400-e29b-41d4-a716-446655440000
    XStablePaySignature:
      name: X-StablePay-Signature
      in: header
      required: true
      description: >-
        使用商户 API Secret 对 `{timestamp}.{nonce}.{requestBody}` 计算
        HMAC-SHA256，结果为小写 hex。GET 请求的 `requestBody` 为空字符串。
      schema:
        type: string
      example: a1b2c3d4e5f6...
  schemas:
    PendingBalanceResponse:
      type: object
      required:
        - balances
        - as_of
      properties:
        balances:
          type: array
          description: 按币种汇总的待结算余额；零合计币种省略，无记录时返回空数组。
          items:
            $ref: '#/components/schemas/PendingBalance'
        as_of:
          type: integer
          format: int64
          description: 本次查询的数据库观察时间，Unix 秒；不是数据版本号，不保证多次请求处于同一快照。
      example:
        balances:
          - currency: USDT
            amount: 2500
          - currency: USDC
            amount: -100
        as_of: 1789084800
    ErrorResponse:
      type: object
      required:
        - error
        - request_id
        - timestamp
      properties:
        error:
          type: object
          required:
            - code
            - message
          properties:
            code:
              type: string
              description: 稳定业务错误码。
            message:
              type: string
              description: 可读错误说明。
        request_id:
          type: string
          description: 请求追踪 ID，不限制为纯数字。
        timestamp:
          type: integer
          format: int64
          description: 错误响应时间，Unix 秒。
    PendingBalance:
      type: object
      required:
        - currency
        - amount
      properties:
        currency:
          type: string
          description: 币种代码；同一币种最多返回一条。
          example: USDT
        amount:
          type: integer
          format: int64
          description: 商户在该币种下的待结算账面余额，使用账本最小单位。允许负值，客户端应原样保留，不应截断为零；非可用或可提现余额。
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key
      description: Bearer API Key，例如 `Bearer sk_live_xxx`。
    stablepayTimestamp:
      type: apiKey
      in: header
      name: X-StablePay-Timestamp
      description: Unix 时间戳（秒）。必须与服务端时间相差不超过 5 分钟。
    stablepayNonce:
      type: apiKey
      in: header
      name: X-StablePay-Nonce
      description: 防重放随机字符串，长度 16-64 个字符。
    stablepaySignature:
      type: apiKey
      in: header
      name: X-StablePay-Signature
      description: 使用商户 API Secret 计算的 HMAC-SHA256 小写 hex 签名。

````

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