Token events

Use token events when an integration needs an indexed activity trail for one token. The endpoint returns events emitted by the token contract and related token-owned contracts, including feature contracts and per-token identity registries.

Token events are REST reads for audit views, reconciliation jobs, support investigations, and token detail screens. They are not webhook deliveries. Use the webhook events catalogue for signed asynchronous deliveries.

Endpoint

GET /api/v2/tokens/{tokenAddress}/events

tokenAddress scopes the result set to one indexed token in the caller's active system context. The endpoint returns a collection envelope with:

• data: event rows
• meta: total count and facet counts
• links: pagination links for the current query

The default order is newest first by blockTimestamp. DALP also uses the event log index as a stable tie-breaker when multiple events share the same block and timestamp, so same-transaction setup events read in chain order in the dapp table.

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?page[limit]=50" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Event row shape

Each row describes one indexed event:

Example response shape:

{
  "data": [
    {
      "id": "evt_123abc",
      "eventName": "TransferCompleted",
      "txIndex": "0",
      "blockNumber": "20000000",
      "blockTimestamp": "2026-01-15T10:15:30.000Z",
      "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef",
      "emitter": {
        "id": "0x0000000000000000000000000000000000000001"
      },
      "sender": {
        "id": "0x0000000000000000000000000000000000000002"
      },
      "values": [
        {
          "id": "evt_123abc-account",
          "name": "account",
          "value": "0x0000000000000000000000000000000000000003"
        },
        {
          "id": "evt_123abc-amount",
          "name": "amount",
          "value": "1000000000000000000"
        }
      ]
    }
  ],
  "meta": {
    "total": 1,
    "facets": {
      "eventName": [{ "value": "TransferCompleted", "count": 1 }]
    }
  },
  "links": {
    "self": "/v2/tokens/0xTOKEN/events?page[limit]=50",
    "first": "/v2/tokens/0xTOKEN/events?page[offset]=0&page[limit]=50",
    "prev": null,
    "next": null,
    "last": "/v2/tokens/0xTOKEN/events?page[offset]=0&page[limit]=50"
  }
}

Which events are included

The token address in the path is always the outer boundary. The endpoint can include:

• events whose indexed tokenAddress is the path token
• events emitted by contracts whose parent_address is the path token, such as feature or extension contracts
• events from per-token identity registries
• events where the token appears in the indexed involved address list and the event is not denormalised to another token

The endpoint excludes unrelated activity from other tokens, even if the same wallet, sender, feature contract, or denomination asset appears in that activity.

Filters

Use collection-style filters for narrowing the result set. curl --globoff avoids shell expansion of bracketed query parameters.

Filter by wallet address:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[walletAddress][eq]=0xHOLDER" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter by multiple wallet addresses:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[walletAddress][inArray]=0xHOLDER1,0xHOLDER2" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter by event name:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[eventName][eq]=TransferCompleted" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter by exact transaction hash:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[transactionHash][eq]=0xTRANSACTION_HASH" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Filter by timestamp range:

curl --globoff "https://your-platform.example.com/api/v2/tokens/0xTOKEN/events?filter[blockTimestamp][gte]=2026-01-01T00:00:00Z&filter[blockTimestamp][lte]=2026-01-31T23:59:59Z" \
  -H "X-Api-Key: sm_dalp_xxxxxxxxxxxxxxxx"

Sorting and pagination

The default sort is -blockTimestamp. Use blockTimestamp for timeline views and blockNumber when an integration wants chain-height ordering.

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

For replay jobs:

1. Scope each reader to one token address.
2. Persist id, blockTimestamp, transactionHash, blockNumber, and txIndex for the last processed row.
3. Resume with an inclusive timestamp window or a paginated reread from the last checkpoint.
4. Reconcile against current holder or token metadata reads when you need the latest state, not only the historical event row.

Dapp events table

The external-token events screen uses the same endpoint through ExternalTokenEventsTable in the dapp. The table is server-side paginated with useServerDataTable, so filtering, sorting, facets, and pagination are applied by the API rather than by a browser-side slice of rows.

The table defaults are:

Columns shown by the component include timestamp, transaction index, formatted event name, sender address, emitter address, and row actions. Row actions open the detail sheet, copy the transaction hash, or open the transaction in the configured block explorer.

The component accepts an optional initialWalletAddressFilter. Feature deep links use that filter to open the table already narrowed to a wallet or feature contract address. The API expands that wallet filter across sender, account, and emitter roles.

Detail sheet behaviour

Clicking a row opens an event detail sheet. The sheet shows:

• sender address
• asset address
• timestamp
• transaction hash
• event parameters from values[]

Parameter values are formatted by type where possible. Ethereum addresses render as addresses, hashes render as transaction hashes, numeric strings render as numbers, and other values stay as text. The sender parameter is omitted from the parameter list because the sheet already shows sender as a top-level detail.

Relationship to webhook events

Token events are indexed REST reads for a token timeline. Webhook events are signed asynchronous deliveries for subscribed lifecycle changes. Use token events to backfill, replay, inspect, and reconcile. Use webhook events when another system needs a pushed notification and raw-body signature verification.

Related pages:

• Token holders and transfers
• Operational integration patterns
• Webhook events
• API reference