# Introduction

> What GameCoin is, how its pieces fit together, and which of the three ways to integrate it suits your game.

## What GameCoin is

GameCoin is the bank of your game. It keeps the virtual currency, the inventory and the orders of a web or mobile game, so you do not build a ledger, a payment flow or VAT handling yourself.

Every change to a balance is an immutable entry in a ledger, so balances stay exact when a request is retried, sent twice, or refunded. You sell currency packs for euros through a hosted payment page, and players spend the currency on items and on anything else your game offers. You call GameCoin from the browser, from your server, or both, and a browser can never add coins to a balance, except the free coins of a gift code that you issued.

> [!NOTE]
> The test environment is open. Payments there are **simulated**: no money moves. Real payments are not available yet.

## The model in one picture

```text
Studio ─ Game ─ Catalog                        what you sell, defined once
                ├─ Currencies   gems (paid), gold (free)
                ├─ Items        potion (consumable), fire-sword (durable)
                └─ Packs        "500 gems + 50 free" for 4.99 €

       Players ─ Wallet         one balance per currency: paid + bonus
               ├ Inventory      the items a player owns
               └ Orders         the packs a player bought, in euros
```

You describe the **catalog** once. Your **players** then fill it with balances, items and orders. Each change to a balance is written in the ledger and never altered. Read [Core concepts](/docs/concepts) for the words used everywhere, one by one.

## Three ways to integrate

| | Where your code runs | Key | Good for |
|---|---|---|---|
| **Browser only** | In the browser, with the SDK | Publishable key | A game with no server: itch.io, a game jam, a no-code engine |
| **Server and browser** | Your server holds the rules; the browser shows and spends | Secret key on the server, publishable key and a token in the browser | A game with accounts, rewards and rules to enforce |
| **Server only** | Your server calls the API; no GameCoin code in the game | Secret key | A backend that sells and credits, with its own client |

What changes between them is **who may credit**. A browser can read, spend, buy items and pay for packs, and it can never add to a balance by itself. Only your server, with the secret key, or a paid order can; the one exception is a gift code you issued, which adds free coins once per player. [Security model](/docs/concepts/security-model) explains why.

## Choose your path

| You want to… | Start here |
|---|---|
| Try everything in ten minutes | [Quickstart](/docs/quickstart) |
| Sell currency in a game with no server | [A game without a backend](/docs/guides/no-backend-game) |
| Reward players and run the rules from your server | [A game with a backend](/docs/guides/game-with-backend) |
| Sell packs for euros, and understand VAT and orders | [Selling packs](/docs/guides/selling-packs) |
| Understand balances, refunds and debts | [Wallets and ledger](/docs/concepts/wallets-and-ledger) |
| Give players a ready-made shop page | [The hosted shop](/docs/guides/hosted-shop) |
| Show that shop inside your web game | [Shop widget](/docs/sdk/widget) |
| Look up every call of the browser SDK | [Browser SDK](/docs/sdk/browser) |
| Call the API from your own language | [Server SDKs](/docs/sdk/server) and [API reference](/docs/api) |

## What you need

1. A GameCoin account, and a game in the dashboard. The dashboard is in French for now; this documentation names its labels where you need them.
2. Your keys: the **publishable key** `gc_pk_test_…` for the browser, and the **secret key** `gc_sk_test_…` for your server. Test keys are created with the game.
3. A catalog: at least one currency and one pack. [Quickstart](/docs/quickstart) lists the steps.

## How this documentation is organised

| Section | What it holds |
|---|---|
| **Getting started** | This page, the quickstart and the core concepts |
| **Concepts** | One page per subject, with the exact rules: the ledger, players, keys, idempotency, security, errors, rate limits |
| **Guides** | Complete walkthroughs you can run |
| **Browser SDK** | The reference of `gamecoin.js` and of the shop widget |
| **Server SDKs** | The SDKs for Node.js, Python, PHP, Go and C# |
| **API reference** | Every route, field and error |

## For AI assistants

Every page is also served as plain Markdown: add `.md` to its address (`https://gamecoin.apilow.com/docs/quickstart.md`). [`/llms.txt`](/llms.txt) lists the pages with a one-line description, and [`/llms-full.txt`](/llms-full.txt) holds the whole documentation in one file. The API is also described as an OpenAPI 3.1 document at [`/api/v1/openapi.json`](/api/v1/openapi.json).