ICON JSON-RPC API v3 Specification

ICON JSON-RPC APIs (version 3) are interfaces to interact with ICON nodes. This document explains ICON JSON-RPC API (version 3) data structures, rules and the list of methods.

ICON JSON-RPC API v3 Specification

API Convention

Follows JSON-RPC 2.0 Specification.

// Request
{
"jsonrpc": "2.0",
"method": "$STRING1",
"id": $INT,
"params": {
"$KEY1": "$VALUE1",
"$KEY2": {
"method": "$STRING2",
"params": {
"$KEY3": "$VALUE3"
}
}
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": $INT,
"result": "$STRING"
// or
"result": {
"$KEY1": "$VALUE1",
"$KEY2": "$VALUE2"
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": $INT1,
"error": {
"code": $INT2,
"message": "$STRING"
}
}
  • "KEY" naming follows camel case.

VALUE Types

Basically, every VALUE in JSON-RPC message is string. Below table shows the most common "VALUE types".

VALUE type

Description

Example

T_ADDR_EOA

"hx" + 40 digit HEX string

hxbe258ceb872e08851f1f59694dac2558708ece11

T_ADDR_SCORE

"cx" + 40 digit HEX string

cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32

T_HASH

"0x" + 64 digit HEX string

0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238

T_INT

"0x" + lowercase HEX string

0xa

T_BIN_DATA

"0x" + lowercase HEX string. Length must be even.

0x34b2

T_SIG

base64 encoded string

VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=

T_DATA_TYPE

Type of data

call, deploy, message or deposit

JSON-RPC Error Codes

This chapter explains the error codes used in ICON JSON-RPC API response.

Below table shows the default error messages for the error code. Actual message may vary depending on the implementation.

Error Codes

Error code

Message

Description

-32700

Parse error

Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.

-32600

Invalid Request

The JSON sent is not a valid Request object.

-32601

Method not found

The method does not exist / is not available.

-32602

Invalid params

Invalid method parameter(s).

-32603

Internal error

Internal JSON-RPC error.

-32000

Server error

IconServiceEngine internal error.

-32100

Score error

Score internal error.

  • Some error codes may change

JSON-RPC Error Response

{
"jsonrpc": "2.0",
"id": 1,
"error": {
"code": -32601,
"message": "Method not found"
}
}

JSON-RPC API v3 ChangeLog

  • Fixed to conform to JSON-RPC 2.0 specification

    • Success response: result

    • Failure response: error

  • Removed additional response generated by loopchain such as "response_code" in SCORE's JSON-PRC Response.

    • v2: "result": {"response_code": "0x0", "response": "0x12345"}

    • v3: "result": "0x12345"

  • Fixed inconsistent KEY naming in v2 API

    • v2: icx_getBlockByHeight: "time_stamp"

    • v2: icx_sendTransaction: "timestamp"

    • v3: "timestamp"

  • Fixed inconsistent VALUE format in v2 API

    • timestamp

      • v2: icx_sendTransaction: "timestamp": "1234567890"

      • v2: icx_getBlockByHeight: "timestamp": 1234567890

      • v3: "timestamp": "0x499602d2"

    • hash

      • v2: icx_getBlockByHash: "hash": "af5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"

      • v3: "hash": "0xaf5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"

  • KEY naming follows camel case.

    • v2: "data_type"

    • v3: "dataType"

  • Removed tx_hash from the icx_sendTransaction message.

JSON-RPC APIs

For multichannel requests, add /<channel_name> at the end of the API path.

Main API

API path : <scheme>://<host>/api/v3

Sub API

API path : <scheme>://<host>/api/v3

IISS API

Debug API

API path : <scheme>://<host>/api/debug/v3

Other API

API path : <scheme>://<host>/api/v3

JSON-RPC Methods

icx_getLastBlock

  • Returns the last block information.

Parameters

None

Returns

  • Block data

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getLastBlock",
"id": 1234
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"version": "0.1a", // NOTE: Block data itself still uses ICON JSON-RPC v2 representation. This will be fixed in the future.
"prev_block_hash": "48757af881f76c858890fb41934bee228ad50a71707154a482826c39b8560d4b",
"merkle_tree_root_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
"time_stamp": 1516498781094429,
"confirmed_transaction_list": [ // Transaction data could be either v2 or v3 depending on its original request
{
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
"value": "0xde0b6b3a7640000",
"stepLimit": "0x12345",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"dataType": "call",
"data": {
"method": "transfer",
"params": {
"to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
"value": "0x1"
}
}
}
],
"block_hash": "1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57",
"height": 3,
"peer_id": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
"signature": "MEQCICT8mTIL6pRwMWsJjSBHcl4QYiSgG8+0H3U32+05mO9HAiBOhIfBdHNm71WpAZYwJWwQbPVVXFJ8clXGKT3ScDWcvw=="
}
}

