ICON1
Search
⌃K
Comment on page

Javascript API Reference

ICON supports JavaScript SDK for 3rd party or user services development. You can integrate ICON JavaScript SDK into your project and utilize ICON’s functionality. This document provides you an API specification.

API Specification - Introduction

IconService is a root class of icon-sdk-js, which provides APIs to communicate with ICON nodes and contains different type of modules. Details of modules are as below:
Module
Description
​IconService​
Class which provides APIs to communicate with ICON nodes
​IconService.IconWallet​
Class which provides EOA functions.
​IconService.IconBuilder​
Builder class for transaction object.
Class representing the signed transaction object.
​IconService.HttpProvider​
Class representing HTTP-based provider
​IconService.IconAmount​
Class which provides unit conversion functions.
Util module contains conversion functions.
Util module contains hex-prefix functions.
Util module contains validator functions.

IconService

IconService is a class which provides APIs to communicate with ICON nodes. It enables you to easily use ICON JSON-RPC APIs (version 3). All instance methods of IconService returns a HttpCall instance. To execute the request and get the result value, you need to run execute() function of HttpCall instance. All requests will be executed asynchronously. Synchronous request is not available.

Constructor

Creates an instance of IconService.
new IconService(provider: HttpProvider)
Parameters
Parameter
Type
Description
provider
HttpProvider
​HttpProvider instance.
Example
const httpProvider = new HttpProvider('https://ctz.solidwallet.io/api/v3');
const iconService = new IconService(httpProvider);

getTotalSupply()

Get the total number of issued coins.
.getTotalSupply() => HttpCall // .execute() => BigNumber
Parameters
None
Returns
HttpCall - The HttpCall instance for icx_getTotalSupply JSON-RPC API request. If execute() successfully, it returns a BigNumber value of total issued coins.
Example
/* Returns the total number of issued coins. */
const totalSupply = await iconService.getTotalSupply().execute();

getBalance()

Get the balance of the address.
.getBalance(address: string) => HttpCall // .execute() => BigNumber
Parameters
Parameter
Type
Description
address
string
an EOA address.
Returns
HttpCall - The HttpCall instance for icx_getBalance JSON-RPC API request. If execute() successfully, it returns a BigNumber value of ICX balance.
Example
/* Returns the balance of a EOA address */
const balance = await iconService.getBalance('hx9d8a8376e7db9f00478feb9a46f44f0d051aab57').execute();

getBlock()

Get the block information.
Since this API is an old version, we recommend to use getBlockByHeight(), getBlockByHash(), getLastBlock() API.
.getBlock(value: string|number|BigNumber) => HttpCall // .execute() => object
Parameters
Parameter
Type
Description
value
string, number, BigNumber
the height or hash value of block.
Depending on the type of input value, there are different ways to get block information.
  1. 1.
    Get block by height - Put integer value of a block height. It will delegate to icx_getBlockByHeight RPC method.
  2. 2.
    Get block by hash - Put block hash value. It will delegate to icx_getBlockByHash RPC method.
  3. 3.
    Get latest block - Put the string 'latest'. It will delegate to icx_getLastBlock RPC method.
Returns
HttpCall - The HttpCall instance for icx_getBlockByHeight, icx_getBlockByHash or icx_getLastBlock JSON-RPC API request. If execute() successfully, it returns a block object. For details of returned block object, see Example section of icx_getLastBlock.
Example
// Returns block information by block height
const block1 = await iconService.getBlock(1000).execute();
​
// Returns block information by block hash
const block2 = await iconService.getBlock("0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95").execute();
​
// Returns latest block information
const block2 = await iconService.getBlock("latest").execute();

getBlockByHeight()

Get the block information by block height.
.getBlockByHeight(value: number|BigNumber) => HttpCall // .execute() => object
Parameters
Parameter
Type
Description
value
number, BigNumber
the height value of block.
Returns
HttpCall - The HttpCall instance for icx_getBlockByHeight JSON-RPC API request. If execute() successfully, it returns a block object.
Example
// Returns block information
const block = await iconService.getBlockByHeight(1000).execute();

getBlockByHash()

Get the block information by block hash.
.getBlockByHash(value: string) => HttpCall // .execute() => object
Parameters
Parameter
Type
Description
value
string
a block hash.
Returns
HttpCall - The HttpCall instance for icx_getBlockByHash JSON-RPC API request. If execute() successfully, it returns a block object.
Example
// Returns block information
const block = await iconService.getBlockByHash('0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95').execute();

getLastBlock()

Get the latest block information.
.getLastBlock() => HttpCall // .execute() => object
Parameters
None
Returns
HttpCall - The HttpCall instance for icx_getLastBlock JSON-RPC API request. If execute() successfully, it returns a block object.
Example
// Returns block information
const block = await iconService.getLastBlock().execute();

getScoreApi()

