REST API v1 · 開發者 · API 參考

銀行 API 參考

BotGG REST API v1 的所有 4 個 銀行 端點:範圍、參數、欄位、錯誤,以及可直接執行的 curl、JavaScript 與 Python 範例。

開發者文件
本頁目錄

端點

路徑皆相對於 https://console.botgg.app/api/v1。請以 Authorization: Bearer botgg_… 傳送你的 API 金鑰,ID 皆為字串。

銀行 端點
端點範圍說明
GET/guilds/{guildId}/bank/members/{userId}bank:readGet a member’s balance
GET/guilds/{guildId}/bank/members/{userId}/transactionsbank:readList a member’s transactions
POST/guilds/{guildId}/bank/members/{userId}/transactionsbank:writeAdd to or remove from a member’s balance
GET/guilds/{guildId}/bank/leaderboardbank:readTop balances

除了下方各自的錯誤外,每個端點還可能回傳這些常見錯誤:

Get a member’s balance

GET/guilds/{guildId}/bank/members/{userId}

範圍: bank:read

Members without an account yet get the server’s starting balance.

需要在伺服器上啟用此功能: 銀行

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)

回應

回應欄位 · 200
欄位類型必填說明
userIdstring是
balanceinteger是
currencyobject是
currency.namestring是
currency.pluralstring是
currency.emojistring | null是
回應 · 200
{
  "userId": "876543210987654321",
  "balance": 1350,
  "currency": {
    "name": "Example",
    "plural": "example",
    "emoji": "🪙"
  }
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

錯誤
HTTP代碼
409BANK_DISABLED
503SERVICE_UNAVAILABLE

List a member’s transactions

GET/guilds/{guildId}/bank/members/{userId}/transactions

範圍: bank:read

Newest first. Pass before=<nextCursor> for the next page.

需要在伺服器上啟用此功能: 銀行

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)
limit查詢字串integer否1–100 · 預設值 25
before查詢字串integer否至少 1

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].idinteger是
items[].typestring是
items[].amountinteger是
items[].balanceAfterinteger是
items[].reasonstring | null是
items[].counterpartyIdstring | null是
items[].createdAtstring是
nextCursorstring | null是
回應 · 200
{
  "items": [
    {
      "id": 98765,
      "type": "example",
      "amount": 100,
      "balanceAfter": 1350,
      "reason": "Tournament prize",
      "counterpartyId": "234567890123456789",
      "createdAt": "2026-10-07T12:00:00.000Z"
    }
  ],
  "nextCursor": "98700"
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions?limit=25" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions?limit=25', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "limit": 25,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

錯誤
HTTP代碼
409BANK_DISABLED
503SERVICE_UNAVAILABLE

Add to or remove from a member’s balance

POST/guilds/{guildId}/bank/members/{userId}/transactions

範圍: bank:writeIdempotency-Key

Same rules as a banker change. Logged in the Bank ledger (type api) and the Bank log channel.

需要在伺服器上啟用此功能: 銀行

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
userId路徑string是成員的 Discord 使用者 ID · Discord ID(字串)
Idempotency-Key標頭string否選填。傳送一個唯一值(UUID),重試時沿用同一個值,變更就只會發生一次。 運作方式

請求內容

請求內容
欄位類型必填說明
typestring是add = credit, remove = debit
其中之一 add, remove
amountinteger是1–1,000,000,000,000
reasonstring | null否Shown in the Bank ledger and log
最多 200 個字元

回應

回應欄位 · 201
欄位類型必填說明
transactionIdinteger是
userIdstring是
typestring是其中之一 add, remove
amountinteger是
previousBalanceinteger是
balanceinteger是
createdAtstring是
回應 · 201
{
  "transactionId": 98765,
  "userId": "876543210987654321",
  "type": "add",
  "amount": 100,
  "previousBalance": 1250,
  "balance": 1350,
  "createdAt": "2026-10-07T12:00:00.000Z"
}

範例

curl
curl -s -X POST "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions" \
  -H "Authorization: Bearer $BOTGG_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: $(uuidgen)" \
  -d '{"type":"add","amount":100,"reason":"Tournament prize"}'
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions', {
  method: 'POST',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
    'Content-Type': 'application/json',
    'Idempotency-Key': crypto.randomUUID(), // reuse it when you retry this request
  },
  body: JSON.stringify({
    type: 'add',
    amount: 100,
    reason: 'Tournament prize',
  }),
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os, uuid
import requests

res = requests.post(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/members/876543210987654321/transactions",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
        "Idempotency-Key": str(uuid.uuid4()),  # reuse it when you retry this request
    },
    json={
        "type": "add",
        "amount": 100,
        "reason": "Tournament prize",
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

Top balances

GET/guilds/{guildId}/bank/leaderboard

範圍: bank:read

需要在伺服器上啟用此功能: 銀行

參數
名稱位置類型必填說明
guildId路徑string是你的伺服器 ID · Discord ID(字串)
limit查詢字串integer否1–100 · 預設值 10

回應

回應欄位 · 200
欄位類型必填說明
itemsarray of object是
items[].rankinteger是
items[].userIdstring是
items[].balanceinteger是
currencyobject是
currency.namestring是
currency.pluralstring是
currency.emojistring | null是
回應 · 200
{
  "items": [
    {
      "rank": 1,
      "userId": "876543210987654321",
      "balance": 1350
    }
  ],
  "currency": {
    "name": "Example",
    "plural": "example",
    "emoji": "🪙"
  }
}

範例

curl
curl -s "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/leaderboard?limit=10" \
  -H "Authorization: Bearer $BOTGG_API_KEY"
JavaScript (fetch)
// Node.js 18+ (built-in fetch) — on your server, never in a browser
const res = await fetch('https://console.botgg.app/api/v1/guilds/123456789012345678/bank/leaderboard?limit=10', {
  method: 'GET',
  headers: {
    Authorization: `Bearer ${process.env.BOTGG_API_KEY}`,
  },
});
const data = await res.json();
if (!res.ok) throw new Error(`${res.status} ${data.error}: ${data.message}`);
console.log(data);
Python (requests)
import os
import requests

res = requests.get(
    "https://console.botgg.app/api/v1/guilds/123456789012345678/bank/leaderboard",
    headers={
        "Authorization": f"Bearer {os.environ['BOTGG_API_KEY']}",
    },
    params={
        "limit": 10,
    },
    timeout=10,
)
data = res.json()
if not res.ok:
    raise RuntimeError(f"{res.status_code} {data['error']}: {data['message']}")
print(data)

錯誤

錯誤
HTTP代碼
409BANK_DISABLED
503SERVICE_UNAVAILABLE

準備好讓你的伺服器升級了嗎?

免費新增 BotGG,再到網頁控制台開啟需要的功能。