MvKT

Authors

This content was created by Tezos Ukraine under MIT Licence, and adapted for OpenMavryk. The original version can be found here in multiple languages.

How to Use the MvKT API in a Simple Project on Mavryk

In the previous lessons, we talked about how indexers work and showed a couple of examples. Now let's explain how to use them for real-life tasks. We will make a simple website for displaying the balance of an address, then explore querying contract and protocol data.

We will use the public MvKT API and JavaScript with the jQuery library in our examples. Nothing complicated, just one HTML file with a script.

Displaying Address Balance Using the MvKT API

The most popular use case for blockchain explorers and indexers is to check the balance of different tokens for a given address. It is convenient when storing cryptocurrencies in a cold wallet: you do not need to connect it to the network again, thus endangering the funds.

We will make a simple page where users can enter their addresses and check the balance in mav. Then we will add the display of token balances and some other information. To do this, we will use the MvKT API.

First, let's create an empty HTML file in VS Code (you may use another editor, of course) and add the essential elements: doctype, head, title, and body.

<!DOCTYPE html>
<html>
<head>
    <title>Mavryk Balance Checker</title>
</head>
<body>
    <h1>Mavryk Balance Checker</h1>
</body>
</html>

We will use AJAX and the jQuery library to request data via the API and process it. Incorporating a library is simple: just provide a link to it in the script element.

<script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>

Let's get the balance of an address via AJAX.

<script>
$(document).ready(function() {
    $.ajax({
        url: "https://api.mavryk.network/v1/accounts/mv1GBb32VWmpErgz1jeyGcBgwYHCzw1XDTBV/balance",
        type: "GET",
        success: function(data) {
            var balance = data / 1000000;
            document.getElementById("balance").innerHTML = balance;
        }
    });
});
</script>

First, we added the $(document).ready() command. It ensures the page is loaded before the scripts are processed.

Then we wrote a request to MvKT using AJAX: in "url," the request link to get the balance; in "type," the type of the GET request to get information; and in "success," the function that will process the response.

In the function, we will declare the variable balance, assign the value of the answer (data), and immediately divide it by a million. You must do this because the indexer returns the balance in mumav, millionths of mav.

To use the balance variable in HTML, you need to assign an internal id to this variable. Let's do this with the document.getElementById method.

In the end, we will add a h2 element, in which we will display the balance. To display the variable's value, we use the span element and the id previously assigned to the balance variable.

<h2>Balance: <span id="balance">Loading...</span> mav</h2>

Adding a button and field to check specific address balance

AJAX now sends an API request as soon as the page loads. Let's add a button, pressing which will launch the request.

To do this, wrap the h2 in a div element and make it hidden with the style="display:none" parameter.

Let's create a button and add a call to the check function to it, in which we will place the entire request code. At the end of the function, add a change in the display style of the div to a visible block.

Now we need to add a field for entering the user's address and tweak the check() function to insert it into the API request.

<!DOCTYPE html>
<html>
<head>
    <title>Mavryk Balance Checker</title>
    <script src="https://code.jquery.com/jquery-3.6.0.min.js"></script>
</head>
<body>
    <h1>Mavryk Balance Checker</h1>

    <input type="text" id="addressInput" placeholder="Enter mv1... address" style="width: 400px;">
    <button onclick="check(document.getElementById('addressInput').value)">Check Balance</button>

    <div id="result" style="display:none">
        <h2>Balance: <span id="balance"></span> mav</h2>
    </div>

    <script>
    function check(address) {
        $.ajax({
            url: "https://api.mavryk.network/v1/accounts/" + address + "/balance",
            type: "GET",
            success: function(data) {
                var balance = data / 1000000;
                document.getElementById("balance").innerHTML = balance;
                document.getElementById("result").style.display = "block";
            },
            error: function() {
                alert("Error fetching balance. Please check the address.");
            }
        });
    }
    </script>
</body>
</html>

To do this, we did the following:

Added the address parameter to the check() function.
Changed the value of the "url" field. When run, the script will make a valid API request using the received address.
Added a field for entering an address with an id.
Changed the button's code so that pressing it would launch the check() function and pass the entered address to it.

Now you can enter any address and, by pressing the button, get its balance in mav.

This is a simple example: the MvKT API returns the user's balance as JSON with only one number. The answer does not even need to be further processed: everything works as it is.

Querying Protocol Information

The MvKT API provides various endpoints to query protocol and network information. For example, you can get current protocol parameters:

$.ajax({
    url: "https://api.mavryk.network/v1/protocols/current",
    type: "GET",
    success: function(data) {
        console.log("Current protocol:", data.alias);
        console.log("Block time:", data.constants.timeBetweenBlocks, "seconds");
    }
});

Querying Account Operations

You can also query the operations history for any account:

$.ajax({
    url: "https://api.mavryk.network/v1/accounts/mv1.../operations",
    type: "GET",
    success: function(data) {
        data.forEach(function(op) {
            console.log(op.type, op.amount / 1000000, "mav");
        });
    }
});

Working with Contracts

To query a smart contract's storage:

$.ajax({
    url: "https://api.mavryk.network/v1/contracts/{contract_address}/storage",
    type: "GET",
    success: function(data) {
        console.log("Contract storage:", data);
    }
});

MvKT API Endpoints

The full MvKT API documentation is available at api.mavryk.network. Some useful endpoints include:

/v1/accounts/{address} - Account information
/v1/accounts/{address}/balance - Account balance
/v1/accounts/{address}/operations - Account operations history
/v1/contracts/{address} - Contract information
/v1/contracts/{address}/storage - Contract storage
/v1/protocols/current - Current protocol information
/v1/tokens/balances?account={address} - Token balances for an account
/v1/head - Current chain head information

Homework

Build a simple dashboard that displays:

Your account balance in mav
Your token balances using the /v1/tokens/balances endpoint
Your recent operations using the /v1/accounts/{address}/operations endpoint

Hints

For token balances, use:

$.ajax({
    url: "https://api.mavryk.network/v1/tokens/balances?account=" + address,
    type: "GET",
    success: function(data) {
        data.forEach(function(token) {
            console.log(token.token.metadata.name, token.balance);
        });
    }
});

Remember that token amounts need to be divided by 10^decimals to get the actual human-readable amount. The decimals value can be found in token.token.metadata.decimals.

How to Use the MvKT API in a Simple Project on Mavryk

Displaying Address Balance Using the MvKT API​

Adding a button and field to check specific address balance​

Querying Protocol Information​

Querying Account Operations​

Working with Contracts​

MvKT API Endpoints​

Homework​

Hints​