Skip to main content

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 on 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

1. Project Setup

  1. To get started, you'll need some basic React scaffolding. To generate this, run the following in your terminal:


    _2
    npx create-react-app my-terra-app
    _2
    cd my-terra-app

  2. Then, install the @terra-money/wallet-provider package:


    _1
    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.

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


    _22
    import ReactDOM from "react-dom";
    _22
    import "./index.css";
    _22
    import App from "./App";
    _22
    import reportWebVitals from "./reportWebVitals";
    _22
    import {
    _22
    getChainOptions,
    _22
    WalletProvider,
    _22
    } from "@terra-money/wallet-provider";
    _22
    _22
    getChainOptions().then((chainOptions) => {
    _22
    ReactDOM.render(
    _22
    <WalletProvider {...chainOptions}>
    _22
    <App />
    _22
    </WalletProvider>,
    _22
    document.getElementById("root")
    _22
    );
    _22
    });
    _22
    _22
    // If you want to start measuring performance in your app, pass a function
    _22
    // to log results (for example: reportWebVitals(console.log))
    _22
    // or send to an analytics endpoint. Learn more: https://bit.ly/CRA-vitals
    _22
    reportWebVitals();

  2. Start the application to make sure it works:


    _1
    npm start

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

Getting polyfill errors?

To solve these errors, can downgrade react-scripts: 4.0.3 in your package.json and reinstall your dependencies as a quick fix:

  1. Navigate to my-terra-app in your terminal and run the following:


    _1
    npm install [email protected]

  2. Reinstall your dependencies:


    _1
    npm install

  3. Restart your app:


    _1
    npm start

Alternatively, you can configure your webpack to include the necessary fallbacks. Here's an example that uses react-app-rewired.

  1. 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.

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

  2. Populate the Connect.js file with the following:


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

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


    _14
    import "./App.css";
    _14
    import Connect from "./components/Connect";
    _14
    _14
    function App() {
    _14
    return (
    _14
    <div className="App">
    _14
    <header className="App-header">
    _14
    <Connect />
    _14
    </header>
    _14
    </div>
    _14
    );
    _14
    }
    _14
    _14
    export default App;

  4. Refresh your browser. There should be some new text and buttons in your browser.

  5. 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 will be 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 LUNA 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.

Be aware that you will not see any tokens if your wallet is empty.

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

  2. Populate Query.js with the following:


    _28
    import {
    _28
    useConnectedWallet,
    _28
    useLCDClient,
    _28
    } from "@terra-money/wallet-provider";
    _28
    import React, { useEffect, useState } from "react";
    _28
    _28
    export default function Query() {
    _28
    const lcd = useLCDClient(); // LCD stands for Light Client Daemon
    _28
    const connectedWallet = useConnectedWallet();
    _28
    const [balance, setBalance] = useState(null);
    _28
    _28
    useEffect(() => {
    _28
    if (connectedWallet) {
    _28
    lcd.bank.balance(connectedWallet.walletAddress).then(([coins]) => {
    _28
    setBalance(coins.toString());
    _28
    });
    _28
    } else {
    _28
    setBalance(null);
    _28
    }
    _28
    }, [connectedWallet, lcd]); // useEffect is called when these variables change
    _28
    _28
    return (
    _28
    <div>
    _28
    {balance && <p>{balance}</p>}
    _28
    {!connectedWallet && <p>Wallet not connected!</p>}
    _28
    </div>
    _28
    );
    _28
    }

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


    _16
    import "./App.css";
    _16
    import Connect from "./components/Connect";
    _16
    import Query from "./components/Query";
    _16
    _16
    function App() {
    _16
    return (
    _16
    <div className="App">
    _16
    <header className="App-header">
    _16
    <Connect />
    _16
    <Query />
    _16
    </header>
    _16
    </div>
    _16
    );
    _16
    }
    _16
    _16
    export default App;

  4. Refresh your browser. Your wallet balance will appear in micro-denominations. Multiply by 10610^6 for an accurate balance.

