Json rpc коды ошибок

JSON-RPC_2_0_Спецификация.txt. GitHub Gist: instantly share code, notes, and snippets.
JSON-RPC 2.0 Спецификация Дата создания: 2010-03-26 (в зависимости от версии 2009-05-24) Обновлено: 2013-01-04 Автор: Рабочая группа JSON-RPC <json-rpc@googlegroups.com> Содержание Обзор Соглашения Совместимость Объект запроса Уведомление Параметр структуры Объект для ответа Объект для ошибки Пакет Примеры Расширения 1 Обзор JSON-RPC является не сохраняющий состояния, легковесный протокол удаленного вызова процедур (RPC). В первую очередь это спецификация определяет некоторые структуры данных и правила их обработки. Это трансцендентное средство передачи, принципы которого могут использоваться одинаково поверх сокетов, протокола HTTP, или других различных сред передачи сообщений. В качестве формата данных использует JSON (RFC 4627) . Он создан, чтобы быть простым! 2 Соглашения Ключевые слова «ДОЛЖЕН», «НЕ ДОЛЖЕН», «ТРЕБУЕМЫЙ», «ДОЛЖНО БЫТЬ», «НЕ ДОЛЖНО БЫТЬ», «РЕКОМЕНДОВАНО», «ВОЗМОЖНО», и «НЕ ОБЯЗАТЕЛЬНО» в этом документе должны интерпретироваться, как описано в RFC 2119. Так как JSON-RPC использует JSON, он имеет такие же типы данных (см http://www.json.org или RFC 4627). JSON может представлять четыре простых типа (строки, числа, логические и NULL) и два структурированных типа (объекты и массивы). Термин «простые» в данном описании ссылаются на любой из этих четырех простых типов JSON. Термин «структурированные» ссылается на структурированные типы JSON. Всякий раз, когда этот документ относится к любому типу JSON, первая буква всегда пишется с большой: Object, Array, String, Number, Boolean, Null. True и False также прописные. Все имена, которыми обмениваются клиент и сервер, которые рассматриваются для любого рода сравнения, должны рассматриваться с учетом регистра. Термины функция, метод и процедура можно считать взаимозаменяемыми. Клиент определяется как источник объектов запроса и обработчик объектов ответа. Сервер определяется как источник объектов ответа и обработчик объектов запроса. Одно реализация этой спецификации могла бы легко исполнять обе из тех ролей, даже в одно и тоже время, другим различным клиентам или тому же самому клиенту. Эта спецификация не обращается к тому слою сложности. 3 Совместимость Объекты запросов и ответов JSON-RPC 2.0 возможно не смогут работать с существующими JSON-RPC 1.0 клиентами или серверами. Тем не менее, легко различать две версии, элементы 2,0 всегда имеют приставку «jsonrpc» со значением «2.0» в то время как 1,0 не имеет этого. Большинство реализаций 2.0 должно попытаться обработать 1.0 объекты, даже если не равнозначны и нет намеков на аспекты класса 1.0. 4 Объекта Запроса RPC вызов осуществляется ​​путем отправки объекта запроса серверу. Объект запроса имеет следующие элементы: jsonrpc Строка, определяющая версию протокола JSON-RPC. Должна быть со значением «2.0». method Строковый элемент, содержащий имя метода, который будет вызван. Имена методов, которые начинаются со слова RPC с последующей точкой (U + 002E или ASCII 46) зарезервированы для внутренних RPC-методов и расширений и НЕ ДОЛЖНЫ использоваться ни для чего другого. params Структура, имеет значения параметров, которые будут использоваться во время вызова метода. Этот элемент может быть опущен. id Идентификатор устанавливаемый Клиентом, который должен содержать строку, число или значение NULL, если он включен в элемент запроса. Если он не существует, предполагается, что это уведомление. Значение должно быть обычно не Null [1], цифры не должны содержат дробную часть [2] Сервер должен ответить тем же значением в объекте ответа, если идентификатор был включен в объект запроса. Этот элемент используется для связи контекста между двумя объектами. [1] Использование Null в качестве значения для элемента id в объект запроса вынужденная мера, потому что эта спецификация использует значение Null для ответов с неизвестной id. Кроме того, необходимо учитывать, что JSON-RPC 1.0 использует значение NULL для идентификатора уведомления, что может привести к путанице при обработке. [2] Дробные части могут создать проблемы, так как многие десятичные дроби не могут быть точно представлены как двоичные дроби. 4.1 Уведомление Уведомление это объект Запроса без элемента «id» . Объект Запроса, который является уведомлением означает отсутствие интереса Клиента в получении соответствующего объекта ответа, и, таким образом объект ответа не будет возвращен клиенту. Сервер не ДОЛЖЕН отвечать на Уведомление, включая на те, которые являются в рамках пакетного запроса. Уведомления не подтверждаемые по определению, так как у них нет объекта Ответа, который должен быть возвращен. К тому же, Клиент не должен быть оповещен ни о каких ошибках (как, например, «Недействительный параметр», «Внутренняя ошибка» 4.2 Структура параметра Если присутствуют параметры вызова RPC, они должны быть представлены в виде структурированного значения. Либо индексированы в массиве, либо по имени через объект. по-индексу: Параметры должны быть массивом, содержащий значения в ожидаемом сервером порядке. по имени: Параметры должны быть объектом, с именами членов, которые соответстветствовали бы ожидаемым сервером именам параметров. Отсутствие ожидаемых имен может привести к генерации ошибки . Имена должны в точности совпадать именам ожидаемых параметров метода. 5 Объект Ответа Когда вызов RPC сделан, сервер должен откликнуться с ответом, за исключением случая уведомления. Отклик выражается в виде одного объекта JSON, со следующими элементами: jsonrpc Строка, определяющая версию протокола JSON-RPC. Должна быть со значением «2.0». result Этот элемент является обязательным при успешном завершении. Этот элемент не должен быть, если произошла ошибка при вызове метода. Значение этого элемента определяется вызванным методом. error Этот элемент является обязательной в случае ошибки. Этот член не должен быть, если не было ошибок во время вызова. Значение этого элемента должно быть объектом, как определено в разделе 5.1. id Этот элемент является обязательным. Он должна быть таким же, как значение id элемента в объекте запроса. Если произошла ошибка при обнаружении идентификатора в объекте запроса (например, ошибка разбора / Неверный запрос), он должен быть в значении NULL. В любом случае ДОЛЖЕН быть включен либо элемент result либо элемент error, но не должны быть включены оба элемента. Объект 5.1 Ошибка Когда вызов RPC обнаруживает ошибку, объект ответа должен содержать элемент error со значением, которое является объектом со следующими членами: code Число, указывающее тип произошедщей ошибки. Это должно быть целое число. message Строка, предоставляющая краткое описание ошибки. Сообщение должно быть ограничено краткое одно предложение. data Простое или Структурированное значение, содержащее дополнительную информацию об ошибке. Это может быть опущенно. Значение этого элемента определяется на Сервере (например, подробные сведения об ошибке, вложенные ошибки и т.д.). Коды ошибок от -32768 до -32000 зарезервированы для предопределенных ошибок. Любой код в пределах этого диапазона, который не определен явно ниже, зарезервирован для будущего использования. Коды ошибок почти такие же, как те, что предлагаются для XML-RPC по адресу: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php Смысл кодов сообщение -32700 Ошибка разбора — Неверный JSON. Произошла ошибка на сервере во время разбора текста JSON. -32600 Неверный запрос JSON — отправлен не допустимый объект запроса. -32601 Метод не найден — метод не существует или не доступен. -32602 Неверные Параметры — Неверный параметры метода. -32603 Внутренняя ошибка — Внутренняя JSON-RPC ошибка. От -32000 до -32099 ошибка сервера Зарезервировано для реализации определенных ошибок сервера. Остальная часть промежутка кодов доступна для применения в приложении для определения ошибок. 6 Пакет Для отправки нескольких объектов запроса, за один раз, клиент может отправить массив заполненный объектами запросов. После того как все объекты массива были обработаны, Сервер должен ответить массивом ответов, содержащий соответствующие объекты отклика. Объекты ответа, должны соответствовать каждому объекту запроса, за исключением каких-либо объектов уведомлений, на которые не требутся ответа. Сервер может обрабатывать пакетный RPC вызов в виде набора параллельных задач, обработывать их в любом порядке и с любой шириной параллелизма. Объекты отклика возвращается из пакетного вызова в любом порядке следования в массиве. Клиент должен сравнивать контексты множества объектов запроса и объектов ответа, основываясь на id элемента внутри каждого объекта. Если при обработке пакетного RPC произойдет сбой распознавания на правильность JSON или массива по крайней мере с одним значением, отклик сервера должен содержать один объект ответа. Если вообще нет объектов ответа, содержащиеся в массиве, который должен быть отправлен клиенту, сервер НЕ ДОЛЖЕН возвращать пустой массив, и не обязан вообще ничего возвращать. 7 Примеры Синтаксис: -> Данные, отправленные на сервер <- Данные, передаваемые Клиенту RPC вызов с индексными параметрами: —> {«jsonrpc»: «2.0», «method»: «subtract», «params»: [42, 23], «id»: 1} <— {«jsonrpc»: «2.0», «result»: 19, «id»: 1} —> {«jsonrpc»: «2.0», «method»: «subtract», «params»: [23, 42], «id»: 2} <— {«jsonrpc»: «2.0», «result»: -19, «id»: 2} RPC вызов с именованными параметрами: —> {«jsonrpc»: «2.0», «method»: «subtract», «params»: {«subtrahend»: 23, «minuend»: 42}, «id»: 3} <— {«jsonrpc»: «2.0», «result»: 19, «id»: 3} —> {«jsonrpc»: «2.0», «method»: «subtract», «params»: {«minuend»: 42, «subtrahend»: 23}, «id»: 4} <— {«jsonrpc»: «2.0», «result»: 19, «id»: 4} уведомления: —> {«jsonrpc»: «2.0», «method»: «update», «params»: [1,2,3,4,5]} —> {«jsonrpc»: «2.0», «method»: «foobar»} RPC вызов несуществующего метода: —> {«jsonrpc»: «2.0», «method»: «foobar», «id»: «1»} <— {«jsonrpc»: «2.0», «error»: {«code»: -32601, «message»: «Method not found»}, «id»: «1»} RPC вызов с недопустимым JSON: —> {«jsonrpc»: «2.0», «method»: «foobar, «params»: «bar», «baz] <— {«jsonrpc»: «2.0», «error»: {«code»: -32700, «message»: «Parse error»}, «id»: null} RPC вызов с недопустимым объекта запроса: —> {«jsonrpc»: «2.0», «method»: 1, «params»: «bar»} <— {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null} Пакетный RPC вызов с недействительным JSON: —> [ {«jsonrpc»: «2.0», «method»: «sum», «params»: [1,2,4], «id»: «1»}, {«jsonrpc»: «2.0», «method» ] <— {«jsonrpc»: «2.0», «error»: {«code»: -32700, «message»: «Parse error»}, «id»: null} RPC вызов с пустой массив: —> [] <— {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null} Не верный RPC вызов (но не пустой): —> [1] <— [ {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null} ] Недопустимы пакетный RPC вызов : -> [1,2,3] <— [ {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null}, {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null}, {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null} ] Пакетный RPC вызов : —> [ {«jsonrpc»: «2.0», «method»: «sum», «params»: [1,2,4], «id»: «1»}, {«jsonrpc»: «2.0», «method»: «notify_hello», «params»: [7]}, {«jsonrpc»: «2.0», «method»: «subtract», «params»: [42,23], «id»: «2»}, {«foo»: «boo»}, {«jsonrpc»: «2.0», «method»: «foo.get», «params»: {«name»: «myself»}, «id»: «5»}, {«jsonrpc»: «2.0», «method»: «get_data», «id»: «9»} ] <— [ {«jsonrpc»: «2.0», «result»: 7, «id»: «1»}, {«jsonrpc»: «2.0», «result»: 19, «id»: «2»}, {«jsonrpc»: «2.0», «error»: {«code»: -32600, «message»: «Invalid Request»}, «id»: null}, {«jsonrpc»: «2.0», «error»: {«code»: -32601, «message»: «Method not found»}, «id»: «5»}, {«jsonrpc»: «2.0», «result»: [«hello», 5], «id»: «9»} ] Пакетный RPC вызов (все уведомления): —> [ {«jsonrpc»: «2.0», «method»: «notify_sum», «params»: [1,2,4]}, {«jsonrpc»: «2.0», «method»: «notify_hello», «params»: [7]} ] <- // Ничего не возвращается для всего пакета уведомлений 8 Расширения Имена методов, которые начинаются с RPC. зарезервированы для системных расширений, и НЕ ДОЛЖНЫ использоваться ни для чего другого. Каждое расширение системы определяется в соответствующей спецификации. Все системные расширения являются необязательными. Copyright (C) 2007-2010 по JSON-RPC Рабочей группы
Источник

ICON JSON-RPC API v3

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

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_PROOF_DATA {«left»: T_HASH} or {«right»: T_HASH} {«left»: «0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238» }
T_SIG base64 encoded string VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=
T_DATA_TYPE Type of data call, deploy, message or deposit

JSON-RPC Error Codes

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

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

Error Codes

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

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.
  • Append icx_getBlockReceipts API

JSON-RPC APIs

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

Main API

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

  • icx_getBlock
  • icx_getLastBlock
  • icx_getBlockByHeight
  • icx_getBlockByHash
  • icx_call
  • icx_getBalance
  • icx_getScoreApi
  • icx_getTotalSupply
  • icx_getTransactionResult
  • icx_getTransactionByHash
  • icx_getTransactionProof
  • icx_getReceiptProof
  • icx_proveTransaction
  • icx_proveReceipt
  • icx_sendTransaction
  • icx_getBlockReceipts

Debug API

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

  • debug_estimateStep
  • debug_getAccount

Other API

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

  • ise_getStatus
  • rep_getListByHash

JSON-RPC Methods

icx_getBlock

  • Returns the block information by given parameter.
  • Depcreated since 1.7.0, will be removed in ICON 2.0

Parameters

KEY VALUE type Description
hash T_HASH Hash of a block
height T_INT Integer of a block height
unconfirmed Boolean (optional) true or false, must be used with height parameter
None — Last block

Returns

Block data (including v0.3)

Example

// Request 1 - get last block
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234
}

