System directory API for contract catalog reads

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

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.

Quick request

The default call reads the Directory contract configured for the active network. Omit contract unless you need to target a different address:

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:

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

Response shape

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

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

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.

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:

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

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.

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

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. To audit the platform-wide trusted issuers already registered and the claim topics each may attest, use the Directory trusted issuers API. To read the platform-wide claim topic scheme catalog, use the Directory topic schemes API. For installed compliance module bindings, use Compliance modules API.