各项操作所需凭据
开发者密钥放在
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 时,可按以下顺序管理会话。
- 获取登录消息。提示用户签名前,先核对钱包、链、来源、签发方、受众、权限及有效期。SDK 会自动执行这些检查。
- 请钱包逐字节签署原始消息,再验证钱包签名,获取访问令牌和刷新令牌。
- 使用当前刷新令牌续签会话。用户退出登录时,撤销会话。