# Gita coins

> How players earn and spend Gita coins, how your game shows the balance, gives coins safely, and treats players who haven't signed in yet.

## How Gita coins work
**Gita coin** (گیتا کوین) is the Baziness currency. Players **earn** it in your game, for example by winning matches, ranking in tournaments, opening gifts or buying packs. They **spend** it on real prizes in the [reward shop](rewards.md). The balance lives **on the platform**, not in your database:

| Action | Who | How |
| --- | --- | --- |
| **Show** the balance | your client | [`user/get-coin`](platform-api.md#step-6-read-the-balance) with the player's user token |
| **Give** coins | your server | [`client/add-coin`](platform-api.md#step-5-give-gita-coins) with the client token |
| **Spend** coins | the player | inside the reward shop page; your game does nothing |

> [!WARNING]
> Never treat a locally stored number as the balance, and never let the client add coins.

## Showing the balance
Refresh the balance:

- right after the client gets its token
- **when a Baziness page closes**, because the player may have spent coins in the reward shop
- when the game comes back to the foreground
- after your server gave coins

While the balance is unknown, or the call failed, show `…` or hide it. **Never show `0`**: the player would think their coins are gone.

## Giving coins safely
Every payout needs a **unique `transactionId` built from what the payout is**, for example `match:17` or `reward_claim:42` ([the formula](platform-api.md#step-5-give-gita-coins)). Then:

- a retry, a double tap or a repeated request can never pay twice: the platform refuses the repeat with `400`
- treat that `400` as "already paid" and finish your own bookkeeping
- record every payout in **your own ledger** too (who, how much, why), for support and reports

## Players who haven't signed in
A guest still has an anonymous Baziness user, so coins *can* be given to them. Many games still draw a line at **signed in**:

| Kind of payout | Player not signed in | Why |
| --- | --- | --- |
| **Claims**: a reward the player taps to collect (a win, a tournament prize, a gift) | refuse with a "sign in first" error; the client opens the sign-in page and retries after a successful sign-in | coins spent on real prizes should belong to a real account |
| **Payouts that must not fail**: a paid purchase that includes Gita coins | keep the coins in a **local holding balance** on your server | a paid order must never fail |
| When the player signs in | move the whole holding balance to Baziness with one `add-coin` (its own `transactionId`), then set the local balance to zero | the coins move exactly once |

When Baziness is **off**, keep Gita coin rewards in that local balance as well, so your economy stays testable without credentials.

## Showing the currency honestly
- Call it «گیتا کوین» everywhere, with its own icon.
- A build that ships **without** Baziness must not advertise Gita coin rewards.

Ready-made code: [giving coins](samples-server.md#giving-gita-coins), [showing the balance](samples-client.md#showing-the-balance).