Configure trusted issuers

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.

Prerequisites

• Platform URL: https://your-platform.example.com
• API key from a user with the Claim Policy Manager role. See 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

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. For the operator workflow around compliance modules, see Compliance overview.

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:

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

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.

Investor verification topics

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

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.

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.

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:

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.

Configuring trusted issuers

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

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

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

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

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

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

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"

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

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.

List token trusted issuers

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.

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

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

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

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.

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.

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.

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:

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

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.

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:

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

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.

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

Response:

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

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.

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

Response:

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

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

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.

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.

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.

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.

Create system trusted issuer

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

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.

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.

Get topic details (with trusted issuers)

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.

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.

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

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.

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

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.

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

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.

Trusted issuer

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

Token trusted issuer row

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

Verification topic

In trusted issuer response (claimTopics array):

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

Includes all fields above plus:

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

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

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

The table below lists common errors and their resolution steps.

Related guides

• Compliance Overview - Complete compliance reference
• Verify KYC - Issue verifications via API
• Claims and identity - Understand claim topics, trusted issuers, and identity checks
• Add Administrators - Grant roles via API
• Configure Trusted Issuers (User Guide) - Web interface approach