BUY and SELL function spotlight

Last updated on 

This document explains the syntax and usage of two of Vektor’s core execution functions: BUY() and SELL().

🧠
If you haven’t used VXL before, try our Quick Start Guide! You may also find it useful to first learn about VXL basics and Common Syntax Patterns, or book a call using the CALL function in the app to learn more.

Summary

Vektor’s BUY and SELL functions facilitate swapping of assets on multiple chains and venues supported by Vektor.

  • Use the BUY function to buy an exact amount of an asset at the current market rate (i.e. known “receive” amount).
  • Use the SELL function to sell an exact amount of an asset at the current market rate (i.e. known “spend” amount).

To see the list of supported chains and venues, use the BLOCKCHAINS.GET and VENUES.GET functions respectively.

To use BUY and SELL, you need to have set up at least one labelled address using the LABELS.ADD function.

The default behaviour of the BUY and SELL functions follows these steps:

  1. Establishes which chain you want to transac on, by looking at blockchain parameter you provide.
  2. Checks the price on all the venues that are currently supported on that chain.
  3. Picks the venue with the best price and prepares the transaction for signing.

Optionally, you can fetch price quotes without actually preparing the transaction, and you can also include or exclude specific venues - this is covered in more detail below.

⚠️
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.

Function Specifications

You can use the .QUOTE and .QUOTES subfunctions to simulate buy and sell executions before instructing them, or just use BUY and SELL to execute actual transactions on chain. All quotes come from actual pool data.

Function Description
BUY.QUOTE(...) Get a quote for buying an exact amount of an asset at current market rate
BUY.QUOTES(...) Get a table of buy quotes, broken down by venue and blockchain
BUY(...) Buy an exact amount of an asset at current market rate
SELL.QUOTE(...) Get a quote for selling an exact amount of an asset at current market rate
SELL.QUOTES(...) Get a table of sell quotes, broken down by venue and blockchain
SELL(...) Sell an exact amount of an asset at current market rate

BUY.QUOTE(...) Syntax

⚠️
Note: The Function Helper box pictured above should be useful in helping guide you through the syntax of Vektor functions. It appears automatically when you open the parentheses of a function.

BUY.QUOTE(...) Examples

Get a quote for buying exactly 1 wrapped ETH, spending USDT, querying all supported venues on all chains (with sample output).

Get a quote for buying exactly 1 wrapped ETH, spending USDT, querying all supported venues on Avalanche.

Get a quote for buying exactly 1,000 Brokoli, spending DAI, querying all supported venues on Ethereum.

Get a quote for buying exactly 1,000 Brokoli, spending DAI, querying only Uniswap v2 on Ethereum.

⚠️
Note: The INCLUDE_BLOCKCHAINS , EXCLUDE_BLOCKCHAINS , INCLUDE_VENUES and EXCLUDE_VENUES are optional arguments, so they must be represent by key=value (Python style). In this instance the value can be a list of venues, so use array notation [venue1,venue2,venue3].

Get three separate quotes at the same time, all of them for buying 1 WETH spending USDC, querying three different blockchains.

⚠️
Note: Press Shift+Enter to start a new line in the same command statement, or use the semicolon ;separator. Everything will be executed like a script, probably resulting in several view panes showing the output of each part.

Get the single best quote for buying 1 WETH spending USDC, querying all venues on three specific blockchains.

Analyse slippage effects by comparing quotes of the same pair with three orders of magnitude, using arithmetic to normalise for comparison.

Return the arithmetic difference between two identical quotes on the same venue on two different chains (with sample output).

The above in text for better readability:

BUY.QUOTE(1, WETH, DAI, INCLUDE_VENUES=[UNISWAP_V3], INCLUDE_BLOCKCHAINS=[ETHEREUM]) - BUY.QUOTE(1, WETH, DAI, INCLUDE_VENUES=[UNISWAP_V3], INCLUDE_BLOCKCHAINS=[OPTIMISM])

BUY.QUOTES(...) Syntax

BUY.QUOTES is very similar to BUY.QUOTE except that it outputs a table showing the same quote for each supported venue on each chain, instead of just the single ‘best’ quote found on all chains.

BUY.QUOTES(...) Examples

Get a table of quotes for buying exactly 1 WETH, spending WBTC, querying all supported venues across all supported blockchains (with sample output).

Tables are ordered by best quote first.

Get a table of quotes for buying exactly 1 WETH, spending USDT, querying all supported venues on Ethereum.

Same as above, but excluding Uniswap v3 from the table.

Get multiple tables of quotes, one each for several different chains.

Get a single table of quotes for the same four blockchains above but including Uniswap v2 only.

BUY(...) Syntax

If you use BUY and omit the subfunction suffixes .QUOTE and .QUOTES you get the default behaviour for the BUY function, which is to actually prepare and execute a buy transaction.

The key differences between BUY and BUY.QUOTE[S] are:

  1. Instead of providing INCLUDE_BLOCKCHAINS or EXCLUDE_BLOCKCHAINS as optional parameters, it is necessary to provide a LABEL (a human-readable label for a blockchain address that you’ve registered in Vektor) and a BLOCKCHAIN explicitly. Since LABELS are natively ‘multi-chain’ or ‘chain-agnostic’, this additional information is needed by Vektor to build the transaction.
  2. Instead of just a read-only output in the workspace, the BUY function will prepare an on-chain transaction that you will need to sign when presented with a Signing Request.

By default, the BUY function will run a quote process in the background and pick the best venue automatically, but just like with BUY.QUOTE[S] this can be overridden to include or exclude specific venues.