// Request 2 - get block by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.3",
        "prevHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x51e030a24c5967047f8463c138024f857ec6663535df1f4e76e224f95abbe4b1",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5908392532c01",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x590839234a5de",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "9MhqZW4n9CtJXTKfDOiVsvZRuGQh9G3X9g3X3+4V2Fp8PcqGvkKHoAI4nJpAxGiJICiT7kgMqwQmvQ8ndGVXrgE="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x590839235367b",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "e2JNWDnNTulhksibVR2AV0/ZLLPwDfeOdq1A5DE/GAIPI56QR+78nV7I/eNHvFDzL6OcpN7D5/VZ5dfFBszB2QE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x590839235419f",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "mjhQSlSZhYuwLSqu+CbNDsiB4WTn8096RQ2EP89YPAVRita+bDuCBhyUkfZWhDqQPVW//sCwQD2GDXxNCC5dCgA="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x59083923541d1",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "o2OnbkaLK1rvGP+pDwrTo/+VV1Ag2/HuDeUV5aoReOhvmS4rOWLGuV00B5KZmE9GO7ZRHl32Ys0oSrj85ve3uAA="
            }
        ],
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "OPHFV8Zfyr//lP+SmKsr/RK3yawJDtolrfsdqDFKh3wxmyMh243zVp7CTLRu5wG5PdneX7mHzuLA9x41mqzjrAE=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}

