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 returns 401 publishable_key_required, a publishable key on a server route 401 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:

  1. The Activity asks for a ticket (POST /v1/client/link) and opens its url with discordSdk.commands.openExternalLink.
  2. 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.
  3. The wallet is linked at once. The Activity sees it through GET /v1/client/link/:ticket or GET /v1/client/me, its server gets a wallet_linked webhook, 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)
  • to is { "userId": "<discord id>" }, { "userId": "<discord id>", "hold": true } or { "address": "<base58>" }.
  • hold: true pays players who haven't linked a wallet yet: the transfer is checked against the policy now, recorded as held, and sent the moment they link. Without hold, an unlinked player gives 404 wallet_not_linked.
  • amount is a decimal string in token units ("0.01"). idempotencyKey is 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" }.

NextQuick Draw example