Skip to main content

Wallet

The Wallet module provides a way to check gems functionality availability, get the amount of Gems from the user's wallet, retrieve configured virtual item bundles and catalog items, and manage the user's virtual item inventory.

Setup​

To use the Wallet module, initialize the SDK and access the wallet component:

import * as ArkadiumSdk from '@arkadiuminc/sdk';

const sdk = await ArkadiumSdk.getInstance();

sdk.wallet;
info

An error will be thrown if these APIs are used in the context of a non-authenticated user. You can use the Auth module to check if the user is properly authenticated before using the Wallet APIs.

Gems​

Check if Gems is supported​

This API should be used to check if the gems functionality is supported on the Arena the game is being served. It's specially useful to decide when to show or hide gems related UI from the user, depending on the functionality availability.

const isSupported = await sdk.wallet.isGemsSupported();  
if(isSupported) {
    console.log('gems is supported')
    // Show Gems related UI here
} else {
    // Hide Gems related UI here
}

Get Gems​

This API should be used to get the amount of gems the user has in their account.

const gemsAmount = await sdk.wallet.getGems();

Virtual Items and Bundles​

info

Virtual items and bundles must be created on Arkadium side. Sync with the Arkadium representative supporting your studio before using these APIs so the required item and bundle SKUs are configured for your game.

The virtual item APIs use the following item and bundle shapes:

type Item = {
    sku: string;
    name: string;
    description: string;
    image: string;
    amount: number;
};

type Items = {
    [sku: string]: Item;
};

type Bundle = {
    sku: string;
    price: number;
    priceSku: string;
    salesPrice: number;
    salesEndDate: string;
    isSalesActive: boolean;
    contents: Item[];
    defaultPrice: BundlePrice;
    allPrices: BundlePrice[];
};

type BundlePrice = {
    amount: number;
    salesAmount: number;
    salesEndDate: string;
    item: Item;
};

type Bundles = {
    [sku: string]: Bundle;
};

type PurchaseBundleOptions = {
    amount?: number;
    priceSku?: string;
};

Pass an explicit amount: number when calling methods that accept an amount. For runtime compatibility, the current SDK implementations default omitted amount values to 1 for purchaseBundle, consumeInventoryItem, and hasInventoryItem.

isInventorySupported​

isInventorySupported(): Promise<boolean> checks whether inventory functionality is available. It returns true only when the host supports Eagle and the Wallet is initialized; it returns false if either condition is absent. This is separate from isGemsSupported(), which checks Gems availability.

const isInventorySupported = await sdk.wallet.isInventorySupported();

getBundles​

getBundles(): Promise<Bundles> returns the bundles configured for the current game, keyed by bundle SKU.

Each bundle's allPrices lists its offered prices. A price's item is the currency item, so item.sku is the SKU to use when choosing that price; it is different from the bundle's sku. When Gems are unsupported, getBundles() removes Gems-priced options. Bundles with no remaining price are omitted, while mixed-price bundles retain their non-Gems options in allPrices. The SDK selects defaultPrice by preferring its Gems currency price when available, then the first surviving price. The price and priceSku fields are derived from that selected price, as are salesPrice, salesEndDate, and isSalesActive.

When Gems are supported, a bundle with no configured prices has an empty allPrices and empty defaultPrice values; do not treat it as a purchasable price. When Gems are unsupported, a bundle with no surviving price is omitted. Backend prices may omit sale values at runtime even though the public BundlePrice type declares them as number and string.

const bundles = await sdk.wallet.getBundles();
const starterBundle = bundles['starter-bundle'];

purchaseBundle​

purchaseBundle(bundleSku: string, amountOrOptions?: number | PurchaseBundleOptions): Promise<boolean> purchases bundles for the authenticated user. Pass a number for the bundle quantity, or options with an amount and a priceSku from an offered price's item.sku. The quantity defaults to 1 when omitted, and an omitted priceSku uses the bundle's selected default price. It returns true when the purchase succeeds and false otherwise.

const purchased = await sdk.wallet.purchaseBundle('starter-bundle', 1);
if (purchased) {
    console.log('bundle purchased successfully');
}

To choose a price explicitly, use a currency item SKU from allPrices. This example selects the first offered price; your game can choose another offered entry:

const bundles = await sdk.wallet.getBundles();
const bundle = bundles['starter-bundle'];
const selectedPrice = bundle?.allPrices[0];

if (bundle && selectedPrice) {
    const purchased = await sdk.wallet.purchaseBundle(bundle.sku, {
        amount: 1,
        priceSku: selectedPrice.item.sku,
    });
}

getCatalog​

getCatalog(): Promise<Items> returns the virtual item catalog configured for the current game, keyed by item SKU.

const catalog = await sdk.wallet.getCatalog();
const booster = catalog['booster-item'];

getInventory​

getInventory(): Promise<Items> returns the authenticated user's inventory items and amounts, keyed by item SKU.

const inventory = await sdk.wallet.getInventory();
const boosterAmount = inventory['booster-item']?.amount ?? 0;

getInventoryItemAmount​

getInventoryItemAmount(sku: string): Promise<number> returns the authenticated user's inventory amount for one item SKU. It returns 0 when the item is not present.

const boosterAmount = await sdk.wallet.getInventoryItemAmount('booster-item');

consumeInventoryItem​

consumeInventoryItem(sku: string, amount: number): Promise<boolean> consumes the requested amount from the authenticated user's inventory. It returns true when the consume operation succeeds and false otherwise.

const consumed = await sdk.wallet.consumeInventoryItem('booster-item', 1);
if (consumed) {
    console.log('item consumed successfully');
}

hasInventoryItem​

hasInventoryItem(sku: string, amount: number): Promise<boolean> checks whether the authenticated user's inventory contains at least the requested amount for one item SKU.

const canUseBooster = await sdk.wallet.hasInventoryItem('booster-item', 1);