Skip to main content

Get started with Fluid.js

This is an in-depth guide on how to use the terra.js SDK.

In this tutorial, you'll learn how to:

  1. Set up your project
  2. Set up a Fluid LCD (light client daemon)
  3. Create and connect a wallet
  4. Query a swap contract
  5. Create, sign, and broadcast a transaction

By the end of this guide, you'll be able to execute a token swap from your application using Fluid.js.

Prerequisites​

1. Set up your project​

  1. Create a new directory for your project:

_1
mkdir my-terra-js-project

  1. Enter your new project directory:

_1
cd <my-terra-js-project>

  1. Next, initialize npm, install the terra.js package, and create an index.js file to house the code:

_3
npm init -y
_3
npm install @terra-money/terra.js
_3
touch index.js

  1. Open the package.json file in a code editor and add "type": "module",.

_5
{
_5
// ...
_5
"type": "module"
_5
// ...
_5
}

2. Initialize the LCD​

Fluid’s LCD or Light Client Daemon allows users to connect to the blockchain, make queries, create wallets, and submit transactions. It's the main workhorse behind terra.js.

  1. Install a fetch library to make HTTP requests and dynamically pull recommended gas prices. You can use the one referenced below or choose your favorite.

_1
npm install --save isomorphic-fetch

  1. Open your index.js file in a code editor and input the following to initialize the LCD:

_14
import fetch from "isomorphic-fetch";
_14
import { Coins, LCDClient } from "@terra-money/terra.js";
_14
const gasPrices = await fetch(
_14
"https://pisco-api.terra.dev/gas-prices", { redirect: 'follow' }
_14
);
_14
const gasPricesJson = await gasPrices.json();
_14
const gasPricesCoins = new Coins(gasPricesJson);
_14
const lcd = new LCDClient({
_14
URL: "https://pisco-lcd.terra.dev", // Use "https://phoenix-lcd.terra.dev" for prod "http://localhost:1317" for localterra.
_14
chainID: "pisco-1", // Use "phoenix-1" for production or "localterra".
_14
gasPrices: gasPricesCoins,
_14
gasAdjustment: "1.5", // Increase gas price slightly so transactions go through smoothly.
_14
gas: 10000000,
_14
});

Switching to LocalTerra or the mainnet

The previous code block shows how to connect to the pisco testnet. To connect to LocalTerra, change the URL to ”http://localhost:1317”. To connect to the phoenix-1 mainnet for production, use “https://phoenix-lcd.terra.dev”.

You will also need to change the chainID from "pisco-1" to ”localterra” or "phoenix-1".

3. Create a pisco testnet wallet​

  1. You'll need a wallet to sign and submit transactions. Create a new wallet using the Fluid Station extension. Be sure to save your mnemonic key!

  2. After creating your wallet, you’ll need to set it to use the testnet. Click the gear icon in the extension and change the network from mainnet to testnet.

  3. Add the following code to your index.js file and input your mnemonic key:


_5
import { MnemonicKey } from "@terra-money/terra.js";
_5
const mk = new MnemonicKey({
_5
mnemonic: " //Input your 24-word mnemonic key here//",
_5
});
_5
const wallet = lcd.wallet(mk);

Mnemonic security

Although this tutorial has you input your mnemonic directly, this practice should be avoided in production. For security reasons, it's better to store your mnemonic key data in your environment by using process.env.SECRET_MNEMONIC or process.env.SECRET_PRIV_KEY. This practice is more secure than a hard-coded string.

  1. Request testnet funds for your wallet by navigating to the Fluid faucet and inputting your wallet address. You'll need these funds to perform swaps and pay for gas fees. Once the funds are in your wallet, you’re ready to move on to the next step.

4. Find a contract address​

To find the contract address for a specific Terraswap pair, visit https://app.terraswap.io/

5. Query a Terraswap contract and set up the transaction​

Before you can perform a swap, you’ll need a belief price. You can calculate the belief price of one token by querying the proportion of the two pooled tokens. The belief price +/- the max_spread is the range of possible acceptable prices for this swap.

  1. Add the following code to your index.js file. Make sure the contract address is correct.

_3
const pool = "<INSERT_POOL_ADDRESS>"; // A terraswap contract address on pisco.
_3
const { assets } = await lcd.wasm.contractQuery(pool, { pool: {} }); // Fetch the amount of each asset in the pool.
_3
const beliefPrice = (assets[0].amount / assets[1].amount).toFixed(18); // Calculate belief price using proportion of pool balances.

  1. Next, generate a message to broadcast to the network:

_20
import { MsgExecuteContract } from "@terra-money/terra.js";
_20
const terraSwap = new MsgExecuteContract(
_20
wallet.key.accAddress,
_20
pool,
_20
{
_20
swap: {
_20
max_spread: "0.001",
_20
offer_asset: {
_20
info: {
_20
native_token: {
_20
denom: "uluna",
_20
},
_20
},
_20
amount: "100000",
_20
},
_20
belief_price: beliefPrice,
_20
},
_20
},
_20
new Coins({ uluna: "100000" })
_20
);

6. Broadcast the transaction​

  1. Add the following code to index.js to create, sign, and broadcast the transaction. It's important to specify uluna as the fee denomination becuase Luna is the only denomination the faucet sends.

_6
const tx = await wallet.createAndSignTx({
_6
msgs: [terraSwap],
_6
feeDenoms: ["uluna"],
_6
});
_6
const result = await lcd.tx.broadcast(tx);
_6
console.log(result);

  1. Run the code in your terminal:

_1
node index.js

If successful, you'll see a log of the successful transaction and some new tokens in your wallet.

And that's it! You can find other pool addresses here to call other swaps. Be sure to use the correct testnet or mainnet contract address.

More examples​

View the Common examples section for more information on using Fluid.js.