# Equity tokenization through APIs
Source: https://docs.settlemint.com/docs/developer-guides/runbooks/equity-tokenization
Run the API-led ACME Holdings equity tokenization walkthrough without confusing it with the console version.
This scenario walkthrough shows integrators how to rehearse ACME Holdings equity tokenization with DALP API flows. You follow request-oriented guides for platform setup, user onboarding, trusted issuers, collateral verification, token configuration, and supply operations.
Stay on this page when the operation starts from an API, script, SDK, or integration test. Use the [console equity
tokenization walkthrough](/docs/user-guides/runbooks/equity-tokenization) when an operator needs UI-led steps through
DALP screens.
Treat the names, email addresses, ISIN, and share values as example data. Use your own legal instrument terms, approved issuer records, and compliance policy for production.
The equity tokenization example spans organization setup, compliance preparation, token deployment, and investor supply.
## Prerequisites [#prerequisites]
Before starting this example, confirm that your EVM network has the core platform contracts deployed:
| Contract | Purpose | Deployed by |
| ------------------------- | ------------------------------------------------------------------------------ | ----------------- |
| **DALP Directory** | Registry and discovery service for all platform instances and their components | Platform deployer |
| **DALP Identity Factory** | Creates on-chain identity contracts for users | Platform deployer |
| **DALP System Factory** | Deploys organization-specific system contracts | Platform deployer |
These contracts are typically deployed during initial platform setup by your implementation team. They provide the
foundation for all organizations to build upon.
**Additional requirements**
* Platform URL (e.g., `https://your-platform.example.com`)
* API access token with appropriate roles
* For public chains: ETH or native tokens for transaction gas fees (see gas requirements below)
* Email addresses for all demo participants
**Gas requirements for public chains**
* **Daniel Admin**: Moderate amount for system deployment and permission management
* **Clara Compliance**: Small amount for user registration and verification issuance
* **Olivia Operator**: Moderate amount for asset creation, permissions, minting, and transfers
* **Colin Collateral**: Small amount for issuing collateral verifications
* **Invited users**: Small amount for identity creation (if using invitation flow)
## Scenario overview [#scenario-overview]
This demonstration tokenizes 100,000 shares of ACME Holdings S.A., a Luxembourg company, using a multi-organization platform operated by Digital Securities S.A.
### Organizations [#organizations]
| Organization | Role | Domain | Jurisdiction |
| ------------------------------------ | ----------------------- | --------------------------- | ------------ |
| **Digital Securities S.A.** | Platform operator | digital-securities.example | Luxembourg |
| **ACME Holdings S.A.** | Issuer (equity owner) | acme-holdings.example | Luxembourg |
| **Guardian Collateral Services Ltd** | Collateral agent | guardian-collateral.example | (generic) |
| **Exchange Ltd** | Exchange/vault provider | exchange.example | (generic) |
### Key personas [#key-personas]
**Platform Operators (Digital Securities S.A.)**
| Persona | Name | Email | Purpose |
| ------------------ | ---------------- | --------------------------------------------------------------------------------------------- | ------------------------------ |
| Platform Admin | Daniel Admin | [admin@digital-securities.example](mailto:admin@digital-securities.example) | System setup and configuration |
| Asset Operator | Olivia Operator | [operator@digital-securities.example](mailto:operator@digital-securities.example) | Asset creation and management |
| Compliance Officer | Clara Compliance | [compliance-kyc@digital-securities.example](mailto:compliance-kyc@digital-securities.example) | KYC and regulatory compliance |
**External Partners**
| Organization | Persona | Name | Email | Purpose |
| ---------------------------- | --------------------- | ---------------- | --------------------------------------------------------------------------------------------------- | ----------------------- |
| ACME Holdings S.A. | Issuer Representative | Ian Issuer | [issuer@acme-holdings.example](mailto:issuer@acme-holdings.example) | Legal equity owner |
| Guardian Collateral Services | Collateral Agent | Colin Collateral | [collateral-agent@guardian-collateral.example](mailto:collateral-agent@guardian-collateral.example) | Collateral verification |
| Exchange Ltd | Vault Provider | NovaX Vault | [vault@exchange.example](mailto:vault@exchange.example) | Token custody |
### ACME equity token specifications [#acme-equity-token-specifications]
**Example instrument:**
| Property | Value |
| ---------------------- | ------------------------------- |
| **Issuer** | ACME Holdings S.A. (Luxembourg) |
| **Security type** | Ordinary shares |
| **Total shares** | 100,000 |
| **Reference currency** | EUR |
| **Price per share** | €0.71 |
**On-chain representation:**
| Property | Value |
| ------------------------ | ------------------------------------ |
| **Token name** | ACME Holdings Equity |
| **Symbol** | ACME |
| **Decimals** | 0 (1 token = 1 share) |
| **Maximum supply** | 100,000 |
| **Asset class** | EQUITY |
| **ISIN** | LU0000ACME01 |
| **Initial distribution** | 80,000 to issuer, 20,000 to exchange |
## Implementation steps [#implementation-steps]
### Platform initialization [#platform-initialization]
As Daniel Admin, set up the platform administrator who initializes the system.
See [First Administrator Setup](/docs/developer-guides/platform-setup/first-admin-setup) for the API flow.
Configure these example values:
* **Email**: [admin@digital-securities.example](mailto:admin@digital-securities.example)
* **Organization name**: Digital Securities S.A.
* **Base currency**: EUR
* **Asset factories to enable**: Equity, ... (add whatever asset types you want to support)
For public chains: Ensure Daniel's wallet has sufficient native tokens (ETH, MATIC, etc.) for system deployment
transactions before proceeding.
As the first user, Daniel Admin will deploy all system contracts including identity registry, access manager, and asset factories.
### Grant additional administrative permissions [#grant-additional-administrative-permissions]
Continue as Daniel Admin. Platform setup gives Daniel the minimum roles for managing the new organization. Grant the additional roles needed to invite users and configure extensions.
See [Change Admin Roles](/docs/developer-guides/platform-setup/change-admin-roles) for the API flow.
Add these roles to Daniel Admin:
* **Add-on Manager**: Manage platform extensions and modules
* **Identity Manager**: Required to invite other users
### Invite platform team [#invite-platform-team]
Continue as Daniel Admin. Add the platform operators and external partners who participate in this example.
See [Create Users](/docs/developer-guides/user-management/create-users) for the API flow.
**Platform operators:**
1. **Olivia Operator** ([operator@digital-securities.example](mailto:operator@digital-securities.example))
* **Responsibilities**: Creates tokens, manages corporate actions, handles minting/burning
* **Also needs**: [Wallet verification](/docs/developer-guides/user-management/create-users#create-api-key-optional) (to send transactions)
2. **Clara Compliance** ([compliance-kyc@digital-securities.example](mailto:compliance-kyc@digital-securities.example))
* **Responsibilities**: Manages KYC/AML verification, registers identities, issues verifications
* **Also needs**: [Wallet verification](/docs/developer-guides/user-management/create-users#create-api-key-optional) (to send transactions)
**External organizations:**
3. **Ian Issuer** ([issuer@acme-holdings.example](mailto:issuer@acme-holdings.example))
* **Responsibilities**: Legal owner of equity being tokenized
4. **Colin Collateral** ([collateral-agent@guardian-collateral.example](mailto:collateral-agent@guardian-collateral.example))
* **Responsibilities**: Independent verification of collateral backing
* **Also needs**: [Wallet verification](/docs/developer-guides/user-management/create-users#create-api-key-optional) (to send transactions)
5. **NovaX Vault** ([vault@exchange.example](mailto:vault@exchange.example))
* **Responsibilities**: Institutional vault for token custody
### Assign platform admins [#assign-platform-admins]
Continue as Daniel Admin. After onboarding the team, assign the roles each platform administrator needs.
See [Add Administrators](/docs/developer-guides/platform-setup/add-admins) for the API flow.
**Olivia Operator** needs these roles:
* **Asset Manager** - Create and configure new assets
These roles let Olivia create and manage assets without granting compliance administration.
**Clara Compliance** needs these roles:
* **Identity Manager** - Manage the users registry, which users are known.
* **Verification Issuer** - Issue KYC and compliance verifications
* **Compliance Manager** - Will be able to manage global compliance rules
* **Verification Policy Manager** - Configure verification topics and trusted issuers
These roles let Clara configure verification topics, trusted issuers, and investor checks.
**Colin Collateral** needs these roles:
* **Verification Issuer** - Issue collateral verifications
This role lets Colin issue collateral verifications without broader platform administration.
### Configure trusted issuers [#configure-trusted-issuers]
Log in as Clara Compliance and configure which issuers can issue each verification topic.
For public chains: Ensure Clara's wallet has native tokens for trusted issuer configuration transactions.
See [Configure Trusted Issuers](/docs/developer-guides/compliance/configure-trusted-issuers) for the API flow.
**Clara Compliance as trusted issuer for investor-level verifications:**
* **Know Your Customer (KYC)** - She verifies all investor identities
* **Accredited Investor** - For US qualified investor status (optional, if needed)
* **Qualified Institutional Investor** - For institutional investors under EU rules (optional, if needed)
* **Anti-Money Laundering** - Source of funds verification (optional, if needed)
* **Professional Investor** - For MiFID professional investor classification (optional, if needed)
Clara issues investor verifications because she owns the investor eligibility checks in this example.
**Colin Collateral as trusted issuer for collateral verification:**
* **Collateral** - Verifies that sufficient collateral backs the token
Colin issues this verification because Guardian Collateral Services is the example collateral verifier.
**Olivia Operator as trusted issuer for asset-level verifications:**
* **Base Price** - Provides reference pricing for the asset
* **Unique Identifier** - Manages ISIN and internal reference numbers
* **Asset Classification** - Confirms asset category and type
* **Asset Location** - Confirms jurisdiction of underlying asset (optional, needed for real-estate)
Olivia issues these asset-level verifications because she manages token metadata and classification in this example.
### Register investors in registry [#register-investors-in-registry]
Log in as Clara Compliance and register the investors that will receive tokens.
See [Register User](/docs/developer-guides/user-management/register-user) for the API flow.
**Register Ian Issuer:**
* Choose **Luxembourg** as jurisdiction
**Register NovaX Vault:**
* Choose **Luxembourg** as jurisdiction
**Result:** Both users now show "Registered" status and can receive KYC verifications.
Platform operators (Daniel, Olivia, Clara) don't need registration unless they'll hold tokens.
### Issue KYC verifications [#issue-kyc-verifications]
Continue as Clara Compliance and issue KYC verifications to the registered investors.
See [Verify KYC](/docs/developer-guides/compliance/verify-kyc) for the API flow.
**Verify Ian Issuer:**
* Issue **Know Your Customer** verification
**Verify NovaX Vault:**
* Issue **Know Your Customer** verification
**Result:** Both users now have KYC verifications and can receive ACME tokens.
### Create the ACME equity token [#create-the-acme-equity-token]
Create the equity token using the Asset Designer and the compliance modules needed for this example.
For public chains: Ensure Olivia's wallet has native tokens for asset creation and permission management transactions.
See [Create Asset](/docs/developer-guides/asset-creation/create-asset) for the API flow.
Log in as Olivia Operator and configure:
**Step 1: Asset Class**
* Select **Flexible Income** class
* Choose **Equity** type
**Step 2: Basic Details**
* **Name**: ACME Holdings Equity
* **Symbol**: ACME
* **Decimals**: 0 (whole shares only)
* **Jurisdiction**: Luxembourg
**Step 3: Asset Classification**
* **Category**: Common Equity
* **Class**: Common Equity
* **Unique Identifier**: LU0000ACME01 (ISIN format)
* **Internal Reference**: ACME-EQ-001
**Step 4: Pricing**
* **Currency**: EUR
* **Base Price**: 0.71 (€0.71 per share)
**Step 5: Compliance Modules**
Enable **Smart Identity Verification**:
* Required verification: "Know Your Customer"
* Purpose: Only KYC-verified users can receive assets
Enable **Collateral Requirement** (optional):
* Topic: "Collateral"
* Ratio: 100% (full collateral backing)
* Purpose: Records the collateral verifier's backing check for this example
### Configure token permissions [#configure-token-permissions]
Asset creation gives Olivia the minimum token administration roles. Grant the token-specific roles needed for supply operations, emergency controls, and controlled servicing operations.
See [Change Asset Admin Roles](/docs/developer-guides/asset-servicing/change-asset-admin-roles) for the API flow.
Assign Olivia Operator these additional roles:
* **Custodian** - Execute transfers and forced transfers
* **Emergency** - Pause/unpause token operations
* **Supply Management** - Mint and burn token supply
### Issue collateral verification [#issue-collateral-verification]
Colin must issue a collateral verification before minting is possible. This is a requirement when collateral modules are enabled.
For public chains: Ensure Colin's wallet has native tokens for issuing collateral verification transactions.
See [Collateral](/docs/developer-guides/compliance/collateral) for the API flow.
Log in as Colin Collateral and issue a verification with these details:
* **Amount**: 100000 (covering full supply)
* **Expiration**: 1 year from now
This records that Guardian Collateral Services verified backing for the full token supply in the demo scenario.
### Unpause the token [#unpause-the-token]
Log in as Olivia Operator and activate the ACME asset.
See [Pause/Unpause Asset](/docs/developer-guides/asset-servicing/pause-unpause-asset) for the API flow.
Collateral verification and token unpausing can be done in any order. Both are needed before minting, but they don't
depend on each other.
Olivia can unpause because she has the Emergency role on the ACME token.
### Mint and distribute ACME tokens [#mint-and-distribute-acme-tokens]
Continue as Olivia Operator and mint tokens to the issuer.
See [Mint Assets](/docs/developer-guides/asset-servicing/mint-assets) for the API flow.
For public chains: Ensure Olivia's wallet has sufficient native tokens for minting transactions, which can be
gas-intensive for large amounts.
Mint to ACME Holdings:
* **Recipient**: Ian Issuer (select from contacts or use wallet address)
* **Amount**: 100000 (full token supply)
* **Purpose**: Initial distribution to issuer
### Execute forced transfer to exchange [#execute-forced-transfer-to-exchange]
Continue as Olivia Operator. Move 20,000 tokens from the issuer to the exchange by using the forced transfer workflow as a controlled custodian operation.
For public chains: Ensure Olivia's wallet has native tokens for the forced transfer transaction.
See [Forced Transfer](/docs/developer-guides/asset-servicing/forced-transfer) for the API flow.
Transfer configuration:
* **From address**: ACME Holdings (select from contacts)
* **To address**: NovaX Exchange (select from contacts)
* **Amount**: 20000
* **Purpose**: Allocate tokens to exchange for secondary market custody
Use forced transfer here only to demonstrate a custodian-controlled servicing operation between verified parties. Do not model ordinary investor transfers on this step.
Olivia can execute this operation because she has the Custodian role on the ACME token.
## Troubleshooting [#troubleshooting]
| Issue | Solution |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| Minting fails | Ensure collateral verification covers mint amount (if enabled). Verify all recipients have required KYC verifications. Check operator has Supply Management role. Confirm wallet has sufficient gas tokens (ETH, MATIC, etc.) for public chains. |
| User cannot receive assets | Verify user is registered in identity registry. Ensure user has valid KYC verification. Check token compliance requirements. Confirm user's wallet address is correct. |
| Verifications not trusted | Verify issuer is configured as trusted for specific topic. Check verification data format and expiration. Ensure issuer transaction was confirmed. Refresh page after configuration changes. |
| Role assignment fails | Confirm you have role management permissions. Verify target user completed onboarding. Ensure user belongs to your organization (for internal roles). Check transaction has sufficient gas tokens for public chains. |
For the next operational step, review [asset detail workspace](/docs/user-guides/asset-servicing/asset-detail-workspace) and the [compliance overview](/docs/user-guides/compliance/overview).