External tokens

An external token is an EVM token contract registered in the active system's external token registry. Registration does not deploy a token, move balances, or import holder history. The platform records the token address and assigned type so it can list the token, index registry metadata, and route operators to token detail and event views.

Use this reference when you need to inspect a contract address, register an on-chain token, or list tokens already recorded as external.

What external-token registration provides

External-token registration makes an on-chain contract visible to the active system. After the registry event is indexed, operators can find the token in external-token lists, and you can query registration metadata through the API or navigate to the token detail and event views.

Registration does not convert the contract into a DALP-issued asset. The platform adds no compliance rules, supply controls, holder onboarding, transfer hooks, reserve checks, or custody policies to an external contract. Rely on the token's own contract, issuer controls, and off-platform operating model for those guarantees.

Registration flow

The flow has two gates. The inspection gate confirms that the address has deployed code and is not already system-managed or registered. The registration gate records the caller-supplied token type in the active system's registry. List and detail views update after the registry event is indexed.

Prerequisites

• The active system has an external token registry configured.
• The effective executor has the system token manager role required for token-create operations.
• The token contract address exists on the active EVM network.
• API-key calls can omit walletVerification. User-session calls that sign with a wallet include wallet verification for the transaction.

Quickstart

Inspect the contract address first. Submit the registration only when registration.eligible is true; any other value means the address is ineligible and the platform will reject the call.

GET /api/v2/contracts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F

