# Economy

**URL:** https://heroiclabs.com/docs/hiro/python/economy/
**Summary:** Manage your game's virtual economy including donations, purchases, rewards, and advertisements.
**Keywords:** currency, economy, virtual economy
**Categories:** hiro, python, economy

---


# Economy

*The Economy system allows you to manage virtual currencies, donations, in-game store transactions, and advertisements.* Learn more in the [Economy concept guide](../../concepts/economy/_index.md).

## Overview

The Economy system enables your game to:

* Handle player donations and rewards.
* Manage in-game store purchases.
* Administer virtual currency and reward distributions.
* Control advertisement placements and rewards.

## Before You Start

Ensure that you have:

* Unity project configured with Hiro SDK.
* Nakama system integrated ([guide](../getting-started/_index.md)).

## Working with Donations

### Claiming Donations

Claim rewards donated by other players:

```py
request = EconomyDonationClaimRequest()
request.donation_ids = ["donation_1", "donation_2"]

donation_rewards = await hiro_client.economy_donation_claim(request)
```

### Donating to Users

Donate resources (currencies, items) to other players:

```py
request = EconomyDonationGiveRequest()
request.user_id = "user_id"
request.donation_id = "donation_1"

update_ack = await hiro_client.economy_donation_give(request)
```

### Checking Donation Progress

Check progress on donations:

```py
request = EconomyDonationGetRequest()
request.ids = ["donation_1", "donation_2"]

donations = await hiro_client.economy_donation_get(request)
```

### Requesting Donations

Request donations from players:

```py
request = EconomyDonationRequest()
request.id = "donation_1"

donation_ack = await hiro_client.economy_donation_request(request)
```

## Managing Store Transactions

### Retrieving Store Items

Fetch available items from the virtual store:

```py
request = EconomyListRequest()
request.store_type = EconomyStoreType.AppleAppstore

economy_list = await hiro_client.economy_store_get(request)
```

### Supported Store Types

Currently supported store types:

* `EconomyStoreType.AppleAppstore`
* `EconomyStoreType.GooglePlay`
* `EconomyStoreType.Fbinstant`
* `EconomyStoreType.Discord`

### Purchase Flow

#### Sending Purchase Intent

Initiate an intent to purchase:

```py
request = EconomyPurchaseIntentRequest()
request.item_id = "item_1"
request.store_type = EconomyStoreType.AppleAppstore
request.sku = "sku_1"

await hiro_client.economy_purchase_intent(request)
```

#### Completing Purchases

Finalize item purchases:

```py
request = EconomyPurchaseRequest()
request.item_id = "item_1"
request.store_type = EconomyStoreType.AppleAppstore
request.receipt = "<receipt>"

purchase_ack = await hiro_client.economy_purchase_item(request)
```

## Granting Rewards

Grant virtual currencies or rewards to players:

```py
request = EconomyGrantRequest()
request.currencies = {"coins": "100"}

update_ack = await hiro_client.economy_grant(request)
```

## Managing Advertisements

### Ad Placement Status

Retrieve status of ad placements:

```py
request = EconomyPlacementStatusRequest()
request.reward_id = "reward_1"
request.placement_id = "placement_1"
request.count = 0

placement_status = await hiro_client.economy_placement_status(request)
```

### Starting Ad Placements

Begin an ad placement:

```py
request = EconomyPlacementStartRequest()
request.placement_id = "placement_1"

placement_status = await hiro_client.economy_placement_start(request)
```

### Handling Ad Callbacks

Handle rewarded video ad callbacks:

```py
# Success Callback
await hiro_client.economy_placement_success()

# Failure Callback
await hiro_client.economy_placement_fail()
```

## Next Steps

- [Create a Collectible Cards System](../../guides/gameplay-mechanics/collectible-cards/)
- [Royal Match King's Cup using Event Leaderboards](../../guides/gameplay-mechanics/event-leaderboard/)
- [Making a Fall Guys Style In-Game Store](../../guides/gameplay-mechanics/in-game-store/)
- [Fortnite Style Solo Live Event](../../guides/gameplay-mechanics/solo-live-event/)
- [Add One Time Offers to the Store](../../guides/personalizer/one-time-store-offers/)