Dynamic wallets
A checkout model where every payment gets its own freshly generated deposit address and amount. Use it for one-off invoices and hosted checkout, where a persistent per-user address doesn't fit.
What are dynamic wallets#
With dynamic wallets you don't hold a long-lived address per customer. Instead, for each payment you call the API with an external_id (your order reference) and an amount, and get back a one-time address the customer should pay into. Once the on-chain payment is detected, the request is marked paid and settled to your balance.
This maps cleanly onto a checkout or invoice: create request → show address, amount and a QR code → wait for confirmation → fulfil the order.
Static vs dynamic#
Both models collect crypto into your balance; they differ in how addresses are assigned.
| Static wallets | Dynamic wallets | |
|---|---|---|
| Address model | One persistent address per user, per chain | A new address per payment request |
| Best for | Ongoing top-ups, account funding | Checkout, invoices, one-off payments |
| You provide | A user; the address is reused across deposits | An external_id and amount per payment |
| Amount | Whatever the user sends | Fixed per request |
Base URL#
The dynamic-wallet API is served by a separate backend with its own host; it is not the same base URL as the static Hbridge API. Send all payment-request calls here:
https://api.hbridge.ccFor contrast, the static-wallet API (users, deposits, payouts) lives at https://api.hbridge.cc. Point your integration at the dynamic host above for everything in this section.
Payment lifecycle#
- Your server creates a payment request for a currency with an
external_idand amount. - The API returns a one-time
addressand the exact amount to collect. - The customer sends the funds (your checkout shows the address + a QR code).
- The payment is detected on-chain and marked paid; the amount settles to your balance.
- Your server confirms completion by tracking the payment (see
/dynamic/payment-requests).
Authentication#
Client (checkout) endpoints authenticate with an API key sent in the x-api-key header. Keep this key on your server; never ship it to the browser.
x-api-key: sk_live_...Supported assets#
Fetch the live list of collectable assets before rendering a currency picker. Each entry has a name (the code you pass in the URL) and a display_name.
{
"code": 200,
"data": [
{ "name": "BTC", "display_name": "Bitcoin" },
{ "name": "ETH", "display_name": "Ethereum" },
{ "name": "USDT", "display_name": "Tether" },
{ "name": "USDC", "display_name": "USD Coin" }
]
}