ICON Developer Portal

ICON Developer Portal

ICON Network is a decentralized smart contract protocol based on ‘loopchain’, a high-performance blockchain engine. The ICON Network aims to remove barriers among different blockchains and allow them to exchange values without intermediaries. By realizing this goal, ICON will realize the mass adoption of blockchain technology and Hyperconnect the World.

Get Started

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 typeDescriptionExample
T_ADDR_EOA"hx" + 40 digit HEX stringhxbe258ceb872e08851f1f59694dac2558708ece11
T_ADDR_SCORE"cx" + 40 digit HEX stringcxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32
T_HASH"0x" + 64 digit HEX string0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238
T_INT"0x" + lowercase HEX string0xa
T_BIN_DATA"0x" + lowercase HEX string. Length must be even.0x34b2
T_SIGbase64 encoded stringVAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=
T_DATA_TYPEType of datacall, 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 codeMessageDescription
-32700Parse errorInvalid JSON was received by the server. An error occurred on the server while parsing the JSON text.
-32600Invalid RequestThe JSON sent is not a valid Request object.
-32601Method not foundThe method does not exist / is not available.
-32602Invalid paramsInvalid method parameter(s).
-32603Internal errorInternal JSON-RPC error.
-32000Server errorIconServiceEngine internal error.
-32100Score errorScore 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

KEYVALUE typeDescription
heightT_INTInteger 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

KEYVALUE typeDescription
hashT_HASHHash 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

KEYVALUE typeDescription
fromT_ADDR_EOAMessage sender's address.
toT_ADDR_SCORESCORE address that will handle the message.
dataTypeT_DATA_TYPEcall is the only possible data type.
dataT_DICTSee Parameters - data.
data.methodStringName of the function.
data.paramsT_DICTParameters 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

KEYVALUE typeDescription
addressT_ADDR_EOA or T_ADDR_SCOREAddress 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

KEYVALUE typeDescription
addressT_ADDR_SCORESCORE adress to be examined.

Returns

Fields containing information about the function

KEYVALUE typeDescription
typeStringfunction, fallback, or eventlog
nameStringfunction name
inputsT_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)
outputsT_LIST(T_DICT)return value
- type : return value type (int, str, bytes, bool, Address, dict, list)
readonlyT_INT0x1 if this is declared as external(readonly=True)
payableT_INT0x1 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

KEYVALUE typeDescription
txHashT_HASHHash of the transaction

Returns

KEYVALUE typeDescription
statusT_INT0x1 on success, 0x0 on failure.
toT_ADDR_EOA or T_ADDR_SCORERecipient address of the transaction
failureT_DICTThis field exists when status is 0x1. Contains code(string) and message(string).
txHashT_HASHTransaction hash
txIndexT_INTTransaction index in the block
blockHeightT_INTHeight of the block that includes the transaction.
blockHashT_HASHHash of the block that includes the transation.
cumulativeStepUsedT_INTSum of stepUsed by this transaction and all preceeding transactions in the same block.
stepUsedT_INTThe amount of step used by this transaction.
stepPriceT_INTThe step price used by this transaction.
scoreAddressT_ADDR_SCORESCORE address if the transaction created a new SCORE. (optional)
eventLogsT_ARRAYArray of eventlogs, which this transaction generated.
logsBloomT_BIN_DATABloom 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

KEYVALUE typeDescription
txHashT_HASHHash of the transaction

Returns

KEYVALUE typeDescription
versionT_INTProtocol version (0x3 for V3)
fromT_ADDR_EOAEOA address that created the transaction
toT_ADDR_EOA or T_ADDR_SCOREEOA address to receive coins, or SCORE address to execute the transaction.
valueT_INTAmount of ICX coins in loop to transfer. When ommitted, assumes 0. (1 icx = 1 ^ 18 loop)
stepLimitT_INTMaximum step allowance that can be used by the transaction.
timestampT_INTTransaction creation time. timestamp is in microsecond.
nidT_INTNetwork ID
nonceT_INTAn arbitrary number used to prevent transaction hash collision.
txHashT_HASHTransaction hash
txIndexT_INTTransaction index in a block. Null when it is pending.
blockHeightT_INTBlock height where this transaction was in. Null when it is pending.
blockHashT_HASHHash of the block where this transaction was in. Null when it is pending.
signatureT_SIGSignature of the transaction.
dataTypeT_DATA_TYPEType of data. (call, deploy, or message)
dataT_DICT or StringContains 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

