# Participant activity API reference Source: https://docs.settlemint.com/docs/api-reference/reference/participant-activity Read a participant's on-chain activity feed and activity time series across every wallet they own, EOA and smart wallet, through the DALP Platform API. A participant's activity is the record of on-chain events that touch any wallet they own. A participant can act through a signing address, an externally owned account, and through a smart wallet when advanced accounts is enabled. Both produce events. An auditor or operator needs one feed that covers all of a participant's wallets, not a separate query per address. These endpoints provide that consolidated view. Two surfaces sit under one participant. The activity feed lists the individual events, newest first, for an audit trail or transaction history. The activity metrics endpoint returns a time series of event counts for the same wallet set, for a chart or a volume check over a window. This surface is read-only. It reports events that already happened. It does not submit transactions or change state. ## Endpoints [#endpoints] | Endpoint | Use it for | | ----------------------------------------------------------- | ---------------------------------------------------------------- | | `GET /api/v2/participants/{participantId}/activities` | List the events involving any of the participant's wallets. | | `GET /api/v2/participants/{participantId}/activity-metrics` | Retrieve the participant'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 organisation 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 | | --------------- | ------ | -------------------------------------------------- | | `participantId` | string | The participant whose wallet set drives the query. | ## What "any wallet" means [#what-any-wallet-means] Both endpoints resolve the participant's full wallet set first, then match events against it. An event counts as the participant's when any of their wallet addresses appears as the sender, the account, the emitting contract, the token, an entry in the event's involved-address list, or the meta-transaction signer. This last match matters for advanced accounts: a smart-wallet operation submitted through a relayer still attributes to the participant who authorised it, so the feed shows both directly submitted transactions and relayed ones in a single stream. ## Authorisation [#authorisation] A participant can read their own activity. A reviewer reads another participant's activity when they hold the `identityManager` or `claimIssuer` role for the active system. A caller who is neither the participant nor a holder of one of those roles still gets a valid response for a participant in their organisation, but the result is empty: `data` is empty, `meta.total` is `0`, and the time series is flat. Treat an empty feed for a participant you expected to be active as a possible permission gap, not proof of no activity. The empty-result behaviour applies only when the participant exists in the caller's organisation. When the participant id does not resolve in the active organisation, both endpoints return `DALP-0524` with status 404 instead. The response does not reveal whether the participant exists elsewhere, so a participant in another tenant returns the same 404 as one that does not exist at all. Confirm the participant id and the active organisation before retrying. ## 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 authorised 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 a sponsored operation, in wei. `null` for events that were not sponsored. | | `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 authorised it. For a directly submitted transaction the two match. For a meta-transaction the contract sees the relayer or forwarder as the immediate caller, but the participant's signing address authorised the transfer, 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. ## List participant activity [#list-participant-activity] `GET /api/v2/participants/{participantId}/activities` returns the events involving any of the participant's wallets, 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/participants/par_01HXYZ/activities?filter[eventName]=TransferCompleted" \ -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": {} }, "links": { "self": "/v2/participants/par_01HXYZ/activities?page[offset]=0&page[limit]=50", "first": "/v2/participants/par_01HXYZ/activities?page[offset]=0&page[limit]=50", "prev": null, "next": null, "last": "/v2/participants/par_01HXYZ/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 how many events carry each event name in the current result set, which you can use to build a filter without a second call. ## Retrieve participant activity metrics [#retrieve-participant-activity-metrics] `GET /api/v2/participants/{participantId}/activity-metrics` returns a time series of event counts and a total, computed over the same wallet set as the feed. 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 participant'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/participants/par_01HXYZ/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/participants/par_01HXYZ/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 a participant took part in, across all their wallets. * Reconstruct a participant's transaction history without querying each wallet address separately. * Attribute a relayed or sponsored operation back to the signing address that authorised it, through `displaySender` and `metaTxSigner`. * Chart a participant's activity over a window, or read the total event count for a range. To read the activity of a single address rather than a participant's whole wallet set, see [Account activity](/docs/api-reference/reference/account-activity). To read participant role assignments rather than activity, see [Participant role assignments](/docs/api-reference/reference/participant-role-assignments).