Buy a card

Submit a signed purchase

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "bidData": {
    "bidder": "<string>",
    "feeBps": "<string>",
    "tokenId": "9007199254740993",
    "amount": "<string>",
    "nonce": "<string>",
    "deadline": "<string>"
  },
  "bidSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    bidData: {
      bidder: '<string>',
      feeBps: '<string>',
      tokenId: '9007199254740993',
      amount: '<string>',
      nonce: '<string>',
      deadline: '<string>'
    },
    bidSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dev-api.renaiss.xyz/v2/marketplace/buy"

payload = {
    "tokenId": "9007199254740993",
    "bidData": {
        "bidder": "<string>",
        "feeBps": "<string>",
        "tokenId": "9007199254740993",
        "amount": "<string>",
        "nonce": "<string>",
        "deadline": "<string>"
    },
    "bidSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "operation": "ask",
  "orderId": "<string>",
  "status": "ACTIVE",
  "executed": true,
  "executionTxHash": "<string>",
  "matchedOrderId": "<string>"
}

Malformed JSON in request body

{
  "error": "Required authentication credential is missing",
  "code": "API_AUTH_MISSING_CREDENTIAL"
}

{
  "error": "Invalid wallet action proof",
  "code": "API_AUTH_INVALID_ACTION"
}

{
  "error": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

Payload Too Large

{
  "error": "Authentication rate limit exceeded",
  "code": "API_AUTH_RATE_LIMITED"
}

Internal Server Error

POST

marketplace

buy

Submit a signed purchase

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/buy \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "bidData": {
    "bidder": "<string>",
    "feeBps": "<string>",
    "tokenId": "9007199254740993",
    "amount": "<string>",
    "nonce": "<string>",
    "deadline": "<string>"
  },
  "bidSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    bidData: {
      bidder: '<string>',
      feeBps: '<string>',
      tokenId: '9007199254740993',
      amount: '<string>',
      nonce: '<string>',
      deadline: '<string>'
    },
    bidSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/buy', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://dev-api.renaiss.xyz/v2/marketplace/buy"

