# Configure trusted issuers

Source: https://docs.settlemint.com/docs/developers/compliance/configure-trusted-issuers
Add, scope, and remove trusted issuer entries in system and token registries so on-chain claim verification resolves the correct identity addresses.



Use this guide to automate issuer and claim topic configuration through the Platform API. You will connect an issuer identity address to approved claim topics and confirm the issuer appears in the resolved system or token issuer list.

For the web interface approach, see the [user guide](/docs/operators/compliance/configure-trusted-issuers).

## Prerequisites [#prerequisites]

* Platform URL: `https://your-platform.example.com`
* API key from a user with the **Claim Policy Manager** role. See [Getting Started](/docs/api-reference/reference/getting-started) for API key setup.
* Wallet verification enabled on your account: pincode or 2FA
* Wallet address of the user you want to make a trusted issuer

## About trusted issuers [#about-trusted-issuers]

Trusted issuers are identity addresses authorized in the active system's trusted issuer registry. Assets that use identity verification rules rely on these issuers when checking whether a wallet has a claim for the required topic. For the underlying wallet, OnchainID, claim-topic, and issuer model, see [Claims and identity](/docs/architecture/concepts/claims-and-identity). For the operator workflow around compliance modules, see [Compliance overview](/docs/operators/compliance/overview).

<Callout type="info" title="System and token scope">
  System endpoints manage the active platform context. Token endpoints manage only the selected asset's token-level
  Trusted Issuer Registry. A token trusted issuer does not replace the system or global registry; DALP resolves the
  effective chain as `token -> system -> global` when it checks which issuer claims count for that token.
</Callout>

## Identity claim model [#identity-claim-model]

DALP separates the wallet, the identity contract, the claim topic, and the trusted issuer. The wallet is the account that acts in the platform. The identity contract is the on-chain identity address attached to that wallet. The claim topic defines the kind of compliance statement, such as KYC or AML. The trusted issuer is the identity address authorised to issue claims for one or more topics.

This separation lets a token policy check that a wallet has the required claim without putting the underlying personal data on-chain. For example, a KYC provider can issue a `knowYourCustomer` claim to an investor identity. A token that requires that topic checks the claim and its trusted issuer during transfer or issuance flows. The source documents and evidence behind the KYC decision stay with the provider or the configured off-chain process.

The API follows the same model:

| Primitive        | What it represents                                          | Where you use it                                           |
| ---------------- | ----------------------------------------------------------- | ---------------------------------------------------------- |
| Wallet address   | The account that signs or receives token operations.        | Identity lookup and operational workflows.                 |
| Identity address | The on-chain identity contract linked to a wallet.          | Trusted issuer configuration and claim issuance.           |
| Claim topic      | The named compliance fact and ABI data shape.               | Claim topic registry and token compliance rules.           |
| Trusted issuer   | An identity authorised to issue claims for selected topics. | System or token trusted issuer registries.                 |
| Claim            | The issued statement attached to an identity for a topic.   | KYC verification, transfer eligibility, and claim history. |

Token claim issuance routes allow either the required token role or a trusted issuer identity for the requested claim topics. System identity claim issuance requires both the platform claim-creation role and trusted issuer status for the requested topics. The trusted issuer check is topic-specific. Being trusted for AML does not automatically authorise the same identity to issue KYC claims.

## Choose the right route family [#choose-the-right-route-family]

| Need                                                                 | Use                                                                     | Why                                                                                                 |
| -------------------------------------------------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| Register a new claim data shape                                      | `/api/v2/system/claim-topics`                                           | Claim topics define the data shape that identity claims use.                                        |
| Trust an issuer for the active platform context                      | `/api/v2/system/trusted-issuers`                                        | System trusted issuers apply across assets that rely on the active system registry.                 |
| Trust an issuer for one asset only                                   | `/api/v2/tokens/{tokenAddress}/trusted-issuers`                         | Token trusted issuers apply to the selected asset's token-level registry when that registry exists. |
| Add or remove one topic without replacing the full issuer topic list | `/api/v2/system/trusted-issuers/{issuerAddress}/claim-topics/{topicId}` | Single-topic routes compute the next topic set server-side and avoid overwriting unrelated topics.  |

## Available verification topics [#available-verification-topics]

The platform includes preset verification topics for common compliance scenarios. Each topic has a unique `topicId` and a `signature` that defines the claim data structure.

<Callout type="info" title="Custom verification topics">
  These are preset topics included with the platform. You can create additional custom verification topics to meet your
  specific compliance requirements.
