> ## 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.

# 创建报价

> 按资金金额申请买入报价，或按数量申请卖出报价。仅提交对应的一个正数十进制字符串；创建订单前检查报价有效期和可空字段。 示例包含实际 Sandbox 标识。新操作应获取新报价并使用新幂等键。

<RequestExample>
  ```bash cURL
  curl --request POST \
    --url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/quote' \
    --header "Content-Type: application/json" \
    --header "x-auth-token: Bearer ${SANDBOX_TOKEN}" \
    --header "x-idempotency-key: ${UNIQUE_IDEMPOTENCY_KEY}" \
    --data '{
    "asset_id": "7453f146-b267-11f1-b4f4-0abd773ba497",
    "side": "BUY",
    "funding_currency": "USDC",
    "cash_amount": "1"
  }'
  ```
</RequestExample>

<ResponseExample>
  ```json 200
  {
    "quote_id": "0576b03b-56dd-48b1-ba24-058ce90d0f53",
    "asset_id": "7453f146-b267-11f1-b4f4-0abd773ba497",
    "symbol": "AAPLx",
    "side": "BUY",
    "network": "Ethereum",
    "funding_currency": "USDC",
    "quantity": "0.00297066689243735",
    "price": "336.624750000000055741",
    "cash_amount": "1",
    "fees": [
      {
        "type": "TRADING",
        "amount": "0.0005",
        "currency": "USDC"
      }
    ],
    "total_amount": "1.0005",
    "created_at": "2026-09-21T01:33:07.797Z",
    "expires_at": "2026-09-21T01:34:04.542Z"
  }
  ```
</ResponseExample>


## OpenAPI

````yaml /zh/stocks/stocks.yaml post /quote
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:
  /quote:
    post:
      tags:
        - Stocks
      summary: 创建报价
      description: >-
        按资金金额申请买入报价，或按数量申请卖出报价。仅提交对应的一个正数十进制字符串；创建订单前检查报价有效期和可空字段。 示例包含实际
        Sandbox 标识。新操作应获取新报价并使用新幂等键。
      operationId: createStocksQuote
      parameters:
        - name: x-idempotency-key
          in: header
          required: true
          schema:
            type: string
            format: uuid
            pattern: ^[0-9a-f]{8}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{4}-[0-9a-f]{12}$
          description: 用于维持操作幂等性的唯一标识符。同一操作重试时使用相同的键和请求内容；新的操作使用新的键。
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/QuoteRequest'
            examples:
              sandbox:
                summary: Sandbox request
                value:
                  asset_id: 7453f146-b267-11f1-b4f4-0abd773ba497
                  side: BUY
                  funding_currency: USDC
                  cash_amount: '1'
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Quote'
              examples:
                sandbox:
                  summary: Sandbox response
                  value:
                    quote_id: 0576b03b-56dd-48b1-ba24-058ce90d0f53
                    asset_id: 7453f146-b267-11f1-b4f4-0abd773ba497
                    symbol: AAPLx
                    side: BUY
                    network: Ethereum
                    funding_currency: USDC
                    quantity: '0.00297066689243735'
                    price: '336.624750000000055741'
                    cash_amount: '1'
                    fees:
                      - type: TRADING
                        amount: '0.0005'
                        currency: USDC
                    total_amount: '1.0005'
                    created_at: '2026-09-21T01:33:07.797Z'
                    expires_at: '2026-09-21T01:34:04.542Z'
        '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 POST \
              --url 'https://api-sandbox.uqpaytech.com/api/v1/stocks/quote' \
              --header "Content-Type: application/json" \
              --header "x-auth-token: Bearer ${SANDBOX_TOKEN}" \
              --header "x-idempotency-key: ${UNIQUE_IDEMPOTENCY_KEY}" \
              --data '{
              "asset_id": "7453f146-b267-11f1-b4f4-0abd773ba497",
              "side": "BUY",
              "funding_currency": "USDC",
              "cash_amount": "1"
            }'
