Onboarding · Dashboard Guide

Currencies

Map every currency in your game — gems, gold, energy, tickets — so the AI can measure economy health, detect inflation, and time offers to exact moments of currency stress.

What do currencies do in gamemantra?

Currencies are the foundation of the economy engine. Every earn and spend event your players fire is denominated in a currency. Without currency definitions, the platform cannot compute FSR (Flow-to-Spend Ratio), detect inflation, or calibrate offer prices.

📊

Economy health

FSR measures how fast currency flows in vs out. Genre-specific thresholds detect inflation.

🎯

Offer timing

Energy = 0 triggers lives_depleted event. The AI offers refills at maximum buy intent.

💰

Price calibration

BCU rates let the AI compare items across currencies and choose the right IAP price tier.

Currency types

Every currency belongs to one of four types. The type determines how the AI uses the currency in offer timing, economy monitoring, and inflation detection.

💎

Premium / Hard

type: "premium"

Examples: Gems, Diamonds, Gold Coins

Purchased with real money. Set is_hard=true. Its USD value is computed automatically from your store's pack prices — you don't configure it.

Monetization role

IAP purchase target. High offer CVR. Track spend carefully.

BCU rate guideline

Computed from your store packs

🪙

Soft / Earned

type: "soft"

Examples: Coins, XP, Stars, Points

Earned through gameplay. Never purchased directly. Used as a sink for engagement rewards. Set is_hard=false.

Monetization role

Used in store to drain currency. High balance = inflation risk.

BCU rate guideline

Computed (packs, dual-priced items, or live data)

⚡

Energy / Lives

type: "energy"

Examples: Energy, Hearts, Lives, Stamina

Time-gated resource. Runs out → session ends or player buys more. Maximum frustration-to-offer conversion point.

Monetization role

Depleted energy = #1 offer trigger. Use lives_depleted event.

BCU rate guideline

Computed (refill pack price, or exchange fact)

🎫

Ticket / Token

type: "ticket"

Examples: Raid Tickets, Arena Tokens, Season Keys

Event-specific access token. Earned by playing or bought directly. Ties currency to LiveOps event access.

Monetization role

Scarcity drives urgency. Offer 5 tickets when player has 0 before event ends.

BCU rate guideline

Computed (pack price or exchange fact)

✨ Currency values are computed for you

The platform automatically works out each currency's and item's USD value from your store prices — you don't configure an exchange rate. That one value is how the platform compares coins vs gems vs energy in your economy health charts, and how offer cards know that a "400 Coins" pack should say 400 coins. If your store sells 150 Coins for $0.49, one coin is worth $0.49 ÷ 150 — that's all there is to it, and it happens on save.

How it's computed (for the curious)

Every method below is the named industry-standard economy valuation — applied automatically, in priority order, using whichever data your catalogue already has:

Method	Used when	Industry standard it implements
Face rate from your store packs	The currency is sold in packs (e.g. 150 Coins for $0.49)	Store-price truth source: base-pack face value; larger packs read as "bonus %" — the universal mobile-store convention
Real-money price as value	An item is sold directly for real money	Receipt/price ground truth — the convention revenue-analytics tools use
Implied rate from dual-priced items	An item has both an in-game price and a real-money price	Implied exchange rate — the economist's purchasing-power trick applied in-game
Exchange fact	The game exchanges currencies (e.g. 1 gem → 10 coins)	One recorded fact + arithmetic — no estimation involved
Live-data refinement	A currency is only earned in-game (no packs, no dual pricing)	Revealed-preference valuation — value measured from what players actually trade

How to add currencies

Go to Settings → Economy → Currencies in the sidebar, or use the API directly.

Click "Add Currency"

A panel opens. Fill in the facts you know — the value is computed for you:

currency_id — machine-readable slug, e.g. gem, gold_coin, energy. Snake_case, no spaces.
display_name — player-visible name, e.g. "Gems", "Gold Coins".
type — premium | soft | energy | ticket.
is_hard — true only for currencies bought with real money.
Value (USD) — computed automatically. For an earned-only currency, answer the one question "How do players get this currency?" (bought / exchanged / earned) and the value follows.

You never send a rate — the platform derives it from your store packs. Example curl:

curl -s -X POST http://localhost:8005/v1/games/{GAME_ID}/currencies \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "currency_id":   "gem",
    "display_name":  "Gems",
    "type":          "premium",
    "is_hard":       true
  }'

Add your store packs — the values follow

As soon as your catalogue has a currency pack (e.g. "150 Coins for $0.49" in the Items tab), the platform derives that currency's USD value from the pack's face rate and fills in every related item's value. Nothing to calculate, nothing to type.

