Getting Started

Welcome to Moralis Beta!

We're excited for you to discover all the cool things you can build with Moralis in just a few lines of code. Before we get started let's go over a few bits of important info.


  • Treat the Beta like a sandbox to try stuff out and have fun. Everything will likely be wiped clean at the end of Beta.

  • The docs assume some knowledge of programming and are a work in progress.

  • If you find a bug, something confusing in the docs, or have suggestions for improvements let us know by posting a new issue in this github repo.


The documentation assumes knowledge of JavaScript, working with objects, querying databases, and some web3 development. See the Pre-Requisites page for more details.

If you're new to Web 3 development this is a great introduction:

And for more experienced devs this is a great introduction to building a dapp on Moralis using Truffle and Ganache.

Create a Moralis server instance

To get started, log into Create a new Moralis Server instance, select your desired location and choose your network. The currently supported networks are:

  • Mainnet

  • Testnet (Ropsten)

  • Local Ganache

It will take a few minutes for the server to spin up. The Dashboard can be accessed by clicking the "Dashboard" button. The Dashboard is where you can view all the data and logs. In server version 0.0.125 or later you will be logged in automatically, otherwise the credentials can be found by clicking the "View Details" button.

Setting Up Local Dev Chain (optional)

When building new smart contracts you need a fast and controlled testing environment. This is where hosting your own local blockchain is extremely useful. If you're new to Web3 development this part can be skipped- use Mainnet or Testnet instead there's plenty you can do with Moralis with existing smart contracts, transactions, and authentication.

To connect Moralis to Ganache or Hardhat check out the video tutorials in the "Setting Up Local Dev Chain" guide.

Email Configuration (optional)

Moralis supports sending emails to users. Click the "View Details" button on your sever instance then the "Email Configuration" tab. You will need to sign up for a SendGrid account and provide the following:

  • API key

  • From Email. This will appear as the "from" address on emails received by users.

Sending an email must done on the server side via Cloud Code as it requires the MasterKey. This is to help prevent the domain from being blacklisted for spam by bad actors.

