icondev

> hyperconnect the world _

ICON is a scalable smart contract enabled blockchain platform with a long-term goal of interoperability between enterprise and public blockchains. Our goal is to Hyperconnect the World, and by combining groundbreaking technology, a strong community, and relentless growth strategies we believe this goal is reachable.

Get Started     Subscribe to our mailing list

ICON JSON-RPC API v3 Specification

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

ICON JSON-RPC API v3 Specification

API Convention

Follows JSON-RPC 2.0 Specification.

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

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

// Response - error
{
    "jsonrpc": "2.0",
    "id": $INT1,
    "error": {
        "code": $INT2,
        "message": "$STRING"
    }
}
  • "KEY" naming follows camel case.

VALUE Types

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

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

Sub API

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

IISS API

Debug API

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

Other API

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

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

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
unstake T_INT X ICX amount of unstake in loop
unstakeBlockHeight T_INT X BlockHeight when unstake will be done
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": "0xde0b6b3a7640000",
        "unstake": "0xde0b6b3a7640000",
        "unstakeBlockHeight": "0xa",
        "blockHeight": "0x23e8"
    }
}

Response on success when there is no unstake

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

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

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
"abc@example.com"
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"

*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": "abc@example.com",
                "website": "https://abc.example.com/",
                "details": "https://abc.example.com/details/",
                "p2pEndpoint": "abc.example.com:7100"
            }
        },
        ...
    }
}

unregisterPRep

  • Unregister a P-Rep
  • CAUTION: Once you unregister an address, you will not be able to register the address again

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

Parameters

KEY VALUE type Required Description
name String X P-Rep name
"ABC Node"
email String X P-Rep email
"abc@example.com"
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/"
p2pEndpoint String X Network info used for connecting among P-Rep nodes
"123.45.67.89:7100", "node.example.com:7100"

*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

{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "icx_sendTransaction",
    "params": {
        "data": {
            "method": "setPRep",
            "params": {
                "name": "Banana Node",
                "email": "banana@email.com"
            }
        },
        ...
    }
}

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
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
"abc@example.com"
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"
irep T_INT O Incentive rep used to calculate the reward for P-Rep
Limit: +- 20% of the previous value
Unit: loop
irepUpdateBlockHeight T_INT O Block height when a P-Rep changed I-Rep value
lastGenerateBlockHeight T_INT O Height of the last block which a P-Rep generated
stake T_INT O Amount of stake that a P-Rep has
delegated T_INT O Delegation amount that a P-Rep receives from ICONists
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

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": {
        "status": "0x0",
        "grade": "0x2",
        "name": "banana",
        "country": "KOR",
        "city": "Seoul",
        "email": "banana@email.com",
        "website": "https://icon.banana.com",
        "details": "https://icon.banana.com/json",
        "p2pEndpoint": "123.45.67.89:7100",
        "irep": "0xa968163f0a57b400000",
        "irepUpdateBlockHeight": "0x847ea",
        "stake": "0x38372",
        "delegated": "0x74287392847",
        "totalBlocks": "0x83261e7",
        "validatedBlocks": "0x83258a9"
    }
}

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 O Default: 1
P-Rep list which starts from start ranking
endRanking T_INT O 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
preps.address String O P-Rep address
preps.grade T_INT O Refer to getPRep
preps.name String O Refer to getPRep
preps.country String O Refer to getPRep
preps.city String O Refer to getPRep
preps.stake T_INT O Refer to getPRep
preps.delegated T_INT O Refer to getPRep
preps.irep T_INT O Refer to getPRep
preps.irepUpdateBlockHeight T_INT O Refer to getPRep
preps.lastGenerateBlockHeight T_INT O Refer to getPRep
preps.totalBlocks T_INT O Refer to getPRep
preps.validatedBlocks T_INT O Refer to getPRep

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": [
            {
                "name": "Banana node",
                "country": "KOR",
                "city": "Seoul",
                "grade": "0x0",
                "address": "hx8f21e5c54f006b6a5d5fe65486908592151a7c57",
                "irep": "0xc350",
                "irepUpdateBlockHeight": "0x1200",
                "lastGenerateBlockHeight": "-0x1",
                "stake": "0x21e19e0c9bab2400000",
                "delegated": "0x204fce5e3e25026110000000",
                "totalBlocks": "0x2710",
                "validatedBlocks": "0x2328"
            },
            {
                "name": "ABC Node",
                "country": "USA",
                "city": "New York",
                "grade": "0x0",
                "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
                "irep": "0xc350",
                "irepUpdateBlockHeight": "0x1100",
                "lastGenerateBlockHeight": "0x1200",
                "stake": "0x28a857425466f800000",
                "delegated": "0x9ed194db19b238c000000",
                "totalBlocks": "0x2720",
                "validatedBlocks": "0x2348"
            },
            ...
        ]
    }
}

References

Updated 2 months ago

ICON JSON-RPC API v3 Specification


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.