// Request 4 - get block by height with unconfirmed
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x5",
        "unconfirmed": true
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.4",
        "prevHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x233f88d770fcca44b9c91ea6e55a4d981b858ea6f69830443811f73d32918f79",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5c8c877889b70",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x5c8c8776cd53d",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "/6LUAH8oWcVWvq3BMzQu/lujO7s5b5cY9ekVDxeIfVE9PFCKHr7ZHDkmhO01jPyg6ZP/XjB9rYTRyoWu1gVanQA="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x5c8c8777e4f88",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "oOoxPUH4UeE+6TBDfc65UjDn5NoxO5aCDY2k/wPENZROdu7piD7muxk/2Z022U63TYcRtbkd1I5lHiXibJnmWgE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x5c8c87783cbc1",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "WrzmUjN7YltUuTU7uPXomzkLgUQdecTZEaVmtx4bnpBa0WP4yfFwnYv1KllK1rD6rpOsvqc5wJlKH6qsacsbDAE="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x5c8c877877aa8",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "AzQb7B/0FcLcC8V/JdBa5Kv3I9J+daMAQq+bWZT2tsRy/xX5kK9vkeUXpWUpzjkgQdnMJWx9X88nclhz4nvWaAA="
            }
        ],
        "hash": "0x7febf336c2a68fb2c844f8b3b9f489d1baa7a5f4910e75d92a89384c9d75551a",
        "height": "0x5",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "bZQBqFO+7Cnsbhc4HdkTyz42MS0yB6q829P2aBL9lYkHKxbldSjPkXNoKcsdtr5Qx7f5pTNdCx93Mczighj6zAA=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}


// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "JSON schema validation error: 'params' has an invalid value"
    },
    "id": 1234
}

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)
      • default: the default value if the parameter has a default value (optional)
      • indexed : 0x1 if the parameter is indexed (when this is eventlog) (optional)
    • 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, message or deposit)
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_getTransactionProof

  • Returns the transaction proof requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

  • T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getTransactionProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_getReceiptProof

  • Returns the transaction receipt proof requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

  • T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getReceiptProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveTransaction

  • Returns the result of proving requested by transaction hash with its proof.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction
proof T_LIST(T_PROOF_DATA) List of proof data

Returns

  • T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveTransaction",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

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

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveReceipt

  • Returns the result of proving the receipt requested by transaction hash with its proof.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction
proof T_LIST(T_PROOF_DATA) List of proof data

Returns

  • T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveReceipt",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

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

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "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"
    }
}

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, message or deposit)
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 transferring a message, and data has a HEX string.

dataType == deposit

It is used when depositing ICX in SCORE or withdrawing the deposited ICX, and data has dictionary value as follows.

KEY VALUE type Required Description
action String required Name of the action (add or withdraw)
id String optional needed when withdrawing the deposited ICX

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

Deposit ICX to SCORE

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

Withdraw ICX from SCORE

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

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

debug_getAccount

  • Returns the Account information including stake, delegation of the given EOA or SCORE.

Parameters

KEY VALUE type Description
address T_ADDR_EOA or T_ADDR_SCORE Address of EOA or SCORE
filter T_INT flag value to what information will be included(coin : 1, stake: 2, delegation: 4)

Returns

Information of Account

Example

// Request
{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "debug_getAccount",
    "params": {
        "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
        "filter": "0x7"
    }
}

