Token topic schemes

Token topic schemes define the data shape behind claim topics used by identity and compliance checks. DALP resolves schemes for a token through a chain of registries: token, system, then global. Use the token topic scheme API when an integration needs to inspect the effective scheme set for an asset or add a scheme that belongs only to that token.

The token routes manage token-level schemes only. Inherited system and global schemes appear in the list response so operators can see what the token already inherits. Those inherited rows are read-only through this API.

Endpoint summary

List effective topic schemes

Call GET /api/v2/tokens/{tokenAddress}/topic-schemes to read the topic schemes that apply to a token.

curl -X GET "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/topic-schemes" \
  -H "X-Api-Key: $DALP_API_TOKEN"

Each row includes the topic id, name, ABI data signature, registry address, and inheritanceLevel:

• token: registered on the token's own Topic Scheme Registry. These rows can be removed with the token delete route.
• system: inherited from the active system registry. These rows are visible here, but must be managed at the system level.
• global: inherited from the global registry. These rows are visible here, but must be managed at the global level.

The response also includes isShadowed for rows where another registry in the resolved chain registered the same numeric topic id with a different signature. Treat a shadowed row as a review signal before changing claim or compliance configuration.

{
  "data": [
    {
      "id": "0x3333333333333333333333333333333333333333#42",
      "topicId": "42",
      "name": "Accredited Investor",
      "signature": "(bool,uint256)",
      "registry": {
        "id": "0x3333333333333333333333333333333333333333"
      },
      "inheritanceLevel": "token",
      "isShadowed": false
    }
  ],
  "meta": {
    "total": 1,
    "hasTokenRegistry": true,
    "facets": {}
  },
  "links": {
    "self": "/v2/tokens/0x1111111111111111111111111111111111111111/topic-schemes"
  }
}

Use filter[q] to search across name, signature, and topic id. Use filter[source] to narrow the chain tier to token, system, or global. The default sort is by name.

If meta.hasTokenRegistry is false, the token has no token-level Topic Scheme Registry indexed yet. DALP can still show inherited system or global schemes, but the token add and remove controls should stay disabled until the token registry exists.

Add a token-specific scheme

Call POST /api/v2/tokens/{tokenAddress}/topic-schemes when the token needs its own claim data shape.

curl -X POST "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/topic-schemes" \
  -H "X-Api-Key: $DALP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Storage Attestation",
    "signature": "string,uint256"
  }'

The signature field is a comma-separated list of ABI parameter types. Submit string,uint256, not (string,uint256). DALP validates the list, wraps it into tuple form for the registry, and queues the on-chain registerTopicScheme call.

A scheme with the same name on the system or global tier does not block this request. A token-level scheme is a legitimate token override. A duplicate name on the same token-level registry returns a conflict instead of silently rewriting the claim data shape.

Synchronous completions return the created scheme name and transaction hash. Queued completions return transaction tracking data, so poll the transaction status endpoint before assuming the scheme is available to downstream claim or compliance configuration.

Remove a token-specific scheme

Call DELETE /api/v2/tokens/{tokenAddress}/topic-schemes/{topicId} to remove a row from the token-level registry.

curl -X DELETE "$DAPI_URL/api/v2/tokens/0x1111111111111111111111111111111111111111/topic-schemes/42" \
  -H "X-Api-Key: $DALP_API_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{}'

The request body is required by the v2 mutation wrapper. API-key requests can send an empty JSON object. Session-cookie requests include the walletVerification object in the same body.

The topicId path value is the numeric topic id as a decimal string. The delete route only removes token-specific schemes. DALP returns not found when the topic id belongs only to an inherited system or global scheme, when no matching token-level row exists, or when the indexer has not caught up to the token registry state.

Integration boundary

Topic schemes describe the claim data shape. They do not issue claims, verify an investor, or bypass transfer compliance on their own. After adding or removing a scheme, check the token's compliance expression, trusted issuers, and claim issuance flow before relying on the new scheme in production.

For the transfer-time compliance path, see Compliance transfer flow. For the conceptual identity model, see Claims and identity.