Deep Dive into the Ratio1 Community Telegram Bot: network insights, for everyone

Decentralized and open source networks such as Ratio1 offer the best transparency, but staying on top of their status and statistics can be challenging. Our new Ratio1 Telegram Bot - built on the Ratio1 tech stack - aims to make it easier for everyone by delivering important network updates and node health alerts right where many of you already chat: on Telegram. Whether you’re a community member tracking the network’s growth or a node runner keeping an eye on your hardware, this bot has you covered.

In this post we’ll explain what the bot does and dissect its codebase and design choices. This implementation is really a springboard for almost any Telegram-based watchdog you can imagine. Because it already handles the heavy lifting - setting up a Ratio1 pipeline, talking to Telegram, querying on-chain data, caching state, and persisting it to disk - you can swap in a different data-fetch routine and instantly build other bots. Think wallet-transaction trackers that ping on high-value transfers, scam-token sentinels flagging sudden rug-pull patterns (analysed by AI), gas-spike alerts, NFT floor-price monitors, and more. Treat this bot as a live template for a whole toolbox of bots you can build.

What does the Ratio1 Bot do?

At a high level, it has two key functions:

• 📆 Automated Epoch Summaries: At the end of each epoch, the bot posts a concise summary of network stats to the public Ratio1 Telegram group. This summary includes metrics like the number of active nodes, total licenses, circulating R1 supply, rewards from the last epoch, and tokens burned. It’s a quick way for everyone to see how the network performed in the latest epoch and how it evolves day by day - no manual queries or block explorer digging needed.

• ⚠️ Node Offline Alerts: If you operate Ratio1 nodes, you can subscribe to offline notifications. Simply send the bot a /watch <YourWalletAddress> command (in a direct chat with the bot), and it will monitor all nodes tied to that wallet. If any of your nodes go offline, the bot immediately sends you a private alert. When the node comes back online, you’ll get a “back online” message as well. You can manage your watch list with commands like /watchlist, /unwatch <wallet> or even /unwatchall to clear the list. No more finding out hours later that your node was down – the bot will ping you in real time.

How to use it?

