v3.md

v3

ICON JSON-RPC APIs (version 3) are interfaces to interact with ICON nodes. This document explains ICON JSON-RPC API (version 3) data structures, rules and the list of methods.

ICON JSON-RPC API v3 Specification

API Convention

Follows JSON-RPC 2.0 Specification.

// Request
{
    "jsonrpc": "2.0",
    "method": "$STRING1",
    "id": $INT,
    "params": {
        "$KEY1": "$VALUE1",
        "$KEY2": {
            "method": "$STRING2",
            "params": {
                "$KEY3": "$VALUE3"
            }
        }
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "id": $INT,
    "result": "$STRING"
    // or
    "result": {
      "$KEY1": "$VALUE1",
      "$KEY2": "$VALUE2"
    }
}

// Response - error
{
    "jsonrpc": "2.0",
    "id": $INT1,
    "error": {
        "code": $INT2,
        "message": "$STRING"
    }
}

• "KEY" naming follows camel case.

VALUE Types

Basically, every VALUE in JSON-RPC message is string. Below table shows the most common "VALUE types".

VALUE type	Description	Example
T_ADDR_EOA	"hx" + 40 digit HEX string	hxbe258ceb872e08851f1f59694dac2558708ece11
T_ADDR_SCORE	"cx" + 40 digit HEX string	cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32
T_HASH	"0x" + 64 digit HEX string	0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238
T_INT	"0x" + lowercase HEX string	0xa
T_BIN_DATA	"0x" + lowercase HEX string. Length must be even.	0x34b2
T_SIG	base64 encoded string	VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=
T_DATA_TYPE	Type of data	call, deploy, message or deposit

JSON-RPC Error Codes

This chapter explains the error codes used in ICON JSON-RPC API response.

Below table shows the default error messages for the error code. Actual message may vary depending on the implementation.

Error Codes

Error code	Message	Description
-32700	Parse error	Invalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600	Invalid Request	The JSON sent is not a valid Request object.
-32601	Method not found	The method does not exist / is not available.
-32602	Invalid params	Invalid method parameter(s).
-32603	Internal error	Internal JSON-RPC error.
-32000	Server error	IconServiceEngine internal error.
-32100	Score error	Score internal error.

• Some error codes may change

JSON-RPC Error Response

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

JSON-RPC API v3 ChangeLog

• Fixed to conform to JSON-RPC 2.0 specification
  • Success response: result
  • Failure response: error
• Removed additional response generated by loopchain such as "response_code" in SCORE's JSON-PRC Response.
  • v2: "result": {"response_code": "0x0", "response": "0x12345"}
  • v3: "result": "0x12345"
• Fixed inconsistent KEY naming in v2 API
  • v2: icx_getBlockByHeight: "time_stamp"
  • v2: icx_sendTransaction: "timestamp"
  • v3: "timestamp"
• Fixed inconsistent VALUE format in v2 API
  • timestamp
    • v2: icx_sendTransaction: "timestamp": "1234567890"
    • v2: icx_getBlockByHeight: "timestamp": 1234567890
    • v3: "timestamp": "0x499602d2"
  • hash
    • v2: icx_getBlockByHash: "hash": "af5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"
    • v3: "hash": "0xaf5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"
• KEY naming follows camel case.
  • v2: "data_type"
  • v3: "dataType"
• Removed tx_hash from the icx_sendTransaction message.

JSON-RPC APIs

For multichannel requests, add /<channel_name> at the end of the API path.

Main API

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

• icx_getLastBlock
• icx_getBlockByHeight
• icx_getBlockByHash
• icx_call
• icx_getBalance
• icx_getScoreApi
• icx_getTotalSupply
• icx_getTransactionResult
• icx_getTransactionByHash
• icx_sendTransaction

IISS API

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

• setStake
• getStake
• setDelegation
• getDelegation
• setBonderList
• getBonderList
• setBond
• getBond
• claimIScore
• queryIScore
• registerPRep
• unregisterPRep
• setPRep
• setGovernanceVariables
• getPRep
• getPReps
• getScoreOwner
• setScoreOwner

Debug API

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

• 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	Required	Description
from	T_ADDR_EOA	O	Message sender's address.
to	T_ADDR_SCORE	O	SCORE address that will handle the message.
height	T_INT	X	Integer of a block height
dataType	T_DATA_TYPE	O	icx_call is the only possible data type.
data	T_DICT	O	See Parameters - data.
data.method	String	O	Name of the function.
data.params	T_DICT	O	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	Requried	Description
address	T_ADDR_EOA or T_ADDR_SCORE	O	Address of EOA or SCORE
height	T_INT	X	Integer of a block height

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	Requried	Description
address	T_ADDR_SCORE	O	SCORE address to be examined
height	T_INT	X	Integer of a block height

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

KEY	VALUE type	Required	Description
height	T_INT	X	Integer of a block height

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	O	Protocol version (0x3 for V3)
from	T_ADDR_EOA	O	EOA address that created the transaction
to	T_ADDR_EOA or T_ADDR_SCORE	O	EOA address to receive coins, or SCORE address to execute the transaction.
value	T_INT	X	Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
stepLimit	T_INT	O	Maximum step allowance that can be used by the transaction.
timestamp	T_INT	O	Transaction creation time. timestamp is in microsecond.
nid	T_INT	O	Network ID (0x1 for Mainnet, 0x2 for Testnet, etc)
nonce	T_INT	X	An arbitrary number used to prevent transaction hash collision.
signature	T_SIG	O	Signature of the transaction.
dataType	T_DATA_TYPE	X	Type of data. (call, deploy, or message)
data	T_DICT or String	X	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	O	Name of the function to invoke in SCORE
params	T_DICT	X	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	O	Mime-type of the content
content	T_BIN_DATA	O	Compressed SCORE data
params	T_DICT	X	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/java",
            "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/java",
            "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	O	Protocol version (0x3 for V3)
from	T_ADDR_EOA	O	EOA address that created the transaction
to	T_ADDR_EOA or T_ADDR_SCORE	O	EOA address to receive coins, or SCORE address to execute the transaction.
value	T_INT	X	Amount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
timestamp	T_INT	O	Transaction creation time. timestamp is in microsecond.
nid	T_INT	O	Network ID (0x1 for Mainnet, 0x2 for Testnet, etc)
nonce	T_INT	X	An arbitrary number used to prevent transaction hash collision.
dataType	T_DATA_TYPE	X	Type of data. (call, deploy, or message)
data	T_DICT or String	X	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"
    }
}