</Callout>

### Investor verification topics [#investor-verification-topics]

These topics cover investor identity verification, accreditation status, AML screening, and regulatory eligibility.

| Topic Name                       | Signature      | Purpose                                   |
| -------------------------------- | -------------- | ----------------------------------------- |
| `knowYourCustomer`               | `string claim` | Basic KYC verification                    |
| `accreditedInvestor`             | `string claim` | Accredited investor status                |
| `accreditedInvestorVerified`     | `string claim` | Verified accredited investor              |
| `qualifiedInstitutionalInvestor` | `string claim` | Qualified institutional buyer (QIB)       |
| `professionalInvestor`           | `string claim` | Professional investor status              |
| `antiMoneyLaundering`            | `string claim` | AML compliance verification               |
| `regulationS`                    | `string claim` | Regulation S (non-US investor) compliance |

### Issuer verification topics [#issuer-verification-topics]

These topics cover issuer licensing, jurisdiction, and reporting obligations. Assign them to issuers that attest compliance state at the issuer or legal entity level.

| Topic Name                 | Signature                                                                           | Purpose                 |
| -------------------------- | ----------------------------------------------------------------------------------- | ----------------------- |
| `issuerLicensed`           | `string licenseType, string licenseNumber, string jurisdiction, uint256 validUntil` | Issuer licensing status |
| `issuerJurisdiction`       | `string jurisdiction`                                                               | Issuer jurisdiction     |
| `issuerProspectusFiled`    | `string prospectusReference`                                                        | Prospectus filing       |
| `issuerProspectusExempt`   | `string exemptionReference`                                                         | Prospectus exemption    |
| `issuerReportingCompliant` | `bool compliant, uint256 lastUpdated`                                               | Reporting compliance    |

### Asset verification topics [#asset-verification-topics]

These topics describe asset classification, geographic location, issuer identity, and collateral details. Assign them to issuers that are authorized to attest token-level or asset-level compliance properties for the instruments they manage.

| Topic Name            | Signature                                             | Purpose                |
| --------------------- | ----------------------------------------------------- | ---------------------- |
| `assetClassification` | `string class, string category`                       | Asset classification   |
| `assetLocation`       | `string city, string districtCode, string areaId`     | Asset location         |
| `assetIssuer`         | `address issuerAddress`                               | Asset issuer identity  |
| `basePrice`           | `uint256 amount, string currencyCode, uint8 decimals` | Base price information |
| `collateral`          | `uint256 amount, uint256 expiryTimestamp`             | Collateral details     |
| `contractIdentity`    | `address contractAddress`                             | Contract identity      |
| `uniqueIdentifier`    | `string identifier`                                   | Unique identifier      |

<Callout type="info" title="Topic IDs">
  Each topic has a unique large numeric `topicId` (e.g.,
  `26984799302505749158794800959285050858086405868089409909048783980951278841746`). Use `GET
    /api/v2/system/claim-topics` to retrieve the exact topic IDs for your platform.
</Callout>

## Managing system claim topics [#managing-system-claim-topics]

Use claim topic mutations only when the platform needs a new or changed claim data shape. Existing asset and compliance flows usually rely on the preset topics above.

To create a claim topic, send a human-readable `name`, a comma-separated ABI type list in `signature`, and wallet verification:

```bash
curl -X POST "https://your-platform.example.com/api/v2/system/claim-topics" \
  -H "X-Api-Key: [REDACTED]" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "assetOrigin",
    "signature": "string,uint256",
    "walletVerification": {
      "secretVerificationCode": "[REDACTED]"
    }
  }'
```

The API normalizes the signature to the parenthesized ABI form on-chain. Send `string,uint256`, not `(string,uint256)`.

To change the data shape for an existing topic, use `PUT /api/v2/system/claim-topics/{name}` with the replacement `signature` and wallet verification. To remove a topic scheme, use `DELETE /api/v2/system/claim-topics/{name}` with wallet verification.

<Callout type="warning" title="Production claim-topic changes">
  Treat topic updates and removals as platform-level configuration changes. Confirm which asset policies, trusted
  issuers, and integrations use the topic before changing its signature or removing it from the registry.
</Callout>

## Configuring trusted issuers [#configuring-trusted-issuers]

