Skip to main content

This is a step by step guide for how to use Tellor’s open-source tip claiming software: the timestamps-tip-scanner.

Caution: Running any Tellor client like the timestamps-tip-scanner involves handling private keys. Never share your private keys with anyone under any circumstances. Take appropriate precautions and know that you are using this software at your own risk. 


Tellor reporters often get paid for data updates via on-chain tips from the Autopay contract. If you’re a reporter using a client that submits for these automatically, you might not even be aware you’ve submitted for them. It’s a good idea to check periodically just in case!

The timestamps-tip-scanner works like an add-on to the Telliot reporting client. If you’re going to install the tip scanner on a machine that’s different from the one you use for reporting (or if you’re using any reporting client other than Telliot), you’ll need to install python3.9 and Telliot first.

The Guide

This guide assumes that you are a Tellor reporter. We will go over all the commands necessary to set up the timestamps-tip-scanner to automatically find your qualifying submissions and claim TRB tips. 

Download Necessary Files and Install

1) Clone the repo. git clone

2) Change the current directory to be the timestamps-tip-scanner folder.  cd timestamps-tip-scanner

3) Create a python virtual environment for installation. python3 -m venv tenv

4) Activate the virtual environment. source tenv/bin/activate

5) Install the tip scanner. pip install -e .

If you’ve completed these steps and you’re getting python errors, please check that your python installation is compatible with Tellor clients.

Set up Reporting Accounts (if Necessary)

The timestamps-tip-scanner needs the keys to your reporting account to be able to call the tip-claiming functions. If you’ve been reporting oracle data with Telliot, you may skip ahead to scanning.

Check whether or not you have an account configured with the command: telliot account find

This will output a list of configured accounts. If you don’t have any accounts configured, you can add yours with the command: chained add <choose-acct-name> <private-key>

Replace “<choose-acct-name>” with any name you like, and “<private-key>” with the private key of your reporting address. Choose a password for your account when prompted.

Scan Your Address for Qualifying Reports

Now the fun part! You can now scan the blockchain for new report events at your address to see if you have any reports that qualify for TRB tips. I will include screenshots using one of my testnet addresses for illustration.

Run the command: scanner scan <chain-id> -a <acct-name> --start-block <block-number>

Replace “<chain-id>” with the chain ID you’ve been reporting on (e.g. 1 for mainnet, 137 for polygon…). Replace “<acct-name>” with your Telliot Account name. Replace “<block-number>” with any block number before tips were created. If you’re not sure what block number to use, try the block number of your depositStake transaction when you became a reporter.

The log will output information about the scan:

The scanner will create a file called ‘new_report_timestamps.json’ in your timestamps-tip-scanner folder with a list of report timestamps organized by queryId. Now it’s time to claim the tips!

Claim the Tips!

There are two kinds of Autopay tips: one-time tips, and feed tips. We’ll do the feed tips first.

Enter the command: scanner claim-tip <chain-id> <acct-name>

Remember to replace “<chain-id>” with the chain ID you’ve been reporting on and “<acct-name>” with your Telliot Account name.

Enter your password when prompted. The program will call the ‘Claim Tip’ function for any qualifying timestamps and log the details:

Darn! It looks like my sepolia address doesn’t qualify for any feed-tips today.

Note: Feed tips cannot be claimed after 14 days.

Next, let’s check for one-time-tips.

Enter the command: scanner claim-one-time-tip <chain-id> <acct-name>

Enter your password when prompted. The program will call the ‘Claim Tip’ function for any qualifying timestamps and log the details:

Alright we claimed some TRB! Check your TRB balance, or use the Tx hash from the log to see how much you made.

Thanks for Reading!

Questions? Feel free to give us a shout in the Tellor Discord! You can yell at me (or thank me) directly by tagging spuddy.eth or find me on Twitter

Have a great day 🤙