Skip to main content
Use your backend for the builder key and the buyer’s wallet for signing. You can browse public packs before connecting a wallet.

Browse packs

Omit x-builder-api-key for public packs. Include it to see packs open to your builder. The catalog omits packs you cannot access. Looking up one of those packs by slug returns HTTP 404. Requests made with a key count toward its rate limit. Keep the catalog id for purchase preparation and onChainPackId for checking the wallet signature. The pack’s activeSetExpectedValueInUsd is the average across the whole active set, in USD cents. Remaining cards can have a different average.

Pull a card

1

Prepare the purchase

Send the buyer’s wallet address, the catalog pack ID and the quantity to Prepare a pull. Check the returned wallet, chain, pack IDs, vending machine and price per card against the purchase the buyer reviewed.
2

Check the USDT allowance

Check the USDT token, Permit2 spender and required amount in approval for the selected network. If the wallet needs to approve USDT, it needs BNB for gas. Wait for that transaction to confirm.
3

Sign the prepared data

Verify the Permit2 domain, spender, amount, nonce and deadline. The witness must match the on-chain pack ID, builder code and quantity. Have the buyer sign permit2TypedData.Copy packId, numOfTokens, amountPerToken, nonce and deadline from unsignedPullPayload. Add buyerWalletAddress and permitSignature. The API derives the builder code from your key.
4

Submit once and track the result

Choose one of the two methods below. If the price or signing details change, show the revised purchase to the buyer first.

Recover an interrupted pull

If you have a requestId, check its status with the original builder key. If the connection closes before you receive the ID, or submission returns HTTP 5xx, resend the same signed pull to POST /v2/gacha/pull/request to recover the original requestId. Send one retry at a time. If you saved the funding hash, look up the draw with buyerWalletAddress and permitFundTxHash. For a FAILED pull, use the recovery step for error.code. For example, top up the wallet for INSUFFICIENT_USDT_AMOUNT or increase its Permit2 allowance for INSUFFICIENT_ALLOWANCE. Wait for confirmation, then resend the same signed pull before its deadline to restart the original request. If the signature has expired, prepare and sign a new pull.

Buybacks and delivery

After a draw resolves, Renaiss holds the card during its buyback window. The buyer can accept an available offer or keep the card for delivery to their wallet.

Buyback values and bonuses

When a card has a bonus, buybackBonus.originalBuybackBaseValueInUSD is its value before the bonus in USD cents. buybackBonus.bonusBps is the rate in basis points (2000 means 20%). Returned base values and tier amounts already include the bonus. Use them directly. You can read buybackBonus in draw status, the stream’s draws_resolved event, a resolved pull’s result, wallet activities, public pack pull history and wallet collectibles in a buyback window. The field is null when there is no bonus or the draw details are unavailable. Public pack history also returns null for this field when you omit the builder key.

Sell the card back

  1. Get the buyer’s offers. Read buybackTiers in order and show the first unexpired tier. A zero-amount tier offers no payout. If the price changes, show the new amount before asking for a signature.
  2. Have the buyer sign BuybackUserAuthorization. A batch can contain 1–10 distinct eligible settlement IDs from the same pack and contract.
  3. Settle the buyback directly or submit it for polling. For polling, save the returned requestId and check its status about once per second until COMPLETED or FAILED.
Both endpoints accept the same signed buyback body. Each submission for polling creates a new request. Use the original builder key to check its status and wait for it to finish before resubmitting. If it stays PENDING for more than ten minutes, stop polling and contact Renaiss with the original requestId. If the buyback is FAILED with OP_WALLET_BUSY, retry with the same signature after a few seconds. For other failures, refresh the offers before signing a new request.

Keep the card

The window starts when the draw resolves. Its length is the largest buybackExpiredInSeconds in the pack’s buybackConfig at the time of the draw. Later changes apply to future draws. After the window closes, Renaiss transfers the card to the buyer’s wallet. Check releaseTxHash and on-chain ownership before showing it as delivered. A card can already be visible in public history while delivery is pending.

Two kinds of history