> ## 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. # 提交买单 > 提交买家已签名的报价，发布买单。 调试面板使用测试网请求格式。当前主网字段见本页说明。 从[准备买单](https://docs.renaiss.xyz/cn/api-reference/marketplace/prepare-bid.md)的响应中取出顶层 `tokenId` 和 `payload.bidData`。分别填入 `tokenId` 和 `bidData`，再附上买家的 `bidSignature`。提交后刷新订单簿。 在测试网上，请提交此处所示的顶层 `tokenId`。主网更新前，请将准备响应的 `payload.collectibleId` 作为主网请求的顶层 `collectibleId`。签名订单数据应与准备响应保持一致。 ## 请求 需要开发者密钥和钱包签名 ## 响应 ## 错误码 在下表中查找接口返回的 HTTP 状态码和响应原文。有关各接口通用的处理建议，请参阅[错误码含义与处理方式](https://docs.renaiss.xyz/cn/api-reference/errors.md)。 | HTTP | 错误码 | 文本字段 | 响应文本与处理方式 | | :- | :- | :- | :- | | `400` | `BID_BELOW_MINIMUM` | `error` | `Bids must be at least 1 USDT` 出价低于最低金额。请提高金额并重新准备。 | | `400` | `BID_HAS_ALREADY_EXPIRED` | `error` | `Bid has already expired` 买单在处理期间过期。请延长有效期并重新准备、签名。 | | `400` | `BID_INSUFFICIENT_BALANCE` | `error` | `USDT balance is below the bid amount` 钱包的 USDT 不足，请补足余额或降低出价。 | | `400` | `BID_TOKEN_ID_MISMATCH` | `error` | `Signed order token ID differs from the submitted token ID` `Bid token ID does not match the collectible` 核对 `tokenId` 与 `bidData.tokenId` 是否指向同一张卡牌。两个字段都应取自同一次准备响应。 | | `400` | `INSUFFICIENT_ALLOWANCE` | `error` | `Insufficient token allowance for Permit2` 钱包为该买单授权的 USDT 不足。授权所需金额后重发。 | | `400` | `INVALID_BID_FEE_BPS` | `error` | `Invalid bid fee BPS` 签名买单的费率无效。请重新准备并签名。 | | `400` | `INVALID_BID_SIGNATURE` | `error` | `Bid signature is invalid` 买单签名无效。请重新准备并让钱包签署新数据。 | | `400` | `OFFER_EXPIRY_TOO_LONG` | `error` | `Offers can expire at most 180 days from now` 买单到期时间过远。请缩短有效期并重新准备。 | | `400` | `TOO_MANY_ACTIVE_BIDS` | `error` | `A wallet can hold at most 250 active bids` 钱包已达到有效买单数量上限。请先撤销一笔买单。 | | `400` | `WRONG_REQUEST_PARAMS` | `error` | `Invalid marketplace request: tokenId: Required` `Invalid marketplace request: Expected object, received array` 请用 JSON 对象传入必填字段。复制准备响应顶层的 `tokenId`，并省略 `collectibleId`。 | | `400` | 无错误码 | `text/plain` | `Malformed JSON in request body` | | `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` | `API_AUTH_INVALID_ACTION` | `error` | `Invalid wallet action proof` 钱包签名与准备数据不符或已过期。请重新准备和签名。合约钱包的 `isValidSignature` 对准备数据的 EIP-712 摘要必须返回 0x1626ba7e。 | | `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` | `COLLECTIBLE_NOT_FOUND` | `error` | `Collectible not found` 代币 ID 未知或藏品在该 API 中不可用。请核对 ID，不要用同一 ID 重试。 | | `409` | `BID_AUTHORIZATION_ALREADY_USED` | `error` | `This bid authorization was already used. Sign a new bid.` 买单已提交。先查看藏品和钱包订单，原单可能仍有效、已撤销或已成交。确需另下买单时才重新签名。 | | `413` | 无错误码 | `text/plain` | `Payload Too Large` | | `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` | 无错误码 | `text/plain` | `Internal Server Error` | | `500` | `COLLECTIBLE_GET_FAILED` `BID_ORDER_INSERT_FAILED` | `error` | `Internal server error` 重新提交前，请查询订单和钱包活动。 | ## OpenAPI ````yaml cn/api-reference/openapi.json POST /v2/marketplace/bids 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/marketplace/bids: post: tags: - Marketplace summary: 提交已签名的买单 description: 提交买家已签名的报价，发布买单。 调试面板使用测试网请求格式。当前主网字段见本页说明。 requestBody: required: true content: application/json: schema: type: object properties: tokenId: type: string pattern: ^\d+$ description: >- 复制准备响应顶层的 `tokenId`，保留十进制字符串格式。其 uint256 数值必须与 `bidData.tokenId` 相同。 example: '9007199254740993' bidData: type: object properties: bidder: type: string feeBps: type: string pattern: ^\d+$ tokenId: type: string pattern: ^\d+$ example: '9007199254740993' amount: type: string pattern: ^\d+$ nonce: type: string pattern: ^\d+$ deadline: type: string pattern: ^\d+$ required: - bidder - feeBps - tokenId - amount - nonce - deadline description: >- 从同一次准备响应复制 `payload.bidData`。请原样保留签名字段，包括以 Unix 秒数字符串表示的截止时间。 bidSignature: type: string required: - tokenId - bidData - bidSignature additionalProperties: false responses: '200': description: 成功 content: application/json: schema: type: object properties: operation: type: string enum: - ask - bid - buy - sell orderId: type: string status: type: string enum: - ACTIVE - EXECUTED executed: type: boolean executionTxHash: type: string matchedOrderId: type: string required: - operation - orderId - status - executed '400': description: |- 请求在执行前被拒绝。请求体不是合法 JSON 时返回纯文本的 HTTP 400。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#http-errors)。 content: text/plain: schema: type: string example: Malformed JSON in request body application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - WRONG_REQUEST_PARAMS - OFFER_EXPIRY_TOO_LONG - BID_HAS_ALREADY_EXPIRED - INVALID_BID_SIGNATURE - BID_BELOW_MINIMUM - BID_TOKEN_ID_MISMATCH - INVALID_BID_FEE_BPS - INSUFFICIENT_ALLOWANCE - BID_INSUFFICIENT_BALANCE - TOO_MANY_ACTIVE_BIDS required: - error - code example: error: Signed order token ID differs from the submitted token ID code: BID_TOKEN_ID_MISMATCH '401': description: |- 缺少开发者密钥或密钥未通过验证。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#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/marketplace/submit-bid#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - API_AUTH_INVALID_ACTION - API_AUTH_CREDENTIAL_NOT_ALLOWED - GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API required: - error - code example: error: Invalid wallet action proof code: API_AUTH_INVALID_ACTION '404': description: |- 未找到藏品。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - COLLECTIBLE_NOT_FOUND required: - error - code example: error: Collectible not found code: COLLECTIBLE_NOT_FOUND '409': description: |- 买单签名已使用。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#http-errors)。 content: application/json: schema: type: object properties: error: type: string description: 简短的错误说明。 code: type: string enum: - BID_AUTHORIZATION_ALREADY_USED required: - error - code example: error: This bid authorization was already used. Sign a new bid. code: BID_AUTHORIZATION_ALREADY_USED '413': description: |- 请求体超过 16 KiB。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#http-errors)。 content: text/plain: schema: type: string example: Payload Too Large '429': description: |- 该开发者密钥的请求过于频繁。 见[错误码与处理方式](/cn/api-reference/marketplace/submit-bid#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/marketplace/submit-bid#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: [] servers: - url: https://dev-api.renaiss.xyz description: BNB 测试网 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.