icx_getBlockByHeight

  • Returns block information by block height.

Parameters

KEY

VALUE type

Description

height

T_INT

Integer of a block height

Returns

  • Block data

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getBlockByHeight",
"id": 1234,
"params": {
"height": "0x3"
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"version": "0.1a", // NOTE: Block data itself still uses ICON JSON-RPC v2 representation. This will be fixed in the future.
"prev_block_hash": "48757af881f76c858890fb41934bee228ad50a71707154a482826c39b8560d4b",
"merkle_tree_root_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
"time_stamp": 1516498781094429,
"confirmed_transaction_list": [ // Transaction data could be either v2 or v3 depending on its original request
{
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
"value": "0xde0b6b3a7640000",
"stepLimit": "0x12345",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"dataType": "call",
"data": {
"method": "transfer",
"params": {
"to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
"value": "0x1"
}
}
}
],
"block_hash": "1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57",
"height": 3,
"peer_id": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
"signature": "MEQCICT8mTIL6pRwMWsJjSBHcl4QYiSgG8+0H3U32+05mO9HAiBOhIfBdHNm71WpAZYwJWwQbPVVXFJ8clXGKT3ScDWcvw=="
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid params height"
}
}

icx_getBlockByHash

  • Returns block information by block hash.

Parameters

KEY

VALUE type

Description

hash

T_HASH

Hash of a block

Returns

  • Block data

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getBlockByHash",
"id": 1234,
"params": {
"hash": "0x1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57"
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"version": "0.1a", // NOTE: Block data itself still uses ICON JSON-RPC v2 representation. This will be fixed in the future.
"prev_block_hash": "48757af881f76c858890fb41934bee228ad50a71707154a482826c39b8560d4b",
"merkle_tree_root_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
"time_stamp": 1516498781094429,
"confirmed_transaction_list": [ // Transaction data could be either v2 or v3 depending on its original request
{
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
"value": "0xde0b6b3a7640000",
"stepLimit": "0x12345",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"dataType": "call",
"data": {
"method": "transfer",
"params": {
"to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
"value": "0x1"
}
}
}
],
"block_hash": "1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57",
"height": 3,
"peer_id": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
"signature": "MEQCICT8mTIL6pRwMWsJjSBHcl4QYiSgG8+0H3U32+05mO9HAiBOhIfBdHNm71WpAZYwJWwQbPVVXFJ8clXGKT3ScDWcvw=="
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid params hash"
}
}

icx_call

  • Calls SCORE's external function.

  • Does not make state transition (i.e., read-only).

Parameters

KEY

VALUE type

Description

from

T_ADDR_EOA

Message sender's address.

to

T_ADDR_SCORE

SCORE address that will handle the message.

dataType

T_DATA_TYPE

call is the only possible data type.

data

T_DICT

See Parameters - data.

data.method

String

Name of the function.

data.params

T_DICT

Parameters to be passed to the function.

Returns

  • Values returned by the executed SCORE function.

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_call",
"id": 1234,
"params": {
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11", // TX sender address
"to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32", // SCORE address
"dataType": "call",
"data": {
"method": "get_balance", // SCORE external function
"params": {
"address": "hx1f9a3310f60a03934b917509c86442db703cbd52" // input parameter of "get_balance"
}
}
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": "0x2961fff8ca4a62327800000"
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32601,
"message": "Method not found"
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid params"
}
}

