Submit an ask

Submit a signed listing

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/asks \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "askData": {
    "salt": "<string>",
    "deadline": "<string>",
    "usdcAmount": "<string>",
    "owner": "<string>",
    "tokenId": "9007199254740993"
  },
  "askSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    askData: {
      salt: '<string>',
      deadline: '<string>',
      usdcAmount: '<string>',
      owner: '<string>',
      tokenId: '9007199254740993'
    },
    askSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/asks', 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/asks"

payload = {
    "tokenId": "9007199254740993",
    "askData": {
        "salt": "<string>",
        "deadline": "<string>",
        "usdcAmount": "<string>",
        "owner": "<string>",
        "tokenId": "9007199254740993"
    },
    "askSignature": "<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

asks

Submit a signed listing

curl --request POST \
  --url https://dev-api.renaiss.xyz/v2/marketplace/asks \
  --header 'Content-Type: application/json' \
  --header 'x-builder-api-key: <api-key>' \
  --data '
{
  "tokenId": "9007199254740993",
  "askData": {
    "salt": "<string>",
    "deadline": "<string>",
    "usdcAmount": "<string>",
    "owner": "<string>",
    "tokenId": "9007199254740993"
  },
  "askSignature": "<string>"
}
'

const options = {
  method: 'POST',
  headers: {'x-builder-api-key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    tokenId: '9007199254740993',
    askData: {
      salt: '<string>',
      deadline: '<string>',
      usdcAmount: '<string>',
      owner: '<string>',
      tokenId: '9007199254740993'
    },
    askSignature: '<string>'
  })
};

fetch('https://dev-api.renaiss.xyz/v2/marketplace/asks', 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/asks"

payload = {
    "tokenId": "9007199254740993",
    "askData": {
        "salt": "<string>",
        "deadline": "<string>",
        "usdcAmount": "<string>",
        "owner": "<string>",
        "tokenId": "9007199254740993"
    },
    "askSignature": "<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 an ask. Send its top-level tokenId, its payload.askData as askData, and the seller’s askSignature.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_AMOUNT_NOT_POSITIVE`	`error`	`Ask amount must be greater than zero` The price is zero. Send a price above zero.
`400`	`ASK_HAS_ALREADY_EXPIRED`	`error`	`Ask has already expired` The listing expired while it was being processed. Prepare again with a later expiry and sign the new data.
`400`	`ASK_TOKEN_ID_MISMATCH`	`error`	`Signed order token ID differs from the submitted token ID` `Ask token ID does not match the collectible` Check that `tokenId` and `askData.tokenId` identify the same card. Use one prepare response for both fields.
`400`	`COLLECTIBLE_ONCHAIN_OWNER_MISMATCH`	`error`	`{onchainOwner} is the on chain owner.` The wallet does not own the collectible. Use the wallet that owns it.
`400`	`INVALID_ASK_SIGNATURE`	`error`	`Ask signature is invalid` The signature on the listing was not accepted. Prepare again and have the wallet sign the new data.
`400`	`OFFER_EXPIRY_TOO_LONG`	`error`	`Offers can expire at most 180 days from now` The listing expires too far from now. Prepare again with a shorter expiry.
`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` `ASK_ORDER_INSERT_FAILED` `ASK_ORDER_UPDATE_FAILED` `CREATE_SELL_OFFER_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 askData.tokenId. Keep it as a decimal string.

Pattern: ^\d+$

Example:

"9007199254740993"

askData

object

required

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

Show child attributes

askSignature

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