# The pack is the fact you know; the values are derived from it.
curl -s -X POST http://localhost:8005/v1/games/{GAME_ID}/items \
  -H "Authorization: Bearer $DASHBOARD_JWT" \
  -H "Content-Type: application/json" \
  -d '{
    "item_id":   "coins_150",
    "item_name": "150 Coins",
    "category":  "currency_pack",
    "price_usd": 0.49,
    "quantity":  150
  }'

Verify in economy dashboard

After adding currencies, the Economy page (Analytics → Economy) will show:

FSR (Flow-to-Spend Ratio) per currency, color-coded against genre thresholds
Wallet distribution histogram — see how currency wealth is spread across players
Velocity — avg transactions per active player per day
Inflation risk score (LOW / MEDIUM / HIGH)

# Verify via API
curl -s http://localhost:8000/v1/games/{GAME_ID}/economy \
  -H "Authorization: Bearer $DASHBOARD_JWT" | jq '.currencies'

⚠️ Changing a live game's currency value rescales its history

The derived value is applied automatically the first time — no action needed. But once players are earning and spending, changing it rescales how all historical economy numbers (FSR, net flow, wallet worth) read, so the dashboard asks for explicit confirmation before applying a change to a live game. Use "Recalculate values" in the catalogue to preview any change first.

How currencies flow into the offer pipeline

Earn event

currency_id=energy, delta=+30, source=gameplay

Player earns energy through gameplay. The ingest server records this.

Spend event

currency_id=energy, delta=-10, source=store

Player uses energy to play. FSR = earned / spent is updated.

Depletion signal

event_type=lives_depleted (auto-detected)

When energy hits 0, the trigger rule fires. AI checks for an active offer.

Offer selection

L1 AI → L2 platform template → L3 studio bundle → L4 store item

Pipeline finds the best energy-refill offer based on player segment + BCU pricing.

Offer shown

price in target_price_usd, items contain energy refill

Player sees a refill bundle. BCU rate converts item BCU value into IAP price.

⚡ Currencies + LiveOps

Live events drive sudden spikes in currency demand. A Raid event means players spend Raid Tickets rapidly. gamemantra detects this acceleration and tightens offer timing — showing offers earlier than normal because the urgency window is shorter.

→ Currency velocity spikes during events → higher inflation risk score
→ Ticket depletion triggers in-event offers automatically
→ Campaign themes reinforce the currency's visual identity

🧪 Currencies + Experiments

A/B experiments can test currency-denominated offers — e.g. does a 200-gem bundle convert better than a 100-gem + 500-coin bundle at the same IAP price? The ARPU comparison in the experiment uses BCU-normalised revenue so you compare apples to apples.

→ BCU rates normalise multi-currency bundles for ARPU comparison
→ Experiment variant can change both price AND currency composition
→ Mann-Whitney U ensures IAP significance even with a few very high spenders

💡 AI prompt you can use

"I have three currencies: Gems (premium, $0.99 = 100 gems), Gold Coins (earned from levels — typical player earns 200/day and spends 150), and Energy (max 50, refills 1 per 5 minutes). What BCU rates should I set for each? What FSR should I target for my casual puzzle game?"

Economy health signals to watch

Signal	Healthy	Warning	Action
FSR (Flow-to-Spend)	Genre-optimal range	FSR > 1.5 sustained	Add new sinks (upgrade costs, limited items)
Wallet concentration	Top 10% holds < 40%	Top 10% holds > 60%	Add exclusive sinks aimed at your highest spenders
Velocity	Stable week-over-week	Accelerating velocity	Increase premium item prices or add sinks
Inflation risk score	LOW (< 0.3)	HIGH (> 0.6)	Emergency sink event via LiveOps
Energy depletion rate	< 30% of sessions	> 60% of sessions	Tune energy regen speed or energy offers

API quick reference

Method	Endpoint	Purpose
GET	`/v1/games/{id}/currencies`	List all currencies for a game
POST	`/v1/games/{id}/currencies`	Add a single currency
POST	`/v1/games/{id}/currencies/bulk`	Add multiple currencies at once
PATCH	`/v1/games/{id}/currencies/{cid}`	Update BCU rate or display_name
DELETE	`/v1/games/{id}/currencies/{cid}`	Remove a currency (soft delete)
GET	`/v1/games/{id}/economy`	Economy health (FSR, velocity, inflation)
GET	`/v1/games/{id}/economy/fsr`	FSR quadrant breakdown per currency
GET	`/v1/games/{id}/economy/risk`	Inflation risk score + components