forked from NemProject/NemProject.github.io
-
Notifications
You must be signed in to change notification settings - Fork 0
/
Copy pathNisApi.src.html
7096 lines (6090 loc) · 262 KB
/
NisApi.src.html
1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
204
205
206
207
208
209
210
211
212
213
214
215
216
217
218
219
220
221
222
223
224
225
226
227
228
229
230
231
232
233
234
235
236
237
238
239
240
241
242
243
244
245
246
247
248
249
250
251
252
253
254
255
256
257
258
259
260
261
262
263
264
265
266
267
268
269
270
271
272
273
274
275
276
277
278
279
280
281
282
283
284
285
286
287
288
289
290
291
292
293
294
295
296
297
298
299
300
301
302
303
304
305
306
307
308
309
310
311
312
313
314
315
316
317
318
319
320
321
322
323
324
325
326
327
328
329
330
331
332
333
334
335
336
337
338
339
340
341
342
343
344
345
346
347
348
349
350
351
352
353
354
355
356
357
358
359
360
361
362
363
364
365
366
367
368
369
370
371
372
373
374
375
376
377
378
379
380
381
382
383
384
385
386
387
388
389
390
391
392
393
394
395
396
397
398
399
400
401
402
403
404
405
406
407
408
409
410
411
412
413
414
415
416
417
418
419
420
421
422
423
424
425
426
427
428
429
430
431
432
433
434
435
436
437
438
439
440
441
442
443
444
445
446
447
448
449
450
451
452
453
454
455
456
457
458
459
460
461
462
463
464
465
466
467
468
469
470
471
472
473
474
475
476
477
478
479
480
481
482
483
484
485
486
487
488
489
490
491
492
493
494
495
496
497
498
499
500
501
502
503
504
505
506
507
508
509
510
511
512
513
514
515
516
517
518
519
520
521
522
523
524
525
526
527
528
529
530
531
532
533
534
535
536
537
538
539
540
541
542
543
544
545
546
547
548
549
550
551
552
553
554
555
556
557
558
559
560
561
562
563
564
565
566
567
568
569
570
571
572
573
574
575
576
577
578
579
580
581
582
583
584
585
586
587
588
589
590
591
592
593
594
595
596
597
598
599
600
601
602
603
604
605
606
607
608
609
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
634
635
636
637
638
639
640
641
642
643
644
645
646
647
648
649
650
651
652
653
654
655
656
657
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
674
675
676
677
678
679
680
681
682
683
684
685
686
687
688
689
690
691
692
693
694
695
696
697
698
699
700
701
702
703
704
705
706
707
708
709
710
711
712
713
714
715
716
717
718
719
720
721
722
723
724
725
726
727
728
729
730
731
732
733
734
735
736
737
738
739
740
741
742
743
744
745
746
747
748
749
750
751
752
753
754
755
756
757
758
759
760
761
762
763
764
765
766
767
768
769
770
771
772
773
774
775
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
801
802
803
804
805
806
807
808
809
810
811
812
813
814
815
816
817
818
819
820
821
822
823
824
825
826
827
828
829
830
831
832
833
834
835
836
837
838
839
840
841
842
843
844
845
846
847
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
877
878
879
880
881
882
883
884
885
886
887
888
889
890
891
892
893
894
895
896
897
898
899
900
901
902
903
904
905
906
907
908
909
910
911
912
913
914
915
916
917
918
919
920
921
922
923
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
989
990
991
992
993
994
995
996
997
998
999
1000
<!--suppress HtmlUnknownTag -->
<html>
<head>
<meta http-equiv=Content-Type content="text/html; charset=utf-8">
<link rel="stylesheet" type="text/css" href="style.css">
</head>
<body>
<div class=document>
<p class=NemTitle style='margin-bottom:88.0pt;'><img src="image002.png"></p>
<p class=NemTitleText>NEM NIS API Documentation</p>
<p class=NemSubtitle>Version 1.18</p>
<p class=NemSubtitle>
<time>FILLED AUTOMATICALLY</time>
</p>
<p style='page-break-before:always'></p>
<p class=NemTocHeading>Contents</p>
<div id="toc">FILLED AUTOMATICALLY
NOTES:
use samp+pre for OUTPUTS (nis answers)
use code+pre for INPUTS (requests
</div>
<hr/>
<div>
<h4>Changes since 1.17</h4>
<ul>
<li>Corrected the API paths for the namespace and mosaic requests in several places.</li>
</ul>
<h4>Changes since 1.16</h4>
<ul>
<li>Added JSON structures for <a href="#mosaic">Mosaic</a>, <a href="#mosaicDefinition">MosaicDefinition</a>,
<a href="#mosaicDefinitionMetaDataPair">MosaicDefinitionMetaDataPair</a>, <a href="#mosaicProperties">MosaicProperties</a>,
<a href="#mosaicLevy">MosaicLevy</a>, <a href="#mosaicId">MosaicId</a>, <a href="#namespace">Namespace</a> and
<a href="#namespaceMetaDataPair">NamespaceMetaDataPair</a>.
</li>
<li>Added or updated JSON structures for <a href="#mosaicDefinitionCreationTransaction">MosaicDefinitionCreationTransaction</a>,
<a href="#mosaicSupplyChangeTransaction">MosaicSupplyChangeTransaction</a>, <a href="#provisionNamespaceTransaction">ProvisionNamespaceTransaction</a>
and
<a href="#transferTransaction">TransferTransaction</a></li>
<li>Added chapters <a href="#namespaces">Namespaces</a> and <a href="#mosaics">Mosiacs</a> to introduce the concept of NEM namespaces and mosaics.
</li>
<li>Added chapters <a href="#provisioning-a-namespace">Provisioning a namespace</a> and <a href="#creating-mosaics">Creating mosaics</a>.</li>
<li>Updated chapter <a href="#initiating-a-transfer-transaction">Initiating a transfer transaction</a>.</li>
<li>Added chapters <a href="#retrieving-namespaces-that-a-account-owns">Retrieving namespaces that an account owns</a>,
<a href="#retrieving-mosaic-definitions-that-an-account-has-created">Retrieving mosaic definitions that an account has created</a> and
<a href="#retrieving-mosaics-that-an-account-owns">Retrieving mosaics that an account owns</a></li>
<li>Added chapters <a href="#retrieving-root-namespaces">Retrieving root namespaces</a>,
<a href="#retrieving-a-specific-namespace">Retrieving a specific namespace</a> and
<a href="#retrieving-mosaic-definitions">Retrieving mosaic definitions</a></li>
<li>Updated chapter <a href="#gathering-data-for-the-signature">Gathering data for the signature</a> by adding the
<a href="#transferTransaction">TransferTransaction</a> version 2 fields and adding the new transactions
<a href="#provisionNamespaceTransaction">ProvisionNamespaceTransaction</a>,
<a href="#mosaicDefinitionCreationTransaction">MosaicDefinitionCreationTransaction</a> and
<a href="#mosaicSupplyChangeTransaction">MosaicSupplyChangeTransaction</a>.
</li>
<li>Added new validation failure messages for namespace and mosaic validation</li>
</ul>
<h4>Changes since 1.15</h4>
<ul>
<li>updated chapter 6.8 to reflect correct fee calculation for aggregate modification transactions.</li>
</ul>
<h4>Changes since 1.14</h4>
<ul>
<li>updated chapter 6.3, 6.5 and appendix A 8.19.2 to reflect that aggregate modification transactions need to have version 2.</li>
</ul>
<h4>Changes since 1.13</h4>
<ul>
<li>added chapter 3.1.10 <a href="#retrieving-the-unlock-info"> Retrieving the unlock info</a></li>
</ul>
<h4>Changes since 1.12</h4>
<ul>
<li>updated chapter 6.3 - 6.5 to reflect the m of n multisig account changes</li>
<li>updated chapter 6.7.1 to reflect the m of n multisig account changes</li>
<li>updated structure <a href="#multisigAggregateModificationTransaction">MultisigAggregateModificationTransaction</a></li>
<li>replaced table tag with fields tag</li>
<li>updated structures that have changed</li>
<li>added missing error messages</li>
</ul>
<h4>Changes since 1.11</h4>
<ul>
<li>updated chapter 3.1.2 <a href="#requesting-the-account-data"> Requesting the account data</a></li>
<li>added chapter 3.1.3 <a href="#requesting-the-original-account-data-for-a-delegate-account"> Requesting the original account data for a delegate
account</a></li>
<li>updated structure <a href="#accountInfo">AccountInfo</a></li>
</ul>
<h4>Changes since 1.10</h4>
<ul>
<li>added chapter 3.2 <a href="#retrieving-historical-account-data"> Retrieving historical account data</a></li>
<li>added structure <a href="#accountHistoricalDataViewModel">AccountHistoricalDataViewModel</a></li>
</ul>
<h4>Changes since 1.9</h4>
<ul>
<li>corrected the fee formula for aggregate modification transactions in the fee table</li>
</ul>
<h4>Changes since 1.8</h4>
<ul>
<li>updated document to reflect the possible versions (main and test network) of the block and transactions structures</li>
<li>updated structure <a href="#node">Node</a></li>
</ul>
<h4>Changes since 1.7</h4>
<ul>
<li>added chapter 6.7 <a href="#creating-a-signed-transaction"> Creating a signed transaction</a> and added structure <a href="#requestAnnounce">RequestAnnounce</a>
</li>
<li>updated structures <a href="#transactionMetaData">TransactionMetaData</a>, <a href="#nemAnnounceResult">NemAnnounceResult</a></li>
</ul>
<h4>Changes since 1.6</h4>
<ul>
<li>added table with <a href="#transaction-fees">transaction fees</a></li>
<li>fixed description of <a href="#requestPrepareAnnounce">RequestPrepareAnnounce</a></li>
</ul>
<h4>Changes since 1.5</h4>
<ul>
<li>added <a href="#generating-new-account-data">Generating new account data</a></li>
<li>updated <a href="#requesting-the-account-data">Requesting the account data</a></li>
<li>updated structures <a href="#keyPairViewModel">KeyPairViewModel</a>, <a href="#accountMetaData">AccountMetaData</a></li>
</ul>
</div>
<hr/>
<h1>Introduction</h1>
<h2>General Information</h2>
<p>The NEM Infrastructure Server (short: NIS) was written in Java. It needs Java 8 to run. It can run with at least 512MB memory for the java virtual
machine but we recommend at least 1GB.</p>
<h2>Installation</h2>
<p>NIS can be installed either via installer using the URL <a href="http://bob.nem.ninja/installer/">NEM Infrastructure Server</a> or as stand-alone package
which is hosted on <a href="http://bob.nem.ninja/">http://bob.nem.ninja/</a>. The installer only supports 64 bit versions of Java. The current
stand-alone version as of this writing is <a href="http://bob.nem.ninja/nis-ncc-0.5.13.tgz">nis-ncc-0.5.13.tgz</a>. When using the installer both
installation and the start-up of the software is automatic. The stand-alone version needs to be unzipped to a directory of your choice. It is then
started by running runNis.bat (windows) or nix.runNis.sh (linux) from the command prompt.</p>
<h2>Requests</h2>
<p>NIS uses port 7890 to communicate with its clients. It accepts both HTTP GET and POST requests.</p>
<p>Assuming that the NIS is running locally, HTTP GET requests can be executed from a browser and have the form:</p>
<p><a href="http://127.0.0.1:7890/">http://127.0.0.1:7890</a><path to API request>?<parameters> for example:</p>
<p><a href="http://127.0.0.1:7890/account/get?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS">http://127.0.0.1:7890/account/get?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS</a>
</p>
<p>HTTP POST request usually cannot be executed from within the browser unless you use a plugin which is able to do it. HTTP POST requests use JSON
structures in the request body to supply data to NIS.</p>
<p>Both request types return (if any data is returned) data using JSON structures. <a href="#appendix-A:-description-of-the-JSON-structures">Appendix A:
Description of the JSON Structures</a> explains all JSON structures used in this document.</p>
<h1>NIS status related requests</h1>
<p>There are two requests by which you can get information about the status of NIS. The /heartbeat request gives you information if the node is up and
responsive. The /status request gives more detailed information about the state of NIS. Both requests return a NemRequestResult object. See
<appa>NemRequestResult</appa>
for more details on the interpretation of a NemRequestResult.
</p>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h2>Heart beat request</h2>
<api get>/heartbeat</api>
<desc>
<p class=NemNoSpacing>Determines if NIS is up and responsive.</p>
</desc>
<h4>No Parameter:</h4>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/heartbeat">http://127.0.0.1:7890/heartbeat</a></p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"code": 1,
"type": 2,
"message": "ok"
}
</resp>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If there is no response to this request,
NIS is either not running or is in a state where it can't serve requests.</p>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h2>Status Request</h2>
<api get>/status</api>
<desc>
<p class=NemNoSpacing>Determines the status of NIS.</p>
</desc>
<h4>No Parameter:</h4>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/status">http://127.0.0.1:7890/status</a></p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"code": 6,
"type": 4,
<b>"message": "status"</b>
}
</resp>
<p class=NemNoSpacing>The code can be interpreted as follows:</p>
<vals>
0: Unknown status.
1: NIS is stopped.
2: NIS is starting.
3: NIS is running.
4: NIS is booting the local node (implies NIS is running).
5: The local node is booted (implies NIS is running).
6: The local node is synchronized (implies NIS is running and the local node is booted).
7: NIS local node does not see any remote NIS node (implies running and booted).
8: NIS is currently loading the block chain from the database. In this state NIS cannot serve any requests.
</vals>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If there is no response to this request,
NIS is either not running or is in a state where it can't serve requests.</p>
<h1>Account related requests</h1>
<p>This chapter will guide you through the
process of retrieving account information from a NEM Infrastructure Server. The
information that can be retrieved is the durable account data, its meta data
and information about transactions and harvested blocks.</p>
<p>NIS supports two different kind of accounts: normal accounts and multsig (short for: multi signature) accounts:</p>
<h4>Normal accounts:</h4>
<p>Normal accounts are created and controlled
by a private key. Any action for the account like sending NEM to another
account via a transfer transaction is signed with this private key. If an
attacker gains knowledge of the private key, he/she can rob the account. The
private key must therefore be kept secret by all means.</p>
<h4>Multisig accounts:</h4>
<p>Multisig accounts can be created by
converting a normal account to a multisig account via a <b>aggregate
modification transaction</b>. This adds cosignatories to the account. After that
modification, only the cosignatories can initiate an action for the account.
Any action must be signed by all cosignatories. This makes a multisig account
significantly more secure than a normal account. When a single cosignatory
private key is gained by an attacker, the attacker still can't initiate any
action on the account since <b>all</b> cosignatories must sign. It is strongly
recommended to convert any account holding a significantly high amount of NEM
into a multisig account with at least 3 cosignatories. Once converted to a
multisig account, the original private key for the account plays no role any
more.</p>
<p>Durable data is either stored in the
database or can be calculated from other database data. The corresponding JSON
object is described in
<appa>AccountInfo</appa>
. It has the fields:
</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>address</p>
</td>
<td>
<p>Each account has a unique address. First letter of an address indicate
the network the account belongs to. Currently two networks are defined: the
test network whose account addresses start with a capital <b>T</b> and the main
network whose account addresses always start with a capital <b>N</b>. Addresses have
always a length of 40 characters and are <a href="http://en.wikipedia.org/wiki/Base32">base-32</a> encoded.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>balance</p>
</td>
<td>
<p>Each account has a balance which is an integer greater or equal to
zero and denotes the number of <b>micro</b> NEMs which the account owns. Thus a
balance of 123456789 means the account owns 123.456789 NEM. A balance is
split into its vested and unvested part. Only the vested part is relevant for
the importance calculation. For transfers from one account to another only
the balance itself is relevant.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>importance</p>
</td>
<td>
<p>Each account is assigned an importance. The importance is a
decimal number between 0 and 1. It denotes the probability of an account to
harvest the next block in case the account has harvesting turned on and all
other accounts are harvesting too. The exact formula for calculating the
importance is not public yet. Accounts need at least 10k <b>vested</b> NEM to be
included in the importance calculation.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>publicKey</p>
</td>
<td>
<p>The public key of an account can be used
to verify signatures of the account. Only accounts that have already
published a transaction have a public key assigned to the account. Otherwise
the field is null.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>label</p>
</td>
<td>
<p>This field is not used yet and is always null.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>harvestedBlocks</p>
</td>
<td>
<p>Harvesting is the process of generating new blocks. The field
denotes the number of blocks that the account harvested so far. For a new
account the number is 0.</p>
</td>
</tr>
</table>
<p>The meta data for an account describes the
harvesting status of an account, and in case that the account is a cosignatory
of at least one multisig account, the list of those multisig accounts. An
account can either harvest with its current importance or delegate the
harvesting to a so called remote account. In the latter case the remote account
uses the importance of the original account to harvest. The corresponding JSON
object and the possible values for the status/remoteStatus are described in
<appa>AccountMetaDataPair</appa>
. The meta
data consists of the following fields:
</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>status</p>
</td>
<td>
<p>This field describes the harvesting status of an account.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>remoteStatus</p>
</td>
<td>
<p>The field describes the status of remote harvesting.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>cosignatoryOf</p>
</td>
<td>
<p>Array of AccountInfo structures that describe the multisig
accounts that this account is cosignatory of.</p>
</td>
</tr>
</table>
<p>Known accounts have at least one incoming
transaction. The corresponding JSON objects are described in
<appa>Transaction</appa>
,
<alnk>TransactionMetaData</alnk>
and
<alnk>TransactionMetaDataPair</alnk>
.
</p>
<p>A transaction has always the following fields:</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>timeStamp</p>
</td>
<td>
<p>The number of seconds elapsed since the creation of the nemesis
block. Future timestamps are not allowed. Transaction validation detects
future timestamps and returns an error in that case. Network time
synchronization ensures that any NEM software component will use valid timestamps
when creating transactions.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>signature</p>
</td>
<td>
<p>The transaction signature. The transaction signature is validated
using the supplied public key in the field signer. If the signature is not
valid, an error is returned from validation.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>fee</p>
</td>
<td>
<p>The fee for the transaction. The higher the fee, the higher is the
priority of the transaction. Transactions with high priority get included in
a block before transactions with lower priority. If the sender does not have
enough funds the validation will result in an error</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>type</p>
</td>
<td>
<p>The transaction type. Currently the following types of
transactions are supported:</p>
<vals>
0x101: Transfer of NEM from sender to recipient.
0x801: Transfer of importance from sender to remote account.
0x1001: An aggregate modification transaction, which converts a normal account into a multisig account.
0x1002: A multisig signature transaction which is used to sign a multisig transaction.
0x1003: A multisig transaction, which is used for multisig accounts.
</vals>
</td>
</tr>
<tr>
<td>
<p class=JSON>deadline</p>
</td>
<td>
<p>The deadline of the transaction. The deadline is given as the
number of seconds elapsed since the creation of the nemesis block. If a
transaction does not get included in a block before the deadline is reached,
it is deleted.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>version</p>
</td>
<td>
<p>The version of the structure. The following version are currently support.</p>
<li>0x68 << 24 + 1 (1744830465 as 4 byte integer): the main network version</li>
<li>0x98 << 24 + 1 (-1744830463 as 4 byte integer): the test network version</li>
</td>
</tr>
<tr>
<td>
<p class=JSON>signer</p>
</td>
<td>
<p>The public key of the account that created the transaction. The
public key is encoded as hexadecimal string.</p>
</td>
</tr>
</table>
<p>Depending on the type of the transaction, there are additional fields which are specific to given type.
For instance a transfer transaction will have the additional fields.</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>recipient</p>
</td>
<td>
<p>The address of the recipient. If the address is not valid an error
is returned from validation.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>message</p>
</td>
<td>
<p>Optionally a transfer transaction can contain a message.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>payload</p>
</td>
<td>
<p>Optional field in case the transaction contains a message. The
payload is the actual (possibly encrypted) message data. The payload is
allowed to have a maximal size of 512 bytes. Transaction validation detects
if the limit is exceeded and returns an error in this case.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>type</p>
</td>
<td>
<p>Optional field in case the transaction contains a message. The
field holds the message type information. Possible message types are:</p>
<vals>
1: The message is not encrypted.
2: The message is encrypted.
</vals>
</td>
</tr>
</table>
<p>Please refer to <a href="#appendix-A:-description-of-the-JSON-structures">Appendix A</a> for detailed information on the various transactions types and
their additional fields.</p>
<p>Transaction meta data contains only following field:</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>height</p>
</td>
<td>
<p>The height of the block in which the transaction was included.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>id</p>
</td>
<td>
<p>The id of the transaction.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>hash</p>
</td>
<td>
<p>The hash of the transaction.</p>
</td>
</tr>
</table>
<p></p>
<p>Accounts can harvest (i.e. generate new)
blocks if they are lucky. The account which harvests a block collects the fees
which are included in the transactions in the block. The information which
blocks were harvested by an account can be requested. The request returns an
array of HarvestInfo JSON objects. For an example see
<appa>HarvestInfo</appa>
</p>
<p>A harvest info object has the following fields:</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>timeStamp</p>
</td>
<td>
<p>The number of seconds elapsed since the creation of the nemesis block.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>id</p>
</td>
<td>
<p>The database id for the block.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>difficulty</p>
</td>
<td>
<p>The block difficulty.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>totalFee</p>
</td>
<td>
<p>The total fee collected by harvesting the block.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>height</p>
</td>
<td>
<p>The height of the harvested block.</p>
</td>
</tr>
</table>
<p></p>
<p>It is possible to request an array with the
importance information for all accounts. The request returns an array of
AccountImportanceViewModel JSON objects. For an example see
<appa>AccountImportanceViewModel</appa>
.
</p>
<p>An account importance view model has the following fields:</p>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>address</p>
</td>
<td>
<p>The address of the account.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>importance</p>
</td>
<td>
<p>Substructure that describes the importance of the account.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>isSet</p>
</td>
<td>
<p>Indicates if the fields "score", "ev" and "height" are available.</p>
<p>isSet can have the values 0 or 1. In case isSet is 0 the following fields are not available.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>score</p>
</td>
<td>
<p>The importance of the account. The importance ranges between 0 and 1.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>ev</p>
</td>
<td>
<p>The page rank portion of the importance. The page rank ranges between 0 and 1.</p>
</td>
</tr>
<tr>
<td>
<p class=JSON>height</p>
</td>
<td>
<p>The height at which the importance calculation was performed.</p>
</td>
</tr>
</table>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h2>Retrieving account data</h2>
<h3>Generating new account data</h3>
<api get>/account/generate</api>
<desc>
<p class=NemNoSpacing>Generates a <a href="#keyPairViewModel">KeyPairViewModel</a>.</p>
</desc>
<h4>No Parameter:</h4>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/generate">http://127.0.0.1:7890/account/generate</a></p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"privateKey": "0962c6505d02123c40e858ff8ef21e2b7b5466be12c4770e3bf557aae828390f",
"address": "NCKMNCU3STBWBR7E3XD2LR7WSIXF5IVJIDBHBZQT",
"publicKey": "c2e19751291d01140e62ece9ee3923120766c6302e1099b04014fe1009bc89d3"
}
</resp>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>None.</p>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h3>Requesting the account data</h3>
<api get>/account/get</api>
<desc>
<p class=NemNoSpacing>Gets an <a href="#accountMetaDataPair">AccountMetaDataPair</a> for an account.</p>
</desc>
<h4>Parameter:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>address</p>
</td>
<td>
<p class=NemNoSpacing>The address of the account.</p>
</td>
</tr>
</table>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/get?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS">http://127.0.0.1:7890/account/get?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS</a>
</p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"account":
{
"address": "TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS",
"balance": 124446551689680,
"vestedBalance": 104443451691625,
"importance": 0.010263666447108395,
"publicKey": "a11a1a6c17a24252e674d151713cdf51991ad101751e4af02a20c61b59f1fe1a",
"label": null,
"harvestedBlocks": 645
},
"meta":
{
"cosignatoryOf": [ ],
"cosignatories": [ ],
"status": "LOCKED",
"remoteStatus": "ACTIVE"
}
}
</resp>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If the address parameter is not valid, NIS returns an error. See
<alnk>Appendix B: NIS Errors</alnk>
for details about errors.
</p>
<p></p>
<p>Alternatively you can retrieve the account data by providing the public key for the account:</p>
<api get>/account/get/from-public-key</api>
<h4>Parameter:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>publicKey</p>
</td>
<td>
<p class=NemNoSpacing>The public key of the account as hex string.</p>
</td>
</tr>
</table>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/get/from-public-key?publicKey=f9bd190dd0c364261f5c8a74870cc7f7374e631352293c62ecc437657e5de2cd">http://127.0.0.1:7890/account/get/from-public-key?publicKey=f9bd190dd0c364261f5c8a74870cc7f7374e631352293c62ecc437657e5de2cd</a>
</p>
<p>The returned JSON object has the same structure as in the first example.</p>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If the public key parameter is not valid, NIS returns an error. See
<alnk>Appendix B: NIS Errors</alnk>
for details about errors.
</p>
<h3>Requesting the original account data for a delegate account</h3>
<api get>/account/get/forwarded</api>
<desc>
<p class=NemNoSpacing>Given a delegate (formerly known as remote) account's address, gets the <a href="#accountMetaDataPair">AccountMetaDataPair</a>
for the account for which the given account is the delegate account. If the given account address is not a delegate account for any account, the
request returns the <a href="#accountMetaDataPair">AccountMetaDataPair</a> for the given address.</p>
</desc>
<h4>Parameter:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>address</p>
</td>
<td>
<p class=NemNoSpacing>The address of the delegate account.</p>
</td>
</tr>
</table>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/get/forwarded?address=NC2ZQKEFQIL3JZEOB2OZPWXWPOR6LKYHIROCR7PK">http://127.0.0.1:7890/account/get/forwarded?address=NC2ZQKEFQIL3JZEOB2OZPWXWPOR6LKYHIROCR7PK</a>
</p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"account":
{
"address": "NALICE2A73DLYTP4365GNFCURAUP3XVBFO7YNYOW",
"balance": 11793338398661,
"vestedBalance": 10890953464862,
"importance": 0.001264596432148395,
"publicKey": "bdd8dd702acb3d88daf188be8d6d9c54b3a29a32561a068b25d2261b2b2b7f02",
"label": null,
"harvestedBlocks": 742
},
"meta":
{
"cosignatoryOf": [ ],
"cosignatories": [ ],
"status": "LOCKED",
"remoteStatus": "ACTIVE"
}
}
</resp>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If the address parameter is not valid, NIS returns an error. See
<alnk>Appendix B: NIS Errors</alnk>
for details about errors.
</p>
<p></p>
<p>Alternatively you can retrieve the original account data by providing the public key of the delegate account:</p>
<api get>/account/get/forwarded/from-public-key</api>
<h4>Parameter:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>publicKey</p>
</td>
<td>
<p class=NemNoSpacing>The public key of the account as hex string.</p>
</td>
</tr>
</table>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/get/forwarded/from-public-key?publicKey=bdd8dd702acb3d88daf188be8d6d9c54b3a29a32561a068b25d2261b2b2b7f02">http://127.0.0.1:7890/account/get/forwarded/from-public-key?publicKey=bdd8dd702acb3d88daf188be8d6d9c54b3a29a32561a068b25d2261b2b2b7f02</a>
</p>
<p>The returned JSON object has the same structure as in the first example.</p>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If the public key parameter is not valid, NIS returns an error. See
<alnk>Appendix B: NIS Errors</alnk>
for details about errors.
</p>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h3>Requesting the account status</h3>
<api get>/account/status</api>
<desc>
<p class=NemNoSpacing>Gets the <a href="#accountMetaData">AccountMetaData</a> from an account.</p>
</desc>
<h4>Parameter:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>Address</p>
</td>
<td>
<p class=NemNoSpacing>The address of the account.</p>
</td>
</tr>
</table>
<h4>Example:</h4>
<p><a href="http://127.0.0.1:7890/account/status?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS">http://127.0.0.1:7890/account/status?address=TALICELCD3XPH4FFI5STGGNSNSWPOTG5E4DS2TOS</a>
</p>
<h4>Example of returned JSON object:</h4>
<resp>
{
"cosignatoryOf": [ ],
"status": "LOCKED",
"remoteStatus": "ACTIVE"
}
</resp>
<h4>Possible Errors:</h4>
<p class=NemNoSpacing>If the address parameter is not valid,
NIS returns an error. See
<alnk>Appendix B: NIS Errors</alnk>
for details about errors.
</p>
<h3>Requesting transaction data for an account</h3>
<p>A transaction is said to be incoming with
respect to an account if the account is the recipient of the transaction. In
the same way outgoing transaction are the transactions where the account is the
sender of the transaction. Unconfirmed transactions are those transactions that
have not yet been included in a block. Unconfirmed transactions are <b>not</b>
guaranteed to be included in any block.</p>
<!-- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- ---- -->
<h4>Incoming transactions</h4>
<api get>/account/transfers/incoming</api>
<desc>
<p class=NemNoSpacing>Gets an array of <a href="#transactionMetaDataPair">TransactionMetaDataPair</a> objects
where the recipient has the address given as parameter to the request. A
maximum of 25 transaction meta data pairs is returned. The returned transaction
meta data pairs are sorted in descending order in which they were written to
the database.</p>
<p class=NemNoSpacing> The second parameter is optional. When it's not present, the
request will return newest transactions according to the above criteria. When hash
is supplied as second parameter, the request will return up to 25 transactions
that appeared directly before the transaction that has the supplied hash sorted
according to the above criteria.</p>
<p class=NemNoSpacing>The third parameter is optional. When an
id is supplied as third parameter, the request will return up to 25
transactions that appeared directly before the transaction that has the
supplied id sorted according to the above criteria.</p>
<p class=NemNoSpacing>If less than 25 transactions fulfill the
requirements, only those transactions are returned.</p>
<p class=NemNoSpacing></p>
</desc>
<h4>Parameters:</h4>
<table class=NemTableGrid>
<tr>
<td>
<p class=JSON>address</p></td>
<td>
<p class=NemNoSpacing>The address of the account.</p>
</td>
</tr>
<tr>