IISS API

• All IISS APIs follow SCORE API call convention
• Target SCORE Address for IISS APIs: cx0000000000000000000000000000000000000000
• Each IISS API method section explains the content of data field in icx_sendTransaction

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "version": "0x3",
        "from": "hx8f21e5c54f016b6a5d5fe65486908592151a7c57",
        "to": "cx0000000000000000000000000000000000000000",
        "stepLimit": "0x7e3a85",
        "timestamp": "0x563a6cf330136",
        "nid": "0x3",
        "nonce": "0x0",
        "value": "0x0",
        "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m5...",
        "dataType": "call",
        "data": {
            "method": "setStake",
            "params": {
                "value": "0x1"
            }
        }
    }
}

setStake

• Stake some amount of ICX

Parameters

KEY	VALUE type	Required	Description
value	T_INT	O	ICX Amount in loop

Returns

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

EventLog

N/A

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setStake",
            "params": {
                "value": "0xde0b6b3a7640000"
            }
        },
        ...
    }
}

getStake

• Returns the stake status of a given address

Parameters

KEY	VALUE type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

KEY	VALUE type	Required	Description
stake	T_INT	O	ICX amount of stake in loop
unstakes	T_LIST[T_DICT]	X	Unstake info list
unstakes.unstake	T_INT	X	ICX amount of unstake in loop
unstakes.unstakeBlockHeight	T_INT	X	BlockHeight when unstake will be done
unstakes.remainingBlocks	T_INT	X	The number of remaining blocks to reach unstakeBlockHeight

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "getStake",
            "params": {
                "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        }
    }
}

Response on success

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "stake": "0x4e1003b28d9280000",
        "unstakes": [
          {
              "unstake": "0x8ac7230489e80000",
              "unstakeBlockHeight": "0x19",
              "remainingBlocks": "0x11"
          }
        ]
    }
}

Response on success when there is no unstake

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "stake": "0xde0b6b3a7640000"
    }
}

setDelegation

• Delegate some ICX amount of stake to P-Reps
• Maximum number of P-Reps to delegate is 10
• The transaction which has duplicated P-Rep addresses will be failed
• This transaction overwrites the previous delegate information

Parameters

KEY	VALUE type	Required	Description
delegations	T_LIST(T_DICT)	O	List of delegation dict (Max: 10 entries)
delegations.address	T_ADDR_EOA	O	Address of P-Rep to delegate
delegations.value	T_INT	O	Delegation amount in loop

Returns

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

EventLog

N/A

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setDelegation",
            "params": {
                "delegations": [
                    {
                        "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
                        "value": "0x3200000000"
                    },
                    {
                        "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
                        "value": "0x1000000000"
                    }
                ]
            }
        },
        ...
    }
}

Request to revoke all delegations

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setDelegation",
            "params": {
                "delegations": []
            }
        },
        ...
    }
}

getDelegation

• Returns the delegation status of a given address

Parameters

KEY	VALUE type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

KEY	VALUE type	Required	Description
delegations	T_LIST(T_DICT)	O	List of delegation dict (Max: 10 entries)
delegation.address	T_ADDR_EOA	X	P-Rep address
delegation.value	T_INT	O	Delegation amount in loop
delegation.status	T_INT	O	0: active 1: Unregistered
totalDelegated	T_INT	O	The sum of delegation amount
votingPower	T_INT	O	Remaining amount of stake that ICONist can delegate to other P-Reps

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "getDelegation",
            "params": {
                "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        }
    }
}

Response on success

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "totalDelegated": "0xa688906bd8b0000",
        "votingPower": "0x3782dace9d90000",
        "delegations": [
            {
                "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
                "value": "0x3782dace9d90000",
            },
            {
                "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
                "value": "0x6f05b59d3b20000"
            }
        ]
    }
}

setBonderList

Set allowed bonder list to P-Rep

• Maximum number of allowed ICONists to bond is 10
• This transaction overwrites the previous bonder list information

Parameters

Key	VALUE Type	Required	Description
bonderList	T_LIST(T_ADDR_EOA,T_ADDR_SCORE)	O	List of address (MAX: 100 entries)

Example

Request

{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "icx_sendTransaction",
  "params": {
    "data": {
      "method": "setBonderList",
      "params": {
        "bonderList": [
          "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
          "cxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826"
        ]
      }
    },
    ...
  }
}

getBonderList

• Returns the allowed bonder list
• Maximum 10 entries are allowed

Parameters

Key	VALUE Type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

Key	VALUE Type	Required	Description
bonderList	T_LIST(T_ADDR_EOA,T_ADDR_SCORE)	O	List of address (MAX: 10 entries)

Example

Request

{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "icx_call",
  "params": {
    "to": "cx0000000000000000000000000000000000000000",
    "dataType": "call",
    "data": {
      "method": "getBonderList",
      "params": {
        "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
      }
    }
  }
}

Response on success

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": {
    "bonderList": [
      "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
      "cxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826"
    ]
  }
}

setBond

Bond some ICX amount of stake to P-Reps

• Maximum number of P-Reps to bond is 100
• The transaction which has duplicated P-Rep addresses will be failed
• This transaction overwrites the previous bond information

Parameters

Key	VALUE Type	Required	Description
bonds	T_LIST(T_DICT)	O	List of bond dict (MAX: 100 entries)
bonds.address	T_ADDR_EOA	O	Address of P-Rep to bond
bonds.value	T_INT	O	Bond amount in loop

Example

Request: Posts bonds to 2 P-Reps

{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "icx_sendTransaction",
  "params": {
    "data": {
      "method": "setBond",
      "params": {
        "bonds": [
          {
            "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
            "value": "0x3200000000"
          },
          {
            "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
            "value": "0x1000000000"
          }
        ]
      }
    },
    ...
  }
}

Request: Reset bonds

{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "icx_sendTransaction",
  "params": {
    "data": {
      "method": "setBond",
      "params": {
        "bonds": []
      }
    },
    ...
  }
}

getBond

Returns the bond status of a given address

Parameters

Key	VALUE Type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

Key	VALUE Type	Required	Description
totalBonded	T_INT	O	The sum of bond amount
votingPower	T_INT	O	Remaining amount of stake that ICONist can delegate and bond to other P-Reps
bonds	T_LIST(T_DICT)	O	List of bond dict
bonds.address	T_ADDR_EOA,T_ADDR_SCORE	X	Address of P-Rep to delegate
bonds.value	T_INT	X	Bond amount in loop
unbonds	T_LIST(T_DICT)	X	List of unbond dict
unbonds.address	T_ADDR_EOA,T_ADDR_SCORE	X	Address of P-Rep to delegate
unbonds.value	T_INT	X	Unbonding amount in loop
unbonds.expireBlockHeight	T_INT	X	BlockHeight when unBonding will be done

