Node.js SDK

npm install @apilow/gamecoin

import { GameCoin, ErrorCode, GameCoinError, ext } from "@apilow/gamecoin";

const { GameCoin, ErrorCode, GameCoinError, ext } = require("@apilow/gamecoin");

const gamecoin = new GameCoin(process.env.GAMECOIN_SECRET_KEY, { baseUrl: "https://gamecoin.apilow.com" });
console.log(gamecoin.environment); // "test" or "live", read from the key

const tuned = new GameCoin(process.env.GAMECOIN_SECRET_KEY, {
  baseUrl: "https://gamecoin.apilow.com",
  timeout: 10_000, // give up on an attempt after 10 seconds
  maxRetries: 3, // retry up to three times, four attempts in all
});
console.log(tuned.environment);

const player = ext("user-42");
console.log(player); // "ext:user-42"

const profile = await gamecoin.players.upsert(player, { displayName: "Alice", country: "BE" });
const same = await gamecoin.players.get(player);
console.log(profile.id === same.id, profile.externalId, profile.kind); // true "user-42" "external"

// A one-hour token for the browser SDK of your game client
const { token, expiresAt } = await gamecoin.players.createToken(player);
console.log(token.startsWith("gc_pt_"), expiresAt > new Date()); // true true

const cleared = await gamecoin.players.upsert(player, { displayName: null });
console.log(cleared.displayName, cleared.country); // null "BE"

const { balance } = await gamecoin.wallet.grant(player, { currency: "gems", amount: 100, reason: "welcome_gift" });
console.log(balance.total, balance.currency); // 100 "gems"

const spent = await gamecoin.wallet.spend(player, { currency: "gems", amount: 30, reason: "revive" });
console.log(spent.balance.total, spent.entry.type); // 70 "spend"

const reward = await gamecoin.wallet.grant(player, {
  currency: "gold",
  amount: 25,
  reason: "daily_reward",
  metadata: { day: "3" },
});
console.log(reward.entry.type, reward.entry.bonusDelta, reward.balance.total); // "grant" 25 25

const wallet = await gamecoin.wallet.get(player);
for (const { currency, paid, bonus, total } of wallet.balances) console.log(currency, paid, bonus, total);
// gems 0 70 70
// gold 0 25 25

const page = await gamecoin.ledger.list(player, { currency: "gems", limit: 1 });
console.log(page.entries.length, page.nextCursor !== null); // 1 true

const older = await gamecoin.ledger.list(player, { currency: "gems", limit: 1, cursor: page.nextCursor });
console.log(older.entries[0].type); // "grant"

for await (const entry of gamecoin.ledger.iterate(player, { currency: "gems", limit: 50 })) {
  console.log(entry.createdAt.toISOString(), entry.type, entry.paidDelta + entry.bonusDelta, entry.balanceAfter.total);
  if (entry.type === "grant") break; // no further page is fetched
}

const catalog = await gamecoin.catalog.get();
console.log(catalog.items.map((item) => `${item.sku} (${item.type})`)); // [ 'potion (consumable)', 'fire-sword (durable)' ]

const granted = await gamecoin.inventory.grant(player, { sku: "potion", quantity: 3 });
console.log(granted.quantity); // 3

const used = await gamecoin.inventory.consume(player, { sku: "potion" }); // quantity defaults to 1
console.log(used.quantity); // 2

const owned = await gamecoin.inventory.list(player); // owned items only (quantity above 0)
console.log(owned.map((item) => `${item.sku} x${item.quantity}`)); // [ 'potion x2' ]

const purchase = await gamecoin.purchases.create(player, { sku: "potion" });
console.log(purchase.balance.total, purchase.item.quantity, purchase.entry.ref.itemSku); // 50 3 "potion"

await gamecoin.inventory.grant(player, { sku: "fire-sword" });
try {
  await gamecoin.inventory.grant(player, { sku: "fire-sword" }); // limited to one per player
} catch (error) {
  console.log(error instanceof GameCoinError && error.code === ErrorCode.LIMIT_REACHED); // true
}

const checkout = await gamecoin.checkouts.create(player, {
  packSku: "gems-500",
  successUrl: "https://example.com/shop/thanks", // where the player goes after paying
  cancelUrl: "https://example.com/shop",
  country: "BE", // the buyer's country decides the VAT (EU countries only)
});
console.log(checkout.order.status, checkout.checkoutUrl.startsWith("http")); // "pending" true

const order = await gamecoin.orders.get(checkout.order.id);
console.log(order.status, order.amountCents, order.vatCents, order.netCents); // "pending" 499 87 412

try {
  await gamecoin.orders.refund(order.id, { reason: "player request" });
} catch (error) {
  if (error instanceof GameCoinError && error.code === ErrorCode.CONFLICT) console.log("not refundable:", error.message);
  else throw error;
}

const idempotencyKey = "quest-17:user-42";
const first = await gamecoin.wallet.grant(player, { currency: "gems", amount: 10 }, { idempotencyKey });
const again = await gamecoin.wallet.grant(player, { currency: "gems", amount: 10 }, { idempotencyKey });
console.log(first.replayed, again.replayed, first.entry.id === again.entry.id); // false true true

const controller = new AbortController();
const timer = setTimeout(() => controller.abort(), 5_000);
const latest = await gamecoin.wallet.get(player, { signal: controller.signal });
clearTimeout(timer);
console.log(latest.balances.length); // 2

try {
  await gamecoin.wallet.spend(player, { currency: "gems", amount: 1_000_000 });
} catch (error) {
  if (error instanceof GameCoinError && error.code === ErrorCode.INSUFFICIENT_FUNDS) {
    console.log(`needs ${error.details.required}, has ${error.details.available}`); // needs 1000000, has 60
  } else {
    throw error;
  }
}

try {
  await gamecoin.wallet.grant(player, { currency: "gems", amount: -5 });
} catch (error) {
  console.log(error.name, error instanceof GameCoinError); // "RangeError" false
}

const calls = [];
let attempts = 0;
const fakeFetch = async (url, init) => {
  calls.push({ method: init.method, key: init.headers["Idempotency-Key"] });
  attempts += 1;
  if (attempts < 3) return new Response("Bad gateway", { status: 502 });
  const body = { playerId: "p1", balances: [{ currency: "gems", paid: 0, bonus: 100, total: 100 }] };
  return new Response(JSON.stringify(body), { status: 200 });
};

const offline = new GameCoin(`gc_sk_test_${"x".repeat(40)}`, { fetch: fakeFetch, sleep: async () => {} });
const result = await offline.wallet.get(player);
console.log(result.balances[0].total, calls.length); // 100 3

const sent = [];
const echo = new GameCoin(`gc_sk_test_${"x".repeat(40)}`, {
  sleep: async () => {},
  fetch: async (url, init) => {
    sent.push(init.headers["Idempotency-Key"]);
    return sent.length < 3
      ? new Response("Bad gateway", { status: 502 })
      : new Response(JSON.stringify({ item: { sku: "potion", quantity: 1, updatedAt: "2026-10-05T12:00:00.000Z" } }), { status: 200 });
  },
});
const gift = await echo.inventory.grant(player, { sku: "potion" });
console.log(gift.quantity, new Set(sent).size); // 1 1

const sandbox = new GameCoin(process.env.GAMECOIN_SECRET_KEY, { baseUrl: "https://gamecoin.apilow.com" });
const fresh = ext(`test-${Date.now()}`);
const start = await sandbox.wallet.grant(fresh, { currency: "gems", amount: 100 });
console.log(start.balance.total); // 100