// Response - success
{
  "coin": {
    "type": "0x1",
    "typeStr": "CoinPartType.GENERAL",
    "flag": "0x0",
    "flagStr": "CoinPartFlag.None"
  },
  "stake": {
    "stake": "0x100",
    "unstake": "0x100",
    "unstakeBlockHeight": "0x200",
    "unstakesInfo": [
      [
        "0x100",
        "0x200"
      ]
    ]
  },
  "delegation": {
    "totalDelegated": "0xa688906bd8b0000",
    "delegations": [
      {
        "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
        "value": "0x3782dace9d90000"
      },
      {
        "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
        "value": "0x6f05b59d3b20000"
      }
    ]
  }
}

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

rep_getListByHash

  • Get all list of Representatives and information by RepsHash

Parameters

KEY VALUE type Required Description
repsHash T_HASH required root hash of representatives

Returns

  • The list of Representatives information by repsHash

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "rep_getListByHash",
    "id": 1234,
    "params": {
        "repsHash": "0x71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "address": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
            "p2pEndpoint": "127.0.0.1:7100"
        },
        {
            "address": "hx9f049228bade72bc0a3490061b824f16bbb74589",
            "p2pEndpoint": "127.0.0.1:7200"
        },
        {
            "address": "hx6435405122df9fe5187d659588beccdf7aee8557",
            "p2pEndpoint": "127.0.0.1:7300"
        },
        {
            "address": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
            "p2pEndpoint": "127.0.0.1:7400"
        }
    ],
    "id": 1234
}

icx_getBlockReceipts

  • Returns the block receipts by given parameter.

Parameters

KEY VALUE type Description
hash T_HASH Hash of a block
height T_INT Integer of a block height
None — Last block

Returns

Block Receipts data (including v0.3)

Example

// Request 1 - get last block receipts
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234
}

// Request 2 - get block receipts by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block receipts by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
		{
			"txHash": "4b9afccf0ce595fc67fd84959d8ff3107aad2e78ea418d8e115d39dbb5ddf683",
			"blockHeight": "0x696",
			"blockHash": "59415879e59977ac29bfa5dcfff3dfff2604beb0f1ba97d1944caf90b39d4c49",
			"txIndex": "0x0",
			"to": "hxe3d6d5d8e433fbd13b9c481d11cf46cebd84b23c",
			"stepUsed": "0x0",
			"stepPrice": "0x0",
			"cumulativeStepUsed": "0x0",
			"eventLogs": [
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"PRepIssued(int,int,int,int)"
					],
					"data": [
						"0xa968163f0a57b400000",
						"0x477",
						"0xd3e02419de2130fd07fe4",
						"0x20bd5ed6b99b1fcb"
					]
				},
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"ICXIssued(int,int,int,int)"
					],
					"data": [
						"0x0",
						"0x20bd5ed6b99b1fcb",
						"0x0",
						"0x53a06a5e791a89dbe"
					]
				}
			],
			"status": "0x1"
		}
	],
  "id": 1234
}

// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid params (only one parameter is allowed)"
    }
}

References

  • JSON-RPC 2.0 Specification
  • ICON JSON RPC API v2
Источник

ICON JSON-RPC API v3

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

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_PROOF_DATA {«left»: T_HASH} or {«right»: T_HASH} {«left»: «0xc71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238» }
T_SIG base64 encoded string VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA=
T_DATA_TYPE Type of data call, deploy, message or deposit

JSON-RPC Error Codes

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

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

Error Codes

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

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.
  • Append icx_getBlockReceipts API

JSON-RPC APIs

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

Main API

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

  • icx_getBlock
  • icx_getLastBlock
  • icx_getBlockByHeight
  • icx_getBlockByHash
  • icx_call
  • icx_getBalance
  • icx_getScoreApi
  • icx_getTotalSupply
  • icx_getTransactionResult
  • icx_getTransactionByHash
  • icx_getTransactionProof
  • icx_getReceiptProof
  • icx_proveTransaction
  • icx_proveReceipt
  • icx_sendTransaction
  • icx_getBlockReceipts

Debug API

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

  • debug_estimateStep
  • debug_getAccount

Other API

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

  • ise_getStatus
  • rep_getListByHash

JSON-RPC Methods

icx_getBlock

  • Returns the block information by given parameter.
  • Depcreated since 1.7.0, will be removed in ICON 2.0

Parameters

KEY VALUE type Description
hash T_HASH Hash of a block
height T_INT Integer of a block height
unconfirmed Boolean (optional) true or false, must be used with height parameter
None — Last block

Returns

Block data (including v0.3)

Example

// Request 1 - get last block
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234
}

// Request 2 - get block by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.3",
        "prevHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x51e030a24c5967047f8463c138024f857ec6663535df1f4e76e224f95abbe4b1",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5908392532c01",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x590839234a5de",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "9MhqZW4n9CtJXTKfDOiVsvZRuGQh9G3X9g3X3+4V2Fp8PcqGvkKHoAI4nJpAxGiJICiT7kgMqwQmvQ8ndGVXrgE="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x590839235367b",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "e2JNWDnNTulhksibVR2AV0/ZLLPwDfeOdq1A5DE/GAIPI56QR+78nV7I/eNHvFDzL6OcpN7D5/VZ5dfFBszB2QE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x590839235419f",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "mjhQSlSZhYuwLSqu+CbNDsiB4WTn8096RQ2EP89YPAVRita+bDuCBhyUkfZWhDqQPVW//sCwQD2GDXxNCC5dCgA="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x59083923541d1",
                "blockHeight": "0x3",
                "blockHash": "0xecafbdc4fb0311995e9f5f4cd01e82deb3d4016c6276c45e77b66eea053a2b22",
                "signature": "o2OnbkaLK1rvGP+pDwrTo/+VV1Ag2/HuDeUV5aoReOhvmS4rOWLGuV00B5KZmE9GO7ZRHl32Ys0oSrj85ve3uAA="
            }
        ],
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "OPHFV8Zfyr//lP+SmKsr/RK3yawJDtolrfsdqDFKh3wxmyMh243zVp7CTLRu5wG5PdneX7mHzuLA9x41mqzjrAE=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}

