# System directory API for contract catalog reads Source: https://docs.settlemint.com/docs/api-reference/reference/directory Read the Directory-backed system contract catalog for the active network or a specific Directory contract. Call this endpoint before token, compliance, or add-on API calls to read the contract implementations and type registries that the network's Directory contract exposes. The response lists each registered implementation, type registry, and add-on slot for the resolved Directory address. The endpoint is read-only. 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] The default call reads the Directory contract configured for the active network. Omit `contract` unless you need to target a different address: ```bash curl "$API_URL/api/v2/system/directory" \ --header "X-Api-Key: $API_TOKEN" ``` To read a specific Directory contract, pass its address in the `contract` query parameter. The response describes the state indexed for that address: ```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", "kind": "factory", "factoryImplementation": "0x0123456789012345678901234567890123456789", "instanceImplementation": "0x1234567890123456789012345678901234567890", "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/api-reference/compliance/compliance-modules). ### Factory and instance implementation addresses [#factory-and-instance-implementation-addresses] A factory-backed type registration carries two implementation addresses, because the component is two layers. The factory implementation is the registry-level contract that deploys instances. The instance implementation is the logic contract that each factory-deployed proxy delegates to. The two layers can move independently, so a current factory paired with a stale instance implementation still leaves deployed proxies running older logic. The catalog entries expose this as follows: | Field | Type catalog | Description | | ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------ | | `factoryImplementation` | `tokenTypes`, `addonTypes` | Registry-level implementation pointer. For factory-backed types, this is the factory that deploys instances. | | `implementation` | `tokenTypes` | Instance implementation that factory-deployed token proxies delegate to. | | `kind` | `addonTypes` | Add-on classification: `factory`, `singleton`, or `unknown`. | | `instanceImplementation` | `addonTypes` | Instance implementation that factory-deployed add-on proxies delegate to. `null` for non-factory add-ons. | For add-ons, `kind` tells you how to read the implementation fields. A `factory` add-on populates both `factoryImplementation`, the registry-level factory that deploys add-on proxies, and `instanceImplementation`, the logic those proxies delegate to. A `singleton` add-on runs from one contract: `factoryImplementation` holds that single registry-level implementation pointer rather than a deploying factory, and `instanceImplementation` is `null`. An `unknown` kind covers unclassified legacy registrations, which also return a `null` instance implementation. Token types always carry both `factoryImplementation` and `implementation`. ## 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/developers/compliance/configure-trusted-issuers). To audit the platform-wide trusted issuers already registered and the claim topics each may attest, use the [Directory trusted issuers API](/docs/api-reference/reference/directory-trusted-issuers). To read the platform-wide claim topic scheme catalog, use the [Directory topic schemes API](/docs/api-reference/reference/directory-topic-schemes). For installed compliance module bindings, use [Compliance modules API](/docs/api-reference/compliance/compliance-modules).