createGachaClient with your app’s EOA signer. Public browsing needs no credentials; purchases and wallet-specific history go through your builder-authorized backend. A wallet access token is not required for these gacha operations.
Browse packs
CalllistGachaMachines().firstPage() for the catalog and fetchGachaMachine({ slug }) for the selected pack and its tiers. Display the price and quantity before preparing a purchase. listGachaMachineContents provides the published contents.
The API calls a pack a machine in SDK method names. The returned id identifies the catalog record; onChainPackId is the contract’s pack ID. Preserve both when validating a purchase.
Pull a card
1
Prepare the selected pack
Call
prepareGachaPull with machineSlug, buyerWalletAddress, quantity and the reviewed per-card expectedPriceInUsdt as a bigint. Keep the pack IDs, price and quantity from the user’s selection for signing validation.Preparation checks the selected network, contracts and price before any approval. If the price changed, refresh the selection and ask the user to review it.2
Check payment and approval
Check the connected wallet and chain, USDT balance, and the token’s allowance to Permit2. If an approval is needed, use your wallet library to approve the reviewed amount and wait for its receipt. The wallet needs BNB for this on-chain transaction.
3
Sign and submit once
Call
signGachaPull({ prepared, expected }), then submitGachaPull({ pull, onEvent }). The SDK rechecks the signing context, amount and expiry before prompting.Save a pending record before submission. Save permitFundTxHash as soon as the stream emits payment_confirmed.4
Show the result
Use stream events to show payment and draw progress. A resolved draw can still be waiting for its buyback window to end before the token reaches the user’s wallet.
Recover an interrupted pull
A disconnected stream does not mean payment failed. With the funding hash, read the existing pull:listWalletPulls and buyback offers after reconciliation. If no hash was received, inspect wallet activity and the pending request before allowing another purchase. An empty history may reflect indexing delay; a new nonce can charge for another pull.
Buybacks and delivery
fetchGachaBuybackOffers returns the wallet’s current offers for your builder. Use createGachaBuyback and submitGachaBuyback to settle selected offers. A batch accepts 1–10 unique, unexpired offers from the same pack and contract. No NFT approval is required for this buyback flow.
Buyback windows vary by pack. Use the returned deadline and status rather than a fixed countdown. After the window closes, token delivery is asynchronous. An expiring offer may race with delivery; refresh offers after a failed settlement.
Two kinds of history
Use wallet history and draw status for recovery. Public history deliberately lags active pulls and is not a payment-status check.