components:
  schemas:
    QuoteRequest:
      oneOf:
        - type: object
          additionalProperties: false
          properties:
            asset_id:
              type: string
              format: uuid
              description: List assets 返回的资产标识。
              example: 7453f146-b267-11f1-b4f4-0abd773ba497
            side:
              type: string
              enum:
                - BUY
              example: BUY
            funding_currency:
              type: string
              enum:
                - USDC
              description: 交易使用的资金币种。
              example: USDC
            cash_amount:
              type: string
              pattern: ^[0-9]{1,18}(\.[0-9]{1,6})?$
              description: 不含手续费的正数资金金额。不要同时提交 quantity。
              example: '1'
          required:
            - asset_id
            - side
            - funding_currency
            - cash_amount
          title: Buy quote
        - type: object
          additionalProperties: false
          properties:
            asset_id:
              type: string
              format: uuid
              description: List assets 返回的资产标识。
            side:
              type: string
              enum:
                - SELL
            funding_currency:
              type: string
              enum:
                - USDC
              description: 交易使用的资金币种。
            quantity:
              type: string
              pattern: ^[0-9]{1,18}(\.[0-9]{1,8})?$
              description: 拟卖出的正数资产数量。不要同时提交 cash_amount。
          required:
            - asset_id
            - side
            - funding_currency
            - quantity
          title: Sell quote
    Quote:
      type: object
      additionalProperties: false
      properties:
        quote_id:
          type: string
          format: uuid
          description: 创建订单时提交的报价标识。
          example: 0576b03b-56dd-48b1-ba24-058ce90d0f53
        asset_id:
          type: string
          format: uuid
          description: 平台资产 UUID，列表与所有交易接口共用
          example: 7453f146-b267-11f1-b4f4-0abd773ba497
        symbol:
          type: string
          description: 资产代码。
          example: AAPLx
        side:
          type: string
          enum:
            - BUY
            - SELL
          description: 拟进行交易的方向。
          example: BUY
        network:
          type: string
          description: 报价所选的区块链网络；报价请求不指定网络。
          example: Ethereum
        funding_currency:
          type: string
          enum:
            - USDC
          description: 资金币种，现为 USDC
          example: USDC
        quantity:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          nullable: true
          description: 报价中的资产数量；需要在执行时确定数量时为 null。
          example: '0.00297066689243735'
        price:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          nullable: true
          description: 以 funding_currency 计价的每单位报价；报价未确定执行价格时为 null。
          example: '336.624750000000055741'
        cash_amount:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          nullable: true
          description: 以 funding_currency 计价、不含手续费的交易金额；需要在执行时确定时为 null。
          example: '1'
        fees:
          type: array
          items:
            $ref: '#/components/schemas/Fee'
          nullable: true
          description: 报价中的费用。null 表示费用暂不可用，不代表免收费用。
        total_amount:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          nullable: true
          description: 以 funding_currency 计价，买入时为含手续费的总支出，卖出时为扣除手续费后的收入；尚无法确定时为 null。
          example: '1.0005'
        created_at:
          type: string
          format: date-time
          description: 报价创建时间。
          example: '2026-09-21T01:33:07.797Z'
        expires_at:
          type: string
          format: date-time
          nullable: true
          description: 客户确认截止时间；过期后应申请新报价
          example: '2026-09-21T01:34:04.542Z'
      required:
        - quote_id
        - asset_id
        - symbol
        - side
        - network
        - funding_currency
        - quantity
        - price
        - cash_amount
        - fees
        - total_amount
        - created_at
        - expires_at
    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: 错误原因的可读说明。
    Fee:
      type: object
      additionalProperties: false
      properties:
        type:
          type: string
          enum:
            - TRADING
            - DEPOSIT
            - WITHDRAWAL
          description: 费用类别。
          example: TRADING
        amount:
          type: string
          pattern: ^-?[0-9]+(\.[0-9]+)?$
          description: 费用金额
          example: '0.0005'
        currency:
          type: string
          description: 收取费用的币种。
          example: USDC
      required:
        - type
        - amount
        - currency
  securitySchemes:
    AuthToken:
      type: apiKey
      in: header
      name: x-auth-token
      description: 由 UQPAY 提供的登录 API Token。

````