<Steps>
  <Step>
    ### Get issuer's identity address [#get-issuers-identity-address]

    First, you need the identity contract address of the user you want to make a trusted issuer. If you have their wallet address, query their identity. The response includes the identity contract address in the `id` field:

    ```bash
    curl -X GET "https://your-platform.example.com/api/system/identity/by-wallet/0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    ```json
    {
      "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
      "account": {
        "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb",
        "contractName": null
      },
      "isContract": false,
      "hasIdentity": true,
      "claims": []
    }
    ```

    Use the `id` field (identity CONTRACT address), not the `account.id` (wallet address).
  </Step>

  <Step>
    ### List available verification topics [#list-available-verification-topics]

    Query the available verification topics to identify which topics you want this issuer to be trusted for:

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

    Response:

    ```json
    [
      {
        "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
        "topicId": "26984799302505749158794800959285050858086405868089409909048783980951278841746",
        "name": "knowYourCustomer",
        "signature": "string claim",
        "registry": {
          "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7"
        }
      },
      {
        "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
        "topicId": "15733030998618876990024220391915773205162379317494393310546829862321881862123",
        "name": "accreditedInvestor",
        "signature": "string claim",
        "registry": {
          "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7"
        }
      },
      {
        "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
        "topicId": "39526553109170329799339511574661256630735485618560740361645615581310848276505",
        "name": "qualifiedInstitutionalInvestor",
        "signature": "string claim",
        "registry": {
          "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7"
        }
      }
      // ... additional topics available
    ]
    ```

    Note the `topicId` values for the topics you want to assign to this issuer. See [Available verification topics](#available-verification-topics) above for the complete list.

    <Callout type="info" title="One row per topic">
      This endpoint resolves the active system's registry chain (`system -> parent -> global`) and returns each topic once,
      keyed by `topicId`. When the same topic is available through more than one tier of the chain, the response keeps the
      registration closest to the active system and drops the inherited duplicates. You can rely on a single row per topic
      and do not need to deduplicate the list yourself.
    </Callout>

    ![Trusted issuer configuration in the verification topic registry](/docs/screenshots/identity/verification-topics.webp)
  </Step>

  <Step>
    ### Add trusted issuer [#add-trusted-issuer]

    Create the trusted issuer by specifying their identity address and the verification topic IDs they can issue:

    ```bash
    curl -X POST "https://your-platform.example.com/api/v2/system/trusted-issuers" \
      -H "X-Api-Key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
        "claimTopicIds": [
          "26984799302505749158794800959285050858086405868089409909048783980951278841746",
          "15733030998618876990024220391915773205162379317494393310546829862321881862123"
        ],
        "walletVerification": {
          "secretVerificationCode": "YOUR_PINCODE"
        }
      }'
    ```

    Response:

    ```json
    {
      "data": {
        "txHash": "0x1234567890abcdef...",
        "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"
      },
      "meta": {
        "txHashes": ["0x1234567890abcdef..."]
      },
      "links": {
        "self": "/v2/system/trusted-issuers"
      }
    }
    ```

    <Callout type="info" title="Multiple verification topics">
      You can assign multiple verification topics in a single request by including multiple topic IDs in the `claimTopicIds`
      array. If you send the request with asynchronous transaction processing enabled, the API accepts the request with a
      `transactionId`, `status`, and `statusUrl` instead of returning the completed blockchain mutation envelope
      immediately.
    </Callout>
  </Step>

  <Step>
    ### Verify completion [#verify-completion]

    Filter by identity address to confirm the issuer appears in the registry. A successful response includes the identity address, the linked wallet account, and the assigned claim topics.

    ```bash
    curl --globoff -X GET "https://your-platform.example.com/api/v2/system/trusted-issuers?filter[id]=0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890&page[offset]=0&page[limit]=25" \
      -H "X-Api-Key: YOUR_API_KEY"
    ```

    ```json
    {
      "data": [
        {
          "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
          "account": {
            "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
          },
          "claimTopics": [
            {
              "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
              "topicId": "26984799302505749158794800959285050858086405868089409909048783980951278841746",
              "name": "knowYourCustomer",
              "signature": "string claim"
            },
            {
              "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
              "topicId": "15733030998618876990024220391915773205162379317494393310546829862321881862123",
              "name": "accreditedInvestor",
              "signature": "string claim"
            }
          ],
          "deployedInTransaction": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
          "isGlobal": false
        }
      ],
      "meta": {
        "total": 1,
        "facets": {}
      },
      "links": {
        "self": "/v2/system/trusted-issuers?sort=id&filter%5Bid%5D=0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890&page%5Boffset%5D=0&page%5Blimit%5D=25",
        "first": "/v2/system/trusted-issuers?sort=id&filter%5Bid%5D=0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890&page%5Boffset%5D=0&page%5Blimit%5D=25",
        "prev": null,
        "next": null,
        "last": "/v2/system/trusted-issuers?sort=id&filter%5Bid%5D=0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890&page%5Boffset%5D=0&page%5Blimit%5D=25"
      }
    }
    ```

    Check the following fields to verify the issuer record is complete and correctly scoped.

    * `data[].id` matches the identity address you added.
    * `data[].account` is the wallet for the issuer, or `null` when none is known.
    * `data[].claimTopics` lists the assigned topics (`id`, `topicId`, `name`, `signature`).
    * `data[].isGlobal` is `true` when the issuer comes from a global registry.

    <Callout type="info" title="What the issuer account resolves to">
      `account` identifies the issuer by wallet, not by identity contract. For a smart wallet, `account.id` is that address. Otherwise, the platform uses the recorded account address.

      A missing or removed identity returns `account: null`. Use `id` for the identity contract and `account` for the wallet.
    </Callout>

    The issuer can now issue verifications for the assigned topics.
  </Step>
</Steps>

## Token-level trusted issuers [#token-level-trusted-issuers]

Use token-level trusted issuers when one asset needs a narrower issuer policy than the platform default. The list endpoint returns the full `token -> system -> global` chain. Each row indicates whether the issuer is token-specific or inherited from a parent registry.

| Source   | What it means                                                | Can this endpoint remove it?                               |
| -------- | ------------------------------------------------------------ | ---------------------------------------------------------- |
| `token`  | Issuer is registered on this token's Trusted Issuer Registry | Yes, with the token delete endpoint                        |
| `system` | Issuer is inherited from the active system registry          | No, manage it through the system trusted-issuer endpoints  |
| `global` | Issuer is inherited from a global registry                   | No, manage it through the global or platform-level process |

<Callout type="warning" title="Token issuers require a token registry">
  When `meta.hasTrustedIssuersRegistry: false`, the token has no token-level registry. The list still shows inherited
  system or global issuers, but token-specific add and remove operations are unavailable.
</Callout>

### List token trusted issuers [#list-token-trusted-issuers]

```bash
curl --globoff -X GET "https://your-platform.example.com/api/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers?filter[source]=token&page[offset]=0&page[limit]=25" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Use `filter[source]` to limit results to `token`, `system`, or `global`. Use `filter[q]` to search by issuer account address. The response is paginated and includes `meta.total`, `meta.facets`, and `meta.hasTrustedIssuersRegistry`.

