# Economy

**URL:** https://heroiclabs.com/docs/hiro/concepts/economy/
**Keywords:** game economy, monetization, in-app purchases, virtual currency, in-game store, rewarded ads, player wallet, free-to-play economy, economy configuration
**Categories:** hiro, economy, concepts

---


# Economy

The Economy system provides a complete monetization and progression framework for your game. It handles virtual currencies, in-app purchases, rewarded video ads, donations, and complex reward mechanics.

## Key features

### Virtual currencies

Define multiple in-game currencies that players can earn through gameplay or purchase with real money. The system tracks player balances and handles all currency transactions atomically.

[Learn more about virtual currencies](/docs/hiro/concepts/economy/virtual-currencies/)

### Virtual store

Create stores where players can purchase items, consumables, or currency packs using soft currency (earned in-game) or hard currency (real money via App Store, Google Play, etc.). The system handles receipt validation, purchase intents, and reward grants.

[Learn more about the virtual store](/docs/hiro/concepts/economy/virtual-store/)

{{< note "important" >}}
The `allow_fake_receipts` field is deprecated. It remains in the config schema for backwards
compatibility but has no effect. Use
[`SetAllowFakeReceipts`](/docs/hiro/server-framework/economy/#setallowfakereceipts) in your server
module initialization code instead.
{{< /note >}}

### Rewarded video

Integrate rewarded video ads from ironSource or AppLovin MAX. Players watch ads in exchange for in-game rewards. Hiro handles server-side webhook verification and provides automatic fallbacks if callbacks don't arrive.

[Learn more about rewarded video](/docs/hiro/concepts/economy/rewarded-video/)

### Donations

Enable social features where players can request help and receive contributions from other players. Donors and recipients both receive configurable rewards.

[Learn more about donations](/docs/hiro/concepts/economy/donations/)

### Rewards

Configure complex reward structures with guaranteed drops, weighted random loot tables, and time-limited modifiers. Rewards can include currencies, items, energy, and more.

[Learn more about rewards](/docs/hiro/concepts/economy/rewards/)

## Economy configuration

The Economy system is configured via a JSON file. Here's an example showing the main sections:

{{< code type="server" filename="base-economy.json" hideable="false" >}}

```json
{
  "initialize_user": {
    "currencies": {
      "GalacticCredits": 100,
      "PlasmaCores": 10
    },
    "items": {
      "StarterKit": 1
    }
  },
  "store_items": {
    "PlasmaCorePack": {
      "name": "Plasma Core Pack",
      "description": "Power your gear with concentrated plasma energy.",
      "category": "powerups",
      "cost": {
        "currencies": {
          "GalacticCredits": 100
        }
      },
      "reward": {
        "guaranteed": {
          "currencies": {
            "PlasmaCores": {
              "min": 5
            }
          }
        }
      }
    },
    "CoinPack": {
      "name": "Coin Pack",
      "description": "A pack of premium currency.",
      "category": "coin packs",
      "cost": {
        "sku": "com.spacegame.coinpack"
      },
      "reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 500
            }
          }
        }
      }
    }
  },
  "placements": {
    "daily_reward_video": {
      "reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 25,
              "max": 50
            }
          }
        }
      }
    }
  },
  "donations": {
    "resource_request": {
      "name": "Resource Request",
      "description": "Request plasma cores from your allies.",
      "cost": {
        "currencies": {
          "PlasmaCores": 1
        }
      },
      "max_count": 10,
      "duration_sec": 86400,
      "user_contribution_max_count": 2,
      "recipient_reward": {
        "guaranteed": {
          "currencies": {
            "PlasmaCores": {
              "min": 1
            }
          }
        }
      },
      "contributor_reward": {
        "guaranteed": {
          "currencies": {
            "GalacticCredits": {
              "min": 10
            }
          }
        }
      }
    }
  }
}
```

{{< / code >}}

{{< table name="gdk.concepts.economy.economy-system" >}}

### Initialize user

The `initialize_user` section defines what currencies and items players start with when they first create an account.

{{< note "important" >}}
By default, `initialize_user` only applies when a player first creates an account. Players who created an account before an `initialize_user` change won't receive the new items or currencies automatically. For example, if version 1.0 of your game initializes players with 100 coins and version 2.0 increases this to 200 coins, players who signed up before version 2.0 won't receive the additional 100 coins unless you [`ReapplyInitializeUser`](#reapply-initialize-user-to-existing-players).
{{< /note >}}

{{< table name="gdk.concepts.economy.initialize-user" >}}

#### Reapply initialize user to existing players

Use `ReapplyInitializeUser` to apply the current `initialize_user` configuration to an existing account. This grants only the currencies the player has never held and the items they don't currently own, so existing progress and balances are preserved.

Hiro tracks a version hash of the `initialize_user` configuration for each player. If the configuration hasn't changed since the player was last initialized, calling `ReapplyInitializeUser` is a no-op. See the [server framework economy reference](../../server-framework/economy/#reapplyinitializeuser) for usage.

## Related resources

- [Hiro Store sample project](../../../sample-projects/unity/hiro-store)
- [Mage Mayhem sample project](../../../sample-projects/games/mage-mayhem)
- [In-app purchase validation](/docs/nakama/concepts/iap-validation/): Configure server-side receipt validation for Apple, Google, and other platforms.