payload = {
    "tokenId": "9007199254740993",
    "bidData": {
        "bidder": "<string>",
        "feeBps": "<string>",
        "tokenId": "9007199254740993",
        "amount": "<string>",
        "nonce": "<string>",
        "deadline": "<string>"
    },
    "bidSignature": "<string>"
}
headers = {
    "x-builder-api-key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

{
  "operation": "ask",
  "orderId": "<string>",
  "status": "ACTIVE",
  "executed": true,
  "executionTxHash": "<string>",
  "matchedOrderId": "<string>"
}

Malformed JSON in request body

{
  "error": "Required authentication credential is missing",
  "code": "API_AUTH_MISSING_CREDENTIAL"
}

{
  "error": "Invalid wallet action proof",
  "code": "API_AUTH_INVALID_ACTION"
}

{
  "error": "Collectible not found",
  "code": "COLLECTIBLE_NOT_FOUND"
}

Payload Too Large

{
  "error": "Authentication rate limit exceeded",
  "code": "API_AUTH_RATE_LIMITED"
}

Internal Server Error

Use the response from prepare a purchase. Send its top-level tokenId, its payload.bidData as bidData, and the buyer’s bidSignature.On testnet, submit the top-level tokenId shown here. Until the mainnet release, send the prepared payload.collectibleId as top-level collectibleId on mainnet. Keep the signed order data exactly as prepared.

Request

Builder key and wallet signature

Response

Error codes

Match the HTTP status and response text to a row below. For guidance on codes shared across endpoints, see Error meanings and recovery.

HTTP	Error code	Text field	Response text and recovery
`400`	`ASK_HAS_ALREADY_EXPIRED`	`error`	`Ask has already expired` The listing has expired. Read the listings again; do not retry this request.
`400`	`BID_HAS_ALREADY_EXPIRED`	`error`	`Bid has already expired` The purchase expired while it was being processed. Prepare again with a later expiry and sign the new data.
`400`	`BID_LOWER_THAN_ASK`	`error`	`Bid amount is lower than current ask price` The amount you signed is lower than the listing price. Prepare again and sign the new data.
`400`	`BID_TOKEN_ID_MISMATCH`	`error`	`Signed order token ID differs from the submitted token ID` `Bid token ID does not match the collectible` Check that `tokenId` and `bidData.tokenId` identify the same card. Use one prepare response for both fields.
`400`	`INSUFFICIENT_ALLOWANCE`	`error`	`Insufficient token allowance for Permit2` The wallet has not approved enough USDT for this purchase. Approve the amount, then send the purchase again.
`400`	`INVALID_ASK_SIGNATURE`	`error`	`Ask signature is invalid` The listing can no longer be bought. Read the listings again; do not retry this request.
`400`	`INVALID_BID_FEE_BPS`	`error`	`Invalid bid fee BPS` The fee in the signed purchase is not accepted. Prepare again and sign the new data.
`400`	`INVALID_BID_SIGNATURE`	`error`	`Bid signature is invalid` The signature on the purchase was not accepted. Prepare again and have the wallet sign the new data.
`400`	`MATCHING_ASK_NOT_FOUND`	`error`	`Listing is no longer available` The collectible has no active listing. Read the listings again; do not retry this request.
`400`	`MATCHING_ASK_PERMIT_NOT_FOUND`	`error`	`Stored ask payload is invalid` The listing cannot be bought. Read the listings again; do not retry this request.
`400`	`WRONG_REQUEST_PARAMS`	`error`	`Invalid marketplace request: tokenId: Required` `Invalid marketplace request: Expected object, received array` Send the required fields in a JSON object. Copy the top-level `tokenId` from preparation and omit `collectibleId`.
`400`	No code	`text/plain`	`Malformed JSON in request body`
`401`	`API_AUTH_INVALID_CREDENTIAL`	`error`	`Invalid authentication credential` The builder key is malformed, unknown, expired or revoked. Check the key. Do not retry with the same key.
`401`	`API_AUTH_MISSING_CREDENTIAL`	`error`	`Required authentication credential is missing` No builder key was sent. Send your builder key in the `x-builder-api-key` header.
`403`	`API_AUTH_CREDENTIAL_NOT_ALLOWED`	`error`	`Credential is not allowed by this policy` This route takes a builder key only. Remove the `Authorization` header and any other credential, then send the request again.
`403`	`API_AUTH_INVALID_ACTION`	`error`	`Invalid wallet action proof` The signature was not accepted for the wallet and the prepared data, or the deadline has passed. Prepare again and sign the new data. For a contract wallet, its `isValidSignature` must return `0x1626ba7e` for the EIP-712 digest of the prepared data.
`403`	`GACHA_V3_BUILDER_NOT_ACCEPTED_ON_PUBLIC_API`	`error`	`This builder checks out on its own surface, not on the public API` This builder key cannot be used on this API. Do not retry; contact Renaiss.
`404`	`COLLECTIBLE_NOT_FOUND`	`error`	`Collectible not found` The token id is unknown or the collectible is not available on this API. Check the token id. Do not retry with the same id.
`413`	No code	`text/plain`	`Payload Too Large`
`429`	`API_AUTH_RATE_LIMITED`	`error`	`Authentication rate limit exceeded` The builder key hit its rate limit. Wait a little, then retry at a lower rate.
`500`	`API_AUTH_ERROR`	`error`	`Internal server error` The signature could not be checked because the chain could not be read. Retry the request.
`500`	`FUNCTION_ERROR`	`error`	`Internal server error`
`500`	No code	`text/plain`	`Internal Server Error`
`500`	`COLLECTIBLE_GET_FAILED` `BID_ORDER_INSERT_FAILED` `MATCHING_ASK_PERMIT_NOT_FOUND` `BUY_NOW_FAILED` `MATCHING_ASK_SHOULD_BE_ONLY_ONE` `EXECUTE_TRADE_INTERNAL_FAILED` `OP_WALLET_NOT_AVAILABLE` `TRANSACTION_VERIFICATION_FAILED` `RPC_BLOCK_NUMBER_NOT_UPDATED` `ACTIVITY_SYNC_FAILED`	`error`	`Internal server error` Check the order and wallet activity before resubmitting.

Authorizations

x-builder-api-key

string

header

required

Your approved builder API key. Keep it on your backend. Gacha and marketplace writes also require wallet action signatures. Redeem also needs a wallet access token, a Bearer token the API issues after the wallet signs a sign-in message.

Body

application/json

tokenId

string

required

Copy the top-level tokenId from preparation. It must have the same uint256 value as bidData.tokenId. Keep it as a decimal string.

Pattern: ^\d+$

Example:

"9007199254740993"

bidData

object

required

Copy payload.bidData from the same preparation. Preserve the signed fields, including the deadline in whole Unix seconds.

Show child attributes

bidSignature

string

required

Response

Success

operation

enum<string>

required

Available options:

ask,

bid,

buy,

sell

orderId

string

required

status

enum<string>

required

Available options:

ACTIVE,

EXECUTED

executed

boolean

required

executionTxHash

string

matchedOrderId

string

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations

Request

Response

Error codes

Authorizations

Body

Response