Get started with Wallet Provider#

Wallet Provider makes it easy to build Terra Station (browser extension and mobile) functionality into your React application. It contains custom hooks that drastically simplify common tasks like connecting a wallet and triggering transactions.

This guide will cover how to set up a React app, integrate Wallet Provider, check the balance of the connected account, and call a token swap. If you want to integrate Terra Station into an existing react app you can skip past the Project Setup section.

Just want to dive in?

Check out the getting started section for the premade templates in Github.

If you’re using a frontend framework other than React you’ll need to use Wallet Controller instead. Controller provides the sub-structure of Provider. You can see an example of how Wallet Controller works in the Vue.js template example.

Prerequisites#

Terra Station Chrome extension
Node.js version 16+
NPM

1. Project Setup#

To get started, you’ll need some basic React scaffolding. To generate this, run the following in your terminal:
```
npx create-react-app my-terra-app
cd my-terra-app
```
Then, install the @terra-money/wallet-provider package:
```
npm install @terra-money/wallet-provider
```

2. Wrap your app in `WalletProvider`#

Next, you’ll wrap your App with <WalletProvider> to give all your components access to useful data, hooks, and utilities. You’ll also need to pass in information about Terra networks, such as the mainnet or chainId, into the provider via getChainOptions.

Navigate to your Index.js in a code editor and replace the code with the following:

import ReactDOM from 'react-dom';
import './index.css';
import App from './App';
import reportWebVitals from './reportWebVitals';
import { getChainOptions, WalletProvider } from '@terra-money/wallet-provider';

getChainOptions().then((chainOptions) => {
  ReactDOM.render(
    <WalletProvider {...chainOptions}>
      <App />
    </WalletProvider>,
    document.getElementById('root'),
  );
});

// If you want to start measuring performance in your app, pass a function
// to log results (for example: reportWebVitals(console.log))
// or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
reportWebVitals();

Start the application to make sure it works:
```
npm start
```

Your browser should open to http://localhost:3000/, and you should see the react logo with a black background and some text.

Create a new directory called components in the source directory. This directory will house components to trigger different actions from our connected wallet.

3. Put `useWallet` to work#

Now that App.js has inherited the context of WalletProvider, you can start putting your imports to work. You’ll use the multi-purpose useWallet hook to connect your terra station extension to your web browser.

Create a new file in the components directory called Connect.js.

Populate the Connect.js file with the following:

import { useWallet, WalletStatus } from '@terra-money/wallet-provider';
import React from 'react';
export default function Connect() {
  const {
    status,
    network,
    wallets,
    availableConnectTypes,
    connect,
    disconnect,
  } = useWallet();
  return (
    <>
        {JSON.stringify({ status, network, wallets }, null, 2 )} 
        {status === WalletStatus.WALLET_NOT_CONNECTED && (
            <>
            {availableConnectTypes.map((connectType) => (
                <button
                    key={'connect-' + connectType}
                    onClick={() => connect(connectType)}
                >
                    Connect {connectType}
                </button>
            ))}
            </>
        )}
        {status === WalletStatus.WALLET_CONNECTED && (
            <button onClick={() => disconnect()}>
                Disconnect
            </button>
        )}
    </>
  );
}

Open App.js in your code editor and replace the code with the following:

import './App.css';
import Connect from './components/Connect';



function App() {
  return (
    <div className="App">
      <header className="App-header">
        <Connect />


        </header>
    </div>
  );
}

export default App;

Refresh your browser. There should be some new text and buttons in your browser.
Make sure your Terra Station extension is connected to a wallet. Click Connect EXTENSION, and the app will connect to your wallet.

The status, network, and wallets properties in your browser provide useful information about the state of the Terra wallet. Before connecting, the status variable is WALLET_NOT_CONNECTED, and upon connection the status becomes WALLET_CONNECTED. In addition, the wallets array now has one entry with the connectType and terraAddress you used to connect.

You should be able to see these changes in real-time.

4. Querying a wallet balance#

It’s common for an app to show the connected user’s UST balance. To achieve this you’ll need two hooks. The first is useLCDClient. An LCDClient is essentially a REST-based adapter for the Terra blockchain. You can use it to query an account balance. The second is useConnectedWallet, which tells you if a wallet is connected, and if so, basic information about that wallet such as its address.

Note that if your wallet is empty you won’t see any tokens.

Create a file in your Components folder named Query.js.

Populate Query.js with the following:

import { useConnectedWallet, useLCDClient } from '@terra-money/wallet-provider';
import React, { useEffect, useState } from 'react';

