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.
// 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.
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 |
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"
}
}
- 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.
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
- 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=="
}
}
- 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"
}
}
- 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"
}
}
- 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"
}
}
- 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"
}
}
- 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"
}
}
- 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"
}
- 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"
}
}
- Returns the transaction information requested by transaction hash.
Parameters
KEY | VALUE type | Description |
txHash |