Currencies and Wallets

Currencies are the units your economy runs on — coins, gems, energy, or anything else. Each game defines its own currencies; every player has a wallet holding their balances.

Scope: currencies are defined per Game Version; each player has a wallet of balances.

Dashboard
Unity
Unreal

Three terms first:

The currency config is the one config of a Game Version that lists its currencies. Game Currencies are earned or bought inside the game, such as coins or gems. Real Currencies are money, such as USD or SAR, that an item can be priced in when a store or a web checkout sells it.
A player template describes one record Flock keeps for every player: its fields and their starting values. Saving the currency config makes a player template tagged currency for you.
A wallet is that record for one player: one balance per currency, made from the currency template.

Set them up in Flock, in this order:

In the menu at the top of the page, choose your game and the Game Version your build runs.
Open Monetization → Currencies. The page is Currency Configuration. Keep the Config Name it offers or type your own.
On the Game Currencies tab, press Add Game Currency and fill in the Currency Name (what players read, such as Gold) and the code (such as GOLD), which your game uses in its calls. Codes keep their letter case and must differ across game and real currencies.
To sell items for money, open the Real Currencies tab, press Add Real Currency, and give each an ISO 4217 code in capitals, such as USD, EUR or SAR.
Press Create Currency Config (Update Currencies once it exists). Success: the page says the currency config was created.
Open Player Management → Player Template. Success: a template tagged currency is listed, read-only: it changes only from Monetization → Currencies.
Only now register your test player. Success: Monetization → Wallets lists the player under Player Wallets, every balance at zero.

The wallet is made when the player registers, from the currency template of the Game Version the build sends. A player who registered before that template existed has no wallet, and signing in again does not make one: register a new test player. A player whose wallet was made under another Game Version keeps it: at sign-in the server moves it to the new version’s currency template, balances kept and new currencies at zero.A version deployed to Production is locked: its currencies then change only through a patch.

The Currency Configuration page with three game currencies, Gold, Crystals and Souls — Monetization → Currencies: the Game Currencies tab of a currency config.

AddGameFundsAsync credits the signed-in player’s wallet. The SDK finds the currency-tagged player template for you. After Sync Schemas (the Code Generation tab of Flock → Settings), a generated overload takes a FlockFundId and carries the template’s id, so the call skips that lookup. The examples on this tab run inside an async method.

using Flock;
using Flock.Generated.Shops;
using Flock.Models;

// Grant. Finds the "currency"-tagged template at runtime. Codes match with their letter case.
PlayerData walletRow = await FlockClient.Instance.Commands.AddGameFundsAsync("Gold", 500);

// After Sync Schemas, with a typed currency:
walletRow = await FlockClient.Instance.Commands.AddGameFundsAsync(FlockFundId.Gold, 500);

Read the balances. Player.GetWalletAsync reads the signed-in player’s wallet as a FlockWallet, with each balance under its currency code. In this example, item is a ShopItem read from its shop (see Shops and Inventory).

using System.Collections.Generic;
using Flock;
using Flock.Models;
using UnityEngine;

FlockWallet balances = await FlockClient.Instance.Player.GetWalletAsync();

long gold = balances.BalanceOf("Gold");        // 0 when the wallet has no Gold
bool hasGems = balances.Holds("Gems");         // whether the wallet has a Gems balance at all
bool canBuy = balances.CanAfford(item);        // enough of the item's currency for its price

foreach (KeyValuePair<string, long> currency in balances.GameCurrencies)
    Debug.Log($"{currency.Value} {currency.Key}");

The wallet is read through the player-data cache, which purchases and grants keep current. CanAfford is false for a real-money item, which a store or a web checkout sells. A purchase’s answer carries the wallet after it when currency moved: bought.Balances?.BalanceOf("Gold"), where Balances is null when no currency moved.The wallet is made when the player registers. The server builds each player’s wallet from the Game Version’s currency template at registration, every currency starting at zero (the player’s achievements record is made the same way, from the template tagged achievement). A player who registered while their Game Version had no currency template has no wallet, and signing in later does not make one: GetWalletAsync throws FlockValidationException, and a purchase fails with ShopWalletNotFound. Create the currency template first, then register the player under this build’s Game Version.A fresh test player. A test player you made in the Quickstart before the currency template existed has no wallet. To make a new one, call FlockClient.Instance.Authentication.Logout() once (the SDK forgets the saved sign-in, but keeps the device ID), then either delete the kept device ID, the file Flock/device_id.txt under Application.persistentDataPath (log Application.persistentDataPath to see where that is; the SDK forgets the ID it read at every Play, so the next Play makes a new one), or pass a new device ID of your own, such as Guid.NewGuid().ToString(), to the device sign-in calls. Press Play again: the next launch registers a new player, with a wallet. Its balances start at zero; give it currency to spend with AddGameFundsAsync, as above.Grants are money-safe. A grant fails rather than queueing when the server is unreachable, and is never re-sent after an ambiguous failure — a timeout may mean the credit already landed, so the SDK will not risk crediting twice. Only failures the server never processed (408/429) are retried, so wrap the call in try/catch. When no answer said whether the grant landed, the exception’s OutcomeUnknown is true: read the wallet before granting again.

