Comment on page

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
​icx_getLastBlock​
​icx_getBlockByHeight​
​icx_getBlockByHash​
​icx_call​
​icx_getBalance​
​icx_getScoreApi​
​icx_getTotalSupply​
​icx_getTransactionResult​
​icx_getTransactionByHash​
​icx_sendTransaction​
Sub API
API path : <scheme>://<host>/api/v3
IISS API
​setStake​
​getStake​
​setDelegation​
​getDelegation​
​claimIScore​
​queryIScore​
​registerPRep​
​unregisterPRep​
​setPRep​
​setGovernanceVariables​
​getPRep​
​getPReps​
Debug API
API path : <scheme>://<host>/api/debug/v3
​debug_estimateStep​
​debug_getAccount​
Other API
API path : <scheme>://<host>/api/v3
​ise_getStatus​
​rep_getList​
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	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

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.

KEY	VALUE type	Description
height	T_INT	Integer of a block height

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.

KEY	VALUE type	Description
address	T_ADDR_EOA or T_ADDR_SCORE	Address of EOA or SCORE

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

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.