# Collateral requirement

Source: https://docs.settlemint.com/docs/developer-guides/compliance/collateral
Configure collateral ratios, issue collateral claims, and read collateral ratio stats via API.
The collateral compliance module uses trusted identity claims to gate minting.




The collateral compliance module uses trusted identity claims to check whether a token can mint more units. It does not prove that an off-chain bank account, custodian, or warehouse holds the reserve.

Your issuer and operating process must verify the reserve first. DALP can then enforce the issued collateral claim during minting.

Use this guide to configure the module through the API, issue the claim to the token identity, and read collateral ratio stats before minting. For the web interface approach, see the [user guide](/docs/user-guides/compliance/collateral).

## How collateral validation works [#how-collateral-validation-works]

When minting new units of an asset with the collateral module enabled, the system:

1. Checks if the asset's identity has a valid collateral claim
2. Verifies the claim was issued by an authorized issuer and is not expired
3. Confirms the collateral amount meets or exceeds the configured ratio based on post-mint total supply

This module only applies to **minting operations**. Regular transfers between wallets are not affected by collateral requirements.

<Callout type="warning" title="Collateral claims are attestations">
  A collateral claim records a trusted issuer's attestation about backing for the token. DALP validates the claim topic,
  issuer trust, expiry, and amount during minting. It does not independently inspect the underlying reserve account,
  custodian statement, warehouse record, or other off-chain proof.
</Callout>

## Configuration parameters [#configuration-parameters]

When configuring the collateral module during asset creation, three parameters are required:

| Parameter          | Type      | Description                                           | Valid values             |
| ------------------ | --------- | ----------------------------------------------------- | ------------------------ |
| **proofTopic**     | BigInt    | ERC-735 claim topic ID for collateral proofs          | System-provided topic ID |
| **ratioBps**       | number    | Required backing ratio in basis points (10000 = 100%) | 0 to 20000               |
| **trustedIssuers** | string\[] | Additional trusted issuers for the proof topic        | Ethereum addresses       |

