Getting Started

Gear-JS API

The Gear-JS API offers a set of utilities, libraries, and tools that enable JavaScript applications to interact with programs running on the Vara network via queries to a Vara node. For applications built using the Sails framework, it is generally recommended to use Sails-JS, which leverages the Gear-JS API for low-level communication with Vara nodes.

The sections below describe tools for implementing basic functions in a JS application, such as managing key pairs (accounts), calculating gas required for network operations, uploading programs to the network, sending messages to programs, reading program states, retrieving messages from the user's mailbox, working with metadata, and more. Useful code snippets are provided in the Cookbook section.

The basic API is implemented on the Substrate layer and is consistent across all Substrate-based networks. The Gear-JS API code is available on GitHub. A complete API overview can be found on the Polkadot documentation portal.

Installation

Install the Gear-JS API using npm:

npm install @gear-js/api

Getting Started

Start the API connection to the local running RPC node:

import { GearApi } from '@gear-js/api';

const gearApi = await GearApi.create();

Connect to a different node:

const gearApi = await GearApi.create({
  providerAddress: 'ws[s]://someIP[:somePort]',
});

ws://127.0.0.1:9944

wss://rpc.vara.network

Retrieve node information:

const chain = await gearApi.chain();
const nodeName = await gearApi.nodeName();
const nodeVersion = await gearApi.nodeVersion();
const genesis = gearApi.genesisHash.toHex();

Example

This simple example demonstrates how to subscribe to new blocks and get chain specifications:

async function connect() {
  const gearApi = await GearApi.create({
    providerAddress: 'wss://rpc.vara.network',
  });

  const [chain, nodeName, nodeVersion] = await Promise.all([
    gearApi.chain(),
    gearApi.nodeName(),
    gearApi.nodeVersion(),
  ]);

  console.log(
    `Connected to chain ${chain} using ${nodeName} v${nodeVersion}`,
  );

  const unsub = await gearApi.gearEvents.subscribeToNewBlocks((header) => {
    console.log(
      `New block with number: ${header.number.toNumber()} and hash: ${header.hash.toHex()}`,
    );
  });
}

connect().catch(console.error);

Refer to the NFT Marketplace example for a demonstration of creating a React application that connects to an NFT smart contract running on the blockchain.