Collateral requirement

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.

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.

Configuration parameters

Asset creation requires three parameters for the collateral compliance module:

Configure collateral during asset creation

Prerequisites

• Platform URL (e.g., https://your-platform.example.com)
• API key from a user with the Token Manager role (see Getting Started for API key setup)
• Wallet verification method enabled on your account (e.g., pincode or 2FA)

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

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

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

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

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

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

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

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 for document types and visibility.

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

A trusted issuer for the collateral topic must issue collateral claims (see Configure trusted issuers)

Claim fields

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

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

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

{
  "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"
      }
    }
  ]
}

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

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

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

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.

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):

{
  "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"
  }
}

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

Collateral module configuration

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

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.

Wallet verification object

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

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

Related guides

• Configure trusted issuers - Set up issuer permissions
• Asset decimals - Format large token and collateral amounts
• Mint assets - Mint tokens after configuring collateral
• Token documents - Attach backing evidence and set document visibility