Tokens pending role migration

This endpoint lists the tokens whose access-control roles still need to be mirrored onto participants' smart accounts after the advanced-accounts migration. An auditor or operator reads it to find every token still waiting, see how many participants each one affects, and see which admin addresses can finish the job.

When a deployment turns on advanced accounts, the platform mirrors each participant's roles from their signing address onto their smart account, so operations routed through the smart account carry the same authority. The platform can mirror a token's roles automatically only when the account that ran the migration is that token's admin. For any token where it was not, the roles stay unmirrored and that token's own admin has to finish the migration, which is why the token appears here. The endpoint is a read: it never changes state and never moves a token.

When to use this read

Call this endpoint to build the work list for finishing advanced-accounts role migration. Each item names a token whose access-manager roles are not yet fully mirrored onto participants' smart accounts, reports the count of affected participants, and lists the admin addresses that can finish the migration for that token. The Console advanced-accounts settings page uses this read to drive its pending-tokens list.

List the pending tokens

The endpoint takes no path parameter. It returns the pending tokens for the active organisation and system as a standard DALP collection: data for the page of items, meta for the total count, and links for pagination. This endpoint defines no facetable fields, so meta.facets is always an empty object.

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

A successful response lists each token still waiting on a role migration:

{
  "data": [
    {
      "tokenAddress": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F",
      "tokenName": "Series A Note",
      "tokenSymbol": "SERA",
      "accessManagerAddress": "0x8ba1f109551bD432803012645Ac136ddd64DBA72",
      "driftingParticipantCount": 3,
      "adminAddresses": ["0xAb5801a7D398351b8bE11C439e05C5B3259aeC9B"]
    }
  ],
  "meta": {
    "total": 1,
    "facets": {}
  },
  "links": {
    "self": "/v2/tokens/aa-role-migration/pending?sort=tokenName&page[offset]=0&page[limit]=50",
    "first": "/v2/tokens/aa-role-migration/pending?sort=tokenName&page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/tokens/aa-role-migration/pending?sort=tokenName&page[offset]=0&page[limit]=50"
  }
}

When no token is pending, data is an empty array and meta.total is 0. The endpoint returns a list with no items, not an error, when the active organisation has no system configured or no token needs migration. Treat that result as a normal signal that no migration work is outstanding.

Item fields

Query the list

The endpoint accepts the standard collection query parameters: pagination with page[limit] and page[offset], and sorting with sort. The default sort is by tokenName. You can filter on tokenAddress, tokenName, tokenSymbol, accessManagerAddress, and driftingParticipantCount. The adminAddresses field is returned in each item but is not a filterable or sortable field.

To list the most affected tokens first, sort by descending drifting-participant count:

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

To find pending tokens by name, filter on tokenName:

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

This endpoint computes no facets, so meta.facets is always an empty object. To summarise the pending set by a field, read the data page and aggregate the values you need.

How the list resolves

A token appears on this list when at least one participant holds a role on their signing address that their smart account is missing. The platform can mirror those roles automatically only when the account that ran the advanced-accounts migration is the token's admin. Where it was not, the token's own admin holders, returned in adminAddresses, complete the migration from the token page.

The list is an indexed snapshot with eventual consistency. A token may stay on the list for a short interval after its roles are migrated on-chain, until the index catches up. The token page verifies live role state before it shows or clears its migration prompt, so use that page as the authority for a single token and this endpoint for the deployment-wide work list.

Related

• Participant role assignments for the per-participant role state, including the drift signal this list aggregates.
• Complete token role migration for the operator workflow that finishes the migration for a token.
• Advanced accounts control center for the settings page that hosts the pending-tokens list.
• Organization and system scope for how the active organisation and system context bound every read.