{"id":15124,"library":"icon-sdk-js","title":"ICON JavaScript SDK","description":"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.","status":"active","version":"1.5.3","language":"javascript","source_language":"en","source_url":"https://github.com/icon-project/icon-sdk-js","tags":["javascript","icon","icx","cryptocurrency","crypto","bitcoin","ethereum","binance","typescript"],"install":[{"cmd":"npm install icon-sdk-js","lang":"bash","label":"npm"},{"cmd":"yarn add icon-sdk-js","lang":"bash","label":"yarn"},{"cmd":"pnpm add icon-sdk-js","lang":"bash","label":"pnpm"}],"dependencies":[{"reason":"Used internally for HTTP requests in Node.js environment; if using an older browser, `whatwg-fetch` polyfill might be required.","package":"node-fetch","optional":true}],"imports":[{"note":"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.","wrong":"import { IconService } from 'icon-sdk-js'; // Incorrect named import for default export in browser\nconst { IconService } = require('icon-sdk-js'); // Incorrect destructuring for default export in Node.js","symbol":"IconService","correct":"import IconService from 'icon-sdk-js'; // For browser/React Native\n// OR\nconst IconService = require('icon-sdk-js'); // For Node.js"},{"note":"IconBuilder is an exposed property of the IconService class, not a direct top-level export. It's typically accessed via the main IconService object.","wrong":"import { IconBuilder } from 'icon-sdk-js'; // Incorrect direct named import\nconst IconBuilder = require('icon-sdk-js').IconBuilder; // Possible but less idiomatic if IconService is already imported","symbol":"IconBuilder","correct":"import IconService from 'icon-sdk-js';\nconst { IconBuilder } = IconService; // Accessing nested builder via default export"},{"note":"Transaction builders like IcxTransactionBuilder are deeply nested under IconService.IconBuilder and must be accessed through the parent objects.","wrong":"import { IcxTransactionBuilder } from 'icon-sdk-js'; // Incorrect direct named import","symbol":"IcxTransactionBuilder","correct":"import IconService from 'icon-sdk-js';\nconst { IconBuilder } = IconService;\nconst { IcxTransactionBuilder } = IconBuilder;"}],"quickstart":{"code":"import IconService from 'icon-sdk-js';\nimport HttpProvider from 'icon-sdk-js/lib/httpprovider';\n\nconst rpcUrl = process.env.ICON_RPC_URL || 'https://lisbon.net.solidwallet.io/api/v3/icon';\nconst provider = new HttpProvider(rpcUrl);\nconst iconService = new IconService(provider);\n\nasync function getNetworkInfo() {\n  try {\n    const networkInfo = await iconService.getNetworkInfo().execute();\n    console.log('ICON Network Info:', networkInfo);\n    \n    const blockHeight = await iconService.getLastBlock().execute();\n    console.log('Current Block Height:', blockHeight.height);\n    \n    // Example of using IconAmount for conversion\n    const icxAmount = IconService.IconAmount.of(100, IconService.IconAmount.Unit.ICX).toLoop();\n    console.log('100 ICX in Loop units:', icxAmount.toString());\n\n  } catch (error) {\n    console.error('Failed to retrieve network info:', error);\n  }\n}\n\ngetNetworkInfo();\n","lang":"typescript","description":"Initializes the ICON SDK, connects to a public ICON node, and fetches basic network information like block height and demonstrates ICX unit conversion."},"warnings":[{"fix":"Upgrade your Node.js runtime to version 18.0.0 or higher using nvm or your preferred package manager.","message":"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.","severity":"gotcha","affected_versions":"<18.0.0"},{"fix":"Include `import 'whatwg-fetch';` in your project's entry point if targeting older browsers.","message":"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.","severity":"gotcha","affected_versions":"<1.0.0"},{"fix":"Update your code to call `iconService.getNetworkInfo().execute()` to retrieve comprehensive network details.","message":"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.","severity":"breaking","affected_versions":"<1.5.0"},{"fix":"Run `yarn upgrade icon-sdk-js` or `npm update icon-sdk-js` to get the latest stable version.","message":"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.","severity":"gotcha","affected_versions":"<=1.5.3"}],"env_vars":null,"last_verified":"2026-04-21T00:00:00.000Z","next_check":"2026-07-20T00:00:00.000Z","problems":[{"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;`","cause":"Attempting to destructure `IconBuilder` directly from the main `icon-sdk-js` module when using `require` or incorrect named import with `import`.","error":"TypeError: Cannot read properties of undefined (reading 'IconBuilder')"},{"fix":"For Node.js, ensure Node.js >=18.0.0. For older browsers, import a `fetch` polyfill like `whatwg-fetch`.","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.","error":"ReferenceError: fetch is not defined"},{"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.","cause":"Network issues, incorrect RPC endpoint URL, or CORS policies preventing the browser from connecting to the ICON node.","error":"Error: Failed to fetch"}],"ecosystem":"npm"}