Tokens pending role migration API

Overview

When you enable advanced accounts, each participant's roles move from their signing address onto the smart account that now transacts for them. The platform can only complete that move for a token when the wallet that ran the migration also holds the token's top-level admin role. For any other token, the participant keeps the roles on their signing address and the smart account holds none, so the smart account cannot act on that token until the token's own admin finishes the migration.

This endpoint returns the cross-token list of tokens still in that state. In one call, an operations team sees which tokens are waiting, how many participants each token affects, and which admin wallets can finish the migration. The same data drives the Tokens needing role migration list in the platform settings.

The endpoint is read-only. It reports which tokens still need migration and does not grant roles or run the migration itself.

Requirements

Before you call this endpoint:

• Authenticate with a DALP account that can read the active organization's tokens.
• Send list controls using the JSON:API query convention: sort, page[offset], page[limit], and filter[<field>].
• Pass --globoff to curl so it does not expand the square brackets in query parameters.

List tokens pending role migration

Load the list with pagination. The default sort is tokenName, ascending.

curl --globoff "https://your-platform.example.com/api/v2/tokens/aa-role-migration/pending?page[offset]=0&page[limit]=50&sort=tokenName" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

{
  "data": [
    {
      "tokenAddress": "0x1111111111111111111111111111111111111111",
      "tokenName": "Acme Senior Bond 2030",
      "tokenSymbol": "ASB30",
      "accessManagerAddress": "0x2222222222222222222222222222222222222222",
      "driftingParticipantCount": 3,
      "adminAddresses": ["0x3333333333333333333333333333333333333333"]
    }
  ],
  "meta": {
    "total": 1,
    "facets": {}
  },
  "links": {
    "self": "/v2/tokens/aa-role-migration/pending?page[offset]=0&page[limit]=50&sort=tokenName",
    "first": "/v2/tokens/aa-role-migration/pending?page[offset]=0&page[limit]=50&sort=tokenName",
    "prev": null,
    "next": null,
    "last": "/v2/tokens/aa-role-migration/pending?page[offset]=0&page[limit]=50&sort=tokenName"
  }
}

The response uses the standard DALP list envelope. data holds one row per token still pending migration, meta.total reports the full count across the active organization, and links carries pagination cursors. An empty data array means every asset in the organization is fully migrated.

Response model

Each row describes one token that still needs migration, the size of the gap, and who can close it.

A token appears only while at least one participant has a role the smart account cannot yet use. The count reflects participants, not roles: a participant missing several roles still counts once.

Filter and sort

The endpoint supports the JSON:API collection controls used across DALP list endpoints.

Sort on a supported field. Prefix the field with - for descending order. For example, sort by the most affected tokens first:

curl --globoff "https://your-platform.example.com/api/v2/tokens/aa-role-migration/pending?sort=-driftingParticipantCount" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter on a single column with filter[<field>]. For example, narrow to one token by symbol:

curl --globoff "https://your-platform.example.com/api/v2/tokens/aa-role-migration/pending?filter[tokenSymbol]=ASB30" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

adminAddresses is returned on every row but is not a filter or sort field. Read it from the response rather than querying on it.

Reporting view versus the per-token check

This list is a reporting view across the organization, derived from indexed role data. The list can briefly lag the chain. A token can stay listed for a short time after the token's roles are migrated on-chain, until indexing catches up. Treat the list as a "needs attention" overview rather than the final word on a single token.

When you act on one specific token, rely on the token's own role view, which checks current role state directly. The token page also shows a live migration warning and a Migrate roles control for that token.

Use the CLI

The same list is available from the DALP CLI for quick checks:

dalp tokens aa-role-migration-pending

The CLI accepts the same pagination, sort, and filter controls as flags. You can use them to script periodic reviews:

dalp tokens aa-role-migration-pending --sort -driftingParticipantCount --page-limit 50

Use the CLI for ad hoc reviews and the API when you build dashboards or governance tooling around outstanding migrations.

Related

• Complete token role migration: the operator how-to for finishing a token's migration as its admin.
• Participant role assignments API: read per-token and deployment-wide role assignments, including the drift signal for a single token.
• Advanced accounts: the model behind signing addresses and smart accounts.
• Error handling: retry and failure-handling patterns.