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

# 按付款哈希查询抽卡

> 使用买家钱包地址和原付款交易的哈希查询抽卡结果。

使用原开发者密钥，提交原买家钱包地址和付款哈希。其他开发者的交易会返回 HTTP `404`。

抽卡结果可能先于卡牌到账。托管期限、到账确认和记录公开时间见[回购与交付](https://docs.renaiss.xyz/cn/gacha.md#回购与交付)。

## 请求

需要开发者密钥

## 响应

## 错误码

在下表中查找接口返回的 HTTP 状态码和响应原文。有关各接口通用的处理建议，请参阅[错误码含义与处理方式](https://docs.renaiss.xyz/cn/api-reference/errors.md)。

| HTTP | 错误码 | 文本字段 | 响应文本与处理方式 |
| :- | :- | :- | :- |
| `400` | `WRONG_REQUEST_PARAMS` | `message` | `Bad request - invalid parameters` 字段缺失或格式错误。修正后重新发送， |
| `401` | `API_AUTH_INVALID_CREDENTIAL` | `error` | `Invalid authentication credential` 开发者密钥格式错误、未知、已过期或已撤销。请核对并更换密钥。 |
| `401` | `API_AUTH_MISSING_CREDENTIAL` | `error` | `Required authentication credential is missing` 请在 `x-builder-api-key` 请求头中提供开发者密钥。 |
| `403` | `API_AUTH_CREDENTIAL_NOT_ALLOWED` | `error` | `Credential is not allowed by this policy` 此路由只接受开发者密钥。移除 `Authorization` 请求头及其他凭据，再重新发送。 |
| `403` | `GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API` | `error` | `This builder checks out on its own surface, not on the public API` 此密钥无法用于当前 API。请联系 Renaiss，无需重试。 |
| `404` | `EOA_PURCHASE_REJECTED` | `error` | `Confirmed pull not found` 当前开发者名下没有匹配钱包和付款哈希的已确认抽卡。请核对两个值；刚发送的交易可能尚未打包，几秒后再查。 |
| `429` | `API_AUTH_RATE_LIMITED` | `error` | `Authentication rate limit exceeded` 已达到密钥的请求频率上限。稍候再以较低频率重试。 |
| `500` | `API_AUTH_ERROR` | `error` | `Internal server error` |
| `500` | `FUNCTION_ERROR` | `error` | `Internal server error` |
| `500` | 其他错误码 | `error` | `Internal server error` |


## OpenAPI

````yaml cn/api-reference/openapi.json GET /v2/gacha/draw-status
openapi: 3.1.1
info:
  version: 1.0.0
  title: Renaiss 开发者 API v2
  description: >-
    在 BNB 智能链（链 ID 56）上使用外部钱包接入抽卡、交易市场和实物兑换。所有已批准且有效的开发者密钥均可准备购买。


    藏品包括钱包可抽取、交易、回售或兑换的物品，例如卡牌。接口路径、字段和描述统一使用 collectible 表示藏品。


    可以匿名浏览目录。准备购买后，请由买家钱包签名。抽卡记录和回购报价需要开发者密钥，购买和回购还需操作签名。私有配送信息及兑换需要钱包访问令牌，由钱包在已注册的合作方来源签署登录消息后签发。抽卡和市场不使用钱包访问令牌。请在后端保管开发者密钥。


    操作钱包可以是 EOA 或已部署的 ERC-1271 合约账户。不支持 EIP-7702 委托账户、ERC-6492 或 ERC-8010 封装签名及
    Renaiss 托管的 Safe（签名验证后才会识别并拒绝该类 Safe）。无法接收 ERC-721 的合约钱包抽卡会返回
    `CONTRACT_WALLET_CANNOT_RECEIVE_NFT`。链上读取失败返回
    `API_AUTH_ERROR`（500）。钱包访问令牌及实物兑换仅支持 EOA。
servers:
  - url: https://api.renaiss.xyz
    description: BNB 智能链主网
  - url: https://dev-api.renaiss.xyz
    description: BNB 测试网
security: []
tags:
  - name: Gacha v2
    description: 使用 EOA 浏览和购买卡包、揭晓藏品、读取购买记录及回购。无需钱包访问令牌。
  - name: Marketplace
    description: 公开浏览藏品，通过外部钱包挂牌、出价、购买或撤单。交易需要开发者授权及钱包操作签名。
  - name: Users
    description: 查询特定钱包的藏品、市场总估值和链上活动。仅需开发者密钥，各接口按相应的可见范围返回记录。
  - name: Redemption
    description: 查询兑换资格、运费报价，准备并提交兑换及跟踪物流。需要开发者密钥及同一钱包的访问令牌。
  - name: Wallet access tokens
    description: >-
      获取、刷新或撤销实物兑换使用的钱包访问令牌。钱包签署一次性登录消息（5 分钟有效）后，API 返回访问令牌（15 分钟）和一次性刷新令牌（7
      天）。先注册精确的合作方前端来源。抽卡和市场无需钱包访问令牌。
paths:
  /v2/gacha/draw-status:
    get:
      tags:
        - Gacha v2
      summary: 按已确认的付款交易查询抽卡结果
      description: 使用买家钱包地址和原付款交易的哈希查询抽卡结果。
      parameters:
        - schema:
            type: string
          required: true
          name: buyerWalletAddress
          in: query
        - schema:
            type: string
          required: true
          name: permitFundTxHash
          in: query
      responses:
        '200':
          description: 成功
          content:
            application/json:
              schema:
                type: object
                properties:
                  permitFundTxHash:
                    type: string
                    description: 32 字节，以 0x 开头，后接 64 个十六进制数字。
                  buyerWalletAddress:
                    type: string
                    description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。
                  packId:
                    type: string
                    format: uuid
                  packName:
                    type: string
                  status:
                    type: string
                    enum:
                      - PENDING_RESOLUTION
                      - RESOLVED
                  numOfTokens:
                    type: integer
                    exclusiveMinimum: 0
                  pulledAt:
                    type:
                      - string
                      - 'null'
                    format: date-time
                  draws:
                    type: array
                    items:
                      type: object
                      properties:
                        settlementId:
                          type: string
                          description: 32 字节，以 0x 开头，后接 64 个十六进制数字。
                        tokenId:
                          type: string
                        releaseTxHash:
                          type:
                            - string
                            - 'null'
                          description: 32 字节，以 0x 开头，后接 64 个十六进制数字。
                        buybackTxHash:
                          type:
                            - string
                            - 'null'
                          description: 32 字节，以 0x 开头，后接 64 个十六进制数字。
                        buybackTiers:
                          type: array
                          items:
                            type: object
                            properties:
                              buybackPercentage:
                                type: number
                                description: 相对于卡牌基础价值的百分比，例如 90 表示 90%。
                              amountInUsdt:
                                type: string
                                description: 本档回购价格，以精度为 18 位的 USDT 最小单位表示。
                              expiresAt:
                                type: string
                                description: 本档截止时间。在此时刻该档仍有效。
                            required:
                              - buybackPercentage
                              - amountInUsdt
                              - expiresAt
                          description: >-
                            本次抽卡的全部回购档位（包含已过期档位），按截止时间排序。价格与 `GET
                            /v2/gacha/buyback/offers` 一致。展示第一个尚未超过 `expiresAt`
                            的档位的
                            `amountInUsdt`，在截止时刻该档仍有效。确认回购前再次查询报价，并签署该接口返回的金额。回售或交付后档位仍会保留，通过
                            `buybackTxHash` 和 `releaseTxHash` 判断实际结果。无回购时返回空列表。
                        tier:
                          anyOf:
                            - type: string
                              enum:
                                - TOP
                                - S
                                - A
                                - B
                                - C
                                - D
                            - type: string
                              enum:
                                - epic
                                - rare
                                - uncommon
                                - common
                                - legendary
                                - thorn
                                - bloom
                                - crown
                            - type: 'null'
                          description: 藏品在本次抽卡中的档位。无法加载藏品详情时为 `null`。
                        buybackBaseValueInUSD:
                          type:
                            - string
                            - 'null'
                          description: 藏品的回购基础价值，以美分计，已含加成。无法加载藏品详情时为 `null`。
                        buybackBonus:
                          type:
                            - object
                            - 'null'
                          properties:
                            originalBuybackBaseValueInUSD:
                              type: string
                              description: 加成前的回购基础价值，以美分计，在该组卡牌形成时确定。
                            bonusBps:
                              type: integer
                              description: 加成基点数，例如 2000 表示增加 20%。
                          required:
                            - originalBuybackBaseValueInUSD
                            - bonusBps
                          description: >-
                            藏品的回购加成。回购基础价值及 `buybackTiers` 已包含该加成。没有加成或无法加载详情时为
                            `null`。
                        type:
                          type: string
                          enum:
                            - POKEMON
                            - ONE_PIECE
                            - SPORTS
                          description: 藏品类别。
                        name:
                          type: string
                          description: 评级、年份、系列、编号和名称。
                        frontImageUrl:
                          type: string
                          format: uri
                          description: 深色背景下带 Renaiss 边框的评级卡盒照片。
                        attributes:
                          type: array
                          items:
                            type: object
                            properties:
                              key:
                                type: string
                              value:
                                type: string
                            required:
                              - key
                              - value
                          description: >-
                            藏品属性以键值对返回。卡牌依次使用 Grader、Grade、Cert
                            Number、Year、Set、Card
                            Number、Character、Language。没有值的属性会省略，所有值均为字符串。
                      required:
                        - settlementId
                        - tokenId
                        - releaseTxHash
                        - buybackTxHash
                        - buybackTiers
                        - tier
                        - buybackBaseValueInUSD
                        - buybackBonus
                required:
                  - permitFundTxHash
                  - buyerWalletAddress
                  - packId
                  - packName
                  - status
                  - numOfTokens
                  - pulledAt
                  - draws
        '400':
          description: |-
            请求在执行前被拒绝。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  code:
                    type: string
                    enum:
                      - WRONG_REQUEST_PARAMS
                  message:
                    type: string
                    description: 简短的错误说明。
                required:
                  - code
                  - message
              example:
                code: WRONG_REQUEST_PARAMS
                message: Bad request - invalid parameters
        '401':
          description: |-
            缺少开发者密钥或密钥未通过验证。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: 简短的错误说明。
                  code:
                    type: string
                    enum:
                      - API_AUTH_MISSING_CREDENTIAL
                      - API_AUTH_INVALID_CREDENTIAL
                required:
                  - error
                  - code
              example:
                error: Required authentication credential is missing
                code: API_AUTH_MISSING_CREDENTIAL
        '403':
          description: |-
            当前凭据无权执行此请求。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: 简短的错误说明。
                  code:
                    type: string
                    enum:
                      - API_AUTH_CREDENTIAL_NOT_ALLOWED
                      - GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API
                required:
                  - error
                  - code
              example:
                error: Credential is not allowed by this policy
                code: API_AUTH_CREDENTIAL_NOT_ALLOWED
        '404':
          description: |-
            未找到已确认的抽卡。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: 简短的错误说明。
                  code:
                    type: string
                    enum:
                      - EOA_PURCHASE_REJECTED
                required:
                  - error
                  - code
              example:
                error: Confirmed pull not found
                code: EOA_PURCHASE_REJECTED
        '429':
          description: |-
            该开发者密钥的请求过于频繁。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: 简短的错误说明。
                  code:
                    type: string
                    enum:
                      - API_AUTH_RATE_LIMITED
                required:
                  - error
                  - code
              example:
                error: Authentication rate limit exceeded
                code: API_AUTH_RATE_LIMITED
        '500':
          description: |-
            服务端暂时失败，请稍后重试。

            见[错误码与处理方式](/cn/api-reference/gacha/get-draw#http-errors)。
          content:
            application/json:
              schema:
                type: object
                properties:
                  error:
                    type: string
                    description: 简短的错误说明。
                  code:
                    type: string
                required:
                  - error
                  - code
              example:
                error: Internal server error
                code: FUNCTION_ERROR
      security:
        - builderAuth: []
components:
  securitySchemes:
    builderAuth:
      type: apiKey
      in: header
      name: x-builder-api-key
      description: >-
        已获准使用的开发者 API 密钥，仅在后端保存。抽卡和市场的写入操作还需钱包签名，实物兑换还需钱包签署登录消息后由 API 签发的 Bearer
        令牌。

````

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