Skip to main content

Basic Usage

Language settings

Our docs and examples are in English. Depending on your language setting you might need to use semi-colons ( ; ) instead of commas ( , ).

Functions

Multichain functions:

  • CallInt(path, targets/cops, function, optional parameters): for functions that return an integer
  • CallAddress(path, targets/cops, function, optional parameters): for functions that return an address
  • CallStr(path, targets/cops, function, optional parameters): for functions that return a string
  • CallCstr(path, targets/cops, function, optional parameters): for functions that return a string
  • EthBalance(targets, block number, network): for getting the Ether balance of an address
  • CurrentBlock(network): returns the current block number
  • BlockToTimestamp(block number, network): returns the timestamp of a block
  • TimestampToBlock(seconds, network): returns the closest blocknumber
  • TokenAddressByName(name,network): returns the token address
  • TokenDecimalsByName(name,network): returns the token decimals
  • TokenAddressBySymbol(symbol,network): returns the token address
  • TokenDecimalsBySymbol(symbol,network): returns the token decimals

Options:

  • COPS(target, block number/latest, network): used in the Call functions to make historical and network specific calls.

Web3 Sheets:

  • Web3SheetsUsage(): returns the number of requests made in a month.
  • Web3SheetsCredits(): returns the number of requests that the user can make in a month.
  • GFXSheetsVersion(): returns the Web3 Sheets version running on the sheet.
Commands are not case sensitive

Commands aren't case sensitive. For example, =currentblock() and =CURRENTBLOCK() will both work.

Feature requests are welcomed. Please post them on Discord.

Components of a query

Basic example​

Function(path, options, signature, arguments) Example to get the WETH balance of an address =CALLINT("","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","balanceOf(address)","0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8")

How to specify the chain​

All queries are assumed to be for Etheruem unless otherwise specified. We recommend using the COPS function, but using CONCATENATE to build a string works as well.

  • =CALLINT(path,targetAddress|latest/blocknumber|chain,function signature,argument)
    • =CALLINT("","0x2791bca1f2de4661ed88a30c99a7a9449aa84174|latest|polygon","balanceOf(address)","0xe7804c37c13166ff0b37f5ae0bb07a3aebb6e245")*10^-6
  • =CALLINT(path,COPS(targetAddress, latest/blocknumber, chain), function signature, argument)
    • =CALLINT("",COPS("0x2791bca1f2de4661ed88a30c99a7a9449aa84174", 40687000, "polygon"), "balanceOf(address)", "0xe7804c37c13166ff0b37f5ae0bb07a3aebb6e245")*10^-6

How path works​

Path is utilized for functions that return objects and arrays. To index an array use "/" and to index an object use "."

  • Example of an array. To get the LTV of USDC on Aave v2. getReserveConfigurationData returns an object that can be indexed. By passing "1" you will get the result on the 1 position. =CALLINT("1","0x057835Ad21a177dbdd3090bB1CAE03EaCF78Fc6d","getReserveConfigurationData(address)","0xa0b86991c6218b36c1d19d4a2e9eb0ce3606eb48")

  • Example of an array within array. To get the 2nd token's symbol & address: WBTC & 0x2260fac5e5542a773aa44fbcfedf7c193bc2c599 

    `=CALLCSTR("/1./","0x057835Ad21a177dbdd3090bB1CAE03EaCF78Fc6d","getAllReservesTokens()")`

    `=CALLADDRESS("/1/0","0x057835Ad21a177dbdd3090bB1CAE03EaCF78Fc6d","getAllReservesTokens()")`

How options work​

Options is by default the target address for the function call. However, the user may utilize COPS(target, blocknumber) to make historical calls.

  • Example to get the WETH balance of an address at a specific block =CALLINT("",COPS("0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2",15986709),"balanceOf(address)","0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8")

How signatures work​

Signature is the function written on the smart contract & displayed on Etherscan.

  • Example to get the WETH balance of an address =CALLINT("","0xc02aaa39b223fe8d0a0e5c4f27ead9083c756cc2","balanceOf(address)","0x8ad599c3a0ff1de082011efddc58f1908eb6e6d8")

How arguments work​

Arguments is whatever you are passing into the function call. You can pass no arguments or multiple arguements by adding multiple commas.

  • Example of having no arguments. This is a query for a Chainlink ETH-USD price at a specific block. =CALLINT("", COPS("0x5f4ec3df9cbd43714fe2740f5e3616155c5b8419", 15986709),"latestAnswer()")
  • Example of having more than one arguement. This is a query for accountAssets by a user's address on Compound v2.=CALLINT("","0x3d9819210a31b4961b30ef54be2aed79b9c9cd3b","accountAssets(address,uint256)","0xdc10fc554d3729d4bd570afe8ff5d8b2f5207781",0)

  • Example of passing an array. This is query is to calculate the TWAP price of the Uniswap v3 ETH-USDC pool. "/0" is to get the tick and "0,14400" is so we get info from now and 14400 seconds ago. =CALLINT("/0","0x88e6a0c2ddd26feeb64f039a2c41296fcb3f5640","observe(uint32[])",ARRAY(0,14400))
  • Example of an array & struct. This is query is calculate the TWAP price of the Balancer wstETH-ETH pool from now to 14400 seconds ago. = CALLINT("/0", "0x32296969ef14eb0c6d29669c550d4a0449130230", "getTimeWeightedAverage((uint8,uint256,uint256)[])", ARRAY(STRUCT(0,1400,0)))

How the Token functions work​

We have four token functions (Ethereum only) - [Web3 Sheets Demo Token Functions][https://docs.google.com/spreadsheets/d/1vDRSv8F2YzIq1VmQLZf_gDScjR112rpnbFqHQ8UR-dM/edit?usp=sharing] For a list of names and symbol check the Token List

  1. TokenAddressByName: returns the token address
  2. TokenDecimalsByName: returns the token decimals
  3. TokenAddressBySymbol: returns the token address
  4. TokenDecimalsBySymbol: returns the token decimals