Users, identity and wallets

A tenant is the unit of administrative isolation within a deployment. In a simple integration it can represent the whole Partner; in other cases it can represent a business line or internal client.

Each end user is represented by a TenantUser, identified by:

tenant_id + user_id

• tenant_id identifies the Partner's scope.
• user_id is an internal, opaque, stable identifier generated by ChatterPay B2B.
• external_user_id is the identifier the Partner already uses in its own systems.

The Partner can keep working with external_user_id, while ChatterPay uses user_id to relate wallets, operations and events.

Because they are data that can change, be recycled or be corrected. They are used as aliases to locate a person, but not as cryptographic identity or as the user's primary key.

The wallet is linked to the TenantUser, which remains stable even if its contact data changes.

The logical wallet, called WalletProfile, represents the user's relationship with its blockchain accounts.

Inside that wallet there are per-network accounts, called ChainAccount. Each account keeps its own address, network, status, signing model and capabilities.

This lets the Partner work with a single wallet from a functional standpoint, even though distinct technical accounts exist internally.

Creating the user generates its identity and its logical wallet. Network accounts are provisioned when the Partner enables a network or when a flow needs to use it.

This model avoids creating keys and accounts the user may never use, and allows onboarding new networks later.

A user has one EVM address, and it is the same on every EVM network the deployment enables: asking for the wallet on Arbitrum and on Base returns the identical address. The identity is derived once per logical wallet and is never scoped by network. Each network still keeps independent balances, nonces, contracts and permissions.

Bitcoin uses a different cryptographic and transactional model, based on addresses and UTXOs. That is why it requires its own account within the same logical wallet.

The Partner or the channel sends a known alias. The first implemented public surface supports E.164-normalized phone numbers: POST /v1/recipient-aliases registers the relationship and POST /v1/recipients/resolve resolves the alias for a chain. The SDK exposes registerRecipientAlias() and resolveRecipient().

The resolution response separates the alias from the financial account and can indicate resolved, unactivated, blocked or not_found. When a usable ChainAccount exists it returns its address; the sandbox obtains the destination through this contract before creating the quote, instead of reading the address from internal state. Claim, change and safe recycling of the phone number are part of the lifecycle that expands without turning the phone number into cryptographic identity or proof of authorization.