API Token

API Token 讓外部系統以程式化方式把名單加進你的 Loot 白名單。在別的平台辦任務、用自己的機器人選出得獎者、或維護一份試算表——然後把合格的錢包或帳號直接推進 Loot 的白名單。

Token 代表你的創作者權限，但僅限白名單操作，而且只能動用簽發帳號自己建立的 Loot。

取得 Token

在 App 進入 個人中心 → API Tokens。
建立一個 Token（可以取個名字，例如 quest-bot）。
複製明文 Token——開頭是 gwl_，只會顯示這一次。我們只儲存雜湊；弄丟了就吊銷重發一個。

最多可同時持有 20 個有效 Token，隨時可以吊銷，吊銷立即生效。

提交白名單

POST https://api.gatoll.io/api/v1/whitelist/submit
Authorization: Bearer gwl_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Content-Type: application/json

{
  "lootId": "<loot-id>",
  "entries": [
    { "address": "0x1234...abcd" },
    { "address": "0x5678...ef01" }
  ]
}

lootId — 從 Loot 頁面網址複製：app.gatoll.io/loot/<loot-id>。Token 持有者必須是該 Loot 的創作者。
entries — 單次最多 2,000 筆。每筆填 address（EVM 錢包）或 userId（Gatoll 使用者 ID）擇一，不能同時給。
重複提交同一個錢包或使用者只會更新該筆資料——呼叫是冪等的，重試安全。

curl 範例：

curl -X POST https://api.gatoll.io/api/v1/whitelist/submit \
  -H "Authorization: Bearer $GATOLL_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{"lootId":"<loot-id>","entries":[{"address":"0x1234...abcd"}]}'

自訂池：分配額度

如果 Loot 是自訂池，每筆資料都必須帶分配額度——該收件者能領到的確切金額（或 token ID）：

{
  "lootId": "<loot-id>",
  "entries": [
    { "address": "0x1234...abcd", "allocation": { "amount": "1000000000000000000" } },
    { "address": "0x5678...ef01", "allocation": { "tokenIds": [42, 43] } }
  ]
}

amount 是十進位字串，以資產的最小單位計（wei 型式——18 位小數的代幣，"1000000000000000000" 就是 1.0）。
tokenIds 用於 ERC-721 池；每個 token ID 只能分給一位收件者。
若整批額度加總超過池子餘額，API 會整批拒絕，修正檔案後重送即可。
隨機與均分池會忽略 allocation——份額由合約自行計算。

回應

回應採用標準信封格式。無效的資料列不會中斷整批——它們會逐列出現在 failed 裡並附原因：

{
  "ok": true,
  "data": {
    "ruleId": "...",
    "addedCount": 2,
    "failedCount": 1,
    "added": [{ "index": 0, "address": "0x..." }, { "index": 1, "address": "0x..." }],
    "failed": [{ "index": 2, "error": "Invalid address: 0xoops" }]
  }
}

常見錯誤：

狀態碼	代碼	意義
401	`UNAUTHORIZED`	Token 缺失、無效或已吊銷
403	`FORBIDDEN`	Token 持有者不是這個 Loot 的創作者
404	`NOT_FOUND`	Loot 不存在
400	`INVALID_ARG`	內容格式錯誤——或自訂池的分配額度超過池子餘額

安全提醒

把 Token 當密碼看待：它能改寫你建立的每一個 Loot 的白名單。請放在伺服器端的秘密設定裡，別寫進前端程式或公開儲存庫；一旦外洩立刻吊銷。透過 API 加入的名單在稽核紀錄中會標示來源管道，隨時能分辨每筆資料是從哪個管道進來的。