Issuer: Token deployment and configuration

This documentation outlines the process flow for creating and deploying tokens using our API. For detailed parameter specifications and error codes, please refer to the Swagger documentation.

📘

Prerequisites:

To complete this use case, you will need to authenticate your request(s). You can generate your token by following these steps:

  • Make sure to leverage an existing account from the correct role, e.g. Agent, Owner, Investor, etc.
  • If this use case requires you to leverage an Agent account, make sure your 2FA is disabled via the Servicing portal.
  • Navigate to the "Getting API access" page to generate the required JWT, thanks to your credentials.
  • Add the JWT to the header of your request.

Token Creation and Deployment Process Flow

 Step 1: Get available blockchain networks

Before creating new token, it’s required to retrieve all supported blockchain networks to guarantee that token will be actually created.

The response contains the details of the actual supported networks, including name, chainId, nativeCurrency, etc.

GET /v2/networks

 Step 2: Get issuer ID

Obtain your issuer_id which is required for token creation.

Key Information: You can get your portal portalId from your CSM manager.

GET /v2/issuer-portals/{portalId}/issuers/me

 Step 3: Create token draft

Create a token draft with basic configuration such as name, symbol, network, and type. Most fields can be modified before deployment begins, but some like name, symbol, and network become locked once deployment starts, which also helps save gas on future changes.

POST /v2/assets/servicing/tokens

Key Information:

  • Store the returned tokenId for subsequent steps
  • Certain fields cannot be changed after deployment (network, name, symbol)

Step 4: Set token owner (Optional)

The owner wallet address is the only wallet with the authority to add agents and configure an ERC-3643 token. This exclusive role guarantees that only trusted parties can manage essential functions of the token, such as governance, access controls, and operational parameters.

Note: If you don’t explicitly set the owner wallet address, the token creator will be assigned as the default owner.

Warning: The token owner can only be updated before the token is deployed.

4.1 Retrieve current token owner

First, use this endpoint to get the owner for your token to understand the existing configuration:

GET /v2/assets/servicing/tokens/{tokenId}/owner

4.2 Set a new token owner

Use this endpoint to modify the owner of your token:

PUT /v2/assets/servicing/tokens/{tokenId}/owner

Step 5: Configure identity eligibility and compliance rules (Optional)

Set the identity eligibility criteria for your token by specifying the claims that must be present on the ONCHAINID profiles of recipients. These claims will correspond to those assigned to onchain identities during the investor qualification process.

Warning: When creating a token a new KYC claim is selected by default. You can edit or remove and add a new one.

5.1 Retrieve current claims

First, use this endpoint to get the current list of claims for your token to understand the existing configuration:

GET /servicing/api/tokens/{tokenId}/required-claims

Response includes:

  • List of required claims with their current status (ACTIVE, PENDING, FAILED, REMOVED)
  • Claim details (name, description, topic, trusted issuers)
  • Available actions for each claim

5.2 Execute claim actions

Use this endpoint to add, modify, or remove claims for your token:

POST /servicing/api/tokens/{tokenId}/required-claims/actions

Key Information:

  • CREATE: Add a new required claim to the token
  • DELETE: Remove an existing required claim from the token
  • The topic parameter identifies the specific claim type
  • Store the returned actionId for transaction logging

5.3 Sign and Submit the Claim Transaction (if token is deployed)

Refer to the guide based on the specific sign and broadcast solution your API integration requires by visiting the following link: Blockchain signature flow.

Include the taskId returned in the previous endpoint's response when calling the following transaction logging endpoint.

Logging the transaction is essential to reconcile on-chain and off-chain flows. Since the user handles blockchain interactions on their own, we use the taskId to:

  • Identify the workflow uniquely.
  • Maintain a consistent link between off-chain logic and on-chain activity.
  • Ensure traceability and reliability in our subscription/order system.

Steps to Complete:

  1. Sign the transaction payload
  2. Broadcast the signed transaction to the blockchain network
  3. Log the transaction hash:

POST /servicing/api/tokens/{tokenId}/required-claims/actions/{actionId}/tasks/{taskId}/transactions

Step 6: Configure compliance rules (Optional)

Use this endpoint to define or apply compliance actions associated with a specific rule. This can include:

  • Country-based restrictions: Restrict token transfers to residents of specific countries by defining an approved list. Any transfer to a recipient outside these countries will be automatically rejected.
  • Supply limitations: Enforce rules such as total token supply caps or per-investor holding limits.
  • Standard compliance rules: Easily configure platform-supported rules like transfer restrictions, conditional transfers, whitelisting, and transfer fees.
  • Custom business logic: Add tailored compliance rules to address specific regulatory or operational requirements unique to your business case.

6.1 Retrieve compliance rules

First, use this endpoint to get the current list of compliance for your token to understand the existing configuration:

GET /servicing/api/tokens/{tokenId}/compliance-rules

6.2 Execute compliance actions

Use this endpoint to add compliance rules for your token:

POST /servicing/api/tokens/{tokenId}/compliance-rules/actions

The response includes the ruleId for each rule, which is required to update a compliance rule, delete a compliance rule or sign and submit the compliance transaction in subsequent steps.

6.3 Update or delete compliance rules

Use this endpoint to modify or remove compliance rules for your token:

POST /servicing/api/tokens/{tokenId}/compliance-rules/{ruleId}/actions

6.4 Sign and Submit the Compliance Transaction (if token is deployed)

Refer to the guide based on the specific sign and broadcast solution your API integration requires by visiting the following link: Blockchain signature flow.

Include the taskId returned in the previous endpoint's response when calling the following transaction logging endpoint.

Logging the transaction is essential to reconcile on-chain and off-chain flows. Since the user handles blockchain interactions on their own, we use the taskId to:

  • Identify the workflow uniquely.
  • Maintain a consistent link between off-chain logic and on-chain activity.
  • Ensure traceability and reliability in our subscription/order system.

Steps to Complete:

  1. Sign the transaction payload
  2. Broadcast the signed transaction to the blockchain network
  3. Log the transaction hash:

POST /servicing/api/tokens/{tokenId}/compliance-rules/{ruleId}/actions/{actionId}/tasks/{taskId}/transactions

 Step 7: Initiate Token Deployment

Start the deployment process for the configured token

POST /v2/assets/servicing/tokens/{tokenId}/actions/deploy

Implementation Note: All token deployment transactions are signed internally by the system.

 Step 8: Token Deployment Status Monitoring

To check the status of a token deployment:

GET /v2/assets/servicing/tokens/{tokenId}

 Frequently Asked Questions

Q: What happens if the deployment fails?

A: The token status will reflect any failure states and error information can be retrieved through the token details endpoint.

Q: Who can initiate a token deployment?

A: Only issuers of the token have the permission to initiate deployments.