HoneyGate Docs
Pricing Add to Discord

REST API

Read your server's gates, members, leaderboard, and audit log over a simple authenticated REST API.

HoneyGate exposes a REST API so you can pull your server's data into your own apps, dashboards, or websites. Keys are read-only unless you tick a write permission (awarding or spending Coins, or renting roles). It's on every plan, Free included. This is infrastructure, not an upsell.

Authentication

Open Integrations → Public API in the admin dashboard (/admin/public-api/). The server owner, HoneyGate-assigned admins, and members with Discord’s Administrator permission can create keys, edit labels and permissions, change approved assets, and revoke keys for that server. A HoneyGate staff assignment alone does not grant API key management. The key is shown once at creation, since we only store a hash, so copy it right then.

Send it as a Bearer token:

Authorization: Bearer $HONEY_GATE_API_KEY

Keys start with hg_live_ and run about 72 characters. Each one is scoped, so you pick what it can read when you create it:

ScopeGrants
gates.readList gates and their conditions
members.readList members (with XP and join dates)
points.readRead points totals, the leaderboard, and rank
points.writeAward guild currency exactly once
points.spendSpend a member's guild currency exactly once, never below zero
points.adjustReverse a prior API award exactly once
roles.writeGive or remove only the roles you mark as rentable, with an end date (see Renting roles)
points.holdPut a member's guild currency on hold, then take it or give it back
audit.readRead audit-log entries
holdings.readRead a member's on-chain holdings (NFT counts and token balances) for your server's tracked assets
snapshots.readRead complete cached NFT holder snapshots, including wallet addresses, for collections you explicitly approve for the key
signals.writeSend login/device signals for your members to Alt Detection (see Sending login signals). Only the HoneyGate platform owner can grant this one; it is greyed out for server owners

There's also an events.read scope for the live Event Stream. That one isn't a REST endpoint on this page; see Outbound webhooks for push-style updates.

A key is tied to one server, and you can hold up to 10 active keys per server. Give a key an optional expiry if you want it to age out.

Base URL & format

Every endpoint lives under:

https://honeygate.app/api/v1/public-api/<endpoint>

Responses are JSON. Success looks like this:

{ "ok": true, "data": { ... }, "request_id": "..." }

Errors look like this:

{ "ok": false, "error": { "message": "...", "code": "..." }, "request_id": "..." }

Common status codes: 200 OK, 401 invalid or expired key, 403 missing scope, 404 unknown endpoint, 429 rate-limited.

Rate limit

120 requests per minute per key by default, and it's configurable per key. Go over and you'll get a 429. Wait, then retry.

Endpoints

GET /gates (scope: gates.read)

Lists the server's gates, each with its role, logic mode (AND/OR), and conditions.

Every condition includes both threshold fields:

Use min_amount_enforced when displaying or independently evaluating what the live gate requires.

GET /members (scope: members.read)

Lists members with discord_id, username, display name, joined_at, left_at, is_bot, and xp. Supports ?limit= (default 100, max 1000) and ?offset= for paging.

GET /member?discord_id=… (scope: members.read)

Looks up one member instead of paging through everyone. Returns their username, display name, avatar, joined_at, xp, and:

Use staff to decide whether to let somebody into your own admin screens.

It answers about your server only. A HoneyGate platform administrator is not reported as staff of your server, and neither is anyone holding an older platform-wide grant. The question this answers is "does this person run things here", which is the one worth acting on.

GET /leaderboard (scope: points.read)

Top members by XP. Supports ?limit= (default 25, max 500).

GET /audit (scope: audit.read)

Audit-log entries: role grants and revokes, gate passes, config changes. Supports ?limit= (default 100, max 500) and ?since=<ISO datetime> (defaults to the last 7 days).

GET /holdings?discord_id=… (scope: holdings.read)

How much of your server's tracked assets a member holds on-chain. It reads the same warm balance/NFT cache HoneyGate uses for its own gate checks, aggregated across every wallet that member has verified.

It answers only about the assets your server tracks (the ones you add under web3 asset tracking). A wallet holding some other token you don't track is never reported.

