Skip to main content

Flipside Integration

Flipside provides reliable blockchain data. You can simply use FlipSideSource to fetch data from Flipside and use it for your model.

API Key Configuration​

To access the Flipside source, you must provide an API key from Flipside.

from seshat.source.flip_side import FlipSideSource

source = FlipSideSource(api_key="your_api_key")

Query​

To use this source, you must provide a query to the Flipside server. There are multiple ways to make the source understand your query. One way is to define the raw query and use it:

query = "SELECT * FROM ethereum.core.ez_token_transfers LIMIT 1000"
source = FlipSideSource(api_key="your_api_key", query=query)

Another approach is to pass the table_name and filters dictionary. The keys of filters are the columns that you want to filter, and the value of each column name must be another dictionary. This new dictionary has two keys: val and op. The first one shows the value for the filter, and the second one shows the operation that should be used for filtering.

For example, if you provide this filter:

filters = {"BLOCK_NUMBER": {"val": 19710819, "op": ">="}}

The filter translates to WHERE BLOCK_NUMBER >= 19710819. So you can simply define multiple filters for your query:

filters = {
    "BLOCK_NUMBER": {"val": 19710819, "op": ">="},
}
source = FlipSideSource(
    api_key="your_api_key",
    filters=filters,
    table_name="ethereum.core.ez_token_transfers",
)

Another way is to use query_fn, a function that will be called to get the query.

def get_query():
    return "SELECT * FROM ethereum.core.ez_token_transfers"

source = FlipSideSource(api_key="your_api_key", query_fn=get_query)

Note that you can still use the filters in all cases. The filters will be added to the end of the query statement.

Pagination​

FlipsideSource has pagination, so the result of the query will be fetched with pagination. You can use page_size to set how many rows each page fetches from the database.

To use pagination, each page will be saved as a separate CSV file locally, named as the hash of the query data. If an error occurs in the middle of fetching the data, there is no need to re-fetch the data that has already been fetched. The source handles fetching such that if one page is fetched, it will be loaded from local storage.

Schema​

Like other sources, you can pass the schema to FlipSideSource. In this source, the schema has additional benefits. First is for the query: if you pass a schema with exclusive set to True, then the columns in the SELECT query statement will be the columns of the schema.

ID Column​

As mentioned in the previous section, the source will save each page in a CSV file to avoid re-fetching it in subsequent attempts. To use this feature, you must provide an id_col for the source. The id_col can be directly passed to the source constructor or derived from the schema passed to the source.