Quickstart

Provision an address, receive a deposit, and pay out — the whole flow in four calls.

1. Create a user#

Register your end user and provision a deposit address on each chain you want. This is idempotent on your own external_ref — calling it again returns the same user and the same addresses.

Request
curl -X POST https://api.hbridge.cc/v1/users \
  -H "Authorization: Bearer hbridge_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "external_ref": "user_42", "chains": ["ETH"] }'
201 Response
{
  "id": "6a44c5fce075c013e82172ff",
  "external_ref": "user_42",
  "addresses": [
    { "chain": "ETH", "address": "0x6535...ce36" }
  ]
}

Show that address to your user — anything they send to it is credited to user_42.

2. Receive a deposit#

When the user sends funds, Hbridge detects the transaction and notifies your webhook endpoint — first deposit.pending, then deposit.confirmed once it reaches finality. No polling required.

Webhook: deposit.confirmed
{
  "type": "deposit.confirmed",
  "id": "evt_9f2c...",
  "user": { "id": "6a44...", "external_ref": "user_42" },
  "chain": "ETH",
  "token": "USDC",
  "amount": "2",
  "txid": "0x3646...98f9a",
  "created_at": "2026-07-02T10:07:00.000Z"
}

Always verify the signature and dedupe on the event id. Prefer a pull model? Poll GET /v1/deposits instead.

3. Check your balance#

Final, not-yet-paid-out deposits accumulate into your collectable balance, grouped by (chain, token) and shown net of the Hbridge fee.

Request
curl https://api.hbridge.cc/v1/balances \
  -H "Authorization: Bearer hbridge_sk_..."
200 Response
{
  "fee_bps": 50,
  "balances": [
    { "chain": "ETH", "token": "USDC", "gross": "2", "fee": "0.01", "net": "1.99", "depositCount": 1 }
  ]
}

net is what you can pay out. See Balances & fees for how the fee is applied.

4. Request a payout#

Register your whitelisted payout address once per chain, then request a payout of a (chain, token) balance. Payouts are asynchronous: you get a 202 with a pending settlement, then a payout.completed webhook when it settles on-chain.

Set payout address (once per chain)
curl -X PUT https://api.hbridge.cc/v1/payout-address \
  -H "Authorization: Bearer hbridge_sk_..." \
  -H "Content-Type: application/json" \
  -d '{ "chain": "ETH", "address": "0xfCd9...17B6" }'
Request the payout
curl -X POST https://api.hbridge.cc/v1/payouts \
  -H "Authorization: Bearer hbridge_sk_..." \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: 3f8c1e5a-..." \
  -d '{ "chain": "ETH", "token": "USDC" }'
202 Response
{ "id": "6c98...", "status": "pending", "gross": "2", "fee": "0.01", "net": "1.99", "txid": null }

Track it via GET /v1/payouts/:id or the payout.completed / payout.failedwebhooks. That's the full loop — see the API reference for every option.

PreviousIntroductionNextCore concepts