KEYVALUE typeRequiredDescription
versionT_INTrequiredProtocol version (0x3 for V3)
fromT_ADDR_EOArequiredEOA address that created the transaction
toT_ADDR_EOA or T_ADDR_SCORErequiredEOA address to receive coins, or SCORE address to execute the transaction.
valueT_INToptionalAmount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
stepLimitT_INTrequiredMaximum step allowance that can be used by the transaction.
timestampT_INTrequiredTransaction creation time. timestamp is in microsecond.
nidT_INTrequiredNetwork ID (0x1 for Mainnet, 0x2 for Testnet, etc)
nonceT_INToptionalAn arbitrary number used to prevent transaction hash collision.
signatureT_SIGrequiredSignature of the transaction.
dataTypeT_DATA_TYPEoptionalType of data. (call, deploy, or message)
dataT_DICT or StringoptionalThe 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.

KEYVALUE typeRequiredDescription
methodStringrequiredName of the function to invoke in SCORE
paramsT_DICToptionalFunction parameters

2. dataType == deploy

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

KEYVALUE typeRequiredDescription
contentTypeStringrequiredMime-type of the content
contentT_BIN_DATArequiredCompressed SCORE data
paramsT_DICToptionalFunction 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
KEYVALUE typeRequiredDescription
versionT_INTrequiredProtocol version (0x3 for V3)
fromT_ADDR_EOArequiredEOA address that created the transaction
toT_ADDR_EOA or T_ADDR_SCORErequiredEOA address to receive coins, or SCORE address to execute the transaction.
valueT_INToptionalAmount of ICX coins in loop to transfer. When omitted, assumes 0. (1 icx = 1 ^ 18 loop)
timestampT_INTrequiredTransaction creation time. timestamp is in microsecond.
nidT_INTrequiredNetwork ID (0x1 for Mainnet, 0x2 for Testnet, etc)
nonceT_INToptionalAn arbitrary number used to prevent transaction hash collision.
dataTypeT_DATA_TYPEoptionalType of data. (call, deploy, or message)
dataT_DICT or StringoptionalThe 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

KEYVALUE typeDescription
filterT_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

KEYVALUE typeRequiredDescription
valueT_INTOICX 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

KEYVALUE typeRequiredDescription
addressT_ADDR_EOAOAddress to query

Returns

KEYVALUE typeRequiredDescription
stakeT_INTOICX amount of stake in loop
unstakeT_INTXICX amount of unstake in loop
unstakeBlockHeightT_INTXBlockHeight when unstake will be done
remainingBlocksT_INTXThe 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

KEYVALUE typeRequiredDescription
delegationsT_LIST(T_DICT)OList of delegation dict (Max: 10 entries)
delegations.addressT_ADDR_EOAOAddress of P-Rep to delegate
delegations.valueT_INTODelegation 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

KEYVALUE typeRequiredDescription
addressT_ADDR_EOAOAddress to query

Returns

KEYVALUE typeRequiredDescription
delegationsT_LIST(T_DICT)OList of delegation dict (Max: 10 entries)
delegation.addressT_ADDR_EOAXP-Rep address
delegation.valueT_INTODelegation amount in loop
delegation.statusT_INTO0: active
1: Unregistered
totalDelegatedT_INTOThe sum of delegation amount
votingPowerT_INTORemaining 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

NameData typeIndexedDescription
IScoreClaimed(int,int)StringOSignature
IScoreT_INTXReward amount in IScore
ICXT_INTXICX 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

KEYVALUE typeRequiredDescription
addressT_ADDR_EOAOAddress to query

Returns

KEYVALUE typeRequiredDescription
blockHeightT_INTOBlock height when I-Score is estimated
iscoreT_INTOAmount of I-Score
estimatedICXT_INTOEstimated 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

