Authentication

Your app owns account login and wallet connection. An externally owned account (EOA) can use Gacha, Marketplace and Redeem without a Renaiss login. Gacha and Marketplace also accept eligible deployed contract wallets through the HTTP API. Renaiss checks the builder’s permission and the wallet’s authority for each action.

Credentials by operation

Operation	Builder key	Wallet access token	Wallet signature
Public marketplace catalog, card details and order book	Omit	No	No
Pack catalog, contents and public pack history	Optional	No	No
Wallet collections and on-chain activities	Yes	No	No
Gacha pull preparation or request status	Yes	No	No
Wallet pull history, draw status and buyback offers	Yes	No	No
Gacha pull or buyback	Yes	No	Action signature
Marketplace prepare	Yes	No	No
Marketplace order, trade or cancellation	Yes	No	Action signature
Shipping challenge, verification, refresh or revoke	Yes	No	Message signature at verification
Redeem cards, quotes, orders and tracking	Yes	Yes	No
Redeem checkout submission	Yes	Yes	Action signature

The builder key uses x-builder-api-key. A wallet access token uses Authorization: Bearer <accessToken>. When both are required, send both headers; they serve different purposes. Wallet access tokens are issued after wallet verification. When requesting a challenge, send both redeem:read and redeem:write in scopes. The access token authorizes private Redeem operations for that wallet and builder.

Keep the builder key on your backend

For browser integrations, send SDK requests through a backend route such as /api/renaiss. The backend forwards to your assigned API and adds its builder key only to routes that accept one. Send public marketplace reads without credentials. Authenticate requests with your own user session, authorize the requested operation and apply rate limits. Allow only the required upstream routes and methods. Set the upstream key yourself rather than forwarding a client-supplied key. Forward the wallet access token when required and preserve streaming responses for gacha pulls. Do not put builder keys in NEXT_PUBLIC_* variables or return them to the browser. Exclude bearer tokens, refresh tokens, signatures and shipping details from routine application logs.

Choose the acting wallet

For Gacha and Marketplace HTTP requests, an EOA signs directly. A deployed contract account must validate the action signature through ERC-1271. Use the contract account’s address as the buyer or seller. Its signature validation must bind the account address to the signed intent. For Gacha it must also accept ERC-721 safe transfers. Check that it can receive the card before paying. The builder API excludes Renaiss-managed Safes and EIP-7702 delegated accounts from these flows. Wallet sessions and Redeem require an EOA. The published TypeScript beta uses an EOA signer.

Verify a wallet for shipping

Request verification when the user opens private shipping data or starts Redeem. Wallet connection alone does not create this session. The user signs a message allowing shipping access; checkout later requires a separate action signature.

import {
  BNB_TESTNET,
  createRedemptionClient,
  getError,
  isFailed,
  type RenaissSigner,
} from '@renaiss-protocol/client';

export async function verifyForShipping(signer: RenaissSigner) {
  const shipping = createRedemptionClient({
    baseUrl: '/api/renaiss',
    network: BNB_TESTNET,
    signer,
    walletSessionIssuer:
      'https://dev-api.renaiss.xyz/v2/auth/wallet',
  });

  const result = await shipping.signInRedemptionWallet({
    origin: window.location.origin,
  });
  if (isFailed(result)) throw new Error(getError(result).detail);
  return shipping;
}

Reuse that client for private requests. It holds the scoped credentials in memory and refreshes them within the session lifetime. On your app’s logout, wallet change or chain change, call signOutRedemptionWallet() and clear private UI state.

Frontend origin and API issuer

Setting	Example	Identifies
Registered frontend origin	`https://cards.example.com`	The page requesting the signature
`walletSessionIssuer`	`https://dev-api.renaiss.xyz/v2/auth/wallet`	The API issuing and verifying the session
SDK `baseUrl`	`/api/renaiss`	Where the browser sends requests

Register the exact frontend scheme, host and port for your builder. An origin has no path or trailing slash. Local HTTP loopback origins must be registered explicitly; http://localhost:3311 and http://127.0.0.1:3311 are separate origins. Configure the issuer from your deployment details. With a relative proxy it is required; with an absolute API URL the SDK defaults to that origin plus /v2/auth/wallet. An alias may still have a different canonical issuer. Never take the expected issuer from an unvalidated signing challenge.

Session timing

Timer	Default	When it expires
Signing challenge	5 minutes	Request a fresh challenge and signature
Wallet access token	15 minutes	SDK refreshes it within the renewable session
Renewable session	7 days	Verify the wallet again

An expired or cancelled signature prompt leaves the wallet unverified. Retry after the user’s next verification action. The signed message explains the permission and session duration; it does not authorize a transaction. For an HTTP integration, follow the session in order.

Get a sign-in message. Check the wallet, chain, origin, issuer, audience, scopes and expiry before prompting the user. The SDK performs these checks for you.
Sign the message byte for byte and verify the signature to obtain the token pair.
Refresh the session with its current refresh token. On sign-out, revoke the session.

Identity providers

You can supply an EOA signer from your own Privy or other embedded-wallet integration. Its login token is not a Renaiss wallet access token. Partner identity-token/JWKS authentication is not supported by this API; obtain a wallet access token through wallet verification. Sign in with Renaiss is optional OIDC account login. It is not required for these wallet flows and does not replace shipping verification.

Getting started

Gacha

Marketplace

Wallet collections

Redeem and shipping

Developer resources

Partner integrations