Initiate user

Creates or connects a user inside the Zaira system. Responds with the user UUID that must be used for all subsequent communication with Zaira (e.g. in ask and ask/stream).

Both x-api-key and x-bakkt-api-key are required on every call. What you send alongside them determines which kind of user is created:

Headers sentMeaning
x-api-key + x-bakkt-api-keyRegister a brand-new user that onboards through Zaira from scratch.
x-api-key + x-bakkt-api-key + x-bakkt-custodial-wallet-uuidConnect an existing Bakkt user who holds a custodial wallet. Zaira signs in with that wallet and can execute transfers on their behalf.
x-api-key + x-bakkt-api-key + x-bakkt-session-idConnect an existing Bakkt user who operates their own (self-custody) wallet. Zaira acts through the user's own Bakkt session.

Rules:

  • x-bakkt-api-key is always required, including for brand-new users. Zaira communicates with the Bakkt API on every request, and that always requires a Bakkt API key.
  • To connect an existing Bakkt user, add either x-bakkt-custodial-wallet-uuid or x-bakkt-session-id. Omit both to register a new user.
  • If both x-bakkt-custodial-wallet-uuid and x-bakkt-session-id are supplied, the custodial wallet takes precedence.
  • You do not supply the Bakkt user UUID. Zaira resolves the user's Bakkt identity directly from Bakkt using the supplied wallet or session.

The response is the same on every path: the Zaira user_uuid. Whether the user is custodial or self-custody is resolved internally by Zaira and is not exposed here.

Optional request body:

  • ip_address — the user's client IP (IPv4 or IPv6). Not required to initiate a user. Store it at initiation if a US self-custody user should be able to fund their wallet. Omitting it does not block initiation or other supported self-custody capabilities, but wallet funding is unavailable until an IP is stored.

Repeat /initiate for an existing user:

  • Send a non-empty IP string to set or overwrite the stored IP.
  • Send null to clear it.
  • Omit the field to leave any stored IP unchanged. Omitting the field does not clear an existing IP.

Sending ip_address on /ask or /ask/stream does not store it and does not enable funding. Wallet funding (adding money to the wallet) is distinct from executing a transfer to a beneficiary; self-custody users still never have Zaira execute that transfer.

Recent Requests
Log in to see full request history
TimeStatusUser Agent
Retrieving recent requests…
LoadingLoading…
Body Params
string | null

User's client IP address (IPv4 or IPv6). Optional. Send a non-empty string to store or overwrite it; send null to clear a previously stored IP. Omit the field to leave any existing IP unchanged. A stored IP is required for wallet funding to be available to US self-custody users. Sending this field only on /ask or /ask/stream does not persist it.

Headers
string
required

Bakkt API key. Required on every call, including when registering a brand-new user. It also authorises the lookup of an existing Bakkt user when a wallet UUID or session ID is supplied.

uuid

UUID of the user's Bakkt custodial wallet. Required together with x-bakkt-api-key unless x-bakkt-session-id is supplied instead. Omit if the user operates their own (self-custody) wallet.

string

Active Bakkt session ID of an existing Bakkt user. Required together with x-bakkt-api-key unless x-bakkt-custodial-wallet-uuid is supplied instead. Use this for self-custody users.

Responses

Language
Credentials
Header
URL
LoadingLoading…
Response
Click Try It! to start a request and see the response here! Or choose an example:
application/json