```json
{
  "data": [
    {
      "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
      "account": { "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb" },
      "inheritanceLevel": "token",
      "registry": { "id": "0x4567890AbCdEf1234567890AbCdEf1234567890123" },
      "isInheritedElsewhere": false,
      "claimTopics": [
        {
          "topicId": "26984799302505749158794800959285050858086405868089409909048783980951278841746",
          "name": "knowYourCustomer"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "facets": {},
    "hasTrustedIssuersRegistry": true
  },
  "links": {
    "self": "/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers?filter%5Bsource%5D=token&page%5Boffset%5D=0&page%5Blimit%5D=25",
    "first": "/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers?filter%5Bsource%5D=token&page%5Boffset%5D=0&page%5Blimit%5D=25",
    "prev": null,
    "next": null,
    "last": "/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers?filter%5Bsource%5D=token&page%5Boffset%5D=0&page%5Blimit%5D=25"
  }
}
```

### Add a token trusted issuer [#add-a-token-trusted-issuer]

```bash
curl -X POST "https://your-platform.example.com/api/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
    "claimTopicIds": [
      "26984799302505749158794800959285050858086405868089409909048783980951278841746"
    ],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE"
    }
  }'
```

`issuerAddress` is the issuer identity contract address, not the issuer's EOA wallet address. `claimTopicIds` must contain at least one decimal-string topic ID and can contain at most 50 topic IDs. The response is an asynchronous blockchain mutation response with `txHash` and `issuerAddress`; refresh the list after indexer pickup to confirm the row appears with `inheritanceLevel: "token"`.

### Remove a token trusted issuer [#remove-a-token-trusted-issuer]

```bash
curl -X DELETE "https://your-platform.example.com/api/v2/tokens/0x1234567890AbCdEf1234567890AbCdEf1234567890/trusted-issuers/0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE"
    }
  }'
```

The delete endpoint only removes token-level rows. If the issuer is inherited from the system or global registry, the token endpoint returns a not-found error and does not remove the inherited issuer from the effective chain. If `isInheritedElsewhere` is `true` on a token row, removing that token row leaves the parent-tier trust visible in the resolved list.

