API Tokens

API Tokens let external systems add entries to your Loot allowlists programmatically. Run a quest on another platform, pick winners with your own bot, or sync a spreadsheet — then push the qualified wallets or accounts straight into your Loot’s allowlist.

A token acts with your creator permissions, for allowlists only. It can only touch Loots created by the account that issued it.

Get a token

1. In the app, go to Profile → API Tokens.
2. Create a token (optionally give it a name like quest-bot).
3. Copy the plaintext token — it starts with gwl_ and is shown only once. We store only a hash; if you lose it, revoke it and create a new one.

You can keep up to 20 active tokens and revoke any of them at any time. Revocation takes effect immediately.

Submit allowlist entries

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 — copy it from the Loot’s page URL: app.gatoll.io/loot/<loot-id>. The token owner must be that Loot’s creator.
• entries — up to 2,000 per request. Each entry is either an address (EVM wallet) or a userId (Gatoll user ID), never both.
• Re-submitting the same wallet or user simply updates its entry — the call is idempotent, so retries are safe.

Example with 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"}]}'

Custom pools: allocations

If the Loot is a Custom pool, every entry must carry an allocation — the exact amount (or token IDs) that recipient will receive:

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

• amount is a decimal string in the asset’s smallest unit (wei-style — "1000000000000000000" is 1.0 for an 18-decimal token).
• tokenIds is for ERC-721 pools; each token ID can be allocated to only one recipient.
• The API rejects the whole batch if the summed allocations would exceed the pool balance, so you can fix the file and resend.
• For Random and Equal pools, allocations are ignored — the contract computes shares itself.

Response

Responses use the standard envelope. Invalid rows don’t abort the batch — they come back in failed with the reason, row by row:

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

Common errors:

Status	Code	Meaning
401	UNAUTHORIZED	Missing, invalid, or revoked token
403	FORBIDDEN	The token owner is not this Loot’s creator
404	NOT_FOUND	Loot doesn’t exist
400	INVALID_ARG	Bad payload — or a Custom-pool allocation exceeds the pool balance

Keep it safe

Treat the token like a password: it can rewrite the allowlists of every Loot you create. Keep it in server-side secrets, never in client code or public repos, and revoke it immediately if it leaks. Entries added via API are labeled in the audit trail, so you can always tell which entries came from which channel.