forked from XRPLF/xrpl-dev-portal
-
Notifications
You must be signed in to change notification settings - Fork 0
/
ripple-rest.html
3362 lines (3238 loc) · 132 KB
/
ripple-rest.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
<!DOCTYPE html>
<html lang="en">
<head>
<meta charset="utf-8">
<meta http-equiv="X-UA-Compatible" content="IE=edge,chrome=1">
<meta name="viewport" content="width=device-width">
<title>Ripple-REST - Ripple Developer Portal</title>
<!-- favicon -->
<link rel="icon" href="favicon.ico" type="image/x-icon">
<link rel="shortcut icon" href="favicon.ico" type="image/x-icon">
<!-- jQuery -->
<script src="vendor/jquery-1.11.1.min.js"></script>
<!-- Bootstrap -->
<link href="css/bootstrap.min.css" rel="stylesheet">
<script src="js/bootstrap.min.js"></script>
<!-- Flatdoc theme -->
<link href='vendor/flatdoc/v/0.8.0/theme-white/style.css' rel='stylesheet'>
<script src="vendor/flatdoc/v/0.8.0/theme-white/script.js"></script>
<!-- syntax highlighting -->
<link rel="stylesheet" href="vendor/docco.min.css">
<script src="vendor/highlight.min.js"></script>
<!-- syntax selection js -->
<script src="js/multicodetab.js"></script>
<!-- Markdown content already parsed+included; just do the code tab stuff -->
<script>
$(document).ready(function() {
$().multicode_tabs_pandoc();
hljs.initHighlighting();
make_code_expandable();
});
</script>
<script src="js/expandcode.js"></script>
<script src="js/fixsidebarscroll.js"></script>
<!-- Custom Stylesheets -->
<link href="font/fonts.css" rel="stylesheet" type="text/css" />
<link href="css/main.css" rel="stylesheet" />
<link href="css/custom.css" rel="stylesheet" />
<link rel="shortcut icon" href="favicon.ico?v=2" type="image/x-icon" />
<link rel="icon" href="favicon.ico?v=2" type="image/x-icon" />
</head>
<body class='no-literate'>
<div class="navbar navbar-inverse navbar-fixed-top" role="navigation">
<div class="container">
<div class="navbar-header">
<button type="button" class="navbar-toggle" data-toggle="collapse" data-target=".navbar-collapse">
<span class="sr-only">Toggle navigation</span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
<span class="icon-bar"></span>
</button>
<a class="navbar-brand" href="./"><img class="small_logo" src="assets/img/ripple_logo_small.png"></a>
</div>
<div class="navbar-collapse collapse">
<ul class="nav navbar-nav">
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Concepts <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="paths.html">Paths</a></li>
<li><a href="fees.html">Fees (Disambiguation)</a></li>
<li><a href="transfer_fees.html">Transfer Fees</a></li>
<li><a href="tx-cost.html">Transaction Cost</a></li>
<li><a href="fee-voting.html">Fee Voting</a></li>
<li><a href="reserves.html">Reserves</a></li>
<li><a href="freeze.html">Freeze</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">References <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-apis.html">rippled</a></li>
<li><a href="ripple-rest.html">Ripple-REST</a></li>
<li><a href="transactions.html">Transactions</a></li>
<li><a href="ripple-ledger.html">Ripple Consensus Ledger</a></li>
<li><a href="historical_data.html">Historical Data API</a></li>
<li><a href="charts_api.html">Ripple Charts API</a></li>
<li><a href="data_api_v2.html">Ripple Data API v2</a></li>
<li><a href="rippleapi.html">RippleAPI</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Tutorials <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rippled-setup.html">rippled Setup</a></li>
<li><a href="reliable_tx.html">Reliable Transaction Submission</a></li>
<li><a href="gateway_guide.html">Gateway Guide</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">API Tools <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="rest-api-tool.html">Ripple-REST API Tool</a></li>
<li><a href="historicaldb-api-tool.html">Historical Database API Tool</a></li>
<li><a href="ripple-api-tool.html">WebSocket API Tool</a></li>
<li><a href="charts-api-tool.html">Charts API Tool</a></li>
<li><a href="data-api-v2-tool.html">Data API v2 Tool</a></li>
</ul>
</li>
<li class="dropdown">
<a href="#" class="dropdown-toggle" data-toggle="dropdown">Resources <span class="caret"></span></a>
<ul class="dropdown-menu" role="menu">
<li><a href="https://forum.ripple.com/viewforum.php?f=2">Forums</a></li>
<li><a href="https://www.bountysource.com/teams/ripple/bounties">Bounties</a></li>
<li><a href="https://ripplelabs.atlassian.net/">Bug Tracking</a></li>
<li><a href="https://ripple.com/category/dev-blog/">Dev Blog</a></li>
<li><a href="https://ripple.com/press-releases/">Press Center</a></li>
<li><a href="https://ripple.com/brand-guidelines/">Brand Guidelines</a></li>
</ul>
<li><a href="https://github.com/ripple/ripple-dev-portal" title="GitHub">Site Source</a></li>
</ul>
</div><!--/.nav-collapse -->
</div>
</div>
<script type="text/javascript">
if (window.location.host.indexOf("github.io") > -1) {
document.write("<div style='background-color:red; color:white; position:fixed; top: 50px; right: 150px; padding: 10px 20px;'>DRAFT</div>");
}
</script>
<div class='wrapper'>
<div class='content-root'>
<div class='menubar'>
<div class='menu section' role='flatdoc-menu'>
<script type="text/javascript" src="js/jquery.gensidebar.js"></script>
<script type="text/javascript">
</script>
</div>
</div>
<div class='content'>
<h1 id="ripple-rest-api">Ripple-REST API</h1>
<p>The Ripple-REST API provides a simplified, easy-to-use interface to the Ripple Network via a RESTful API. This page explains how to use the API to send and receive payments on Ripple.</p>
<p>We recommend Ripple-REST for users just getting started with Ripple, since it provides high-level abstractions and convenient simplifications in the data format. If you prefer to access a <code>rippled</code> server directly, you can use <a href="rippled-apis.html">rippled's WebSocket or JSON-RPC APIs</a> instead, which provide the full power of Ripple at the cost of more complexity.</p>
<h2 id="available-api-routes">Available API Routes</h2>
<h4 id="accounts">Accounts</h4>
<ul>
<li><a href="#generate-wallet">Generate Wallet - <code>GET /v1/wallet/new</code></a></li>
<li><a href="#get-account-balances">Get Account Balances - <code>GET /v1/accounts/{:address}/balances</code></a></li>
<li><a href="#get-account-settings">Get Account Settings - <code>GET /v1/accounts/{:address}/settings</code></a></li>
<li><a href="#update-account-settings">Update Account Settings - <code>POST /v1/accounts/{:address}/settings</code></a></li>
</ul>
<h4 id="payments">Payments</h4>
<ul>
<li><a href="#prepare-payment">Prepare Payment - <code>GET /v1/accounts/{:source_address}/payments/paths/{:destination_address}/{:amount}</code></a></li>
<li><a href="#submit-payment">Submit Payment - <code>POST /v1/accounts/{:source_address}/payments</code></a></li>
<li><a href="#confirm-payment">Confirm Payment - <code>GET /v1/accounts/{:address}/payments/{:id}</code></a></li>
<li><a href="#get-payment-history">Get Payment History - <code>GET /v1/accounts/{:address}/payments</code></a></li>
</ul>
<h4 id="orders">Orders</h4>
<ul>
<li><a href="#place-order">Place Order - <code>POST /v1/accounts/{:address}/orders</code></a></li>
<li><a href="#cancel-order">Cancel Order - <code>DELETE /v1/accounts/{:address}/orders/{:sequence}</code></a></li>
<li><a href="#get-account-orders">Get Account Orders - <code>GET /v1/accounts/{:address}/orders</code></a></li>
<li><a href="#get-order-book">Get Order Book - <code>GET /v1/accounts/{:address}/order_book/{:base}/{:counter}</code></a></li>
<li><a href="#get-order-transaction">Get Order Transaction - <code>GET /v1/accounts{:address}/orders/{:hash}</code></a></li>
</ul>
<h4 id="trustlines">Trustlines</h4>
<ul>
<li><a href="#get-trustlines">Get Trustlines - <code>GET /v1/accounts/{:address}/trustlines</code></a></li>
<li><a href="#grant-trustline">Grant Trustline - <code>POST /v1/accounts/{:address}/trustlines</code></a></li>
</ul>
<h4 id="notifications">Notifications</h4>
<ul>
<li><a href="#check-notifications">Check Notifications - <code>GET /v1/accounts/{:address}/notifications/{:id}</code></a></li>
</ul>
<h4 id="status">Status</h4>
<ul>
<li><a href="#check-connection">Check Connection - <code>GET /v1/server/connected</code></a></li>
<li><a href="#get-server-status">Get Server Status - <code>GET /v1/server</code></a></li>
</ul>
<h4 id="utilities">Utilities</h4>
<ul>
<li><a href="#retrieve-ripple-transaction">Retrieve Ripple Transaction - <code>GET /v1/transactions/{:id}</code></a></li>
<li><a href="#retrieve-transaction-cost">Retrieve Transaction Cost - <code>GET /v1/transaction-fee</code></a></li>
<li><a href="#create-client-resource-id">Generate UUID - <code>GET /v1/uuid</code></a></li>
</ul>
<h2 id="api-overview">API Overview</h2>
<h3 id="ripple-concepts">Ripple Concepts</h3>
<p>Ripple is a system for making financial transactions. You can use Ripple to send money anywhere in the world, in any currency, instantly and for free.</p>
<p>In the Ripple world, each account is identified by a <a href="https://ripple.com/wiki/Account">Ripple Address</a>. A Ripple address is a string that uniquely identifies an account, for example: <code>rNsJKf3kaxvFvR8RrDi9P3LBk2Zp6VL8mp</code></p>
<p>A Ripple <strong><em>payment</em></strong> can be sent using Ripple's native currency, XRP, directly from one account to another. Payments can also be sent in other currencies, for example US dollars, Euros, Pounds or Bitcoins, though the process is slightly more complicated.</p>
<p>Payments are made between two accounts, by specifying the <strong><em>source</em></strong> and <strong><em>destination</em></strong> address for those accounts. A payment also involves an <strong><em>amount</em></strong>, which includes both the numeric amount and the currency, for example: <code>100+XRP</code>.</p>
<p>When you make a payment in a currency other than XRP, you also need to include the Ripple address of the <strong><em>counterparty</em></strong>. The counterparty is the gateway or other entity who holds the funds on your behalf. For non-XRP payments, the amount looks something like this: <code>100+USD+rNsJKf3kaxvFvR8RrDi9P3LBk2Zp6VL8mp</code>.</p>
<p>Although the Ripple-REST API provides a high-level interface to Ripple, there are also API methods for checking the status of the <code>rippled</code> server and retrieving a Ripple transaction in its native format.</p>
<h3 id="sending-payments">Sending Payments</h3>
<p>Sending a payment involves three steps:</p>
<ol>
<li>Generate the payment object with the <a href="#prepare-payment">Prepare Payment method</a>. If the payment is not a direct send of XRP from one account to another, the Ripple system identifies the chain of trust, or <strong><em>path</em></strong>, that connects the source and destination accounts, and includes it in the payment object.</li>
<li>Modify the payment object if desired, and then <a href="#submit-payment">submit it</a> to the API for processing. <em>Caution:</em> Making many changes to the payment object increases the chances of causing an error.</li>
<li>Finally, <strong><em>confirm</em></strong> that the payment has completed, using the <a href="#confirm-payment">Confirm Payment method</a>. Payment submission is an asynchronous process, so payments can fail even after they have been submitted successfully.</li>
</ol>
<p>When you submit a payment for processing, you assign a unique <code>client resource identifier</code> to that payment. This is a string which uniquely identifies the payment, and ensures that you do not accidentally submit the same payment twice. You can also use the <code>client_resource_id</code> to retrieve a payment once it has been submitted.</p>
<h3 id="transaction-types">Transaction Types</h3>
<p>The Ripple protocol supports multiple types of transactions, not just payments. Transactions are considered to be any changes to the database made on behalf of a Ripple Address. Transactions are first constructed and then submitted to the network. After transaction processing, meta data is associated with the transaction which itemizes the resulting changes to the ledger.</p>
<ul>
<li>Payment: A Payment transaction is an authorized transfer of balance from one address to another. (This maps to rippled's <a href="transactions.html#payment">Payment transaction type</a>)</li>
<li>Trustline: A Trustline transaction is an authorized grant of trust between two addresses. (This maps to rippled's <a href="transactions.html#trustset">TrustSet transaction type</a>)</li>
<li>Setting: A Setting transaction is an authorized update of account flags under a Ripple Account. (This maps to rippled's <a href="transactions.html#accountset">AccountSet transaction type</a>)</li>
</ul>
<h3 id="client-resource-ids">Client Resource IDs</h3>
<p>All Ripple transactions are identified by a unique hash, which is generated with the fields of the transaction. Ripple-REST uses an additional type of identifier, called a Client Resource ID, which is an arbitrary string provided at the time a transaction is submitted.</p>
<p>A client resource ID generally maps to one Ripple transaction. However, if Ripple-REST re-submits a failed transaction, the client resource ID can become associated with the new transaction, which may have slightly different properties (such as the deadline for it to succeed) and therefore a different transaction hash.</p>
<p>You can create client resource IDs using any method you like, so long as you follow some simple rules:</p>
<ul>
<li>Do not reuse identifiers. </li>
<li>A client resource ID cannot be a 256-bit hex string, because that is ambiguous with Ripple transaction hashes.</li>
<li>Client resource IDs must be properly <a href="http://tools.ietf.org/html/rfc3986#section-2.1">encoded</a> when provided as part of a URL.</li>
</ul>
<p>You can use the <a href="#create-client-resource-id">Create Client Resource ID</a> method in order to generate new Client Resource IDs.</p>
<h2 id="using-ripple-rest">Using Ripple-REST</h2>
<p>You don't need to do any setup to retrieve information from a public Ripple-REST server. Ripple Labs hosts a public Ripple-REST server here:</p>
<p><code>https://api.ripple.com</code></p>
<p>If you want to run your own Ripple-REST server, see the <a href="#running-ripple-rest">installation instructions</a>.</p>
<p>In order to submit payments or other transactions, you need an activated Ripple account. See the <a href="https://support.ripplelabs.com/hc/en-us/categories/200194196-Set-Up-Activation">online support</a> for how you can create an account using the <a href="https://rippletrade.com/">Ripple Trade client</a>.</p>
<p>Make sure you know both the account address and the account secret for your account:</p>
<ul>
<li>The <em>address</em> can be found by clicking the <em>Show Address</em> button in the <strong>Fund</strong> tab of Ripple Trade</li>
<li>The <em>secret</em> is provided when you first create your account. <strong>WARNING: If you submit your secret to a server you do not control, your account can be stolen, along with all the money in it.</strong> We recommend using a test account with very limited funds on the public Ripple-REST server.</li>
</ul>
<p>As a programmer, you will also need to have a suitable HTTP client that allows you to make secure HTTP (<code>HTTPS</code>) GET and POST requests. For testing, there are lots of options, including:</p>
<ul>
<li>The <a href="http://curl.haxx.se/"><code>curl</code></a> commandline utility</li>
<li>The <a href="https://addons.mozilla.org/en-US/firefox/addon/poster/">Poster Firefox extension</a></li>
<li>The <a href="https://chrome.google.com/webstore/detail/postman-rest-client/fdmmgilgnpjigdojojpjoooidkmcomcm?hl=en">Postman Chrome extension</a></li>
</ul>
<p>You can also use the <a href="rest-api-tool.html">REST API Tool</a> here on the Dev Portal to try out the API.</p>
<p><a class="button" href="rest-api-tool.html">Try it! ></a></p>
<h3 id="exploring-the-api">Exploring the API</h3>
<p>A REST API makes resources available via HTTP, the same protocol used by your browser to access the web. This means you can even use your browser to get a response from the API. Try visiting the following URL:</p>
<p>https://api.ripple.com/v1/server</p>
<p>The response should be a page with content similar to the following:</p>
<pre><code class="js">{
"rippled_server_url": "wss://s-west.ripple.com:443",
"rippled_server_status": {
"build_version": "0.23.0",
"complete_ledgers": "5526705-6142138",
"fetch_pack": 2004,
"hostid": "NEAT",
"last_close": {
"converge_time_s": 2.005,
"proposers": 5
},
"load_factor": 1,
"peers": 55,
"pubkey_node": "n9KmrBnGoyVf89WYdiAnvGnKFaVqjLdAYjKrBuvg2r8pMxGPp6MF",
"server_state": "full",
"validated_ledger": {
"age": 1,
"base_fee_xrp": 0.00001,
"hash": "BADDAB671EF21E8ED56B21253123D2C74139FE34E12DBE4B1F5527772EC88494",
"reserve_base_xrp": 20,
"reserve_inc_xrp": 5,
"seq": 6142138
},
"validation_quorum": 3
},
"success": true,
"api_documentation_url": "https://github.com/ripple/ripple-rest"
}
</code></pre>
<p>If you want to connect to your own server, just replace the hostname and port with the location of your instance. For example, if you are running Ripple-REST locally on port 5990, you can access the same information at the following URL:</p>
<p>http://localhost:5990/v1/server</p>
<p>Since the hostname depends on where your chosen Ripple-REST instance is, the methods in this document are identified using only the part of the path that comes after the hostname.</p>
<h1 id="running-ripple-rest">Running Ripple-REST</h1>
<h2 id="quick-start">Quick Start</h2>
<p>Ripple-REST requires <a href="http://nodejs.org/">Node.js</a> and <a href="http://www.sqlite.org/">sqlite 3</a>. Before starting, you should make sure that you have both installed. </p>
<p>Following that, use these instructions to get Ripple-REST installed and running:</p>
<ol>
<li>Clone the Ripple-REST repository with git:
<code>git clone https://github.com/ripple/ripple-rest.git</code></li>
<li>Switch to the <code>ripple-rest</code> directory:
<code>cd ripple-rest</code></li>
<li>Use <em>npm</em> to install additional dependencies:
<code>npm install</code></li>
<li>Copy the example config file to <code>config.json</code>:
<code>cp config-example.json config.json</code></li>
<li>Start the server:
<code>npm start</code></li>
<li>Visit <code>http://localhost:5990</code> in a browser to view available endpoints and get started</li>
</ol>
<h2 id="configuring-ripple-rest">Configuring <code>ripple-rest</code></h2>
<p>The Ripple-REST server uses <a href="https://github.com/flatiron/nconf">nconf</a> to load configuration options from several sources. Settings from sources earlier in the following hierarchy override settings from the later levels:</p>
<ol>
<li>Command line arguments</li>
<li>Environment variables</li>
<li>The <code>config.json</code> file</li>
</ol>
<p>The path to the <code>config.json</code> file can be specified as a command line argument (<code>node server.js --config /path/to/config.json</code>). If no path is specified, the default location for that file is Ripple-REST's root directory.</p>
<p>Available configuration options are outlined in the <a href="https://github.com/ripple/ripple-rest/blob/develop/docs/server-configuration.md"><strong>Server Configuration</strong></a> document. The <code>config-example.json</code> file in the root directory contains a sample configuration.</p>
<h2 id="debug-mode">Debug mode</h2>
<p>You can run the server in Debug Mode with the following command:</p>
<pre><code>node server.js --debug
</code></pre>
<h2 id="running-ripple-rest-securely-over-ssl">Running Ripple-REST securely over SSL</h2>
<p>We highly recommend running Ripple-REST securely over SSL. Doing so requires a certificate. For development and internal-only deployments, you can use a self-signed certificate. For production servers that are accessed over untrusted network connections, you should purchase a cert from a proper authority.</p>
<p>You can perform the following steps to generate a self-signed cert with <a href="https://www.openssl.org/">OpenSSL</a> and configure Ripple-REST to use it:</p>
<ol>
<li>Generate the SSL certificate:</li>
</ol>
<pre><code class="bash">openssl genrsa -out /etc/ssl/private/server.key 2048
openssl req -utf8 -new -key /etc/ssl/private/server.key -out /etc/ssl/server.csr -sha512
-batch
openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/server.key
-out /etc/ssl/certs/server.crt -sha512
</code></pre>
<ol>
<li>Modify the <code>config.json</code> to enable SSL and specify the paths to the <code>certificate</code> and <code>key</code> files</li>
</ol>
<pre><code> "ssl_enabled": true,
"ssl": {
"key_path": "./certs/server.key",
"cert_path": "./certs/server.crt"
},
</code></pre>
<h2 id="deployment-tips">Deployment Tips</h2>
<h3 id="keeping-the-service-running">Keeping the service running</h3>
<p>Monitor <code>ripple-rest</code> using <a href="http://mmonit.com/monit/"><code>monit</code></a>. On Ubuntu you can install <code>monit</code> using <code>sudo apt-get install monit</code>.</p>
<p>Here is an example of a monit script that will restart the server if:</p>
<ul>
<li>memory usage surpasses 25% of the server's available memory</li>
<li>the server fails responding to server status</li>
</ul>
<pre><code>set httpd port 2812 and allow localhost
check process ripple-rest with pidfile /var/run/ripple-rest/ripple-rest.pid
start program = "/etc/init.d/ripple-rest start"
stop program = "/etc/init.d/ripple-rest stop"
if memory > 25% then restart
if failed port 5990 protocol HTTP
and request "/v1/server"
then restart
</code></pre>
<h1 id="formatting-conventions">Formatting Conventions</h1>
<p>The <code>ripple-rest</code> API conforms to the following general behavior for <a href="http://en.wikipedia.org/wiki/Representational_state_transfer">RESTful API</a>:</p>
<ul>
<li>You make HTTP (or HTTPS) requests to the API endpoint, indicating the desired resources within the URL itself. (The public server, for the sake of security, only accepts HTTPS requests.)</li>
<li>The HTTP method identifies what you are trying to do. Generally, HTTP <code>GET</code> requests are used to retrieve information, while HTTP <code>POST</code> requests are used to make changes or submit information.</li>
<li>If more complicated information needs to be sent, it will be included as JSON-formatted data within the body of the HTTP POST request.</li>
<li>This means that you must set <code>Content-Type: application/json</code> in the headers when sending POST requests with a body.</li>
<li>Upon successful completion, the server returns an <a href="http://www.w3.org/Protocols/rfc2616/rfc2616-sec10.html">HTTP status code</a> of 200 OK, and a <code>Content-Type</code> value of <code>application/json</code>. The body of the response will be a JSON-formatted object containing the information returned by the endpoint.</li>
</ul>
<p>As an additional convention, all responses from Ripple-REST contain a <code>"success"</code> field with a boolean value indicating whether or not the success</p>
<h2 id="errors">Errors</h2>
<p>When errors occur, the server returns an HTTP status code in the 400-599 range, depending on the type of error. The body of the response contains more detailed information on the cause of the problem.</p>
<p>In general, the HTTP status code is indicative of where the problem occurred:</p>
<ul>
<li>Codes in the 200-299 range indicate success. (<em>Note:</em> This behavior is new in <a href="https://github.com/ripple/ripple-rest/releases/tag/1.3.0">Ripple-REST v1.3.0</a>. Previous versions sometimes return 200 OK for some types of errors.)<ul>
<li>Unless otherwise specified, methods are expected to return <code>200 OK</code> on success.</li>
</ul>
</li>
<li>Codes in the 400-499 range indicate that the request was invalid or incorrect somehow. For example:<ul>
<li><code>400 Bad Request</code> occurs if the JSON body is malformed. This includes syntax errors as well as when invalid or mutually-exclusive options are selected.</li>
<li><code>404 Not Found</code> occurs if the path specified does not exist, or does not support that method (for example, trying to POST to a URL that only serves GET requests)</li>
</ul>
</li>
<li>Codes in the 500-599 range indicate that the server experienced a problem. This could be due to a network outage or a bug in the software somewhere. For example:<ul>
<li><code>500 Internal Server Error</code> occurs when the server does not catch an error. This is always a bug. If you can reproduce the error, file it at <a href="https://ripplelabs.atlassian.net/browse/RA/">our bug tracker</a>.</li>
<li><code>502 Bad Gateway</code> occurs if Ripple-REST could not contact its <code>rippled</code> server at all.</li>
<li><code>504 Gateway Timeout</code> occurs if the <code>rippled</code> server took too long to respond to the Ripple-REST server.</li>
</ul>
</li>
</ul>
<p>When possible, the server provides a JSON response body with more information about the error. These responses contain the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>success</td>
<td>Boolean</td>
<td><code>false</code> indicates that an error occurred.</td>
</tr>
<tr>
<td>error_type</td>
<td>String</td>
<td>A short code identifying a general category for the error that occurred.</td>
</tr>
<tr>
<td>error</td>
<td>String</td>
<td>A human-readable summary of the error that occurred.</td>
</tr>
<tr>
<td>message</td>
<td>String</td>
<td>(May be omitted) A longer human-readable explanation for the error.</td>
</tr>
</tbody>
</table>
<p>Example error:</p>
<pre><code class="js">{
"success": false,
"error_type": "invalid_request",
"error": "Invalid parameter: destination_amount",
"message": "Non-XRP payment must have an issuer"
}
</code></pre>
<h2 id="quoted-numbers">Quoted Numbers</h2>
<p>In any case where a large number should be specified, Ripple-REST uses a string instead of the native JSON number type. This avoids problems with JSON libraries which might automatically convert numbers into native types with differing range and precision.</p>
<p>You should parse these numbers into a numeric data type with adequate precision. If it is not clear how much precision you need, we recommend using an arbitrary-precision data type.</p>
<h2 id="currency-amounts"><a id="amount_object"></a> Currency Amounts</h2>
<p>There are two kinds of currency on the Ripple network: XRP, and issuances. XRP is the native cryptocurrency that only exists in the network, and can be held by accounts and sent directly to other accounts with no trust necessary.</p>
<p>All other currencies take the form of <em>issuances</em>, which are held in the <em>trust lines</em> that link accounts. Issuances are identified by a <code>counterparty</code> on the other end of the trust line, sometimes also called the <code>issuer</code>. Sending and trading issuances actually means debiting the balance of a trust line and crediting the balance of another trust line linked to the same account. Ripple ensures this operation happens atomically.</p>
<p>Issuances are typically created by Gateway accounts in exchange for assets in the outside world. In most cases, the <code>counterparty</code> of a currency refers to the gateway that created the issuances. XRP never has a counterparty.</p>
<p>You can read more about <a href="https://ripple.com/knowledge_categories/xrp/">XRP</a> and <a href="https://ripple.com/knowledge_center/gateways/">Gateways</a> in the Knowledge Center.</p>
<h3 id="amounts-in-json">Amounts in JSON</h3>
<p>When an amount of currency is specified as part of a JSON body, it is encoded as an object with three fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>value</td>
<td>String (Quoted decimal)</td>
<td>The quantity of the currency</td>
</tr>
<tr>
<td>currency</td>
<td>String</td>
<td>Three-digit <a href="http://www.xe.com/iso4217.php">ISO 4217 Currency Code</a> specifying which currency. Alternatively, a 160-bit hex value. (Some advanced features, like <a href="https://ripple.com/wiki/Gateway_demurrage">demurrage</a>, require the hex version.)</td>
</tr>
<tr>
<td>counterparty</td>
<td>String</td>
<td>(New in <a href="https://github.com/ripple/ripple-rest/releases/tag/1.4.0">v1.4.0</a>) The Ripple address of the account that is a counterparty to this currency. This is usually an <a href="https://ripple.com/knowledge_center/gateways/">issuing gateway</a>. Always omitted, or an empty string, for XRP.</td>
</tr>
<tr>
<td>issuer</td>
<td>String</td>
<td>(Prior to 1.4.0) <strong>DEPRECATED</strong> alias for <code>counterparty</code>. Some methods may still return this instead.</td>
</tr>
</tbody>
</table>
<p>Example Amount Object:</p>
<pre><code class="js">{
"value": "1.0",
"currency": "USD",
"counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q"
}
</code></pre>
<p>or for XRP:</p>
<pre><code class="js">{
"value": "1.0",
"currency": "XRP",
"counterparty": ""
}
</code></pre>
<p>The <code>value</code> field can get very large or very small. See the <a href="https://wiki.ripple.com/Currency_Format">Currency Format</a> for the exact limits of Ripple's precision.</p>
<h3 id="amounts-in-urls">Amounts in URLs</h3>
<p>When an amount of currency has to be specified in a URL, you use the same fields as the JSON object -- value, currency, and counterparty -- but concatenate them with <code>+</code> symbols in that order.</p>
<p>Example Amount:</p>
<p><code>1.0+USD+rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q</code></p>
<p>When specifying an amount of XRP, you must omit the counterparty entirely. For example:</p>
<p><code>1.0+XRP</code></p>
<h3 id="counterparties-in-payments">Counterparties in Payments</h3>
<p>Most of the time, the <code>counterparty</code> field of a non-XRP currency indicates the account of the gateway that issues that currency. However, when describing payments, there are a few nuances that are important:</p>
<ul>
<li>There is only ever one balance for the same currency between two accounts. This means that, sometimes, the <code>counterparty</code> field of an amount actually refers to a counterparty that is redeeming issuances, instead of the account that created the issuances.</li>
<li>You can omit the counterparty from the <code>destination_amount</code> of a payment to mean "any counterparty that the destination accepts". This includes all accounts to which the destination has extended trust lines, as well as issuances created by the destination which may be held on other trust lines. <ul>
<li>For compatibility with <code>rippled</code>, setting the <code>counterparty</code> of the <code>destination_amount</code> to be the destination account's address means the same thing.</li>
</ul>
</li>
<li>You can omit the counterparty from the <code>source_amount</code> of a payment to mean "any counterparty the source can use". This includes creating new issuances on trust lines that other accounts have extended to the source account, as well as issuances from other accounts that the source account possesses.<ul>
<li>Similarly, setting the <code>counterparty</code> of the <code>source_amount</code> to be the source account's address means the same thing.</li>
</ul>
</li>
</ul>
<h2 id="payment-objects"><a id="payment_object"></a> Payment Objects</h2>
<p>The <code>Payment</code> object is a simplified version of the standard Ripple transaction format.</p>
<p>This <code>Payment</code> format is intended to be straightforward to create and parse, from strongly or loosely typed programming languages. Once a transaction is processed and validated it also includes information about the final details of the payment.</p>
<p>An example Payment object looks like this:</p>
<pre><code class="js">{
"source_address": "rKXCummUHnenhYudNb9UoJ4mGBR75vFcgz",
"source_tag": "",
"source_amount": {
"value": "0.001",
"currency": "XRP",
"issuer": ""
},
"source_slippage": "0",
"destination_address": "rNw4ozCG514KEjPs5cDrqEcdsi31Jtfm5r",
"destination_tag": "",
"destination_amount": {
"value": "0.001",
"currency": "XRP",
"issuer": ""
},
"invoice_id": "",
"paths": "[]",
"flag_no_direct_ripple": false,
"flag_partial_payment": false
}
</code></pre>
<p>The fields of a Payment object are defined as follows:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td><code>source_account</code></td>
<td>String</td>
<td>The Ripple address of the account sending the payment</td>
</tr>
<tr>
<td><code>source_amount</code></td>
<td><a href="#amount_object">Amount Object</a></td>
<td>The amount to deduct from the account sending the payment.</td>
</tr>
<tr>
<td><code>destination_account</code></td>
<td>String</td>
<td>The Ripple address of the account receiving the payment</td>
</tr>
<tr>
<td><code>destination_amount</code></td>
<td><a href="#amount_object">Amount Object</a></td>
<td>The amount that should be deposited into the account receiving the payment.</td>
</tr>
<tr>
<td><code>source_tag</code></td>
<td>String (Quoted unsigned integer)</td>
<td>(Optional) A quoted 32-bit unsigned integer (0-4294967294, inclusive) to indicate a sub-category of the source account. Typically, it identifies a hosted wallet at a gateway as the sender of the payment.</td>
</tr>
<tr>
<td><code>destination_tag</code></td>
<td>String (Quoted unsigned integer)</td>
<td>(Optional) A quoted 32-bit unsigned integer (0-4294967294, inclusive) to indicate a particular sub-category of the destination account. Typically, it identifies a hosted wallet at a gateway as the recipient of the payment.</td>
</tr>
<tr>
<td><code>source_slippage</code></td>
<td>String (Quoted decimal)</td>
<td>(Optional) Provides the <code>source_amount</code> a cushion to increase its chance of being processed successfully. This is helpful if the payment path changes slightly between the time when a payment options quote is given and when the payment is submitted. The <code>source_address</code> will never be charged more than <code>source_slippage</code> + the <code>value</code> specified in <code>source_amount</code>.</td>
</tr>
<tr>
<td><code>invoice_id</code></td>
<td>String</td>
<td>(Optional) Arbitrary 256-bit hash that can be used to link payments to an invoice or bill.</td>
</tr>
<tr>
<td><code>paths</code></td>
<td>String</td>
<td>A "stringified" version of the Ripple PathSet structure. You can get a path for your payment from the <a href="#prepare-payment">Prepare Payment</a> method.</td>
</tr>
<tr>
<td><code>no_direct_ripple</code></td>
<td>Boolean</td>
<td>(Optional, defaults to false) <code>true</code> if <code>paths</code> are specified and the sender would like the Ripple Network to disregard any direct paths from the <code>source_address</code> to the <code>destination_address</code>. This may be used to take advantage of an arbitrage opportunity or by gateways wishing to issue balances from a hot wallet to a user who has mistakenly set a trustline directly to the hot wallet. Most users will not need to use this option.</td>
</tr>
<tr>
<td><code>partial_payment</code></td>
<td>Boolean</td>
<td>(Optional, defaults to false) If set to <code>true</code>, fees will be deducted from the delivered amount instead of the sent amount. (<em>Caution:</em> There is no minimum amount that will actually arrive as a result of using this flag; only a miniscule amount may actually be received.) See <a href="transactions.html#partial-payments">Partial Payments</a></td>
</tr>
<tr>
<td><code>memos</code></td>
<td>Array</td>
<td>(Optional) Array of <a href="#memo-objects">memo objects</a>, where each object is an arbitrary note to send with this payment.</td>
</tr>
</tbody>
</table>
<p>Submitted transactions can have additional fields reflecting the current status and outcome of the transaction, including:</p>
<p><a href="https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/lib/tx-to-rest-converter.js#L25" title="Source">[Source]<br/></a></p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>direction</td>
<td>String</td>
<td>The direction of the payment relative to the account from the URL, either <code>"outgoing"</code> (sent by the account in the URL) or <code>"incoming"</code> (received by the account in the URL)</td>
</tr>
<tr>
<td>result</td>
<td>String</td>
<td>The <a href="transactions.html#transaction-results">Ripple transaction status code</a> for the transaction. A value of <code>"tesSUCCESS"</code> indicates a successful transaction.</td>
</tr>
<tr>
<td>timestamp</td>
<td>String</td>
<td>The time the ledger containing this transaction was validated, as a <a href="http://en.wikipedia.org/wiki/ISO_8601">ISO8601 extended format</a> string in the form <code>YYYY-MM-DDTHH:mm:ss.sssZ</code>.</td>
</tr>
<tr>
<td>fee</td>
<td>String (Quoted decimal)</td>
<td>The amount of XRP charged as a transaction fee.</td>
</tr>
<tr>
<td>source_balance_changes</td>
<td>Array</td>
<td>Array of <a href="#amount_object">Amount objects</a> indicating changes in balances held by the account sending the transaction as a result of the transaction.</td>
</tr>
<tr>
<td>destination_balance_changes</td>
<td>Array</td>
<td>Array of <a href="#amount_object">Amount objects</a> indicating changes in balances held by the account receiving the transaction as a result of the transaction.</td>
</tr>
<tr>
<td>order_changes</td>
<td>Array</td>
<td>Array of <a href="#amount_object">Amount objects</a> indicating changes to orders caused by the Payment.</td>
</tr>
<tr>
<td>source_amount_submitted</td>
<td>Object</td>
<td>An <a href="#amount_object">Amount object</a> indicating the source amount submitted (useful when <code>payment.partial_payment</code> flag is set to <em>true</em></td>
</tr>
</tbody>
</table>
<h3 id="memo-objects">Memo Objects</h3>
<p><em>(New in <a href="https://github.com/ripple/ripple-rest/releases/tag/1.3.0">Ripple-REST v1.3.0</a>)</em></p>
<p>Memo objects represent arbitrary data that can be included in a transaction. The overall size of the <code>memos</code> field cannot exceed 1KB after serialization.</p>
<p>Each Memo object must have at least one of the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>MemoType</td>
<td>String</td>
<td>A string using URL-safe characters, conventionally a unique relation type (according to <a href="http://tools.ietf.org/html/rfc5988#section-4">RFC 5988</a>) that defines the format of this memo.</td>
</tr>
<tr>
<td>MemoFormat</td>
<td>String</td>
<td>A string using URL-safe characters, conventionally containing information on how the memo is encoded, for example as a <a href="http://www.iana.org/assignments/media-types/media-types.xhtml">MIME type</a></td>
</tr>
<tr>
<td>MemoData</td>
<td>String</td>
<td>Arbitrary UTF-8 string representing the content of the memo.</td>
</tr>
</tbody>
</table>
<p>The MemoType and MemoFormat fields should only consist of the following characters: <code>ABCDEFGHIJKLMNOPQRSTUVWXYZabcdefghijklmnopqrstuvwxyz0123456789-._~:/?#[]@!$&'()*+,;=%</code></p>
<p>Example of the memos field:</p>
<pre><code class="js"> "memos": [
{
"MemoType": "http://example.com/unique/memo/relation",
"MemoData": "Lorem ipsum dolor sit amet, consectetur adipiscing elit. Lorem ipsum是指一篇常用於排版設計領域的拉丁文文章，主要的目的為測試文章或文字在不同字型、版型下看起來的效果。Lorem ipsum es el texto que se usa habitualmente en diseño gráfico en demostraciones de tipografías o de borradores de diseño para probar el diseño visual antes de insertar el texto final."
},
{
"MemoData": "Fusce est est, malesuada in tincidunt mattis, auctor eu magna."
}
]
</code></pre>
<h2 id="order-objects">Order Objects</h2>
<p><em>(New in <a href="https://github.com/ripple/ripple-rest/releases/tag/1.4.0">Ripple-REST 1.4.0</a>)</em></p>
<p>An order object describes an offer to exchange two currencies. Order objects are used when creating or looking up individual orders.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>String (<code>buy</code> or <code>sell</code>)</td>
<td>Whether the order is to buy or sell.</td>
</tr>
<tr>
<td>taker_pays</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The amount the taker must pay to consume this order.</td>
</tr>
<tr>
<td>taker_gets</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The amount the taker will get once the order is consumed.</td>
</tr>
<tr>
<td>sequence</td>
<td>Number</td>
<td>The sequence number of the transaction that created the order. Used in combination with account to uniquely identify the order.</td>
</tr>
<tr>
<td>passive</td>
<td>Boolean</td>
<td>Whether the order should be <a href="transactions.html#offercreate-flags">passive</a>.</td>
</tr>
<tr>
<td>sell</td>
<td>Boolean</td>
<td>Whether the order should be <a href="transactions.html#offercreate-flags">sell</a>.</td>
</tr>
<tr>
<td>immediate_or_cancel</td>
<td>Boolean</td>
<td>Whether the order should be <a href="transactions.html#offercreate-flags">immediate or cancel</a>.</td>
</tr>
<tr>
<td>fill_or_kill</td>
<td>Boolean</td>
<td>Whether the order should be <a href="transactions.html#offercreate-flags">fill or kill</a>.</td>
</tr>
</tbody>
</table>
<h2 id="order-change-objects">Order Change Objects</h2>
<p>An order change object describes the changes to to a Ripple account's open order due to a transaction.</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>String (<code>buy</code> or <code>sell</code>)</td>
<td>Whether the order is to buy or sell.</td>
</tr>
<tr>
<td>taker_pays</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The <code>value</code> of the amount is expressed as the difference between the final amount and original amount.</td>
</tr>
<tr>
<td>taker_gets</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The <code>value</code> of the amount is expressed as the difference between the final amount and original amount.</td>
</tr>
<tr>
<td>sequence</td>
<td>Number</td>
<td>The sequence number of the transaction that created the order. Used in combination with account to uniquely identify the order.</td>
</tr>
<tr>
<td>status</td>
<td>String(<code>created</code>, <code>closed</code>, <code>canceled</code>, <code>open</code>)</td>
<td>The status of the order on the ledger. An order that is partially filled has the status <code>open</code>.</td>
</tr>
</tbody>
</table>
<h2 id="bid-objects">Bid Objects</h2>
<p>An bid object describes an offer to exchange two currencies, including the current funding status of the offer. Bid objects are used to describe bids and asks when retrieving an order book. </p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>type</td>
<td>String (<code>buy</code> or <code>sell</code>)</td>
<td>Whether the order is to buy or sell.</td>
</tr>
<tr>
<td>price</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The quoted price, denominated in total units of the counter currency per unit of the base currency</td>
</tr>
<tr>
<td>taker_pays_total</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The total amount the taker must pay to consume this order.</td>
</tr>
<tr>
<td>taker_pays_funded</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The actual amount the taker must pay to consume this order, if the order is <a href="transactions.html#lifecycle-of-an-offer">partially funded</a>.</td>
</tr>
<tr>
<td>taker_gets_total</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The total amount the taker will get once the order is consumed.</td>
</tr>
<tr>
<td>taker_gets_funded</td>
<td>String (<a href="#amount_object">Amount Object</a>)</td>
<td>The actual amount the taker will get once the order is consumed, if the order is <a href="transactions.html#lifecycle-of-an-offer">partially funded</a>.</td>
</tr>
<tr>
<td>order_maker</td>
<td>String</td>
<td>The Ripple address of the account that placed the bid or ask on the order book.</td>
</tr>
<tr>
<td>sequence</td>
<td>Number</td>
<td>The sequence number of the transaction that created the order. Used in combination with account to uniquely identify the order.</td>
</tr>
<tr>
<td>sell</td>
<td>Boolean</td>
<td>Whether the order should be <a href="https://ripple.com/build/transactions/#offercreate-flags">sell</a>.</td>
</tr>
<tr>
<td>passive</td>
<td>Boolean</td>
<td>Whether the order should be <a href="https://ripple.com/build/transactions/#offercreate-flags">passive</a>.</td>
</tr>
</tbody>
</table>
<h2 id="trustline-objects">Trustline Objects</h2>
<p>A trustline object describes a link between two accounts that allows one to hold the other's issuances. A trustline can also be two-way, meaning that each can hold balances issued by the other, but that case is less common. In other words, a trustline tracks money owed.</p>
<p>A trustline with a positive limit indicates an account accepts issuances from the other account (typically an issuing gateway) as payment, up to the limit. An account cannot receive a payment that increases its balance over that trust limit. It is possible, however, to go over a limit by either by trading currencies or by decreasing the limit while already holding a balance.</p>
<p>From the perspective of an account on one side of the trustline, the trustline has the following fields:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Value</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>account</td>
<td>String (Address)</td>
<td>This account</td>
</tr>
<tr>
<td>counterparty</td>
<td>String (Address)</td>
<td>The account at the other end of the trustline</td>
</tr>
<tr>
<td>currency</td>
<td>String</td>
<td>Currency code for the type of currency that is held on this trustline.</td>
</tr>
<tr>
<td>limit</td>
<td>String (Quoted decimal)</td>
<td>The maximum amount of currency issued by the counterparty account that this account should hold.</td>
</tr>
<tr>
<td>reciprocated_limit</td>
<td>String (Quoted decimal)</td>
<td>(Read-only) The maximum amount of currency issued by this account that the counterparty account should hold.</td>
</tr>
<tr>
<td>account_allows_rippling</td>
<td>Boolean</td>
<td>If set to false on two trustlines from the same account, payments cannot ripple between them. (See the <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">NoRipple flag</a> for details.)</td>
</tr>
<tr>
<td>counterparty_allows_rippling</td>
<td>Boolean</td>
<td>(Read-only) If false, the counterparty account has the <a href="https://ripple.com/knowledge_center/understanding-the-noripple-flag/">NoRipple flag</a> enabled.</td>
</tr>
<tr>
<td>account_trustline_frozen</td>
<td>Boolean</td>
<td>Indicates whether this account has <a href="https://wiki.ripple.com/Freeze">frozen</a> the trustline. (<code>account_froze_trustline</code> prior to <a href="https://github.com/ripple/ripple-rest/releases/tag/1.4.0">v1.4.0</a>)</td>
</tr>
<tr>
<td>counterparty_trustline_frozen</td>
<td>Boolean</td>
<td>(Read-only) Indicates whether the counterparty account has <a href="https://wiki.ripple.com/Freeze">frozen</a> the trustline. (<code>counterparty_froze_line</code> prior to <a href="https://github.com/ripple/ripple-rest/releases/tag/1.4.0">v1.4.0</a>)</td>
</tr>
</tbody>
</table>
<p>The read-only fields indicate portions of the trustline that pertain to the counterparty, and can only be changed by that account. (The <code>counterparty</code> field is technically part of the identity of the trustline. If you "change" it, that just means that you are referring to a different trustline object.)</p>
<p>A trust line with a limit <em>and</em> a balance of 0 is equivalent to no trust line.</p>
<h1 id="accounts-1">ACCOUNTS</h1>
<p>Accounts are the core unit of authentication in the Ripple Network. Each account can hold balances in multiple currencies, and all transactions must be signed by an account’s secret key. In order for an account to exist in a validated ledger version, it must hold a minimum reserve amount of XRP. (The <a href="reserves.html">account reserve</a> increases with the amount of data it is responsible for in the shared ledger.) It is expected that accounts will correspond loosely to individual users.</p>
<h2 id="generate-wallet">Generate Wallet</h2>
<p>(New in <a href="https://github.com/ripple/ripple-rest/releases/tag/1.3.0">Ripple-REST v1.3.0</a>)</p>
<p>Randomly generate keys for a potential new Ripple account.</p>
<div class="multicode">
*REST*
wzxhzdk:9
</div>
<p><a class="button" href="rest-api-tool.html#generate-wallet">Try it! ></a></p>
<p>There are two steps to making a new account on the Ripple network: randomly creating the keys for that account, and sending it enough XRP to meet the account reserve.</p>
<p>Generating the keys can be done offline, since it does not affect the network at all. To make it easy, Ripple-REST can generate account keys for you.</p>
<p><em>Caution:</em> Ripple account keys are very sensitive, since they give full control over that account's money on the Ripple network. Do not transmit them to untrusted servers, or unencrypted over the internet (for example, through HTTP instead of HTTPS). There <em>are</em> bad actors who are sniffing around for account keys so they can steal your money!</p>
<h4 id="response">Response</h4>
<p>The response is an object with the address and the secret for a potential new account:</p>
<pre><code class="js">{
"success": true,
"account": {
"address": "raqFu9wswvHYS4q5hZqZxVSYei73DQnKL8",
"secret": "shUzHiYxoXX2FgA54j42cXCZ9dTVT"
}
}
</code></pre>
<p>The second step is <a href="#payments">making a payment</a> of XRP to the new account address. (Ripple lets you send XRP to any mathematically possible account address, which creates the account if necessary.) The generated account does not exist in the ledger until it receives enough XRP to meet the account reserve.</p>
<h2 id="get-account-balances">Get Account Balances</h2>
<p><a href="https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/balances.js#L34" title="Source">[Source]<br/></a></p>
<p>Retrieve the current balances for the given Ripple account.</p>
<div class="multicode">
*REST*
wzxhzdk:11
</div>
<p><a class="button" href="rest-api-tool.html#get-account-balances">Try it! ></a></p>
<p>The following URL parameters are required by this API endpoint:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>address</td>
<td>String</td>
<td>The Ripple account address of the account whose balances to retrieve.</td>
</tr>
</tbody>
</table>
<p>Optionally, you can also include any of the following query parameters:</p>
<table>
<thead>
<tr>
<th>Field</th>
<th>Type</th>
<th>Description</th>
</tr>
</thead>
<tbody>
<tr>
<td>currency</td>
<td>String (<a href="http://www.xe.com/iso4217.php">ISO 4217 Currency Code</a>)</td>
<td>If provided, only include balances in the given currency.</td>
</tr>
<tr>
<td>counterparty</td>
<td>String (Address)</td>
<td>If provided, only include balances issued by the provided address (usually a gateway).</td>
</tr>
<tr>
<td>marker</td>
<td>String</td>
<td>Server-provided value that marks where to resume pagination.</td>
</tr>
<tr>
<td>limit</td>
<td>String (Integer or <code>all</code>)</td>
<td>(Defaults to 200) Max results per response. Cannot be less than 10. Cannot be greater than 400. Use <code>all</code> to return all results</td>
</tr>
<tr>
<td>ledger</td>
<td>String (ledger hash or sequence, or 'validated', 'current', or 'closed')</td>
<td>(Defaults to 'validated') Identifying ledger version to pull results from.</td>
</tr>
</tbody>
</table>
<p><em>Note:</em> Pagination using <code>limit</code> and <code>marker</code> requires a consistent ledger version, so you must also provide the <code>ledger</code> hash or sequence query parameter to use pagination.</p>
<p><em>Caution:</em> When an account holds balances on a very large number of trust lines, specifying <code>limit=all</code> may take a long time or even time out. If you experience timeouts, try again later, or specify a smaller limit.</p>
<h4 id="response-1">Response</h4>
<pre><code class="js">{