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

# 列出持仓

> 查询有效资产持仓，包括可用数量和冻结数量。

<RequestExample>
  ```bash cURL
  curl --request GET \
    --url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/position' \
    --header "Content-Type: application/json" \
    --header "x-auth-token: Bearer ${SANDBOX_TOKEN}"
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  {
    "data": [
      {
        "asset_id": "7453f146-b267-11f1-b4f4-0abd773ba497",
        "available_quantity": "0.00297066689243735",
        "frozen_quantity": "0",
        "quantity": "0.00297066689243735",
        "symbol": "AAPLx",
        "updated_at": "2026-09-21T01:50:53.852Z"
      }
    ],
    "total_items": 1,
    "total_pages": 1
  }
  ```
</ResponseExample>


## OpenAPI

````yaml /zh/stocks/stocks.yaml get /position
openapi: 3.0.3
info:
  title: UQPAY Stocks API
  version: 1.0.0
  description: 浏览资产、获取报价、创建订单并查询订单及持仓。金额和数量使用十进制字符串。
  x-source-en-commit: 586409f
  x-source-en-path: stocks/stocks.yaml
servers:
  - url: https://api-sandbox.uqpaytech.com/api/v1/stocks
    description: Sandbox
security:
  - AuthToken: []
paths:
  /position:
    get:
      tags:
        - Stocks
      summary: 列出持仓
      description: 查询有效资产持仓，包括可用数量和冻结数量。
      operationId: listStocksPositions
      parameters:
        - name: page_number
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 1000000
            default: 1
          description: 要查询的页码。
        - name: page_size
          in: query
          required: false
          schema:
            type: integer
            minimum: 1
            maximum: 100
            default: 10
          description: 每页返回的最大条目数。
        - name: asset_id
          in: query
          required: false
          schema:
            type: string
            format: uuid
          description: List assets 返回的资产标识。
        - name: symbol
          in: query
          required: false
          schema:
            type: string
            maxLength: 32
          description: 按资产代码筛选。
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PositionPage'
              examples:
                sandbox:
                  summary: Sandbox response
                  value:
                    data:
                      - asset_id: 7453f146-b267-11f1-b4f4-0abd773ba497
                        available_quantity: '0.00297066689243735'
                        frozen_quantity: '0'
                        quantity: '0.00297066689243735'
                        symbol: AAPLx
                        updated_at: '2026-09-21T01:50:53.852Z'
                    total_items: 1
                    total_pages: 1
        '400':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '429':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '502':
          description: 网关未能完成请求。写入操作应先核对结果，再使用同一幂等键重试。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '503':
          description: 请求失败。读取错误响应中的 type、code 和 message。
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
      x-codeSamples:
        - lang: cURL
          source: |-
            curl --request GET \
              --url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/position' \
              --header "Content-Type: application/json" \
              --header "x-auth-token: Bearer ${SANDBOX_TOKEN}"
components:
  schemas:
    PositionPage:
      type: object
      additionalProperties: false
      properties:
        data:
          type: array
          items:
            $ref: '#/components/schemas/Position'
          description: 本页记录。空数组可能表示没有匹配记录或页码超出结果范围。
        total_pages:
          type: integer
          format: int64
          minimum: 0
          description: 按请求的每页条数计算的结果总页数。
          example: 1
        total_items:
          type: integer
          format: int64
          minimum: 0
          description: 所有页中符合筛选条件的记录总数。
          example: 1
      required:
        - data
        - total_pages
        - total_items
    Error:
      type: object
      additionalProperties: false
      required:
        - type
        - code
        - message
      properties:
        type:
          type: string
          description: 用于分类处理失败的错误类别。
          pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
        code:
          type: string
          description: 可供程序处理的业务错误码。结合 HTTP 状态处理，不要依赖 message 文本匹配。
          pattern: ^[a-z][a-z0-9]*(_[a-z0-9]+)*$
        message:
          type: string
          description: 错误原因的可读说明。
    Position:
      type: object
      additionalProperties: false
      properties:
        asset_id:
          type: string
          format: uuid
          description: 平台资产 UUID，列表与所有交易接口共用
          example: 7453f146-b267-11f1-b4f4-0abd773ba497
        symbol:
          type: string
          description: 资产代码。
          example: AAPLx
        quantity:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: 账户持有的有效资产总数量。
          example: '0.00297066689243735'
        available_quantity:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: 从 quantity 扣除 frozen_quantity 后的可用有效数量。
          example: '0.00297066689243735'
        frozen_quantity:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: 当前已冻结、不可用于另一笔交易的有效数量。
          example: '0'
        updated_at:
          type: string
          format: date-time
          description: 持仓最近更新时间。
          example: '2026-09-21T01:50:53.852Z'
      required:
        - asset_id
        - symbol
        - quantity
        - available_quantity
        - frozen_quantity
        - updated_at
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: 由 UQPAY 提供的登录 API Token。

````