# Token events Source: https://docs.settlemint.com/docs/developer-guides/api-integration/token-events Use the token events endpoint to read indexed on-chain events for one token, with collection pagination, filters, facets, and dapp table behaviour. 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](/docs/events) for signed asynchronous deliveries. ## Endpoint [#endpoint] ```http 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. ```bash 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 [#event-row-shape] Each row describes one indexed event: | Field | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Stable event identifier. Persist this with replay checkpoints when you mirror the feed. | | `eventName` | Contract event name, such as `TransferCompleted`, `MintCompleted`, `BurnCompleted`, or a feature event. | | `txIndex` | Indexed event log index, returned as a string for compatibility. Use it as the chain-order tie-breaker; do not treat it as a transaction-local counter. | | `blockNumber` | Block number as a decimal string. | | `blockTimestamp` | ISO timestamp for the indexed block. | | `transactionHash` | Transaction hash that produced the log. | | `emitter.id` | Contract address that emitted the event. This may be the token contract, a token feature contract, or a per-token registry. | | `sender.id` | Sender, account, or fallback contract address associated with the event. | | `values[]` | Projected event values. The current token-events projection includes `account` when an account address is indexed and `amount` when an amount is indexed. Values are strings. | Example response shape: ```json { "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 [#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 [#filters] Use collection-style filters for narrowing the result set. `curl --globoff` avoids shell expansion of bracketed query parameters. | Filter | Default operator | Notes | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------- | | `eventName` | `eq` | Facetable. Use it for event-type tabs or dropdown filters. | | `senderAddress` | `eq` | Matches the indexed sender role. | | `accountAddress` | `eq` | Matches the indexed account role. | | `walletAddress` | `eq` | Convenience filter that matches sender, account, or emitter address. Supports `eq` and `inArray`. | | `transactionHash` | `iLike` | Shorthand uses case-insensitive substring matching. Use `eq` for an exact transaction hash. | | `blockTimestamp` | date operators | Use `gte` and `lte` for bounded replay windows. | Filter by wallet address: ```bash 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: ```bash 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: ```bash 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: ```bash 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: ```bash 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 [#sorting-and-pagination] The default sort is `-blockTimestamp`. Use `blockTimestamp` for timeline views and `blockNumber` when an integration wants chain-height ordering. ```bash 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 [#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: | Behaviour | Value | | ------------------------------ | --------------------------------------------------- | | Dataset | `tokenAddress`, plus optional initial wallet filter | | Page size | 20 rows | | Initial sort | `blockTimestamp` descending | | Global search | Disabled | | Advanced filters | Enabled | | Export | Enabled | | Hidden columns at first render | `emitterAddress`, `txIndex` | 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 [#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 [#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](/docs/developer-guides/api-integration/token-holders-transfers) * [Operational integration patterns](/docs/developer-guides/api-integration/operational-integration-patterns) * [Webhook events](/docs/events) * [API reference](/docs/developer-guides/api-integration/api-reference)