​

Overview

Aggregations enable tracking and persistence of metric data from RPC requests over time. They allow policy rules to evaluate wallet activity against historical data, enabling more sophisticated controls like rate limiting and spending caps. Together with policies, aggregations make it possible to express constraints that depend on cumulative behavior rather than just the current request. This approach offers several benefits:

• Rate limiting: Enforce transaction volume limits over time windows
• Spending caps: Limit total value transferred within a period
• Activity monitoring: Track transaction patterns across chain IDs or contract addresses
• Dynamic policies: Create rules that adapt based on historical wallet behavior

​

Concepts

Aggregations are defined by four core primitives: aggregations, metrics, windows, and group-by fields. At a high-level:

• Aggregations define what data to track from RPC requests and how to aggregate it over time
• Metrics specify which field to extract from requests and how to aggregate values (e.g., sum transaction values)
• Windows define the time period over which to aggregate data (e.g., rolling 1-hour windows)
• Conditions define pre-filters that determine which requests should be included in the aggregation (e.g., only transactions to a specific contract)
• Group-by fields optionally partition aggregations by specific attributes (e.g., by chain ID or recipient)

Once created, aggregations can be referenced in policy conditions using the reference field source. When a condition uses field_source: 'reference' and aggregation.{aggregation_id} as the field, the policy engine evaluates the current aggregated value against the specified threshold.

​

Create aggregations

Refer to the API reference for creating aggregations.

​

How aggregations are applied

When a wallet receives an RPC request, aggregations are processed in two phases: data collection and policy evaluation.

​

Data collection

When a request is made, all aggregations referenced in the wallet’s policies are updated. Multiple policies can reference the same aggregation, which is useful for sharing limits across different policy types (e.g., multiple signer override policies can reference the same aggregation to limit total transfer value out of a wallet in a rolling time window). This includes aggregations from:

• The wallet’s directly assigned policy
• Owner policies (if the wallet has an owner)
• Signer override policies (if the request includes a signer with an override policy)

For each aggregation:

1. The aggregation’s conditions are evaluated against the request. If all conditions pass, the aggregation proceeds to value extraction.
2. The metric value is extracted from the request based on the aggregation’s metric configuration.
3. If the value cannot be extracted (e.g., the field doesn’t exist or the calldata doesn’t match the ABI), the value defaults to 0. Be careful when defining metrics: if you want the limit to apply to multiple operations (e.g., both approve() and transfer() calls against a contract ABI), you must configure separate aggregations or conditions for each operation.
4. The extracted value is added to the aggregation’s running total for the current time bucket.

​

Policy evaluation

When evaluating a policy condition that references an aggregation:

1. The policy engine retrieves the current aggregated value for the time window.
2. If group-by fields are configured, the engine uses the group key derived from the current request.
3. If the metric value cannot be extracted from the current request, the policy engine uses the existing aggregated value (without including the current request).
4. If the metric value can be extracted, the policy engine uses the aggregated value plus the current request’s value.
5. The total is compared against the condition’s threshold using the specified operator.

​

Supported RPC methods

Aggregations can be configured for the following RPC methods:

​

Metric configuration

The metric object defines what value to extract from requests:

Hide metric attributes

​

field

string

required

The field to extract from the request. For example, 'value' for transaction value.

​

field_source

'ethereum_transaction' | 'ethereum_calldata'

required

The data source from which to derive the field. Must correspond to the aggregation’s method.

​

function

'sum'

required

The aggregation function to apply. Currently, only 'sum' is supported.

​

abi

JSON

Contract ABI to decode calldata against. Required when field_source is 'ethereum_calldata'.

​

Supported field sources

​

Window configuration

The window object defines the time bucketing strategy:

Hide window attributes

​

type

'rolling'

required

The bucketing type. Currently, only 'rolling' windows are supported.

​

seconds

number

required

The duration of the time window in seconds. Minimum value is 3600 (1 hour), and maximum is 259200 (72 hours).

​

Conditions configuration

The optional conditions array defines pre-filters that determine which requests should be included in the aggregation. Only requests that match all conditions will have their metric values aggregated.

Hide condition attributes

​

field_source

'ethereum_transaction' | 'ethereum_calldata'

required

The data source from which to derive the field for the condition.

​

field

string

required

The field to evaluate. For example, 'to' for the transaction recipient or 'chain_id' for the chain ID.

​

operator

'eq' | 'neq' | 'lt' | 'lte' | 'gt' | 'gte' | 'in' | 'in_condition_set'

required

The comparison operator to use. The in_condition_set operator is supported for aggregation conditions.

​

value

string | number | string[]

required

The value to compare against. Use an array for the 'in' operator.

​

abi

JSON

Contract ABI to decode calldata against. Required when field_source is 'ethereum_calldata'.

​

Group-by configuration

The optional group_by array partitions aggregations by specific fields:

Hide group_by attributes

​

field

string

required

The field to group by. For example, 'chain_id'.

​

field_source

string

required

The data source from which to derive the grouping field.

When group-by fields are configured, separate aggregation buckets are maintained for each unique combination of group-by values.