<Callout type="info" title="Understanding collateral ratios">
  The collateral ratio is specified in basis points (1/100th of a percent): -
  **10000** = 100% backing (1,000 minted units require 1,000 collateral) -
  **15000** = 150% over-collateralized (1,000 minted units require 1,500
  collateral) - **20000** = 200% maximum ratio (1,000 minted units require 2,000
  collateral)

  See [Example scenario](#example-scenario) for a minting simulation.
</Callout>

## Configure collateral during asset creation [#configure-collateral-during-asset-creation]

### Prerequisites [#prerequisites]

* Platform URL (e.g., `https://your-platform.example.com`)
* API key from a user with the **Token Manager** role (see [Getting Started](/docs/developer-guides/api-integration/getting-started) for API key setup)
* Wallet verification method enabled on your account (e.g., pincode or 2FA)

![Supply cap and collateral requirement configuration](/docs/screenshots/asset-designer/asset-designer-supply-limit.webp)

<Steps>
  <Step>
    ### Get collateral module address [#get-collateral-module-address]

    Query the system to get the registered collateral compliance module address:

    ```bash
    curl -X GET "https://your-platform.example.com/api/system/default" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    **Response:**

    ```json
    {
      "complianceModuleRegistry": {
        "complianceModules": [
          {
            "typeId": "collateral",
            "module": "0x5FC8d32690cc91D4c39d9d3abcBD16989F875707",
            "name": "Collateral Compliance Module"
          }
          // ... other modules
        ]
      }
    }
    ```

    Save the `module` address for the `typeId: "collateral"` entry.
  </Step>

  <Step>
    ### Get collateral topic ID [#get-collateral-topic-id]

    Query the registered claim topics to find the collateral topic ID:

    ```bash
    curl -X GET "https://your-platform.example.com/api/system/claim-topics" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    **Response:**

    ```json
    [
      {
        "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
        "topicId": "56591694316807385155654796962642700009023257328234168678289712861780104020528",
        "name": "collateral",
        "signature": "uint256 amount, uint256 expiryTimestamp",
        "registry": {
          "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7"
        }
      }
      // ... other topics
    ]
    ```

    Save the `topicId` value for the topic with `name: "collateral"`.
  </Step>

  <Step>
    ### Create asset with collateral module [#create-asset-with-collateral-module]

    Include the collateral module in the `initialModulePairs` array when creating the asset:

    ```bash
    curl -X POST "https://your-platform.example.com/api/token/create" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "type": "equity",
        "name": "Collateralized Equity",
        "symbol": "COLEQ",
        "decimals": 18,
        "countryCode": "840",
        "priceCurrency": "USD",
        "basePrice": "100",
        "initialModulePairs": [
          {
            "typeId": "collateral",
            "module": "0x5FC8d32690cc91D4c39d9d3abcBD16989F875707",
            "values": {
              "proofTopic": "56591694316807385155654796962642700009023257328234168678289712861780104020528",
              "ratioBps": 10000,
              "trustedIssuers": []
            }
          }
        ],
        "walletVerification": {
          "secretVerificationCode": "YOUR_PINCODE",
          "verificationType": "PINCODE"
        }
      }'
    ```

    **Response:**

    ```json
    {
      "id": "0x1234567890AbCdEf1234567890AbCdEf12345678",
      "txHash": "0x8d95bfd5381478d90992d3e2e64c73178e46bb18592bfcbffdf899f2407aee9b"
    }
    ```

    **Key fields in `initialModulePairs`:**

    | Field                   | Description                                                                     |
    | ----------------------- | ------------------------------------------------------------------------------- |
    | `typeId`                | Must be `"collateral"` for the collateral module                                |
    | `module`                | The collateral module address from step 1                                       |
    | `values.proofTopic`     | The collateral topic ID from step 2                                             |
    | `values.ratioBps`       | Collateral ratio (10000 = 100%, 15000 = 150%)                                   |
    | `values.trustedIssuers` | Additional issuers recognized alongside the global registry (not a replacement) |
  </Step>

  <Step>
    ### Verify module configuration [#verify-module-configuration]

    Query the asset to confirm the collateral module is configured:

    ```bash
    curl -X GET "https://your-platform.example.com/api/token/0x1234567890AbCdEf1234567890AbCdEf12345678" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    Check that `complianceModuleConfigs` contains an entry with `typeId: "collateral"`.
  </Step>
</Steps>

## Issue a collateral claim [#issue-a-collateral-claim]

After the asset is deployed with the collateral module, a collateral claim must be issued to the asset's identity before minting can occur.

### Prerequisites [#prerequisites-1]

Collateral claims must be issued by a **Trusted issuer** for the collateral topic (see [Configure trusted issuers](/docs/developer-guides/compliance/configure-trusted-issuers))

<Callout type="info" title="Who should issue collateral claims?">
  Most teams delegate collateral attestations to compliance or treasury officers who operate as trusted issuers. Assign
  the `claimIssuer` role to those identities and register them for the collateral topic so they can service multiple
  assets.
</Callout>

### Claim fields [#claim-fields]

| Field               | Description                                    | Format                 |
| ------------------- | ---------------------------------------------- | ---------------------- |
| **amount**          | The collateral value backing the asset         | String (in base units) |
| **expiryTimestamp** | When the claim expires (must be in the future) | ISO 8601 date-time     |

<Steps>
  <Step>
    ### Issue the collateral claim [#issue-the-collateral-claim]

    The collateral amount must be specified in base units (the smallest unit of the asset). For an asset with 18 decimals, multiply the desired amount by 10^18. For example, to back 100,000 units on an 18-decimal asset, use `"100000000000000000000000"` (100,000 × 10^18).

    You issue collateral claims to the token's OnchainID identity using the system endpoint. You can obtain the `targetIdentityAddress` from the token creation response (`identity.id`) or by calling `GET /token/{address}`.

    <Callout type="info" title="Use the identity contract address">
      Collateral claims are issued to the token's identity contract, not the token address or an operator wallet. Always
      pass the `identity.id` value as `targetIdentityAddress`.
    </Callout>

    ```bash
    curl -X POST "https://your-platform.example.com/api/system/identity/claim/issue" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "targetIdentityAddress": "0x20ADDd5023c494eA1594282ab6E94fA5A658C4f2",
        "claim": {
          "topic": "collateral",
          "data": {
            "amount": "100000000000000000000000",
            "expiryTimestamp": "2025-12-31T23:59:59Z"
          }
        },
        "walletVerification": {
          "secretVerificationCode": "YOUR_PINCODE",
          "verificationType": "PINCODE"
        }
      }'
    ```

    **Response:**

    ```json
    {
      "txHash": "0x9f85bfd5381478d90992d3e2e64c73178e46bb18592bfcbffdf899f2407aee9b",
      "success": true,
      "claimTopic": "collateral",
      "targetIdentity": "0x20ADDd5023c494eA1594282ab6E94fA5A658C4f2"
    }
    ```

    <Callout type="info" title="Amount formatting">
      Asset amounts depend on the asset's decimal configuration. See [Asset
      Decimals](/docs/developer-guides/api-integration/asset-decimals) for formatting guidance.
    </Callout>

    With this collateral claim of 100,000 units and the 100% ratio configured above, you can mint up to 100,000 tokens. The [example scenario](#example-scenario) shows the minting calculation.
  </Step>

  <Step>
    ### Verify the claim [#verify-the-claim]

    Query the asset to confirm the collateral claim was issued:

    ```bash
    curl -X GET "https://your-platform.example.com/api/token/0x1234567890AbCdEf1234567890AbCdEf12345678" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    **Response (relevant fields):**

    ```json
    {
      "id": "0x1234567890AbCdEf1234567890AbCdEf12345678",
      "type": "equity",
      "name": "Collateralized Equity",
      "symbol": "COLEQ",
      "identity": {
        "id": "0x20ADDd5023c494eA1594282ab6E94fA5A658C4f2",
        "claims": [
          {
            "name": "collateral",
            "revoked": false,
            "values": [
              { "key": "amount", "value": "100000000000000000000000" },
              { "key": "expiryTimestamp", "value": "1767225599" }
            ],
            "isTrusted": false
          }
        ]
      },
      "complianceModuleConfigs": [
        {
          "complianceModule": {
            "typeId": "collateral"
          }
        }
      ]
    }
    ```

    **Key fields to verify:**

    * `identity.claims` contains the collateral claim with amount and expiry
    * `identity.claims[].revoked` is `false` (claim is active)
  </Step>
</Steps>

<Callout type="warning" title="Plan for renewal">
  Collateral claims have an expiry date. Renew claims before they expire to avoid blocking future minting operations.
</Callout>

## Example scenario [#example-scenario]

Using the configuration from this guide, a company issues equity shares with 100% collateral backing.

### Configuration [#configuration]

* **Collateral ratio:** 100% (10000 basis points)
* **Proof topic:** System default (collateral)
* **Trusted issuers:** Empty (using global registry)

### Collateral claim [#collateral-claim]

* **Amount:** 100,000 units
* **Expiry:** December 31, 2025

### Minting simulation [#minting-simulation]

| Operation    | Current supply | Mint amount | Post-mint supply | Required collateral (100%) | Available | Result    |
| ------------ | -------------- | ----------- | ---------------- | -------------------------- | --------- | --------- |
| Initial mint | 0              | 50,000      | 50,000           | 50,000                     | 100,000   | ✅ Allowed |
| Second mint  | 50,000         | 50,000      | 100,000          | 100,000                    | 100,000   | ✅ Allowed |
| Third mint   | 100,000        | 10,000      | 110,000          | 110,000                    | 100,000   | ❌ Blocked |

### Why the third mint fails [#why-the-third-mint-fails]

The third mint is blocked because:

* Post-mint supply would be 110,000 units
* At 100% ratio, required collateral = 110,000
* Current collateral claim only covers 100,000
* A new collateral claim with a higher amount is needed

### To unblock [#to-unblock]

1. Issue a new collateral claim with amount ≥ 110,000 (see [Issue a collateral claim](#issue-a-collateral-claim))
2. Retry the minting operation

## Read collateral ratio stats [#read-collateral-ratio-stats]

After the module and claim are in place, use the collateral ratio stats endpoint to check the indexed view before you mint.

```bash
curl -X GET "https://your-platform.example.com/api/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf12345678/stats/collateral-ratio" \
  -H "X-Api-Key: YOUR_API_KEY"
```

**Response (relevant fields):**

```json
{
  "data": {
    "buckets": [
      { "name": "collateralAvailable", "value": "50000.000000000000000000" },
      { "name": "collateralUsed", "value": "50000.000000000000000000" }
    ],
    "totalCollateral": "100000.000000000000000000",
    "requiredCollateral": "50000.000000000000000000",
    "mintableSupply": "100000.000000000000000000",
    "collateralizationPercentage": 200,
    "configuredCollateralRatioBps": 10000,
    "utilizationPercentage": 50,
    "parity_confidence": "high"
  }
}
```

| Field                         | Meaning                                                                                                                     |
| ----------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `totalCollateral`             | Decimal string for the collateral amount from the active trusted claim used by the indexer                                  |
| `requiredCollateral`          | Decimal string for the collateral required for the current supply and configured ratio                                      |
| `mintableSupply`              | Decimal string for the maximum token supply supported by the current collateral claim and ratio                             |
| `collateralizationPercentage` | `totalCollateral / requiredCollateral * 100`; values above 100 are over-collateralized                                      |
| `utilizationPercentage`       | `requiredCollateral / totalCollateral * 100`; values above 100 indicate under-collateralization                             |
| `parity_confidence`           | `high` when indexed stats match the expected claim data; `degraded` when the indexer saw malformed or incomplete claim data |

Treat `parity_confidence: "degraded"` as an operations signal. Re-check the token identity claim and issuer setup before relying on the stats for a minting decision.

## Request parameters [#request-parameters]

### Collateral module configuration [#collateral-module-configuration]

| Parameter               | Type      | Required | Description                                                                     |
| ----------------------- | --------- | -------- | ------------------------------------------------------------------------------- |
| `typeId`                | string    | Yes      | Must be `"collateral"`                                                          |
| `module`                | string    | Yes      | Collateral module contract address (from system query)                          |
| `values.proofTopic`     | string    | Yes      | ERC-735 claim topic ID (from claim topics query)                                |
| `values.ratioBps`       | number    | Yes      | Collateral ratio in basis points (0-20000)                                      |
| `values.trustedIssuers` | string\[] | No       | Additional issuers recognized alongside the global registry (not a replacement) |

### Collateral claim issuance [#collateral-claim-issuance]

| Parameter                    | Type   | Required | Description                                             |
| ---------------------------- | ------ | -------- | ------------------------------------------------------- |
| `targetIdentityAddress`      | string | Yes      | Token identity address receiving the claim              |
| `claim.topic`                | string | Yes      | Must be `"collateral"`                                  |
| `claim.data.amount`          | string | Yes      | Collateral amount as string (in base units)             |
| `claim.data.expiryTimestamp` | string | Yes      | Claim expiry in ISO 8601 format (must be in the future) |
| `walletVerification`         | object | Yes      | Wallet verification (pincode or TOTP)                   |

### Wallet verification object [#wallet-verification-object]

| Field                    | Type   | Description                                         |
| ------------------------ | ------ | --------------------------------------------------- |
| `secretVerificationCode` | string | 6-digit pincode or TOTP code                        |
| `verificationType`       | string | `"PINCODE"` (default), `"SECRET_CODES"`, or `"OTP"` |

## Best practices [#best-practices]

### Collateral ratio planning [#collateral-ratio-planning]

* Start with 100% (10000 basis points) when each minted unit must have one unit of attested collateral backing
* Use 150% (15000 basis points) or higher when your policy requires over-collateralization
* Keep the reserve verification workflow outside DALP explicit: who checks the source record, who can issue the claim, and how renewal evidence is retained
* Check `parity_confidence` and collateral utilization before large minting operations

### Claim renewal [#claim-renewal]

To renew a collateral claim, issue a new claim using the steps in [Issue a collateral claim](#issue-a-collateral-claim) with an updated `expiryTimestamp` set to a future date.

* Monitor collateral claim expiry dates and renew before they expire
* Set calendar reminders or automated alerts for upcoming expirations
* Allow buffer time for renewal to avoid blocking minting operations

### Trusted issuers [#trusted-issuers]

* Leave `trustedIssuers` empty to rely solely on the global registry
* Adding addresses to `trustedIssuers` extends the global registry. It does not replace it
* Use this array for issuers not registered globally but authorized for this specific asset
* Verify issuer addresses carefully before adding them

## Troubleshooting [#troubleshooting]

| Issue                             | Solution                                                                                                                                  |
| --------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                | API key is invalid, expired, or disabled                                                                                                  |
| `403 USER_NOT_AUTHORIZED`         | Ensure the caller has the required role: `tokenManager` for asset creation, or `claimIssuer` and trusted issuer status for claim issuance |
| `Collateral module not found`     | Query `/system/default` to get the correct module address                                                                                 |
| `Invalid topic ID`                | Query `/system/claim-topics` to get the correct collateral topic ID                                                                       |
| `Insufficient collateral`         | Issue a collateral claim with sufficient amount before minting                                                                            |
| `Collateral verification expired` | Issue a new collateral claim with a future expiry date                                                                                    |
| `ratioBps out of range`           | Value must be between 0 and 20000                                                                                                         |

## Related guides [#related-guides]

* [Configure Trusted Issuers](/docs/developer-guides/compliance/configure-trusted-issuers) - Set up issuer permissions
* [Asset Decimals](/docs/developer-guides/api-integration/asset-decimals) - Format large token and collateral amounts
* [Mint Assets](/docs/developer-guides/asset-servicing/mint-assets) - Mint tokens after configuring collateral