Core concepts

A user is one of your customers, identified by your own external_ref. Hbridge never needs their personal data — just a stable reference you choose.

Each user is provisioned a persistent deposit address per chain. The address never changes, so you can display it once and reuse it for every future deposit. Provisioning is idempotent on external_ref, and you can add chains to an existing user later (lazy provisioning). You may only provision on chains an admin has enabled for your account.

Reference: Users & addresses.

A deposit is a single incoming on-chain transaction to one of your deposit addresses. Deposits move through a finality gate:

• pending— detected on-chain but not yet final. Reported quickly so you can show "processing", but not yet spendable.
• final— reached the chain's finality threshold. Only final deposits count toward your balance.
• reorged — a previously reported deposit was dropped by a chain reorganization. Rare, but you should handle the deposit.reorged event and never treat a pending deposit as money in the bank.

Deposits are de-duplicated on (txid, outputIndex), so the same on-chain output is never counted twice. Reference: Deposits & balances.

Your balance is the sum of final, not-yet-paid-out deposits, grouped per (chain, token). It's reported three ways:

• gross — the total amount deposited.
• fee — the Hbridge fee, applied at fee_bps basis points (e.g. 50 = 0.50%).
• net — gross − fee, i.e. what you can actually pay out.

Amounts are always decimal strings — parse them with a decimal library, never a float. Reference: Balances.

A payout is tracked as a settlement. It's asynchronous: Hbridge sweeps the funds sitting across your deposit addresses into your treasury, then sends the net to your whitelisted payout address. The settlement moves through:

pending → sweeping → swept → paying → completed (or failed).

Because it's multi-step, always send an Idempotency-Key so a retried request returns the original settlement instead of paying twice. The fee is retained during settlement, so you receive exactly net. Reference: Payouts.

Rather than polling, let Hbridge push you events as they happen — address.provisioned, deposit.*, payout.*. Delivery is at-least-once and retried on failure, so:

• Dedupe on the event id (you may receive the same event more than once).
• Verify the X-Hbridge-Signature header on every request before trusting it.
• Every event is also stored, so you can replay anything your endpoint missed.

Reference: Webhooks & events.