# Vybe for games: USDC shop for web games

> Add a shop to a browser game with one script. Players add balance in USDC, then spend it on items that cost a cent or less. The USDC goes straight to the developer's wallet. Vybe keeps the balance ledger. No backend needed.

Free during early access. Pricing coming soon.

## Setup

1. The developer opens Vybe > Business > Games, creates a game and copies its publishable key (vybe_pk_...).
2. Add the script and start the SDK:

```html
<script src="https://www.vybe.finance/games.js" data-key="vybe_pk_..."></script>
<script>
  Vybe.games().then(function (shop) {
    // shop.player.balance.usd, shop.game.name, shop.game.topUpAmounts
  });
</script>
```

The publishable key is safe in browser code. Lock it to your domains in the dashboard (allowed origins). An empty list allows any origin.

## SDK

All methods return promises. Amounts are in US dollars.

- Vybe.games({ key?, playerToken?, apiBase? }): starts the shop. Creates an anonymous player on first visit and remembers it in localStorage. Pass playerToken if your server issued one for a logged-in user.
- shop.balance(): { usd }.
- shop.spend(amountUsd, { item, idempotencyKey? }): charges the balance. Rejects with code "insufficient" when the player needs to top up. Reuse the idempotencyKey when retrying so a purchase is never charged twice.
- shop.topUp(amountUsd?): opens the USDC pay window. Without an amount the player picks one of the game's amounts. Call it from a click handler so the browser allows the popup. Resolves with the new balance once paid; rejects with "cancelled" or "expired".
- shop.restore(): lets a player get their balance back on a new device by email code or by signing with their wallet.
- shop.history(): recent ledger entries.
- shop.on("balance", fn): called with { usd } whenever the balance changes. Use it to update the HUD.

Errors are VybeError objects with a code. The ones to handle: insufficient (top up first), cancelled and expired (top-up window), over_max (balance would pass the game's max), game_paused, origin_not_allowed and invalid_key (setup), network.

### Example

```js
const shop = await Vybe.games();
const hud = document.querySelector("#balance");
shop.on("balance", (b) => (hud.textContent = "$" + b.usd.toFixed(2)));
hud.textContent = "$" + shop.player.balance.usd.toFixed(2);

buySword.onclick = async () => {
  try {
    await shop.spend(0.05, { item: "sword" });
    giveSword();
  } catch (e) {
    if (e.code === "insufficient") await shop.topUp();
  }
};
```

## Rules

- Top-ups: $0.10 to $100 each, paid in USDC. Players can't hold more than the game's max balance (default $50).
- Items can cost less than a cent. Balances are tracked in micro dollars.
- Grant items only after spend() resolves. Never trust the balance shown in the client for anything valuable.
- Top-ups are final once paid on-chain. Refund a player with a server grant.

## Server API (optional)

For games with their own accounts or server logic. Authenticate with the Collect secret key: Authorization: Bearer vybe_col_... Never ship it to the browser.

- POST https://www.vybe.finance/api/games/v1/server/players {gameId, externalId}: returns a player token for your user. Pass it to Vybe.games({ playerToken }).
- GET https://www.vybe.finance/api/games/v1/server/players/{playerId}?gameId=...: balance and details.
- POST https://www.vybe.finance/api/games/v1/server/grant {gameId, playerId, amountUsd, reason, idempotencyKey}: add balance (rewards, refunds).
- POST https://www.vybe.finance/api/games/v1/server/debit {gameId, playerId, amountUsd, reason, idempotencyKey}: spend from the server.

Webhook: set a Collect webhook URL in the dashboard to receive game.topup_paid with {gameId, playerId, externalId, publicId, amount, balanceUsd}.

## Browser API (what the SDK calls)

Header X-Vybe-Key: vybe_pk_..., plus Authorization: Bearer vybe_plr_... for player calls. Base https://www.vybe.finance/api/games/v1.

- POST /players, GET /me, GET /ledger
- POST /topups {amountUsd}, GET /topups/{publicId}
- POST /spend {amountUsd, itemId, idempotencyKey}; 402 with code insufficient when short
- POST /restore/email/start {email}, POST /restore/email/verify {email, code}
- POST /restore/wallet/challenge (returns a message to sign), POST /restore/wallet/verify {address, signature}

## More

- Product page: https://www.vybe.finance/games
- Other Vybe docs: https://www.vybe.finance/llms.txt