## Managing trusted issuers [#managing-trusted-issuers]

### Add or remove one topic atomically [#add-or-remove-one-topic-atomically]

Use the single-topic endpoints to add or remove one topic at a time. These routes leave the issuer's other topics untouched.

```bash
curl -X POST "https://your-platform.example.com/api/v2/system/trusted-issuers/0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890/claim-topics/26984799302505749158794800959285050858086405868089409909048783980951278841746" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE"
    }
  }'
```

Use `DELETE` on the same path to remove the topic from that issuer. These endpoints compute the next topic list server-side, so a single-topic add or remove does not overwrite unrelated topics already assigned to the issuer. The response includes `issuerAddress`, `topicId`, and `txHash`. An add that is already present, or a remove that is already absent, is treated as idempotent: the call returns an empty `txHash` and skips the on-chain update.

<Callout type="info" title="Retry concurrent topic edits">
  If another claim-topic mutation for the same trusted issuer is already running, the API returns a retryable `409`
  `DALP-0461` conflict. Wait for the active mutation to finish, refresh the issuer's topic list, then retry only if the
  topic still needs to change.
</Callout>

### Update issuer topics [#update-issuer-topics]

To replace the full set of verification topics for an issuer, send a PATCH with the complete desired topic list. The platform replaces the existing set atomically.

```bash
curl -X PATCH "https://your-platform.example.com/api/v2/system/trusted-issuers/0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "claimTopicIds": [
      "26984799302505749158794800959285050858086405868089409909048783980951278841746",
      "15733030998618876990024220391915773205162379317494393310546829862321881862123",
      "39526553109170329799339511574661256630735485618560740361645615581310848276505"
    ],
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE"
    }
  }'
```

Response:

```json
{
  "txHash": "0xabcdef1234567890...",
  "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"
}
```

<Callout type="warning" title="Topic replacement">
  The `claimTopicIds` array replaces all existing topics. Include all topics you want the issuer to be trusted for, not
  just new additions.
</Callout>

### Remove trusted issuer [#remove-trusted-issuer]

To revoke an issuer's trusted status, send a DELETE request with wallet verification. DALP checks the indexed registry before queueing the on-chain call, so the request fails cleanly if the issuer is not registered.

```bash
curl -X DELETE "https://your-platform.example.com/api/v2/system/trusted-issuers/0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890" \
  -H "X-Api-Key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "walletVerification": {
      "secretVerificationCode": "YOUR_PINCODE"
    }
  }'
```

Response:

```json
{
  "txHash": "0x9876543210fedcba...",
  "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890"
}
```

Before submitting the removal transaction, DALP checks the indexed trusted-issuer registry. If the issuer is not registered for the active system, the API returns `SYSTEM_TRUSTED_ISSUER_NOT_FOUND` and does not queue the on-chain call.

<Callout type="warning" title="Impact of removal">
  Removing an issuer takes that issuer out of the trusted-issuer registry and its claim-topic mappings. Existing
  verification records remain available for review, but claims from the removed issuer no longer count as trusted for
  compliance checks.
</Callout>

### Get topic details with trusted issuers [#get-topic-details-with-trusted-issuers]

This call returns full claim topic metadata plus the list of non-revoked trusted issuers authorized for that topic. Use it to audit which issuers are currently trusted for a given claim type.

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

Response:

```json
{
  "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
  "name": "knowYourCustomer",
  "signature": "string claim",
  "topicId": "26984799302505749158794800959285050858086405868089409909048783980951278841746",
  "trustedIssuers": [
    {
      "id": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
      "addedAt": "2024-01-15T10:30:00Z",
      "revokedAt": "1970-01-01T00:00:00Z",
      "account": {
        "id": "0x742d35Cc6634C0532925a3b844Bc9e7595f0bEb"
      }
    }
  ]
}
```

The response includes full topic details along with all non-revoked trusted issuers authorized for that topic.

### List claim topics for a trusted issuer [#list-claim-topics-for-a-trusted-issuer]

This call returns all claim topics currently assigned to one trusted issuer. Use it to verify the issuer's topic set before adding or removing a single topic.

```bash
curl -X GET "https://your-platform.example.com/api/v2/system/trusted-issuers/0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890/topics" \
  -H "X-Api-Key: YOUR_API_KEY"
```

Response:

