TypeScript SDK

The SDK provides Gacha, Marketplace and Redeem clients through @renaiss-protocol/client.

Clients

Factory	Use
`createGachaClient`	Packs, pulls, wallet pull history and buybacks
`createMarketplaceClient`	Cards, asks, bids, purchases and cancellations
`createRedemptionClient`	Shipping verification, eligibility, quotes, checkout and tracking

Client construction makes no request. A public catalog client needs only an explicit baseUrl and the matching network.

Option	Purpose
`baseUrl`	API origin or backend proxy prefix, without `/v2`
`network`	`BNB_TESTNET` or `BNB_MAINNET`; defaults to testnet
`signer`	The acting user’s EOA signer; needed for wallet actions
`builderApiKey`	Server-only credential; omit in browsers and inject it through your backend
`expectedChainId`	Optional additional chain constraint; cannot override the selected network
`walletSessionIssuer`	Redeem only: the trusted API issuer, required for relative proxies

See authentication for frontend origins and session setup.

Use an existing wallet

For viem, adapt the wallet client your app already connected:

import { BNB_TESTNET, createGachaClient } from '@renaiss-protocol/client';
import { signerFrom } from '@renaiss-protocol/client/viem';
import type { WalletClient } from 'viem';

export function createGachaForWallet(walletClient: WalletClient) {
  return createGachaClient({
    baseUrl: '/api/renaiss',
    network: BNB_TESTNET,
    signer: signerFrom(walletClient),
  });
}

Other wallet libraries can implement RenaissSigner. Embedded and external EOA wallets use the same interface; the wallet provider decides when to show a confirmation. Safe signing is not supported by these clients.

Handle results

Expected request failures are returned as Result values. Check isFailed(result) before calling getValue(result). getError(result) exposes the SDK error’s code, HTTP status and detail.

import {
  getError, getValue, isFailed, type GachaClient,
} from '@renaiss-protocol/client';

export async function loadPack(gacha: GachaClient, slug: string) {
  const result = await gacha.fetchGachaMachine({ slug });
  if (isFailed(result)) {
    const error = getError(result);
    throw new Error(`${error.code}: ${error.detail}`);
  }
  return getValue(result);
}

Handle cancellation without automatically reopening the wallet. A network failure after submission needs reconciliation, because the action may already have succeeded. Each flow guide describes its recovery path.

Pagination

List methods are lazy. Call .firstPage() for one page or use for await to iterate pages. Each page is a separate Result with items, hasMore and an optional nextCursor.

import {
  getError, getValue, isFailed, type MarketplaceClient,
} from '@renaiss-protocol/client';

export async function readCatalog(marketplace: MarketplaceClient) {
  const catalog = marketplace.listMarketplaceCards({ pageSize: 25 });
  for await (const result of catalog) {
    if (isFailed(result)) throw new Error(getError(result).detail);
    for (const card of getValue(result).items) console.log(card.tokenId);
  }
}

For a Load more button, save nextCursor and call catalog.from(nextCursor).firstPage(). Treat cursors as opaque; keep the same filters and page size while using one.

Amounts and IDs

Value	Representation
SDK monetary inputs	`bigint` in token base units
`inUsdt` amounts	18 decimals on both supported BNB networks
`inUsd` amounts	USD cents; `1000` means $10.00
HTTP token IDs and large amounts	Decimal strings; never JavaScript `number`

Use a decimal-aware utility such as viem’s parseUnits('10', 18) to create a token amount. Do not parse money with Number or assume USDT has six decimals. A missing price is not a zero price. The SDK’s TypeScript declarations contain the complete method and result types. Use the API reference for HTTP bodies, status codes and streaming events.

Getting started

Build a flow

Reference

Partner integrations

Clients

Use an existing wallet

Handle results

Amounts and IDs

​Clients

​Use an existing wallet

​Handle results

​Pagination

​Amounts and IDs

Clients

Use an existing wallet

Handle results

Pagination

Amounts and IDs