// in Cloud Code
Moralis.Cloud.define("sendEmailToUser", function (request) {
to: request.user.get("email"),
subject: "Fundamentals",
html: "Pampamentally it does make sense"

EVM Configuration 🚧

Also sync transactions from Ethereum EVM compatible chains

  • Binance Smart Chain (BSC)

  • Polygon (MATIC)

This will create additional tables with similar names and structures as the Ethereum ones but with a different prefix

  • BscTransactions

  • BscTokenTransactions

🚧 When creating new plugins to watch contract events there will be an option to select which EVM network Moralis should watch for the event on (under construction) 🚧.

Install the SDK


The fastest way to get the Moralis SDK into your JavaScript project is through npmcdn available at

<script src="[email protected]/dist/web3.min.js"></script>
<script src=""></script>


In production, make sure to specify the specific version to guard against malicious package updates.

You can use npm info moralis versions to obtain a lits of the available versions and replace <VERSION> below with the lastest value.

<script src="[email protected]<VERSION>/dist/web3.min.js"></script>
<script src="[email protected]<VERSION>/dist/moralis.js"></script>


For larger projects use the npm module​

npm install moralis


Then include it as usual.

const Moralis = require('moralis');


For server-side applications or NodeJs command line tools, include

// In a node environment
const Moralis = require('moralis/node');

Moralis Snippets

To help you code fast you can make use of Moralis snippets available as an extension to Visual Studio Code.

With the extension installed, begin my typing: "moralis" anywhere inside a javascript file.

You will get IntelliSense for the available snippets.

Initialize Moralis

In order to use Moralis in your code it needs to be initialized. You'll need the Server URL and APP ID. These can be found by pressing the "View Details" button on the server instance created above.

Moralis.serverURL = 'https://YOUR_MORALIS_SERVER:1337/server'

⚠️ If the Masterkey needs to be provided, use the following. Please note that the master key should only be used in safe environments and never on the client side‼️

Moralis.initialize("YOUR_APP_ID", "", "YOUR_MASTERKEY");
Moralis.serverURL = 'http://YOUR_MORALIS_SERVER:1337/server'

The JavaScript SDK is originally based on the popular Backbone.js framework, but it provides flexible APIs that allow it to be paired with your favorite JS libraries. Our goal is to minimize configuration and let you quickly start building your JavaScript and HTML5 app on Moralis.

The SDK supports Firefox 23+, Chrome 17+, Safari 5+, and IE 10. IE 9 is supported only for apps that are hosted with HTTPS.


Authenticating new users with Web3 is as simple as:

Moralis.Web3.authenticate().then(function (user) {

This will prompt the user to connect a Web3 wallet like Metamask and request signature. Once the signature has been verified the promise will resolve with a User object.


await Moralis.User.logOut();

How to Authenticate With Metamask, Web3 Development - Ivan on Tech


How to Merge MetaMask Addresses? Web3 Programming Tutorial - Ivan on Tech




Once the user has been authenticated the User object can be retrieved from anywhere with

const user = Moralis.User.current();

The current user will always be authenticated. If there is no logged in user Moralis.User.current() will return null.

Getting Attributes

The User object itself looks like the following.

className: "_User",
id: "EFurGjRPhl",
_objCount: 0,
attributes: {
ACL: ParseACL {permissionsById: {…}},
accounts: ["0xda...cb83"],
authData: {moralisEth: {…}},
createdAt: Date,
ethAddress: "0xda...cb83",
sessionToken: "r:3be8c91cb4db8fe2f154021f96496f49",
updatedAt: Date,
username: "Y9jPGr0H1TcMFHUpYZPjj9xhE",

There are 2 methods for getting user attributes

const user = Moralis.User.current();
const userAddress = user.get("ethAddress");
const username = user.attributes.username;

Setting Attributes

Always use the set() method to change user attributes. Then call save(). Any new attributes will be created automatically.

user.set("phone", "555-555-1234");
user.set("birthDate", "2000-01-01");

For more details see the Users Section.



Once you have data stored in Moralis, you'll probably want to use it! The foundation of retrieving data is the Query. A query describes what data to retrieve and from where.

// set the collection to query
const collectionName = "EthTokenBalance";
const query = new Moralis.Query(collectionName);


To filter the data returned by a query all the usual constraints like equalTo, notEqualTo, greaterThan, lessThanOrEqualTo, containedIn, and limit are available. The query object uses similar syntax as MongoDB queries.

// users with DOGE tokens
query.equalTo("symbol", "DOGE");
// where the balance > 0
query.greaterThan("balance", 0);
// at most 10 results
const results = await query.find();


The data can also be sorted according to specific attributes using the ascending and descending functions.

// highest to lowest balance


Once the query is constructed the results can be obtained using find.

const results = await query.find();
// [EthTokenBalance, EthTokenBalance, ...]

Or only the first

// get a specific user by email
const query = new Moralis.Query(Moralis.User);
query.equalTo("email", "[email protected]");
const user = await query.first();
// {id: "23r2r2qawsdf", attributes: {...} }

For more details see the Queries page

Historical Transaction Data

Whenever a new user is authenticated via Web3, all of their transactions are synced by Moralis into the EthTransactions collection. This data can then be queried.

// get all ETH transactions made by the user
const user = Moralis.User.current();
const transQuery = new Moralis.Query("EthTransactions");
transQuery.equalTo("from_address", user.get("ethAddress"));
const results = await transQuery.find();
// [EthTransaction, EthTransaction, ...]

Note that querying user related data like transactions requires permissions governed by the Access Control List (ACL). This means any data private to a specific user, like transactions, can only be queried by that user. Querying data from other users (like finding someone's profile) requires using the MasterKey. For security reasons the master key should only be used on the server inside Cloud Functions.

Real-Time Data

Historical data is great, but what if we you're building blog site and want to display a special message whenever a new user buys your BLOG token? This is where Live Queries come in. In addition to grabbing the historical results with find() a query can be subscribed to!

// BLOG token holders
const query = new Moralis.Query("EthTokenBalance");
query.equalTo("symbol", "BLOG");
query.greaterThan("balance", 0);
// subscribe for real-time updates
const subscription = await query.subscribe();
// handle events
subscription.on("create", function(data) {
console.log(data.attributes.address, " has joined the BLOG army!");

This will cause an event to be fired whenever the dataset defined by the query changes.

  • create: when a new object is created and fulfills the query

  • update: when an existing object in the query is updated and both the old and new values satisfy the query

  • enter: when an existing object's old values did not satisfy the query but the new values do

  • leave: when an existing object's old values satisfied the query but new values do not

  • delete: when an existing object is deleted

Live queries can be created for any other collection as well. See the Live Query page for more details. To receive real-time updates on smart contract events see the Plugins section of the Web 3 page.

Ethereum Real-Time and Historic Transactions - Web3 Programming


There are several demo projects on our github that highlight the major features of Moralis. Most of the demos are written in plain JavaScript and html to keep them as small as possible.

  • ​Sign in boilerplate: the base for the Severless Dapps tutorial​

    • ​Casino Dapp is the finished dapp for this tutorial

  • ​React-app: a React template starter app

  • ​Gas Demo: authentication, historical transactions, Cloud Functions

    • Displays average gas fees for the top 10 users that paid the most in gas

  • ​Tether Printer: smart contract events, Live Queries

    • Shows the most recent ETH USDT printed by Tether

  • ​Swap Monitor: smart contracts events, Triggers, Live Queries

    • Real-time swaps on the UniSwap DAI / wETH pair

    • Stats on net volume over the last 60 minutes

  • ​User profiles: authentication with both username and Metamask, address linking, changing password, saving additional info to the User object.