# External tokens

Source: https://docs.settlemint.com/docs/developer-guides/api-integration/external-tokens
Register and list tokens that were not deployed through DALP factories so they can be tracked from the external token registry.



External tokens are token contracts deployed outside the active DALP system's asset factories. Registration adds an existing token to the system's external token registry. After registration, DALP can list the token, index registration metadata, and route users to token detail and event views.

Use this flow when you need DALP to track an existing EVM token alongside assets created in DALP.

## Prerequisites [#prerequisites]

* The active system has an external token registry configured.
* The caller has the `tokenManager` system role required to register tokens.
* The token contract address is on the active EVM network.
* API-key requests can omit `walletVerification`; user-session requests that sign with a wallet must include wallet verification for that transaction.

## Register an external token [#register-an-external-token]

Submit the token contract address and the token type you want DALP to assign to it. API-key auth callers do not need to send `walletVerification`:

```http
POST /api/v2/external-tokens
Content-Type: application/json

{
  "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "tokenType": "stablecoin"
}
```

When registering through a user session that requires wallet verification, include the wallet verification payload with the request:

```json
{
  "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
  "tokenType": "stablecoin",
  "walletVerification": {
    "secretVerificationCode": "123456",
    "verificationType": "PINCODE"
  }
}
```

The registration is an on-chain transaction. DALP queues the registry call and returns an asynchronous blockchain mutation response with the registered token address and transaction status information.

The dApp exposes the same flow from **External Tokens**. Select **Register External Token**, enter the token address, choose a token type such as bond, equity, fund, stablecoin, deposit, cryptocurrency, or other, then complete wallet verification.

## List registered external tokens [#list-registered-external-tokens]

Read registered external tokens with:

```http
GET /api/v2/external-tokens
```

The response uses the standard paginated collection shape with `data`, `meta`, and `links`. Each row can include:

* contract address, name, symbol, decimals, and total supply
* assigned token type
* paused or active status when the token exposes pausable state
* registration timestamp and registering account when indexed registration events are available
* detected interfaces when the token reports them, including SMART and ERC-3643 indicators

The list route supports pagination, sorting, filters, type and status facets, and search across token name, symbol, and assigned type. The default dApp table sorts by registration time and lets users filter, export, copy the address, open the configured block explorer, or navigate to the external token detail page.

## Operational notes [#operational-notes]

* Registration does not deploy a new token contract. It records an existing EVM token in the registry.
* DALP assigns the provided token type during registration; it does not infer the asset class from the address alone.
* SMART and ERC-3643 indicators are shown only when detected interface data is available.
* If the external token registry is missing from the active system, registration fails with `DALP-0122`; REST clients see it as `error.id`, and oRPC JSON-RPC clients see it as `data.dapiError.id`. See the [DAPI error reference](/docs/developer-guides/api-integration/dapi-error-reference).

Related pages:

* [Token lifecycle](/docs/developer-guides/api-integration/token-lifecycle)
* [CLI command reference](/docs/developer-guides/cli/command-reference)
* [Supported networks](/docs/architecture/integrations/supported-networks)