Smart identity verification

This guide explains how to configure the identity verification compliance module when creating an asset via API. This module ensures both sender and recipient wallets have verified OnchainID claims before any transfer can occur.

For the web interface approach, see the compliance overview.

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)
• Token factory for your desired asset type must be deployed
• Wallet verification method enabled on your account (pincode or 2FA)

How identity verification works

When you enable the identity verification compliance module on an asset, the blockchain validates every transfer by checking:

1. Sender verification - The sending wallet must have an OnchainID with the required claim(s)
2. Recipient verification - The receiving wallet must have an OnchainID with the required claim(s)
3. Trusted issuer - The claim must be issued by an issuer in the asset's trusted issuer registry

If any check fails, the transfer is rejected on-chain.

Configuration parameters

When configuring the identity verification module during asset creation, you set these parameters:

Expression nodes

The values array contains expression nodes that define which claims are required. Each node has two fields:

Configuring identity verification during asset creation

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

{
  "complianceModuleRegistry": {
    "complianceModules": [
      {
        "typeId": "identity-verification",
        "module": "0x7a2088a1bFc9d81c55368AE168C2C02570cB814F",
        "name": "SMART Identity Verification Module"
      }
      // ... other modules
    ]
  }
}

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": "KYC Protected Equity",
    "symbol": "KYCE",
    "decimals": 18,
    "countryCode": 840,
    "priceCurrency": "USD",
    "basePrice": "100",
    "initialModulePairs": [
      {
        "typeId": "identity-verification",
        "module": "0x7a2088a1bFc9d81c55368AE168C2C02570cB814F",
        "values": [
          {
            "nodeType": 0,
            "value": "26984799302505749158794800959285050858086405868089409909048783980951278841746"
          }
        ]
      }
    ],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE",
      "verificationType": "PINCODE"
    }
  }'

{
  "id": "0x1234567890AbCdEf1234567890AbCdEf12345678",
  "type": "equity",
  "createdAt": "2025-01-15T10:30:00.000Z",
  "name": "KYC Protected Equity",
  "symbol": "KYCE",
  "decimals": 18,
  "basePrice": "[\"100\",0]",
  "basePriceCurrencyCode": "USD",
  "totalSupply": "[\"0\",0]",
  "pausable": {
    "paused": true
  }
}

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

{
  "id": "0x1234567890AbCdEf1234567890AbCdEf12345678",
  "type": "equity",
  "name": "KYC Protected Equity",
  "symbol": "KYCE",
  "complianceModuleConfigs": [
    {
      "complianceModule": {
        "typeId": "identity-verification",
        "module": "0x7a2088a1bFc9d81c55368AE168C2C02570cB814F"
      }
    }
  ]
}

Expression examples

Single requirement (KYC only)

Require only the knowYourCustomer claim:

{
  "values": [
    {
      "nodeType": 0,
      "value": "26984799302505749158794800959285050858086405868089409909048783980951278841746"
    }
  ]
}

Combined requirements (KYC AND AML)

Require both knowYourCustomer AND antiMoneyLaundering claims:

{
  "values": [
    {
      "nodeType": 0,
      "value": "26984799302505749158794800959285050858086405868089409909048783980951278841746"
    },
    {
      "nodeType": 0,
      "value": "66602700950116947137359654609674923607788815289970476259958745144319039408766"
    },
    { "nodeType": 1, "value": "0" }
  ]
}

Alternative requirements (KYC OR accreditedInvestor)

Require either knowYourCustomer OR accreditedInvestor claim:

{
  "values": [
    {
      "nodeType": 0,
      "value": "26984799302505749158794800959285050858086405868089409909048783980951278841746"
    },
    {
      "nodeType": 0,
      "value": "15733030998618876990024220391915773205162379317494393310546829862321881862123"
    },
    { "nodeType": 2, "value": "0" }
  ]
}

Complex expression with grouping

Require (KYC AND AML) OR qualifiedInstitutionalInvestor:

{
  "values": [
    "(",
    {
      "nodeType": 0,
      "value": "26984799302505749158794800959285050858086405868089409909048783980951278841746"
    },
    {
      "nodeType": 0,
      "value": "66602700950116947137359654609674923607788815289970476259958745144319039408766"
    },
    { "nodeType": 1, "value": "0" },
    ")",
    {
      "nodeType": 0,
      "value": "39526553109170329799339511574661256630735485618560740361645615581310848276505"
    },
    { "nodeType": 2, "value": "0" }
  ]
}

Request parameters

Identity verification module configuration

Wallet verification object

Best practices

Claim selection

• Start with knowYourCustomer for basic regulatory compliance
• Add antiMoneyLaundering for enhanced due diligence requirements
• Use accreditedInvestor or qualifiedInstitutionalInvestor for securities with investor restrictions
• Combine claims with AND for stricter requirements, OR for flexibility

Expression design

• Keep expressions simple when possible - a single topic is often sufficient
• Test complex expressions thoroughly before deploying to production
• Document your expression logic for compliance audits
• Consider using OR with accreditation claims to support different investor types

Trusted issuers

• Ensure claim issuers are registered in the trusted issuer registry
• Verify issuer credentials before adding them to the registry
• Regularly audit trusted issuer permissions

Troubleshooting

Related guides

• Verify KYC - Issue KYC verifications to users
• Configure Trusted Issuers - Set up issuer permissions