# Coin value

Every integrated game shares **one canonical coin value**, so you can price in-game
items and show real-world worth consistently. It's served from the Gamma Games
backend and can change without you shipping a new build.

## Read it

```js
const v = await gamma.getCoinValue();
// {
//   usdPerCoin: 0.01,          // 100 coins = $1.00
//   currencyCode: 'USD',
//   displayName: 'Gamma Coins',
//   symbol: 'GC',
//   iconUrl: null
// }
```

Type:

```ts
interface CoinValue {
  usdPerCoin: number;
  currencyCode: string;
  displayName: string;
  symbol: string;
  iconUrl: string | null;
}
```

The value is cached after the first read for the session.

## Helpers

```js
await gamma.coinsToUsd(100);  // 1.00  — amount × usdPerCoin
await gamma.formatCoins(50);  // "50 GC" — uses the symbol
```

## Pricing example

```js
const {usdPerCoin, symbol} = await gamma.getCoinValue();

function priceLabel(coins) {
  const usd = (coins * usdPerCoin).toFixed(2);
  return `${coins} ${symbol} (≈ $${usd})`;
}

priceLabel(250); // "250 GC (≈ $2.50)"
```

## Compatibility

`getCoinValue` requires host app **GammaSDK ≥ 1.1.0**. On older hosts the call
fails internally and the package returns the **default value**
(`usdPerCoin: 0.01`, `USD`, `Gamma Coins`, `GC`) so your UI never breaks. Outside
the app it also returns the default (it's just a display constant, not an economy
operation).