Documentation for eth_defi.balances.fetch_erc20_balances_by_transfer_event function.

fetch_erc20_balances_by_transfer_event(web3, owner, from_block=1, last_block_num=None)[source]

Get all current holdings of an account.

We attempt to build a list of token holdings by analysing incoming ERC-20 Transfer events to a wallet.

The blockchain native currency like ETH or MATIC is not included in the analysis, because native currency transfers do not generate events.

We are not doing any throttling: If you ask for too many events once this function and your Ethereum node are likely to blow up.


Because the limitations of GoEthereum, this method is likely to fail on public JSON-RPC nodes for blockchains like Binance Smart Chain, Polygon and others. E.g. BSC nodes will fail with {‘code’: -32000, ‘message’: ‘exceed maximum block range: 5000’}. Even if the nodes don’t directly fail, their JSON-RPC APIs are likely to timeout.


# Load up the user with some tokens
usdc.functions.transfer(user_1, 500).transact({"from": deployer})
aave.functions.transfer(user_1, 200).transact({"from": deployer})
balances = fetch_erc20_balances(web3, user_1)
assert balances[usdc.address] == 500
assert balances[aave.address] == 200
  • web3 (web3.main.Web3) – Web3 instance

  • owner (HexAddress) – The address we are analysis

  • from_block (Optional[int]) – As passed to eth_getLogs

  • last_block_num (Optional[BlockNumber]) – Set to the last block, inclusive, if you want to have an analysis of in a point of history.


Map of (token address, amount)

Return type

Dict[HexAddress, int]