// Request 4 - get block by height with unconfirmed
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "height": "0x5",
        "unconfirmed": true
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": {
        "version": "0.4",
        "prevHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
        "transactionsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "stateHash": "0xa7ffc6f8bf1ed76651c14756a061d662f580ff4de43b49fa82d80a4b80f8434a",
        "receiptsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "repsHash": "0xa0fa1058145d96226fbe31d4987ae43b54fe83a6bed7939dc7c38da1d44f06bc",
        "nextRepsHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "leaderVotesHash": "0x0000000000000000000000000000000000000000000000000000000000000000",
        "prevVotesHash": "0x233f88d770fcca44b9c91ea6e55a4d981b858ea6f69830443811f73d32918f79",
        "logsBloom": "0x00000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000000",
        "timestamp": "0x5c8c877889b70",
        "transactions": [],
        "leaderVotes": [],
        "prevVotes": [
            {
                "rep": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
                "timestamp": "0x5c8c8776cd53d",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "/6LUAH8oWcVWvq3BMzQu/lujO7s5b5cY9ekVDxeIfVE9PFCKHr7ZHDkmhO01jPyg6ZP/XjB9rYTRyoWu1gVanQA="
            },
            {
                "rep": "hx9f049228bade72bc0a3490061b824f16bbb74589",
                "timestamp": "0x5c8c8777e4f88",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "oOoxPUH4UeE+6TBDfc65UjDn5NoxO5aCDY2k/wPENZROdu7piD7muxk/2Z022U63TYcRtbkd1I5lHiXibJnmWgE="
            },
            {
                "rep": "hx6435405122df9fe5187d659588beccdf7aee8557",
                "timestamp": "0x5c8c87783cbc1",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "WrzmUjN7YltUuTU7uPXomzkLgUQdecTZEaVmtx4bnpBa0WP4yfFwnYv1KllK1rD6rpOsvqc5wJlKH6qsacsbDAE="
            },
            {
                "rep": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
                "timestamp": "0x5c8c877877aa8",
                "blockHeight": "0x4",
                "round_": 0,
                "blockHash": "0x884e98940e774915bbac14137168894f39682531f4edef2b7ea272afbbfdaebb",
                "signature": "AzQb7B/0FcLcC8V/JdBa5Kv3I9J+daMAQq+bWZT2tsRy/xX5kK9vkeUXpWUpzjkgQdnMJWx9X88nclhz4nvWaAA="
            }
        ],
        "hash": "0x7febf336c2a68fb2c844f8b3b9f489d1baa7a5f4910e75d92a89384c9d75551a",
        "height": "0x5",
        "leader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
        "signature": "bZQBqFO+7Cnsbhc4HdkTyz42MS0yB6q829P2aBL9lYkHKxbldSjPkXNoKcsdtr5Qx7f5pTNdCx93Mczighj6zAA=",
        "nextLeader": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe"
    },
    "id": 1234
}


// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlock",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "JSON schema validation error: 'params' has an invalid value"
    },
    "id": 1234
}

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)
      • default: the default value if the parameter has a default value (optional)
      • indexed : 0x1 if the parameter is indexed (when this is eventlog) (optional)
    • 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, message or deposit)
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_getTransactionProof

  • Returns the transaction proof requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

  • T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getTransactionProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_getReceiptProof

  • Returns the transaction receipt proof requested by transaction hash.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction

Returns

  • T_LIST(T_PROOF_DATA) : List of proof data.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_getReceiptProof",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
        },
        {
            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
        },
        {
            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
        },
        {
            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
        },
        {
            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
        },
        {
            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
        },
        {
            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
        }
    ],
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveTransaction

  • Returns the result of proving requested by transaction hash with its proof.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction
proof T_LIST(T_PROOF_DATA) List of proof data

Returns

  • T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveTransaction",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

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

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "id": 1234
}

icx_proveReceipt

  • Returns the result of proving the receipt requested by transaction hash with its proof.

Parameters

KEY VALUE type Description
txHash T_HASH Hash of the transaction
proof T_LIST(T_PROOF_DATA) List of proof data

Returns

  • T_INT : 1 on success, 0 on failure.

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "icx_proveReceipt",
    "id": 1234,
    "params": {
        "txHash": "0x6c85809ead0e601de5e84f063ef3b7d7c504b95a404356af6094f26a39713eb1",
        "proof":  [
        	{
	            "left": "0xac1695c9d3ec0dedd7320d49e8b28bb76cb3f4332f99b396154d35cdb521efbc"
	        },
	        {
	            "right": "0xbb65b23173914f5618c4101b93a8a9e221814b3733dbd4cab6ae06f47982808e"
	        },
	        {
	            "right": "0xc845505ca7667bec30d03c67ba6cfa5a3829ed7d7f1250729bed5f780c31606e"
	        },
	        {
	            "left": "0x0a4ec933df08db2d6982b43b97b5c9564a27dd37ee844660e2613d2d183afce5"
	        },
	        {
	            "left": "0xac51d42744d093dfaff493de34cc1eff77e4f86989dabf53254f1acea40c6322"
	        },
	        {
	            "left": "0x757f4ab5a86f8a159f1dac9a7c50c2522b223c9b17fa6d5beeb0c1c20b4cc948"
	        },
	        {
	            "left": "0x3454646a681c036075b30eb1ca096057cc1a357d861e9ee4c8c8cb2ed6eaae26"
	        }
	    ]
    }
}

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

// Response - failure
{
    "jsonrpc": "2.0",
    "result": 0x0,
    "id": 1234
}

// Response - error
{
    "jsonrpc": "2.0",
    "error": {
        "code": -32602,
        "message": "Tx does not exist."
    },
    "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"
    }
}

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, message or deposit)
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 transferring a message, and data has a HEX string.

dataType == deposit

It is used when depositing ICX in SCORE or withdrawing the deposited ICX, and data has dictionary value as follows.

KEY VALUE type Required Description
action String required Name of the action (add or withdraw)
id String optional needed when withdrawing the deposited ICX

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

Deposit ICX to SCORE

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

Withdraw ICX from SCORE

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

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

debug_getAccount

  • Returns the Account information including stake, delegation of the given EOA or SCORE.

Parameters

KEY VALUE type Description
address T_ADDR_EOA or T_ADDR_SCORE Address of EOA or SCORE
filter T_INT flag value to what information will be included(coin : 1, stake: 2, delegation: 4)

Returns

Information of Account

Example

// Request
{
    "jsonrpc": "2.0",
    "id": 1234,
    "method": "debug_getAccount",
    "params": {
        "address": "hxe7af5fcfd8dfc67530a01a0e403882687528dfcb",
        "filter": "0x7"
    }
}

