How to Add Your Own Tags

Tags identify traits or behaviors that belong to an address.

For a table of all tagged addresses see the Crosschain schema.

Do you often copy/paste lists of addresses into your queries? Tags are for you. Tags can be specific and provable, e.g. "OpenSea user", or simply a tool to group addresses and clean up your code.

Your tags. Your rules.

How are tags different than labels?

Tags are more unstructured and free-form than labels. An address's tags can be provable and durable, or subjective and temporary. An address can have as many tags as desired.

In contrast labels serve as a "source of truth" for an address, and are used to label known addresses that are associated with a CEX, DEX, NFT project, liquidity pool, or other entity. An address can have only one label.

What do our tags look like?

Our tags use a 2-level hierarchy, just like our labels.

tag_type	A high-level category describing the address' main function or ownership (i.e. NFT)
tag_name	A sub-category of tag_type providing further detail (e.g. Moonbird Holder)

Tags example:

tag_type	tag_name
Celebrity	Steve Aoki
Celebrity	Mark Cuban
Celebrity	Justin Bieber

Using tag_type you can pull all celebrities tagged by the Flipside community, or use tag_name to pull a specific celebrity.

The tags table

The data for our tags is stored in the data table: crosschain.core.address_tags.

Column Name	Data type	Description
blockchain	string	The blockchain that the address belongs to.
creator	string	Who created the tag. Use your Flipside username, shown in your Flipside profile URL, for tags you create.
address	string	The address of the contract or wallet the tag describes.
tag_name	string	Tag name (sub-category)
tag_type	string	Tag type (high-level category)
start_date	timestamp	Date the tag first applies. For tags that are permanent, this might be the date the address had its first behavior that warrants its tag, or the addresses' first transaction (e.g. if the tag identifies a celebrity NFT address).
end_date	timestamp	Date the tag no longer applies (for tags that are permanent or currently active, end_date can be NULL)
tag_created_at *	timestamp	Timestamp for when the tag was inserted into our data.

* tag_created_at is auto-generated by Flipside.

How to add tags

There are 3 ways to add tags to our data! 1. Add a SQL statement to our GitHub You can use a Flipside query to create a tag set that will run on a reoccurring basis. This is a very powerful and scalable way to create a dynamic tag set that can update regularly. Please see our Github for how to upload your tag set queries. 2. Add a DBT seed file to our GitHub If you have a static list of addresses that need a tag, a DBT seed file is the best route. This is the most efficient method to tag a list of addresses that will not change and don't rely on a SQL query. Please see our Github for how to upload your own DBT seed files. 3. I know what I want but I don't know how to tag Flipside has a very active community and extraordinarily helpful employees. Reach out to the community, or to @gto, in Discord and someone will help you set up your tags.

How to query tags

It's important to remember that a particular address can (and should) have multiple tags.

BE CAREFUL WHEN JOINING TO THE TAGS TABLE, SO YOU DON'T DUPLICATE ROWS.

A common use-case for tags is to exclude addresses that are contracts from an analysis. A query such as:

select 
    address 
from crosschain.core.address_tags 
where tag_name = 'contract address' 
limit 100

will return a list of all addresses that are contracts.

Another use-case is to find addresses that are active on multiple EVM's. For our example, lets say active on both Ethereum and Avalanche. For this example a query such as:

select 
    distinct address
from crosschain.core.address_tags 
where tag_name in ('active on ethereum last 7', 'active on avalanche last 7') 
limit 100

will return a list of addresses that are active on both Ethereum and Avalanche. Our tags are augmented by our start_date and end_date fields, which allows you to see tags historically! A simple query like:

select 
    distinct address
from crosschain.core.address_tags 
where tag_name = 'active on ethereum last 7' 
limit 100

will return a list of addresses that were ever active on Ethereum. A query such as:

select 
    distinct address
from crosschain.core.address_tags 
where tag_name = 'active on ethereum last 7' 
and end_date is null
limit 100

will return a list of addresses that were active in the last 7 days! We can also use the start and end dates to find addresses that were active in a date range! A query such as:

select 
    distinct address
from crosschain.core.address_tags 
where tag_name = 'active on ethereum last 7' 
    and start_date < '2021-07-01'
    and (end_date >= '2021-06-01' or end_date is null)
limit 100

will return a list of addresses that were active on Ethereum during June 2021.