Example

Request

{
  "jsonrpc": "2.0",
  "id": 1234,
  "method": "icx_call",
  "params": {
    "to": "cx0000000000000000000000000000000000000000",
    "dataType": "call",
    "data": {
      "method": "getBond",
      "params": {
        "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
      }
    }
  }
}

Response on success

{
  "jsonrpc": "2.0",
  "id": 1234,
  "result": {
    "totalBonded": "0xa688906bd8b0000",
    "votingPower": "0x3782dace9d90000",
    "bonds": [
      {
        "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
        "value": "0x3782dace9d90000"
      },
      {
        "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
        "value": "0x6f05b59d3b20000"
      }
    ],
    "unbonds": [
      {
        "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
        "value": "0x3782dace9d90000",
        "expireBlockHeight": "0xa"
      },
      {
        "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
        "value": "0x6f05b59d3b20000",
        "expireBlockHeight": "0xa"
      }
    ]
  }
}

claimIScore

• Claim the total reward that a ICONist has received

Parameters

N/A

Returns

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

EventLog

Name	Data type	Indexed	Description
IScoreClaimed(int,int)	String	O	Signature
IScore	T_INT	X	Reward amount in IScore
ICX	T_INT	X	ICX amount in loop

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "claimIScore"
        },
        ...
    }
}

The result of claimIScore transaction

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "status": "0x1",
        "to": "cx0000000000000000000000000000000000000000",
        "txHash": "0xb903239f8543d04b5d...",
        "txIndex": "0x1",
        "blockHeight": "0x1234",
        "blockHash": "0xc71303ef8543d04b5d...",
        "cumulativeStepUsed": "0x1234",
        "stepUsed": "0x1234",
        "stepPrice": "0x2540be400",
        "eventLogs":[
            {
                "scoreAddress": "cx0000000000000000000000000000000000000000",
                "indexed": [
                    "IScoreClaimed(int,int)"
                ],
                "data":[
                    "0x186a0",
                    "0x64"
                ]
            }
        ],
        "logsBloom":"0x0000000000000..."
    }
}

queryIScore

• Returns the amount of I-Score that a ICONist has received as a reward

Parameters

KEY	VALUE type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

KEY	VALUE type	Required	Description
blockHeight	T_INT	O	Block height when I-Score is estimated
iscore	T_INT	O	Amount of I-Score
estimatedICX	T_INT	O	Estimated amount in loop 1000 I-Score == 1 loop

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "queryIScore",
            "params": {
                "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        }
    }
}

Response on success

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "blockHeight": "0xe3d2",
        "iscore": "0x3e8",
        "estimatedICX": "0x1"
    }
}

registerPRep

• Register an address as a P-Rep to Blockchain
• 2000 ICX are required as a registration fee
• Empty string is not allowed for every field

Parameters

KEY	VALUE type	Required	Description
name	String	O	P-Rep name "ABC Node"
email	String	O	P-Rep email "[email protected]"
country	String	O	ISO 3166-1 alpha-3 "KOR", "USA", "CHN"
city	String	O	"Seoul", "New York", "Paris"
website	String	O	P-Rep homepage url "https://abc.example.com/"
details	String	O	Url including P-Rep detail information "https://abc.example.com/details/"
p2pEndpoint	String	O	Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100"
nodeAddress	String	X	Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"

*details : See JSON Standard for P-Rep Detailed Information

Returns

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

EventLog

Name	Data type	Indexed	Description
PRepRegistered(Address)	String	O	Signature
Address	Address	X	P-Rep address

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "value": "0x6c6b935b8bbd400000",
        "data": {
            "method": "registerPRep",
            "params": {
                "name": "ABC Node",
                "country": "KOR",
                "city": "Seoul",
                "email": "[email protected]",
                "website": "https://abc.example.com/",
                "details": "https://abc.example.com/details/",
                "p2pEndpoint": "abc.example.com:7100",
                "nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        },
        ...
    }
}

unregisterPRep

• Unregister a P-Rep

Parameters

N/A

Returns

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

EventLog

Name	Data type	Indexed	Description
PRepUnregistered(Address)	String	O	Signature
Address	Address	X	P-Rep address

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "unregisterPRep"
        },
        ...
    }
}