// Response - success
{
  "coin": {
    "type": "0x1",
    "typeStr": "CoinPartType.GENERAL",
    "flag": "0x0",
    "flagStr": "CoinPartFlag.None"
  },
  "stake": {
    "stake": "0x100",
    "unstake": "0x100",
    "unstakeBlockHeight": "0x200",
    "unstakesInfo": [
      [
        "0x100",
        "0x200"
      ]
    ]
  },
  "delegation": {
    "totalDelegated": "0xa688906bd8b0000",
    "delegations": [
      {
        "address": "hx1d6463e4628ee52a7f751e9d500a79222a7f3935",
        "value": "0x3782dace9d90000"
      },
      {
        "address": "hxb6bc0bf95d90cb3cd5b3abafd9682a62f36cc826",
        "value": "0x6f05b59d3b20000"
      }
    ]
  }
}

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

rep_getListByHash

  • Get all list of Representatives and information by RepsHash

Parameters

KEY VALUE type Required Description
repsHash T_HASH required root hash of representatives

Returns

  • The list of Representatives information by repsHash

Example

// Request
{
    "jsonrpc": "2.0",
    "method": "rep_getListByHash",
    "id": 1234,
    "params": {
        "repsHash": "0x71303ef8543d04b5dc1ba6579132b143087c68db1b2168786408fcbce568238"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
        {
            "address": "hx86aba2210918a9b116973f3c4b27c41a54d5dafe",
            "p2pEndpoint": "127.0.0.1:7100"
        },
        {
            "address": "hx9f049228bade72bc0a3490061b824f16bbb74589",
            "p2pEndpoint": "127.0.0.1:7200"
        },
        {
            "address": "hx6435405122df9fe5187d659588beccdf7aee8557",
            "p2pEndpoint": "127.0.0.1:7300"
        },
        {
            "address": "hx475bfec4178f3abc88c959faa2e6384e6b409c8f",
            "p2pEndpoint": "127.0.0.1:7400"
        }
    ],
    "id": 1234
}

icx_getBlockReceipts

  • Returns the block receipts by given parameter.

Parameters

KEY VALUE type Description
hash T_HASH Hash of a block
height T_INT Integer of a block height
None — Last block

Returns

Block Receipts data (including v0.3)

Example

// Request 1 - get last block receipts
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234
}

// Request 2 - get block receipts by hash
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977"
    }
}

// Request 3 - get block receipts by height
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "height": "0x4"
    }
}

// Response - success
{
    "jsonrpc": "2.0",
    "result": [
		{
			"txHash": "4b9afccf0ce595fc67fd84959d8ff3107aad2e78ea418d8e115d39dbb5ddf683",
			"blockHeight": "0x696",
			"blockHash": "59415879e59977ac29bfa5dcfff3dfff2604beb0f1ba97d1944caf90b39d4c49",
			"txIndex": "0x0",
			"to": "hxe3d6d5d8e433fbd13b9c481d11cf46cebd84b23c",
			"stepUsed": "0x0",
			"stepPrice": "0x0",
			"cumulativeStepUsed": "0x0",
			"eventLogs": [
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"PRepIssued(int,int,int,int)"
					],
					"data": [
						"0xa968163f0a57b400000",
						"0x477",
						"0xd3e02419de2130fd07fe4",
						"0x20bd5ed6b99b1fcb"
					]
				},
				{
					"scoreAddress": "cx0000000000000000000000000000000000000000",
					"indexed": [
						"ICXIssued(int,int,int,int)"
					],
					"data": [
						"0x0",
						"0x20bd5ed6b99b1fcb",
						"0x0",
						"0x53a06a5e791a89dbe"
					]
				}
			],
			"status": "0x1"
		}
	],
  "id": 1234
}

// Request (fail if both parameters are in request message.)
{
    "jsonrpc": "2.0",
    "method": "icx_getBlockReceipts",
    "id": 1234,
    "params": {
        "hash": "0x6d4a4dbb950152050684eef5d0e228b8a31cae7afd37d9760b79312305008977",
        "height": "0x4"
    }
}
 
 
// Response - fail
{
    "jsonrpc": "2.0",
    "id": 1234,
    "error": {
        "code": -32602,
        "message": "Invalid params (only one parameter is allowed)"
    }
}

References

  • JSON-RPC 2.0 Specification
  • ICON JSON RPC API v2
Источник

According to specification, error code should be in response message. Http
server should respond with status code 200, even if there is an error.

JSON-RPC Errors¶

Note

Error is an object which represent any kind of erros in JSON-RPC specification. It is not python Exception and could not be raised.

Errors (Error messages) are members of JSONRPCError class. Any custom error messages should be inherited from it.
The class is responsible for specification following and creates response string based on error’s attributes.

JSON-RPC has several predefined errors, each of them has reserved code, which should not be used for custom errors.

Code Message Meaning
-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 to -32099 Server error Reserved for implementation-defined server-errors.

JSONRPCResponseManager handles common errors. If you do not plan to implement own manager, you do not need to write custom errors. To controll error messages and codes, json-rpc has exceptions, covered in next paragraph.

JSON-RPC Exceptions¶

Note

Exception here a json-rpc library object and not related to specification. They are inherited from python Exception and could be raised.

JSON-RPC manager handles dispatcher method’s exceptions, anything you raise would be catched.
There are two ways to generate error message in manager:

First is to simply raise exception in your method. Manager will catch it and return JSONRPCServerError message with description. Advantage of this mehtod is that everything is already implemented, just add method to dispatcher and manager will do the job.

If you need custom message code or error management, you might need to raise exception, inherited from JSONRPCDispatchException. Make sure, your exception class has error code.

New in version 1.9.0: Fix Invalid params error false generated if method raises TypeError. Now in this case manager introspects the code and returns proper exception.

Источник

Содержание

  1. Exceptions¶
  2. JSON-RPC Errors¶
  3. JSON-RPC Exceptions¶
  4. JSON-RPC 2.0
  5. 2 Conventions
  6. 3 Compatibility
  7. 4 Request object
  8. 4.1 Notification
  9. 4.2 Parameter Structures
  10. 5 Response object
  11. 5.1 Error object
  12. 6 Batch
  13. simple is better
  14. 1 Overview
  15. 2 Conventions
  16. 3 Compatibility
  17. 4 Request object
  18. 4.1 Notification
  19. 4.2 Parameter Structures
  20. 5 Response object
  21. 5.1 Error object
  22. 6 Batch
  23. 7 Examples
  24. 8 Extensions

Exceptions¶

According to specification, error code should be in response message. Http server should respond with status code 200, even if there is an error.

JSON-RPC Errors¶

Error is an object which represent any kind of erros in JSON-RPC specification. It is not python Exception and could not be raised.

