ICON Developer Portal

ICON Developer Portal

ICON Network is a decentralized smart contract protocol based on ‘loopchain’, a high-performance blockchain engine. The ICON Network aims to remove barriers among different blockchains and allow them to exchange values without intermediaries. By realizing this goal, ICON will realize the mass adoption of blockchain technology and Hyperconnect the World.

Get Started

JavaScript API Reference

The source code is found on GitHub at https://github.com/icon-project/icon-sdk-js

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:

ModuleDescription
IconServiceClass which provides APIs to communicate with ICON nodes
IconService.IconWalletClass which provides EOA functions.
IconService.IconBuilderBuilder class for transaction object.
IconService.SignedTransactionClass representing the signed transaction object.
IconService.HttpProviderClass representing HTTP-based provider
IconService.IconAmountClass which provides unit conversion functions.
IconService.IconConverterUtil module contains conversion functions.
IconService.IconHexadecimalUtil module contains hex-prefix functions.
IconService.IconValidatorUtil 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

ParameterTypeDescription
providerHttpProviderHttpProvider 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

ParameterTypeDescription
addressstringan 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

ParameterTypeDescription
valuestring, number, BigNumberthe 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

// 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

ParameterTypeDescription
valuenumber, BigNumberthe 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

ParameterTypeDescription
valuestringa 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

ParameterTypeDescription
addressstringa 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

ParameterTypeDescription
hashstringa 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

ParameterTypeDescription
hashstringa 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

ParameterTypeDescription
signedTransactionSignedTransactionan 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

ParameterTypeDescription
callCallan 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

ParameterTypeDescription
privKeystringa private key.
pubKeystringa 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

ParameterTypeDescription
privKeystringa 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

ParameterTypeDescription
keystoreobject, stringthe keystore object (or stringified object.)
passwordstringthe password of keystore object.
nonStrict (optional)booleanset 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

ParameterTypeDescription
passwordstringa new password for encryption.
opts (optional)objectthe 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

ParameterTypeDescription
dataBufferthe 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:

ModuleDescription
IcxTransactionBuilderBuilder class for IcxTransaction instance, which is for sending ICX.
MessageTransactionBuilderBuilder class for MessageTransaction instance, which is for sending message data. Extends IcxTransactionBuilder class.
DeployTransactionBuilderBuilder class for DeployTransaction instance, which is for deploying SCORE. Extends IcxTransactionBuilder class.
CallTransactionBuilderBuilder class for CallTransaction instance, which is for invoking a state-transition function of SCORE. Extends IcxTransactionBuilder class.
CallBuilderBuilder 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:

ParameterDescription
toAn EOA address to receive coins, or SCORE address to execute the transaction.
fromAn 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)
stepLimitMaximum step allowance that can be used by the transaction.
nidNetwork ID ("0x1" for Mainnet, "0x2" for Testnet, etc)
nonceAn arbitrary number used to prevent transaction hash collision.
versionProtocol version ("0x3" for V3)
timestampTransaction 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

ParameterTypeDescription
tostringan 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

ParameterTypeDescription
fromstringan 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

ParameterTypeDescription
valuestring, BigNumber, numberthe 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

ParameterTypeDescription
stepLimitstring, BigNumber, numberthe 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

ParameterTypeDescription
nidstring, BigNumber, numbera 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

ParameterTypeDescription
noncestring, BigNumber, numbera 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

ParameterTypeDescription
versionstring, BigNumber, numberthe 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: string|BigNumber|number) => IcxTransactionBuilder

Parameters

ParameterTypeDescription
timestampstring, BigNumber, numbertimestamp value. (microsecond)

Returns

IcxTransactionBuilder - Returns an instance of itself

Example

// Set `timestamp` property.
const txObj = new IcxTransactionBuilder()
    .timestamp(1544596599371000)

build()

Returns an IcxTransaction instance which contains parameter you set.

.build() => IcxTransaction

Parameters

None

Returns

IcxTransaction - Returns an IcxTransaction instance.

Example