5. Sending a transaction

You can also create and send transactions to the Terra network while utilizing Wallet Provider. You can use Terra.js to generate a sample transaction:


_1
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 Terra Station and select testnet.

You can request tesnet funds from the Terra Testnet Faucet.

To transfer LUNA, you will need to supply a message containing the sender address, recipient address, and send amount (in this case 1 LUNA), as well as fee parameters. Once the message is constructed, the post method on connectedWallet broadcasts it to the network.

📝What happens if something goes wrong?

Wallet Provider supplies useful error types. This example will handle the UserDenied error case, but you can find other cases for error handling on GitHub.

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

  2. Populate Tx.js with the following:


    _63
    import { Fee, MsgSend } from "@terra-money/terra.js";
    _63
    import {
    _63
    useConnectedWallet,
    _63
    UserDenied,
    _63
    } from "@terra-money/wallet-provider";
    _63
    import React, { useCallback, useState } from "react";
    _63
    _63
    const TEST_TO_ADDRESS = "terra12hnhh5vtyg5juqnzm43970nh4fw42pt27nw9g9";
    _63
    _63
    export default function Tx() {
    _63
    const [txResult, setTxResult] = useState(null);
    _63
    const [txError, setTxError] = useState(null);
    _63
    _63
    const connectedWallet = useConnectedWallet();
    _63
    _63
    const testTx = useCallback(async () => {
    _63
    if (!connectedWallet) {
    _63
    return;
    _63
    }
    _63
    if (connectedWallet.network.chainID.startsWith("phoenix")) {
    _63
    alert(`Please only execute this example on Testnet`);
    _63
    return;
    _63
    }
    _63
    _63
    try {
    _63
    const transactionMsg = {
    _63
    fee: new Fee(1000000, "20000uluna"),
    _63
    msgs: [
    _63
    new MsgSend(connectedWallet.walletAddress, TEST_TO_ADDRESS, {
    _63
    uluna: 1000000,
    _63
    }),
    _63
    ],
    _63
    };
    _63
    _63
    const tx = await connectedWallet.post(transactionMsg);
    _63
    setTxResult(tx);
    _63
    } catch (error) {
    _63
    if (error instanceof UserDenied) {
    _63
    setTxError("User Denied");
    _63
    } else {
    _63
    setTxError(
    _63
    "Unknown Error: " +
    _63
    (error instanceof Error ? error.message : String(error))
    _63
    );
    _63
    }
    _63
    }
    _63
    }, [connectedWallet]);
    _63
    _63
    return (
    _63
    <>
    _63
    {connectedWallet?.availablePost && !txResult && !txError && (
    _63
    <button onClick={testTx}>Send 1USD to {TEST_TO_ADDRESS}</button>
    _63
    )}
    _63
    _63
    {txResult && <>{JSON.stringify(txResult, null, 2)}</>}
    _63
    {txError && <pre>{txError}</pre>}
    _63
    _63
    {connectedWallet && !connectedWallet.availablePost && (
    _63
    <p>This connection does not support post()</p>
    _63
    )}
    _63
    </>
    _63
    );
    _63
    }

    📝note

    Because all coins are denominated in micro-units, you will need to multiply any coins by 10610^6 . For example, 1000000 uluna = 1 LUNA.

  3. 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:


    _18
    import "./App.css";
    _18
    import Connect from "./components/Connect";
    _18
    import Query from "./components/Query";
    _18
    import Tx from "./components/Tx";
    _18
    _18
    function App() {
    _18
    return (
    _18
    <div className="App">
    _18
    <header className="App-header">
    _18
    <Connect />
    _18
    <Query />
    _18
    <Tx />
    _18
    </header>
    _18
    </div>
    _18
    );
    _18
    }
    _18
    _18
    export default App;

  4. 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: