Account activity API reference

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. Either way the surface is read-only: it reports events that already happened, and it does not submit transactions or change state.

Endpoints

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.

Path parameters

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

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

Each item in the activities feed describes one indexed blockchain event.

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

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.

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"

{
  "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

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.

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"

{
  "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

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. For retries, readback checks, and reconciliation around these reads, see Operational integration patterns.