Identity verification

The identity verification compliance module requires OnchainID claim topics before regulated asset operations can complete. Pass the module address and a postfix claim expression in initialModulePairs during asset creation.

For the full module reference, including the runtime flow, trusted issuer path, failure modes, and expression semantics, see Identity Verification reference. For the underlying wallet, OnchainID, claim-topic, and trusted issuer model, see Claims and identity. For the web interface approach, see the compliance overview.

Prerequisites

You need a Platform URL (for example https://your-platform.example.com) and an API key from a user with the Token Manager role. See Getting Started for API key setup.

You also need a token factory for your desired asset type deployed to the network, and a wallet verification method enabled on your account (pincode or 2FA).

How identity verification works

Integrators and auditors both need to understand this gate. When you add this module, the blockchain validates every transfer by checking the recipient's OnchainID claims against the token's configured postfix expression. A claim counts only when the topic exists, the recipient wallet resolves to an accepted identity, the wallet is not marked as lost, and a trusted issuer validates the claim signature and data.

1. Recipient check: The receiving wallet must resolve to an accepted OnchainID that is not marked as lost.
2. Claim check: That OnchainID must hold a valid claim for every topic the expression requires.
3. Trusted issuer: A registered claim signer in the asset's issuer registry must have signed each claim.

The module evaluates the recipient only. It does not check the sender. If the expression evaluates to false, the transfer reverts with RecipientNotVerified before execution.

Configuration parameters

Pass these parameters when you attach the compliance module during asset creation. All three fields are required.

Expression nodes

The values array contains postfix expression nodes that define which claims the module requires. Each node has two fields to configure:

The expression can contain up to 32 nodes. A non-empty expression must leave exactly one boolean value on the stack after evaluation. Topic ID 0 is invalid. An empty expression skips claim-topic evaluation, but the recipient wallet still needs a registered identity and must not be marked as lost.

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

The examples below show how to construct the values array for common compliance scenarios. Each example demonstrates one pattern; combine them as your asset's regulatory requirements demand. For the full expression semantics, operator precedence, and node type reference, see the Identity Verification reference.

Single requirement (KYC only)

For most regulated assets, a single KYC check is sufficient. The values array contains one TOPIC node. The recipient wallet must hold a valid knowYourCustomer claim from a trusted issuer.

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

KYC and AML combined

Use an AND node to require both knowYourCustomer and antiMoneyLaundering. List the first TOPIC node, then the AND operator node, then the second TOPIC node:

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

Alternative requirements (KYC OR accreditedInvestor)

Use an OR node to accept either knowYourCustomer or accreditedInvestor. This pattern suits assets where different investor types qualify under different rules:

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

Complex expression with grouping

Use grouping to require (KYC AND AML) OR qualifiedInstitutionalInvestor. Add the literal strings "(" and ")" as array elements around the sub-expression:

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

Request parameters

Use these fields when constructing the module configuration. The values array drives on-chain evaluation, so every node must be valid before you submit the request.

Identity verification module configuration

Fields for the identity verification entry in initialModulePairs. The values field accepts node objects and "(" / ")" grouping markers.

Wallet verification object

Include a wallet verification object in every mutation request to authorize the on-chain write. The secretVerificationCode must match your configured method: a 6-digit code for PINCODE, a backup code for SECRET_CODES, or a TOTP for OTP.

If you omit verificationType, the platform defaults to "PINCODE". Use "OTP" for TOTP-based authenticators, or "SECRET_CODES" for backup code authentication.

Best practices

Claim selection

Choose claims that match your regulatory context. Start with knowYourCustomer for basic compliance, then layer additional claims as your rules require. The combination determines the strictness of the gate for every transfer on that asset.

Add antiMoneyLaundering for enhanced due diligence. Use accreditedInvestor or qualifiedInstitutionalInvestor for securities with investor restrictions. Combine claims with AND for stricter requirements, or with OR for flexibility.

Expression design

Keep expressions simple: a single topic is sufficient in most cases. Test complex expressions in a non-production environment and document the logic for compliance audits. Use OR with accreditation claims to support different investor types.

Trusted issuers

• Confirm all claim issuers appear in the trusted issuer registry before enabling the module.
• Verify each issuer's credentials before adding them.
• Review issuer permissions on a regular schedule.

Troubleshooting

Use the table below to identify the cause and corrective step for each error.

Related guides

• Identity Verification reference - Runtime claim evaluation, trusted issuer lookup, failure behavior, and expression semantics
• Verify KYC - Issue KYC verifications to users
• Configure Trusted Issuers - Set up issuer permissions