createRedemptionClient; private requests require your builder key and a wallet access token for that same wallet. See authentication for setup.
Vault regions and redemption batches
Renaiss stores cards in vaults across regions including Hong Kong (HK), Malaysia (MY) and the United States (US). Each redeemable card belongs to the region of its current vault. The card response exposes this as regionCountryCode, with vaultDisplayName identifying the vault.
One redemption batch can contain cards from only one vault region. A Hong Kong card and a Malaysia card cannot be redeemed in the same batch, even when both are going to the same recipient and delivery address.
Call
fetchRedemptionRegions() for the verified wallet’s current card counts by region. Use listRedeemableCards({ countryCode: 'HK' }).firstPage() to browse one region, and group selections by each card’s regionCountryCode. Keep each batch within the 50-card limit.
For each regional batch, request its own shipping quote, review its fees and complete its checkout. The API resolves the cards’ current vault locations and rejects a mixed-region selection with Choose cards from a single region. Refresh the selection if a card’s vault or eligibility has changed.
The delivery country is supplied separately as address.countryCode. The API validates the route from the vault region to that destination and returns the available courier options. Vault regions are determined by card custody; changing the delivery address does not combine cards from different regions into one batch.
From card to delivery
1
Verify the wallet
Ask the user to verify when they open shipping data. Call
connectRedemptionWallet({ origin }) with your registered frontend origin. This signs an access message, not a payment.2
Select eligible cards
Call
listRedeemableCards().firstPage() and use fetchRedemptionRegions() to show available regions. A cart may contain up to 50 cards from the same vault country/region.The API checks current on-chain ownership, vault readiness and shipping eligibility. A card displayed elsewhere in a collection is not necessarily ready to ship.3
Validate the address and quote shipping
Use
REDEMPTION_COUNTRIES for country choices and state-field requirements. Call validateRedemptionAddress({ address }), then fetchRedemptionQuote({ tokenIds, address }) for current courier options and fees.Country metadata is a form aid; it does not guarantee that a card or destination is serviceable. The API decides eligibility and prices.4
Prepare the selected courier
Call
prepareRedemption({ quoteId, courierId, recipient, insurance }). Show the selected cards, destination, recipient and total fee for review. Duties are estimates shown separately from the charged shipping checkout total.5
Sign and submit
Check the chain, wallet balance and USDT allowance to Permit2. If needed, approve the reviewed amount with your wallet library and wait for confirmation.Pass the reviewed selection to
signRedemption({ prepared, expected }), then call submitRedemption({ signed }) once. The SDK validates the contracts, token, spender, amount, address, recipient and expiry before signing.6
Track the request
Save the
preparationId before submission and the returned requestId. Use fetchRedemptionCheckout for checkout status, then the order and tracking methods below.Successful checkout starts the Redeem request. It does not mean a shipment has been created or dispatched.Keep the reviewed intent
expected must contain the card IDs, total, address and recipient the user approved. Pass money and token IDs as bigint values in SDK requests.
expected from an unexpected preparation to bypass a mismatch. Return to review if the quote, recipient or destination changes.
Expiry and recovery
Shipping quotes expire after 10 minutes. A preparation inherits its quote’s deadline, so preparing near expiry does not start a fresh 10-minute window. Use the returned expiry timestamp and keep the device clock accurate.
Checkout status is retained for 24 hours. Do not create and pay for a new checkout merely because the first response was lost or the order list has not caught up. Keep pending IDs per wallet and chain; do not persist signatures, session tokens or contact details in a recovery record.
Orders and tracking
Use
shipmentStatus, trackingNumber, trackingUrl and trackingLastSyncedAt to describe delivery. Order createdAt and updatedAt are record timestamps; neither proves dispatch or delivery.
See the API reference for address and recipient fields, courier responses and error codes. The SDK keeps its Redemption* method/type names and the API keeps its existing JSON fields; Redeem is the documentation section name.