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:
| Scope | Grants |
|---|---|
gates.read | List gates and their conditions |
members.read | List members (with XP and join dates) |
points.read | Read points totals, the leaderboard, and rank |
points.write | Award guild currency exactly once |
points.spend | Spend a member's guild currency exactly once, never below zero |
points.adjust | Reverse a prior API award exactly once |
roles.write | Give or remove only the roles you mark as rentable, with an end date (see Renting roles) |
points.hold | Put a member's guild currency on hold, then take it or give it back |
audit.read | Read audit-log entries |
holdings.read | Read a member's on-chain holdings (NFT counts and token balances) for your server's tracked assets |
snapshots.read | Read complete cached NFT holder snapshots, including wallet addresses, for collections you explicitly approve for the key |
signals.write | Send 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:
min_amountis the raw value stored in the gate configuration, retained for compatibility.min_amount_enforcedis the value HoneyGate actually compares during evaluation. NFT and trait counts are rounded up to a whole item and never below 1; fungible-token amounts pass through.
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:
in_server—trueorfalse. A member's record is kept after they leave so older history still makes sense, so "we found a record" is not the same as "they are still here." This field says which.staff— their standing in your server:levelisowner,admin,stafformember, alongsideis_owner/is_admin/is_staffbooleans. An owner counts as an admin, and an admin counts as staff.
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:
- Tokens return
amount_raw— the balance in the token's smallest unit, as a string — plusdecimals. Render it asamount_raw ÷ 10^decimals. We never send a floating-point token amount, because float rounding loses precision on large balances. - NFT collections return a whole
count.
Each asset, and the response overall, carries freshness evidence:
checked_at(overall) — when this response was produced (UTC).data_as_of(overall) — the oldest underlying cache timestamp that fed it.checked_at(per asset) — when that asset's data was last read on-chain.complete(overall) —trueonly if every tracked asset could be read.
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:
| Field | Required | Notes |
|---|---|---|
discord_id | yes | The member's Discord ID. They must be in your server. |
amount | yes | A whole number above zero, up to 1,000,000 per call. |
idempotency_key | yes | Any string unique to this award — your own play or transaction id works well. |
source | no | A short label that shows in the ledger, e.g. arcade_win. Defaults to external_api. |
note | no | A human-readable note, up to 500 characters. |
kind | no | reward (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.
| Field | Meaning |
|---|---|
cash_held | Coins in members' pockets (positive balances only). |
bank_held | Coins in members' banks, or null if your server has no bank. |
total_held | cash_held + bank_held. |
holders | How many members hold more than 0 (cash and bank together). cash_holders counts cash only. |
median_balance | The middle balance among holders (cash and bank together), rounded down. |
top | The 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_total | Coins earned (credits) and spent (debits) in the period, as positive numbers. |
period.earned_by_source / period.spent_by_source | The same, per ledger source (for example daily, work, shop_buy), largest first, with an entries count. |
currency | Your 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:
| Field | Meaning |
|---|---|
other_discord_id | The other account. other_display_name, other_username and other_in_server are filled in when HoneyGate knows that account in your server, otherwise null. |
direction | alt_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. |
status | pending (flagged, not reviewed yet) or confirmed (staff agreed). |
confidence | How strongly the signals matched, 0 to 100. |
created_at / reviewed_at | When 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:
| Field | Meaning |
|---|---|
inviter_discord_id | Whose 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_username | The inviter's name in your server, when known. |
invite_code | The invite code used, when known. |
first_joined_at / last_joined_at / join_count | Their first join, their most recent join, and how many times they have joined. |
is_fake | true 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.
POST /points-holdtakes the Coins out of the member's balance straight away, so they can't be spent anywhere else while you wait. Senddiscord_id,amount(1 to 1,000,000), a requiredidempotency_key, and optionalsource,note,expires_in_minutes(1 to 43,200, which is 30 days; default 1,440, one day) andkind(burn, the default, orpot_in: what capturing the hold will count as). It is refused with409 insufficient_balanceif the member doesn't have enough. The answer includeshold_id,status(held),amount,balance(after the hold) andexpires_at.POST /points-capturekeeps the held Coins: the hold becomes a final spend.POST /points-releasegives them back. Both takehold_id(orhold_idempotency_key, the key you placed the hold with) and a newidempotency_keyfor this step. They answer with the hold'sstatus(capturedorreleased) and the member'sbalance.- A hold can only be settled once. Capturing or releasing a hold that is already settled answers
409with a code naming its current status:hold_captured,hold_releasedorhold_expired. - If you do neither before
expires_at, HoneyGate gives the Coins back by itself within about a minute (statusexpired). A capture that arrives after the expiry time is refused with409 hold_expiredand the Coins go back. GET /points-holds?discord_id=…lists that member's holds that are stillheldin your server, newest first (up to 100), withheld_totaland the member'sbalance.
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": [ {...}, {...} ] }.
| Field | Rules |
|---|---|
discord_id | Required. A member who is currently in your server (the key's server). |
ip | The 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_agent | Browser string, up to 512 characters. |
timezone, locale | For example Europe/London (64 max) and en-GB (16 max). |
screen, platform | For example 1920x1080 (16 max) and Win32 (64 max). |
seen_at | Optional. 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" } ] } }
statusisstored,duplicate(the same details for this member within an hour; nothing new to save, which is fine),invalid(with acodesuch asinvalid_ip,invalid_discord_id,invalid_seen_at,no_signals), orskipped(member_not_found).- Sending one signal: an invalid one answers
400with its code, and a member who isn't in your server answers404 member_not_found. A batch always answers200with a result per item. - It is safe to call on every login or page load: repeats within an hour are skipped. Each key can store up to 50,000 signals a day (on top of the normal 120 requests a minute); past that you get
429 signal_quotaand nothing from that request is stored. 409 alt_detection_offmeans Alt Detection isn't installed on HoneyGate, so nothing is collected.
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.
| Field | Required | Notes |
|---|---|---|
discord_id | yes | The member's Discord ID. They must be in your server. |
role_key | yes | The short name from the Rentable roles list. |
duration_days | one of these two | A whole number of days, 1 or more. |
expires_at | one of these two | An end date and time in ISO 8601, in UTC, e.g. 2026-11-22T12:00:00Z. Must be in the future. |
idempotency_key | yes | Any string unique to this purchase (your order id works well), up to 128 characters. |
How extending works when the member already rents that role:
- With
duration_days, the days are added to the current end date (7 days left + 3 more = 10 days left). - With
expires_at, the rental ends at whichever is later: the current end or the date you send. An extension never shortens a rental. - Either way, the end is never more than the role's longest rental counted from now. If your request went past that, the end is cut to the limit and the answer says
"capped": true.
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.