title
ICON JSON-RPC API v3 Guide

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, or message

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

Debug API

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

debug_estimateStep

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
txHash	T_HASH	Hash of the transaction

Returns

KEY	VALUE type	Description
version	T_INT	Protocol version (`0x3` for V3)
from	T_ADDR_EOA	EOA address that created the transaction
to	T_ADDR_EOA or T_ADDR_SCORE	EOA address to receive coins, or SCORE address to execute the transaction.
value	T_INT	Amount of ICX coins in loop to transfer. When ommitted, assumes 0. (1 icx = 1 ^ 18 loop)
stepLimit	T_INT	Maximum step allowance that can be used by the transaction.
timestamp	T_INT	Transaction creation time. timestamp is in microsecond.
nid	T_INT	Network ID
nonce	T_INT	An arbitrary number used to prevent transaction hash collision.
txHash	T_HASH	Transaction hash
txIndex	T_INT	Transaction index in a block. Null when it is pending.
blockHeight	T_INT	Block height where this transaction was in. Null when it is pending.
blockHash	T_HASH	Hash of the block where this transaction was in. Null when it is pending.
signature	T_SIG	Signature of the transaction.
dataType	T_DATA_TYPE	Type of data. (call, deploy, or message)
data	T_DICT or String	Contains various type of data depending on the dataType. See Parameters - data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getTransactionByHash",
    "id": 1234,
    "params": {
        "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    }
}

// Response - coin transfer
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
        "value": "0xde0b6b3a7640000",
        "stepLimit": "0x12345",
        "timestamp": "0x563a6cf330136",
        "nid": "0x3",
        "nonce": "0x1",
        "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "txIndex": "0x1",
        "blockHeight": "0x1234",
        "blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA="
    }
}

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

// Response - error
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid params txHash"
    }
}

icx_sendTransaction

You can do one of the followings using this method.

Transfer designated amount of ICX coins from 'from' address to 'to' address.
Install a new SCORE.
Update the SCORE in the 'to' address.
Invoke a function of the SCORE in the 'to' address.
Transfer a message.

This function causes state transitions.

Parameters

KEY	VALUE type	Required	Description
version	T_INT	required	Protocol version (`0x3` for V3)
from	T_ADDR_EOA	required	EOA address that created the transaction
to	T_ADDR_EOA or T_ADDR_SCORE	required	EOA address to receive coins, or SCORE address to execute the transaction.
value	T_INT	optional	Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
stepLimit	T_INT	required	Maximum step allowance that can be used by the transaction.
timestamp	T_INT	required	Transaction creation time. timestamp is in microsecond.
nid	T_INT	required	Network ID (`0x1` for Mainnet, `0x2` for Testnet, etc)
nonce	T_INT	optional	An arbitrary number used to prevent transaction hash collision.
signature	T_SIG	required	Signature of the transaction.
dataType	T_DATA_TYPE	optional	Type of data. (call, deploy, or message)
data	T_DICT or String	optional	The content of data varies depending on the dataType. See Parameters - data. The maximum size of data is 512 KB.

Parameters - data

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

1. dataType == call

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

KEY	VALUE type	Required	Description
method	String	required	Name of the function to invoke in SCORE
params	T_DICT	optional	Function parameters

2. dataType == deploy

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

KEY	VALUE type	Required	Description
contentType	String	required	Mime-type of the content
content	T_BIN_DATA	required	Compressed SCORE data
params	T_DICT	optional	Function parameters will be delivered to on_install() or on_update()

3. dataType == message

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

Returns

Transaction hash (T_HASH) on success
Error code and message on failure

Example

Coin transfer

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

SCORE function call

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

SCORE install

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

SCORE update

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

Message transfer

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

Responses

// Response - success
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": "0x4bf74e6aeeb43bde5dc8d5b62537a33ac8eb7605ebbdb51b015c1881b45b3aed" // transaction hash
}

// Response - error
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32600,
        "message": "Invalid signature"
    }
}

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

debug_estimateStep

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

Parameters

The transaction information without stepLimit and signature

KEY	VALUE type	Required	Description
version	T_INT	required	Protocol version (`0x3` for V3)
from	T_ADDR_EOA	required	EOA address that created the transaction
to	T_ADDR_EOA or T_ADDR_SCORE	required	EOA address to receive coins, or SCORE address to execute the transaction.
value	T_INT	optional	Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
timestamp	T_INT	required	Transaction creation time. timestamp is in microsecond.
nid	T_INT	required	Network ID (`0x1` for Mainnet, `0x2` for Testnet, etc)
nonce	T_INT	optional	An arbitrary number used to prevent transaction hash collision.
dataType	T_DATA_TYPE	optional	Type of data. (call, deploy, or message)
data	T_DICT or String	optional	The content of data varies depending on the dataType. See Parameters - data.

Returns

The amount of an estimated step

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "debug_estimateStep",
    "id": 1234,
    "params": {
        "version": "0x3",
        "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
        "to": "hx5bfdb090f43a808005ffc27c25b213145e80b7cd",
        "value": "0xde0b6b3a7640000",
        "timestamp": "0x563a6cf330136",
        "nid": "0x3",
        "nonce": "0x1"
    }
}

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

// Response - error
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "JSON schema validation error: 'version' is a required property"
    }
}

rep_getList

Get all list of Representatives and information about terms & RepRootHash

Parameters

None

Returns

The list of Representatives of the last block

Example

// Request
{
    "jsonrpc" : "2.0",
    "method": "rep_getList",
    "id": 1234
}

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

ise_getStatus

Returns the status of iconservice

Parameters

KEY	VALUE type	Description
filter	T_LIST(String)	List of keys to filter

Returns

T_DICT(String)

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "ise_getStatus",
    "id": 1234,
    "params": {
        "filter": ["lastBlock"]
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
         "lastBlock": {
	      "blockHeight": "0x3",
	      "blockHash": "0x1145f61e69d2a6265f00c29ae2da9a2c73100c9ab4221c6612cfd04edfa0e30d",
	      "timestamp": "0x5739b20776a61",
	      "prevBlockHash": "0xaeb6768558648eed2a36ac13bc6501d075a8dd2ee6a23e277a5def596bfed603"
	}
}

// Response - error
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid address"
    }
}

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 Specification

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_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_sendTransaction

Parameters

Returns

Example

debug_estimateStep

Parameters

Returns

Example

rep_getList

Parameters

Returns

Example

ise_getStatus

Parameters

Returns

Example

References