Wallet & Economy Integration¶

This guide walks you through integrating the IntelliVerseX wallet cache, Hiro economy (donations, rewarded video), in-game store, and IAP validation into a Unity game. It complements the reference material in the Wallet module.

Overview¶

The SDK splits economy concerns into two layers that work together:

Use the wallet manager for fast UI and optimistic hints (for example enabling a button). Use Hiro for anything that must be validated on the server—store purchases, donation flows, and real-money IAP.

Prerequisites¶

Before following the steps below, ensure the following are in place:

1. Nakama — A running Nakama stack with Hiro RPCs configured for economy, store, and IAP (see Backend module and Nakama integration).
2. Hiro coordinator — IVXHiroCoordinator initialized with a valid IClient and ISession after authentication (see Hiro module).
3. IVXBootstrap — Your scene or startup flow uses the SDK bootstrap so identity, session, and backend wiring are consistent (IVXBootstrap in the _IntelliVerseXSDK package).
4. Wallet IDs on the user — Wallet identifiers are assigned when the user is created or synced (for example via create_or_sync_user on your backend). IVXWalletManager.HasWalletIds() should become true after a successful auth/sync path.

Step 1 — Access the wallet manager¶

IVXWalletManager is a public static class in the IntelliVerseX.Backend namespace. You do not obtain it through a MonoBehaviour singleton.

using IntelliVerseX.Backend;

// Correct — static API
int coins = IVXWalletManager.GetGameBalance();

// Incorrect — will not compile
// var wallet = IVXWalletManager.Instance;

Add using IntelliVerseX.Backend; wherever you read balances, subscribe to events, or call refresh helpers.

Step 2 — Check balances¶

All balance reads use the cached values stored on identity. They do not perform network I/O, so they are safe to call from UI every frame if needed (still prefer event-driven updates when possible).

int game = IVXWalletManager.GetGameBalance();
int global = IVXWalletManager.GetGlobalBalance();

if (!IVXWalletManager.HasWalletIds())
{
    // User not fully provisioned — avoid relying on balances for purchases yet
    return;
}

bool canBuyPowerUp = IVXWalletManager.CanAfford(100);
bool canBuyCosmetic = IVXWalletManager.CanAfford(50, useGlobal: true);

Step 3 — Grant currency locally (AddCoins)¶

AddCoins(int amount, string source = "unknown") increases the game wallet balance on the client and raises OnBalanceChanged.

Per the API contract in source, this is a local update; server sync is separate. Use it for:

• Offline or demo flows
• Temporary UI feedback before a server round-trip confirms the grant
• Test harnesses

// Award 25 coins locally after a client-only milestone (sync via your own RPC if needed)
IVXWalletManager.AddCoins(25, source: "level_complete_bonus");

Step 4 — Refresh from server (RefreshWalletsAsync)¶

RefreshWalletsAsync() returns Task<bool>. It is intended to refresh balances via the server (for example create_or_get_wallet for both wallets). The SDK documents this intent in IVXWalletManager.

Current behavior in the repository: if HasWalletIds() is false, it logs a warning and returns false. Otherwise it completes without a remote fetch, logs cached balances, and returns true. Wire your Nakama client to populate authoritative values and call UpdateBalances when that path is ready.

private async System.Threading.Tasks.Task SyncWalletsFromServer()
{
    bool ok = await IVXWalletManager.RefreshWalletsAsync();
    if (!ok)
    {
        // Missing wallet IDs or error — OnWalletError may have fired on exception
        return;
    }

    // After you extend RefreshWalletsAsync or use UpdateBalances from Nakama:
    UpdateHud(IVXWalletManager.GetGameBalance(), IVXWalletManager.GetGlobalBalance());
}

If another subsystem receives authoritative balances from Nakama, push them explicitly:

IVXWalletManager.UpdateBalances(gameBalance: 1200, globalBalance: 40,
    gameCurrency: "coins", globalCurrency: "gems");

Step 5 — Server-authoritative economy (IVXEconomySystem)¶

Access the economy system through the Hiro coordinator after initialization:

using IntelliVerseX.Hiro;

var economy = IVXHiroCoordinator.Instance.Economy;

Typical RPC-backed methods:

