# Account activity API reference Source: https://docs.settlemint.com/docs/api-reference/reference/account-activity Read the on-chain activity feed and activity time series for a single account address through the DALP Platform API, including meta-transaction attribution. An auditor reconstructing what an address did, or an operator checking that a sponsored transaction landed, needs every on-chain event that touches that address in one place. The account activity surface answers by address. It lists each indexed event where the address appears, and reports how many events that address produced over a window. These endpoints read by a single account address. To read every wallet a participant owns in one consolidated feed instead, use the [participant activity API](/docs/api-reference/reference/participant-activity). Either way the surface is read-only: it reports events that already happened, and it does not submit transactions or change state. ## Endpoints [#endpoints] | Endpoint | Use it for | | --------------------------------------------------------------- | --------------------------------------------------------------- | | `GET /api/v2/system/accounts/{accountAddress}/activities` | List the indexed events that involve the address, newest first. | | `GET /api/v2/system/accounts/{accountAddress}/activity-metrics` | Retrieve the address's event-count time series over a range. | The activities feed uses the collection envelope with `data`, `meta`, and pagination `links`. The metrics endpoint uses the single-resource envelope with `data` and `links.self`. The active organization and system context bound every read, as described in [Organization and system scope](/docs/api-reference/reference/organization-system-scope). ## Path parameters [#path-parameters] | Parameter | Type | Description | | ---------------- | ----------- | ------------------------------------------- | | `accountAddress` | EVM address | The address whose activity the query reads. | ## What counts as an event for the address [#what-counts-as-an-event-for-the-address] Both endpoints match an event to the address when the address appears as the sender, the account, the emitting contract, the token, the system, or any entry in the event's involved-address list. A single match on any of these places the event in the feed. This wide match means a transfer shows up for both sides of the transaction and for the token contract, so the same event can appear in the feed of several related addresses. ## Authorization [#authorization] The feed returns events for an address only when the caller is allowed to read that address. Four cases qualify as an allowed read. You can always read an address that belongs to your own wallet set, including your signing address and any smart wallet you control. A caller holding the `identityManager` or `claimIssuer` role can read an address their organization owns or an address registered as an identity in the active system. Any caller can read the activity of a price-feed address registered in the active system. A caller holding the `admin`, `systemManager`, `auditor`, or `gasManager` role can read the organization's configured bundler wallet or a paymaster address. For these infrastructure addresses, the feed also includes events on global contracts that carry no system address, so a bundler or paymaster panel shows the operations it relayed or sponsored. When the caller is not allowed to read the address, both endpoints return a valid, empty response rather than an error: `data` is empty, `meta.total` is `0`, and the metrics time series is flat. Treat an empty feed for an address you expected to be active as a possible permission gap, not proof of no activity. ## Activity event fields [#activity-event-fields] Each item in the activities feed describes one indexed blockchain event. | Field | Type | Description | | ----------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | | `id` | string | Unique identifier for the event. | | `eventName` | string | The event name, such as `TransferCompleted` or `MintCompleted`. | | `blockNumber` | string | Block number when the event occurred, as a decimal string for full precision. | | `blockTimestamp` | string | Timestamp when the event occurred. | | `txIndex` | string | Log index within the transaction. | | `transactionHash` | string | Hash of the transaction that produced the event. | | `emitter` | object | The contract that emitted the event, as `{ "id": "0x..." }`. | | `sender` | object | The address that triggered the event, as `{ "id": "0x..." }`. | | `displaySender` | object | The canonical originator: the signing address that authorized the operation. Prefer this for display. | | `metaTxSigner` | object or `null` | The signing address behind a meta-transaction. `null` for directly submitted transactions. | | `relayerKind` | string or `null` | The relayer type, such as `forwarder` or `user-operation`. `null` when no relayer was involved. | | `relayer` | object or `null` | The relayer address that submitted the meta-transaction. `null` when none was detected. | | `userOpHash` | string or `null` | The UserOperation hash, populated only for operations routed through the account-abstraction path. | | `paymaster` | object or `null` | The paymaster that sponsored the operation's gas, when one did. | | `actualGasCost` | string or `null` | Gas cost charged for the operation, in wei. Populated for all UserOperation events; use `paymaster` to determine whether the operation was sponsored. `null` for non-UserOperation events. | | `involved` | array | The addresses involved in the event, each as `{ "id": "0x..." }`. | | `values` | array | Decoded event parameters, each carrying `id`, `name`, and `value`. | ### Reading the attribution fields [#reading-the-attribution-fields] `sender` reports who triggered the event at the contract level. `displaySender` reports who authorized it. For a directly submitted transaction the two match. For a meta-transaction the contract sees the relayer or forwarder as the immediate caller, while the signing address behind the operation authorized it, which `displaySender` and `metaTxSigner` surface. Read `displaySender` when you want a single, stable answer to "who did this" without re-deriving it from the relayer fields. For a UserOperation, `actualGasCost` reports the gas cost in wei and `paymaster` names the address that sponsored it, when one did. A `null` paymaster means the sender paid the gas directly; a present paymaster means the gas was drawn from its deposit. Together they let an auditor reconcile activity against the paymaster balance. ## List account activity [#list-account-activity] `GET /api/v2/system/accounts/{accountAddress}/activities` returns the events that involve the address, newest first. The feed supports pagination, sorting by `blockTimestamp` or `blockNumber`, filtering by `eventName`, and global search with `filter[q]` against the event name. The default sort is newest first by `blockTimestamp`. ```bash curl --globoff "https://your-platform.example.com/api/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activities?filter[eventName]=TransferCompleted&page[limit]=50" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": [ { "id": "evt_123abc", "eventName": "TransferCompleted", "blockNumber": "20000000", "blockTimestamp": "2024-01-01T00:00:00Z", "txIndex": "0", "transactionHash": "0x1234567890abcdef1234567890abcdef1234567890abcdef1234567890abcdef", "emitter": { "id": "0x71C7656EC7ab88b098defB751B7401B5f6d8976F" }, "sender": { "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30" }, "displaySender": { "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30" }, "metaTxSigner": null, "relayerKind": null, "relayer": null, "userOpHash": null, "paymaster": null, "actualGasCost": null, "involved": [{ "id": "0x2546BcD3c84621e976D8185a91A922aE77ECEc30" }], "values": [{ "id": "evt_123abc-value-0", "name": "amount", "value": "1000000000000000000" }] } ], "meta": { "total": 1, "facets": { "eventName": [{ "value": "TransferCompleted", "count": 1 }] } }, "links": { "self": "/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activities?page[offset]=0&page[limit]=50", "first": "/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activities?page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activities?page[offset]=0&page[limit]=50" } } ``` The feed returns 50 events per page by default, up to 200. Use `page[offset]` and `page[limit]` to page through longer histories. The `eventName` field is faceted, so `meta.facets` reports the count of events under each event name in the current result set, which lets you build a filter without a second call. ### Filter and sort parameters [#filter-and-sort-parameters] | Parameter | Type | Description | | ------------------- | ------- | ------------------------------------------------------------------------------- | | `filter[eventName]` | string | Match a single event name exactly. Faceted, so counts appear in `meta.facets`. | | `filter[q]` | string | Free-text search against the event name. | | `sort` | string | `blockTimestamp` or `blockNumber`. Prefix with `-` for descending, the default. | | `page[limit]` | integer | Page size, up to 200. Defaults to 50. | | `page[offset]` | integer | Offset into the result set. | ## Retrieve account activity metrics [#retrieve-account-activity-metrics] `GET /api/v2/system/accounts/{accountAddress}/activity-metrics` returns a time series of event counts and a total for the address over a range. Supply a `range` object with an `interval` of `hour` or `day`, a `from` and `to` timestamp, and `isPreset` set to `false` for an explicit window. The series buckets the address's events by that interval across the window. When `from` is later than `to`, the endpoint returns an empty series rather than an error. ```bash curl --globoff "https://your-platform.example.com/api/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activity-metrics?range[interval]=day&range[from]=2024-01-01T00:00:00Z&range[to]=2024-01-07T00:00:00Z&range[isPreset]=false" \ -H "x-api-key: YOUR_API_KEY" ``` ```json { "data": { "timeSeries": [ { "timestamp": "2024-01-01T00:00:00Z", "count": 4 }, { "timestamp": "2024-01-02T00:00:00Z", "count": 0 }, { "timestamp": "2024-01-03T00:00:00Z", "count": 7 } ], "count": 11 }, "links": { "self": "/v2/system/accounts/0x2546BcD3c84621e976D8185a91A922aE77ECEc30/activity-metrics" } } ``` The series fills every interval in the window, so a quiet hour or day appears as a bucket with `count` set to `0` rather than a gap. `count` at the top level is the total across the whole window. Use the series to chart activity over time and the total to read volume for the range at a glance. ## When to use it [#when-to-use-it] Use these endpoints when you need to: * Produce an audit trail of every on-chain event that involved one address. * Confirm that a sponsored or relayed operation landed, and attribute it back to the signing address through `displaySender` and `metaTxSigner`. * Inspect a bundler or paymaster address to review the operations it relayed or sponsored. * Chart an address's activity over a window, or read its total event count for a range. To read every wallet a participant owns in one feed rather than a single address, see [Participant activity](/docs/api-reference/reference/participant-activity). For retries, readback checks, and reconciliation around these reads, see [Operational integration patterns](/docs/api-reference/reference/operational-integration-patterns).