Converting tokens

The API allows you to convert any in-game tokens or BEAM associated with a profile, using Beam's decentralized exchange swap.onbeam.com (opens in a new tab). Conversion rates are determined via an Automated Market Maker mechanism, and depend on supply and demand of the respective tokens. You can learn more about setting up a liquidity pool for your own tokens here (opens in a new tab), in order to enable trading.

General flow

In general, swapping tokens via the API always follows the same process - fetching the price for the conversion, and then executing the swap. This two-step process serves as an important safeguard against overpaying, as exchange prices fluctuate.

To obtain prices, you'd pass in to the API

the contract addresses of the desired input and output tokens
- the zero address (0x0000000000000000000000000000000000000000) can be used to refer to BEAM tokens
an amount to swap, either a desired input and output token amount

Depending on the "direction" of the conversion, there are two different use cases, which are covered with examples below too. Let's assume we have two tokens IN and OUT:

The player wants to swap 100 IN to OUT
- we first need to get the amount of OUT we can expect to get for 100 IN
- then convert it with an exact input swap to make sure we get the highest amount of OUT for our 100 IN
The player wants to buy 10 OUT
- here we first fetch the required amount of IN to obtain 10 OUT
- then convert it with an exact output swap to make sure get exactly 10 OUT

Converting with an exact input amount

We assume our player owns 1000 in-game tokens, and wants to convert them on the spot to BEAM tokens. We first need to get a quote and see how much BEAM we'd get by calling getQuoteForOutput, and passing in our input amount of 1000.

const quoteOutput = await beam.exchange.getQuoteForOutput(
  "0x008518e76FAD03f592Bbb7E394C762d5FD54cb97", // input token address
  "0x0000000000000000000000000000000000000000", // output token address, 0x0... refers to native BEAM (gas token)
  "1000" // input token amount to swap
);
 
// {
//   "tokenIn": "0x008518e76FAD03f592Bbb7E394C762d5FD54cb97",
//   "tokenOut": "0x0000000000000000000000000000000000000000",
//   "amountIn": "1000",
//   "amountOut": "10.1"
// }

In this case we can expect to get 10.1 BEAM for 1000 of our tokens. If the player is happy with the result, we execute the swap by simply passing in the result of the previous call to convertInputs, which makes sure we spend exactly 1000 in-game tokens, and receive at least 10.1 BEAM.

const swapTransaction = await beam.exchange.convertInput(
  "entity-id",
  quoteOutput
);
 
// {
//   "status": "success",
//   "type": "custodial",
//   "transactionHash": '0x71f3f259568e9875c41a4350a3912a3a7650d9321ccd1d57641241128b4e504f',
//   "explorerUrl": "https://subnets.avax.network/beam/0x71f3f259568e9875c41a4350a3912a3a7650d9321ccd1d57641241128b4e504f"
// }

Converting with an exact output amount

In this example, the player wants to buy exactly 10 jewel tokens, using some of their in-game tokens. To determine the price the player has to pay, we call getQuoteForInput with the desired output amount of 10.

const quoteInput = await beam.exchange.getQuoteForInput(
  "0x008518e76FAD03f592Bbb7E394C762d5FD54cb97", // input token address
  "0xF65B6f9c94187276C7d91F4F74134751d248bFeA", // output token address, "jewel token"
  "10" // desired output token amount
);
 
// {
//   "tokenIn": "0x008518e76FAD03f592Bbb7E394C762d5FD54cb97",
//   "tokenOut": "0xF65B6f9c94187276C7d91F4F74134751d248bFeA",
//   "amountIn": "42.1",
//   "amountOut": "10"
// }

Calling convertOutput with the result above makes sure we spend a maximum of 42.1 in-game tokens, and receive exactly 10 jewels.

const swapTransaction = await beam.exchange.convertOutput(
  "entity-id",
  quoteInput
);
 
// {
//   "status": "success",
//   "type": "custodial",
//   "transactionHash": '0x71f3f259568e9875c41a4350a3912a3a7650d9321ccd1d57641241128b4e504f',
//   "explorerUrl": "https://subnets.avax.network/beam/0x71f3f259568e9875c41a4350a3912a3a7650d9321ccd1d57641241128b4e504f"
// }

Introduction Introduction