// Build `IcxTransaction` instance.
const txObj = new IcxTransactionBuilder()
    .from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
    .to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
    .value(IconAmount.of(7, IconAmount.Unit.ICX).toLoop())
    .stepLimit(IconConverter.toBigNumber(100000))
    .nid(IconConverter.toBigNumber(3))
    .nonce(IconConverter.toBigNumber(1))
    .version(IconConverter.toBigNumber(3))
    .timestamp(1544596599371000)
    .build()

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:

ParameterDescription
dataA message data. Data type of the data should be lowercase hex string prefixed with '0x'.
dataTypeData 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.

new MessageTransactionBuilder()

Parameters

None

data()

Setter method of 'data' property.

.data(data: string) => MessageTransactionBuilder

Parameters

ParameterTypeDescription
datastringthe data (hex string) to send.

Returns

MessageTransactionBuilder - Returns an instance of itself

Example

// Set `data` property.
const txObj = new MessageTransactionBuilder()
    .data(IconConverter.fromUtf8('Hello'))

build()

Returns an MessageTransaction instance which contains parameter you set.

.build() => MessageTransaction

Parameters

None

Returns

MessageTransaction - Returns an MessageTransaction instance.

Example

// Build `MessageTransaction` instance.
const txObj = new MessageTransactionBuilder()
    .from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
    .to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
    .stepLimit(IconConverter.toBigNumber(100000))
    .nid(IconConverter.toBigNumber(3))
    .nonce(IconConverter.toBigNumber(1))
    .version(IconConverter.toBigNumber(3))
    .timestamp(1544596599371000)
    .data(IconConverter.fromUtf8('Hello'))
    .build()

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:

ParameterDescription
dataA 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()
dataTypeData 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.

new DeployTransactionBuilder()

Parameters

None

contentType()

Setter method of 'contentType' property in 'data'.

.contentType(contentType: string) => DeployTransactionBuilder

Parameters

ParameterTypeDescription
contentTypestringthe content type of content

Returns

DeployTransactionBuilder - Returns an instance of itself

Example

// Set `contentType` property.
const txObj = new DeployTransactionBuilder()
    .contentType('application/zip')

content()

Setter method of 'content' property in 'data'.

.content(content: string) => DeployTransactionBuilder

Parameters

ParameterTypeDescription
contentstringthe content to deploy.

Returns

DeployTransactionBuilder - Returns an instance of itself

Example

// Set `content` property.
const txObj = new DeployTransactionBuilder()
    .content('0x504b03040a0000000000d3a68e4d000000000000000...')

params()

Setter method of 'params' property in 'data'.

.params(params: object) => DeployTransactionBuilder

Parameters

ParameterTypeDescription
paramsobjectFunction parameters delivered to on_install() or on_update().

Returns

DeployTransactionBuilder - Returns an instance of itself

Example

// Set `params` property.
const txObj = new DeployTransactionBuilder()
    .params({
        initialSupply: IconConverter.toHex('100000000000'),
        decimals: IconConverter.toHex(18),
        name: 'StandardToken',
        symbol: 'ST',
    })

build()

Returns an DeployTransaction instance which contains parameter you set.

.build() => DeployTransaction

Parameters

None

Returns

DeployTransaction - Returns an DeployTransaction instance.

Example

// Build `DeployTransaction` instance.
const txObj = new DeployTransactionBuilder()
    .from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
    .to('cx0000000000000000000000000000000000000000')
    .stepLimit(IconConverter.toBigNumber(2500000))
    .nid(IconConverter.toBigNumber(3))
    .nonce(IconConverter.toBigNumber(1))
    .version(IconConverter.toBigNumber(3))
    .timestamp(1544596599371000)
    .contentType('application/zip')
    .content('0x504b03040a0000000000d3a68e4d000000000000000...')
    .params({
        initialSupply: IconConverter.toHex('100000000000'),
        decimals: IconConverter.toHex(18),
        name: 'StandardToken',
        symbol: 'ST',
    })
    .build()

IconService.IconBuilder.CallTransactionBuilder

Builder class for CallTransaction instance. CallTransaction is an object representing a transaction object used for invoking a state-transition function of SCORE. It extends IcxTransaction class, so instance parameters and methods are mostly identical to IcxTransaction class, except for the following:

ParameterDescription
dataAn object data for calling method. It contains 2 parameters: 1) method - The method name of SCORE API. 2) params (optional) - The input params for method
dataTypeData type of data. Fixed string call is in value.