```json
{
  "issuerAddress": "0x8e5F72f6E5b3B4D1234567890AbCdEf1234567890",
  "claimTopics": [
    {
      "id": "0x534b8f03c16c92c70d1da1d2fae43b98352bf3d7...",
      "topicId": "26984799302505749158794800959285050858086405868089409909048783980951278841746",
      "name": "knowYourCustomer",
      "signature": "string claim"
    }
  ]
}
```

## Request parameters [#request-parameters]

The sections below document the input fields for each endpoint. All mutation endpoints require wallet verification. Pagination parameters apply to list endpoints only.

### Create claim topic [#create-claim-topic]

`POST /api/v2/system/claim-topics` creates a new claim topic scheme. Provide a human-readable `name` and a comma-separated ABI type list in `signature`.

| Parameter            | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `name`               | string | Yes      | Topic scheme name, up to 100 characters               |
| `signature`          | string | Yes      | Comma-separated ABI type list, without parentheses    |
| `walletVerification` | object | Yes      | Your wallet verification to authorize the transaction |

### Update claim topic [#update-claim-topic]

`PUT /api/v2/system/claim-topics/{name}` updates the signature for an existing topic. Send the replacement `signature` without parentheses. Existing claims for that topic remain valid; only the expected data shape changes.

| Parameter            | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `name`               | string | Yes      | Topic name to update (path parameter)                 |
| `signature`          | string | Yes      | Replacement comma-separated ABI type list             |
| `walletVerification` | object | Yes      | Your wallet verification to authorize the transaction |

### Delete claim topic [#delete-claim-topic]

`DELETE /api/v2/system/claim-topics/{name}` removes the named topic scheme from the registry. Confirm which asset policies and integrations reference the topic before removal, because deleting a topic does not automatically clean up issuer assignments or compliance rules that depend on it.

| Parameter            | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `name`               | string | Yes      | Topic name to remove (path parameter)                 |
| `walletVerification` | object | Yes      | Your wallet verification to authorize the transaction |

### List system trusted issuers [#list-system-trusted-issuers]

`GET /api/v2/system/trusted-issuers` returns results in identity-address order. Use `filter[id]` to scope the response to one issuer. Results are paginated with `meta.total` and `links`.

| Parameter      | Type   | Required | Description                                      |
| -------------- | ------ | -------- | ------------------------------------------------ |
| `page[limit]`  | number | No       | Number of trusted issuers to return              |
| `page[offset]` | number | No       | Number of trusted issuers to skip                |
| `filter[id]`   | string | No       | Filter by trusted issuer identity address        |
| `filter[q]`    | string | No       | Global search across supported collection fields |

### Create system trusted issuer [#create-system-trusted-issuer]

`POST /api/v2/system/trusted-issuers` registers a trusted issuer. Use the identity contract address in `issuerAddress`, not the EOA.

| Parameter            | Type      | Required | Description                                           |
| -------------------- | --------- | -------- | ----------------------------------------------------- |
| `issuerAddress`      | string    | Yes      | Identity contract address (0x...)                     |
| `claimTopicIds`      | string\[] | Yes      | Array of verification topic IDs (min: 1)              |
| `walletVerification` | object    | Yes      | Your wallet verification to authorize the transaction |

### Update system trusted issuer [#update-system-trusted-issuer]

`PATCH /api/v2/system/trusted-issuers/{issuerAddress}` replaces the issuer's full topic set with `claimTopicIds`. The call replaces all existing topics atomically. Use the single-topic routes to add or remove one topic without replacing the whole set.

| Parameter            | Type      | Required | Description                                           |
| -------------------- | --------- | -------- | ----------------------------------------------------- |
| `issuerAddress`      | string    | Yes      | Identity address to update (path parameter)           |
| `claimTopicIds`      | string\[] | Yes      | New array of verification topic IDs (min: 1)          |
| `walletVerification` | object    | Yes      | Your wallet verification to authorize the transaction |

### Delete system trusted issuer [#delete-system-trusted-issuer]

`DELETE /api/v2/system/trusted-issuers/{issuerAddress}` removes the issuer from the registry. Claims from the removed issuer are immediately invalidated for compliance checks. Requires the `claimPolicyManager` role and wallet verification.

| Parameter            | Type   | Required | Description                                           |
| -------------------- | ------ | -------- | ----------------------------------------------------- |
| `issuerAddress`      | string | Yes      | Identity address to remove (path parameter)           |
| `walletVerification` | object | Yes      | Your wallet verification to authorize the transaction |

### Get topic details (with trusted issuers) [#get-topic-details-with-trusted-issuers-1]