Get the SCORE API list.
.getScoreApi(address: string) => HttpCall // .execute() => array
Parameters
Parameter
Type
Description
address
string
a SCORE address.
Returns
HttpCall - The HttpCall instance for icx_getScoreApi JSON-RPC API request. If execute() successfully, it returns a ScoreApiList instance, the API list of SCORE address.
ScoreApiList provides two instance methods, getList() and getMethod().
  • getList() - Returns array of API list.
  • getMethod(method: string) - Returns object of method information.
Example
// Returns the SCORE API list
const apiList = await iconService.getScoreApi('cx0000000000000000000000000000000000000001').execute();
​
// [ { type: 'function', name: 'acceptScore', inputs: [ [Object] ] outputs: [] }, ··· { type: 'eventlog', name: 'UpdateServiceConfigLog', inputs: [ [Object] ] }]
console.log(apiList.getList());
​
// { type: 'function', name: 'getStepCosts', inputs: [], outputs: [ { type: 'dict' } ], readonly: '0x1' }
console.log(apiList.getMethod('getStepCosts'));

getTransaction()

Get the transaction information.
.getTransaction(hash: string) => HttpCall // .execute() => object
Parameters
Parameter
Type
Description
hash
string
a transaction hash.
Returns
HttpCall - The HttpCall instance for icx_getTransactionByHash JSON-RPC API request. If execute() successfully, it returns a transaction object. For details of returned object, see here.
Example
// Returns the transaction object.
const txObject = await iconService.getTransaction('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();

getTransactionResult()

Get the result of transaction by transaction hash.
.getTransactionResult(hash: string) => HttpCall // .execute() => object
Parameters
Parameter
Type
Description
hash
string
a transaction hash.
Returns
HttpCall - The HttpCall instance for icx_getTransactionResult JSON-RPC API request. If execute() successfully, it returns a transaction result object. For details of returned object, see here.
Example
// Returns the transaction result object.
const txObject = await iconService.getTransactionResult('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();

sendTransaction()

Send a transaction that changes the states of address.
.sendTransaction(signedTransaction: SignedTransaction) => HttpCall // .execute() => string
Parameters
Parameter
Type
Description
signedTransaction
SignedTransaction
an instance of SignedTransaction class.
Returns
HttpCall - The HttpCall instance for icx_sendTransaction JSON-RPC API request. If execute() successfully, it returns a string value of transaction hash.
Example
// Returns the tx hash of transaction.
const txHash = await iconService.sendTransaction(signedTransaction).execute();

call()

Calls external function of SCORE.
.call(call: Call) => HttpCall // .execute() => any
Parameters
Parameter
Type
Description
call
Call
an instance of Call class builded by CallBuilder.
Returns
HttpCall - The HttpCall instance for icx_call JSON-RPC API request. If execute() successfully, it returns a any type of value returned by the executed SCORE function.
Example
// Returns the value returned by the executed SCORE function.
const result = await iconService.call(call).execute();

IconService.IconWallet (Wallet)

IconWallet is a class which provides EOA functions. It enables you to create, load, and store Wallet object.

Constructor

Creates an instance of Wallet class. To create wallet, please use create() static function instead of instantiating this class directly.
new Wallet(privKey: string, pubKey: string)
Parameters
Parameter
Type
Description
privKey
string
a private key.
pubKey
string
a public key.

static create()

Creates an instance of Wallet class.
IconWallet.create() => Wallet
Parameters
None
Returns
Wallet - Wallet instance. It contains a public key and a private key randomly generated by create() function.
Example
// Creates an instance of Wallet.
const wallet = IconWallet.create();

static loadPrivateKey()

Import existing wallet using private key.
IconWallet.loadPrivateKey(privKey: string) => Wallet
Parameters
Parameter
Type
Description
privKey
string
a private key.
Returns
Wallet - a Wallet instance.
Example
// Load wallet object
const wallet = IconWallet.loadPrivateKey('2ab···e4c');

static loadKeystore()

Import existing wallet using keystore object.
IconWallet.loadKeystore(keystore: object|string, password: string, nonStrict?: boolean) => Wallet
Parameters
Parameter
Type
Description
keystore
object, string
the keystore object (or stringified object.)
password
string
the password of keystore object.
nonStrict (optional)
boolean
set whether checking keystore file case-insensitive or not. (affects when keystore param is string.)
Returns
Wallet - a Wallet instance.
Example
const testKeystore = { "version": 3, "id": "41fc1ddb-4faf-4c88-b494-8fe82a4bab63", "address": "hxd008c05cbc0e689f04a5bb729a66b42377a9a497", "crypto": { "ciphertext": "c4046f5a735403a963110d24f39120a102ad7bc462bf2a14ae334ba4a8c485f6", "cipherparams": { "iv": "441b5a5de3dd33de6f7838b6075702d2" }, "cipher": "aes-128-ctr", "kdf": "scrypt", "kdfparams": { "dklen": 32, "salt": "39d45ffead82d554e35a55efcc7a1f64afe73e9a8ab6b750d959f904e32294ba", "n": 16384, "r": 8, "p": 1 }, "mac": "9bca1f2e8750efb27b7357e1a6a727c596cb812f7a4c45792494a8b0890774d7" }, "coinType": "icx" }
const testPassword = 'qwer1234!'
​
// Load wallet object
const wallet = IconWallet.loadKeystore(testKeystore, testPassword)

store()

Get keystore object of an instance of a Wallet class.
.store(password: string, opts?: object) => object
Parameters
Parameter
Type
Description
password
string
a new password for encryption.
opts (optional)
object
the custom options for encryption.
Returns
object - a keystore object.
Example
const wallet = IconWallet.create()
// Get keystore object of an instance of a `Wallet` class.
const keystore = wallet.store("qwer1234!")

sign()

Generate signature string by signing transaction object.
.sign(data: Buffer) => string
Parameters
Parameter
Type
Description
data
Buffer
the serialized transaction object.
Returns
string - a signature string.
Example
const wallet = IconWallet.create()
// Get keystore object of an instance of a `Wallet` class.
const signature = wallet.sign('ba4···f64')

getPrivateKey()

Get a private key of Wallet instance.
.getPrivateKey() => string
Parameters
None
Returns
string - a private key.
Example
const wallet = IconWallet.create()
// Get private key of `Wallet` instance.
const pk = wallet.getPrivateKey()

getPublicKey()

Get a public key of Wallet instance.
.getPublicKey() => string
Parameters
None
Returns
string - a public key.
Example
const wallet = IconWallet.create()
// Get public key of `Wallet` instance.
const pk = wallet.getPublicKey()

getAddress()

Get an address of Wallet instance.
.getAddress() => string
Parameters
None
Returns
string - an EOA address.
Example
const wallet = IconWallet.create()
// Get address of `Wallet` instance.
const pk = wallet.getAddress()

IconService.IconBuilder

IconBuilder is an object containing builder class for transaction object. Builder class enables you to make transaction object easily. There are 5 types of builder class as follows:
Module
Description
​IcxTransactionBuilder​
Builder class for IcxTransaction instance, which is for sending ICX.
Builder class for MessageTransaction instance, which is for sending message data. Extends IcxTransactionBuilder class.
​DeployTransactionBuilder​
Builder class for DeployTransaction instance, which is for deploying SCORE. Extends IcxTransactionBuilder class.
​CallTransactionBuilder​
Builder class for CallTransaction instance, which is for invoking a state-transition function of SCORE. Extends IcxTransactionBuilder class.
​CallBuilder​
Builder class for Call instance, which is for invoking a read-only function of SCORE.

IconService.IconBuilder.IcxTransactionBuilder

Builder class for IcxTransaction instance. IcxTransaction is an object representing a transaction object used for sending ICX. The parameter details are as follows:
Parameter
Description
to
An EOA address to receive coins, or SCORE address to execute the transaction.
from
An EOA address that created the transaction
value (optional)
Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 10 ^ 18 loop)
stepLimit
Maximum step allowance that can be used by the transaction.
nid
Network ID ("0x1" for Mainnet, "0x2" for Testnet, etc)
nonce
An arbitrary number used to prevent transaction hash collision.
version
Protocol version ("0x3" for V3)
timestamp
Transaction creation time. timestamp is in microsecond.

Constructor

Creates an instance of IcxTransactionBuilder class.
new IcxTransactionBuilder()
Parameters
None

to()

Setter method of 'to' property.
.to(to: string) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
to
string
an EOA or SCORE address.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `to` property.
const txObj = new IcxTransactionBuilder()
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')

from()

Setter method of 'from' property.
.from(from: string) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
from
string
an EOA address.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `from` property.
const txObj = new IcxTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')

value()

Setter method of 'value' property.
.value(value: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
value
string, BigNumber, number
the sending amount of ICX in loop unit.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.value(IconAmount.of(1, IconAmount.Unit.ICX).toLoop())

stepLimit()

Setter method of 'stepLimit' property.
.stepLimit(stepLimit: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
stepLimit
string, BigNumber, number
the amount of step limit.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.stepLimit(IconConverter.toBigNumber(100000))

nid()

Setter method of 'nid' property.
.nid(nid: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
nid
string, BigNumber, number
a network ID.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `nid` property.
const txObj = new IcxTransactionBuilder()
.nid(IconConverter.toBigNumber(1))

nonce()

Setter method of 'nonce' property.
.nonce(nonce: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
nonce
string, BigNumber, number
a nonce value.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `nonce` property.
const txObj = new IcxTransactionBuilder()
.nonce(IconConverter.toBigNumber(1))

version()

Setter method of 'version' property.
.version(version: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter
Type
Description
version
string, BigNumber, number
the version value.
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
// Set `version` property.
const txObj = new IcxTransactionBuilder()
.version(IconConverter.toBigNumber(3))

timestamp()

Setter method of 'timestamp' property.
.timestamp(version: