Users, Accounts, and Wallets

A customer wallet includes more than an address. In OOLIN, accounts belong to the integrating service's uid; those accounts own asset balances, deposit destinations, and transaction records. Your application combines these resources into a customer wallet interface.

Users, accounts, and addresses

Concept	Meaning	Identification
Your customer or merchant	The login or business entity in your service	Your customer or merchant ID
uid	The stable customer/business identifier you provide to the Wallet API	The string supplied when creating an account
Account	The unit that owns asset balances and transactions	The returned account_id
Deposit Address	A network-specific destination for funds received by an account	account_id, asset_type_id, network_id, address and memo

One uid can have multiple accounts. Do not equate uid with account_id or automatically choose the first account as the customer's primary account. Explicitly map each account to its business role in your service.

Your customer customer-001
  → uid: user-customer-001
    → USER account
      → balances by asset type: USDT, ETH, etc.
      → destinations by asset and network
      → deposits, withdrawals, and ledger entries

Your merchant merchant-001
  → uid: business-merchant-001
    → BUSINESS account
      → received payment balances
      → external settlements and ledger entries

These strings are design examples. Choose a uid that is unique in your service and whose customer mapping remains stable across account lifecycle events and service restarts.

USER and BUSINESS roles

account_type	Typical purpose	Fund owner
USER	Customer deposits, balance queries, transfers, and withdrawals	Individual customer wallet
BUSINESS	Business deposits, fund holding, transfers, and withdrawals	Business or merchant wallet

In a customer wallet, external deposits credit a USER account and external withdrawals use its balance. A BUSINESS account holds business funds; it does not need to be created for every customer.

For payments, an internal transfer moves funds from a customer USER account to a merchant BUSINESS account. A 10 USDT payment decreases the customer balance by 10 USDT and increases the merchant balance by 10 USDT. Other account transfers use the same movement; the sender and recipient must be different active accounts.

Account type describes the financial role. It does not replace administrator or login permissions in your application. Your backend checks account ownership and action permissions for every request.

Create or reuse an account

POST /accounts can create additional accounts for the same uid. Provision accounts in this order:

1. Check the customer/account mapping stored in your service.
2. Query existing accounts with GET /users/{uid}/accounts. An absent account returns an empty items array.
3. Reuse the intended active account for the required type and role.
4. Create an account only when that intended account is absent, then persist its returned account_id.

Serialize concurrent provisioning for the same customer in your backend. If a create response is lost, inspect the account list for the same uid and your stored mapping first. Define role-specific selection rules when your service supports multiple accounts.

Account state and fund movements

status	Meaning	Your service's behavior
ACTIVE	Available for normal use	Also verify asset, balance, and authorization conditions
LOCKED	Locked	Check the state and reason before new fund movements
DISABLED	Disabled	Confirm eligibility before proceeding

Account state differs from transaction completion. An ACTIVE account does not prove a withdrawal completed, and locking an account does not erase existing transactions or ledger entries. Retrieve transaction detail to confirm results.

Persist a deposit destination

Request deposit destinations by account, asset type, and network. An account can have multiple destinations; the address string alone does not identify its supported asset or network.

Store the following together and display the required destination information:

• Account: account_id
• Asset and network: asset_type_id, network_id
• Destination: address, tag_or_memo
• Your mapping: customer/merchant ID, environment, and account role

Treat an address and required memo as one destination. For an internal payment, you can specify the recipient account_id instead of an address.

See Deposit Addresses for destination roles, address_id versus deposit_id, allocation/retrieval, and interface information.

Networks and Assets explains asset balances and network destinations. For provisioning examples, see Create a User and Wallet Account and Design Payment Accounts.