`GET /api/v2/system/claim-topics/{name}` returns full topic metadata and all non-revoked issuers trusted for that topic. Use this endpoint to audit which issuers are currently authorized for a given claim type. The `name` parameter is the human-readable topic name, for example `knowYourCustomer`.

| Parameter | Type   | Required | Description                                                 |
| --------- | ------ | -------- | ----------------------------------------------------------- |
| `name`    | string | Yes      | Claim topic name (path parameter, e.g., `knowYourCustomer`) |

### List claim topics for issuer [#list-claim-topics-for-issuer]

`GET /api/v2/system/trusted-issuers/{issuerAddress}/topics` lists all claim topics for one issuer. Review the current set before adding or removing a topic.

| Parameter       | Type   | Required | Description                                  |
| --------------- | ------ | -------- | -------------------------------------------- |
| `issuerAddress` | string | Yes      | Trusted issuer identity address (path param) |

### Add or remove one claim topic [#add-or-remove-one-claim-topic]

Use these routes when the issuer already exists and you need to add or remove exactly one topic. Both operations leave the issuer's other topics untouched and are idempotent. Use `POST` to add one topic and `DELETE` to remove one topic; the path parameter `topicId` is the numeric topic ID.

* `POST /api/v2/system/trusted-issuers/{issuerAddress}/claim-topics/{topicId}` adds one topic to the issuer.
* `DELETE /api/v2/system/trusted-issuers/{issuerAddress}/claim-topics/{topicId}` removes one topic from the issuer.

Both routes require `walletVerification` in the request body and return the same blockchain mutation response shape as other trusted-issuer mutations. Adding a topic that is already present, or removing one that is already absent, is treated as idempotent and may return no transaction hash.

### Token trusted issuers [#token-trusted-issuers]

These endpoints manage the token-level Trusted Issuer Registry for one asset. The GET endpoint returns the full resolved chain across all tiers. The POST and DELETE endpoints operate only on token-level rows.

| Endpoint                                                               | Required parameters                                                                   | Description                                                                     |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| `GET /api/v2/tokens/{tokenAddress}/trusted-issuers`                    | `tokenAddress`; optional `filter[q]`, `filter[source]`, `page[offset]`, `page[limit]` | Lists the resolved token, system, and global trusted issuer chain for one token |
| `POST /api/v2/tokens/{tokenAddress}/trusted-issuers`                   | `tokenAddress`, `issuerAddress`, non-empty `claimTopicIds`, `walletVerification`      | Adds an issuer to the token-level Trusted Issuer Registry                       |
| `DELETE /api/v2/tokens/{tokenAddress}/trusted-issuers/{issuerAddress}` | `tokenAddress`, `issuerAddress`, `walletVerification`                                 | Removes a token-level issuer row                                                |

`filter[source]` accepts `token`, `system`, or `global`. Token create requests accept 1 to 50 `claimTopicIds`; each ID must be a non-negative decimal string that fits `uint256`. Create requests can return `DALP-4001`, `DALP-4003`, or `DALP-4214`. Delete requests can return `DALP-4001` or `DALP-4003`. The token trusted issuer list always returns the full resolved chain. Use `filter[source]=token` to see only the token-specific entries.

### Wallet verification object [#wallet-verification-object]

All mutation endpoints require a `walletVerification` object in the request body. The default verification type is `PINCODE`. Supply `SECRET_CODES` when the user authenticates with backup codes, or `OTP` for a time-based one-time password authenticator. The `secretVerificationCode` field carries the six-digit value in all three cases.

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

## Response fields [#response-fields]

The sections below describe the fields returned by each endpoint family. Mutation endpoints return a transaction envelope; list and detail endpoints return structured objects with pagination metadata.

### Trusted issuers list [#trusted-issuers-list]

`GET /api/v2/system/trusted-issuers` returns a paginated object. Navigate pages with `links.next` and `links.prev`. Each page includes `meta.total` for the total count across all pages.

| Field         | Type   | Description                                      |
| ------------- | ------ | ------------------------------------------------ |
| `data`        | array  | Trusted issuer records for the requested page    |
| `meta.total`  | number | Total matching trusted issuers before pagination |
| `meta.facets` | object | Facet metadata for collection filters            |
| `links`       | object | Pagination links for the current query           |

### Trusted issuer [#trusted-issuer]

Each row is one trusted issuer. `id` is the on-chain identity contract address.

