How To: Find out where all your ETH is using BALANCES

Last updated on Aug 22, 2023

🧠

This is part of our How To series: A selection of use-cases that have high educational value, and/or best showcases Vektor's capabilities. We will continue to add new How To articles over time, and they should not be considered exhaustive! Vektor is a powerful tool and VXL is a very flexible language with many different use-cases; this is just a taster.

🏁 Skip to the "answer"

Objective & Benefit

When you use Multi-chain DeFi for a while, especially if you use multiple addresses on chain, it's common to lose track of where all your assets are, especially ETH as this is the native asset on several chains also.

We're going to use this example to show how Vektor can very easily search for and summarise the exact locations and amounts of all your ETH, wherever it is, and even show you a global total. No static spreadsheets required!

Functions used

BLOCKCHAINS - get the list of blockchains supported by Vektor
LABELS - get a list of labelled addresses.
LABELS.ADD - add a human-readable label to a blockchain address.
BALANCE - get the balance of an asset on a blockchain for a label
BALANCES - get the balances for all assets on all blockchains for all labels
BALANCES.SUM - sum the balances for all assets on all blockchains for all labels

Step-by-step

1. Understand which blockchains Vektor supports

Submit the BLOCKCHAINS function to see the current list of chains supported by Vektor. This represents the current total search space.

A list of blockchains suppored by Vektor

2. Add your labelled addresses

For Vektor to peform a multi-chain asset balance search, you first need to assign addresses as LABELS.

About Labels

LABELS in Vektor are human-readable names that you assign to blockchain addresses.

Vektor is a powerful tool that executes transactions on multiple blockchains. By registering an address as a Vektor label, you unlock many useful multi-chain functionalities. The names you assign to labels also become easier to use in functions, and save you from copy-and-pasting addresses everywhere.

LABELS can be assigned to any address present on one or more Vektor-supported chains, whether that address is controlled by you (i.e. you have the private key) or the address is controlled by someone else (i.e. a 'Watch only' address). Vektor can only execute transactions using addresses controlled by you.

To see which labels you have already assigned, use the LABELS function.

A list of labelled addresses (aka "labels")

You can leave this pane open; it will auto-update if you add/remove labels.

To add a new label, use the LABELS.ADD subfunction. You will see a confirmation in a new pane.

3. Check a single balance

To check a single balance of a single asset on a single chain, use the BALANCE function.

This is useful if we know where to look - but the point of this procedure is to find your ETH wherever it is!

4. Check all your balances of everything

Now for the good part - use the BALANCES to make Vektor search all of your labelled addresses, for all assets, on all (supported) chains.

Great - but we are only interested in ETH for now. Let's refine on the next step.

⚠️

Note: to work with Vektor functions, assets need to be listed in Vektor’s asset registry. You can see this using the ASSETS.GET function. We plan to give users the ability to register their own assets, but for now you need to let us know if there is something missing that you need - we can add it quickly.

5. Check all your ETH balances

Use INCLUDE_ASSETS=, one of the optional arguments of BALANCES, to filter the assets.

Multi-balances check, including only ETH

⚠️

As a general rule, 'singular' functions like BALANCE will return a single object/value, while 'plural' functions like BALANCES will return a list of objects/values. You can read more about common syntax patterns here.

Did you notice something missing? We are showing only native ETH here, but probably we should include all the different forms of ETH for a complete picture.

6. Include ETH equivalents

You can include several assets in the INCLUDE_ASSETS= filter by using array notation. Let's expand to include Wrapped ETH WETH and staked ETH STETH.

Multi-balances check, including various ETH-like assets

Great! Now we have a complete picture of our ETH, WETH, and STETH balances, across all my labels, whichever chain they are on.

💎

Bonus FYI: You can use the WRAP function in Vektor to easily convert between native and wrapped assets.

Now I want to know the TOTAL amount (in ETH), not the USDC value as per the default.

7. Change the QUOTE asset

You can use the QUOTE option in BALANCES to change the quote from USDC to ETH.

Overriding the quote asset of the VALUE column using the QUOTE option

8. Compute the total

Finally, let's use the BALANCES.SUM sub-function to add all this together.

SUM of all ETH and ETH-equivalents across all chains and all labelled addresses

Hope you liked this How-To use-case! You can find more here.

💎

Do you have an excellent Vektor use-case that you'd like to have featured? We'd love to hear from you!

Request Access