export default function Query() {
  const lcd = useLCDClient(); // LCD stands for Light Client Daemon
  const connectedWallet = useConnectedWallet();
  const [balance, setBalance] = useState(null);

  useEffect(() => { 
    if (connectedWallet) { 
      lcd.bank.balance(connectedWallet.walletAddress).then(([coins]) => {
        setBalance(coins.toString());
      });
    } else {
      setBalance(null);
    }
  }, [connectedWallet, lcd]); // useEffect is called when these variables change

  return (
    <div>
      {balance && <p>{balance}</p>}
      {!connectedWallet && <p>Wallet not connected!</p>}
    </div>
  );
}

Open App.js in your code editor and add import Query from './components/Query' to line 3, and <Query /> to line 11. The whole file should look like the following:

import './App.css';
import Connect from './components/Connect';
import Query from './components/Query'


function App() {
  return (
    <div className="App">
      <header className="App-header">
        <Connect />
        <Query />

        </header>
    </div>
  );
}

export default App;

Refresh your browser. Your wallet balance will appear in micro-denominations. Multiply by \(10^6\) for an accurate balance.

5. Sending a transaction#

WalletProvider also helps create and send transactions to the Terra network. You’ll also need Terra.js to help generate the sample transaction:

npm install @terra-money/terra.js

Before broadcasting this example transaction, ensure you’re on the Terra testnet. To change networks click the gear icon in your Terra station and select testnet.

You can request tesnet funds from the faucet. You’ll receive luna which can be swapped for UST within the Station extension.

A UST transfer transaction needs a fee and a message containing the sender address, recipient address, and send amount (in this case 1 UST). Once the message is constructed, the post method on connectedWallet broadcasts it to the network.

What happens if something goes wrong?

Wallet provider also supplies useful error types. This example will handle the UserDenied error case. You can find other cases to handle on Github.

Create a file in your Components folder named Tx.js.

Populate Tx.js with the following:

import { Fee, MsgSend } from '@terra-money/terra.js';
import { useConnectedWallet, UserDenied } from '@terra-money/wallet-provider';
import React, { useCallback, useState } from 'react';

const TEST_TO_ADDRESS = 'terra12hnhh5vtyg5juqnzm43970nh4fw42pt27nw9g9';

export default function Tx() {
  const [txResult, setTxResult] = useState(null);
  const [txError, setTxError] = useState(null);

  const connectedWallet = useConnectedWallet();

  const testTx = useCallback(async () => {
    if (!connectedWallet) {
      return;
    }
    if (connectedWallet.network.chainID.startsWith('columbus')) {
      alert(`Please only execute this example on Testnet`);
      return;
    }
  
    try {
      const transactionMsg = {
        fee: new Fee(1000000, '200000uusd'),
        msgs: [
          new MsgSend(connectedWallet.walletAddress, TEST_TO_ADDRESS, {
            uusd: 1000000,
          }),
        ],
      }

      const tx = await connectedWallet.post(transactionMsg);
      setTxResult(tx);
    } catch (error) {
      if (error instanceof UserDenied) {
        setTxError('User Denied');
      } else {
        setTxError(
          'Unknown Error: ' +
          (error instanceof Error ? error.message : String(error)),
        );
      }
    }
  }, [connectedWallet]);

  return (
    <>
      {connectedWallet?.availablePost && !txResult && !txError && (
        <button onClick={testTx}>Send 1USD to {TEST_TO_ADDRESS}</button>
      )}

      {txResult && <>{JSON.stringify(txResult, null, 2)}</>}
      {txError && <pre>{txError}</pre>}

      {connectedWallet && !connectedWallet.availablePost && (
        <p>This connection does not support post()</p>
      )}
    </>
  );
}

Note

Because all coins are denominated in micro-units, you will need to multiply any coins by \(10^6\) . For example, 1000000 uusd = 1 UST.

Open App.js in your code editor and add import Tx from './components/Tx' to line 4, and <Tx /> to line 12. The whole file should look like the following:

import './App.css';
import Connect from './components/Connect';
import Query from './components/Query';
import Tx from './components/Tx';

function App() {
  return (
    <div className="App">
      <header className="App-header">
        <Connect />
        <Query />
        <Tx />
        </header>
    </div>
  );
}

export default App;

Refresh your browser. You’ll see a new Send button. Click the button to send your transaction. Your station extension will ask you to confirm the transaction.

That’s all! You can find more examples of WalletProvider capabilities in the following example templates:

Get started with Wallet Provider

Contents