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 sent | Meaning |
|---|---|
x-api-key + x-bakkt-api-key | Register a brand-new user that onboards through Zaira from scratch. |
x-api-key + x-bakkt-api-key + x-bakkt-custodial-wallet-uuid | Connect 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-id | Connect an existing Bakkt user who operates their own (self-custody) wallet. Zaira acts through the user's own Bakkt session. |
Rules:
x-bakkt-api-keyis 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-uuidorx-bakkt-session-id. Omit both to register a new user. - If both
x-bakkt-custodial-wallet-uuidandx-bakkt-session-idare 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
nullto 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.
| Time | Status | User Agent | |
|---|---|---|---|
Retrieving recent requests… | |||
