> ## 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. # 查询钱包活动 > 按时间倒序查看钱包的链上卡牌活动。使用游标翻页读取抽卡、回购、交易、转账和兑换记录。 **读取事件。** 每条记录对应该地址的一次链上事件，包括铸造、交付和兑换销毁。签名地址和 Safe 钱包需要分别查询。Renaiss 托管钱包没有活动记录，未向当前密钥开放的卡包事件也会省略。 | 事件信息 | 用法 | | - | - | | 卡包或结算 ID | 可将抽卡事件中的卡包 ID 与目录的 `onChainPackId` 对照，或将回购事件中的结算 ID 与钱包抽卡记录的 `settlementId` 对照。 | | `collectibles[]` | 通过你的应用抽卡，结果确定后即可展示卡牌。其他开发者的普通 v3 抽卡须等待原回购期结束，且已确认交付或回售。限量卡包的历史关联仅对卖方可见。商店抽卡仅返回链上信息。 | | 金额 | 事件金额为总额。符合条件的卡牌可返回抽卡时锁定的 `buybackBaseValueInUsd`（美分）。回购事件还可返回 18 位精度的 `buybackPaidInUsdt`，其值可能为 `null`。 | **翻页。** 将 `nextCursor` 作为下一次请求的 `cursor`。即使当前页为空，只要仍有游标，就继续翻页。值为 `null` 时结束。一笔交易包含的多个事件可能分布在不同页。 ## 请求 需要开发者密钥 ## 响应 ## 错误码 在下表中查找接口返回的 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，无需重试。 | | `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` | `ACTIVITY_QUERY_FAILED` | `error` | `Internal server error` 请稍后重新查询。 | | `500` | 其他错误码 | `error` | `Internal server error` | | `500` | 无错误码 | `text/plain` | `Internal Server Error` | ## OpenAPI ````yaml cn/api-reference/openapi.json GET /v2/users/{walletAddress}/activities 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/users/{walletAddress}/activities: get: tags: - Users summary: 列出钱包的链上藏品活动 description: 按时间倒序查看钱包的链上卡牌活动。使用游标翻页读取抽卡、回购、交易、转账和兑换记录。 parameters: - schema: type: string description: 只查询传入的这个钱包地址。 required: true description: 只查询传入的这个钱包地址。 name: walletAddress in: path - schema: type: string enum: - all - gacha-v3-pull - gacha-v3-buyback - gacha-v3-release-token - buy - sell - transfer - mint - burn default: all description: 按活动类型筛选。all 表示全部类型。 required: false description: 按活动类型筛选。all 表示全部类型。 name: filter in: query - schema: type: string pattern: ^\d+$ required: false name: cursor in: query - schema: type: integer minimum: 1 maximum: 50 default: 20 required: false name: limit in: query responses: '200': description: 成功 content: application/json: schema: type: object properties: activities: type: array items: oneOf: - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string type: type: string enum: - gacha-v3-pull contractAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 packId: type: string description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 token: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 checkoutIds: type: array items: type: string pattern: ^\d+$ totalAmount: type: string pattern: ^\d+$ blockHash: type: string collectibles: type: array items: type: object properties: type: type: string enum: - POKEMON - ONE_PIECE - SPORTS description: 藏品类别。 name: type: string description: 评级、年份、系列、编号和名称。 frontImageUrl: type: string format: uri description: 深色背景下带 Renaiss 边框的评级卡盒照片。 tokenId: type: string pattern: ^\d+$ subtitle: type: string description: 系列与年份之间用 • 分隔，与网页动态一致。两项均缺失时为空。 buybackBaseValueInUsd: type: string pattern: ^\d+$ description: 该历史卡位锁定的回购基础价值，以美分计，含加成，不代表当前估值或购买价。 buybackBonus: type: - object - 'null' properties: originalBuybackBaseValueInUSD: type: string description: 加成前的回购基础价值，以美分计，在该组卡牌形成时确定。 bonusBps: type: integer description: 加成基点数，例如 2000 表示增加 20%。 required: - originalBuybackBaseValueInUSD - bonusBps description: >- 藏品的回购加成。回购基础价值及 `buybackTiers` 金额已计入加成，不要重复计算。无加成时为 `null`。 required: - type - name - frontImageUrl - tokenId - subtitle - buybackBaseValueInUsd - buybackBonus description: >- 可展示当前开发者售出且结果已确定的藏品，以及回购期结束且已确认交付或回售的普通 v3 抽卡。限量卡包历史关联仅向卖方显示。只含指定钱包的 `EXTERNAL` 抽卡，无符合条件的藏品时省略；批次内可能只返回部分藏品，按事件标识的顺序排列。 required: - user - timestamp - blockNumber - txHash - type - contractAddress - packId - token - checkoutIds - totalAmount - blockHash - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string type: type: string enum: - gacha-v3-buyback contractAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 buybackIds: type: array items: type: string description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 token: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 priceInUsdt: type: string pattern: ^\d+$ collectibles: type: array items: type: object properties: type: type: string enum: - POKEMON - ONE_PIECE - SPORTS description: 藏品类别。 name: type: string description: 评级、年份、系列、编号和名称。 frontImageUrl: type: string format: uri description: 深色背景下带 Renaiss 边框的评级卡盒照片。 tokenId: type: string pattern: ^\d+$ subtitle: type: string description: 系列与年份之间用 • 分隔，与网页动态一致。两项均缺失时为空。 buybackBaseValueInUsd: type: string pattern: ^\d+$ description: 该历史卡位锁定的回购基础价值，以美分计，含加成，不代表当前估值或购买价。 buybackBonus: type: - object - 'null' properties: originalBuybackBaseValueInUSD: type: string description: 加成前的回购基础价值，以美分计，在该组卡牌形成时确定。 bonusBps: type: integer description: 加成基点数，例如 2000 表示增加 20%。 required: - originalBuybackBaseValueInUSD - bonusBps description: >- 藏品的回购加成。回购基础价值及 `buybackTiers` 金额已计入加成，不要重复计算。无加成时为 `null`。 buybackPaidInUsdt: type: - string - 'null' pattern: ^\d+$ description: >- 仅用于回购活动。表示每件藏品实际支付的 USDT，精度为 18 位。历史付款无法确认时为 `null`。 required: - type - name - frontImageUrl - tokenId - subtitle - buybackBaseValueInUsd - buybackBonus - buybackPaidInUsdt description: >- 可展示当前开发者售出且结果已确定的藏品，以及回购期结束且已确认交付或回售的普通 v3 抽卡。限量卡包历史关联仅向卖方显示。只含指定钱包的 `EXTERNAL` 抽卡，无符合条件的藏品时省略；批次内可能只返回部分藏品，按事件标识的顺序排列。 required: - user - timestamp - blockNumber - txHash - type - contractAddress - buybackIds - token - priceInUsdt - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - gacha-v3-release-token contractAddress: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 releaseTokenId: type: string description: 32 字节，以 0x 开头，后接 64 个十六进制数字。 nftTokenId: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - contractAddress - releaseTokenId - nftTokenId - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - buy bidder: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 asker: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 nftTokenId: type: string pattern: ^\d+$ erc20Token: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 amount: type: string pattern: ^\d+$ feeAccrued: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - bidder - asker - nftTokenId - erc20Token - amount - feeAccrued - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - sell bidder: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 asker: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 nftTokenId: type: string pattern: ^\d+$ erc20Token: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 amount: type: string pattern: ^\d+$ feeAccrued: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - bidder - asker - nftTokenId - erc20Token - amount - feeAccrued - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - transfer to: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 tokenId: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - to - tokenId - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - mint tokenAmount: type: string pattern: ^\d+$ tokenId: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - tokenAmount - tokenId - type: object properties: user: type: string description: 带 0x 前缀的 20 字节钱包或合约地址。请使用全小写或有效的校验和格式。 timestamp: type: string pattern: ^\d+$ blockNumber: type: string pattern: ^\d+$ txHash: type: string item: type: object properties: tokenId: type: string pattern: ^\d+$ imageUrl: type: string title: type: string subtitle: type: string required: - tokenId - imageUrl - title - subtitle type: type: string enum: - burn tokenAmount: type: string pattern: ^\d+$ tokenId: type: string pattern: ^\d+$ required: - user - timestamp - blockNumber - txHash - type - tokenAmount - tokenId nextCursor: type: - string - 'null' required: - activities - nextCursor '400': description: |- 请求在执行前被拒绝。 见[错误码与处理方式](/cn/api-reference/wallets/list-activities#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/wallets/list-activities#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/wallets/list-activities#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 '429': description: |- 该开发者密钥的请求过于频繁。 见[错误码与处理方式](/cn/api-reference/wallets/list-activities#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/wallets/list-activities#http-errors)。 content: text/plain: schema: type: string example: Internal Server Error 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.