Search…
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
Class which provides APIs to communicate with ICON nodes
Class which provides EOA functions.
Builder class for transaction object.
Class representing the signed transaction object.
Class representing HTTP-based provider
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.
1
new IconService(provider: HttpProvider)
Copied!
Parameters
Parameter
Type
Description
provider
HttpProvider
HttpProvider instance.
Example
1
const httpProvider = new HttpProvider('https://ctz.solidwallet.io/api/v3');
2
const iconService = new IconService(httpProvider);
Copied!

getTotalSupply()

Get the total number of issued coins.
1
.getTotalSupply() => HttpCall // .execute() => BigNumber
Copied!
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
1
/* Returns the total number of issued coins. */
2
const totalSupply = await iconService.getTotalSupply().execute();
Copied!

getBalance()

Get the balance of the address.
1
.getBalance(address: string) => HttpCall // .execute() => BigNumber
Copied!
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
1
/* Returns the balance of a EOA address */
2
const balance = await iconService.getBalance('hx9d8a8376e7db9f00478feb9a46f44f0d051aab57').execute();
Copied!

getBlock()

Get the block information.
Since this API is an old version, we recommend to use getBlockByHeight(), getBlockByHash(), getLastBlock() API.
1
.getBlock(value: string|number|BigNumber) => HttpCall // .execute() => object
Copied!
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.
    Get block by height - Put integer value of a block height. It will delegate to icx_getBlockByHeight RPC method.
    2.
    Get block by hash - Put block hash value. It will delegate to icx_getBlockByHash RPC method.
    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
1
// Returns block information by block height
2
const block1 = await iconService.getBlock(1000).execute();
3
4
// Returns block information by block hash
5
const block2 = await iconService.getBlock("0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95").execute();
6
7
// Returns latest block information
8
const block2 = await iconService.getBlock("latest").execute();
Copied!

getBlockByHeight()

Get the block information by block height.
1
.getBlockByHeight(value: number|BigNumber) => HttpCall // .execute() => object
Copied!
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
1
// Returns block information
2
const block = await iconService.getBlockByHeight(1000).execute();
Copied!

getBlockByHash()

Get the block information by block hash.
1
.getBlockByHash(value: string) => HttpCall // .execute() => object
Copied!
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
1
// Returns block information
2
const block = await iconService.getBlockByHash('0xdb310dd653b2573fd673ccc7489477a0b697333f77b3cb34a940db67b994fd95').execute();
Copied!

getLastBlock()

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

getScoreApi()

Get the SCORE API list.
1
.getScoreApi(address: string) => HttpCall // .execute() => array
Copied!
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
1
// Returns the SCORE API list
2
const apiList = await iconService.getScoreApi('cx0000000000000000000000000000000000000001').execute();
3
4
// [ { type: 'function', name: 'acceptScore', inputs: [ [Object] ] outputs: [] }, ··· { type: 'eventlog', name: 'UpdateServiceConfigLog', inputs: [ [Object] ] }]
5
console.log(apiList.getList());
6
7
// { type: 'function', name: 'getStepCosts', inputs: [], outputs: [ { type: 'dict' } ], readonly: '0x1' }
8
console.log(apiList.getMethod('getStepCosts'));
Copied!

getTransaction()

