BotGG developer API: connect your Discord server to anything

curl -s https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321 \
  -H "Authorization: Bearer $BOTGG_API_KEY"

{
  "userId": "876543210987654321",
  "balance": 1250,
  "currency": { "name": "Coin", "plural": "Coins", "emoji": "🪙" }
}

// Node.js 22+ (built-in fetch). Run it on your server — never in a browser or game client.
const API = 'https://console.botgg.app/api/v1';
const KEY = process.env.BOTGG_API_KEY; // a key with the bank:write scope, kept in a secret
const GUILD_ID = '123456789012345678';

export async function changeBalance(userId, type, amount, reason) {
  // One Idempotency-Key per logical change: every retry below reuses it, so the change happens once.
  const idempotencyKey = crypto.randomUUID();

  for (let attempt = 1; attempt <= 3; attempt++) {
    const res = await fetch(`${API}/guilds/${GUILD_ID}/bank/members/${userId}/transactions`, {
      method: 'POST',
      headers: {
        Authorization: `Bearer ${KEY}`,
        'Content-Type': 'application/json',
        'Idempotency-Key': idempotencyKey,
      },
      body: JSON.stringify({ type, amount, reason }),
    });
    const data = await res.json();

    if (res.ok) return data; // 201 — or the original response, replayed

    if (res.status === 429 || res.status === 503) {
      const seconds = Number(res.headers.get('Retry-After')) || attempt * 2;
      await new Promise((resolve) => setTimeout(resolve, seconds * 1000));
      continue;
    }
    if (data.error === 'INSUFFICIENT_FUNDS') {
      throw new Error(`Not enough balance: the member has ${data.balance}`);
    }
    throw new Error(`${res.status} ${data.error}: ${data.message}`);
  }
  throw new Error('BotGG API is busy, try again later');
}

const tx = await changeBalance('876543210987654321', 'add', 100, 'Tournament prize');
console.log(`New balance: ${tx.balance}`);

# Python 3 + requests. Run it on your server — never ship the key to clients.
import os, time, uuid
import requests

API = "https://console.botgg.app/api/v1"
KEY = os.environ["BOTGG_API_KEY"]  # a key with the bank:write scope
GUILD_ID = "123456789012345678"

def change_balance(user_id, type_, amount, reason=None):
    idempotency_key = str(uuid.uuid4())  # one per logical change, reused on every retry
    for attempt in range(1, 4):
        res = requests.post(
            f"{API}/guilds/{GUILD_ID}/bank/members/{user_id}/transactions",
            headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": idempotency_key},
            json={"type": type_, "amount": amount, "reason": reason},
            timeout=10,
        )
        data = res.json()
        if res.ok:
            return data  # 201 — or the original response, replayed
        if res.status_code in (429, 503):
            time.sleep(int(res.headers.get("Retry-After", attempt * 2)))
            continue
        raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
    raise RuntimeError("BotGG API is busy, try again later")

print(change_balance("876543210987654321", "add", 100, "Tournament prize")["balance"])