ICON JSON-RPC API v3

This document explains JSON-RPC APIs (version 3) available to interact with ICON nodes.

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_PROOF_DATA	{"left": T_HASH} or {"right": T_HASH}	{"left": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238" }
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.

JSON-RPC Error Response

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

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.
Append icx_getBlockReceipts API

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_getBlock
icx_getLastBlock
icx_getBlockByHeight
icx_getBlockByHash
icx_call
icx_getBalance
icx_getScoreApi
icx_getTotalSupply
icx_getTransactionResult
icx_getTransactionByHash
icx_getTransactionProof
icx_getReceiptProof
icx_proveTransaction
icx_proveReceipt
icx_sendTransaction
icx_getBlockReceipts

Debug API

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

debug_estimateStep
debug_getAccount

Other API

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

ise_getStatus
rep_getListByHash

JSON-RPC Methods

icx_getBlock

Returns the block information by given parameter.
Depcreated since 1.7.0, will be removed in ICON 2.0

Parameters

KEY	VALUE type	Description
hash	T_HASH	Hash of a block
height	T_INT	Integer of a block height
unconfirmed	Boolean	(optional) true or false, must be used with height parameter
None	-	Last block

Returns

Block data (including v0.3)

Example

// Request 1 - get last block
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234
}

// Request 2 - get block by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.3",
        "prevHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x51e030a24c5967047f8463c138024f857ec6663535df1f4e76e224f95abbe4b1",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5908392532c01",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x590839234a5de",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "9MhqZW4n9CtJXTKfDOiVsvZRuGQh9G3X9g3X3+4V2Fp8PcqGvkKHoAI4nJpAxGiJICiT7kgMqwQmvQ8ndGVXrgE="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x590839235367b",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "e2JNWDnNTulhksibVR2AV0/ZLLPwDfeOdq1A5DE/GAIPI56QR+78nV7I/eNHvFDzL6OcpN7D5/VZ5dfFBszB2QE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x590839235419f",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "mjhQSlSZhYuwLSqu+CbNDsiB4WTn8096RQ2EP89YPAVRita+bDuCBhyUkfZWhDqQPVW//sCwQD2GDXxNCC5dCgA="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x59083923541d1",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "o2OnbkaLK1rvGP+pDwrTo/+VV1Ag2/HuDeUV5aoReOhvmS4rOWLGuV00B5KZmE9GO7ZRHl32Ys0oSrj85ve3uAA="
            }
        ],
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "OPHFV8Zfyr//lP+SmKsr/RK3yawJDtolrfsdqDFKh3wxmyMh243zVp7CTLRu5wG5PdneX7mHzuLA9x41mqzjrAE=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}

// Request 4 - get block by height with unconfirmed
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x5",
        "unconfirmed": true
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.4",
        "prevHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x233f88d770fcca44b9c91ea6e55a4d981b858ea6f69830443811f73d32918f79",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5c8c877889b70",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x5c8c8776cd53d",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "/6LUAH8oWcVWvq3BMzQu/lujO7s5b5cY9ekVDxeIfVE9PFCKHr7ZHDkmhO01jPyg6ZP/XjB9rYTRyoWu1gVanQA="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x5c8c8777e4f88",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "oOoxPUH4UeE+6TBDfc65UjDn5NoxO5aCDY2k/wPENZROdu7piD7muxk/2Z022U63TYcRtbkd1I5lHiXibJnmWgE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x5c8c87783cbc1",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "WrzmUjN7YltUuTU7uPXomzkLgUQdecTZEaVmtx4bnpBa0WP4yfFwnYv1KllK1rD6rpOsvqc5wJlKH6qsacsbDAE="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x5c8c877877aa8",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "AzQb7B/0FcLcC8V/JdBa5Kv3I9J+daMAQq+bWZT2tsRy/xX5kK9vkeUXpWUpzjkgQdnMJWx9X88nclhz4nvWaAA="
            }
        ],
        "hash": "0x7febf336c2a68fb2c844f8b3b9f489d1baa7a5f4910e75d92a89384c9d75551a",
        "height": "0x5",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "bZQBqFO+7Cnsbhc4HdkTyz42MS0yB6q829P2aBL9lYkHKxbldSjPkXNoKcsdtr5Qx7f5pTNdCx93Mczighj6zAA=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}


// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "JSON schema validation error: 'params' has an invalid value"
    },
    "id": 1234
}

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
- type : function, fallback, or eventlog
- name : function name
- inputs : parameters in array
  - name : parameter name
  - type : parameter type (int, str, bytes, bool, Address)
  - default: the default value if the parameter has a default value (optional)
  - indexed : 0x1 if the parameter is indexed (when this is eventlog) (optional)
- outputs : return value
  - type : return value type (int, str, bytes, bool, Address, dict, list)
- readonly : 0x1 if this is declared as external(readonly=True)
- payable : 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	1 on success, 0 on failure.
to	T_ADDR_EOA or T_ADDR_SCORE	Recipient address of the transaction
failure	T_DICT	This field exists when status is 0. Contains code(str) and message(str).
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, message or deposit)
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_getTransactionProof

Returns the transaction proof requested by transaction hash.

Parameters

KEY	VALUE type	Description
txHash	T_HASH	Hash of the transaction

Returns

T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getTransactionProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_getReceiptProof

Returns the transaction receipt proof requested by transaction hash.

Parameters

KEY	VALUE type	Description
txHash	T_HASH	Hash of the transaction

Returns

T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getReceiptProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveTransaction

Returns the result of proving requested by transaction hash with its proof.

Parameters

