Huddle HTTP API
The SDK (@huddle/sdk in the Activity, @huddle/sdk/server on its server) wraps all of this. You only need this page
to call the API from another language or to debug.
Every response is JSON. Errors look like this:
{ "error": { "code": "wallet_not_linked", "message": "Player 80351110224678912 has not linked a wallet" } }
Two kinds of keys
| Key | Where it lives | What it can do |
|---|---|---|
Secret, hdl_live_<43> |
Your Activity's server only | Everything under /v1: wallets of any player, reads, transfers, mints |
Publishable, hdl_pub_<43> |
Your Activity's client (it is public) | /v1/client/* only, and only for the player whose Discord token comes with the request |
- Keys are created in the dashboard. The full key is shown once; Huddle stores its SHA-256 hash and a short prefix.
- A project can have up to 10 active keys. A revoked key stops working within 30 seconds on every API instance.
- A missing, malformed, unknown or revoked key returns
401 unauthorized. A secret key on a client route returns401 publishable_key_required, a publishable key on a server route401 secret_key_required.
Discord user IDs are snowflakes: always send and expect them as strings (they don't fit in a JavaScript number).
Inside Discord: the URL mapping
Activities run in an iframe and every request goes through Discord's proxy. In the Discord Developer Portal, under your
app's Activities → URL Mappings, add the prefix /huddle pointing to api.huddle.cash (the Huddle API). The client SDK then calls
/.proxy/huddle/v1/client/... by default. Outside Discord (local testing), pass baseUrl.
Client API (/v1/client, publishable key)
Headers: x-api-key: hdl_pub_… and authorization: Bearer <the player's Discord access token> (the token your Activity
passes to discordSdk.commands.authenticate, with the identify scope).
Huddle checks the token with Discord (GET /oauth2/@me) and caches the answer for up to 5 minutes. The token must have
been issued to the project's Discord application (set in the dashboard); otherwise 401 discord_token_invalid. Without
an application ID in the project, 409 discord_app_not_set.
| Route | Response |
|---|---|
GET /v1/client/me |
{ user: { id, username, displayName, avatarUrl }, wallet: { address, linkedAt } | null, held: Held[], cluster } |
POST /v1/client/link |
{ url, ticket, expiresAt }: a one-click linking page for this player (15 minutes, one use) |
GET /v1/client/link/:ticket |
{ status: "waiting" | "linked" | "expired", address?, expiresAt? } |
POST /v1/client/link-codes/claim { code } |
{ address, linkedAt }: links the wallet behind a code from the linking page |
DELETE /v1/client/wallet |
{ address | null }: unlinks the player's wallet |
GET /v1/client/wallet/balance |
{ address, lamports, sol } (404 wallet_not_linked without a wallet) |
GET /v1/client/wallet/tokens[?mint=] |
{ address, tokens: [{ mint, amount, decimals, uiAmount }] } |
Held is { idempotencyKey, kind, asset ("SOL" or a mint), units, amount (decimal SOL, or null for tokens), createdAt }.
Linking a wallet
Wallet extensions don't run inside Discord, so linking happens in the player's browser:
- The Activity asks for a ticket (
POST /v1/client/link) and opens itsurlwithdiscordSdk.commands.openExternalLink. - The page already knows the Discord account. The player picks a wallet (Wallet Standard: Phantom, Solflare,
Backpack…) and signs a free message in Sign-In With Solana format: "Link this wallet to the Discord account @name in
" . No transaction, nothing to pay. - The wallet is linked at once. The Activity sees it through
GET /v1/client/link/:ticketorGET /v1/client/me, its server gets awallet_linkedwebhook, and every transfer held for the player goes out.
A ticket works once. A wallet belongs to one Discord account per project: linking it from another account moves it, and
the previous account gets wallet_unlinked.
Fallback, with a code: opened without a ticket (<API>/link/<project-slug>), the page hands out an 8-character code
(XXXX-XXXX, 15 minutes, one use) that the player types in the Activity, which claims it with
POST /v1/client/link-codes/claim (or its server with POST /v1/link-codes/claim).
Server API (/v1, secret key)
Project and players
| Route | Response |
|---|---|
GET /v1/project |
{ id, name, slug, cluster, discordAppId, walletAddress | null, linkUrl, webhooks } |
GET /v1/players/:userId/wallet |
{ userId, address | null, linkedAt | null } |
POST /v1/players/wallets { userIds: string[] } (max 200) |
{ wallets: { "<userId>": address | null } } |
GET /v1/players/:userId/held |
{ userId, held: Held[] } |
DELETE /v1/players/:userId/wallet |
{ userId, address | null } |
POST /v1/link-tickets { userId, username, avatar? } |
{ url, ticket, expiresAt }, for a server that identified the player itself |
GET /v1/link-tickets/:ticket |
{ status, address?, expiresAt? } |
POST /v1/link-codes/lookup { code } |
{ address, expiresAt } (the code isn't used up) |
POST /v1/link-codes/claim { code, userId, username? } |
{ userId, address, linkedAt } |
Reads
Reads use the project's cluster and are cached for about 10 seconds.
| Route | Response |
|---|---|
GET /v1/wallets/:address/balance |
{ address, lamports, sol } |
GET /v1/wallets/:address/tokens[?mint=] |
{ address, tokens: [...] } (Token and Token-2022) |
GET /v1/wallets/:address/assets[?collection=] |
{ address, assets: [{ id, name, collection, image, interface }] } (DAS when configured) |
GET /v1/signatures/:signature |
{ signature, status, slot, error } |
Transactions
Signed by the project's managed wallet (keys held by Turnkey in production). Until the wallet is created in the
dashboard: 409 wallet_not_configured.
| Route | Body |
|---|---|
POST /v1/tx/transfer-sol |
{ to, amount, idempotencyKey } |
POST /v1/tx/transfer-token |
{ to, mint, amount, idempotencyKey } |
POST /v1/tx/mint-token |
{ to, mint, amount, idempotencyKey } |
GET /v1/tx/:idempotencyKey |
the TxResult (404 not_found if unknown) |
DELETE /v1/tx/:idempotencyKey |
cancels a held transfer (409 not_held otherwise) |
tois{ "userId": "<discord id>" },{ "userId": "<discord id>", "hold": true }or{ "address": "<base58>" }.hold: truepays players who haven't linked a wallet yet: the transfer is checked against the policy now, recorded asheld, and sent the moment they link. Withouthold, an unlinked player gives404 wallet_not_linked.amountis a decimal string in token units ("0.01").idempotencyKeyis 1 to 128 characters, unique per project: the same key never pays twice.
TxResult:
{ "idempotencyKey": "round:42", "kind": "transfer-sol", "status": "confirmed", "signature": "5h6x…", "recipient": "9xQe…", "error": null }
status is held, pending, submitted, confirmed or failed. A request waits up to 15 seconds for confirmation;
past that it answers submitted and the final status arrives as a tx webhook and through GET /v1/tx/:key.
Same key, same body: the earlier attempt's result (a failed one is tried again, since it moved nothing). Same key,
different body: 409 idempotency_conflict.
The project's transaction policy (dashboard): max SOL per transfer (none = SOL transfers off), allowed mints with a max each, per-wallet and per-player hourly limits (20 by default), hourly budgets per asset. Held transfers count toward limits and budgets from the moment they are requested.
Webhooks
Set a webhook URL in the dashboard. Huddle POSTs each event as JSON with
x-huddle-signature: t=<unix seconds>,v1=<hex HMAC-SHA256 of "<t>.<raw body>">, keyed with the project's signing secret
(whsec_…, shown in the dashboard). Refuse signatures older than 5 minutes. HuddleServer.verifyWebhook(secret, rawBody, header) in the server SDK does it and returns the event.
{ "v": 1, "at": 1795276420479, "type": "wallet_linked", "userId": "80351110224678912", "address": "9xQe…" }
{ "v": 1, "at": …, "type": "wallet_unlinked", "userId": "…", "address": "…" }
{ "v": 1, "at": …, "type": "tx", "key": "round:42", "kind": "transfer-sol", "status": "held" | "confirmed" | "failed",
"signature": "…" | null, "userId": "…" | null, "error": null }
{ "v": 1, "at": …, "type": "watch", "name": "treasury", "address": "…", "signature": "…", "slot": 312345678, "failed": false }
{ "v": 1, "at": …, "type": "ping" }
Deliveries are retried 4 times on network errors, 429 and 5xx. Treat events as hints and read the API for the authoritative state.
Quotas and errors
Per project: 600 requests a minute, 100,000 a day, 1,000 transactions in any 24 hours, 5 open linking tickets per player.
| Code | HTTP | Meaning |
|---|---|---|
unauthorized / secret_key_required / publishable_key_required |
401 | Key missing, revoked, or the wrong kind for the route |
discord_token_invalid / discord_scope_missing |
401 | The Discord token is expired, revoked, from another app, or lacks identify |
discord_app_not_set |
409 | The project has no Discord application ID |
discord_unreachable / discord_rate_limited |
502 / 429 | Discord couldn't check the token right now |
invalid_request / invalid_json / invalid_user_id / invalid_address / invalid_mint / invalid_amount |
400 | Bad input |
ticket_expired / challenge_expired / invalid_signature |
400 | Linking page: reused or late ticket, stale message, wrong signature |
link_code_invalid |
404 | Code mistyped, used, expired, or from another project |
wallet_not_linked |
404 | to.userId has no wallet (send hold: true to keep the transfer for them) |
mint_not_allowed / amount_over_limit / sol_transfers_disabled |
403 | Refused by the policy |
wallet_not_configured / idempotency_conflict / not_held |
409 | See above |
recipient_rate_limited / player_rate_limited / hourly_budget_exceeded / daily_tx_quota_exceeded / too_many_tickets |
429 | Limits (the SDK doesn't retry these) |
rate_limited / daily_quota_exceeded |
429 | Request quotas |
rpc_error / wallet_unavailable |
502 | The attempt is recorded failed; retry with the same key |
GET /health needs no key: { ok: true, wallets: "turnkey" | "local" | "none" }.