setPRep

• Update P-Rep register information
• Add the only fields which you want to change

Parameters

KEY	VALUE type	Required	Description
name	String	X	P-Rep name "ABC Node"
email	String	X	P-Rep email "[email protected]"
country	String	X	ISO 3166-1 alpha-3 "KOR", "USA", "CHN"
city	String	X	"Seoul", "New York", "Paris"
website	String	X	P-Rep homepage url "https://abc.example.com/"
details	String	X	Url including P-Rep detail information "https://abc.example.com/details/"
nodeAddress	String	X	Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"

*details : See JSON Standard for P-Rep Detailed Information

Returns

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

EventLog

Name	Data type	Indexed	Description
PRepSet(Address)	String	O	Signature
Address	Address	X	P-Rep address

Example

Request in case when you want to change name, email and nodeAddress

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setPRep",
            "params": {
                "name": "Banana Node",
                "email": "[email protected]",
                "nodeAddress": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        },
        ...
    }
}

setGovernanceVariables

• Update governance variables
• Allowed only once in a term

Parameters

KEY	VALUE type	Required	Description
irep	T_INT	X	- Incentive rep used to calcualte the reward for P-Rep - Limit: +- 20% of the previous value - Unit: loop

Returns

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

EventLog

N/A

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setGovernanceVariables",
            "params": {
                "irep": "0x21e19e0c9bab2400000"
            }
        },
        ...
    }
}

getPRep

• Returns P-Rep register information

Parameters

KEY	VALUE type	Required	Description
address	T_ADDR_EOA	O	Address to query

Returns

KEY	VALUE type	Required	Description
status	T_INT	O	0: active 1: unregistered 2: disqualified
penalty	T_INT	O	0: none 1: disqualification 2: low productivity 3: block validation failure
grade	T_INT	O	0: Main P-Rep 1: Sub P-Rep 2: P-Rep candidate
name	String	O	P-Rep name "ABC Node", "Banana Node"
email	String	O	P-Rep email "[email protected]"
country	String	O	ISO 3166-1 alpha-3 "KOR", "USA", "CHN"
city	String	O	"Seoul", "New York", "Paris"
website	String	O	P-Rep homepage url "https://abc.example.com/"
details	String	O	Url including P-Rep detail information "https://abc.example.com/details/"
nodeAddress	String	O	Node Key for only consensus "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
stake	T_INT	O	Amount of stake that a P-Rep has
bonded	T_INT	O	Bond amount that a P-Rep receives from ICONists
delegated	T_INT	O	Delegation amount that a P-Rep receives from ICONists
power	T_INT	O	P-Rep ranking score. power = min(bonded * 20, bonded + delegated) See this(https://icondev.io/introduction/icon-key-concepts/governance-iiss#bond-requirement) for more details.
totalBlocks	T_INT	O	The number of blocks that a P-Rep received when running as a Main P-Rep
validatedBlocks	T_INT	O	The number of blocks that a P-Rep validated when running as a Main P-Rep
lastHeight	T_HASH	O	The last height of the block which this P-Rep validated as a validator
irep	T_INT	X	(deprecated) Incentive rep used to calculate the reward for P-Rep Limit: +- 20% of the previous value Unit: loop
irepUpdateBlockHeight	T_INT	X	(deprecated) Block height when a P-Rep changed I-Rep value
p2pEndpoint	String	X	(deprecated) Network info used for connecting among P-Rep nodes "123.45.67.89:7100", "node.example.com:7100"

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "getPRep",
            "params": {
                "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
            }
        }
    }
}

Response on success

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "grade": "0x0",
        "status": "0x0",
        "penalty": "0x0",
        "bonded": "0x0",
        "stake": "0x28a857425466f800000",
        "delegated": "0xb390f6390fef898000",
        "power": "0xb390f6390fef898000",
        "name": "Banana node",
        "country": "KOR",
        "city": "Seoul",
        "details": "https://banana.com/detail.json",
        "website": "https://banana.com/index.html",
        "address": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
        "nodeAddress": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
        "irep": "0xc350",
        "irepUpdateBlockHeight": "0x1200",
        "lastHeight": "0x3456",
        "totalBlocks": "0x2710",
        "validatedBlocks": "0x2328"
        "p2pEndpoint": "1.2.3.4:7100",
    }
}

Response on failure

{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32006,
        "message": "P-Rep not found: hxe7af5fcfd8dfc67530a01a0e403882687528dfcb"
    }
}

