TRON Developer Guide—TronGridJS

Introduction

TronGridJS is a Javascript library for utilizing TronGrid APIs to retrieve blockchain data from the TRON network.

Compatibility

• Version built for Node.js v6 and above.
• Version built for browsers with more than 0.25% market share.

TronGridJS is also compatible with front-end frameworks like:

• Angular
• React
• Vue

TronGridJS can also be shipped in a Chrome extension.

Installation

TronGridJS — NPM Package

NPM

• Shell

> npm install trongrid

Yarn

• Shell

> yarn add trongrid

Build Steps

If you would like to download and build locally, please follow the below steps:

• Shell

git clone https://github.com/TRON-US/trongrid-js.git
cd trongrid-js
yarn install
yarn dev
yarn build
yarn test

Supported APIs

TronGridJS allows for easy access to the new v1 APIs provided by TronGrid. Since TronGridJS uses TronWeb as a dependency, you need to initialize TronGridJS with TronWeb as a constructor parameter:

• JavaScript

const tronWeb = new TronWeb({
        fullHost: node.HOST,
        privateKey: node.PRIVATE_KEY
    })
const tronGrid = new TronGrid(tronWeb)
tronGrid.account.get(accountAddress, options)

• JavaScript

tronGrid.account.getTransactions(accountAddress, options)

• JavaScript

tronGrid.asset.getAll(options)

• JavaScript

tronGrid.asset.get(assetIdentifier, options)

• JavaScript

tronGrid.asset.getList(assetName, options)

• JavaScript

tronGrid.block.getEvents(identifier, options)

• JavaScript

tronGrid.contract.getEvents(contractAddress, options)

• JavaScript

tronGrid.transaction.getEvents(id, options)

Responses & Pagination

Any API will return a response with a success property, a data array, and a meta object. For example, await tronGrid.asset.getAll() will return something like:

• JSON

{
    "success": true,
    "data": [
        {
            "confirmed": true,
            "id": "1002225",
            "abbr": "DbDsgVP3GRh",
            "description": "KEYS unlock Cryptocurrency. Keys are a digital asset designed to work as medium of exchange.",
            "frozen_supply": [
                {
                    "frozen_days": 730,
                    "frozen_amount": 75926666666
                }
            ],
            "name": "KEYS",
            "num": 22778,
            "precision": 0,
            "total_supply": 227780000000,
            "trx_num": 22778,
            "url": "www.KEYS.crypto.org",
            "vote_score": 0,
            "owner_address": "4149b3dad5ef9dbab6a059fc95159efcecd5db910e",
            "start_time": 1553538720706,
            "end_time": 1553538960706
        },
        ...
    ],
    "meta": {
        "total": 2,
        "at": 1553548776704,
        "fingerprint": "8xuwf4jd2dpoSms5KzLhxY9fmCm9oJA5164Qd7T2SexRSHYCwvRAr2zJGtwJceEcGWz",
        ...
    }
}

As you can see, in the meta fields, there is the fingerprint you must pass to next request as an option in order to get next page.

Usage

Regular Use

Install TronWeb

• Shell

npm install tronweb

Initialize TronWeb and create a TronGridJS instance

• JavaScript

const TronGrid = require('trongrid');
const TronWeb = require('tronweb');
const tronWeb = new TronWeb({
    fullHost: 'https://api.trongrid.io'
});
const tronGrid = new TronGrid(tronWeb);

Example

• JavaScript

const TronGrid = require('trongrid');
const TronWeb = require('tronweb');
const tronWeb = new TronWeb({
    fullHost: 'https://api.trongrid.io'
});
const tronGrid = new TronGrid(tronWeb);
tronGrid.setExperimental('your experimental key');
async function getAccount() {
    const address = 'TPL66VK2gCXNCD7EJg9pgJRfqcRazjhUZY';
    const options = {
        Show_assets: true,
        only_confirmed: true,
    };
    // awaiting
    const account = await tronGrid.account.get(address, options);
    console.log({account});
    // promise
    tronGrid.account.get(address, options).then(account => {
        console.log({account});
    }).catch(err => console.error(err));
    // callback
    tronGrid.account.get(address, options, (err, account) => {
        if (err)
            return console.error(err);
        console.log({account});
    });
}
async function getTransactions() {
    const address = 'TPL66VK2gCXNCD7EJg9pgJRfqcRazjhUZY';
    const options = {
        only_to: true,
        only_confirmed: true,
        limit: 100,
        order_by: 'timestamp,asc',
        min_timestamp: Date.now() - 60000 // from a minute ago to go on
    };
    // awaiting
    const transactions = await tronGrid.account.getTransactions(address, options);
    console.log({transactions});
    // promise
    tronGrid.account.getTransactions(address, options).then(transactions => {
        console.log({transactions});
    }).catch(err => console.error(err));
    // callback
    tronGrid.account.getTransactions(address, options, (err, transactions) => {
        if (err)
            return console.error(err);
        console.log({transactions});
    });
}
async function getAssets() {
    const address = 'TXk39yyhzpfbqtU1BATUzpcfQ37L8Tc4Ht';
    const options = {};
    // awaiting
    const assets = await tronGrid.asset.get(address);
    console.log({assets});
    // promise
    tronGrid.asset.get(address, options).then(assets => {
        console.log({assets});
    }).catch(err => console.error(err));
    // callback
    tronGrid.asset.get(address, options, (err, assets) => {
        if (err)
            return console.error(err);
        console.log({assets});
    });
}
getAccount();
getTransactions();
getAssets();

Plugin

You can plug TronGrid in TronWeb to substitute the standard method tronWeb.trx.getTransactionRelated(...) with a method that calls internally tronGrid.account.getTransactions(...).

To use it, the user must register TronGrid as a plugin:

• JavaScript

tronWeb.plugin.register(TronGrid);

It may sometimes be necessary to pass some options to the plugin interface. Looking at the test in test/unit/plugin.test.js, you can register the plugin as:

• JavaScript

let result = tronWeb.plugin.register(GetNowBlock, {
    someParameter: 'some value'
})

For the MVP, the experimental access code can be passed as an option to the plugin:

• JavaScript

tronWeb.plugin.register(TronGrid, {experimental: ... });

After registering the plugin, call:

• JavaScript

await tronWeb.trx.getTransactionsFromAddress(address);

and

• JavaScript

await tronWeb.trx.getTransactionsToAddress(address);

will return results from TronGrid under the hood.