⚠️
Note: on Curve and Curve clones, due to their StableSwap algorithm design, it is not possible to specify an exact receive amount, hence for Curve on Vektor you must use the SELL function; BUY is not supported.

BUY Examples

Buy exactly 2500 USDC using my ETH on Ethereum, using the labelled address MY_ETH_ADDRESS_4 (with sample Signing Request).

⚠️
Note: You may be prompted to approve a token first before it can be spent on a sell transaction.

Buy exactly 10,000 GMX using my DAI on Arbitrum, using the labelled address MY_ADDRESS , and override default 1% slippage to set at 5%.

Buy exactly 1,000 WETH, using my WBTC on BNBChain (Binance Chain), using the labelled address MY_ADDRESS , and override default 1% slippage to set at 5%, and force venue selection to be Pancakeswap.

Buy exactly 12,500 USDC, using my ETH on Ethereum, using the labelled address MY_ADDRESS, and exclude venues Sushiswap and Uniswap v2.

SELL.QUOTE(...) Syntax

SELL.QUOTE(...) Examples

Get a quote for selling exactly 1 WETH, receiving USDT, querying all supported venues on BNB chain (with sample output).

Get a quote for selling exactly 1 WETH, receiving USDT, querying all supported venues on Fantom.

Get a quote for selling exactly 1,000 Brokoli, receiving DAI, querying all supported venues on Ethereum.

Get a quote for selling exactly 1,000 Brokoli, receiving DAI, querying only Uniswap v2 on Ethereum.

⚠️
Note: The INCLUDE_BLOCKCHAINS , EXCLUDE_BLOCKCHAINS , INCLUDE_VENUES and EXCLUDE_VENUES are optional arguments, so they must be represent by key=value (Python style). In this instance the value can be a list of venues, so use array notation [venue1,venue2,venue3].

Get three separate quotes at the same time, all of them for selling 1 WETH receiving USDC, querying three different blockchains.

⚠️
Note: Press Shift+Enter to start a new line in the same command statement, or use the semicolon ;separator. Everything will be executed like a script, probably resulting in several view panes showing the output of each part.

Analyse slippage effects by comparing quotes of the same pair with three orders of magnitude, using arithmetic to normalise for comparison.

Return the arithmetic difference between two identical quotes on the same venue on two different chains (with sample output).

The above in text for better readability:

SELL.QUOTE(1, WETH, DAI, INCLUDE_BLOCKCHAINS=[ETHEREUM], INCLUDE_VENUES=[UNISWAP_V3]) - SELL.QUOTE(1, WETH, DAI, INCLUDE_BLOCKCHAINS=[OPTIMISM], INCLUDE_VENUES=[UNISWAP_V3])

SELL.QUOTES(...) Syntax

SELL.QUOTES is very similar to SELL.QUOTE except that it outputs a table showing the same quote for each supported venue on each chain, instead of just the single ‘best’ quote found on all chains.

SELL.QUOTES(...) Examples

Get a table of quotes for selling exactly 15 WETH, receiving DAI, querying all supported venues across all supported blockchains (with sample output).

Tables are ordered by best quote first.

Get a table of quotes for selling exactly 1 WETH, receiving USDT, querying all supported venues on Ethereum.

Same as above, but excluding Uniswap venues from the table.

Get multiple tables of quotes, one each for several different chains.

Get a single table of quotes for selling 1 WETH, receiving USDT, querying all venues but Uniswap v3 on the four chains above.

SELL(...) Syntax

If you use SELL and omit the subfunction suffixes .QUOTE and .QUOTES you get the default behaviour for the SELLfunction, which is to actually prepare and execute a sell transaction.

The key differences between SELL and SELL.QUOTE[S] are:

  1. Instead of providing INCLUDE_BLOCKCHAINS or EXCLUDE_BLOCKCHAINS as optional parameters, it is necessary to provide a LABEL (a human-readable label for a blockchain address that you’ve registered in Vektor). and a BLOCKCHAIN explicitly. Since LABELS are natively ‘multi-chain’ or ‘chain-agnostic’, this additional information is needed by Vektor to build the transaction.
  2. Instead of just a read-only output in the workspace, the SELL function will prepare an on-chain transaction that you will need to sign when presented with a Signing Request.

By default, the SELL function will run a quote process in the background and pick the best venue automatically, but just like with SELL.QUOTE[S] this can be overridden to include or exclude specific values.

⚠️
Note: on Curve and Curve clones, due to their stableswap algorithm design, it is not possible to specify an exact receive amount, hence for Curve on Vektor you must use the SELL function; BUY is not supported.

SELL(...) Examples

Sell exactly 1 ETH for USDC on Ethereum, using the labelled address MY_ETH_ADDRESS_4 on Ethereum (with sample Signing Request).

⚠️
Note: You may be prompted to approve a token first before it can be spent on a buy transaction.

Sell 50% of the total balance of NFTX held at the  MY_ADDRESS on Ethereum, and receive DAI, and override default 1% slippage to set at 5%.

Sell 75% of the total balance of WBTC on BNBChain, held at the labelled address MY_ADDRESS , and receive DAI, and override default 1% slippage to set at 5%, and force venue selection to be Pancakeswap.

The above in text for better readability:

SELL(0.75*BALANCE(WBTC, BNBCHAIN, MY_ADDRESS), WBTC, DAI, BNBCHAIN, MY_ADDRESS, SLIPPAGE=0.05, INCLUDE_VENUES=[PANCAKESWAP])

Questions?

Email: [email protected]
Zoom: Use CALL function in Vektor