getPReps

• Returns the status of all registered P-Rep candidates in descending order by delegated ICX amount
• Unregistered or disqualified P-Reps are not included

Parameters

KEY	VALUE type	Required	Description
startRanking	T_INT	X	Default: 1 P-Rep list which starts from start ranking
endRanking	T_INT	X	Default: the last ranking

Returns

KEY	VALUE type	Required	Description
blockHeight	T_INT	O	The latest block height when this request was processed
startRanking	T_INT	O	Start ranking of P-Rep list
totalDelegated	T_INT	O	Total delegation amount that all P-Reps receive
totalStake	T_INT	O	The sum of ICX that all ICONists stake
preps	T_LIST(T_DICT)	O	P-Rep list. See getPRep for P-Rep attributes.

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "getPReps",
            "params": {
                "startRanking" : "0x1",
                "endRanking": "0xa"
            }
        }
    }
}

Response

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "blockHeight": "0x1234",
        "startRanking": "0x1",
        "totalDelegated": "0x2863c1f5cdae42f9540000000",
        "totalStake": "0x193e5939a08ce9dbd480000000",
        "preps": [
            {
                "grade": "0x0",
                "status": "0x0",
                "penalty": "0x0",
                "bonded": "0x0",
                "stake": "0x28a857425466f800000",
                "delegated": "0xb390f6390fef898000",
                "power": "0xb390f6390fef898000",
                "name": "Banana node",
                "country": "KOR",
                "city": "Seoul",
                "details": "https://banana.com/detail.json",
                "website": "https://banana.com/index.html",
                "address": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
                "nodeAddress": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
                "irep": "0xc350",
                "irepUpdateBlockHeight": "0x1200",
                "lastHeight": "0x1",
                "totalBlocks": "0x2710",
                "validatedBlocks": "0x2328"
                "p2pEndpoint": "1.2.3.4:7100",
            },
            {
                "grade": "0x0",
                "status": "0x0",
                "penalty": "0x0",
                "bonded": "0x0",
                "stake": "0x28a857425466f800000",
                "delegated": "0xb390f6390fef898000",
                "power": "0xb390f6390fef898000",
                "name": "ABC Node",
                "country": "USA",
                "city": "New York",
                "details": "https://comcom.ai/detail.json",
                "email": "[email protected]",
                "address": "hx12abcdef628ee52a7f751e9d500a79222a7f4567",
                "nodeAddress": "hx37ff490d628ee52a7f751e9d500a79222a7fe568",
                "irep": "0xc350",
                "irepUpdateBlockHeight": "0x1100",
                "lastHeight": "0x1200",
                "totalBlocks": "0x2720",
                "validatedBlocks": "0x2348",
                "p2pEndpoint": "1.2.3.4:7100",
            },
            ...
        ]
    }
}

getScoreOwner

• Returns the owner of the score indicated by a given address

Parameters

KEY	VALUE type	Required	Description
score	T_ADDRESS	O	score address to query

Returns

• owner address of a given score

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_call",
    "params": {
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "getScoreOwner",
            "params": {
                "score": "cx8d3ef83a63d8bbd3f08c4a8b8a18fbae13368b40"
            }
        },
    }
}

Response on success

{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": "hx3ece50aaa01f7c4d128c029d569dd86950c34215"
}

Response on failure

{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -30006,
        "message": "SystemError(-30006): E0006:Invalid score address"
    }
}

setScoreOwner

• Changes the owner of the score indicated by a given address
• Only the score owner can change its owner.
• If a score owner changes its owner to hx0000000000000000000000000000000000000000, it means that the score is frozen and no one can update or modify it anymore.
• score address can also be used as a score owner.
• A score itself can be set to its owner.

Parameters

KEY	VALUE type	Required	Description
score	T_ADDRESS	O	score address to change its owner
owner	T_ADDRESS	O	new owner address of a given score

Returns

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

Example

Request

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        ...
        "to": "cx0000000000000000000000000000000000000000",
        "dataType": "call",
        "data": {
            "method": "setScoreOwner",
            "params": {
                "score": "cx8d3ef83a63d8bbd3f08c4a8b8a18fbae13368b40",
                "owner": "hx3ece50aaa01f7c4d128c029d569dd86950c34215"
            }
        }
    }
}

References

• JSON-RPC 2.0 Specification
• JSON Standard for P-Rep Detailed Information