# Token factory registry API

Source: https://docs.settlemint.com/docs/api-reference/reference/token-factories
Read the token factories deployed on your system through the DALP Platform API. List every factory and its asset type, read one by address, and check whether an address is available before you deploy.



A token factory is the contract that mints one asset type on your system: the bond factory creates bonds, the equity factory creates equities, and so on. Before you create an asset, the matching factory has to exist on the system. This surface lets you read that registry. An integration or operations team uses it to confirm which asset types a system can issue, to look up a factory by address, and to check whether a deployment address is free before installing a new factory.

The surface is read-only. It reports the factories on your active system and changes nothing; deploying a new factory is a separate write operation outside this reference.

## Endpoints [#endpoints]

| Endpoint                                                 | Use it for                                                                                  |
| -------------------------------------------------------- | ------------------------------------------------------------------------------------------- |
| `GET /api/v2/system/factories`                           | List the token factories on the active system, with filtering, sorting, and faceted values. |
| `GET /api/v2/system/factories/{factoryAddress}`          | Read one token factory by its contract address.                                             |
| `GET /api/v2/system/factory-address-availability-checks` | Check whether an address or token configuration is free before a deployment.                |

The active organization and system context bound these reads, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope). The list returns the factories registered under the active system. The single read resolves a factory by its address on the active network and uses the system context to fill the implementation pointers. Pass an address you already hold from the list when you need a result scoped to the active system.

A system has a small, fixed set of factories, one per asset type it supports. When an organization has no system bootstrapped yet, the list returns an empty collection rather than an error, which lets an onboarding flow read the registry safely before setup completes.

## Factory fields [#factory-fields]

Each factory in the list and the single read describes one asset type and where its implementation lives.

| Field                    | Type             | Description                                                                                                       |
| ------------------------ | ---------------- | ----------------------------------------------------------------------------------------------------------------- |
| `id`                     | string           | The factory contract address.                                                                                     |
| `name`                   | string           | The factory name, such as `Bond Factory` or `Equity Factory`.                                                     |
| `typeId`                 | string           | The asset type the factory creates, such as `bond`, `equity`, `fund`, `deposit`, `stablecoin`, or `real-estate`.  |
| `hasTokens`              | boolean          | Whether the factory has created any tokens yet. Returned by the list read.                                        |
| `tokenExtensions`        | array            | The token extensions associated with the factory, such as `pausable` or `burnable`. Returned by the list read.    |
| `factoryImplementation`  | string or `null` | The registry-level implementation address for the factory itself. `null` when the indexer has not recorded it.    |
| `instanceImplementation` | string or `null` | The implementation that tokens deployed by this factory delegate to. `null` when the indexer has not recorded it. |

The two implementation pointers let you confirm both layers of a factory at once: the factory's own implementation and the implementation its deployed tokens share. Each pointer reads `null` until the indexer has recorded the factory-instance row for the system.

## List token factories [#list-token-factories]

`GET /api/v2/system/factories` returns the factories on the active system as a paginated collection. The default sort is `name` ascending.

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

```json
{
  "data": [
    {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "name": "Bond Factory",
      "typeId": "bond",
      "hasTokens": true,
      "tokenExtensions": ["pausable", "burnable"],
      "factoryImplementation": "0x1111111111111111111111111111111111111111",
      "instanceImplementation": "0x2222222222222222222222222222222222222222"
    },
    {
      "id": "0x3333333333333333333333333333333333333333",
      "name": "Equity Factory",
      "typeId": "equity",
      "hasTokens": false,
      "tokenExtensions": [],
      "factoryImplementation": "0x1111111111111111111111111111111111111111",
      "instanceImplementation": "0x2222222222222222222222222222222222222222"
    }
  ],
  "meta": {
    "total": 2,
    "facets": {
      "typeId": [
        { "value": "bond", "count": 1 },
        { "value": "equity", "count": 1 }
      ],
      "hasTokens": [
        { "value": "true", "count": 1 },
        { "value": "false", "count": 1 }
      ]
    }
  },
  "links": {
    "self": "/v2/system/factories?sort=name&page[offset]=0&page[limit]=50",
    "first": "/v2/system/factories?sort=name&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/system/factories?sort=name&page[offset]=0&page[limit]=50"
  }
}
```

### Filter and sort [#filter-and-sort]

The list accepts filtering, sorting, and search through standard query parameters. Use them to narrow the registry to the factories you care about.

| Field       | Filter | Sort | Notes                                                                          |
| ----------- | ------ | ---- | ------------------------------------------------------------------------------ |
| `id`        | yes    | yes  | Match a factory address. Address matching ignores case.                        |
| `name`      | yes    | yes  | Match on the factory name.                                                     |
| `typeId`    | yes    | yes  | Match an asset type such as `bond` or `equity`. Returned as a faceted value.   |
| `hasTokens` | yes    | yes  | Filter to factories that have or have not created tokens. Returned as a facet. |

Search across `id` and `name` with `filter[q]`. The response `meta.facets` lists the available values for `typeId` and `hasTokens`, so a UI can offer filter options that reflect the system's actual factories. For the full filter, sort, and pagination convention, see [Getting started](/docs/api-reference/reference/getting-started).

```bash
curl --globoff "https://your-platform.example.com/api/v2/system/factories?filter[typeId]=bond&filter[hasTokens]=true" \
  -H "x-api-key: YOUR_API_KEY"
```

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

Read a single factory by its contract address with `GET /api/v2/system/factories/{factoryAddress}`. The response carries the same fields as a list item, without the list-only `hasTokens` and `tokenExtensions` values.

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

```json
{
  "data": {
    "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "name": "Bond Factory",
    "typeId": "bond",
    "factoryImplementation": "0x1111111111111111111111111111111111111111",
    "instanceImplementation": "0x2222222222222222222222222222222222222222"
  },
  "links": {
    "self": "/v2/system/factories/0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }
}
```

### Errors [#errors]

| Status | Error       | When it happens                                                                                                                              |
| ------ | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `404`  | `DALP-0290` | No factory was found at the address. The system may not have finished bootstrapping, or the address is wrong. List the factories to confirm. |
| `404`  | `DALP-0291` | A contract exists at the address, but its type is not a recognized factory type. List the factories to see the recognized types.             |

For the full error model and how to read the `why` and `fix` fields, see [Error reference](/docs/api-reference/errors).

## Check availability [#check-availability]

`GET /api/v2/system/factory-address-availability-checks` reports whether an address or a token configuration is free, and returns a single flag. It works in two modes:

* Pass an `accessControl` address to check whether that address is already deployed on the active network.
* Pass token `parameters` (the asset type, name, symbol, and decimals, with an optional factory address) to check whether a token with that exact configuration already exists under the matching factory.

```json
{
  "data": {
    "isAvailable": true
  },
  "links": {
    "self": "/v2/system/factory-address-availability-checks"
  }
}
```

`isAvailable` is `true` when nothing occupies the address or matches the token configuration, and `false` when a deployed contract or an existing token already does. Read it before a deployment to catch a clash early.

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

Read the token factory registry when you need to:

* Confirm which asset types a system can issue before creating an asset.
* Look up a factory by address and read both its implementation layers in one call.
* Drive a UI that lists the factories on a system, filtered by asset type or by whether they have created tokens.
* Check whether an address or a token configuration is free before a deployment.

To understand how the active organization and system bound every read, see [Organization and system scope](/docs/api-reference/reference/organization-system-scope).