└── README.md
/README.md:
--------------------------------------------------------------------------------
1 | ICON JSON RPC API V2 document
2 | ========
3 |
4 |
5 |
6 | - [Endpoint](#endpoint)
7 | - [icx_sendTransaction](#icx_sendtransaction)
8 | - [icx_getTransactionResult](#icx_gettransactionresult)
9 | - [icx_getBalance](#icx_getbalance)
10 | - [icx_getBlockByHeight](#icx_getblockbyheight)
11 | - [icx_getBlockByHash](#icx_getblockbyhash)
12 | - [icx_getLastBlock](#icx_getlastblock)
13 |
14 |
15 |
16 | # Endpoint
17 | * Mainnet: https://wallet.icon.foundation/api/v2
18 | * Testnet: https://testwallet.icon.foundation/api/v2
19 |
20 | # icx_sendTransaction
21 |
22 | Transfer ICX value from one wallet to another with the fee.
23 |
24 | ## Request
25 |
26 | ### JSON RPC data
27 |
28 | * ``` jsonrpc```: Fixed as "2.0"
29 |
30 | * ``` method```: "icx_sendTransaction"
31 |
32 | * ``` 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 and Numbers SHOULD NOT contain fractional parts.
33 |
34 | ### Params
35 |
36 | * ```from```
37 |
38 | * Wallet address of the sender
39 |
40 | * Type: String
41 |
42 | * Format: ‘hx’ + 40 digit hex string
43 |
44 | * ```to```
45 |
46 | * Wallet address of the recipient
47 |
48 | * Type: String
49 |
50 | * Format: ‘hx’ + 40 digit hex string
51 |
52 | * ```value```
53 |
54 | * The transfer amount(ICX)
55 |
56 | * Type: String
57 |
58 | * Format: ```0x``` + Hex string
59 |
60 | * Unit: 1/1018 icx
61 |
62 | * To transfer 1.0 icx, the value must be the hex value of 1.0 X 1018.
63 |
64 | * Ex) 1 icx = 1018 loop = "0xDE0B6B3A7640000"
65 |
66 | * ```fee```
67 |
68 | * The fee for the transaction
69 |
70 | * Type: String
71 |
72 | * Format: 0x’ + Hex string string
73 |
74 | * Unit: 1/1018 icx
75 |
76 | * Currently, it’s 0.01 icx (Jan 25, 2018)
77 |
78 | * Ex) 0.01icx = 1016 = "0x2386f26fc10000"
79 |
80 | * ```timestamp```
81 |
82 | * UNIX epoch time (Begin from 1970.1.1 00:00:00)
83 |
84 | * Type: string
85 |
86 | * Unit: microseconds
87 |
88 | * Meaning: creation time of this transaction to avoid ‘replay attack’.
89 |
90 | * ```nonce``` (optional)
91 |
92 | * Type: string
93 |
94 | * Integer value increased by request to avoid ‘replay attack’
95 |
96 | * ```tx_hash```
97 |
98 | * See ‘Additional information.’
99 |
100 | * ```signature```
101 |
102 | * See ‘Additional information.’
103 |
104 | ### Additional information
105 |
106 | #### Generate tx_hash
107 |
108 | ```tx_hash``` has bundled the parameters of the transaction. Pseudo code to generate ```tx_hash``` is as follows:
109 |
110 | ```python
111 | def create_dictionary_with_key( from, to, value, fee):
112 | temp_dict = dict()
113 | temp_dict["from"] = from
114 | temp_dict[“to”] = to
115 | temp_dict[“value”] = value
116 | temp_dict[“time”] = get_UNIX_time_in_string()
117 | temp_dict[“nonce”] = get_nonce_value()
118 | return temp_dict
119 |
120 |
121 | def get_dump_string(key_sorted_data):
122 | str_tmp = “icx_sendTransaction”
123 | for key, value in key_sorted_data.item():
124 | str_tmp += “.”
125 | str_tmp += str(key)
126 | str_tmp += “.”
127 | str_tmp += str(value)
128 |
129 | return str_tmp
130 |
131 |
132 | tx_tmp = create_dictionary_with_key(from, to, value, fee)
133 | key_sorted_data = get_dictionary_with_sorted_by_key_in_unicode(tx_tmp)
134 | dumped_string = get_dump_string(key_sorted_data)
135 | tx_hash = hashlib.sha3_256(dumped_string.encode()).hexdigest()
136 | ```
137 |
138 | #### Generate signature
139 |
140 | The ```signature``` is electronic signature data derived from the wallet’s private key of the sender. Pseudo code to generate the signature is as follows:
141 |
142 | ``` python
143 | signature = SECP256k1.ecdsa_sign_recoverable(msg=binascii.unhexlify(tx_hash),
144 | raw=True,
145 | digest=hashlib.sha3_256)
146 | serialized_sig = SECP256k1.ecdsa_recoverable_serialize(signature)
147 | sig_message = b''.join([serialized_sig[0], bytes([serialized_sig[1]])])
148 | signature = base64.b64encode(sig_message).decode()
149 | ```
150 |
151 |
152 | ### Example of request
153 |
154 | ```json
155 | {
156 | "jsonrpc": "2.0",
157 | "method": "icx_sendTransaction",
158 | "id": 2,
159 | "params": {
160 | "from": "hxbe258ceb872e08851f1f59694dac2558708ece11",
161 | "to": "hxb0776ee37f5b45bfaea8cff1d8232fbb6122ec32",
162 | "value": "0xde0b6b3a7640000",
163 | "fee": "0x2386f26fc10000",
164 | "timestamp": "1516942975500598",
165 | "nonce": "8367273",
166 | "tx_hash": "4bf74e6aeeb43bde5dc8d5b62537a33ac8eb7605ebbdb51b015c1881b45b3aed",
167 | "signature": "VAia7YZ2Ji6igKWzjR2YsGa2m53nKPrfK7uXYW78QLE+ATehAVZPC40szvAiA6NEU5gCYB4c4qaQzqDh2ugcHgA="
168 | }
169 | }
170 | ```
171 |
172 | ## Response
173 |
174 | * ```response_code```: JSON RPC error code.
175 | * ```tx_hash```: Hash data of the result. Use icx_getTransactionResult to get the result.
176 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
177 |
178 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
179 |
180 | ### Successful case
181 |
182 | ``` json
183 | {
184 | "jsonrpc": "2.0",
185 | "result": {
186 | "response_code": 0,
187 | "tx_hash": "4bf74e6aeeb43bde5dc8d5b62537a33ac8eb7605ebbdb51b015c1881b45b3aed"
188 | },
189 | "id":2
190 | }
191 | ```
192 |
193 |
194 |
195 | ### Unsuccessful case
196 |
197 | ```json
198 | {
199 | "jsonrpc": "2.0",
200 | "result": {
201 | "message": "create tx message",
202 | "response_code": -11
203 | },
204 | "id": 2
205 | }
206 | ```
207 |
208 |
209 | # icx_getTransactionResult
210 |
211 | Request the result of previous transaction.
212 |
213 | ## Request
214 |
215 | ### JSON RPC data
216 |
217 | * ```jsonrpc```: Fixed as "2.0"
218 | * ```method```: "icx_getTransactionResult"
219 | * ```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 and Numbers SHOULD NOT contain fractional parts.
220 |
221 | ### Params
222 |
223 | * ```tx_hash```: Hash string from the result of icx_sendTransaction
224 |
225 | #### Example of request
226 |
227 | ``` json
228 | {
229 | "jsonrpc" : "2.0",
230 | "method": "icx_getTransactionResult",
231 | "id": 2,
232 | "params": {
233 | "tx_hash": "e670ec64341771606e55d6b4ca35a1a6b75ee3d5145a99d05921026d1527331"
234 | }
235 | }
236 | ```
237 |
238 |
239 | ## Response
240 |
241 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
242 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
243 | * ``` response_code```: JSON RPC error code.
244 | * ``` response```: Code or message. See the following explanation for code.
245 | * SUCCESS = 0
246 | * EXCEPTION = 90
247 | * NOT_INVOKED = 2 # means pending
248 | * NOT_EXIST = 3 # possibly means failure
249 | * SCORE_CONTAINER_EXCEPTION = 9100
250 |
251 | ### Successful case
252 |
253 | ```json
254 | {
255 | "jsonrpc": "2.0",
256 | "result": {
257 | "response_code": 0,
258 | "response": {
259 | "code": 0
260 | }
261 | },
262 | "id": 2
263 | }
264 | ```
265 |
266 |
267 | ### Unsuccessful case
268 |
269 | ```json
270 | {
271 | "jsonrpc": "2.0",
272 | "result": {
273 | "response_code": -6,
274 | "message": "Invalid transaction hash."
275 | },
276 | "id": 2
277 | }
278 | ```
279 |
280 | # icx_getBalance
281 |
282 | Get the balance of the wallet address.
283 |
284 | ## Request
285 |
286 | ### JSON RPC data
287 |
288 | * ```jsonrpc```: Fixed as "2.0"
289 | * ```method```: "icx_getBalance"
290 | * ```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 and Numbers SHOULD NOT contain fractional parts.
291 |
292 | ### Params
293 | * ```address```: Address of wallet.
294 |
295 | ### Example of request
296 |
297 | ```json
298 | {
299 | "jsonrpc" : "2.0",
300 | "method": "icx_getBalance",
301 | "id": 1234,
302 | "params": {
303 | "address": "hxaa688d74eb5f98b577883ca203535d2aa4f0838c"
304 | }
305 | }
306 | ```
307 |
308 |
309 | ## Response
310 |
311 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
312 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
313 | * ``` response_code```: JSON RPC error code.
314 | * ```response```: code or message. See the following explanation for code.
315 | * SUCCESS = 0
316 |
317 | ### Successful case
318 |
319 | ```json
320 | {
321 | "jsonrpc": "2.0",
322 | "result": {
323 | "response": "0x0",
324 | "response_code": 0
325 | },
326 | "id": 1234
327 | }
328 | ```
329 |
330 |
331 | ### Unsuccessful case
332 |
333 | ```json
334 | {
335 | "jsonrpc": "2.0",
336 | "id": 123,
337 | "result": {
338 | "code": -32602,
339 | "message": "Invalid params"
340 | }
341 | }
342 | ```
343 |
344 |
345 | # icx_getBlockByHeight
346 |
347 | Get block information and transactions by block height
348 |
349 | ## Request
350 | ### JSON RPC data
351 |
352 | * ```jsonrpc```: Fixed as "2.0"
353 | * ```method```: "icx_getBlockByHeight"
354 | * ```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 and Numbers SHOULD NOT contain fractional parts.
355 |
356 | ### Params
357 | * ```height```: Block height
358 |
359 | ### Example of request
360 |
361 | ```json
362 | {
363 | "jsonrpc" : "2.0",
364 | "method": "icx_getBlockByHeight",
365 | "id": 1234,
366 | "params": {
367 | "height": "1234"
368 | }
369 | }
370 | ```
371 |
372 | ## Response
373 |
374 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
375 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
376 | * ``` response_code```: JSON RPC error code.
377 | * ```block```: Block information
378 | - ```version``` : Version of block structure
379 | - ```height```: Height of current block
380 | - ```prev_block_hash```: Block hash of previous block
381 | - ```merkle_tree_root_hash```:Merkle tree root hash of transactions in this block.
382 | - ```time_stamp``` : UNIX epoch time (Begin from 1970.1.1 00:00:00)
383 | * Unit: microseconds
384 | - ```block_hash```: Hash of block
385 | - ```peer_id```: Id of node
386 | - ```signature```: See [this](#request) section
387 | - ```confirmed_transaction_list```: List of transactions in this block.
388 | - ```from``` : See [this](#request) section
389 | - ```to``` : See [this](#request) section
390 | - ```value``` : See [this](#request) section
391 | - ```nonce``` : See [this](#request) section
392 | - ```tx_hash``` : See [this](#request) section
393 | - ```signature``` : See [this](#request) section
394 | - ```method```: Fixed as "icx_sendTransaction"
395 |
396 | ### Successful case
397 |
398 | ```json
399 | {
400 | "jsonrpc": "2.0",
401 | "id": 1234,
402 | "result": {
403 | "response_code": 0,
404 | "block": {
405 | "version": "0.1a",
406 | "prev_block_hash": "48757af881f76c858890fb41934bee228ad50a71707154a482826c39b8560d4b",
407 | "merkle_tree_root_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
408 | "time_stamp": 1516498781094429,
409 | "block_hash": "1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57",
410 | "height": 3,
411 | "peer_id": "e07212ee-fe4b-11e7-8c7b-acbc32865d5f",
412 | "signature": "MEQCICT8mTIL6pRwMWsJjSBHcl4QYiSgG8+0H3U32+05mO9HAiBOhIfBdHNm71WpAZYwJWwQbPVVXFJ8clXGKT3ScDWcvw==",
413 | "confirmed_transaction_list": [
414 | {
415 | "from": "hx63fac3fc777ad647d2c3a72cf0fc42d420a2ba81",
416 | "to": "hx5f8bfd603f1712ccd335d7648fbc989f63251354",
417 | "value": "0xde0b6b3a7640000",
418 | "fee": "0x2386f26fc10000",
419 | "nonce": "0x3",
420 | "tx_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
421 | "signature": "cpSevyvPKC4OpAyywnoNyf0gamHylHOeuSPnLjkyILl1n9Xo4ygezzxda8LpcQ6K1rmo4JU+mXdh+Beh+/mhBgA=",
422 | "method": "icx_sendTransaction"
423 | }
424 | ]
425 | }
426 | }
427 | }
428 | ```
429 | ### TIP : To get the total block height of current block loopchain
430 | Request ```height``` as ```-1```. Then it returns the top block in blockchain. You can get the total block height by using ```result.height.height```.
431 |
432 | # icx_getBlockByHash
433 |
434 | Get block information and transactions by block hash.
435 |
436 | ## Request
437 | ### JSON RPC data
438 |
439 | * ```jsonrpc```: Fixed as "2.0"
440 | * ```method```: "icx_getBlockByHash"
441 | * ```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 and Numbers SHOULD NOT contain fractional parts.
442 |
443 | ### Params
444 | * ```hash```: Hash of block
445 |
446 | ### Example of request
447 |
448 | ```json
449 | {
450 | "jsonrpc" : "2.0",
451 | "method": "icx_getBlockByHash",
452 | "id": 1234,
453 | "params": {
454 | "hash": "af5570f5a1810b7af78caf4bc70a660f0df51e42baf91d4de5b2328de0e83dfc"
455 | }
456 | }
457 | ```
458 |
459 | ## Response
460 |
461 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
462 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
463 | * ``` response_code```: JSON RPC error code.
464 | * ```block```: Block information
465 | - ```version``` : Version of block structure
466 | - ```height```: Height of current block
467 | - ```prev_block_hash```: Block hash of previous block
468 | - ```merkle_tree_root_hash```:Merkle tree root hash of transactions in this block.
469 | - ```time_stamp``` : UNIX epoch time (Begin from 1970.1.1 00:00:00)
470 | * Unit: microseconds
471 | - ```block_hash```: Hash of block
472 | - ```peer_id```: Id of node
473 | - ```signature```: See [this](#request) section
474 | - ```confirmed_transaction_list```: List of transactions in this block.
475 | - ```from``` : See [this](#request) section
476 | - ```to``` : See [this](#request) section
477 | - ```value``` : See [this](#request) section
478 | - ```nonce``` : See [this](#request) section
479 | - ```tx_hash``` : See [this](#request) section
480 | - ```signature``` : See [this](#request) section
481 | - ```method```: Fixed as "icx_sendTransaction"
482 |
483 | ### Successful case
484 |
485 | ```json
486 | {
487 | "jsonrpc": "2.0",
488 | "id": 1234,
489 | "result": {
490 | "response_code": 0,
491 | "block": {
492 | "version": "0.1a",
493 | "prev_block_hash": "48757af881f76c858890fb41934bee228ad50a71707154a482826c39b8560d4b",
494 | "merkle_tree_root_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
495 | "time_stamp": 1516498781094429,
496 | "block_hash": "1fcf7c34dc875681761bdaa5d75d770e78e8166b5c4f06c226c53300cbe85f57",
497 | "height": 3,
498 | "peer_id": "e07212ee-fe4b-11e7-8c7b-acbc32865d5f",
499 | "signature": "MEQCICT8mTIL6pRwMWsJjSBHcl4QYiSgG8+0H3U32+05mO9HAiBOhIfBdHNm71WpAZYwJWwQbPVVXFJ8clXGKT3ScDWcvw==",
500 | "confirmed_transaction_list": [
501 | {
502 | "from": "hx63fac3fc777ad647d2c3a72cf0fc42d420a2ba81",
503 | "to": "hx5f8bfd603f1712ccd335d7648fbc989f63251354",
504 | "value": "0xde0b6b3a7640000",
505 | "fee": "0x2386f26fc10000",
506 | "nonce": "0x3",
507 | "tx_hash": "fabc1884932cf52f657475b6d62adcbce5661754ff1a9d50f13f0c49c7d48c0c",
508 | "signature": "cpSevyvPKC4OpAyywnoNyf0gamHylHOeuSPnLjkyILl1n9Xo4ygezzxda8LpcQ6K1rmo4JU+mXdh+Beh+/mhBgA=",
509 | "method": "icx_sendTransaction"
510 | }
511 | ]
512 | }
513 | }
514 | }
515 | ```
516 |
517 | # icx_getLastBlock
518 |
519 | Get last block information and transactions.
520 |
521 | ## Request
522 | ### JSON RPC data
523 |
524 | * ```jsonrpc```: Fixed as "2.0"
525 | * ```method```: "icx_getLastBlock"
526 | * ```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 and Numbers SHOULD NOT contain fractional parts.
527 |
528 | ### Params
529 | * ```hash```: Hash of block
530 |
531 | ### Example of request
532 |
533 | ```json
534 | {
535 | "jsonrpc" : "2.0",
536 | "id": 1234,
537 | "method": "icx_getLastBlock"
538 | }
539 | ```
540 |
541 | ## Response
542 |
543 | * ```id```: It MUST be the same as the value of the id member in the Request Object.
544 | * If there was an error in detecting the id in the Request object (e.g. Parse error/Invalid Request), it MUST be Null.
545 | * ```result```: Block information
546 | - ```response_code```:JSON RPC error code.
547 | - ```block```: Block information
548 | - ```version``` : Version of block structure
549 | - ```prev_block_hash```: Block hash of previous block
550 | - ```merkle_tree_root_hash```:Merkle tree root hash of transactions in this block.
551 | - ```time_stamp``` : UNIX epoch time (Begin from 1970.1.1 00:00:00)
552 | * Unit: microseconds
553 | - ```confirmed_transaction_list```: List of transactions in this block.
554 | - ```from``` : See [this](#request) section
555 | - ```to``` : See [this](#request) section
556 | - ```value``` : See [this](#request) section
557 | - ```nonce``` : See [this](#request) section
558 | - ```tx_hash``` : See [this](#request) section
559 | - ```signature``` : See [this](#request) section
560 | - ```method```: Fixed as "icx_sendTransaction"
561 | - ```block_hash```: Hash of block
562 | - ```height```: Height of current block
563 | - ```peer_id```: Id of node
564 | - ```signature```: See [this](#request) section
565 |
566 |
567 |
568 | ### Successful case
569 |
570 | ```json
571 | {
572 | "jsonrpc": "2.0",
573 | "result": {
574 | "response_code": 0,
575 | "block": {
576 | "version": "0.1a",
577 | "prev_block_hash": "423b1c293f9c3618250c0ed071ee02943ee0b3d3578a27d45e93e01a28bbb465",
578 | "merkle_tree_root_hash": "09a34405c44ca8fca9c2a1bb14da0d78aad2f295b2db01a005b801eb8498394b",
579 | "time_stamp": 1529631853679726,
580 | "confirmed_transaction_list": [
581 | {
582 | "from": "hxa9a783effea6e17d78e100c2883beefb6c8f8840",
583 | "to": "hx4d41b920df9b161d0e1a5ad06b6c5380fbe03411",
584 | "value": "0x4563918244f40000",
585 | "fee": "0x2386f26fc10000",
586 | "timestamp": "1529631853018000",
587 | "nonce": "8367273",
588 | "tx_hash": "09a34405c44ca8fca9c2a1bb14da0d78aad2f295b2db01a005b801eb8498394b",
589 | "signature": "FJGkkD3l1q6aaqAdL3hU4jC/rsReJU9dJc7HzkW3GYnKteIuM05twFfksfXOuesurPVmEvAn8kuD1mPrORN2QgA=",
590 | "method": "icx_sendTransaction"
591 | }
592 | ],
593 | "block_hash": "702fe614ef9680de0be0241f5a62b943e07ea298f461123c7b95cf0d60be8dca",
594 | "height": 20343,
595 | "peer_id": "hxbda7906f9969af02cc81ca9b8088263bd4f26d7f",
596 | "signature": "hAMdNx8n0d5zlK8qnfbZIiqfOndAsK3GkYIeFNORuK1ePlU7Wxqbb1BPJN2ZGrdeOkJZ+rkHbbEx2oJAISa0sQE="
597 | }
598 | },
599 | "id": 1234
600 | }
601 | ```
602 |
--------------------------------------------------------------------------------