icx_getBalance

  • Returns the ICX balance of the given EOA or SCORE.

Parameters

KEY

VALUE type

Description

address

T_ADDR_EOA or T_ADDR_SCORE

Address of EOA or SCORE

Returns

  • Number of ICX coins.

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getBalance",
"id": 1234,
"params": {
"address": "hxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": "0xde0b6b3a7640000"
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid address"
}
}

icx_getScoreApi

  • Returns SCORE's external API list.

Parameters

KEY

VALUE type

Description

address

T_ADDR_SCORE

SCORE adress to be examined.

Returns

Fields containing information about the function

KEY

VALUE type

Description

type

String

function, fallback, or eventlog

name

String

function name

inputs

T_LIST(T_DICT)

parameters in array - name : parameter - nametype : parameter type (int, str, bytes, bool, Address) - indexed : 0x1 if the parameter is indexed (when this is eventlog)

outputs

T_LIST(T_DICT)

return value - type : return value type (int, str, bytes, bool, Address, dict, list)

readonly

T_INT

0x1 if this is declared as external(readonly=True)

payable

T_INT

0x1 if this has payable decorator

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getScoreApi",
"id": 1234,
"params": {
"address": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32" // SCORE address
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": [
{
"type": "function",
"name": "balanceOf",
"inputs": [
{
"name": "_owner",
"type": "Address"
}
],
"outputs": [
{
"type": "int"
}
],
"readonly": "0x1"
},
{
"type": "eventlog",
"name": "FundTransfer",
"inputs": [
{
"name": "backer",
"type": "Address",
"indexed": "0x1"
},
{
"name": "amount",
"type": "int",
"indexed": "0x1"
},
{
"name": "is_contribution",
"type": "bool",
"indexed": "0x1"
}
]
},
{...}
]
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid address"
}
}

icx_getTotalSupply

  • Returns total ICX coin supply that has been issued.

Parameters

None

Returns

  • Total number of ICX coins issued.

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getTotalSupply",
"id": 1234
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": "0x2961fff8ca4a62327800000"
}

icx_getTransactionResult

  • Returns the transaction result requested by transaction hash.

Parameters

KEY

VALUE type

Description

txHash

T_HASH

Hash of the transaction

Returns

KEY

VALUE type

Description

status

T_INT

0x1 on success, 0x0 on failure.

to

T_ADDR_EOA or T_ADDR_SCORE

Recipient address of the transaction

failure

T_DICT

This field exists when status is 0x1. Contains code(string) and message(string).

txHash

T_HASH

Transaction hash

txIndex

T_INT

Transaction index in the block

blockHeight

T_INT

Height of the block that includes the transaction.

blockHash

T_HASH

Hash of the block that includes the transation.

cumulativeStepUsed

T_INT

Sum of stepUsed by this transaction and all preceeding transactions in the same block.

stepUsed

T_INT

The amount of step used by this transaction.

stepPrice

T_INT

The step price used by this transaction.

scoreAddress

T_ADDR_SCORE

SCORE address if the transaction created a new SCORE. (optional)

eventLogs

T_ARRAY

Array of eventlogs, which this transaction generated.

logsBloom

T_BIN_DATA

Bloom filter to quickly retrieve related eventlogs.

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getTransactionResult",
"id": 1234,
"params": {
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"status": "0x1",
"to": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"txIndex": "0x1",
"blockHeight": "0x1234",
"blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"cumulativeStepUsed": "0x1234",
"stepUsed": "0x1234",
"stepPrice": "0x5678",
"scoreAddress": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
"eventLogs":[
{
"scoreAddress": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
"indexed": [
"Transfer(Address,Address,int)",
"hx4873b94352c8c1f3b2f09aaeccea31ce9e90bd31",
"hx0000000000000000000000000000000000000000",
"0x8ac7230489e80000"
],
"data":[]
}
],
"logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000002000000000021000000000000000000000000000000000000000000000000003000000000031400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000"
}
}
// Response - failed tx
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"status": "0x0",
"failure": {
"code": "0x7d00",
"message": "Out of balance"
},
"to": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"txIndex": "0x1",
"blockHeight": "0x1234",
"blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"cumulativeStepUsed": "0x1234",
"stepUsed": "0x1234",
"stepPrice": "0x5678"
}
}
// Response - error (invalid txHash was given)
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid txHash"
}
}
// Response - pending tx
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Pending transaction"
}
}

