Payouts and holds

Payouts are signed by your project's managed wallet, created in the dashboard and held by Turnkey. Your server asks, Huddle checks your policy, signs and sends.

await huddle.transferSol({ to: { userId, hold: true }, amount: "0.001", idempotencyKey: `round:${roundId}` });
await huddle.transferToken({ to: { userId }, mint, amount: "25", idempotencyKey: `quest:${userId}:intro` });
await huddle.mintToken({ to: { address }, mint, amount: "1", idempotencyKey: `badge:${userId}` });

Paying players who have no wallet yet

Most of your players won't have linked a wallet when they win. Pass hold: true:

  • the transfer is checked against your policy now (amount, token, limits, budgets) and recorded as held;
  • huddle.me() in the Activity lists it under held, so you can say "0.001 SOL is waiting for you";
  • the moment the player links a wallet, Huddle sends it, and your webhook gets the tx result;
  • cancelHeld(idempotencyKey) cancels it if they never come back.

Without hold, paying an unlinked player fails with 404 wallet_not_linked.

Never twice

Every payout has an idempotencyKey (1 to 128 characters, unique in the project). Retrying with the same key and body returns the first attempt's result instead of sending again; a failed attempt moved nothing, so it is tried again. The same key with a different body is refused (409 idempotency_conflict). Use keys that name the reason: round:<id>, quest:<player>:<quest>.

Your policy

Set in the dashboard, enforced on every request:

Setting Default
Max SOL per payout none: SOL payouts are off until you set it
Allowed tokens, with a max per payout none
Payouts per wallet, per rolling hour 20
Payouts per player, per rolling hour 20
Hourly budget per asset, across everyone none

Requests wait up to 15 seconds for confirmation, then answer submitted; the final status arrives by webhook and through huddle.tx(key).

No bets

Quick Draw and every example here pay rewards from the developer's wallet. Don't take entry fees or wagers: Discord's Developer Policy forbids illegal online gambling, and Huddle's terms follow it.

NextWebhooks