KEYVALUE typeRequiredDescription
nameStringOP-Rep name
"ABC Node"
emailStringOP-Rep email
"[email protected]"
countryStringOISO 3166-1 alpha-3
"KOR", "USA", "CHN"
cityStringO"Seoul", "New York", "Paris"
websiteStringOP-Rep homepage url
"https://abc.example.com/"
detailsStringOUrl including P-Rep detail information
"https://abc.example.com/details/"
p2pEndpointStringONetwork 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

NameData typeIndexedDescription
PRepRegistered(Address)StringOSignature
AddressAddressXP-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"
            }
        },
        ...
    }
}

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

NameData typeIndexedDescription
PRepUnregistered(Address)StringOSignature
AddressAddressXP-Rep address

Example

Request

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

setPRep

  • Update P-Rep register information

Parameters

KEYVALUE typeRequiredDescription
nameStringXP-Rep name
"ABC Node"
emailStringXP-Rep email
"[email protected]"
countryStringXISO 3166-1 alpha-3
"KOR", "USA", "CHN"
cityStringX"Seoul", "New York", "Paris"
websiteStringXP-Rep homepage url
"https://abc.example.com/"
detailsStringXUrl including P-Rep detail information
"https://abc.example.com/details/"
p2pEndpointStringXNetwork 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

NameData typeIndexedDescription
PRepSet(Address)StringOSignature
AddressAddressXP-Rep address

Example

Request

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

setGovernanceVariables

  • Update governance variables
  • Allowed only once in a term

Parameters

KEYVALUE typeRequiredDescription
irepT_INTX- 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

KEYVALUE typeRequiredDescription
addressT_ADDR_EOAOAddress to query

Returns

KEYVALUE typeRequiredDescription
statusT_INTO0: active
1: unregistered
gradeT_INTO0: Main P-Rep
1: Sub P-Rep
2: P-Rep candidate
nameStringOP-Rep name
"ABC Node", "Banana Node"
emailStringOP-Rep email
"[email protected]"
countryStringOISO 3166-1 alpha-3
"KOR", "USA", "CHN"
cityStringO"Seoul", "New York", "Paris"
websiteStringOP-Rep homepage url
"https://abc.example.com/"
detailsStringOUrl including P-Rep detail information
"https://abc.example.com/details/"
p2pEndpointStringONetwork info used for connecting among P-Rep nodes
"123.45.67.89:7100", "node.example.com:7100"
irepT_INTOIncentive rep used to calculate the reward for P-Rep
Limit: +- 20% of the previous value
Unit: loop
irepUpdateBlockHeightT_INTOBlock height when a P-Rep changed I-Rep value
lastGenerateBlockHeightT_INTOHeight of the last block which a P-Rep generated
stakeT_INTOAmount of stake that a P-Rep has
delegatedT_INTODelegation amount that a P-Rep receives from ICONists
totalBlocksT_INTOThe number of blocks that a P-Rep received when running as a Main P-Rep
validatedBlocksT_INTOThe 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": "[email protected]",
        "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

KEYVALUE typeRequiredDescription
startRankingT_INTODefault: 1
P-Rep list which starts from start ranking
endRankingT_INTODefault: the last ranking

Returns

KEYVALUE typeRequiredDescription
blockHeightT_INTOThe latest block height when this request was processed
startRankingT_INTOStart ranking of P-Rep list
totalDelegatedT_INTOTotal delegation amount that all P-Reps receive
totalStakeT_INTOThe sum of ICX that all ICONists stake
prepsT_LIST(T_DICT)OP-Rep list
preps.addressStringOP-Rep address
preps.gradeT_INTORefer to getPRep
preps.nameStringORefer to getPRep
preps.countryStringORefer to getPRep
preps.cityStringORefer to getPRep
preps.stakeT_INTORefer to getPRep
preps.delegatedT_INTORefer to getPRep
preps.irepT_INTORefer to getPRep
preps.irepUpdateBlockHeightT_INTORefer to getPRep
preps.lastGenerateBlockHeightT_INTORefer to getPRep
preps.totalBlocksT_INTORefer to getPRep
preps.validatedBlocksT_INTORefer 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 10 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.