Skip to content
Permalink
Branch: master
Find file Copy path
Fetching contributors…
Cannot retrieve contributors at this time
1206 lines (1027 sloc) 36.2 KB

ICON JSON-RPC API v3

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

API Convention

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

JSON-RPC Error Response

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

JSON-RPC API v3 ChangeLog

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

JSON-RPC APIs

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

Main API

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

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
    • type : function, fallback, or eventlog
    • name : function name
    • inputs : parameters in array
      • name : parameter name
      • type : parameter type (int, str, bytes, bool, Address)
      • indexed : 0x1 if the parameter is indexed (when this is eventlog)
    • outputs : return value
      • type : return value type (int, str, bytes, bool, Address, dict, list)
    • readonly : 0x1 if this is declared as external(readonly=True)
    • payable : 0x1 if this has payable decorator

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getScoreApi",
    "id": 1234,
    "params": {
        "address": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32"  // SCORE address
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": [
        {
            "type": "function",
            "name": "balanceOf",
            "inputs": [
                {
                    "name": "_owner",
                    "type": "Address"
                }
            ],
            "outputs": [
                {
                    "type": "int"
                }
            ],
            "readonly": "0x1"
        },
        {
            "type": "eventlog",
            "name": "FundTransfer",
            "inputs": [
                {
                    "name": "backer",
                    "type": "Address",
                    "indexed": "0x1"
                },
                {
                    "name": "amount",
                    "type": "int",
                    "indexed": "0x1"
                },
                {
                    "name": "is_contribution",
                    "type": "bool",
                    "indexed": "0x1"
                }
            ]
        },
        {...}
    ]
}

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

icx_getTotalSupply

  • Returns total ICX coin supply that has been issued.

Parameters

None

Returns

Total number of ICX coins issued.

Example

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

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

icx_getTransactionResult

  • Returns the transaction result requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

KEY VALUE type Description
status T_INT 1 on success, 0 on failure.
to T_ADDR_EOA or T_ADDR_SCORE Recipient address of the transaction
failure T_DICT This field exists when status is 0. Contains code(str) and message(str).
txHash T_HASH Transaction hash
txIndex T_INT Transaction index in the block
blockHeight T_INT Height of the block that includes the transaction.
blockHash T_HASH Hash of the block that includes the transation.
cumulativeStepUsed T_INT Sum of stepUsed by this transaction and all preceeding transactions in the same block.
stepUsed T_INT The amount of step used by this transaction.
stepPrice T_INT The step price used by this transaction.
scoreAddress T_ADDR_SCORE SCORE address if the transaction created a new SCORE. (optional)
eventLogs T_ARRAY Array of eventlogs, which this transaction generated.
logsBloom T_BIN_DATA Bloom filter to quickly retrieve related eventlogs.

Example

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

// Response - success
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "status": "0x1",
        "to": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
        "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "txIndex": "0x1",
        "blockHeight": "0x1234",
        "blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "cumulativeStepUsed": "0x1234",
        "stepUsed": "0x1234",
        "stepPrice": "0x5678",
        "scoreAddress": "cxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
        "eventLogs":[
            {
                "scoreAddress": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
                "indexed": [
                    "Transfer(Address,Address,int)",
                    "hx4873b94352c8c1f3b2f09aaeccea31ce9e90bd31",
                    "hx0000000000000000000000000000000000000000",
                    "0x8ac7230489e80000"
                ],
                "data":[]
            }
        ],
        "logsBloom":"0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000000000000000000000000000000000000000000000000000020000000000000000000000000000000000000000000000000002000000000021000000000000000000000000000000000000000000000000003000000000031400000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000200000000000000"
    }
}

// Response - failed tx
{
    "jsonrpc": "2.0",
    "id": 1234,
    "result": {
        "status": "0x0",
        "failure": {
            "code": "0x7d00",
            "message": "Out of balance"
        },
        "to": "cx4d6f646441a3f9c9b91019c9b98e3c342cceb114",
        "txHash": "0xb903239f8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "txIndex": "0x1",
        "blockHeight": "0x1234",
        "blockHash": "0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238",
        "cumulativeStepUsed": "0x1234",
        "stepUsed": "0x1234",
        "stepPrice": "0x5678"
    }
}

// Response - error (invalid txHash was given)
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid txHash"
    }
}

// Response - pending tx
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Pending transaction"
    }
}

icx_getTransactionByHash

  • Returns the transaction information requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

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

ise_getStatus

  • Returns the status of iconservice

Parameters

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

Returns

T_DICT(String)

Example

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

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

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

icx_sendTransaction

You can do one of the followings using this function.

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

This function causes state transition.

Parameters

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

Parameters - data

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

dataType == call

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

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

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

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

It is used when transfering 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 ommitted, assumes 0. (1 icx = 1 ^ 18 loop)
timestamp T_INT required Transaction creation time. timestamp is in microsecond.
nid T_INT required Network ID ("0x1" for Mainnet, "0x2" for Testnet, etc)
nonce T_INT optional An arbitrary number used to prevent transaction hash collision.
dataType T_DATA_TYPE optional Type of data. (call, deploy, or message)
data T_DICT or String optional The content of data varies depending on the dataType. See Parameters - data.

Returns

  • The amount of an estimated step

Example

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

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

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

rep_getList

  • Get all list of Representatives and information about terms & RepRootHash

Parameters

None

Returns

  • The list of Representatives of 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
}

References

You can’t perform that action at this time.