ICON JavaScript SDK

1.5.3 · active · verified Tue Apr 21

The ICON JavaScript SDK provides a comprehensive set of tools for interacting with the ICON blockchain network. It enables developers to build decentralized applications (dApps) and services by offering APIs for transaction building, wallet management, unit conversions, and communication with ICON nodes using JSON-RPC version 3. Currently at version 1.5.3, the library sees active development with regular dependency updates and feature additions, as evidenced by recent releases including new APIs like `icx_getNetworkInfo` and ongoing maintenance. Key differentiators include its explicit support for various JavaScript environments (Node.js, browser, React Native) and a modular builder pattern for constructing complex transactions.

Common errors

```
TypeError: Cannot read properties of undefined (reading 'IconBuilder')
```
cause Attempting to destructure `IconBuilder` directly from the main `icon-sdk-js` module when using `require` or incorrect named import with `import`.

fix Access `IconBuilder` as a property of the `IconService` object: `const IconService = require('icon-sdk-js'); const { IconBuilder } = IconService;` or `import IconService from 'icon-sdk-js'; const { IconBuilder } = IconService;`
```
ReferenceError: fetch is not defined
```
cause Running `icon-sdk-js` in an environment (e.g., older Node.js versions or some browser environments) where the global `fetch` API is not available.

fix For Node.js, ensure Node.js >=18.0.0. For older browsers, import a `fetch` polyfill like `whatwg-fetch`.
```
Error: Failed to fetch
```
cause Network issues, incorrect RPC endpoint URL, or CORS policies preventing the browser from connecting to the ICON node.

fix Verify your `rpcUrl` is correct and accessible. Ensure the ICON node is running and configured for public access. For browser apps, check server-side CORS configuration.

Warnings

gotcha The Node.js environment requires a minimum version of 18.0.0. Using older Node.js versions may lead to unexpected errors or unsupported features.
Fix: Upgrade your Node.js runtime to version 18.0.0 or higher using nvm or your preferred package manager.
gotcha When using `icon-sdk-js` in older browser environments that do not natively support the `fetch` API, a polyfill like `whatwg-fetch` is required for network requests to function correctly.
Fix: Include `import 'whatwg-fetch';` in your project's entry point if targeting older browsers.
breaking Version 1.5.0 introduced the `icx_getNetworkInfo` API. If your application relies on network information that might have been inferred differently before, consider updating your logic to use this new, explicit API.
Fix: Update your code to call `iconService.getNetworkInfo().execute()` to retrieve comprehensive network details.
gotcha Dependency vulnerabilities are regularly addressed through minor version bumps (e.g., `get-func-name`, `browserify-sign`, `@babel/traverse`). Users should regularly update to the latest patch version to ensure all known security fixes are applied.
Fix: Run `yarn upgrade icon-sdk-js` or `npm update icon-sdk-js` to get the latest stable version.

Install

npm install icon-sdk-js npm
yarn add icon-sdk-js yarn
pnpm add icon-sdk-js pnpm

Imports

IconService

wrong:

import { IconService } from 'icon-sdk-js'; // Incorrect named import for default export in browser
const { IconService } = require('icon-sdk-js'); // Incorrect destructuring for default export in Node.js

correct:

import IconService from 'icon-sdk-js'; // For browser/React Native
// OR
const IconService = require('icon-sdk-js'); // For Node.js

IconService is the default export in browser/React Native environments and the module.exports in Node.js. The library ships with TypeScript types, supporting type-safe development.

IconBuilder

wrong:

import { IconBuilder } from 'icon-sdk-js'; // Incorrect direct named import
const IconBuilder = require('icon-sdk-js').IconBuilder; // Possible but less idiomatic if IconService is already imported

correct:

import IconService from 'icon-sdk-js';
const { IconBuilder } = IconService; // Accessing nested builder via default export

IconBuilder is an exposed property of the IconService class, not a direct top-level export. It's typically accessed via the main IconService object.

IcxTransactionBuilder

wrong:

import { IcxTransactionBuilder } from 'icon-sdk-js'; // Incorrect direct named import

correct:

import IconService from 'icon-sdk-js';
const { IconBuilder } = IconService;
const { IcxTransactionBuilder } = IconBuilder;

Transaction builders like IcxTransactionBuilder are deeply nested under IconService.IconBuilder and must be accessed through the parent objects.

Quickstart

Initializes the ICON SDK, connects to a public ICON node, and fetches basic network information like block height and demonstrates ICX unit conversion.

import IconService from 'icon-sdk-js';
import HttpProvider from 'icon-sdk-js/lib/httpprovider';

const rpcUrl = process.env.ICON_RPC_URL || 'https://lisbon.net.solidwallet.io/api/v3/icon';
const provider = new HttpProvider(rpcUrl);
const iconService = new IconService(provider);

async function getNetworkInfo() {
  try {
    const networkInfo = await iconService.getNetworkInfo().execute();
    console.log('ICON Network Info:', networkInfo);
    
    const blockHeight = await iconService.getLastBlock().execute();
    console.log('Current Block Height:', blockHeight.height);
    
    // Example of using IconAmount for conversion
    const icxAmount = IconService.IconAmount.of(100, IconService.IconAmount.Unit.ICX).toLoop();
    console.log('100 ICX in Loop units:', icxAmount.toString());

  } catch (error) {
    console.error('Failed to retrieve network info:', error);
  }
}

getNetworkInfo();

view raw JSON →