# Deploy and mint a stablecoin

Source: https://docs.settlemint.com/docs/developer-guides/runbooks/create-mint-stablecoins
Create a stablecoin token with the DALP TypeScript client, configure the
required roles and collateral issuer, add collateral, and mint supply.




A stablecoin needs a token contract, system roles, token roles, trusted collateral issuer status,
and recorded collateral before minting. Create the stablecoin with the DALP TypeScript client.
Then configure issuer and role permissions, add collateral with an expiry timestamp, and mint supply.
Fiat reserve custody, treasury approval, and payment-rail settlement stay outside this API path.

<Mermaid
  chart="`
flowchart TD
Issuer[&#x22;Stablecoin operator&#x22;] --> Client[&#x22;TypeScript client&#x22;]
Client --> API[&#x22;DALP asset API&#x22;]
API --> Collateral[&#x22;Collateral and reserve policy&#x22;]
API --> Issuers[&#x22;Trusted issuers&#x22;]
API --> Compliance[&#x22;Identity and compliance checks&#x22;]
Collateral --> Contract[&#x22;Stablecoin token contract&#x22;]
Contract --> Holder[&#x22;Holder wallet supply&#x22;]
`"
/>

## Prerequisites [#prerequisites]

Before you run the script, you need:

1. A running DALP instance and its platform URL, such as `https://your-platform.example.com`.
2. A DALP API key for the account that runs the script.
3. A wallet PIN code configured from **Account → Wallet** in the DALP UI.
4. An account with the `admin` role, or an administrator who can grant the required system roles and trusted issuer status.
5. The wallet address returned by `dalp.user.me({})`. The script uses it when granting token roles and minting to the first holder.

***

## Quick reference [#quick-reference]

| Step | What                          | Method                                           |
| ---- | ----------------------------- | ------------------------------------------------ |
| 1    | Initialize Client             | `initializeClient`                               |
| 2    | Get user info                 | `userMe`                                         |
| 3    | Set up roles & trusted issuer | Grant `tokenManager`, `claimPolicyManager` roles |
| 4    | Create stablecoin             | `tokenCreate` (type: "stablecoin")               |
| 5    | Grant token roles             | `tokenGrantRole`                                 |
| 6    | Unpause token                 | `tokenUnpause`                                   |
| 7    | Add collateral                | `tokenUpdateCollateral`                          |
| 8    | Mint tokens                   | `tokenMint`                                      |
| 9    | Verify                        | `tokenHolders`                                   |

***

## Stablecoin token lifecycle flow [#stablecoin-token-lifecycle-flow]

The stablecoin path has one extra control before minting: collateral must be recorded by an identity trusted for the collateral claim topic.

<Mermaid
  chart="`flowchart TB
  Init[Initialize Client<br/>initializeClient] --> Auth[Verify Auth<br/>GET /user/me]
  Auth --> Roles[Set Up System Roles<br/>+ Trusted Issuer]
  Roles --> RolesNote[Required:<br/>tokenManager<br/>claimPolicyManager]
  RolesNote --> Create[Create Stablecoin<br/>POST /token/create]
  Create --> Grant[Grant Token Roles<br/>POST /token/:address/grant-role]
  Grant --> Unpause[Unpause Token<br/>PUT /token/:address/unpause]
  Unpause --> Collateral[Add Collateral<br/>PUT /token/:address/update-collateral]
  Collateral --> CollateralNote[Required before<br/>minting stablecoins]
  CollateralNote --> Mint[Mint Stablecoins<br/>POST /token/:address/mint]
  Mint --> Verify[Verify Holders<br/>GET /token/:address/holders]
  
  style Init fill:#5fc9bf,stroke:#3a9d96,stroke-width:2px,color:#fff
  style Auth fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style Roles fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style RolesNote fill:#6ba4d4,stroke:#4a7ba8,stroke-width:2px,color:#fff
  style Create fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style Grant fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style Unpause fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style Collateral fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style CollateralNote fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style Mint fill:#8571d9,stroke:#654bad,stroke-width:2px,color:#fff
  style Verify fill:#b661d9,stroke:#8a3fb3,stroke-width:2px,color:#fff
`"
/>

Stablecoin-specific requirements:

* Trusted issuer registration: register the collateral updater as a trusted issuer for the `collateral` claim topic before adding collateral.
* Collateral update: call `tokenUpdateCollateral` before minting stablecoin supply.
* System roles: use `tokenManager` to create the token and `claimPolicyManager` to manage trusted issuer configuration.
* Token roles: use `supplyManagement` for minting and `emergency` for unpausing.
* Collateral amount: the recorded collateral must cover the minted supply under the configured collateral policy.

***

## Step-by-step commands [#step-by-step-commands]

### Step 1: initialise the client [#step-1-initialise-the-client]

Initialise the DALP SDK client with your platform URL and API key.

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L1-L23
import { createDalpClient } from "@settlemint/dalp-sdk";

async function main() {
  // Step 1: Create the SDK client
  const dalp = createDalpClient({
    url: "https://your-platform.example.com",
    apiKey: "YOUR_API_KEY",
  });
  const pincode = "YOUR_PINCODE";

  // Step 2: Get your wallet address
  const me = await dalp.user.me({});
  const myWallet = me.data.wallet;
  if (!myWallet) {
    throw new Error("No wallet found. Create a wallet first via the DALP dashboard.");
  }
  console.log("Wallet:", myWallet);

  // Step 3: Set up system roles and trusted issuer status
  // Grant yourself 'tokenManager' and 'claimPolicyManager'
  // Register as a trusted issuer for the 'collateral' claim topic

  // Step 4: Create stablecoin token
```

<details>
  <summary>
    <strong>Client helper implementation details</strong>
  </summary>

  The helper wraps common client setup:

  ```ts file=<rootDir>/src/examples/client.ts
  import { createDalpClient } from "@settlemint/dalp-sdk";

  // Create the SDK client — replace with your actual values
  const dalp = createDalpClient({
    url: "https://your-platform.example.com",
    apiKey: "sm_dalp_xxxxxxxxxxxxxxxx",
  });

  // All methods are fully typed with auto-complete
  const me = await dalp.user.me({});
  console.log("Wallet:", me.data.wallet);

  const tokens = await dalp.token.list({ query: {} });
  console.log("Tokens:", tokens.data.length);
  ```

  The helper handles:

  * `initializeClient(baseUrl, apiKey)` for one-time API authentication.
  * `toBigDecimal()` and `fromBigDecimal()` for precise numeric values.
  * SDK function re-exports so the examples can import API methods directly.

  Copy `src/examples/client.ts` into your project if you want to reuse the same helper.
</details>

***

### Step 2: check you're logged in [#step-2-check-youre-logged-in]

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L25-L32
    body: {
      type: "stablecoin",
      name: "Test USD Coin",
      symbol: "TUSD",
      decimals: 18,
      countryCode: "840",
      priceCurrency: "USD",
      basePrice: "1.00",
```

Save the returned wallet address. Later steps use it for role grants and minting.

***

### Step 3: set up system roles and trusted issuer status [#step-3-set-up-system-roles-and-trusted-issuer-status]

Complete the role and issuer setup before you create the stablecoin.

1. Grant system roles:
   * `tokenManager`, which allows the account to create tokens.
   * `claimPolicyManager`, which allows the account to manage trusted issuer configuration.

2. Register the collateral issuer:
   * Register the identity that updates collateral as a trusted issuer for the `collateral` claim topic.

Only an account with the `admin` role can grant system roles. If your API key does not belong to an administrator, ask an administrator to grant the roles and register the trusted issuer before continuing.

***

### Step 4: create a stablecoin token [#step-4-create-a-stablecoin-token]

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L40-L57

  if ("transactionId" in stablecoin) {
    console.log("Stablecoin creation queued:", stablecoin.transactionId);
    return;
  }
  const tokenAddress = stablecoin.data.id;
  console.log("Stablecoin created:", tokenAddress);

  // Step 5: Grant token roles
  await dalp.token.grantRole({
    params: { tokenAddress },
    body: {
      accounts: [myWallet],
      role: "supplyManagement",
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
```

Parameters:

* `type`: set this to `"stablecoin"`.
* `name`: the token name, such as `"Test USD Coin"`.
* `symbol`: the token symbol, such as `"TUSD"`.
* `decimals`: the precision for token amounts. The example script uses `18`. Use the decimal precision configured for your programme.
* `countryCode`: ISO country code, such as `840` for the United States, `056` for Belgium, or `276` for Germany.
* `priceCurrency`: ISO currency code for liability tracking, such as `"USD"`, `"EUR"`, or `"GBP"`.
* `basePrice`: the peg value for the token, such as `"1.00"`.
* `initialModulePairs`: compliance modules. The example uses `[]` for a basic setup.

The response returns token data with `id`, which is the contract address. Save it for the token role, collateral, mint, and holder calls.

***

### Step 5: grant token roles [#step-5-grant-token-roles]

Grant `supplyManagement` for minting and `emergency` for unpausing on the stablecoin contract.

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L69-L81
    },
  });
  console.log("Roles granted");

  // Step 6: Unpause the stablecoin
  await dalp.token.unpause({
    params: { tokenAddress },
    body: {
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
```

***

### Step 6: unpause the token [#step-6-unpause-the-token]

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L83-L94
  console.log("Stablecoin unpaused");

  // Step 7: Add collateral (Required for stablecoins)
  const expiryDate = new Date();
  expiryDate.setFullYear(expiryDate.getFullYear() + 1);

  await dalp.token.updateCollateral({
    params: { tokenAddress },
    body: {
      amount: 1_000_000_000_000_000_000_000_000n,
      expiryTimestamp: expiryDate.toISOString(),
      walletVerification: {
```

***

### Step 7: add collateral (required for stablecoins) [#step-7-add-collateral-required-for-stablecoins]

Stablecoin minting requires collateral first. The account that updates collateral must already be trusted for the collateral claim topic.

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L96-L112
        verificationType: "PINCODE",
      },
    },
  });
  console.log("Collateral added");

  // Step 8: Mint stablecoins — 1000 TUSD
  await dalp.token.mint({
    params: { tokenAddress },
    body: {
      recipients: [myWallet],
      amounts: [1_000_000_000_000_000_000_000n],
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
```

Parameters:

* `amount`: collateral amount in the token's smallest unit. Match this to the token decimals you configured.
* `expiryTimestamp`: ISO 8601 timestamp for when the collateral claim expires.

The call returns token data with updated collateral. If DALP reports that the caller is not a trusted issuer, complete the trusted issuer setup for the `collateral` claim topic before retrying.

***

### Step 8: mint stablecoins [#step-8-mint-stablecoins]

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L114-L129
  console.log("Minted stablecoins");

  // Step 9: Verify holders
  const holders = await dalp.token.holders({ params: { tokenAddress }, query: { limit: 200 } });
  console.log("Holders:", holders.data);
}

await main();

```

Parameters:

* `contract`: the stablecoin contract address.
* `recipients`: recipient wallet addresses.
* `amounts`: amounts in the token's smallest unit. For the 18-decimal example script, `1_000_000_000_000_000_000_000n` represents 1,000 tokens.

The call returns token data with updated `totalSupply`.

***

### Step 9: verify the mint [#step-9-verify-the-mint]

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts#L131-L136
```

The holder query returns wallets and balances for the token.

***

## Full script [#full-script]

Replace `YOUR_PLATFORM_URL`, `YOUR_API_KEY`, and `YOUR_PINCODE` in the complete script before you run it.

Important:

* Step 3 in the script is a placeholder because role and trusted issuer setup is an administrative action.
* Complete the `tokenManager`, `claimPolicyManager`, and collateral trusted issuer setup before you continue.
* If you do not have admin access, ask an administrator to complete those setup steps.

```ts file=<rootDir>/src/examples/create-mint-stablecoin.ts
import { createDalpClient } from "@settlemint/dalp-sdk";

async function main() {
  // Step 1: Create the SDK client
  const dalp = createDalpClient({
    url: "https://your-platform.example.com",
    apiKey: "YOUR_API_KEY",
  });
  const pincode = "YOUR_PINCODE";

  // Step 2: Get your wallet address
  const me = await dalp.user.me({});
  const myWallet = me.data.wallet;
  if (!myWallet) {
    throw new Error("No wallet found. Create a wallet first via the DALP dashboard.");
  }
  console.log("Wallet:", myWallet);

  // Step 3: Set up system roles and trusted issuer status
  // Grant yourself 'tokenManager' and 'claimPolicyManager'
  // Register as a trusted issuer for the 'collateral' claim topic

  // Step 4: Create stablecoin token
  const stablecoin = await dalp.token.create({
    body: {
      type: "stablecoin",
      name: "Test USD Coin",
      symbol: "TUSD",
      decimals: 18,
      countryCode: "840",
      priceCurrency: "USD",
      basePrice: "1.00",
      initialModulePairs: [],
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });

  if ("transactionId" in stablecoin) {
    console.log("Stablecoin creation queued:", stablecoin.transactionId);
    return;
  }
  const tokenAddress = stablecoin.data.id;
  console.log("Stablecoin created:", tokenAddress);

  // Step 5: Grant token roles
  await dalp.token.grantRole({
    params: { tokenAddress },
    body: {
      accounts: [myWallet],
      role: "supplyManagement",
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });
  await dalp.token.grantRole({
    params: { tokenAddress },
    body: {
      accounts: [myWallet],
      role: "emergency",
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });
  console.log("Roles granted");

  // Step 6: Unpause the stablecoin
  await dalp.token.unpause({
    params: { tokenAddress },
    body: {
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });
  console.log("Stablecoin unpaused");

  // Step 7: Add collateral (Required for stablecoins)
  const expiryDate = new Date();
  expiryDate.setFullYear(expiryDate.getFullYear() + 1);

  await dalp.token.updateCollateral({
    params: { tokenAddress },
    body: {
      amount: 1_000_000_000_000_000_000_000_000n,
      expiryTimestamp: expiryDate.toISOString(),
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });
  console.log("Collateral added");

  // Step 8: Mint stablecoins — 1000 TUSD
  await dalp.token.mint({
    params: { tokenAddress },
    body: {
      recipients: [myWallet],
      amounts: [1_000_000_000_000_000_000_000n],
      walletVerification: {
        secretVerificationCode: pincode,
        verificationType: "PINCODE",
      },
    },
  });
  console.log("Minted stablecoins");

  // Step 9: Verify holders
  const holders = await dalp.token.holders({ params: { tokenAddress }, query: { limit: 200 } });
  console.log("Holders:", holders.data);
}

await main();
```

***

## Common country codes [#common-country-codes]

* 840 = USA
* 056 = Belgium
* 276 = Germany
* 826 = UK
* 392 = Japan

***

## Amount calculations [#amount-calculations]

DALP expects mint and collateral amounts in the token's smallest unit. Use:

```text
token amount * 10^decimals
```

For a 6-decimal token:

* 1 token = `1 * 10^6` = `1000000`
* 1,000 tokens = `1000 * 10^6` = `1000000000`

For the 18-decimal token in the example script:

* 1 token = `1 * 10^18` = `1000000000000000000`
* 1,000 tokens = `1000 * 10^18` = `1000000000000000000000`

***

![Stablecoin listing with collateral information](/docs/screenshots/stablecoins/stablecoins.webp)

## Troubleshooting [#troubleshooting]

`"Authentication missing"`: check the API key passed to `initializeClient`.

`"PINCODE_INVALID"`: reconfirm the PIN from **Account → Wallet** (`/account/wallet`).

`"USER_NOT_AUTHORIZED"` or `"tokenManager required"`: grant the `tokenManager` role. This requires admin access.

`"Permission denied"`: grant the required token roles, such as `supplyManagement` or `emergency`.

`"Token is paused"`: make sure Step 6 succeeded and the caller has the `emergency` role.

`"InsufficientCollateral"`: make sure Step 7 succeeded and the collateral amount covers the mint amount under the configured policy.

`"You are not a trusted issuer for topic(s): collateral"`: register the collateral updater as a trusted issuer for the collateral claim topic.

`"RecipientNotVerified"`: the recipient wallet needs an identity before it can receive tokens. Register the identity with `systemIdentityCreate`.

`jq` is optional for local scripting. Install it with `brew install jq` on macOS or `apt install jq` on Linux if you want to parse JSON responses in shell commands.

## Related [#related]

* [Stablecoin use case](/docs/executive-overview/use-cases/stablecoins)
* [Collateral compliance controls](/docs/developer-guides/compliance/collateral)
* [Configure trusted issuers](/docs/developer-guides/compliance/configure-trusted-issuers)
* [Mint assets](/docs/developer-guides/asset-servicing/mint-assets)