KEY	VALUE type	Description
txHash	T_HASH	Hash of the transaction
proof	T_LIST(T_PROOF_DATA)	List of proof data

Returns

T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveTransaction",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": 0x1,
    "id": 1234
}

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveReceipt

Returns the result of proving the receipt requested by transaction hash with its proof.

Parameters

KEY	VALUE type	Description
txHash	T_HASH	Hash of the transaction
proof	T_LIST(T_PROOF_DATA)	List of proof data

Returns

T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveReceipt",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": 0x1,
    "id": 1234
}

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "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"
    }
}

icx_sendTransaction

You can do one of the followings using this function.

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 transition.

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 ommitted, 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, message or deposit)
data	T_DICT or String	optional	The content of data varies depending on the dataType. See Parameters - data.

Parameters - data

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

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

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()

dataType == message

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

dataType == deposit

It is used when depositing ICX in SCORE or withdrawing the deposited ICX, and data has dictionary value as follows.

KEY	VALUE type	Required	Description
action	String	required	Name of the action (`add` or `withdraw`)
id	String	optional	needed when withdrawing the deposited ICX

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"
    }
}

Deposit ICX to SCORE

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "cxbe258ceb872e08851f1f59694dac2558708ece11",
        "value": "0x10f0cf064dd59200000",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x3",
        "nonce": "0x1",
        "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
        "dataType": "deposit",
        "data": {
            "action": "add"
        }
    }
}

Withdraw ICX from SCORE

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_sendTransaction",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "cxbe258ceb872e08851f1f59694dac2558708ece11",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x3",
        "nonce": "0x1",
        "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=",
        "dataType": "deposit",
        "data": {
            "action": "withdraw",
            "id": "0x4bf74e6aeeb43bde5dc8d5b62537a33ac8eb7605ebbdb51b015c1881b45b3111"
        }
    }
}

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 ommitted, 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_getListByHash

Get all list of Representatives and information by RepsHash

Parameters

KEY	VALUE type	Required	Description
repsHash	T_HASH	required	root hash of representatives

Returns

The list of Representatives information by repsHash

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "rep_getListByHash",
    "id": 1234,
    "params": {
        "repsHash": "0x71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "address": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
            "p2pEndpoint": "127.0.0.1:7100"
        },
        {
            "address": "hx9f049228bade72bc0a3490061b824f16bbb74589",
            "p2pEndpoint": "127.0.0.1:7200"
        },
        {
            "address": "hx6435405122df9fe5187d659588beccdf7aee8557",
            "p2pEndpoint": "127.0.0.1:7300"
        },
        {
            "address": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
            "p2pEndpoint": "127.0.0.1:7400"
        }
    ],
    "id": 1234
}

icx_getBlockReceipts

Returns the block receipts by given parameter.

Parameters

KEY	VALUE type	Description
hash	T_HASH	Hash of a block
height	T_INT	Integer of a block height
None	-	Last block

Returns

Block Receipts data (including v0.3)

Example

// Request 1 - get last block receipts
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234
}

// Request 2 - get block receipts by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block receipts by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
		{
			"txHash": "4b9afccf0ce595fc67fd84959d8ff3107aad2e78ea418d8e115d39dbb5ddf683",
			"blockHeight": "0x696",
			"blockHash": "59415879e59977ac29bfa5dcfff3dfff2604beb0f1ba97d1944caf90b39d4c49",
			"txIndex": "0x0",
			"to": "hxe3d6d5d8e433fbd13b9c481d11cf46cebd84b23c",
			"stepUsed": "0x0",
			"stepPrice": "0x0",
			"cumulativeStepUsed": "0x0",
			"eventLogs": [
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"PRepIssued(int,int,int,int)"
					],
					"data": [
						"0xa968163f0a57b400000",
						"0x477",
						"0xd3e02419de2130fd07fe4",
						"0x20bd5ed6b99b1fcb"
					]
				},
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"ICXIssued(int,int,int,int)"
					],
					"data": [
						"0x0",
						"0x20bd5ed6b99b1fcb",
						"0x0",
						"0x53a06a5e791a89dbe"
					]
				}
			],
			"status": "0x1"
		}
	],
  "id": 1234
}

// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid params (only one parameter is allowed)"
    }
}

References

JSON-RPC 2.0 Specification
ICON JSON RPC API v2

Files

icon-json-rpc-v3.md

Latest commit

History

icon-json-rpc-v3.md

File metadata and controls

ICON JSON-RPC API v3

API Convention

VALUE Types

JSON-RPC Error Codes

Error Codes

JSON-RPC Error Response

JSON-RPC API v3 ChangeLog

JSON-RPC APIs

Main API

Debug API

Other API

JSON-RPC Methods

icx_getBlock

Parameters

Returns

Example

icx_getLastBlock

Parameters

Returns

Example

icx_getBlockByHeight

Parameters

Returns

Example

icx_getBlockByHash

Parameters

Returns

Example

icx_call

Parameters

Returns

Example

icx_getBalance

Parameters

Returns

Example

icx_getScoreApi

Parameters

Returns

Example

icx_getTotalSupply

Parameters

Returns

Example

icx_getTransactionResult

Parameters

Returns

Example

icx_getTransactionByHash

Parameters

Returns

Example

icx_getTransactionProof

Parameters

Returns

Example

icx_getReceiptProof

Parameters

Returns

Example

icx_proveTransaction

Parameters

Returns

Example

icx_proveReceipt

Parameters

Returns

Example

ise_getStatus

Parameters

Returns

Example

icx_sendTransaction

Parameters