# System addon factory registry API reference

Source: https://docs.settlemint.com/docs/api-reference/reference/addon-factories
List and read the system addon factories registered on the active DALP system through the Platform API, including type, kind, deployment, and implementation fields.



A system addon factory is an extension installed on a DALP system that adds capability beyond the core token contracts, such as XvP settlement, token sales, or fixed yield schedules. Each installed addon is registered under the system's addon registry, and these endpoints let an integration read that registry directly instead of through the Console.

Use them when you need to confirm which extensions a system runs, resolve an addon factory address before you call an addon workspace, or audit the implementation contracts an addon delegates to. For the operator workflow that installs and opens addons, see [System addons](/docs/operators/system-addons/introduction).

## Endpoints [#endpoints]

| Endpoint                                              | Use it for                                                |
| ----------------------------------------------------- | --------------------------------------------------------- |
| `GET /api/v2/system/addon-factories`                  | List the addon factories registered on the active system. |
| `GET /api/v2/system/addon-factories/{factoryAddress}` | Read one addon factory by its contract address.           |

The list response uses the DALP collection envelope with `data`, `meta`, and pagination `links`. The single read uses the single-resource envelope with `data` and `links.self`.

Both endpoints resolve the active system from the caller's organisation context. Set the participant and wallet context with the standard request headers before calling them. See [Request headers](/docs/api-reference/reference/request-headers).

## Addon kinds [#addon-kinds]

Every addon carries a `kind` that describes how it is implemented on chain.

* **`singleton`**: one registry-level contract serves the whole system. The `systemAddonImplementation` field holds its implementation address.
* **`factory`**: the addon deploys a separate proxy per instance, such as one contract per XvP settlement or token sale. The `factoryImplementation` field holds the factory implementation, and `instanceImplementation` holds the implementation each deployed proxy delegates to.
* **`unknown`**: a legacy or unclassified registration whose kind the registry cannot resolve.

## List addon factories [#list-addon-factories]

`GET /api/v2/system/addon-factories` returns the addon factories registered under the active system, with their type, kind, deployment transaction, and Directory implementation addresses. When the system has no registered addons, or before a system is bootstrapped, the list is empty.

The list supports pagination, global search across `id` and `name`, and sorting by `id`, `name`, or `typeId`. The default sort is `name` ascending. You can filter on these fields:

| Filter    | Matches on                                                    |
| --------- | ------------------------------------------------------------- |
| `id`      | Addon contract address, case-insensitive.                     |
| `name`    | Addon name, partial text.                                     |
| `typeId`  | Addon type, exact value. Facetable.                           |
| `account` | Deployer address, exact value.                                |
| `kind`    | `singleton`, `factory`, or `unknown`, exact value. Facetable. |

Faceted counts are returned for `typeId` and `kind`, so a client can show how many addons of each type and implementation kind a system runs.

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/addon-factories?filter[kind]=factory&sort=name" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": [
    {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "name": "XvP Settlement",
      "typeId": "xvp-settlement",
      "deployedInTransaction": "0xabcdef1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef12",
      "account": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30",
      "kind": "factory",
      "systemAddonImplementation": null,
      "factoryImplementation": "0xCf7Ed3AccA5a467e9e704C703E8D87F634fB0Fc9",
      "instanceImplementation": "0xDc64a140Aa3E981100a9becA4E685f962f0cF6C9"
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "typeId": [{ "value": "xvp-settlement", "count": 1 }],
      "kind": [{ "value": "factory", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/system/addon-factories?filter[kind]=factory&sort=name&page[offset]=0&page[limit]=50",
    "first": "/v2/system/addon-factories?filter[kind]=factory&sort=name&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/addon-factories?filter[kind]=factory&sort=name&page[offset]=0&page[limit]=50"
  }
}
```

### List fields [#list-fields]

Each item in the list response carries these fields:

| Field                       | Type             | Description                                                                          |
| --------------------------- | ---------------- | ------------------------------------------------------------------------------------ |
| `id`                        | string           | The addon contract address.                                                          |
| `name`                      | string           | The addon name, such as `XvP Settlement` or `Yield Schedule`.                        |
| `typeId`                    | string           | The addon type, such as `xvp-settlement` or `fixed-yield-schedule`.                  |
| `deployedInTransaction`     | string           | The transaction hash where the addon was deployed.                                   |
| `account`                   | string           | The account that deployed the addon.                                                 |
| `kind`                      | string           | How the addon is implemented: `singleton`, `factory`, or `unknown`.                  |
| `systemAddonImplementation` | string or `null` | Registry-level singleton implementation. Set for `singleton` kind only.              |
| `factoryImplementation`     | string or `null` | Factory implementation registered in the Directory.                                  |
| `instanceImplementation`    | string or `null` | Implementation that deployed addon proxies delegate to. Set for `factory` kind only. |

## Read one addon factory [#read-one-addon-factory]

`GET /api/v2/system/addon-factories/{factoryAddress}` reads a single addon factory by its contract address on the active network. The response carries the addon's identity, type, and detected contract version.

```bash
curl "https://your-platform.example.com/api/v2/system/addon-factories/0x71C7656EC7ab88b098defB751B7401B5f6d8976F" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "data": {
    "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "name": "XvP Factory",
    "typeId": "xvp-settlement",
    "version": 2,
    "type": "xvp-settlement"
  },
  "links": {
    "self": "/v2/system/addon-factories/0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }
}
```

### Read fields [#read-fields]

| Field     | Type   | Description                                                                         |
| --------- | ------ | ----------------------------------------------------------------------------------- |
| `id`      | string | The addon contract address.                                                         |
| `name`    | string | The addon factory name.                                                             |
| `typeId`  | string | The addon type, such as `xvp-settlement` or `fixed-yield-schedule`.                 |
| `version` | number | Contract version detected on chain. Defaults to `1` when no later version is found. |
| `type`    | string | The addon type. Holds the same value as `typeId`.                                   |

When the address is not registered as an addon factory on the active system, the read returns `404` with error code `DALP-0227`. See the [Platform API error reference](/docs/api-reference/errors/platform-api-error-reference).