Compliance modules API

Compliance module endpoints cover two related surfaces. System endpoints manage the registry that exposes approved module implementations. Token endpoints install and configure those modules on an issued token so transfer checks enforce the selected policy.

For reusable asset creation policies, use Compliance templates. Templates decide which controls an asset starts with. Compliance module endpoints manage the registry and the token-level bindings behind those controls.

Endpoint summary

The system list endpoint reads indexed registry state. System register, system uninstall, and token-level mutation endpoints queue on-chain mutations and can complete synchronously or return transaction tracking data.

List registered modules

curl --globoff "$API_URL/api/v2/system/compliance-modules?page[limit]=20&sort=name" \
  --header "X-Api-Key: $API_TOKEN"

The response uses the collection envelope:

{
  "data": [
    {
      "id": "0x71c7656ec7ab88b098defb751b7401b5f6d8976f2546bcd3c84621e976d8185a91a922ae77ecec30",
      "module": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "typeId": "identity-verification",
      "name": "identity-verification",
      "globalConfigs": []
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "name": [{ "value": "identity-verification", "count": 1 }],
      "typeId": [{ "value": "identity-verification", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/system/compliance-modules?sort=name&page%5Boffset%5D=0&page%5Blimit%5D=20",
    "first": "/v2/system/compliance-modules?sort=name&page%5Boffset%5D=0&page%5Blimit%5D=20",
    "prev": null,
    "next": null,
    "last": "/v2/system/compliance-modules?sort=name&page%5Boffset%5D=0&page%5Blimit%5D=20"
  }
}

Each item includes:

You can filter by module, name, or typeId. Address filters are normalized before query execution. name uses text matching and both name and typeId return facets in meta.facets, so clients can build picker filters from the response.

globalConfigs is returned for display and review. It is not a filter field. When the system has no compliance contract or module registry address, the list endpoint returns an empty page. In that case, meta.total is 0.

Register modules

Register every Directory-backed module by sending "all":

curl --request POST \
  "$API_URL/api/v2/system/compliance-modules" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "complianceModules": "all"
  }'

Register one module by type:

{
  "complianceModules": {
    "type": "identity-verification"
  }
}

Register selected modules by sending an array:

{
  "complianceModules": [{ "type": "identity-verification" }, { "type": "country-allow-list" }]
}

The platform resolves implementation addresses from indexed Directory state when you omit implementation. Send implementation only when your deployment uses an approved custom module address for that type. If the requested type is not available in indexed Directory state, the platform rejects the request instead of guessing an implementation address.

Register calls require the system compliance module creation permission and wallet verification before the platform queues the mutation. The request is scoped to the caller's tenant and active system.

Uninstall a module

Read the module list first, then pass the registered module address to the uninstall endpoint:

curl --request DELETE \
  "$API_URL/api/v2/system/compliance-modules" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Content-Type: application/json" \
  --data '{
    "module": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }'

The module value is the contract address of the registered compliance module, not the composite id returned by the list endpoint. The platform verifies that the address is registered in the system compliance module registry, resolves the bound instance address from the compliance contract, and queues the uninstall transaction.

Uninstall calls require the system compliance module removal permission and wallet verification. If the module is not registered, the platform rejects the request before queue submission.

Configure modules on a token

Token-level compliance routes apply registered modules to an issued token. Read the token first, then submit one module mutation at a time with a request idempotency key.

Install one standard module binding:

curl --request POST \
  "$API_URL/api/v2/tokens/$TOKEN_ADDRESS/compliance-modules" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "params": {
      "typeId": "identity-verification-v2",
      "module": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "values": []
    }
  }'

Use the standard install endpoint when one active binding of a module type is enough for the token. The platform resolves the module type from the implementation address and rejects a duplicate binding for the same type. Tokens with a dedicated compliance engine execute the install through that engine; older token models execute it through the token contract.

Use scoped install when a token with a dedicated compliance engine needs more than one binding of the same module type for different transfer populations:

