Skip to content

Setting Up a Moonbeam Node and Connecting to the Polkadot JS GUI

You can find all of the relevant code for this tutorial on the code snippets page


This guide outlines steps to create a node for testing the Ethereum compatibility functionality of Moonbeam.


This tutorial was created using the pre-alpha release of Moonbeam. The Moonbeam platform, and the Frontier components it relies on for Substrate-based Ethereum compatibility, are still under very active development. We have created this tutorial so you can test out Moonbeam’s Ethereum compatibility features. Even though it is still in development, we believe it’s important that interested community members and developers have the opportunity to start to try things with Moonbeam and provide feedback.

The examples in this guide assume an Ubuntu 18.04-based environment and will need to be adapted accordingly for MacOS or Windows. If you follow to the end of this guide, you will have a running Moonbeam node and will be able to connect it to the default Polkadot JS GUI.

Installation and Setup

We start by cloning a specific branch of the moonbeam repo that you can find here:

git clone -b moonbeam-tutorials

Then, initialize and update the following git sub-modules:

cd moonbeam && git submodule update --init --recursive

Here is what the output of the whole process should display:

Output from clone action

Next, install Substrate and all its prerequisites (including rust), by executing:

curl -sSf | bash -s -- --fast

Once you have followed all of the procedures above, it's time to build the node by running:

cargo build --release

If a cargo not found error shows up in the terminal, manually add Rust to your system path (or restart your system):

source $HOME/.cargo/env


The initial build will take a while, depending on your hardware. You should plan on 30 minutes. You may see warnings related to evm v0.16.1 and use of deprecated item 'sc_service::AbstractService::spawn_essential_task' which can be ignored for purposes of this guide.

Here is what the tail end of the build output should look like:

End of build output

Then you will want to run the node in dev mode using the following command:

./target/release/node-moonbeam --dev


For people not familiar with Substrate, the --dev flag is a way you can run a Substrate-based node in a single node developer configuration for testing purposes. You can learn more about --dev in this Substrate tutorial.

You should see an output that looks like the following, showing that blocks are being produced:

Output shows blocks being produced

Connecting Polkadot JS Apps to a Local Moonbeam Node

The locally-running Moonbeam node is a Substrate-based node, so we can interact with it using standard Substrate tools. Let’s start by connecting to it with Polkadot JS Apps.
Open a browser to:

This will open Polkadot JS Apps and bring you to the RPC configuration area, where you specify which Substrate RPC endpoint you want to connect to. You will want to toggle the “remote node/endpoint to connect to” to “Local Node (Own,” which is the very last option in the dropdown (you have to scroll down):

Select Local Node

Next, we need to add Moonbeam custom types to Polkadot JS, so it understands them. Under settings navigate to the “Developer” tab, enter the following JSON and hit Save:

  "Address": "AccountId",
  "LookupSource": "AccountId",
  "Account": {
    "nonce": "U256",
    "balance": "U256"
  "Transaction": {
    "nonce": "U256",
    "action": "String",
    "gas_price": "u64",
    "gas_limit": "u64",
    "value": "U256",
    "input": "Vec<u8>",
    "signature": "Signature"
  "Signature": {
    "v": "u64",
    "r": "H256",
    "s": "H256"

It should look like this in the UI:

Node selected in UI

With Polkadot JS properly set up, you can look at blocks being produced in the explorer view, examine the chain state, etc.

An important note is that, in this development node, there are two completely different sets of states:

  1. Substrate account state which you will see under Accounts, for example
  2. State that is contained within the included EVM

Querying Account State

Since many of you will be familiar with the standard Substrate-based functionality, let’s look at state within the EVM using the Substrate API.

Navigate to Chain state, select the “evm” module, and select “accounts(H160): Account” as the thing we want to query.

Enter 0x6Be02d1d3665660d22FF9624b7BE0551ee1Ac91b as the account whose state we want to query. This is an account in the Moonbeam dev node that has been given an initial balance via the genesis configuration. If you query this account, you should get a balance back that looks like this:

Querying the account


If you see “Unknown” in the response, check that the Moonbeam custom types have been loaded as described above.

From here, you can begin testing Moonbeam’s Ethereum compatibility by sending money via MetaMask, via Remix, with Truffle, or using the Web3 library.