# Collateral requirement

Source: https://docs.settlemint.com/docs/developers/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. DALP gates each mint against a collateral claim issued to the token identity. The module does not prove that an off-chain bank account, custodian, or warehouse holds the reserve; your issuer and operating process must verify that first.

Configure the module through the API, then read collateral ratio stats before you mint. DALP enforces the attestation at mint time. For the web interface instead, see the [user guide](/docs/operators/compliance/collateral).

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

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

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

This module applies only to minting operations. Regular transfers between wallets are not subject to 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. The reserve account, custodian statement, warehouse record,
  and other off-chain proof remain outside DALP's scope.
</Callout>

## Configuration parameters [#configuration-parameters]

Asset creation requires three parameters for the collateral compliance module:

| 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">
  Specify the collateral ratio in basis points. A value of `10000` means 100% backing: 1,000
  minted units require 1,000 collateral. A value of `15000` means 150% backing: 1,000 minted
  units require 1,500 collateral. The maximum accepted ratio is `20000`, or 200% backing.
  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/api-reference/reference/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 for the registered collateral compliance module address. The platform returns a `complianceModuleRegistry` object. Save the `module` value from the entry where `typeId` is `"collateral"` and use it in the next step.

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

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

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

    Query the registered claim topics. Locate the entry where `name` is `"collateral"` and save its `topicId`. You will pass this value as `values.proofTopic` when creating the asset. The platform returns the full topic list:

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

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

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

    Include the collateral module in the `initialModulePairs` array when creating the asset. Use the module address and topic ID from the previous steps. The `ratioBps` value below sets a 100% backing requirement.

    ```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"
        }
      }'
    ```

    The platform returns the new asset address and transaction hash. Save `id` for subsequent calls:

    ```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 and confirm that `complianceModuleConfigs` contains an entry with `typeId: "collateral"`. A missing entry means the module was not attached during creation.

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

## Verify backing before issuing the claim [#verify-backing-before-issuing-the-claim]

The collateral claim is the on-chain attestation DALP checks during minting. Issue it only after your issuer or its appointed verifier has checked the external reserve evidence for the asset programme.

Keep the evidence process outside the claim itself. Before writing the claim, verify bank, custodian, warehouse, or trustee records and record the amount and expiry to attest. Attach supporting documents to the token record when your operating model requires an audit trail. Renew or replace the claim before expiry if minting must continue.

The token document surface supports asset-specific evidence types. For reserve or physical-asset backing, use the type that matches the asset profile. A stablecoin uses a reserve audit. A precious metal asset uses an assay certificate, storage receipt, or chain-of-custody document. See [Token documents](/docs/api-reference/tokens/token-documents) for document types and visibility.

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

Once the asset deploys with the collateral module, a trusted issuer must issue a collateral claim to the asset's identity before minting can occur.

### Prerequisites [#prerequisites-1]

A trusted issuer for the collateral topic must issue collateral claims (see [Configure trusted issuers](/docs/developers/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]

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

    Issue collateral claims to the token's OnchainID identity using the system endpoint. 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">
      The platform issues collateral claims 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"
        }
      }'
    ```

    The platform returns:

    ```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/api-reference/reference/asset-decimals) for formatting guidance.
    </Callout>

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

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

    Query the asset to confirm the trusted issuer wrote the claim. Check that `identity.claims` contains the attestation and `revoked` is `false`:

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

    Relevant response fields (check `identity.claims` for the attestation and confirm `revoked` is `false`):

    ```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` must contain the collateral claim with amount and expiry, and `identity.claims[].revoked` must be `false`.
  </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]

A company issues equity shares with 100% collateral backing, using the configuration from this guide. The module is configured with a 100% ratio (10000 basis points), the system default collateral proof topic, and no additional trusted issuers. The collateral claim covers 100,000 units and expires 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 platform blocks the third mint because:

* Post-mint supply would be 110,000 units
* At 100% ratio, required collateral = 110,000
* The current claim covers only 100,000
* The issuer must write a new claim with a higher amount

### 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]

With the module and claim in place, use the collateral ratio stats endpoint to check the indexed view before you mint. This gives you a live snapshot of collateral availability without waiting for a mint attempt to fail.

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

Relevant response fields (all amounts are decimal strings, collateral figures are in the same units as the token):

```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 you rely on the stats for a minting decision.

## Request parameters [#request-parameters]

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

Pass these fields in the `initialModulePairs` array when creating the asset. All three are required unless noted otherwise.

| 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]

Pass these fields to `POST /api/system/identity/claim/issue` to write a collateral claim. The caller must hold the `claimIssuer` role and be registered as a trusted issuer for the collateral topic.

| 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]

The `walletVerification` object identifies the caller's wallet when submitting on-chain transactions. Pass the method your account has configured.

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

## Best practices [#best-practices]

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. Document clearly 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.

Plan for claim expiry from the start. To renew, 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 expiry dates and renew before they lapse so minting is not blocked. Set calendar reminders or automated alerts for upcoming expirations, and allow buffer time for the renewal transaction to confirm.

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 authorized for a specific asset but not registered globally, and 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/developers/compliance/configure-trusted-issuers) - Set up issuer permissions
* [Asset decimals](/docs/api-reference/reference/asset-decimals) - Format large token and collateral amounts
* [Mint assets](/docs/developers/asset-servicing/mint-assets) - Mint tokens after configuring collateral
* [Token documents](/docs/api-reference/tokens/token-documents) - Attach backing evidence and set document visibility