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

# 抽卡接入指南

> 通过 v2 API 准备开包、签署付款、恢复抽卡进度并结算回购。

由后端提供开发者密钥，让买家使用钱包签名。浏览公开卡包时无需连接钱包。

## 浏览卡包

| 想展示的内容 | 使用的接口 |
| - | - |
| 可用卡包 | [列出卡包](https://docs.renaiss.xyz/cn/api-reference/gacha/list-packs.md)。按 `stage` 筛选，用 `limit` 和 `offset` 分页。 |
| 价格、各档概率和回购规则 | 用 `slug` [查询卡包详情](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pack.md)。 |
| 可能抽出的卡牌 | [查询卡包内容](https://docs.renaiss.xyz/cn/api-reference/gacha/list-pack-contents.md)。 |
| 最近公开的抽卡结果 | [查询卡包公开记录](https://docs.renaiss.xyz/cn/api-reference/gacha/list-pack-history.md)。 |

浏览公开卡包可省略 `x-builder-api-key`。传入密钥还可看到专门向你的应用开放的卡包。列表会省略无权访问的卡包。使用这类卡包的 slug 查询会返回 HTTP `404`。使用密钥的请求会计入该密钥的限流额度。

准备购买时使用目录中的 `id`，核对钱包签名时使用 `onChainPackId`。`activeSetExpectedValueInUsd` 是当前整组卡牌的平均价值，单位为美分。剩余卡牌的平均价值可能不同。

## 提交抽卡

**1. 准备购买**

将买家钱包地址、目录中的卡包 ID 和数量提交至[准备抽卡](https://docs.renaiss.xyz/cn/api-reference/gacha/prepare-pull.md)接口。核对返回的钱包、链、卡包 ID、售卡机合约和每张卡的价格，确保与买家确认的内容一致。

**2. 检查 USDT 授权额度**

在 `approval` 中核对所选网络的 USDT 合约、Permit2 支出方和所需额度。如果需要授权，钱包必须有 BNB 支付 Gas。等待授权交易确认后再继续。

**3. 签署购买数据**

核对 Permit2 的域、支出方、金额、nonce 和截止时间。检查 witness 中的链上卡包 ID、开发者代码和数量，再让买家签署 `permit2TypedData`。

从 `unsignedPullPayload` 复制 `packId`、`numOfTokens`、`amountPerToken`、`nonce` 和 `deadline`，再加上 `buyerWalletAddress` 和 `permitSignature`。接口通过密钥确定开发者代码。

**4. 提交一次，跟踪结果**

选择下表中的一种方式提交。如果价格或签名内容发生变化，先请买家重新核对。

| 提交方式 | 如何跟踪结果 |
| - | - |
| [提交抽卡请求](https://docs.renaiss.xyz/cn/api-reference/gacha/submit-pull.md) | 保存 HTTP `202` 返回的 `requestId`，约每秒[查询一次抽卡状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pull-status.md)。 |
| [使用事件流](https://docs.renaiss.xyz/cn/api-reference/gacha/stream-pull.md) | 收到 `pull_started` 时保存 `data.requestId`，收到 `payment_confirmed` 时保存 `data.permitFundTxHash`。收到 `draws_resolved` 后展示卡牌。 |

## 恢复中断的抽卡

如果已取得 `requestId`，使用原开发者密钥[查询请求状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-pull-status.md)。

| 状态 | 处理方式 |
| - | - |
| `PENDING_PAYMENT` | 继续轮询。若持续超过十分钟，请停止轮询并携原 ID 联系 Renaiss。使用新 nonce 再签名可能导致重复扣款。 |
| `PENDING_RESOLUTION` | 付款已确认，等待抽卡结果。 |
| `RESOLVED` | 展示抽到的卡牌，另行核对是否已转入钱包。 |
| `FAILED` | 买家未被扣款。重试前先查看错误码。 |

如果还没收到 ID 就断开了连接，或提交时收到 HTTP `5xx`，请向 [`POST /v2/gacha/pull/request`](https://docs.renaiss.xyz/cn/api-reference/gacha/submit-pull) 重发**同一份已签名的抽卡数据**，找回原 `requestId`。每次只发送一个重试请求。如果保存了付款哈希，也可用 `buyerWalletAddress` 和 `permitFundTxHash` [查询抽卡结果](https://docs.renaiss.xyz/cn/api-reference/gacha/get-draw.md)。

抽卡状态为 `FAILED` 时，请按 [`error.code` 对应的步骤](https://docs.renaiss.xyz/cn/api-reference/gacha/submit-pull#pull-failures)处理。若为 `INSUFFICIENT_USDT_AMOUNT`，请补足钱包的 USDT 余额。若为 `INSUFFICIENT_ALLOWANCE`，请提高 Permit2 授权额度。等待链上确认后，在签名截止前重发原请求即可使用同一 ID 重新抽卡。如果签名已过期，请重新准备并签名。

## 回购与交付

抽卡结果确定后，卡牌在回购期内由 Renaiss 保管。买家可以接受当前回购报价，也可以保留卡牌，等待转入钱包。

### 回购价值与加成

| 数据来源 | 如何展示 |
| - | - |
| [卡包内容](https://docs.renaiss.xyz/cn/api-reference/gacha/list-pack-contents.md) | `buybackBaseValueInUsd` 是目录中展示的价值，单位为美分。买家抽中卡牌后可查询实际报价。 |
| [钱包藏品](https://docs.renaiss.xyz/cn/api-reference/wallets/list-collectibles.md) | 状态为 `IN_BUYBACK_WINDOW` 时，可用 `state.buybackBaseValueInUSD` 展示回购基础价值。`state.buybackTiers` 中第一个未过期档位的 `amountInUsdt` 是当前报价。 |
| [回购报价](https://docs.renaiss.xyz/cn/api-reference/gacha/list-buybacks.md) | 签名前刷新报价，使用返回的档位金额。各档金额均已包含加成，此接口不单列加成明细。 |

卡牌有加成时，`buybackBonus.originalBuybackBaseValueInUSD` 是加成前的价值，单位为美分。`buybackBonus.bonusBps` 是以基点表示的比例，例如 `2000` 表示 20%。接口返回的基础价值和各档金额已包含加成，可直接使用。

以下响应提供 `buybackBonus`：抽卡结果查询、事件流的 `draws_resolved` 事件、已完成抽卡请求的 `result`、钱包活动、卡包公开抽卡记录，以及回购期内的钱包藏品。如果没有加成或无法读取抽卡详情，该字段为 `null`。查询卡包公开记录时，省略开发者密钥也会使该字段返回 `null`。

### 回售卡牌

1. [查询买家的回购报价](https://docs.renaiss.xyz/cn/api-reference/gacha/list-buybacks.md)。按顺序读取 `buybackTiers`，展示第一个未过期档位的金额。金额为零时没有回购款。如果价格变化，先展示新金额，再请求签名。
2. 请买家签署 `BuybackUserAuthorization`。一笔回购可包含同一卡包和合约的 1 至 10 个结算 ID。每个 ID 都须符合回购条件，且不能重复。
3. 选择[直接结算](https://docs.renaiss.xyz/cn/api-reference/gacha/settle-buyback.md)或[提交后轮询](https://docs.renaiss.xyz/cn/api-reference/gacha/submit-buyback.md)。轮询时，保存返回的 `requestId`，约每秒[查询一次回购状态](https://docs.renaiss.xyz/cn/api-reference/gacha/get-buyback-status.md)，直到返回 `COMPLETED` 或 `FAILED`。

两种接口接受同一份已签名的回购数据。每次向轮询接口提交都会生成独立请求。请使用原开发者密钥查询状态，等待该请求结束后再决定是否重试。若 `PENDING` 持续超过十分钟，请停止轮询，携原 `requestId` 联系 Renaiss。

回购状态为 `FAILED` 且错误码为 `OP_WALLET_BUSY` 时，请稍等几秒，再使用原签名重试。其他错误请先刷新回购报价，再签署新请求。

### 保留卡牌

回购期从抽卡结果确定时开始，时长取**当时**卡包 `buybackConfig` 中最大的 `buybackExpiredInSeconds`。后续调整仅影响之后的抽卡。

回购期结束后，Renaiss 会将卡牌转入买家钱包。展示“已到账”前，核对 `releaseTxHash` 和链上持有人。卡牌出现在公开记录中时，交付仍可能尚未完成。

## 两类抽卡记录

| 查询方式 | 返回内容 |
| - | - |
| [钱包抽卡记录](https://docs.renaiss.xyz/cn/api-reference/gacha/list-wallet-pulls.md) | 该买家通过你的应用完成的抽卡，需要开发者密钥。 |
| [卡包公开记录](https://docs.renaiss.xyz/cn/api-reference/gacha/list-pack-history.md) | 最近最多 100 次抽卡，最新的排在最前。回购期结束或结果确定满 24 小时后公开，以较早者为准。限量卡包返回空列表。 |


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