For details of extended parameters and methods, see IcxTransactionBuilder section.

Constructor

Creates an instance of CallTransactionBuilder class.

new CallTransactionBuilder()

Parameters

None

method()

Setter method of 'method' property in 'data'.

.method(method: string) => CallTransactionBuilder

Parameters

ParameterTypeDescription
methodstringthe method name of SCORE API.

Returns

CallTransactionBuilder - Returns an instance of itself

Example

// Set `method` property.
const txObj = new CallTransactionBuilder()
    .method('transfer')

params()

Setter method of 'params' property in 'data'.

.params(params: object) => CallTransactionBuilder

Parameters

ParameterTypeDescription
paramsobjectthe input params for method.

Returns

CallTransactionBuilder - Returns an instance of itself

Example

// Set `params` property.
const txObj = new CallTransactionBuilder()
    .params({
        _to: 'hxd008c05cbc0e689f04a5bb729a66b42377a9a497',
        _value: IconConverter.toHex(IconAmount.of(1, IconAmount.Unit.ICX).toLoop()),
    })

build()

Returns an CallTransaction instance which contains parameter you set.

.build() => CallTransaction

Parameters

None

Returns

CallTransaction - Returns an CallTransaction instance.

Example

// Build `CallTransaction` instance.
const txObj = new CallTransactionBuilder()
    .from('hx902ecb51c109183ace539f247b4ea1347fbf23b5')
    .to('cx3502b4dadbfcd654d26d53d8463f2929c2c3948d')
    .stepLimit(IconConverter.toBigNumber('2000000'))
    .nid(IconConverter.toBigNumber('3'))
    .nonce(IconConverter.toBigNumber('1'))
    .version(IconConverter.toBigNumber('3'))
    .timestamp((new Date()).getTime() * 1000)
    .method('transfer')
    .params({
        _to: 'hxd008c05cbc0e689f04a5bb729a66b42377a9a497',
        _value: IconConverter.toHex(IconAmount.of(1, IconAmount.Unit.ICX).toLoop()),
    })
    .build()

IconService.IconBuilder.CallBuilder

Builder class for Call instance. Call is an object representing a transaction object used for invoking a read-only function of SCORE. The parameter details are as follows:

ParameterDescription
toa SCORE address to execute the call.
dataan object data for calling method. It contains 2 parameters: 1) method - The method name of SCORE API. 2) params (optional) - The input params for method
dataTypeData type of data. Fixed string call is in value.

Constructor

Creates an instance of CallBuilder class.

new CallBuilder()

Parameters

None

to()

Setter method of 'to' property.

.to(to: string) => CallBuilder

Parameters

ParameterTypeDescription
tostringa SCORE address.

Returns

CallBuilder - Returns an instance of itself

Example

// Set `to` property.
const txObj = new CallBuilder()
    .to('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')

method()

Setter method of 'method' property in 'data'.

.method(method: string) => CallBuilder

Parameters

ParameterTypeDescription
methodstringthe method name of SCORE API.

Returns

CallBuilder - Returns an instance of itself

Example

// Set `method` property.
const txObj = new CallBuilder()
    .method('balanceOf')

params()

Setter method of 'params' property in 'data'.

.params(params: object) => CallBuilder

Parameters

ParameterTypeDescription
paramsobjectthe input params for method.

Returns

CallBuilder - Returns an instance of itself

Example

// Set `params` property.
const txObj = new CallBuilder()
    .params({ 
        _owner: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a' 
    })

build()

Returns an Call instance which contains parameter you set.

.build() => Call

Parameters

None

Returns

Call - Returns an Call instance.

Example