icx_getTransactionByHash

  • Returns the transaction information requested by transaction hash.

Parameters

KEY

VALUE type

Description

txHash

T_HASH

Hash of the transaction

Returns

KEY

VALUE type

Description

version

T_INT

Protocol version (0x3 for V3)

from

T_ADDR_EOA

EOA address that created the transaction

to

T_ADDR_EOA or T_ADDR_SCORE

EOA address to receive coins, or SCORE address to execute the transaction.

value

T_INT

Amount of ICX coins in loop to transfer. When ommitted, assumes 0. (1 icx = 1 ^ 18 loop)

stepLimit

T_INT

Maximum step allowance that can be used by the transaction.

timestamp

T_INT

Transaction creation time. timestamp is in microsecond.

nid

T_INT

Network ID

nonce

T_INT

An arbitrary number used to prevent transaction hash collision.

txHash

T_HASH

Transaction hash

txIndex

T_INT

Transaction index in a block. Null when it is pending.

blockHeight

T_INT

Block height where this transaction was in. Null when it is pending.

blockHash

T_HASH

Hash of the block where this transaction was in. Null when it is pending.

signature

T_SIG

Signature of the transaction.

dataType

T_DATA_TYPE

Type of data. (call, deploy, or message)

data

T_DICT or String

Contains various type of data depending on the dataType. See Parameters - data.

Example

// Request
{
"jsonrpc": "2.0",
"method": "icx_getTransactionByHash",
"id": 1234,
"params": {
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
}
}
// Response - coin transfer
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
"value": "0xde0b6b3a7640000",
"stepLimit": "0x12345",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"txIndex": "0x1",
"blockHeight": "0x1234",
"blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA="
}
}
// Response - SCORE function call
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
"stepLimit": "0x12345",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1",
"txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"txIndex": "0x1",
"blockHeight": "0x1234",
"blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
"dataType": "call",
"data": {
"method": "transfer",
"params": {
"to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
"value": "0x1"
}
}
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid params txHash"
}
}

icx_sendTransaction

You can do one of the followings using this method.

  • Transfer designated amount of ICX coins from 'from' address to 'to' address.

  • Install a new SCORE.

  • Update the SCORE in the 'to' address.

  • Invoke a function of the SCORE in the 'to' address.

  • Transfer a message.

This function causes state transitions.

Parameters

KEY

VALUE type

Required

Description

version

T_INT

required

Protocol version (0x3 for V3)

from

T_ADDR_EOA

required

EOA address that created the transaction

to

T_ADDR_EOA or T_ADDR_SCORE

required

EOA address to receive coins, or SCORE address to execute the transaction.

value

T_INT

optional

Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)

stepLimit

T_INT

required

Maximum step allowance that can be used by the transaction.

timestamp

T_INT

required

Transaction creation time. timestamp is in microsecond.

nid

T_INT

required

Network ID (0x1 for Mainnet, 0x2 for Testnet, etc)

nonce

T_INT

optional

An arbitrary number used to prevent transaction hash collision.

signature

T_SIG

required

Signature of the transaction.

dataType

T_DATA_TYPE

optional

Type of data. (call, deploy, or message)

data

T_DICT or String

optional

The content of data varies depending on the dataType. See Parameters - data. The maximum size of data is 512 KB.

Parameters - data

data contains the following data in various formats depending on the dataType.

1. dataType == call

It is used when calling a function in SCORE, and data has dictionary value as follows.

KEY

VALUE type

Required

Description

method

String

required

Name of the function to invoke in SCORE

params