To see the epoch summaries, just join our official Telegram community chat where the bot posts updates at every epoch change. For node alerts, start a conversation with the Ratio1 bot (https://t.me/Ratio1ai_bot) and use the /watch command as described. In short, anyone can follow network progress in the group, and node operators can get peace of mind through instant outage notifications.

What’s under the hood?

Next, we’ll shift gears and explore how this bot is built and how it leverages the Ratio1 technology to make it easier for anyone to develop their own bot. While this part is mainly for developers, you might still be interested in finding out how easy it is to develop bots on Ratio1, and you might find yourself interested in vibe-coding your next idea, without having all the overhead from complex DevOps preparations, libraries handling and so on.

Behind the scenes, the Ratio1 Telegram Bot is powered by a Ratio1 pipeline, which leverages the already existing Telegram Bot plugin. Thanks to this architecture, the entire bot is implemented in a clean, concise way - no need to set up servers, complex cron jobs, webhooks.

The entire bot creation and handling is done in a few lines of code, allowing developers to focus on what really matters for their app. We’ll break down some key code snippets of the bot’s code to show how it works, but you can find the full code at https://github.com/Ratio1/ratio1_sdk/blob/main/tutorials/ex21_telegram_community_bot.py. For a more detailed description of the basics of deploying a Telegram bot, you can read more in our previous blogpost “Deploying Telegram bots on Ratio1: from naive Echo-bot to a serious Blackjack-dealer” (https://ratio1.ai/blog/deploying-telegram-bots-on-ratio1) - we’ll build on that foundation here without repeating some of the basics.

In Ratio1, your code runs inside a pipeline - essentially a containerized agent that executes on an Edge Node in the network. The Ratio1 SDK makes it extremely easy to deploy a Telegram bot pipeline. In fact, you can do it in just a few lines of code. We start by creating a session and instructing it to use our target node (by address). Then we call the handy create_telegram_simple_bot method, which sets up a Telegram bot pipeline with the given token and handlers in one go. Finally, we deploy the pipeline to actually run it on the node. Here’s what that looks like in code:

if __name__ == "__main__":  
 session = Session()
 node = os.getenv("RATIO1_NODE")
 session.wait_for_node(node)
  pipeline, _ = session.create_telegram_simple_bot(
   node=node,
   name="ratio1_telegram_bot",
   telegram_bot_token=os.getenv("TELEGRAM_BOT_TOKEN"),
   chat_id=os.getenv("TELEGRAM_CHAT_ID"),
   message_handler=reply,
   processing_handler=loop_processing,
 )
 pipeline.deploy()

As you can see, all the boilerplate is handled for us. We didn’t have to write any low-level Telegram polling logic or web server - Ratio1’s SDK created a bot instance connected to Telegram and tied it into our custom logic. We provided two callbacks here: message_handler=reply for processing incoming user commands, and processing_handler=loop_processing for continuous background tasks. Let’s explore those next.

Live Network Monitoring with plugin.netmon and plugin.bc

One of the bot’s jobs is to keep an eye on the Ratio1 network and summarize each epoch. We achieve this using Ratio1’s Network Monitor plugin (plugin.netmon), which gives our code easy access to the network's data. Inside the loop_processing function (which runs continuously in the background), the bot does roughly the following:

• Get the latest epoch: Using the network monitor’s epoch manager, the bot fetches the current epoch number with a single call: last_epoch = plugin.netmon.epoch_manager.get_last_sync_epoch() . This tells the bot which epoch just completed and got synced between all the oracles.

• Gather node statistics: The bot retrieves the list of all active nodes from the monitor (plugin.netmon.available_nodes_prefixed). It even breaks them down by type (ND, MND, GND licenses) and calculates the total ND mining rewards for the epoch by checking on-chain data for each node’s contribution. All of this is done with straightforward calls like plugin.bc.get_node_license_info(...) to fetch a node’s license type and assigned rewards, and plugin.netmon.network_node_is_online(...) to check if a node is currently online. No complex web3 code is needed – the Ratio1 plugin provides high-level methods for these common tasks.

• Detect offline/online nodes: Still in the background loop, the bot checks each watched wallet (those that users subscribed via /watch) and looks up all node addresses under that wallet (plugin.bc.get_wallet_nodes(...)). For each node, it uses the network monitor to see if the node is online. If a node that was previously online goes offline, or vice versa, the bot immediately sends the user an alert message with the node’s alias and address. This logic ensures that node operators get timely notifications about status changes without any manual intervention.

Crucially, the plugin system allows us to do all the above in a few lines of Python, without dealing with raw RPC calls or external monitoring scripts.

On-Chain and Off-Chain Data Made Easy

The Ratio1 bot doesn’t only rely on local node data; it also pulls in additional info via HTTP requests and blockchain queries - all integrated into the plugin environment. This serves as a great example of how you can fetch data from multiple sources for your logic. For example, to populate the epoch summary, the bot needs token supply and burn statistics. Rather than running a separate script or calling a blockchain RPC manually, our code simply uses Ratio1’s built-in request module:

 # We get token details from the Ratio1 API
 tokenDetails = plugin.requests.get("https://dapp-api.ratio1.ai/token/supply").json()
 current_burn = tokenDetails["burned"]
 circulating_supply = tokenDetails["circulatingSupply"]
 total_supply = tokenDetails["totalSupply"]

 def get_erc721_total_supply(contract_address: str) -> int:
   return int(plugin.requests.post("https://base.drpc.org", json={
     "jsonrpc": "2.0",
     "method": "eth_call",
     "params": [
       {
         "to": contract_address,
         "data": "0x18160ddd" # totalSupply()
       },
       "latest"
     ],
     "id": 1
   }).json()["result"], 16)

In the snippet above, the bot uses plugin.requests.get(...) to call Ratio1’s public API for the latest R1 token metrics (circulating supply, total supply, and how much R1 has been burned so far). It also defines a helper to perform an EVM query via plugin.requests.post to an Ethereum RPC URL, in order to get the total supply of ND and MND license NFTs on Base. All these HTTP and blockchain queries are done with standard Python requests semantics - the Ratio1 environment allows them safely, so our bot can easily mix on-chain data with off-chain API data.

Caching and Persistence with plugin.cache and diskapi

To make the bot efficient and stateful, we take advantage of Ratio1’s caching system. The bot needs to remember some information between iterations of the loop and even across restarts of the pipeline. For example, it keeps track of which epoch summaries have already been sent (so it doesn’t repeat work for the same epoch) and which nodes have already triggered an offline alert (so it won’t spam you repeatedly for the same outage). It also needs to remember the list of wallets each user is watching for offline alerts.

Ratio1 plugins provide an in-memory object cache (plugin.obj_cache) for storing arbitrary Python objects across function calls. We use this to hold dictionaries of past epoch data and watched wallets. Additionally, Ratio1 offers a persistent storage API (plugin.diskapi) which allows saving data simply and safely, so that it can be reloaded even if the pipeline stops and restarts later. Here’s how we utilize these features in the bot code: 

# If it is the first run, we need to initialize the cache from diskapi
 if plugin.obj_cache.get(cache_already_read_key) is None:
   plugin.obj_cache[epoch_review_cache_key] = plugin.diskapi_load_pickle_from_data(diskapi_epoch_review_file_name) or {}
   plugin.obj_cache[watched_wallets_cache_key] = plugin.diskapi_load_pickle_from_data(diskapi_watched_wallets_file_name) or {}
# ... bot runs, updates plugin.obj_cache during processing ...
 # Save the epoch review data to the cache and diskapi
 plugin.obj_cache[epoch_review_cache_key][last_epoch] = …
 plugin.diskapi_save_pickle_to_data(plugin.obj_cache.get(epoch_review_cache_key), diskapi_epoch_review_file_name)

With a few simple lines of code, we ensure that the bot never loses its memory, ensuring at the same time a simple developer experience to save and load data from storage and cache, and full safety for node operators (no dangerous operation can be done using this system)

Message handling

Last but not least, we’ll showcase how to handle received messages, and how to send them.

As you have seen, we had two parameters for the create_telegram_simple_bot function: message_handler and processing_handler.

In processing_handler, where we are monitoring nodes and epoch change, we want to send messages without an immediate previous interaction from the user. This is achieved with with a few very simple lines of code:

# Offline node monitor:
plugin.send_message_to_user(user_id=user, text=f"⚠️ Node {plugin.netmon.network_node_eeid(node_internal_addr)} ({node}) is offline. Please check your node status.")
# Epoch change message:
 message = f"📆 Epoch {last_epoch} Summary\n\n"
 message += f"🛰️ Active Nodes: {nodes_count} ({nd_count} ND, {mnd_count} MND, {gnd_count} GND)\n"
 message += f"🪪 Total Licenses: {total_licenses}\n"
 message += f"🔄 Circulating R1 Supply: {circulating_supply:,.0f} R1\n"
 message += f"💎 Total R1 Supply: {total_supply:,.0f} R1\n"
 message += f"🎁 Last Epoch PoA Rewards: {(last_epoch_nd_mining):,.2f} R1\n"
 message += f"🔥 Last Epoch Burn: {(burned_last_epoch):,.2f} R1\n"
 message += f"🔥 Total Burn: {(current_burn):,.2f} R1\n"
 plugin.send_message_to_user(user_id=plugin.cfg_chat_id, text=message)

And that’s it! It’s enough for you to know the user_id, prepare the message text, and send it with one line of code!

On the other hand, when a user sends a message to your bot, the reply function will be called, giving you as a parameter all the information you need: the message, the user who sent it, and the chat where the message was sent.

And replying to it is as easy as a return statement:

return "Welcome to the Ratio1 Bot! Use /watch <wallet_address> to start watching your nodes. You will receive notifications when your nodes are offline."

Conclusion & Next Steps

Building this Telegram bot was a powerful demonstration of how Ratio1 is able to retrieve data from multiple sources and simplifies the development of any kind of application. In under a few hundred lines of code, we created a bot that taps into on-chain data, calls external APIs, maintains state, and interacts with users - all while running on a trustless, distributed network of nodes. The concise code is made possible by Ratio1’s plugin system, which provides high-level tools out of the box (from network monitors to caching and Telegram integration).

For developers, the take-away is clear: Ratio1 makes it easy to build bots and agents that are not only scalable and secure, but also easy to write and maintain. You focus on your bot’s logic, and Ratio1 handles the heavy lifting of deployment, scaling, and connectivity. If a simple network-monitoring bot can be this straightforward, imagine what else you can create - from AI-powered chatbots to automated on-chain traders or decentralized assistants.

We encourage you to explore the simplicity and flexibility of Ratio1 for your own projects. Check out our docs and other tutorials, grab the SDK, and start coding. Whether it’s another Telegram bot or any decentralized application, Ratio1’s platform is designed to let your creativity run wild without worrying about the infrastructure. We can’t wait to see what you build next!