# System directory API

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/directory
Read the Directory-backed system contract catalog for the active network or a specific Directory contract.



The system directory endpoint returns the indexed Directory catalog for the active network.

Use this endpoint before token, compliance, or add-on API calls. It shows the contract implementations and type registries available from the network's Directory contract.

This is a read-only reference endpoint. It does not deploy contracts, register modules, or change token configuration.

## Endpoint [#endpoint]

```http
GET /api/v2/system/directory
```

By default, the API resolves the Directory contract from the active network configuration. Send `contract` only when you need to read a specific Directory contract address.

| Query parameter | Required | Description                                                                                                           |
| --------------- | -------- | --------------------------------------------------------------------------------------------------------------------- |
| `contract`      | No       | Directory contract address to read. If omitted, the API uses the Directory address configured for the active network. |

## Quick request [#quick-request]

```bash
curl "$API_URL/api/v2/system/directory" \
  --header "X-Api-Key: $API_TOKEN"
```

Read an explicit Directory contract:

```bash
curl "$API_URL/api/v2/system/directory?contract=0x1111111111111111111111111111111111111111" \
  --header "X-Api-Key: $API_TOKEN"
```

## Response shape [#response-shape]

A successful response uses the single-resource envelope. The `data` field contains one directory object or `null`.

```json
{
  "data": {
    "id": "0x1111111111111111111111111111111111111111",
    "systemImplementation": "0x2222222222222222222222222222222222222222",
    "systemAccessManagerImplementation": "0x3333333333333333333333333333333333333333",
    "forwarder": "0x4444444444444444444444444444444444444444",
    "systemFactory": "0x5555555555555555555555555555555555555555",
    "identityFactory": "0x6666666666666666666666666666666666666666",
    "identityFactoryImplementation": "0x7777777777777777777777777777777777777777",
    "identityImplementations": {
      "identityImplementation": "0x8888888888888888888888888888888888888888",
      "contractIdentityImplementation": "0x9999999999999999999999999999999999999999"
    },
    "systemImplementations": {
      "complianceImplementation": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
      "identityRegistryImplementation": "0xbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbbb",
      "identityRegistryStorageImplementation": "0xcccccccccccccccccccccccccccccccccccccccc",
      "trustedIssuersRegistryImplementation": "0xdddddddddddddddddddddddddddddddddddddddd",
      "trustedIssuersMetaRegistryImplementation": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
      "topicSchemeRegistryImplementation": "0xffffffffffffffffffffffffffffffffffffffff",
      "tokenAccessManagerImplementation": "0x1234567890123456789012345678901234567890",
      "tokenFactoryRegistryImplementation": "0x2345678901234567890123456789012345678901",
      "complianceModuleRegistryImplementation": "0x3456789012345678901234567890123456789012",
      "addonRegistryImplementation": "0x4567890123456789012345678901234567890123",
      "identityVerificationComplianceModule": "0x5678901234567890123456789012345678901234",
      "externalTokenRegistryImplementation": "0x6789012345678901234567890123456789012345"
    },
    "tokenTypes": [
      {
        "id": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "typeId": "0xaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaaa",
        "name": "Bond",
        "implementation": "0x7890123456789012345678901234567890123456",
        "factoryImplementation": "0x8901234567890123456789012345678901234567",
        "registeredAt": "2026-05-18T23:35:43.787Z",
        "isExperimental": false
      }
    ],
    "complianceModuleTypes": [
      {
        "id": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "typeId": "0xcccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccccc",
        "name": "IdentityVerification",
        "implementation": "0x9012345678901234567890123456789012345678",
        "registeredAt": "2026-05-18T23:35:43.787Z",
        "isExperimental": false
      }
    ],
    "addonTypes": [
      {
        "id": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "typeId": "0xeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeeee",
        "name": "XvP",
        "factoryImplementation": "0x0123456789012345678901234567890123456789",
        "registeredAt": "2026-05-18T23:35:43.787Z",
        "isExperimental": false
      }
    ]
  },
  "links": {
    "self": "/v2/system/directory"
  }
}
```

The exact type names and addresses depend on the indexed Directory state for the selected network. Treat addresses as network-specific values. Do not hard-code addresses from one environment into another.

## Top-level fields [#top-level-fields]

| Field                               | Description                                                                                   |
| ----------------------------------- | --------------------------------------------------------------------------------------------- |
| `id`                                | Directory contract address that the response describes.                                       |
| `systemImplementation`              | DALPSystem implementation address.                                                            |
| `systemAccessManagerImplementation` | System access manager implementation address.                                                 |
| `forwarder`                         | Trusted forwarder address for meta-transactions.                                              |
| `systemFactory`                     | System factory address.                                                                       |
| `identityFactory`                   | Identity factory proxy address.                                                               |
| `identityFactoryImplementation`     | Identity factory implementation address.                                                      |
| `systemImplementations`             | Core registry, compliance, token access, add-on, and external token implementation addresses. |
| `identityImplementations`           | Identity and contract identity implementation addresses.                                      |
| `tokenTypes`                        | Token type catalog available from this Directory.                                             |
| `complianceModuleTypes`             | Compliance module type catalog available from this Directory.                                 |
| `addonTypes`                        | Add-on type catalog available from this Directory.                                            |

## Type catalogs [#type-catalogs]

`tokenTypes`, `complianceModuleTypes`, and `addonTypes` use the `chainId` and Directory address from the lookup. Each catalog therefore matches the Directory contract in `data`. In these arrays, `id` and `typeId` are the same bytes32 type identifier.

Use `typeId` to decide which type identifiers are available before making mutation calls that resolve implementations from Directory state. For example, a compliance integration can read `complianceModuleTypes` before registering modules through the [Compliance modules API](/docs/developer-guides/api-integration/compliance-modules).

## Null response [#null-response]

The endpoint returns `data: null` when no indexed Directory row exists for the resolved network Directory address, or for the explicit `contract` address you provided.

```json
{
  "data": null,
  "links": {
    "self": "/v2/system/directory"
  }
}
```

A `data: null` response means the API did not find indexed Directory state for that address. Check that:

1. The network configuration points to the intended Directory contract.
2. The explicit `contract` value, if provided, is the Directory address for the same chain.
3. Indexing has processed the Directory deployment and related registry rows.

Do not treat `data: null` as an empty catalog. An empty catalog would still return a directory object with empty arrays. `data: null` means the Directory row itself was not found.

## When to use it [#when-to-use-it]

Use this endpoint when you need to:

* Display the system contract catalog for an operator or integration health check.
* Validate available token, compliance module, or add-on type identifiers before configuration.
* Confirm which Directory address is backing the active network environment.
* Diagnose why a type-based API request cannot resolve an implementation address.

For claim topic and trusted issuer setup, use [Configure trusted issuers](/docs/developer-guides/compliance/configure-trusted-issuers). For installed compliance module bindings, use [Compliance modules API](/docs/developer-guides/api-integration/compliance-modules).