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.
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
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.Creates an instance of IconService.
new IconService(provider: HttpProvider)
Parameters
Parameter | Type | Description |
provider | HttpProvider |
Example
const httpProvider = new HttpProvider('https://ctz.solidwallet.io/api/v3');
const iconService = new IconService(httpProvider);
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();
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();
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.Get block by height - Put integer value of a block height. It will delegate to icx_getBlockByHeight RPC method.
- 2.
- 3.
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();
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();
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();
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();
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
) - Returnsobject
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'));
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();
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();
Send a transaction that changes the states of address.
.sendTransaction(signedTransaction: SignedTransaction) => HttpCall // .execute() => string
Parameters
Parameter | Type | Description |
signedTransaction | SignedTransaction |
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();
Calls external function of SCORE.
.call(call: Call) => HttpCall // .execute() => any
Parameters
Parameter | Type | Description |
call | Call |
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();
IconWallet
is a class which provides EOA functions. It enables you to create, load, and store Wallet
object.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. |
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();
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');
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)
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!")
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')
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()
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()
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()
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. |
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. |
Creates an instance of
IcxTransactionBuilder
class.new IcxTransactionBuilder()
Parameters
None
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 itselfExample
// Set `to` property.
const txObj = new IcxTransactionBuilder()
.to('hx87a90bfe8ed49e1a25184ce77fa0d9c4b0484d6a')
Setter method of 'from' property.
.from(from: string) => IcxTransactionBuilder
Parameters
Parameter | Type | Description |
from | string | an EOA address. |
Returns
IcxTransactionBuilder
- Returns an instance of itselfExample
// Set `from` property.
const txObj = new IcxTransactionBuilder()
.from('hx46293d558d3bd489c3715e7e3648de0e35086bfd')
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 itselfExample
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.value(IconAmount.of(1, IconAmount.Unit.ICX).toLoop())
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 itselfExample
// Set `value` property.
const txObj = new IcxTransactionBuilder()
.stepLimit(IconConverter.toBigNumber(100000))
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 itselfExample
// Set `nid` property.
const txObj = new IcxTransactionBuilder()
.nid(IconConverter.toBigNumber(1))
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 itselfExample
// Set `nonce` property.
const txObj = new IcxTransactionBuilder()
.nonce(IconConverter.toBigNumber(1))
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 itselfExample
// Set `version` property.
const txObj = new IcxTransactionBuilder()
.version(IconConverter.toBigNumber(3))
Setter method of 'timestamp' property.
.timestamp(version: string|BigNumber|number) => IcxTransactionBuilder
Parameters
Parameter | Type | Description |
timestamp |