Get the transaction information.
1
.getTransaction(hash: string) => HttpCall // .execute() => object
Copied!
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
1
// Returns the transaction object.
2
const txObject = await iconService.getTransaction('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();
Copied!

getTransactionResult()

Get the result of transaction by transaction hash.
1
.getTransactionResult(hash: string) => HttpCall // .execute() => object
Copied!
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
1
// Returns the transaction result object.
2
const txObject = await iconService.getTransactionResult('0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238').execute();
Copied!

sendTransaction()

Send a transaction that changes the states of address.
1
.sendTransaction(signedTransaction: SignedTransaction) => HttpCall // .execute() => string
Copied!
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
1
// Returns the tx hash of transaction.
2
const txHash = await iconService.sendTransaction(signedTransaction).execute();
Copied!

call()

Calls external function of SCORE.
1
.call(call: Call) => HttpCall // .execute() => any
Copied!
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
1
// Returns the value returned by the executed SCORE function.
2
const result = await iconService.call(call).execute();
Copied!

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.
1
new Wallet(privKey: string, pubKey: string)
Copied!
Parameters
Parameter
Type
Description
privKey
string
a private key.
pubKey
string
a public key.

static create()

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

static loadPrivateKey()

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

static loadKeystore()

Import existing wallet using keystore object.
1
IconWallet.loadKeystore(keystore: object|string, password: string, nonStrict?: boolean) => Wallet
Copied!
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
1
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" }
2
const testPassword = 'qwer1234!'
3
4
// Load wallet object
5
const wallet = IconWallet.loadKeystore(testKeystore, testPassword)
Copied!

store()

Get keystore object of an instance of a Wallet class.
1
.store(password: string, opts?: object) => object
Copied!
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
1
const wallet = IconWallet.create()
2
// Get keystore object of an instance of a `Wallet` class.
3
const keystore = wallet.store("qwer1234!")
Copied!

sign()

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

getPrivateKey()

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

getPublicKey()

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

getAddress()

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

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
Builder class for IcxTransaction instance, which is for sending ICX.
Builder class for MessageTransaction instance, which is for sending message data. Extends IcxTransactionBuilder class.
Builder class for DeployTransaction instance, which is for deploying SCORE. Extends IcxTransactionBuilder class.
Builder class for CallTransaction instance, which is for invoking a state-transition function of SCORE. Extends IcxTransactionBuilder class.
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.
1
new IcxTransactionBuilder()
Copied!
Parameters
None

to()

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

from()

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

value()

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

stepLimit()

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

nid()

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

nonce()

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

version()

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

timestamp()

Setter method of 'timestamp' property.
1
.timestamp(version: string|BigNumber|number) => IcxTransactionBuilder
Copied!
Parameters
Parameter
Type
Description
timestamp
string, BigNumber, number
timestamp value. (microsecond)
Returns
IcxTransactionBuilder - Returns an instance of itself
Example
1
// Set `timestamp` property.
2
const txObj = new IcxTransactionBuilder()
3
.timestamp(1544596599371000)
Copied!

build()

Returns an IcxTransaction instance which contains parameter you set.
1
.build() => IcxTransaction
Copied!
Parameters
None
Returns
IcxTransaction - Returns an IcxTransaction instance.
Example
1
// Build `IcxTransaction` instance.
2
const txObj = new IcxTransactionBuilder()
3
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
4
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
5
.value(IconAmount.of(7, IconAmount.Unit.ICX).toLoop())
6
.stepLimit(IconConverter.toBigNumber(100000))
7
.nid(IconConverter.toBigNumber(3))
8
.nonce(IconConverter.toBigNumber(1))
9
.version(IconConverter.toBigNumber(3))
10
.timestamp(1544596599371000)
11
.build()
Copied!

IconService.IconBuilder.MessageTransactionBuilder

Builder class for MessageTransaction instance. MessageTransaction is an object representing a transaction object used for sending message data. It extends IcxTransaction class, so instance parameters and methods of builder class are mostly identical to IcxTransaction class, except for the following:
Parameter
Description
data
A message data. Data type of the data should be lowercase hex string prefixed with '0x'.
dataType
Data type of data. Fixed string message is in value.
For details of extended parameters and methods, see IcxTransactionBuilder section.

Constructor

Creates an instance of MessageTransactionBuilder class.
1
new MessageTransactionBuilder()
Copied!
Parameters
None

data()

Setter method of 'data' property.
1
.data(data: string) => MessageTransactionBuilder
Copied!
Parameters
Parameter
Type
Description
data
string
the data (hex string) to send.
Returns
MessageTransactionBuilder - Returns an instance of itself
Example
1
// Set `data` property.
2
const txObj = new MessageTransactionBuilder()
3
.data(IconConverter.fromUtf8('Hello'))
Copied!

build()

Returns an MessageTransaction instance which contains parameter you set.
1
.build() => MessageTransaction
Copied!
Parameters
None
Returns
MessageTransaction - Returns an MessageTransaction instance.
Example
1
// Build `MessageTransaction` instance.
2
const txObj = new MessageTransactionBuilder()
3
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
4
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
5
.stepLimit(IconConverter.toBigNumber(100000))
6
.nid(IconConverter.toBigNumber(3))
7
.nonce(IconConverter.toBigNumber(1))
8
.version(IconConverter.toBigNumber(3))
9
.timestamp(1544596599371000)
10
.data(IconConverter.fromUtf8('Hello'))
11
.build()
Copied!

IconService.IconBuilder.DeployTransactionBuilder

Builder class for DeployTransaction instance. DeployTransaction is an object representing a transaction object used for deploying SCORE. It extends IcxTransaction class, so instance parameters and methods of builder class are mostly identical to IcxTransaction class, except for the following:
Parameter
Description
data
A deploy object data. It contains 3 parameters: 1) contentType - Mime-type of the content. 2) content - Compressed SCORE data. 3) params (optional) - Function parameters delivered to on_install() or on_update()
dataType
Data type of data. Fixed string deploy is in value.
For details of extended parameters and methods, see IcxTransactionBuilder section.

Constructor

Creates an instance of DeployTransactionBuilder class.
1
new DeployTransactionBuilder()
Copied!
Parameters
None

contentType()

Setter method of 'contentType' property in 'data'.
1
.contentType(contentType: string) => DeployTransactionBuilder
Copied!
Parameters
Parameter
Type
Description
contentType
string
the content type of content
Returns
DeployTransactionBuilder - Returns an instance of itself
Example
1
// Set `contentType` property.
2
const txObj = new DeployTransactionBuilder()
3
.contentType('application/zip')
Copied!

content()

Setter method of 'content' property in 'data'.
1
.content(content: string) => DeployTransactionBuilder
Copied!
Parameters
Parameter
Type
Description
content
string
the content to deploy.
Returns
DeployTransactionBuilder - Returns an instance of itself
Example
1
// Set `content` property.
2
const txObj = new DeployTransactionBuilder()
3
.content('0x504b03040a0000000000d3a68e4d000000000000000...')
Copied!

params()

Setter method of 'params' property in 'data'.
1
.params(params: object) => DeployTransactionBuilder
Copied!
Parameters
Parameter
Type
Description
params
object
Function parameters delivered to on_install() or on_update().
Returns
DeployTransactionBuilder - Returns an instance of itself
Example
1
// Set `params` property.
2
const txObj = new DeployTransactionBuilder()
3
.params({
4
initialSupply: IconConverter.toHex('100000000000'),
5
decimals: IconConverter.toHex(18),
6
name: 'StandardToken',
7
symbol: 'ST',
8
})
Copied!

build()

Returns an DeployTransaction instance which contains parameter you set.
1
.build() => DeployTransaction
Copied!
Parameters
None
Returns
DeployTransaction - Returns an DeployTransaction instance.
Example
1
// Build `DeployTransaction` instance.
2
const txObj = new DeployTransactionBuilder()