Virtual Currencies

Soft and premium currencies with auto-recharge, balance caps, and transaction history.

Define virtual currencies for your app. Currencies can be soft (earned through gameplay) or premium (purchased with real money), with optional auto-recharge for time-gated mechanics.

SDK usage

Get balances

const balances = await client.currencies.getBalances();
// Returns:
// [
//   { currency_code: "gold", name: "Gold Coins", balance: 500, is_premium: false },
//   { currency_code: "gems", name: "Gems", balance: 10, is_premium: true }
// ]

Get transactions

const { data, total } = await client.currencies.getTransactions({
  currency_code: 'gold',
  limit: 20,
});

Client API reference

Method	Path	Description
`GET`	`/client/currencies`	Get all currency balances
`GET`	`/client/currencies/transactions`	Get transaction history

MCP tools

Tool	Description
`amba_create_currency`	Create a currency (soft/premium, auto-recharge, caps)
`amba_list_currencies`	List all currencies
`amba_grant_currency`	Grant currency to a user (admin)

Example: Hearts system

Agent: "Create a hearts currency that recharges 1 heart every 30 minutes, max 5"

amba_create_currency({
  project_id: "proj_xxx",
  code: "hearts",
  name: "Hearts",
  description: "Lives for gameplay",
  is_premium: false,
  initial_balance: 5,
  max_balance: 5,
  auto_recharge_amount: 1,
  auto_recharge_interval_hours: 0.5
})

Currency options

Field	Type	Description
`code`	string	Unique code (e.g., "gold", "gems")
`name`	string	Display name
`is_premium`	boolean	Premium (real money) currency
`initial_balance`	number	Starting balance for new users (default 0)
`max_balance`	number	Balance cap (null for unlimited)
`auto_recharge_amount`	number	Amount to auto-recharge
`auto_recharge_interval_hours`	number	Hours between recharges

Database tables

Table	Purpose
`currency_definitions`	Currency definitions with type and recharge config
`user_balances`	Per-user balances by currency
`currency_transactions`	Full transaction ledger with amounts and reasons

Virtual Currencies

On this page