Using Filters

Learn how to use filters to get notifications on the activity you care about.

Filters are a set of conditions and values that allow you to specify the onchain event that should trigger a notification. You can quickly set parameters on any field in the payload. Filters are created using field_name, operator, value_type, and value.

Name	Definition
field_name	The specific attribute within the event data that you want to filter on. See a complete list of filters below.
operator	Specifies the logical or comparison operation to apply between the field_name and value. See complete list of operators below.
value_type	The data type of the value you are filtering with
value	The actual value or list of values to compare against the specified operator

Example Request:

 "filters": [
            { "field_name": str, "operator": str, "value": str, "value_type": str },
            # ... more filters if needed
        ],

List of Operators

Operators must be used with a valid value type to successfully create the notification.

Operator	Definition	Value_Type
eq	variable is equal to a value [ = ]	int, float, str, boolean
neq	variable does not equal a value [ != ]	int, float, str, boolean
gt	variable is greater than a value [ > ]	int, float
lt	variable is less than a value [ < ]	int, float
in	variable is in a list	list
nin	variable is not in a list	list
contains	a list contains the variable	string
ncontains	a list does not contain the variable	string

List of Variables

You can apply filters on any of the data fields in the primary payload. Please reference the tables below for list of field_names and corresponding value_type.

Address_Activity Filters

Field Name	Definition	Value Type
hash	The unique hash identifying the transaction on the blockchain.	str
fromAddress	The address sending the asset in a transaction.	str
toAddress	The address receiving the asset in a transaction.	str
asset	The symbol or address of the asset or token involved in the transaction. (e.g. ETH, USDC)	str
value	The amount of the asset or token transferred or exchanged in the transaction.	int
blockNum	The block number in which the transaction was included.	int
category	The category of the transaction (e.g., "external", "internal").	str

GraphQL Filters

Field Name	Definition	Value Type
transaction.hash	The hash of the transaction.	str
transaction.from.address	The sender address of the transaction.	str
transaction.to.address	The recipient address of the transaction	str
transaction.value	The value of the transaction	int

Note: additional filters on event address and topic-level parameters can be applied in the GRAPHQL object. See Smart Contracts for more detail.

NFT_Activity Filters

Field Name	Definition	Value Type
hash	The unique hash identifying the transaction on the blockchain.	str
fromAddress	The address sending the NFT in a transfer or sale.	str
toAddress	The address receiving the NFT in a transfer or sale.	str
asset	The address of the NFT contract.	str
erc721TokenId	The unique identifier (token ID) of the NFT involved in the event.	int
log.logIndex	The index of the log within the block.	int
log.blockHash	The hash of the block in which the transaction occurred.	str
log.transactionIndex	The index of the transaction within the block.	int
log.blockNumber	The block number in which the transaction was included.	int
log.data	The raw data associated with the event log.	str
log.topics.text	A text representation of the topics (indexed parameters) of the event log.	str
log.topics	The topics (indexed parameters) of the event log.	list
log.address	The address of the contract that emitted the event.	str

Farcaster_Cast Filters:

Field Name	Definition	Value Type
hash	The unique hash identifying the cast on Farcaster.	str
text	The text content of the cast.	str
author.fid	The Farcaster ID (FID) of the author of the cast.	int
author.username	The username of the author of the cast.	str
author.display.name	The display name of the author of the cast.	str
author.pfp.url	The URL of the author's profile picture.	str
author.profile.bio.text	The text of the author's profile bio.	str
author.follower.count	The number of followers the author has.	int
author.following.count	The number of users the author is following.	int
power_badge	A boolean of the author's power badge status	boolean
timestamp	The timestamp of when the cast was created.	int
parent.url	The URL of the farcaster channel	str
parent.hash	The hash of the farcaster channel	str
thread.hash	The hash of the thread this cast belongs to.	str
replies.count	The number of replies to this cast.	int
reactions.recasts.text	A text representation of the recast (re-share) reactions to this cast.	str
reactions.recasts	An array of recast (re-share) reactions to this cast.	list
reactions.likes.text	The like reactions to this cast.	str
reactions.likes	An array of like reactions to this cast.	list