| Field                   | Type    | Description                                                                      |
| ----------------------- | ------- | -------------------------------------------------------------------------------- |
| `id`                    | string  | Issuer identity contract address                                                 |
| `account`               | object  | Reserved for linked account details; the paginated list currently returns `null` |
| `claimTopics`           | array   | Verification topics this issuer can verify                                       |
| `deployedInTransaction` | string  | Transaction hash where issuer was added                                          |
| `isGlobal`              | boolean | Whether the issuer came from a global registry rather than organization-only     |

### Token trusted issuer row [#token-trusted-issuer-row]

Each row in the token trusted-issuer list response includes these fields:

| Field                            | Type    | Description                                                                    |
| -------------------------------- | ------- | ------------------------------------------------------------------------------ |
| `id`                             | string  | Issuer identity contract address                                               |
| `account.id`                     | string  | Issuer account address when linked account details are available               |
| `inheritanceLevel`               | string  | `token`, `system`, or `global` source for this row                             |
| `claimTopics`                    | array   | Claim topics this issuer is trusted for at that source tier                    |
| `registry.id`                    | string  | Trusted Issuer Registry contract address that holds this row                   |
| `isInheritedElsewhere`           | boolean | Whether the same issuer also exists in a parent registry in the resolved chain |
| `meta.hasTrustedIssuersRegistry` | boolean | Whether token-specific add and remove operations are available for this token  |

### Verification topic [#verification-topic]

**In trusted issuer response (`claimTopics` array):**

| Field       | Type   | Description                                 |
| ----------- | ------ | ------------------------------------------- |
| `id`        | string | Topic scheme identifier                     |
| `topicId`   | string | Large numeric ID unique to the topic        |
| `name`      | string | Human-readable name of the topic            |
| `signature` | string | Claim data parameter types for verification |

**In claim topics endpoint (`GET /api/v2/system/claim-topics`):**

Includes all fields above plus:

| Field         | Type   | Description                                  |
| ------------- | ------ | -------------------------------------------- |
| `registry`    | object | Registry information containing registry ID  |
| `registry.id` | string | Contract address of the claim topic registry |

Each `topicId` appears once across the resolved `system -> parent -> global` registry chain. When a topic exists in more than one tier, `registry.id` reflects the registration closest to the active system. Both `meta.total` and the `source` facet count the single deduplicated row.

## Operational notes [#operational-notes]

### Issuer selection [#issuer-selection]

Choose issuers with legal or professional authority for the claim topics they will attest. Separate issuer types by compliance domain: a KYC provider and an AML provider should each control only the topics they are qualified to sign. For critical topics, register at least two issuers so a single removal does not block transfers across the token set.

### Lifecycle management [#lifecycle-management]

Review the trusted issuer registry periodically. Remove stale or superseded issuers using the DELETE endpoint or the single-topic routes.

Removing an issuer immediately invalidates its outstanding claims for compliance checks. Coordinate with affected token policy owners before proceeding. Record the rationale for each change so auditors can reconstruct the trust chain.

## Troubleshooting [#troubleshooting]

The table below lists common errors and their resolution steps.

| Issue                                         | Solution                                                                                                          |
| --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `401 Unauthorized`                            | API key is invalid, expired, or disabled                                                                          |
| `403 USER_NOT_AUTHORIZED`                     | Ensure your account has `claimPolicyManager` role                                                                 |
| `Identity not found`                          | User must be registered first; see [Register User](/docs/developers/user-management/register-user)                |
| `Invalid issuer address`                      | Use the identity CONTRACT address, not the wallet address                                                         |
| `Topic not found`                             | Verify the topic ID exists using `GET /api/v2/system/claim-topics`                                                |
| `409 DALP-0461` retryable conflict            | Another topic mutation for this trusted issuer is still running. Refresh the topic list, then retry if needed     |
| `Issuer already exists`                       | The issuer is already registered; use PATCH to replace topics, or the single-topic routes for one assignment      |
| Token trusted issuer registry missing         | The token can show inherited issuers, but token-specific add and remove operations are unavailable for that token |
| Inherited issuer cannot be removed from token | Remove system or global inherited issuers from the registry where they are defined, not from the token endpoint   |

## Related guides [#related-guides]

* [Compliance Overview](/docs/operators/compliance/overview) - Complete compliance reference
* [Verify KYC](/docs/developers/compliance/verify-kyc) - Issue verifications via API
* [Claims and identity](/docs/architecture/concepts/claims-and-identity) - Understand claim topics, trusted issuers, and identity checks
* [Add Administrators](/docs/developers/platform-setup/add-admins) - Grant roles via API
* [Configure Trusted Issuers (User Guide)](/docs/operators/compliance/configure-trusted-issuers) - Web interface approach