How to Build an Ethereum Token Bot with User-Defined APIs


This use-case relies on a lot of historical data. Please allow extra time to run the query.

In this part, we’re going to create an Ethereum Token Bot which supports real-time inquiry for token metadata and token price on Telegram.

We’re going to build this bot with ZettaBlock GraphQL API.

Step 1. Make a Data Query

To build a GraphQL API, we need to create a SQL query to access the data we want to integrate into our Telegram Bot. First, let's visit the Query Builder on ZettaBlock.

Here’re the steps to make a SQL query to get the metadata of ERC20 tokens on Ethereum:

Choose a Database and Table

We first select the prices database, which contains abstraction price info processed by ZettaBlock already, then choose the usd table which contains the token metadata and price.

Write Query with SQL

Here is the SQL code, you can copy and paste it into the query window.

  prices.usd p  
  INNER join ethereum_mainnet.ethereum_erc20_tokens t  
  ON LOWER(p.ethereum_token_address) = LOWER(t.contract_address)  
  data_creation_date >= date('2022-01-01')

In order to extract data of the verified ERC20 tokens, we set up the statement
LOWER(p.ethereum_token_address) = LOWER(t.contract_address).

Additionally, we want to focus on data in 2022, which requires a WHERE condition on data creation date: data_creation_date >= date('2022-01-01').

Then, we can click the SAVE & RUN button to execute the query. Note that it might take some time to run given the scanned data size.

In order to avoid the query timing out, we also want to increase the Cache TTL to at least 10 minutes.

Once the execution is complete, we can check the results in the result console below.

Step 2. Create a GraphQL API

Start Creating an API

After we validate the query results, we can click the Create API button on the top right of the window and move to the next step.

Customize the API

To customize our API, the first thing we need to do is set the Data Refresh Interval which decides how often the underlying data will be refreshed for the API. We’d like our API to be refreshed every 24 hours, so we choose the24hrs in the option list.

Then we can choose the index fields, which can make the fields faster to query. We’d like to turn on the name, symbol, slug, ethereum_token_address, minute, data_creation_date .

Enable Incremental Data Refresh

To optimize the API cost and performance, we’d like to enable the incremental data refresh option by turning on the toggle.

The first step is to set the primary key, a unique and not null key in the API table. When ZettaBlock processes the incremental data refresh, it will use this key to overwrite stale partitioned data. The primary key here is a set: name, ethereum_token_address, minute.

The second step is to provide the Incremental SQL Code, which will be used to partially refresh the data, and could greatly reduce the cost by controlling how much data to scan and how to scan. We can copy and paste the API transformation code into the Incremental SQL Code console. Then, we need to modify the time condition to: data_creation_date >= DATE_ADD('day', -4, current_date), which will make the future refresh update only scanning through the last 4 days of data.

Once everything is set up, we can click the Create API button to start building our GraphQL API. It might take a few minutes to build the GraphQL API.

Explore the API Info

After API indexing is complete, we can click the Info bar to check the API info.

In the API info window, there are two useful links: The first one is for API Reference, and the second one is for API Key Management.

We can copy the GraphQL URL, visit API Key Management to get the API key, and then visit API Introduction to test out the GraphQL query and read the example code. The string sq_xxxxx is our GraphQL API ID, which is the identifier of our API.

Step 3. Build a Telegram Bot with the GraphQL API

Test GraphQL Query

In the API Reference page, we can visit the “GraphQL Query” section. First, we need to paste the API ID and API Key into the id and X-API-KEY boxes. Then we can write a sample query to test the API.

Here is an GraphQL example of querying the Uniswap token metadata:

  records(symbol:"UNI", limit:1){  

We choose JavaScript with Axios to run the query. Developers can choose different languages to query as needed. Clicking "Try it", we can see the API response in the result window. Besides, we can copy the request code and use it as a code reference.

Set Up a New Telegram Bot

Now, we’re going to create a Telegram bot with the GraphQL API above. In short, we need to create a Telegram bot on BotFather, and copy the bot's HTTP API key. For details, you can read the Telegram bot creation tutorial

Install the Ethereum Token Bot

In your terminal, run the command below to clone the repository and install the dependencies.

$ git clone
$ cd ethereum-token-metadata-bot
$ yarn install

Configure the Bot

Create a .env file in the root directory of the project. Copy the contents of .env.example into the .env file, and fill in the values for the variables.

.env file example:

API_ID = 'sq_bce0000af5014d96ac0995578cd7a403' # You can change this ID to your own API ID

Activate the Bot

To activate the bot, run the command below in your terminal:

$ node bot.js

Try the Bot on Telegram

Visit your Telegram Bot, and type /token ${symbol} to query the Uniswap token metadata. For example, if we'd like to query the Uniswap token, we should type /token UNI and send it to the bot.

Your bot should work like this:

Congratulation! You have successfully finished the tutorial of building a Telegram bot with ZettaBlock API! To learn more about ZettaBlock, please refer to ZettaBlock Overview.