Marketplace integration

The Marketplace API serves a public catalog and an order book. Catalog reads accept anonymous requests. For trades, your backend supplies the builder key and the acting wallet signs the order. The paths below are relative to /v2/marketplace.

Browse and price a card

Browse the catalog without credentials. Use the tokenId of the card the user selects to get its details.
Read the order book for the current ask (the seller’s price) and funded bids (buyers’ offers). Refresh it before showing a trade for confirmation.
Use the prepared quote for the price, fee and seller proceeds. The RIX price is the card’s estimated fair market value (FMV).

Trade actions

Prepare the trade

Send the card’s tokenId as a decimal string and the acting wallet’s walletAddress. Include expiresAt in every request. Send JSON null for 30 days from preparation, or a future UTC timestamp ending in Z within 180 days.

Action	Prepare	Submit
List a card	Prepare a listing with the buyer’s fee-inclusive `totalPriceInUsdt`.	Submit the signed listing.
Make an offer	Prepare a bid with `amountInUsdt`. The minimum is 1 USDT.	Submit the signed bid.
Buy at the asking price	Prepare a purchase with the displayed `expectedTotalPriceInUsdt`.	Buy the card.
Sell to a bidder	Prepare a sale with the selected `bidOrderId`.	Accept the bid.

Use 18-decimal USDT base units for prices. For example, a listing total of 102 USDT is "102000000000000000000". Show the seller the returned quote.sellerReceivesInUsdt and quote.platformFeeInUsdt. A wallet can have up to 250 active standing bids.

Sign and submit

Before the wallet signs typedData, check the chain, contracts, card, wallet, fee, amount and expiry against the user’s selection. If the price changes, ask the user to review it again. Build the submit body from a single prepare response. After the seller signs a listing, send the following body to POST /v2/marketplace/asks.

const body = {
  tokenId: prepared.tokenId,
  askData: prepared.payload.askData,
  askSignature: signature,
};

For a bid or a purchase, use payload.bidData and bidSignature. To accept a bid, use payload.askData, askSignature and payload.bidOrderId. Copy the signed order as returned, including its deadline in whole Unix seconds. Keep tokenId as a string so large IDs retain their precision. The prepare response still includes payload.collectibleId. Copy only the fields the submit endpoint accepts. Forwarding the entire payload includes this extra field and returns HTTP 400.

Contract approvals

Buyers and bidders need enough USDT balance and allowance to Permit2. Check the token and spender against the network constants and wait for any approval transaction to confirm. The seller authorizes the transfer by signing the ask. A bidder’s balance or allowance can change before the seller accepts.

Cancel an order

Call POST /orders/cancel/prepare with the order ID and its owner’s wallet address. Have that wallet review and sign the cancellation, then call POST /orders/cancel. This removes the order from the API’s book. The underlying ask or Permit2 signature remains valid on chain. Invalidating a bid’s Permit2 nonce requires a separate wallet transaction.

Recover an uncertain trade

After a timeout, check the transaction hash if available, the on-chain owner and the refreshed order book. A submitted order can already have filled. Keep another submission disabled until you know the outcome.

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations