Token events

Use token events when your 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 endpoints when you need 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 Console 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. The following example shows a full response with one event:

{
  "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 the outer boundary. An event is included when any of the following is true.

• Its indexed tokenAddress is the path token.
• It was emitted by a contract whose parent_address is the path token, such as a feature or extension contract.
• It came from a per-token identity registry.
• The token appears in its indexed involved address list and the event is not denormalised to another token.

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

Filters

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

To narrow by wallet address, pass a single address with eq or a comma-separated list with inArray. The eq form matches one holder; inArray lets you compare multiple wallets in a single request:

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

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

To narrow by event name, use the eq operator. To match an exact transaction hash, prefer eq over the default iLike substring form:

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

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

To bound by a timestamp range, combine gte and lte on blockTimestamp:

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.

Console events table

The Console events screen for external tokens reads from this endpoint through ExternalTokenEventsTable. The table paginates server-side with useServerDataTable. The Platform API handles filtering, sorting, facets, and pagination.

Columns include timestamp, transaction index, event name, sender address, and emitter address.

Each row opens a detail sheet. Row controls copy the transaction hash or open the transaction in the configured block explorer.

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

Detail sheet behaviour

Clicking a row opens an event detail sheet with the following fields: sender address, asset address, timestamp, transaction hash, and event parameters from values[]. Parameter values are formatted by type where possible. Ethereum addresses display as addresses, hashes appear as transaction hashes, numeric strings appear 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 field.

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 endpoints
• API reference