T_DICT

optional

Function parameters

2. dataType == deploy

It is used when installing or updating a SCORE, and data has dictionary value as follows.

KEY

VALUE type

Required

Description

contentType

String

required

Mime-type of the content

content

T_BIN_DATA

required

Compressed SCORE data

params

T_DICT

optional

Function parameters will be delivered to on_install() or on_update()

3. dataType == message

It is used when transferring a message, and data has a HEX string.

Returns

  • Transaction hash (T_HASH) on success

  • Error code and message on failure

Example

  • Coin transfer

    // Request
    {
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
    "version": "0x3",
    "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
    "value": "0xde0b6b3a7640000",
    "stepLimit": "0x12345",
    "timestamp": "0x563a6cf330136",
    "nid": "0x3",
    "nonce": "0x1",
    "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA="
    }
    }
  • SCORE function call

    // Request
    {
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
    "version": "0x3",
    "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
    "stepLimit": "0x12345",
    "timestamp": "0x563a6cf330136",
    "nid": "0x3",
    "nonce": "0x1",
    "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
    "dataType": "call",
    "data": {
    "method": "transfer",
    "params": {
    "to": "hxab2d8215eab14bc6bdd8bfb2c8151257032ecd8b",
    "value": "0x1"
    }
    }
    }
    }
  • SCORE install

    // Request
    {
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
    "version": "0x3",
    "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "to": "cx0000000000000000000000000000000000000000", // address 0 means SCORE install
    "stepLimit": "0x12345",
    "timestamp": "0x563a6cf330136",
    "nid": "0x3",
    "nonce": "0x1",
    "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
    "dataType": "deploy",
    "data": {
    "contentType": "application/zip",
    "content": "0x1867291283973610982301923812873419826abcdef91827319263187263a7326e...", // compressed SCORE data
    "params": { // parameters to be passed to on_install()
    "name": "ABCToken",
    "symbol": "abc",
    "decimals": "0x12"
    }
    }
    }
    }
  • SCORE update

    // Request
    {
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
    "version": "0x3",
    "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "to": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32", // SCORE address to be updated
    "stepLimit": "0x12345",
    "timestamp": "0x563a6cf330136",
    "nid": "0x3",
    "nonce": "0x1",
    "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
    "dataType": "deploy",
    "data": {
    "contentType": "application/zip",
    "content": "0x1867291283973610982301923812873419826abcdef91827319263187263a7326e...", // compressed SCORE data
    "params": { // parameters to be passed to on_update()
    "amount": "0x1234"
    }
    }
    }
    }
  • Message transfer

    // Request
    {
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
    "version": "0x3",
    "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "to": "hxbe258ceb872e08851f1f59694dac2558708ece11",
    "stepLimit": "0x12345",
    "timestamp": "0x563a6cf330136",
    "nid": "0x3",
    "nonce": "0x1",
    "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
    "dataType": "message",
    "data": "0x4c6f72656d20697073756d20646f6c6f722073697420616d65742c20636f6e7365637465747572206164697069736963696e6720656c69742c2073656420646f20656975736d6f642074656d706f7220696e6369646964756e74207574206c61626f726520657420646f6c6f7265206d61676e6120616c697175612e20557420656e696d206164206d696e696d2076656e69616d2c2071756973206e6f737472756420657865726369746174696f6e20756c6c616d636f206c61626f726973206e69736920757420616c697175697020657820656120636f6d6d6f646f20636f6e7365717561742e2044756973206175746520697275726520646f6c6f7220696e20726570726568656e646572697420696e20766f6c7570746174652076656c697420657373652063696c6c756d20646f6c6f726520657520667567696174206e756c6c612070617269617475722e204578636570746575722073696e74206f6363616563617420637570696461746174206e6f6e2070726f6964656e742c2073756e7420696e2063756c706120717569206f666669636961206465736572756e74206d6f6c6c697420616e696d20696420657374206c61626f72756d2e"
    }
    }
  • Responses

// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": "0x4bf74e6aeeb43bde5dc8d5b62537a33ac8eb7605ebbdb51b015c1881b45b3aed" // transaction hash
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32600,
"message": "Invalid signature"
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32601,
"message": "Method not found"
}
}

debug_estimateStep

  • Generates and returns an estimated step of how much step is necessary to allow the transaction to complete. The transaction will not be added to the blockchain. Note that the estimation can be larger than the actual amount of step to be used by the transaction for several reasons such as node performance.

Parameters

  • The transaction information without stepLimit and signature

KEY

VALUE type

Required

Description

version

T_INT

required

Protocol version (0x3 for V3)

from

T_ADDR_EOA

required

EOA address that created the transaction

to

T_ADDR_EOA or T_ADDR_SCORE

required

EOA address to receive coins, or SCORE address to execute the transaction.

value

T_INT

optional

Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)

timestamp

T_INT

required

Transaction creation time. timestamp is in microsecond.

nid

T_INT

required

Network ID (0x1 for Mainnet, 0x2 for Testnet, etc)

nonce

T_INT

optional

An arbitrary number used to prevent transaction hash collision.

dataType

T_DATA_TYPE

optional

Type of data. (call, deploy, or message)

data

T_DICT or String

optional

The content of data varies depending on the dataType. See Parameters - data.

Returns

  • The amount of an estimated step

Example

// Request
{
"jsonrpc": "2.0",
"method": "debug_estimateStep",
"id": 1234,
"params": {
"version": "0x3",
"from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
"to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
"value": "0xde0b6b3a7640000",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x1"
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": "0x109eb0"
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "JSON schema validation error: 'version' is a required property"
}
}

debug_getAccount

  • Returns the Account information including stake, delegation of the given EOA or SCORE.

Parameters

KEY

VALUE type

Description

address

T_ADDR_EOA or T_ADDR_SCORE

Address of EOA or SCORE

filter

T_INT

flag value to what information will be included(coin : 1, stake: 2, delegation: 4)

Returns

Information of Account

Example

// Request
{
"jsonrpc": "2.0",
"id": 1234,
"method": "debug_getAccount",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
"filter": "0x7"
}
}
// Response - success
{
"coin": {
"type": "0x1",
"typeStr": "CoinPartType.GENERAL",
"flag": "0x0",
"flagStr": "CoinPartFlag.None"
},
"stake": {
"stake": "0x100",
"unstake": "0x100",
"unstakeBlockHeight": "0x200",
"unstakesInfo": [
[
"0x100",
"0x200"
]
]
},
"delegation": {
"totalDelegated": "0xa688906bd8b0000",
"delegations": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3782dace9d90000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x6f05b59d3b20000"
}
]
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid address"
}
}

rep_getList

  • Get all list of Representatives and information about terms & RepRootHash

Parameters

None

Returns

  • The list of Representatives of the last block

Example

// Request
{
"jsonrpc" : "2.0",
"method": "rep_getList",
"id": 1234
}
// Response - success
{
"jsonrpc": "2.0",
"result": {
"startTermHeight": "0x0",
"endTermHeight": "0x0",
"repHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
"rep": [
{
"id": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
},
{
"id": "hx9f049228bade72bc0a3490061b824f16bbb74589"
},
{
"id": "hx6435405122df9fe5187d659588beccdf7aee8557"
},
{
"id": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f"
}
]
},
"id": 1234
}

ise_getStatus

  • Returns the status of iconservice

Parameters

KEY

VALUE type

Description

filter

T_LIST(String)

List of keys to filter

Returns

  • T_DICT(String)

Example

// Request
{
"jsonrpc": "2.0",
"method": "ise_getStatus",
"id": 1234,
"params": {
"filter": ["lastBlock"]
}
}
// Response - success
{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"lastBlock": {
"blockHeight": "0x3",
"blockHash": "0x1145f61e69d2a6265f00c29ae2da9a2c73100c9ab4221c6612cfd04edfa0e30d",
"timestamp": "0x5739b20776a61",
"prevBlockHash": "0xaeb6768558648eed2a36ac13bc6501d075a8dd2ee6a23e277a5def596bfed603"
}
}
// Response - error
{
"jsonrpc": "2.0",
"id": 1234,
"error": {
"code": -32602,
"message": "Invalid address"
}
}

