Users & addresses

Register your end users and provision a persistent deposit address per chain. Provisioning is idempotent on your external_ref.

Create user#

The core provisioning call: create (or fetch) a user and hand back a deposit address on each requested chain. Safe to call on every login — it's idempotent on external_ref.

POST/v1/users

Create (or fetch) a user and provision a deposit address on each requested chain. Idempotent on external_ref — calling again returns the same user and the same addresses.

Body
FieldTypeRequiredDescription
external_refstringyesYour own unique id for this user.
chainsstring[]noSubset of your enabled chains to provision. Omit to provision on all of your enabled chains. A chain you are not enabled for returns 422 chain_not_enabled.
Request
POST /v1/users
{
  "external_ref": "user_42",
  "chains": ["ETH"]
}
201 Response
{
  "id": "6a44c5fce075c013e82172ff",
  "external_ref": "user_42",
  "addresses": [
    { "chain": "ETH", "address": "0x653528F39C3b6Aa847ea36268e403Bb610f1ce36" }
  ]
}

List users#

GET/v1/users

List your users (newest first) with their provisioned addresses. Paginated.

Query
FieldTypeRequiredDescription
limitnumbernoPage size, 1–200, default 50.
cursorstringnoPrevious response's next_cursor for the next page.
200 Response
{
  "users": [
    {
      "id": "6a44c5fce075c013e82172ff",
      "external_ref": "user_42",
      "created_at": "2026-07-02T10:00:00.000Z",
      "addresses": [
        { "chain": "ETH", "address": "0x6535...ce36" }
      ]
    }
  ],
  "next_cursor": "6a44c5fce075c013e82172ff",
  "has_more": true
}

Get user#

GET/v1/users/:id

Fetch a single user and their provisioned addresses.

Path
FieldTypeRequiredDescription
idstringyesThe Hbridge user id.
200 Response
{
  "id": "6a44c5fce075c013e82172ff",
  "external_ref": "user_42",
  "created_at": "2026-07-02T10:00:00.000Z",
  "addresses": [
    { "chain": "ETH", "address": "0x6535...ce36" }
  ]
}

Add address#

Already created a user on some chains and now need another? Add chains to an existing user without re-sending their whole profile.

POST/v1/users/:id/addresses

Add one or more chains to an existing user (lazy provisioning). Requested chains are gated to your enabled set (422 chain_not_enabled otherwise).

Body
FieldTypeRequiredDescription
chainsstring[]yesChains to provision for this user.
Request
POST /v1/users/6a44c5fce075c013e82172ff/addresses
{
  "chains": ["POLYGON"]
}
201 Response
{
  "id": "6a44c5fce075c013e82172ff",
  "addresses": [
    { "chain": "POLYGON", "address": "0x..." }
  ]
}
PreviousCore conceptsNextDeposits & balances