{
  "data": {
    "address": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
    "hasCode": true,
    "token": {
      "name": "Northwind Settlement Token",
      "symbol": "NWST",
      "decimals": 18,
      "totalSupply": "1000000"
    },
    "isSmart": true,
    "knownTo": null,
    "registration": {
      "eligible": true,
      "blockingReason": null
    }
  },
  "links": {
    "self": "/api/v2/contracts/0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  }
}

Then register the token with the type operators should see in DALP:

POST /api/v2/external-tokens
Content-Type: application/json
Idempotency-Key: ext-token-nwst-2026-05

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

The response uses the blockchain mutation envelope shape. Synchronous responses include the registered token address, transaction hashes, and a self link. The handler encodes a registerToken(tokenAddress, tokenType) call against the registry and submits it through the transaction queue.

{
  "data": {
    "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F"
  },
  "meta": {
    "txHashes": ["0x6d3f8e4f6e9a7b5c4d3e2f1a0b9c8d7e6f5a4b3c2d1e0f9a8b7c6d5e4f3a2b1c"]
  },
  "links": {
    "self": "/v2/external-tokens"
  }
}

When the request uses asynchronous transaction processing, the platform returns an accepted transaction state instead:

{
  "transactionId": "018f2b79-7f3c-7a3d-9f60-29b2cf4d8a40",
  "status": "QUEUED",
  "statusUrl": "/api/v2/transaction-requests/018f2b79-7f3c-7a3d-9f60-29b2cf4d8a40"
}

When registering through a user session that requires wallet verification, include the verification payload with the same request body. API-key integrations can omit this object when the deployment policy allows server-side execution.

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

For Console steps, see Register external tokens in the Console.

Contract inspection fields

The contract inspector combines data from the active-system indexer with best-effort on-chain reads. Use it as the preflight gate for registration forms and API clients.

A no-code blocking reason means the address has no deployed bytecode on the active chain. Do not submit that address as an external token.

Register request fields

The platform requires an explicit asset class: the address alone does not determine it. Send the type that operators should see in the external token list. The Console offers common choices for consistency, while API and CLI integrations pass the string you supply.

List external tokens

GET /api/v2/external-tokens?page[limit]=20&page[offset]=0&sort=-externalRegisteredAt&filter[q]=northwind

{
  "data": [
    {
      "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "name": "Northwind Settlement Token",
      "symbol": "NWST",
      "decimals": 18,
      "totalSupply": "1000000",
      "totalSupplyExact": "1000000000000000000000000",
      "type": "stablecoin",
      "pausable": {
        "paused": false
      },
      "externalRegisteredAt": "2026-03-21T12:00:00.000Z",
      "externalRegisteredBy": {
        "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30"
      },
      "externalDetectedInterfaces": ["ERC20", "ERC3643", "SMART"],
      "implementsERC3643": true,
      "implementsSMART": true
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "type": [{ "value": "stablecoin", "count": 1 }],
      "paused": [{ "value": "active", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/external-tokens?page%5Blimit%5D=20&page%5Boffset%5D=0&sort=-externalRegisteredAt&filter%5Bq%5D=northwind",
    "first": "/v2/external-tokens?page%5Blimit%5D=20&page%5Boffset%5D=0&sort=-externalRegisteredAt&filter%5Bq%5D=northwind",
    "prev": null,
    "next": null,
    "last": "/v2/external-tokens?page%5Blimit%5D=20&page%5Boffset%5D=0&sort=-externalRegisteredAt&filter%5Bq%5D=northwind"
  }
}

The list endpoint uses the standard collection shape: data, meta, and links. The endpoint accepts JSON:API bracket parameters such as page[offset], page[limit], sort, and supported field filters such as filter[type]. The SDK also accepts flat shorthand because the contract normalizes both forms.

What DALP indexes for external tokens

The platform lists external tokens from the current system's external token registry. The list is scoped to the active organization, the configured chain, and the current registry address, so a token recorded in a different system does not appear until you register it here.

The indexer-backed list can show registry metadata and token facts when those records are available:

External-token registration gives the platform a reference to an on-chain contract. Historical balances, the issuer's compliance model, DALP transfer rules, and off-chain backing proofs all remain outside this surface. Treat it as an integration and reconciliation entry point for an already deployed EVM token.

List fields and filters

Only name, symbol, type, and externalRegisteredAt are accepted as public list query fields for sort and filter[...]. Global search uses filter[q] and matches against token name, symbol, and the assigned classification.

The Console External Tokens table uses the same endpoint, sorts by registration time by default, and lets operators copy the address, open the configured block explorer, export the table, or navigate to the token detail page.

Supporting surfaces

The API, Console, and CLI share the same registration contract. Each surface targets a different operator workflow.

Current and legacy API contracts

Prefer the /api/v2 endpoints for new integrations. The v2 list endpoint adds pagination links, collection metadata, typed facets, and standard filter semantics that the legacy wrapper lacks.

CLI commands

Use the CLI for the same list and registration operations:

dalp external-tokens list
dalp external-tokens register --token-address 0x71C7656EC7ab88b098defB751B7401B5f6d8976F --token-type stablecoin

--token-type is the same caller-supplied classification as the API tokenType field. Use the shared business vocabulary your operators expect to see in DALP.

Error handling

A DALP-9079 response is a transient transport result, not a verdict about the token. This error is the retryable counterpart to the permanent "not an ERC-20" outcome: a contract that genuinely lacks readable symbol() and decimals() is rejected as a non-retryable client fault, while an RPC blip while reading those values returns the retryable 503 above. The registration endpoint returns the typed retryable 503 with the Retry-After header and the data.retryAfterSeconds hint. Treat DALP-9079 as a backoff-and-retry signal in your registration client.

The already-registered preflight reason and the DALP-1079 contract error describe the same condition at two different points. The preflight reason appears on contract inspection so a client can block submission prior to sending a transaction. DALP-1079 is the contract-level rejection a client receives when it submits the registration anyway, either by skipping inspection or by losing a race to another caller that registered the same address first. Require registration.eligible on the inspected address to avoid the duplicate path. See the Platform API error reference for the shared error envelope.

Production checks

Before you ship an external-token integration:

• Inspect the address and require registration.eligible before you submit registration.
• Use one idempotency key per logical registration attempt.
• Store the returned transaction hash or transaction status URL with your integration log.
• Treat the token type as an explicit business classification, not as an inferred fact from the contract address.
• Confirm that the active system and network match the token contract address.
• Retry registration calls that return a retryable 503 after the Retry-After interval, with a bounded give-up.
• Show delayed indexer metadata as pending instead of failed when the registry transaction is still processing.
• Keep wallet verification out of logs and never store verification codes.

External-token registration is an audit-relevant system mutation. Your integration should retain who requested the registration, the token address, the assigned type, the transaction reference, and the registration record as indexed, where your compliance process requires evidence.

Related pages

• Contract inspector API
• Register external tokens in the Console
• Token lifecycle
• Request headers
• Platform API error reference
• CLI command reference
• Supported networks