What the hot wallet is for
The hot wallet is the part of Guveno that moves money in seconds, not minutes. It is for things that have to happen while a customer is staring at a screen: deposits, refunds, gas top-ups, payouts. It is intentionally not where you keep your treasury.
If a function is on the critical path of a user interaction, it almost certainly belongs in the hot wallet. If it can wait until end-of-day batching, it almost certainly does not.
The smallest useful thing: a deposit webhook
Spin up a hot wallet, generate a deposit address per user with /wallet/users/:id/address, and register a webhook for transaction.confirmed. The payload includes the user id, the asset, the amount, and the on-chain tx hash. That is enough to credit a balance in your app.
Important detail: Guveno only fires transaction.confirmed once. If your endpoint times out, we retry with exponential backoff up to 24 hours. Make it idempotent by storing the tx hash before you credit anything.
A worked refund flow
Imagine a customer wants a $20 refund in USDT. From your backend: POST /wallet/transfers with the user id, asset USDT, amount 20, and an idempotency key. Guveno returns a transfer id immediately and processes the on-chain send asynchronously.
Subscribe to transfer.completed and transfer.failed on the same webhook. On completed, mark the refund as settled. On failed, surface the error to the operator queue; failed transfers are usually a fee bump or a paused asset, both fixable in a couple of clicks.
Gas, the silent killer
The most common reason hot-wallet automations stall is a gas balance you forgot to refill. Guveno gives you two ways out: a managed gas pool that tops up from a reserved buffer, or a custom rule that pages someone when gas drops below N. Pick one.
When to graduate to the payment wallet
If you find yourself building invoicing, stablecoin auto-conversion, or merchant reconciliation on top of the hot wallet, stop. That is what the payment wallet is for, and it is one Tweak away.
