Token holders

Access prerequisites

• Permission (module): manageToken
• License/Feature: None
• Menu container: GENERAL → Users group

What it is / when to use

A query screen that lists who holds a balance of a specific token and how much each customer owns. The operator selects a token from the dropdown and the screen returns, for that token, the balance of each wallet (along with the account holder's e-mail). Use it for auditing token distribution, verifying circulation, gathering holders for an event (snapshot, distribution), or simply to investigate an asset's position in the database.

This is a read-only screen: it does not credit, debit, or move any balance. To act on a customer's balance, use the actions in User details.

Prerequisites

• Permission: manageToken registered for the operator's role (menu item gating). Permission is dual — static CPM enum + dynamic module in the DB; both must be associated with the role for the screen to appear. In the API-Gateway, the balance-by-unit endpoint (readAllForUnit) is validated by viewGeneralJournal — ensure the operator's role also has it so the query does not return an error.
• License/Feature: none.
• Dependencies on other screens: the token must exist (registered under Tokenization → Manage Tokens) to appear in the dropdown.

Step by step

1. Go to the Users → Token holders menu (/manage-owners).
2. In the dropdown, select the token whose holders you want to query.
3. The table automatically loads the holders with their e-mail and balance.
4. Click the view icon (eye) on a row to open the User details of that holder.
5. Optional: click Export to download the token's holder list as a CSV file.

Filters and columns

Filter / Column	What it shows	Data source
Token selection	Lists all registered tokens; changing it triggers the search (search)	getTokens (TokenController / obs-lib)
E-mail (Name) column	E-mail of the holding wallet's account owner	Cross-reference customerId → user.email (user list loaded in initData)
Value (Balance) column	Token balance in that wallet, displayed with 2–8 decimal places	balance of each AccountBalance returned by readAllForUnit(unitOfMoney) (FinLib) — considers only wallet movements (CREDIT/DEBIT)
View action	Opens the User details of the holder	Navigates to /users/informations/details?userEmail=...

Actions and modals

• Select token: changing the token in the dropdown re-executes the readAllForUnit query for the new unit.
• Export (CSV): generates a CSV in the browser with the columns name (e-mail) and amount (balance) of the listed holders. The file is assembled on the front end (no extra backend call) and named transactions_<date>.csv.
• View (eye): opens the User details of the holder, where individual administrative actions are available.

Business rules / considerations

Attention

• Balance ≠ available for withdrawal. The number displayed is the accounting balance of the wallet for that token. Locks such as a wallet in fundraising (fundraiser's fundraising status), holds, or open orders are not deducted in this view — a holder may appear with a balance here and still be blocked from withdrawal/transfer. For the customer's operational state, check the User details.
• The list depends on the cross-reference with the user database. The e-mail comes from matching customerId → user; technical/system wallets (e.g., token owner, sinks) may appear without a readable e-mail.

• Financial values: balances come from FinLib and are handled with precision (BigNumber) — the UI only formats them to 2–8 decimal places for display. For an exact check, use the raw balance (export/CSV) and respect the token's decimal places.

Related screens

• User details — administrative actions on a holder's balance.
• Manage Tokens — where the tokens listed in the selection are registered.
• Balances (Dashboard) — aggregated view of platform balances.