Send an issuer its shareholder list after an auction or at month end
Produce one security's shareholder list at a record block, check that it adds up to total supply, and send the CSV, XLSX or PDF file to the issuer.
Overview
After each auction cycle settles, and on the last trading day of each month for securities that trade continuously, the settlement team sends each issuer the list of its shareholders and their settled holdings. DALP produces that list for one security at one record block. Every holder's balance in the list is the on-chain balance after that block.
The settlement team runs this procedure and sends the file. DALP does not start it after an auction and does not deliver it to the issuer yet.
Before you start
- The security must have the historical-balances feature, attached when the security was created. DALP reads holders from the balance history that feature records. A security without it, a record block before the feature was attached, or a security that already had supply when the feature was attached is rejected, because its balance history is incomplete.
- You need a reporting role on the organization's system: admin, auditor, compliance manager or system manager.
- For the Platform API, use an API key from the organization that holds the security. Send it as
X-Api-Key.
Choose when to run it
| Trading model | When to run | Record block |
|---|---|---|
| Auction | After every trade of the auction cycle is final. | The block that holds the cycle's last settlement, or any later block before the next trade of that security. |
| Continuous trading | On the last trading day of the month in the venue calendar, after the close, once the day's trades are final. | The last block of that trading day. DALP does not compute the last trading day; take it from the venue calendar. |
The record block must be final. DALP returns an error for a block later than the newest final block, so the list cannot change after you send it. Leave the record block out to use the newest final block. The answer names the block it used.
Export from the Console
- Open the security and go to Historical balances.
- Enter the record block in As-of block, or leave it empty for the newest final block.
- In Issuer shareholder list, read the record block, the number of holders, the shares held and the total supply.
- Check that Adds up to total supply shows Yes.
- Select Download PDF, Download CSV or Download XLSX. The file is read at the record block shown above the buttons.
Export with the Platform API
Read the totals first:
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>?atBlock=<recordBlock>" \
-H "X-Api-Key: <your api key>"data.reconciled is true when the holders' balances add up to data.totalSupply. data.recordBlock is the block the list is read at.
Then download the file at that same block. format is csv, xlsx or pdf:
curl "https://your-instance.example.com/api/v2/reporting/shareholder-lists/<tokenAddress>/download?atBlock=<recordBlock>&format=csv" \
-H "X-Api-Key: <your api key>" \
-o shareholder-list.csvPass atBlock on the download even when you left it out of the first request. The newest final block moves as the chain grows, and a fixed block keeps the file equal to the totals you checked.
What the file contains
The CSV and XLSX files have one row per wallet that holds the security after the record block, largest holding first. A wallet with a zero balance is left out. The PDF shows the same holders with the record block and its time, the totals and the reconciliation result.
The columns follow the shareholder response of Commission Implementing Regulation (EU) 2018/1212, Annex Table 2, and the register of members of the ADGM Companies Regulations 2020, section 118. They hold the fields the chain records.
| Column | Content | Table 2 field | Section 118 entry |
|---|---|---|---|
security | The security's contract address, in place of an ISIN. | A.4 | Shares held, by class |
symbol | The security's symbol. | ||
recordDate | The date of the record block, as YYYYMMDD in UTC. | A.5 | |
recordBlock | The record block. | ||
account | The holder's wallet, the account the shares are held in. | B.7 | |
identity | The holder's registered OnchainID identity. Empty when the wallet has no registered identity. | C.1 | Member |
country | The holder's registered country as an ISO 3166-1 alpha-2 code. | C.6 | |
shares | The holder's balance in the security's own units. | C.11 | Shares held |
percentOfSupply | The holder's share of total supply, cut to four decimal places and not rounded, so the column never adds up to more than 100. |
The file does not hold names or postal addresses. The issuer matches each identity to the member's name and address in its own records.
Check the list before you send it
- Adds up to total supply must be Yes, or
reconciledmust betrue. A No means a holder is missing from the list. Do not send it; contact support with the security and the record block. - The number of holders should match the investors you expect after the auction or month.
Send the list
Send the CSV or XLSX file, and the PDF as the record of what was sent, through the channel agreed with the issuer. Keep the security address and the record block with the sent file, so that the same list can be produced again.
When DALP cannot produce the list
A refused list returns DALP-0753 with a reason in data.reason:
data.reason | What it means | What to do |
|---|---|---|
feature-not-attached | The security had no historical-balances feature at the record block, so there is no balance history to list. | For a security created without the feature, none: DALP attaches the feature only when it creates a security, so issue new securities with it. For a security whose feature was detached, choose a record block from before the detachment. |
enablement-after-record-block | The feature was attached after the record block. data.boundaryBlock is the block it was attached at. | Choose a record block at or after data.boundaryBlock. |
history-incomplete | The security had supply before the feature was attached, so the balance history is incomplete. data.boundaryBlock is the block the feature was attached at. | No record block can be listed. |
record-block-not-final | The record block is later than the newest final block, data.boundaryBlock. | Wait until the block is final, or leave the record block out. |
Investor statements
List the monthly statements DALP produced for the caller's own wallets, then download each one as CSV or PDF through a short-lived link.
Webhooks
Register an HTTPS endpoint, verify the Standard Webhooks signature DALP sends, and build a receiver against DALP's three-day retry window.