跳转到主要内容
你的应用负责登录和钱包连接。外部账户(EOA)无需登录 Renaiss 即可使用抽卡、市场和实物兑换。抽卡和市场 HTTP API 也接受符合条件的已部署合约钱包。每次操作都会分别检查开发者权限和钱包授权。

各项操作所需凭据

开发者密钥放在 x-builder-api-key 中。钱包令牌使用 Authorization: Bearer <accessToken>。接口同时要求两种凭据时,请同时发送两个请求头。钱包验证后才会签发访问令牌。请求质询时,scopes 必须同时包含 redeem:read 和 redeem:write。令牌仅授权该钱包与该开发者之间的私有兑换操作。

在后端保管密钥

让浏览器 SDK 调用你的后端,例如 /api/renaiss。后端转发到指定的 Renaiss API,仅对接受开发者密钥的路由添加密钥。公开市场查询请省略凭据。 后端应验证用户会话、逐项授权并限流。仅允许必要的上游路径和 HTTP 方法。由后端设置密钥,不要转发客户端传入的密钥。按需转发钱包访问令牌,并保留抽卡请求的流式响应。 不要将开发者密钥存入 NEXT_PUBLIC_* 变量或返回给浏览器。日常日志应排除访问令牌、刷新令牌、签名和收货信息。

选择执行操作的钱包

EOA 可直接为抽卡和市场操作签名。已部署的合约账户须通过 ERC-1271 验证操作签名,且验证逻辑必须将账户地址与签名意图绑定。买家或卖家地址应填合约账户本身。抽卡前还需确认它能接收 ERC-721 安全转账。 这些流程不支持 Renaiss 托管的 Safe 或 EIP-7702 委托账户。钱包会话和实物兑换仅支持 EOA。TypeScript 测试版使用 EOA 签名器。

验证配送钱包

在用户查看私有配送信息或开始兑换时发起验证。连接钱包后,用户还需签署允许访问配送数据的消息。之后提交结账时需要另签操作授权。
后续私有请求应复用该客户端。它在内存中保存限定权限的凭据,并在会话有效期内刷新。用户退出、切换钱包或网络时,调用 signOutRedemptionWallet() 并清除界面中的私有数据。

前端来源与签发方

注册完整的协议、主机和端口,不含路径或末尾斜杠。本地回环地址也要分别注册,例如 http://localhost:3311 和 http://127.0.0.1:3311 属于不同来源。 根据部署信息配置签发方。使用相对代理路径时必须显式指定;使用绝对 API URL 时,SDK 默认取其来源加上 /v2/auth/wallet。部署别名可能与规范签发方不同。不要从未经验证的签名质询中提取预期签发方。

会话有效期

签名提示过期或被取消后,钱包仍未验证。等用户再次选择验证时重试。此消息说明权限和会话期限,不授权链上交易。 直接使用 HTTP 时,可按以下顺序管理会话。
  1. 获取登录消息。提示用户签名前,先核对钱包、链、来源、签发方、受众、权限及有效期。SDK 会自动执行这些检查。
  2. 请钱包逐字节签署原始消息,再验证钱包签名,获取访问令牌和刷新令牌。
  3. 使用当前刷新令牌续签会话。用户退出登录时,撤销会话。

身份提供方

你可以使用 Privy 或其他嵌入式钱包的 EOA 签名器。其登录令牌不能用作 Renaiss 钱包访问令牌。此 API 不接受合作方的身份令牌或 JWKS 认证,请通过钱包验证获取令牌。 使用 Renaiss 登录是可选的 OIDC 账户登录方式。钱包操作无需接入它,配送仍须单独验证。