Errors (Error messages) are members of JSONRPCError class. Any custom error messages should be inherited from it. The class is responsible for specification following and creates response string based on error’s attributes.

JSON-RPC has several predefined errors, each of them has reserved code, which should not be used for custom errors.

Code Message Meaning
-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 to -32099 Server error Reserved for implementation-defined server-errors.

JSONRPCResponseManager handles common errors. If you do not plan to implement own manager, you do not need to write custom errors. To controll error messages and codes, json-rpc has exceptions, covered in next paragraph.

JSON-RPC Exceptions¶

Exception here a json-rpc library object and not related to specification. They are inherited from python Exception and could be raised.

JSON-RPC manager handles dispatcher method’s exceptions, anything you raise would be catched. There are two ways to generate error message in manager:

First is to simply raise exception in your method. Manager will catch it and return JSONRPCServerError message with description. Advantage of this mehtod is that everything is already implemented, just add method to dispatcher and manager will do the job.

If you need custom message code or error management, you might need to raise exception, inherited from JSONRPCDispatchException . Make sure, your exception class has error code.

New in version 1.9.0: Fix Invalid params error false generated if method raises TypeError. Now in this case manager introspects the code and returns proper exception.

© Copyright 2013-2015, Kirill Pavlov. Revision f1b4e5e9 .

Источник

JSON-RPC 2.0

Date: 2010-03-26 (based on the 2009-05-24 version)
Author: JSON-RPC Working Group

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

It is designed to be simple!

2 Conventions

The key words «MUST», «MUST NOT», «REQUIRED», «SHALL», «SHALL NOT», «SHOULD», «SHOULD NOT», «RECOMMENDED», «MAY», and «OPTIONAL» in this document are to be interpreted as described in RFC 2119.

Since JSON-RPC utilizes JSON, it has the same type system (see http://www.json.org or RFC 4627). JSON can represent four primitive types (Strings, Numbers, Booleans, and Null) and two structured types (Objects and Arrays). The term «Primitive» in this specification references any of those four primitive JSON types. The term «Structured» references either of the structured JSON types. Whenever this document refers to any JSON type, the first letter is always capitalized: Object, Array, String, Number, Boolean, Null. True and False are also capitalized.

All member names exchanged between the Client and the Server that are considered for matching of any kind should be considered to be case-sensitive. The terms function, method, and procedure can be assumed to be interchangeable.

The Client is defined as the origin of Request objects and the handler of Response objects.
The Server is defined as the origin of Response objects and the handler of Request objects.

One implementation of this specification could easily fill both of those roles, even at the same time, to other different clients or the same client. This specification does not address that layer of complexity.

3 Compatibility

JSON-RPC 2.0 Request objects and Response objects may not work with existing JSON-RPC 1.0 clients or servers. However, it is easy to distinguish between the two versions as 2.0 always has a member named «jsonrpc» with a String value of «2.0» whereas 1.0 does not. Most 2.0 implementations should consider trying to handle 1.0 objects, even if not the peer-to-peer and class hinting aspects of 1.0.

4 Request object

A rpc call is represented by sending a Request object to a Server. The Request object has the following members:

jsonrpc A String specifying the version of the JSON-RPC protocol. MUST be exactly «2.0». method A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else. params A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted. id An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2]

The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.

[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

4.1 Notification

A Notification is a Request object without an «id» member. A Request object that is a Notification signifies the Client’s lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. «Invalid params.», «Internal error.»).

4.2 Parameter Structures

If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object.

  • by-position: params MUST be an Array, containing the values in the Server expected order.
  • by-name: params MUST be an Object, with member names that match the Server expected parameter names. The absence of expected names MAY result in an error being generated. The names MUST match exactly, including case, to the method’s expected parameters.

5 Response object

When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications. The Response is expressed as a single JSON Object, with the following members:

jsonrpc A String specifying the version of the JSON-RPC protocol. MUST be exactly «2.0». result This member is REQUIRED on success.
This member MUST NOT exist if there was an error invoking the method.
The value of this member is determined by the method invoked on the Server. error This member is REQUIRED on error.
This member MUST NOT exist if there was no error triggered during invocation.
The value for this member MUST be an Object as defined in section 5.1. id This member is REQUIRED.
It MUST be the same as the value of the id member in the Request Object.
If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.

Either the result member or error member MUST be included, but both members MUST NOT be included.

5.1 Error object

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

code A Number that indicates the error type that occurred.
This MUST be an integer. message A String providing a short description of the error.
The message SHOULD be limited to a concise single sentence. data A Primitive or Structured value that contains additional information about the error.
This may be omitted.
The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. The error codes are nearly the same as those suggested for XML-RPC at the following url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code message meaning
-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.
-32099 to -32000 Server error Reserved for implementation-defined server-errors.

The remainder of the space is available for application defined errors.

6 Batch

To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.

The Server should respond with an Array containing the corresponding Response objects, after all of the batch Request objects have been processed. A Response object SHOULD exist for each Request object, except that there SHOULD NOT be any Response objects for notifications. The Server MAY process a batch rpc call as a set of concurrent tasks, processing them in any order and with any width of parallelism.

The Response objects being returned from a batch call MAY be returned in any order within the Array. The Client SHOULD match contexts between the set of Request objects and the resulting set of Response objects based on the id member within each Object.

If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response object. If there are no Response objects contained within the Response array as it is to be sent to the client, the server MUST NOT return an empty Array and should return nothing at all.

Источник

simple is better

Table of Contents

1 Overview

JSON-RPC is a stateless, light-weight remote procedure call (RPC) protocol. Primarily this specification defines several data structures and the rules around their processing. It is transport agnostic in that the concepts can be used within the same process, over sockets, over http, or in many various message passing environments. It uses JSON (RFC 4627) as data format.

It is designed to be simple!

2 Conventions

The key words «MUST», «MUST NOT», «REQUIRED», «SHALL», «SHALL NOT», «SHOULD», «SHOULD NOT», «RECOMMENDED», «MAY», and «OPTIONAL» in this document are to be interpreted as described in RFC 2119.