curl --request POST \
  "$API_URL/api/v2/tokens/$TOKEN_ADDRESS/compliance-modules/scoped" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "params": {
      "typeId": "investor-count-v2",
      "module": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "values": { "maxInvestors": 100 }
    },
    "scope": {
      "senderCountryInclusion": [56],
      "senderCountryExclusion": [],
      "receiverCountryInclusion": [],
      "receiverCountryExclusion": [],
      "senderInclusion": [],
      "senderExemption": [],
      "receiverInclusion": [],
      "receiverExemption": [],
      "executionMode": 0
    }
  }'

Scoped installs require a dedicated compliance engine. They create a separate module instance and attach the supplied scope. Use the returned token state or a fresh compliance-module read to capture the instanceAddress before updating that instance.

Indexing and constraint symptoms

Compliance module reads come from indexed contract state. After a queued mutation returns tracking data, poll the transaction status before relying on the list response or token state. A successful transaction can take a short indexing interval to appear in reads. If the transaction succeeds but the module list or token binding view does not change after status polling completes, treat it as an indexing issue and retry the read before submitting another mutation.

Constraint failures happen before a new binding becomes visible in indexed state. Duplicate standard installs return a terminal error for an already added module instead of creating a second row. Scoped installs on tokens without a dedicated compliance engine fail instead of falling back to a standard binding. Reconfiguration fails when the instance address is not part of the token compliance engine, the instance is inactive, the request typeId does not match the on-chain type, or the module has immutable parameters such as capital-raise-limit.

Reconfigure installed modules

Standard parameter updates use the module address for older token models. Tokens with a dedicated compliance engine use the installed instance address when the token can have more than one binding for the same module type:

curl --request PATCH \
  "$API_URL/api/v2/tokens/$TOKEN_ADDRESS/compliance-module-parameters" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "instanceAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
    "params": {
      "typeId": "investor-count-v2",
      "module": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "values": { "maxInvestors": 150 }
    }
  }'

The platform validates that the instance belongs to the token compliance engine, that it is active, and that its on-chain typeId matches the params.typeId in the request. capital-raise-limit configuration is immutable after installation; deploy a new module instance to change its parameters.

For scoped bindings, update parameters and scope together when both change:

curl --request PATCH \
  "$API_URL/api/v2/tokens/$TOKEN_ADDRESS/compliance-modules/$INSTANCE_ADDRESS/scoped-parameters" \
  --header "X-Api-Key: $API_TOKEN" \
  --header "Idempotency-Key: $IDEMPOTENCY_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "params": {
      "typeId": "investor-count-v2",
      "module": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "values": { "maxInvestors": 150 }
    },
    "scope": {
      "senderCountryInclusion": [56],
      "senderCountryExclusion": [],
      "receiverCountryInclusion": [],
      "receiverCountryExclusion": [],
      "senderInclusion": [],
      "senderExemption": [],
      "receiverInclusion": [],
      "receiverExemption": [],
      "executionMode": 0
    }
  }'

Use PUT /api/v2/tokens/{tokenAddress}/compliance-modules/{instanceAddress}/scope only when the scope changes and the module parameters stay the same. The combined scoped-parameters endpoint keeps the rule edit in one queued transaction and one wallet verification.

Operational notes

• Use the system list endpoint as the source for available module implementations before token install workflows.
• Read the token compliance bindings before every token-level reconfiguration or uninstall operation.
• Treat register, uninstall, install, and configure calls as transaction queue workflows. Poll the returned transaction status when the platform accepts the mutation asynchronously.
• Use Transaction tracking for queued mutation status and failure handling.
• Use Request headers when your integration needs idempotency, acting participant headers, or transaction speed headers.

Related pages

• Compliance templates for reusable asset creation policies
• Token lifecycle API for lifecycle, scoped compliance, and feature operation patterns
• Create asset via API for using templates during asset deployment
• Compliance overview for module concepts and transfer checks