Example: rewarded video completion → apply server reward to UI and balances:

var rv = await economy.CompleteRewardedVideoAsync(gameId: null);
if (rv != null && rv.rewarded && rv.reward != null)
{
    ApplyRewardToUi(rv.reward);
    // Optionally map rv.reward.currencies into IVXWalletManager.UpdateBalances
    // once you know the mapping from Hiro currency keys to game/global wallets.
}

Step 6 — In-game store (IVXStoreSystem)¶

Access:

var store = IVXHiroCoordinator.Instance.Store;

var list = await store.ListAsync();
if (list.sections == null) { /* treat as empty */ }

foreach (var section in list.sections)
{
    foreach (var item in section.items)
    {
        if (item.disabled) continue;
        // item.cost is Dictionary<string, long> — keys are currency ids from Hiro
        ShowRow(section.sectionId, item);
    }
}

Step 7 — End-to-end purchase flow¶

Recommended pattern:

1. Optional UI hint: CanAfford against cached balance for the relevant currency key (for example "coins").
2. Server purchase: PurchaseAsync.
3. Handle result: if non-null, show reward / updated item; if null, show failure.
4. Reconcile wallet: RefreshWalletsAsync and/or UpdateBalances from server payload.

using IntelliVerseX.Backend;
using IntelliVerseX.Hiro;
using UnityEngine;

public async void BuyStoreItem(string sectionId, IntelliVerseX.Hiro.IVXStoreItem item)
{
    long coinCost = item.cost != null && item.cost.TryGetValue("coins", out var c) ? c : 0;
    if (coinCost > 0 && !IVXWalletManager.CanAfford((int)coinCost))
    {
        ShowNotEnoughCoins();
        return;
    }

    var purchased = await IVXHiroCoordinator.Instance.Store.PurchaseAsync(sectionId, item.itemId);
    if (purchased == null)
    {
        Debug.LogWarning("Store purchase failed (server rejected or RPC error).");
        ShowPurchaseFailed();
        return;
    }

    if (purchased.reward != null)
        ShowRewardPopup(purchased.reward);

    await IVXWalletManager.RefreshWalletsAsync();
}

Step 8 — IAP validation (ValidateIAPAsync, receipts)¶

Real-money purchases are not handled by IVXWalletManager. Use IVXHiroCoordinator.Instance.Base (IVXBaseSystem):

After the platform store reports a successful purchase, obtain the platform receipt string (Google Play, App Store, etc.) and validate server-side:

var baseSystem = IVXHiroCoordinator.Instance.Base;

var validation = await baseSystem.ValidateIAPAsync(
    receipt: platformReceipt,
    storeType: "googleplay",   // Must match what your Hiro server expects
    productId: sku,
    price: localizedPrice,
    currency: isoCurrencyCode,
    gameId: null);

if (validation != null && validation.valid && validation.reward != null)
{
    ApplyRewardToUi(validation.reward);
    await IVXWalletManager.RefreshWalletsAsync();
}

Events and callbacks¶

IVXWalletManager (static events)¶

Subscribe in OnEnable / unsubscribe in OnDisable on UI components:

private void OnEnable()
{
    IVXWalletManager.OnBalanceChanged += HandleBalanceChanged;
    IVXWalletManager.OnWalletError += HandleWalletError;
    RefreshLabels();
}

private void OnDisable()
{
    IVXWalletManager.OnBalanceChanged -= HandleBalanceChanged;
    IVXWalletManager.OnWalletError -= HandleWalletError;
}

private void HandleBalanceChanged(int game, int global) => SetLabels(game, global);
private void HandleWalletError(string message) => Debug.LogWarning($"Wallet: {message}");

Troubleshooting¶

See also¶

• Wallet module — Full API tables, models, and RPC reference
• Backend module — Nakama session, identity, and wallet IDs
• Hiro module — IVXHiroCoordinator, IVXHiroRpcClient, initialization
• Monetization module — Ad and IAP SDK wiring at the game layer
• Nakama integration — Backend connection patterns
• Authentication flow — Ensuring users are signed in before economy calls

Last updated to match SDK sources: IVXWalletManager, Hiro economy/store/base as documented in the Wallet module.