# Token topic schemes

Source: https://docs.settlemint.com/docs/developers/api-integration/tokens/token-topic-schemes
Read inherited claim topic schemes for a token and register token-specific schemes through the DALP API.



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 [#endpoint-summary]

| Operation             | Endpoint                                                       | Use it to                                                             |
| --------------------- | -------------------------------------------------------------- | --------------------------------------------------------------------- |
| List topic schemes    | `GET /api/v2/tokens/{tokenAddress}/topic-schemes`              | Read the resolved token, system, and global scheme chain for a token. |
| Add a token scheme    | `POST /api/v2/tokens/{tokenAddress}/topic-schemes`             | Register a scheme on the token-level Topic Scheme Registry.           |
| Remove a token scheme | `DELETE /api/v2/tokens/{tokenAddress}/topic-schemes/{topicId}` | Remove a token-specific scheme by numeric topic id.                   |

## List effective topic schemes [#list-effective-topic-schemes]

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

```bash
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.

```json
{
  "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 [#add-a-token-specific-scheme]

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

```bash
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 [#remove-a-token-specific-scheme]

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

```bash
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 [#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](/docs/architects/flows/compliance-transfer). For the conceptual identity model, see [Claims and identity](/docs/architects/concepts/claims-and-identity).