# Economy

**URL:** https://heroiclabs.com/docs/hiro/concepts/economy/
**Keywords:** economy, hiro
**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](/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](/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`](/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](/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](/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](/hiro/concepts/economy/rewards/)

## Economy configuration

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

```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
            }
          }
        }
      }
    }
  }
}
```

{{< 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" >}}
When `initialize_user` is updated, players who created an account prior to the change won't receive the new updates. For example, if version 1.0 of your game initializes players with 100 coins and in version 2.0 this amount is increased to 200 coins, then players who signed up prior to version 2 won't receive the additional 100 coins.
{{< /note >}}

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

## Related resources

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