// Build `Call` instance.
const txObj = new CallBuilder()
    .to('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')
    .method('balanceOf')
    .params({ _owner: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a' })
    .build()

IconService.SignedTransaction

SignedTransaction is a class for signing transaction object. It enables you to make signature, and signed transaction object by calling instance methods. Also, by passing SignedTransaction instance to sendTransaction(), it will automatically generate transaction object including signature, and send to ICON node.

Constructor

Creates an instance of SignedTransaction class.

new SignedTransaction(transaction: IcxTransaction|MessageTransaction|CallTransaction|DeployTransaction, wallet: Wallet)

Parameters

ParameterTypeDescription
transactionIcxTransaction, MessageTransaction, CallTransaction, DeployTransactiona transaction object.
walletWalletwallet instance used for signing.

getSignature()

Get a signature string.

.getSignature() => string

Parameters

None

Returns

string - a signature string.

Example

/* Returns the signature */
const signature = new SignedTransaction(icxTransaction, wallet).getSignature() 
// 'YV3eNgVjLFwXS65Bk...+lC90KgRBh7FtwE='

getProperties()

Get a raw signed transaction object.

.getProperties() => object

Parameters

None

Returns

object - the raw signed transaction object.

Example

/* Returns the raw signed transaction object */
const signature = new SignedTransaction(icxTransaction, wallet).getProperties()
// {
//  to: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a',
//  from: 'hx46293d558d3bd489c3715e7e3648de0e35086bfd',
//  stepLimit: '0x186a0',
//  nid: '0x3',
//  version: '0x3',
//  timestamp: '0x57ccd6ba074f8',
//  value: '0x7',
//  nonce: '0x1',
//  signature: 'YV3eNgVjLFwXS65Bk...+lC90KgRBh7FtwE=',
// };

getRawTransaction()

Get a raw transaction object of transaction property.

.getRawTransaction() => object

Parameters

None

Returns

object - the raw transaction object of transaction property.

Example

/* Returns the signed transaction object */
const signature = new SignedTransaction(icxTransaction, wallet).getRawTransaction()
// {
//  to: 'hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a',
//  from: 'hx46293d558d3bd489c3715e7e3648de0e35086bfd',
//  stepLimit: '0x186a0',
//  nid: '0x3',
//  version: '0x3',
//  timestamp: '0x57ccd6ba074f8',
//  value: '0x7',
//  nonce: '0x1'
// };

IconService.HttpProvider

HttpProvider is a class representing HTTP-based provider. It is commonly used for setting provider url of IconService instance. For details of network and node url, see ICON Networks document.

Constructor

Creates an instance of HttpProvider class.

new HttpProvider(url: string)

Parameters

ParameterTypeDescription
urlstringICON node url

IconService.IconAmount

IconAmount is a class representing BigNumber value and unit data. It also provides unit conversion static functions. It enables you to manage different types of numeric data easily.

(IconAmount contains static class property called Unit, which has constant number value of different types of unit digit. IconAmount.Unit.LOOP is 0, and IconAmount.Unit.ICX is 18.)

Constructor

Creates an instance of IconAmount class.

new IconAmount(value: string|BigNumber|number, digit: string|BigNumber|number)

Parameters

ParameterTypeDescription
valuestring, BigNumber, numberthe value of amount.
digitstring, BigNumber, numberthe digit of unit.

Note: According to official document of BigNumber.js, it is recommended to create BigNumbers from string values rather than number values to avoid a potential loss of precision.

static of()

Creates an instance of IconAmount class.

IconAmount.of(value: string|BigNumber|number, digit: string|BigNumber|number) => IconAmount

Parameters

ParameterTypeDescription
valuestring, BigNumber, numberthe value of amount.
digitstring, BigNumber, numberthe digit of unit.

Note: According to official document of BigNumber.js, it is recommended to create BigNumbers from string values rather than number values to avoid a potential loss of precision.

Returns

IconAmount - IconAmount instance.

Example

// Returns IconAmount instance
const iconAmount = IconAmount.of('2', IconAmount.Unit.ICX);

toString()

Converts value property into string

.toString() => string

Parameters

None

Returns

string - The stringified value property of IconAmount instance.

Example

// Returns stringified value property
const value = IconAmount.of('2', IconAmount.Unit.ICX).toString();

getDigit()

Get digit property.

.getDigit() => number

Parameters

None

Returns

number - The digit property of IconAmount instance.

Example

// Returns digit property
const digit = IconAmount.of('2', IconAmount.Unit.ICX).getDigit();

toLoop()

Get value property converted into loop unit.

.toLoop() => BigNumber

Parameters

None

Returns

BigNumber - The value property converted into loop unit.

Example

// Returns value property converted into loop unit.
const value = IconAmount.of('2', IconAmount.Unit.ICX).toLoop();

convertUnit()

Converts value property into custom digit

.convertUnit(digit: string|BigNumber|number) => IconAmount

Parameters

ParameterTypeDescription
digitstring, BigNumber, numberthe digit of unit.

Returns

IconAmount - The IconAmount instance converted into custom digit.

Example

// Returns IconAmount instance converted into custom digit.
const value = IconAmount.of('2', IconAmount.Unit.ICX).convertUnit(IconAmount.Unit.LOOP);

IconService.IconConverter

IconConverter is a utility module which contains conversion functions.

static fromUtf8()

Converts UTF-8 text to hex string with '0x' prefix.

IconConverter.fromUtf8(value: string) => string

Parameters

ParameterTypeDescription
valuestringan UTF-8 text string.

Returns

string - a hex string with '0x' prefix

Example

// Returns hex string
const value = IconConverter.fromUtf8('hello')

static toNumber()

Converts string, hex string or BigNumber value to number.

IconConverter.toNumber(value: string|BigNumber) => number

Parameters

ParameterTypeDescription
valuestring, BigNumbera string, hex string or BigNumber type value

Returns

number - a value converted to number type.

Example

// Returns number value
const value = IconConverter.toNumber('123')

static toBigNumber()

Converts string, hex string or number value to BigNumber.

IconConverter.toBigNumber(value: string|number) => BigNumber

Parameters

ParameterTypeDescription
valuestring, numbera string, hex string or number type value

Returns

BigNumber - a value converted to BigNumber type.

Example

// Returns BigNumber value
const value = IconConverter.toBigNumber('123')

static toHex()

Converts string, number or BigNumber value to hex string.

IconConverter.toHex(value: string|number|BigNumber) => string

Parameters

ParameterTypeDescription
valuestring, number, BigNumbera string, number or BigNumber type value

Returns

string - a value converted to hex string with '0x' prefix.

Example

// Returns hex string
const value = IconConverter.toHex('123')

static toRawTransaction()

Converts transaction object to raw transaction object.

IconConverter.toRawTransaction(transaction: IcxTransaction|MessageTransaction|CallTransaction|DeployTransaction) => object

Parameters

ParameterTypeDescription
transactionIcxTransaction, MessageTransaction, CallTransaction, DeployTransactiona transaction object

Returns

object - a raw transaction object.

Example

const txObj = new IcxTransactionBuilder()
    .from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
    .to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
    .value(IconAmount.of(7, IconAmount.Unit.ICX).toLoop())
    .stepLimit(IconConverter.toBigNumber(100000))
    .nid(IconConverter.toBigNumber(3))
    .nonce(IconConverter.toBigNumber(1))
    .version(IconConverter.toBigNumber(3))
    .timestamp(1544596599371000)
    .build()
// Returns raw transaction object
const rawTxObj = IconConverter.toRawTransaction(txObj)

IconService.IconHexadecimal

IconHexadecimal is a utility module which contains functions related to hex prefix.

static is0xPrefix()

Check whether string starts with '0x' prefix.

IconHexadecimal.is0xPrefix(str: string) => boolean

Parameters

ParameterTypeDescription
strstringa string

Returns

boolean - returns true if string starts with '0x' prefix.

Example

// Returns true if string starts with '0x' prefix
const value = IconHexadecimal.is0xPrefix('0x61')

static isHxPrefix()

Check whether string starts with 'hx' prefix.

IconHexadecimal.isHxPrefix(str: string) => boolean

Parameters

ParameterTypeDescription
strstringa string

Returns

boolean - returns true if string starts with 'hx' prefix.

Example

// Returns true if string starts with 'hx' prefix
const value = IconHexadecimal.isHxPrefix('hx902ecb51c109183ace539f247b4ea1347fbf23b5')

static isCxPrefix()

Check whether string starts with 'cx' prefix.

IconHexadecimal.isCxPrefix(str: string) => boolean

Parameters

ParameterTypeDescription
strstringa string

Returns

boolean - returns true if string starts with 'cx' prefix.

Example

// Returns true if string starts with 'cx' prefix
const value = IconHexadecimal.isCxPrefix('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')

static add0xPrefix()

Add '0x' prefix to string.

IconHexadecimal.add0xPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string with '0x' prefix.

Example

// Returns a string with '0x' prefix.
const value = IconHexadecimal.add0xPrefix('1234')

static addHxPrefix()

Add 'hx' prefix to string.

IconHexadecimal.addHxPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string with 'hx' prefix.

Example

// Returns a string with 'hx' prefix.
const value = IconHexadecimal.addHxPrefix('902ecb51c109183ace539f247b4ea1347fbf23b5')

static addCxPrefix()

Add 'cx' prefix to string.

IconHexadecimal.addCxPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string with 'cx' prefix.

Example

// Returns a string with 'cx' prefix.
const value = IconHexadecimal.addCxPrefix('c248ee72f58f7ec0e9a382379d67399f45b596c7')

static remove0xPrefix()

Remove '0x' prefix from string.

IconHexadecimal.remove0xPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string without '0x' prefix.

Example

// Returns a string without '0x' prefix.
const value = IconHexadecimal.remove0xPrefix('0x61')

static removeHxPrefix()

Remove 'hx' prefix from string.

IconHexadecimal.removeHxPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string without 'hx' prefix.

Example

// Returns a string without 'hx' prefix.
const value = IconHexadecimal.removeHxPrefix('hx902ecb51c109183ace539f247b4ea1347fbf23b5')

static removeCxPrefix()

Remove 'cx' prefix from string.

IconHexadecimal.removeCxPrefix(str: string) => string

Parameters

ParameterTypeDescription
strstringa string

Returns

string - a string without 'cx' prefix.

Example

// Returns a string without 'cx' prefix.
const value = IconHexadecimal.removeCxPrefix('cxc248ee72f58f7ec0e9a382379d67399f45b596c7')

IconService.IconValidator

IconValidator is a utility module which contains validation functions.

static isPrivateKey()

Check if input value is a private key type string.

IconValidator.isPrivateKey(privKey: any) => boolean

Parameters

ParameterTypeDescription
privKeyanyan input value

Returns

boolean - Returns true if the input value is a private key type string.

Example

// Returns true if the input value is a private key type string.
const isPrivateKey = IconValidator.isPrivateKey('7abca1...20a9f1')

static isPublicKey()

Check if input value is a public key type string.

IconValidator.isPublicKey(pubKey: any) => boolean

Parameters

ParameterTypeDescription
publicanyan input value

Returns

boolean - Returns true if the input value is a public key type string.

Example

// Returns true if the input value is a public key type string.
const isPublicKey = IconValidator.isPublicKey('7abca1...20a9f1')

static isEoaAddress()

Check if input value is a EOA address type string.

IconValidator.isEoaAddress(address: any) => boolean

Parameters

ParameterTypeDescription
addressanyan input value

Returns

boolean - Returns true if the input value is a EOA address type string.

Example

// Returns true if the input value is a EOA address type string.
const isEoaAddress = IconValidator.isEoaAddress('hxca12a...209f1')

static isScoreAddress()

Check if input value is a SCORE address type string.

IconValidator.isScoreAddress(address: any) => boolean

Parameters

ParameterTypeDescription
addressanya input value

Returns

boolean - Returns true if the input value is a SCORE address type string.

Example

// Returns true if the input value is a SCORE address type string.
const isScoreAddress = IconValidator.isScoreAddress('cx1b32a...99f01')

static isAddress()

Check if input value is a EOA or SCORE address type string.

IconValidator.isAddress(address: any) => boolean

Parameters

ParameterTypeDescription
addressanyan input value

Returns

boolean - Returns true if the input value is a EOA or SCORE address type string.

Example

// Returns true if the input value is a EOA or SCORE address type string.
const isAddress = IconValidator.isAddress('cx1b32a...99f01')

Error cases

There are 6 types of error cases. Details are as below:

Error codeDescription
DATA ERRORException class related to data type.
FORMAT ERRORException class related to data format.
WALLET ERRORException class related to wallet errors.
RPC ERRORException class related to network errors.
SCORE ERRORException class related to SCORE call error.
NETWORK ERRORException class related to network errors.

References

Updated 12 months ago

JavaScript API Reference


The source code is found on GitHub at https://github.com/icon-project/icon-sdk-js

Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.