using Flock;
using Flock.Exceptions;
using Flock.Models;
using UnityEngine;

try
{
    await FlockClient.Instance.Commands.AddGameFundsAsync("Gold", 500);
}
catch (FlockException e) when (e.OutcomeUnknown)
{
    FlockWallet now = await FlockClient.Instance.Player.GetWalletAsync();   // did it land?
    Debug.Log($"Gold is now {now.BalanceOf("Gold")}");
}

FlockFundId has one member per currency your shops’ items are priced in, named after the currency’s code as written: letter case is kept, any character other than a letter or digit becomes an underscore, and a code that starts with a digit gets a leading underscore (GOLD gives FlockFundId.GOLD). FlockFundId.Gold above stands for a currency whose code is Gold. Sync again after adding a currency.

AddGameFunds (the Flock Add Game Funds node) credits the signed-in player’s wallet. The SDK resolves the currency-tagged template, and a schema sync bakes its id so the call skips that lookup. The sync’s FlockCurrencyId lists the game currencies your shops price items in, the funds a grant can credit; a real-money item’s currency is never one of them (the item itself is still in FlockShopItemId).

#include "FlockSubsystem.h"
#include "Providers/FlockCommandProvider.h"
#include "Providers/FlockPlayerProvider.h"

UFlockSubsystem* Sdk = UFlockSubsystem::Get(this);   // this: any object in the game's world

// Grant. Resolves the "currency"-tagged template at runtime.
Sdk->GetCommandProvider()->AddGameFunds(TEXT("coins"), 250, [](TFlockResult<FFlockPlayerData> Credited)
{
    if (!Credited.bSuccess && Credited.Error.bOutcomeUnknown)
    {
        // No answer said whether the grant landed: read the wallet before granting again.
    }
});

// After Code Generation's sync, with a typed currency:
FFlockGenerated::AddFunds(this, EFlockCurrencyId::Gold, 100, [](TFlockResult<FFlockPlayerData> Credited) {});

Read the balances. GetWallet reads the signed-in player’s wallet by currency code.

// Item: an FFlockShopItem read from its shop.
Sdk->GetPlayerProvider()->GetWallet([Item](TFlockResult<FFlockWallet> Read)
{
    if (!Read.bSuccess)
    {
        UE_LOG(LogTemp, Warning, TEXT("%s"), *Read.Error.ToDisplayText());   // e.g. no wallet in this Game Version
        return;
    }
    const FFlockWallet& Wallet = Read.Value;

    const int64 Gold = Wallet.BalanceOf(TEXT("Gold"));   // 0 when the wallet has no Gold
    const bool bHasGems = Wallet.Holds(TEXT("Gems"));    // whether the wallet has a Gems balance at all
    const bool bCanBuy = Wallet.CanAfford(Item);         // enough of the item's currency for its price

    for (const FFlockCurrencyBalance& Currency : Wallet.GameCurrencies)
    {
        UE_LOG(LogTemp, Display, TEXT("%lld %s"), Currency.Amount, *Currency.Code);
    }
});

The wallet is read through the player-data cache, which purchases and grants keep current. A player with no wallet row in this Game Version fails (Validation). Currency codes match with their case. CanAfford is false for a real-money item, which a store sells. A purchase’s answer carries the wallet after it only when currency moved: check Bought.Value.HasWallet() first, then read FFlockWallet::From(Bought.Value.Wallet). A real-money purchase through a web checkout, and a pending one, carry no wallet: call GetWallet after them (after a paid web checkout it asks the server).In Blueprint, Flock Get Wallet (under Flock | Player) reads it; ask Wallet Balance Of, Wallet Holds and Can Afford on its Wallet, and Purchase Balances on a purchase result once Has Wallet is true for it.Grants are money-safe. A grant fails rather than queueing when the server is unreachable, and is never re-sent after an ambiguous failure — a timeout may mean the credit already landed, so the SDK will not risk crediting twice. When no answer said whether the grant landed, the error’s bOutcomeUnknown is true: read the wallet before granting again.

Shop purchases debit the relevant wallet automatically as part of the transaction — you don’t adjust balances by hand for a normal buy.

Getting Started

Concepts

Features

Reference

Currencies and Wallets