Filters for List and Query Methods

Utila’s API methods that retrieve collections (e.g. ListTransactions, QueryBalances) support a powerful, flexible filtering system based on the Google AIP‑160 standard. Filters let clients limit results using a familiar and intuitive syntax which includes logical operators, comprarison operation, custom functions and more.

General Usage and Syntax Overview

• Single filter field:

  • An endpoint which supports filtering include exactly one filter string field (query parameter) in the request in which the filter string should be supplied.
    • When the filter field is supplied twice, the latter will apply.

• Literals:

  • Bare values (e.g. 42, "foo") match anywhere unless restricted.
  • Multiple bare literals imply AND (e.g. foo bar ≈ foo AND bar).

• Logical operators:

  • AND, OR (OR binds tighter than AND).
  • Precedence: a AND b OR c ≡ a AND (b OR c).
  • Best practice: use parentheses to clarify.

• Negation:

  • Supported via NOT a or -a.

• Comparison operators:

  • =, !=, <, >, <=, >= for numeric, string, timestamp.
  • Left-hand side must be a field; right-hand side is a literal.

• Functions:

  • Most of the filters in Utila are exposed as functions.
  • The supported functions for each endpoint are documented.

Example Filters in Utila

GET /v2/vaults/{vault_id}/transactions?filter=state(AWAITING_SIGNATURE) AND create_time() >= "2025-01-01T00:00:00Z"

Returns transactions which are awaiting signature and were created in 2025 or later.

POST /v1/vaults/{vault_id}:queryBalances?filter=asset("assets/native.ethereum-mainnet")

Returns the vault balance of Ethereum's native asset.

GET /v1/vaults/{vault_id}/transactions?filter=from\_wallet("vaults/c3b45307702d/wallets/02622144f54e") AND state(AWAITING\_SIGNATURE)

Returns transactions which are awaiting signature by wallet vaults/c3b45307702d/wallets/02622144f54e

Endpoint-Specific Behavior

Each endpoint defines which functions are supported for filtering. For example, ListTransactions allows: