Creating Wallets

This guide explains how to set up currencies and configure earning rules for your wallet system.

Overview

Wallet setup involves:

Creating currency types (coins, gems, XP, etc.)
Configuring earning rules (how users earn currency)
Setting up loyalty tiers (optional progression system)

All wallet configuration is done through the Admin API.

Creating Currencies

Before users can earn or spend currency, you need to define the currency types.

Endpoint

POST /v1/tenants/wallet/currencies?tenant_id=${tenant_id}

Example: Gold Coins

{
  "id": "gold_coins",
  "name": "Gold Coins",
  "symbol": "🪙",
  "is_spendable": true,
  "decimal_places": 0
}

Response:

{
  "id": "gold_coins",
  "tenant_id": "your_tenant",
  "name": "Gold Coins",
  "symbol": "🪙",
  "is_spendable": true,
  "decimal_places": 0,
  "active": true,
  "created_at": "2026-01-28T10:00:00Z",
  "updated_at": "2026-01-28T10:00:00Z"
}

Example: Experience Points (Non-Spendable)

{
  "id": "xp",
  "name": "Experience Points",
  "symbol": "✨",
  "is_spendable": false,
  "decimal_places": 0
}

Example: Bonus Cash (With Decimals)

{
  "id": "bonus_cash",
  "name": "Bonus Cash",
  "symbol": "$",
  "is_spendable": true,
  "decimal_places": 2
}

Currency Properties

Property	Type	Description
`id`	string	Unique identifier (lowercase, underscores only)
`name`	string	Display name
`symbol`	string	Optional emoji or symbol
`is_spendable`	boolean	If false, currency only accumulates (like XP)
`decimal_places`	integer	0 for integers, 2 for cash-like values

Creating Earning Rules

Earning rules automatically grant currency when specific events occur.

Endpoint

POST /v1/tenants/wallet/earning-rules?tenant_id=${tenant_id}

Grant 10 coins when a user logs in daily.

{
  "name": "Daily Login Bonus",
  "currency_id": "gold_coins",
  "event_type": "user.login",
  "event_filter": null,
  "calculation": {
    "type": "fixed",
    "amount": 10
  },
  "max_per_event": null,
  "max_per_day": 1,
  "max_per_week": null,
  "priority": 10
}

Example: Match Completion Bonus

Grant coins based on match score.

{
  "name": "Match Completion Bonus",
  "currency_id": "gold_coins",
  "event_type": "match.completed",
  "event_filter": {
    "op": "gte",
    "field": "attrs.score",
    "value": 100
  },
  "calculation": {
    "type": "per_unit",
    "points": 1,
    "per": 10,
    "field": "attrs.score"
  },
  "max_per_event": 100,
  "max_per_day": 1000,
  "max_per_week": 5000,
  "priority": 5
}

This grants 1 coin per 10 points scored, with a maximum of 100 coins per match and 1000 coins per day.

Calculation Types

Fixed Amount:

{
  "type": "fixed",
  "amount": 10
}

Per Unit (e.g., 1 point per $10 wagered):

{
  "type": "per_unit",
  "points": 1,
  "per": 1000,
  "field": "attrs.amount"
}

Percentage (e.g., 0.1% of transaction):

{
  "type": "percentage",
  "rate": 0.001,
  "field": "attrs.amount"
}

Earning Rule Properties

Property	Type	Description
`name`	string	Display name
`currency_id`	string	Currency to grant
`event_type`	string	Event type to match
`event_filter`	object	Optional filter expression
`calculation`	object	How to calculate amount
`max_per_event`	integer	Cap per single event
`max_per_day`	integer	Daily cap per user
`max_per_week`	integer	Weekly cap per user
`priority`	integer	Higher = evaluated first

Creating Loyalty Tiers

Tiers provide progression based on lifetime earnings.

Endpoint

POST /v1/tenants/wallet/tiers?tenant_id=${tenant_id}

Example: Bronze to Platinum Tiers

