ERC-20 Balance Changes Substreams

ERC-20 is the most popular token standard for EVM-compatible blockchains. ERC-20 tokens such as USDT, USDC, or BUSD are among the most used ERC-20 tokens, so the demand for retrieving, tracking and transforming these kinds of tokens efficiently has increased lately.

Consider that you want to retrieve the current USDT balance of a specific address; the ERC-20 standard allows you to get this value by using the “balanceOf(address)” method of the smart contract. However, if you want to retrieve the full history of balance changes (USDT incoming and outgoing transfers), there is no straightforward way to do it. Substreams to the rescue!

The StreamingFast team has created a ready-to-use Substreams that extracts all ERC-20 transfers in the form of balance changes.

It is worth noting that different contracts have different methods of storing balances. The ERC-20 Balance Changes Substreams uses two strategies to discover balance changes but does not cover all edge cases. Nevertheless, this Substreams is able to retrieve approximately 97% of the balance changes successfully. This 97% covers all major tokens, leaving some of the more obscure ERC-20 tokens unhandled.

Running the Substreams

The main module of the ERC-20 Balance Changes Substreams is the “map_valid_balance_changes” module, which outputs erc20.types.v1.ValidBalanceChanges data:

{
"contract": "c02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",
"owner": "6b75d8af000000e20b7a7ddf000ba900b4009a80",
"oldBalance": "62342581577012030851",
"newBalance": "61671907525910146435",
"transaction": "a278205118a242c87943b9ed83aacafe9906002627612ac3672d8ea224e38181"
}

You can read the previous balance change like: “For the token c02a…6cc2, the address 6b75..9a80 went from a balance of 62.34 to a balance of 61.67 in the transaction a278…8181”.

You can use the Substreams GUI to run this Substreams package.

substreams gui https://github.com/streamingfast/substreams-erc20-balance-changes/releases/download/v0.0.5/erc20-balance-changes-v0.0.5.spkg map_valid_balance_changes -e mainnet.eth.streamingfast.io:443 -s 17000000 -t +10

Try out the Substreams right now!

Click on the Result tab just below to see it in action.

NOTE: If you do not already have a StreamingFast authentication API key, get one from the StreamingFast portal.