ICON1
Search
⌃K

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

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