{
  "tier_name": "Bronze",
  "tier_level": 1,
  "min_lifetime_points": 0,
  "currency_id": "gold_coins",
  "icon_url": "https://example.com/bronze.png",
  "badge_color": "#CD7F32",
  "benefits": {
    "earning_multiplier": 1.0,
    "daily_spin": 1
  }
}

{
  "tier_name": "Silver",
  "tier_level": 2,
  "min_lifetime_points": 1000,
  "currency_id": "gold_coins",
  "icon_url": "https://example.com/silver.png",
  "badge_color": "#C0C0C0",
  "benefits": {
    "earning_multiplier": 1.1,
    "daily_spin": 2
  }
}

{
  "tier_name": "Gold",
  "tier_level": 3,
  "min_lifetime_points": 5000,
  "currency_id": "gold_coins",
  "icon_url": "https://example.com/gold.png",
  "badge_color": "#FFD700",
  "benefits": {
    "earning_multiplier": 1.25,
    "daily_spin": 3,
    "exclusive_wheels": true
  }
}

{
  "tier_name": "Platinum",
  "tier_level": 4,
  "min_lifetime_points": 10000,
  "currency_id": "gold_coins",
  "icon_url": "https://example.com/platinum.png",
  "badge_color": "#E5E4E2",
  "benefits": {
    "earning_multiplier": 1.5,
    "daily_spin": 5,
    "exclusive_wheels": true,
    "priority_support": true
  }
}

Tier Properties

Property	Type	Description
`tier_name`	string	Display name
`tier_level`	integer	Numeric level (1, 2, 3...)
`min_lifetime_points`	integer	Points required
`currency_id`	string	Currency to track
`icon_url`	string	Badge icon URL
`badge_color`	string	Hex color code
`benefits`	object	Tier-specific benefits (custom structure)

Manual Currency Grants

You can manually grant currency to users (for promotions, adjustments, etc.).

Endpoint

POST /v1/tenants/wallet/grant?tenant_id=${tenant_id}

Example

{
  "user_id": "user_123",
  "currency_id": "gold_coins",
  "amount": 100,
  "source_type": "promotion",
  "source_ref": "promo_jan2026",
  "description": "January promotion bonus",
  "idempotency_key": "promo_jan2026_user123"
}

Response:

{
  "transaction_id": "a1b2c3d4-5678-90ab-cdef-1234567890ab",
  "balance_after": 1500
}

Manual Currency Deductions

You can manually deduct currency from users (for adjustments, refunds, etc.).

Endpoint

POST /v1/wallet/deduct?tenant_id=${tenant_id}

Example

{
  "user_id": "user_123",
  "currency_id": "gold_coins",
  "amount": 50,
  "source_type": "manual_adjustment",
  "source_ref": "ticket_12345",
  "description": "Customer support adjustment",
  "idempotency_key": "adjustment_ticket_12345"
}

Response:

{
  "transaction_id": "b2c3d4e5-6789-01ab-cdef-2345678901bc",
  "balance_after": 1450
}

Updating Currencies

To update an existing currency:

PUT /v1/wallet/currencies/{currency_id}?tenant_id=${tenant_id}

Only include fields you want to update:

{
  "name": "Updated Currency Name",
  "active": false
}

Updating Earning Rules

To update an existing earning rule:

PUT /v1/wallet/earning-rules/{rule_id}?tenant_id=${tenant_id}

{
  "max_per_day": 2000,
  "active": true
}

Best Practices

Start Simple: Begin with one or two currencies, add more as needed
Set Reasonable Caps: Use daily/weekly limits to prevent abuse
Use Idempotency Keys: Always provide unique keys for grants/deducts
Test Earning Rules: Verify rules work correctly before production
Monitor Transactions: Review transaction history regularly
Tier Progression: Make tiers achievable but meaningful

Next Steps

Querying Wallets - Learn how to check balances and transactions
Wallets Overview - Understand the wallet system

Creating Wallets

On this page