Distribution (Dividends)
Access prerequisites
- Permission (module):
manageDividends(to create, approve, and delete distributions). Listing visibility is granted with access to the Investments group. - License/Feature: None specific.
- Menu container: GENERAL → Investments / Financial Distributions group
What it is / when to use
Distribution is the mechanism for paying out earnings (dividends/yields) to holders of a token or an NFT. The operator chooses the asset whose holders will receive payment (a token or an NFT), defines the token to distribute, the total amount, and the percentages, and the system generates a payment list proportional to each holder's position.
The distribution is created in AWAITING_APPROVAL status and only executes after explicit approval. Use this screen to create new distributions, review the generated allocation, approve (release payment), or delete (discard before approving).
Prerequisites
- Permission:
manageDividendsto create/approve/delete (dual — CPM enum on the backend + module in DB). Without it, the approve/delete actions do not appear in the row context menu. - Dependencies: the asset (token or NFT) must already exist and have holders; the token used as the payment method must be registered.
Step by step
- Go to Investments → Distribution (route
/manage-distributions). - Click Create to open the distribution modal.
- Choose the By tokens or By NFTs tab, select the considered asset (holders), the token to distribute, enter the total amount and the percentages.
- Click Generate to preview the per-user allocation; adjust individual values if needed.
- Confirm to save the distribution in
AWAITING_APPROVAL. - Back on the list, in the actions menu (
⋮) of the distribution, use Approve to release the payment.
Fields (creation modal)
| Field | What it is | Required? | System/backend effect |
|---|---|---|---|
| Tab (By tokens / By NFTs) | Defines whether the recipients are holders of a token or an NFT | Yes | Sets token_id (tokens) or nft_id (NFTs) in the payload |
| Considered asset | The token/NFT whose holders will receive payment | Yes | token_id/nft_id; must be validated (selected from the list) — an unvalidated free-text field blocks submission |
| Token to distribute | The token used as the payment method for the earnings | Yes | token_to_distribute |
| Total amount to distribute | Total earnings amount | Yes | total_to_distribute; must be > 0 |
| Percentage to distribute | Percentage applied to the base | No | percentage_to_distribute; if filled, must be ≥ 0 |
| Network percentage | Portion allocated to the network (tokens tab only) | No | percentage_to_network; only exists in the By tokens tab |
In the preview step, each recipient appears with their name, e-mail, and individual amount, which is editable. The sum of individual amounts cannot exceed the total (exceedsTotal blocks confirmation).
Filters and columns (listing)
| Filter / Column | What it shows | Data source |
|---|---|---|
| Search by asset name | Filters by assetName | assetName parameter |
| Order | Newest / oldest | order (newest/oldest) |
| Token | Filters by the considered token | token |
| Status | AWAITING_APPROVAL, PROCESSED, APPROVED, CANCELLED | status |
| Type | All / Token / NFT | type |
| Date | Request date | request_date |
| Token to distribute | Payment method | token_to_distribute |
| Quantity | Total to distribute | total_to_distribute |
| Considered asset | Asset name | assetName |
| Status (column) | Current state; PROCESSED in green, CANCELED in red | status |
Actions and modals
- Create: opens the distribution modal (generation + preview). Saves via
createDistributionRequestinAWAITING_APPROVAL. - View (
⋮ → View): opens the distribution detail with the payment list and how many have already been applied (applied). - Approve (
⋮ → Approve): available only whenstatus === AWAITING_APPROVALand withmanageDividendspermission. Confirms in a bottom-sheet and callsconfirmDistributionRequest— releases payment execution. - Delete (
⋮ → Delete): available only inAWAITING_APPROVALand withmanageDividends. Discards the distribution viadeleteDistributionRequest.
Business rules / considerations
Attention
- The sum of individual amounts in the allocation cannot exceed the total to distribute; confirmation is blocked (
exceedsTotal). - Approve and Delete only exist while the distribution is in
AWAITING_APPROVAL. Once approved/processed, those actions no longer appear on the row. - The network percentage only applies to token distributions — it does not appear for NFTs.
Irreversible
- Approval releases the payment of earnings to holders. Once approved, the distribution cannot be undone from the screen — review the allocation before confirming.
- Financial values:
total_to_distribute, individual amounts, and percentages are handled as BigNumber (up to 8 decimal places,ROUND_DOWN) — no undue rounding. - Idempotency: financial execution in FIN is idempotent by
externalId. If a payment returnsE00021("already processed"), it means success (already credited), not a failure — reprocessing is safe. - Crowdfunding NFTs: the distribution pays earnings, it does not mint or burn NFTs. For assets originating from crowdfunding, the issuance/burn of shares is exclusive to the crowdfunding job — the distribution only credits the payment token to holders.
Examples
Scenario 1 — Distribute profit to holders of a participation token
The company has recognized profit and wants to pay earnings to holders of the EMPX token. Click Create, tab By tokens, set EMPX as the considered asset, choose the payment token (e.g., tBRL), enter the total amount and the desired percentage. Generate the allocation, review the per-holder values, and save in AWAITING_APPROVAL. Then approve from the list to release the payments.
Scenario 2 — Earnings for holders of an NFT collection
A participation NFT distributes periodic yield. Click Create, tab By NFTs, select the NFT, the payment token, and the total amount. Note that the network percentage does not appear on this tab. Generate, review, and save; then approve. The distribution credits the token to the owners — it does not change the NFT quantity.
Scenario 3 — Manual adjustment of a recipient in the allocation
After generating the allocation, a specific holder needs to receive a different amount than the proportional share (e.g., a one-off agreement). In the preview step, edit the value on that row. The system recalculates the remainder and blocks confirmation if the sum exceeds the total. Adjust until the sum fits within the total and confirm.