IISS API

  • All IISS APIs follow SCORE API call convention

  • Target SCORE Address for IISS APIs: cx0000000000000000000000000000000000000000

  • Each IISS API method section explains the content of data field in icx_sendTransaction

{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"version": "0x3",
"from": "hx8f21e5c54f016b6a5d5fe65486908592151a7c57",
"to": "cx0000000000000000000000000000000000000000",
"stepLimit": "0x7e3a85",
"timestamp": "0x563a6cf330136",
"nid": "0x3",
"nonce": "0x0",
"value": "0x0",
"signature": "VAia7YZ2Ji6igKWzjR2YsGa2m5...",
"dataType": "call",
"data": {
"method": "setStake",
"params": {
"value": "0x1"
}
}
}
}

setStake

  • Stake some amount of ICX

Parameters

KEY

VALUE type

Required

Description

value

T_INT

O

ICX Amount in loop

Returns

  • Transaction hash(T_HASH) on success

  • Error code and message on failure

EventLog

N/A

Example

Request

{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setStake",
"params": {
"value": "0xde0b6b3a7640000"
}
},
...
}
}

getStake

  • Returns the stake status of a given address

Parameters

KEY

VALUE type

Required

Description

address

T_ADDR_EOA

O

Address to query

Returns

KEY

VALUE type

Required

Description

stake

T_INT

O

ICX amount of stake in loop

unstakes

T_LIST[T_DICT]

X

Unstake info list

unstakes.unstake

T_INT

X

ICX amount of unstake in loop

unstakes.unstakeBlockHeight

T_INT

X

BlockHeight when unstake will be done

unstakes.remainingBlocks

T_INT

X

The number of remaining blocks to reach unstakeBlockHeight

Example

Request

{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_call",
"params": {
"to": "cx0000000000000000000000000000000000000000",
"dataType": "call",
"data": {
"method": "getStake",
"params": {
"address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
}
}
}
}

Response on success

{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"stake": "0x4e1003b28d9280000",
"unstakes": [
{
"unstake": "0x8ac7230489e80000",
"unstakeBlockHeight": "0x19",
"remainingBlocks": "0x11"
}
]
}
}

Response on success when there is no unstake

{
"jsonrpc": "2.0",
"id": 1234,
"result": {
"stake": "0xde0b6b3a7640000"
}
}

setDelegation

  • Delegate some ICX amount of stake to P-Reps

  • Maximum number of P-Reps to delegate is 10

  • The transaction which has duplicated P-Rep addresses will be failed

  • This transaction overwrites the previous delegate information

Parameters

KEY

VALUE type

Required

Description

delegations

T_LIST(T_DICT)

O

List of delegation dict (Max: 10 entries)

delegations.address

T_ADDR_EOA

O

Address of P-Rep to delegate

delegations.value

T_INT

O

Delegation amount in loop

Returns

  • Transaction hash(T_HASH) on success

  • Error code and message on failure

EventLog

N/A

Example

Request

{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setDelegation",
"params": {
"delegations": [
{
"address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
"value": "0x3200000000"
},
{
"address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
"value": "0x1000000000"
}
]
}
},
...
}
}

Request to revoke all delegations

{
"jsonrpc": "2.0",
"id": 1234,
"method": "icx_sendTransaction",
"params": {
"data": {
"method": "setDelegation",
"params": {
"delegations": []
}
},
...
}
}

getDelegation

  • Returns the delegation status of a given address

Parameters

KEY

VALUE type

Required

Description

address

T_ADDR_EOA

O

Address to query

Returns

KEY

VALUE type

Required

Description

delegations

T_LIST(T_DICT)

O

List of delegation dict (Max: 10 entries)

delegation.address

T_ADDR_EOA

X

P-Rep address

delegation.value

T_INT

O

Delegation amount in loop

delegation.status

T_INT

O

0: active 1: Unregistered