Since JSON-RPC utilizes JSON, it has the same type system (see http://www.json.org or RFC 4627). JSON can represent four primitive types (Strings, Numbers, Booleans, and Null) and two structured types (Objects and Arrays). The term «Primitive» in this specification references any of those four primitive JSON types. The term «Structured» references either of the structured JSON types. Whenever this document refers to any JSON type, the first letter is always capitalized: Object, Array, String, Number, Boolean, Null. True and False are also capitalized.

All member names exchanged between the Client and the Server that are considered for matching of any kind should be considered to be case-sensitive. The terms function, method, and procedure can be assumed to be interchangeable.

The Client is defined as the origin of Request objects and the handler of Response objects. The Server is defined as the origin of Response objects and the handler of Request objects.

One implementation of this specification could easily fill both of those roles, even at the same time, to other different clients or the same client. This specification does not address that layer of complexity.

3 Compatibility

JSON-RPC 2.0 Request objects and Response objects may not work with existing JSON-RPC 1.0 clients or servers. However, it is easy to distinguish between the two versions as 2.0 always has a member named «jsonrpc» with a String value of «2.0» whereas 1.0 does not. Most 2.0 implementations should consider trying to handle 1.0 objects, even if not the peer-to-peer and class hinting aspects of 1.0.

4 Request object

A rpc call is represented by sending a Request object to a Server. The Request object has the following members:

jsonrpc A String specifying the version of the JSON-RPC protocol. MUST be exactly «2.0». method A String containing the name of the method to be invoked. Method names that begin with the word rpc followed by a period character (U+002E or ASCII 46) are reserved for rpc-internal methods and extensions and MUST NOT be used for anything else. params A Structured value that holds the parameter values to be used during the invocation of the method. This member MAY be omitted. id An identifier established by the Client that MUST contain a String, Number, or NULL value if included. If it is not included it is assumed to be a notification. The value SHOULD normally not be Null [1] and Numbers SHOULD NOT contain fractional parts [2].

The Server MUST reply with the same value in the Response object if included. This member is used to correlate the context between the two objects.

[1] The use of Null as a value for the id member in a Request object is discouraged, because this specification uses a value of Null for Responses with an unknown id. Also, because JSON-RPC 1.0 uses an id value of Null for Notifications this could cause confusion in handling.
[2] Fractional parts may be problematic, since many decimal fractions cannot be represented exactly as binary fractions.

4.1 Notification

A Notification is a Request object without an «id» member. A Request object that is a Notification signifies the Client’s lack of interest in the corresponding Response object, and as such no Response object needs to be returned to the client. The Server MUST NOT reply to a Notification, including those that are within a batch request.

Notifications are not confirmable by definition, since they do not have a Response object to be returned. As such, the Client would not be aware of any errors (like e.g. «Invalid params.», «Internal error.»).

4.2 Parameter Structures

If present, parameters for the rpc call MUST be provided as a Structured value. Either by-position through an Array or by-name through an Object.

  • by-position: params MUST be an Array, containing the values in the Server expected order.
  • by-name: params MUST be an Object, with member names that match the Server expected parameter names. The absence of expected names MAY result in an error being generated. The names MUST match exactly, including case, to the method’s expected parameters.

5 Response object

When a rpc call is made, the Server MUST reply with a Response, except for in the case of Notifications. The Response is expressed as a single JSON Object, with the following members:

jsonrpc A String specifying the version of the JSON-RPC protocol. MUST be exactly «2.0». result

Either the result member or error member MUST be included, but both members MUST NOT be included.

5.1 Error object

When a rpc call encounters an error, the Response Object MUST contain the error member with a value that is a Object with the following members:

code A Number that indicates the error type that occurred. This MUST be an integer. message A String providing a short description of the error. The message SHOULD be limited to a concise single sentence. data A Primitive or Structured value that contains additional information about the error. This may be omitted. The value of this member is defined by the Server (e.g. detailed error information, nested errors etc.).

The error codes from and including -32768 to -32000 are reserved for pre-defined errors. Any code within this range, but not defined explicitly below is reserved for future use. The error codes are nearly the same as those suggested for XML-RPC at the following url: http://xmlrpc-epi.sourceforge.net/specs/rfc.fault_codes.php

code message Meaning
-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 to -32099 Server error Reserved for implementation-defined server-errors.

The remainder of the space is available for application defined errors.

6 Batch

To send several Request objects at the same time, the Client MAY send an Array filled with Request objects.

The Server should respond with an Array containing the corresponding Response objects, after all of the batch Request objects have been processed. A Response object SHOULD exist for each Request object, except that there SHOULD NOT be any Response objects for notifications. The Server MAY process a batch rpc call as a set of concurrent tasks, processing them in any order and with any width of parallelism.

The Response objects being returned from a batch call MAY be returned in any order within the Array. The Client SHOULD match contexts between the set of Request objects and the resulting set of Response objects based on the id member within each Object.

If the batch rpc call itself fails to be recognized as an valid JSON or as an Array with at least one value, the response from the Server MUST be a single Response object. If there are no Response objects contained within the Response array as it is to be sent to the client, the server MUST NOT return an empty Array and should return nothing at all.

7 Examples

rpc call with positional parameters:

rpc call with named parameters:

rpc call of non-existent method:

rpc call with invalid JSON:

rpc call with invalid Request object:

rpc call Batch, invalid JSON:

rpc call with an empty Array:

rpc call with an invalid Batch (but not empty):

rpc call with invalid Batch:

rpc call Batch (all notifications):

8 Extensions

Method names that begin with rpc. are reserved for system extensions, and MUST NOT be used for anything else. Each system extension is defined in a related specification. All system extensions are OPTIONAL.

Copyright (C) 2007-2010 by the JSON-RPC Working Group

This document and translations of it may be used to implement JSON-RPC, it may be copied and furnished to others, and derivative works that comment on or otherwise explain it or assist in its implementation may be prepared, copied, published and distributed, in whole or in part, without restriction of any kind, provided that the above copyright notice and this paragraph are included on all such copies and derivative works. However, this document itself may not be modified in any way.

The limited permissions granted above are perpetual and will not be revoked.

This document and the information contained herein is provided «AS IS» and ALL WARRANTIES, EXPRESS OR IMPLIED are DISCLAIMED, INCLUDING BUT NOT LIMITED TO ANY WARRANTY THAT THE USE OF THE INFORMATION HEREIN WILL NOT INFRINGE ANY RIGHTS OR ANY IMPLIED WARRANTIES OF MERCHANTABILITY OR FITNESS FOR A PARTICULAR PURPOSE.

Источник

Источник

Понравилась статья? Поделить с друзьями:
  • Js catch specific error
  • Js axios catch error code
  • Jrpcexception asn 1 decode error offset 0 unexpected end of buffer encountered что это
  • Jrpcexception asn 1 decode error offset 0 unexpected end of buffer encountered перевести
  • Jrexpressionevalexception error evaluating expression for source text