Numbers are exact and integer-based, on purpose:

Each asset, and the response overall, carries freshness evidence:

It fails closed, never to a false zero. If an asset's on-chain data can't be read right now (for example the server's Solana provider is briefly unreachable), that asset comes back "available": false with a reason and no amount — never 0. A 0 here always means "we checked and they hold none"; it never means "we couldn't find out." Treat complete: false as "ask again shortly," not as "they hold less."

It returns a wallet_count so you know how many verified wallets fed the answer. It does not return the wallet addresses themselves — a holdings total doesn't require handing out someone's wallets.

{
  "ok": true,
  "data": {
    "guild_id": "123456789012345678",
    "discord_id": "DISCORD_ID",
    "wallet_count": 2,
    "checked_at": "2026-08-13 12:00:00",
    "data_as_of": "2026-08-13 11:42:00",
    "complete": true,
    "assets": [
      {
        "asset_id": "fook",
        "label": "$FOOK",
        "type": "token",
        "mint": "Foo...mint",
        "units": "$FOOK",
        "available": true,
        "amount_raw": "1500000000",
        "decimals": 6,
        "checked_at": "2026-08-13 11:42:00",
        "from_cache": true
      },
      {
        "asset_id": "zombabiez",
        "label": "Animated ZomBabieZ",
        "type": "nft_collection",
        "mint": "Col...addr",
        "available": true,
        "count": 3,
        "checked_at": "2026-08-13 11:50:00"
      }
    ]
  }
}
curl "https://honeygate.app/api/v1/public-api/holdings?discord_id=DISCORD_ID" \
  -H "Authorization: Bearer $HONEY_GATE_API_KEY"

GET /holder-snapshot?asset_id=…&min_count=… (scope: snapshots.read)

Returns the wallet address and whole NFT count for every holder meeting min_count in one of your server's tracked NFT collections. asset_id is the tracked asset's short ID. min_count defaults to 1 and can be changed on every request, so an outside app can build different claim rounds without changing HoneyGate.

This endpoint exposes wallet addresses, so it has stricter access than /holdings: the API key must have snapshots.read, and you must explicitly save the collection as an approved asset on that key. Older keys with no asset restriction are refused.

The response includes snapshot_at, snapshot_age_seconds, total_holder_count, eligible_count, and complete: true. A capped background job runs every 10 minutes for assets explicitly approved on active keys. It reuses recent collection snapshots belonging to the API key's server and re-scans approved collections about once an hour and checks approved tokens for current verified members roughly every four hours. Large backlogs and provider outages can delay those checks. Another server's check cannot supply or overwrite your collection snapshot, even for the same collection. A newly isolated cache stays unavailable until your server's own check succeeds. The public request itself reads the existing cache only; it does not make an on-chain request while answering. If the cache is stale, missing, malformed, or incomplete, the snapshot request fails with 503 instead of returning a partial allowlist.

The background job continues through all approved assets over successive runs, resuming after the last attempted asset when its request allowance is used. It returns to the beginning after reaching the end; a large list is not limited permanently to its first page.

For /holdings, inspect each asset's available field and the response's complete field. Tokens can use a bounded last-known balance, with its original check time: seven hours by default, never more than the configured limit. Retaining an old balance does not make it newly checked. An unavailable amount is unknown, not zero. Rate-limited checks pause and retry automatically to protect the server's Helius allowance.

Routine refresh-budget pauses are recorded without repeated operator warnings. HoneyGate names the affected server and asset when NFT evidence stays stale or incomplete for two hours, or token evidence for twelve hours. It sends one warning for that incident and a recovery when complete evidence is again within that warning threshold. Provider rejections have a separate named warning. Provider recovery requires completed holdings refreshes at least fifteen minutes apart without another recorded rejection; individual successful pages cannot trigger it. Other stale assets keep their own warnings, and recovery does not confirm the provider's remaining credit allowance. These notification thresholds do not extend the API freshness limits above.

{
  "ok": true,
  "data": {
    "asset": { "asset_id": "pixel-zombabiez", "type": "nft_collection" },
    "min_count": 41,
    "snapshot_at": "2026-08-18 12:00:00",
    "eligible_count": 27,
    "complete": true,
    "holders": [{ "wallet": "...", "count": 54 }]
  }
}

POST /points-award (scope: points.write) — writes

Awards Coins to a member. This is the only endpoint that changes anything, so it has its own scope: a key that reads your leaderboard cannot also create currency. Grant points.write only to an app you trust.

Send JSON:

FieldRequiredNotes
discord_idyesThe member's Discord ID. They must be in your server.
amountyesA whole number above zero, up to 1,000,000 per call.
idempotency_keyyesAny string unique to this award — your own play or transaction id works well.
sourcenoA short label that shows in the ledger, e.g. arcade_win. Defaults to external_api.
notenoA human-readable note, up to 500 characters.
kindnoreward (the default: new Coins) or pot_out (paying out of a prize pot you collected with pot_in). Lets your reports tell new Coins apart from pot payouts.

The idempotency_key is the important one. If a request times out you have no way of knowing whether it arrived, so you have to retry — and a retry must not pay someone twice. Send the same key again and nothing is credited the second time:

{ "ok": true, "data": { "applied": false, "balance": 1250, "amount": 250, ... } }

applied: false means "this one was already counted." That is a success, not an error — the player has their Coins. Retrying a timed-out request with the exact same key is always safe, and is what you should do.

GET /points-balance?discord_id=… (scope: points.read)

Returns one member's authoritative spendable balance for the API key's server, plus that server's configured currency name and abbreviation. The server is taken only from the API key; callers cannot select another server in the request.

GET /points-history?discord_id=… (scope: points.read)

Returns up to 100 of one member's newest ledger entries for the API key's server. Use limit and the optional before_id cursor to page backward. Entries contain the signed amount, source, note, idempotency evidence, any reversal link, and kind: reward, pot_out, burn, pot_in, hold (on hold, or a hold that was given back), hold_return (Coins a hold gave back), or null for entries made by the Discord bot or before kinds existed. Another server's member history is never returned.

POST /points-spend (scope: points.spend) — writes

Deducts a positive whole-number amount from one member. Send discord_id, amount, a required idempotency_key, and optional source, note and kind: burn (the default: the Coins are destroyed) or pot_in (they move into a prize pot you will pay out later with a pot_out award). HoneyGate locks the member's balance, refuses overdrafts, makes retries exactly-once, and rejects reuse of a key with different data. This only reduces the internal ledger; it does not sign or send an on-chain transaction.

POST /points-reverse (scope: points.adjust) — writes

Creates one exact compensating entry for a prior /points-award. Send the original award's idempotency_key, a new idempotency key for the reversal, and a required human reason. HoneyGate refuses unknown awards, awards belonging to another server, reused keys with different data, a second reversal of the same award, or a reversal that would make the member's balance negative. This is intentionally not a general debit endpoint.

GET /points-stats?period=… (scope: points.stats)

The big picture of your server's Coins economy, meant for your own admin tools. It has its own scope so a key that shows one player's balance cannot also read the whole server's economy.

period is day (last 24 hours), week (last 7 days, the default) or month (last 30 days). Periods are rolling, counted back from the moment you ask, and the response gives the exact start and end in UTC.

FieldMeaning
cash_heldCoins in members' pockets (positive balances only).
bank_heldCoins in members' banks, or null if your server has no bank.
total_heldcash_held + bank_held.
holdersHow many members hold more than 0 (cash and bank together). cash_holders counts cash only.
median_balanceThe middle balance among holders (cash and bank together), rounded down.
topThe 20 richest members: rank, discord_id, display_name, username, in_server, cash, bank, total. Ranked the same way as /richest in Discord. Names are null for someone HoneyGate has no member record for.
period.earned_total / period.spent_totalCoins earned (credits) and spent (debits) in the period, as positive numbers.
period.earned_by_source / period.spent_by_sourceThe same, per ledger source (for example daily, work, shop_buy), largest first, with an entries count.
currencyYour server's currency name and abbreviation.

Moving Coins between cash and bank (bank_deposit, bank_withdraw) is not earning or spending, so it is left out of the two totals. It still appears in the per-source lists with counted_in_total: false. A tip between members shows on both sides: the sender's debit under spent, the receiver's credit under earned.

{
  "ok": true,
  "data": {
    "guild_id": "123456789012345678",
    "cash_held": 750, "bank_held": 90, "total_held": 840, "bank_available": true,
    "holders": 4, "cash_holders": 3, "median_balance": 200,
    "top": [{ "rank": 1, "discord_id": "111", "display_name": "Alice", "username": "alice", "in_server": true, "cash": 400, "bank": 0, "total": 400 }],
    "period": {
      "name": "week", "start": "2026-11-08 12:00:00", "end": "2026-11-15 12:00:00",
      "earned_total": 420, "spent_total": 120,
      "earned_by_source": [{ "source": "work", "amount": 320, "entries": 2, "counted_in_total": true }],
      "spent_by_source": [{ "source": "bank_deposit", "amount": 50, "entries": 1, "counted_in_total": false }]
    },
    "currency": { "name": "Coins", "short": "CN", "decimals": 0 },
    "generated_at": "2026-11-15 12:00:00"
  }
}

GET /linked-accounts?discord_id=… (scope: alts.read)

The other accounts Alt Detection thinks belong to the same person as this member, in your server only. Each link has:

FieldMeaning
other_discord_idThe other account. other_display_name, other_username and other_in_server are filled in when HoneyGate knows that account in your server, otherwise null.
directionalt_of: this member is the newer account and looks like an alt of the other one. has_alt: this member is the older (main) account and the other one looks like their alt.
statuspending (flagged, not reviewed yet) or confirmed (staff agreed).
confidenceHow strongly the signals matched, 0 to 100.
created_at / reviewed_atWhen it was flagged, and when staff reviewed it (null if not yet).

Links your staff dismissed as wrong are left out. Add include_dismissed=1 to include them (their status is dismissed). Newest links come first, up to 200.

The response also has alt_detection_enabled. It is true only when Alt Detection is installed, included in your plan, and switched on for your server. If it is false, an empty links list means "not looking", not "no alts". Links found while it was on are still returned after you switch it off. If Alt Detection was never installed you get alt_detection_enabled: false and an empty list, not an error.

{
  "ok": true,
  "data": {
    "guild_id": "123456789012345678",
    "discord_id": "100",
    "alt_detection_enabled": true,
    "count": 1,
    "links": [{ "other_discord_id": "200", "direction": "alt_of", "status": "confirmed", "confidence": 85,
                "created_at": "2026-11-01 10:00:00", "reviewed_at": "2026-11-02 09:00:00",
                "other_display_name": "Main Account", "other_username": "mainacct", "other_in_server": true }]
  }
}

GET /invites?discord_id=… (scope: invites.read)

What Invite Tracking recorded for one member in your server.

invited_by is how this member got in, or null if nothing was recorded:

FieldMeaning
inviter_discord_idWhose invite link they used. null when no person's link was used (for example your vanity URL); source says which (invite, vanity, widget or unknown).
inviter_display_name / inviter_usernameThe inviter's name in your server, when known.
invite_codeThe invite code used, when known.
first_joined_at / last_joined_at / join_countTheir first join, their most recent join, and how many times they have joined.
is_faketrue if the join was flagged (the account was very new).

invited is a page of the people this member invited, newest first. Each has discord_id, display_name, username, first_joined_at, last_joined_at, join_count, in_server (still in your server right now), left_at (when they left, if they did) and is_fake. Use page (default 1) and limit (default 25, max 100); pagination gives total and has_more.

summary gives the same invite numbers the Invite Tracking page shows for this member: total, still_in_server, left, fake, bonus, and real (people still here and not fake, plus any bonus you granted), the score reward roles use.

If Invite Tracking was never installed you get invite_tracking_available: false with nothing recorded, not an error.

{
  "ok": true,
  "data": {
    "guild_id": "123456789012345678",
    "discord_id": "100",
    "invite_tracking_available": true,
    "invited_by": { "inviter_discord_id": "900", "inviter_display_name": "The Founder", "inviter_username": "founder",
                    "invite_code": "top", "source": "invite", "first_joined_at": "2026-09-01 00:00:00",
                    "last_joined_at": "2026-09-01 00:00:00", "join_count": 1, "is_fake": false },
    "summary": { "total": 3, "still_in_server": 2, "left": 1, "fake": 1, "bonus": 0, "real": 1 },
    "invited": [{ "discord_id": "600", "display_name": "Six", "username": "six", "first_joined_at": "2026-10-05 00:00:00",
                  "last_joined_at": "2026-11-01 00:00:00", "join_count": 2, "in_server": true, "left_at": null, "is_fake": true }],
    "pagination": { "page": 1, "limit": 25, "total": 3, "has_more": false }
  }
}

GET /wallets?discord_id=… (scope: wallets.read)

The Solana wallets a member has verified with HoneyGate (by signing a message with that wallet), with their addresses. Wallet addresses are personal, so this has its own permission: only tick wallets.read on a key for an app you trust with them. /holdings is unchanged and still never returns addresses.

A verified wallet belongs to the person, not to one server, so the limit is membership: a key only gets the wallets of someone who is currently a member of your server. Anyone else, including a member who has left, gets 404 with member_not_found.

Each wallet has address, chain (always solana), label (the name the member gave it, or null) and verified_at (UTC). The first wallet they verified comes first. HoneyGate has no "main wallet" setting, so there is no primary flag. If wallet verification was never installed you get wallet_verify_available: false and an empty list.

For a profile page, combine this with /member, which already returns the member's display_name and avatar.

{
  "ok": true,
  "data": {
    "guild_id": "123456789012345678",
    "discord_id": "100",
    "wallet_verify_available": true,
    "count": 1,
    "wallets": [{ "address": "7xKX...AsU", "chain": "solana", "label": "main", "verified_at": "2026-10-01 00:00:00" }]
  }
}

Holds: POST /points-hold, /points-capture, /points-release, GET /points-holds (scope: points.hold) — writes

For auctions and prize pots: set a member's Coins aside now, decide later.

Leaving kind out of any request behaves exactly as before kinds existed. A retry must repeat the same kind (leaving it out and naming the default count as the same).

Retries are safe, like every write: sending the same request again changes nothing and answers applied: false; reusing an idempotency_key for different data is refused with 409 idempotency_conflict. Holds are confined to the API key's server, and another server's key gets 404 hold_not_found. Nothing here signs or sends an on-chain transaction.

Sending login signals to Alt Detection

If your website has members log in with their Discord account (for example a game site), it can send HoneyGate the same login clues HoneyGate collects when a member signs in to the HoneyGate website: IP address, browser, timezone, language, screen size and device type. Alt Detection compares them with everyone else's, so two accounts that log in to your site from the same place get noticed.

These signals help Alt Detection on every HoneyGate server, not only yours. That is why the signals.write permission can only be switched on by the HoneyGate platform owner. Ask HoneyGate if your site should send them.

Privacy: tell your players. IP addresses are personal data. Your site must tell its players (for example in its privacy policy) that it shares their login details with HoneyGate to detect alt accounts. HoneyGate deletes these raw signals after 90 days, the same as signals from its own website; alt findings that staff have reviewed are kept.

POST /alt-signals (scope: signals.write) — writes

Send one signal:

{
  "discord_id": "DISCORD_ID",
  "ip": "203.0.113.7",
  "user_agent": "Mozilla/5.0 (Windows NT 10.0; Win64; x64) ...",
  "timezone": "Europe/London",
  "locale": "en-GB",
  "screen": "1920x1080",
  "platform": "Win32",
  "seen_at": "2026-11-15T12:00:00Z"
}

or up to 100 at once as { "signals": [ {...}, {...} ] }.

FieldRules
discord_idRequired. A member who is currently in your server (the key's server).
ipThe player's public IPv4 or IPv6 address. Private or local addresses (10.x, 192.168.x, 127.0.0.1...) are refused: if you see those, your site is behind a proxy and should read the real address from it.
user_agentBrowser string, up to 512 characters.
timezone, localeFor example Europe/London (64 max) and en-GB (16 max).
screen, platformFor example 1920x1080 (16 max) and Win32 (64 max).
seen_atOptional. When the player logged in, ISO 8601 or Unix seconds, within the last 24 hours. Defaults to now.

At least one of ip, user_agent, timezone, locale, screen, platform is required. Odd characters are removed and long values are cut, the same way HoneyGate treats its own website's signals.

The answer:

{ "ok": true, "data": { "stored": 1, "duplicates": 0, "skipped": 0, "guild_id": "123456789012345678",
  "results": [ { "index": 0, "status": "stored" } ] } }

Renting roles

Your app can give a member a Discord role for a set time, for example a colour role, a title, or the role that opens a members-only channel, sold in your shop for 7 days. HoneyGate gives the role, remembers the end date, and takes the role away by itself when the time is up (it checks every minute).

First, the server owner picks which roles can be rented. On Integrations → Public API, the Rentable roles card lists each one with a short name (for example color-red), the Discord role, and the longest rental allowed in days. Your app only ever uses the short name, and a roles.write key can never touch a role that is not on that list. Roles with admin or moderator powers, roles above HoneyGate's own role, and roles Discord manages itself (bot roles, Server Booster) cannot be listed.

POST /roles-grant (scope: roles.write) — writes

Gives the role, or extends the rental the member already has.

FieldRequiredNotes
discord_idyesThe member's Discord ID. They must be in your server.
role_keyyesThe short name from the Rentable roles list.
duration_daysone of these twoA whole number of days, 1 or more.
expires_atone of these twoAn end date and time in ISO 8601, in UTC, e.g. 2026-11-22T12:00:00Z. Must be in the future.
idempotency_keyyesAny string unique to this purchase (your order id works well), up to 128 characters.

How extending works when the member already rents that role:

The answer:

{ "ok": true, "data": { "applied": true, "rental_id": 81, "role_key": "color-red", "discord_id": "DISCORD_ID",
  "expires_at": "2026-11-22T12:00:00Z", "extended": false, "capped": false, "guild_id": "…", "idempotency_key": "order-991" } }

Sending the same idempotency_key again changes nothing and returns the same answer with applied: false, so a timed-out request is always safe to retry. Reusing a key with different data is refused (409 idempotency_conflict). If Discord could not give the role (503 bot_unavailable, or 409 grant_failed with the reason, for example HoneyGate's role sitting below the rented role), nothing was saved, and you can retry with the same key. An unknown role_key is 404 unknown_role_key.

POST /roles-revoke (scope: roles.write) — writes

Send discord_id and role_key to end a rental now and take the role away. If there is no running rental the answer is revoked: false with reason: "no_active_rental", which is a success, and the role is left alone: HoneyGate only removes a role it is renting to that member.

GET /roles-rentals?discord_id=… (scope: roles.write)

Lists a member's running rentals in your server: rental_id, role_key, started_at and expires_at (UTC).

Good to know: if a member leaves the server, their rental simply ends. If Discord is briefly unreachable when a rental ends, HoneyGate tries again a little later instead of forgetting it. Use a role that is only handed out by rentals: when a rental ends the role is removed, even if the member also had it before.

Example

curl https://honeygate.app/api/v1/public-api/leaderboard?limit=10 \
  -H "Authorization: Bearer $HONEY_GATE_API_KEY"

Awarding Coins:

curl -X POST https://honeygate.app/api/v1/public-api/points-award \
  -H "Authorization: Bearer $HONEY_GATE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"discord_id":"123456789012345678","amount":250,"idempotency_key":"play-abc123","source":"arcade_win"}'

Want live updates instead of polling?

For push-style integration, reach for Outbound webhooks. HoneyGate calls your URL when things happen, so you skip the polling entirely.