From df7e0a1dbfe740896f4f1354e35a31a6757eb445 Mon Sep 17 00:00:00 2001 From: Alan Cohen Date: Sun, 8 Feb 2015 16:19:34 -0800 Subject: [PATCH] [REST] Update API docs to add `Get Order Transaction` - Updates Payments API - Adds a new response object `Order Change` to describe changes to orders in the order book - Update all source code URLs to permalinks - --- content/ripplerest_api.md | 864 +++++++++++++++----------------------- js/apitool-rest.js | 13 +- rest-api-tool.html | 1 + 3 files changed, 362 insertions(+), 516 deletions(-) diff --git a/content/ripplerest_api.md b/content/ripplerest_api.md index 12474ab58d..6a8ef5293b 100644 --- a/content/ripplerest_api.md +++ b/content/ripplerest_api.md @@ -22,10 +22,12 @@ We recommend Ripple-REST for users just getting started with Ripple, since it pr * [Get Payment History - `GET /v1/accounts/{:address}/payments`](#get-payment-history) #### Orders #### + * [Place Order - `POST /v1/accounts/{:address}/orders`](#place-order) * [Cancel Order - `DELETE /v1/accounts/{:address}/orders/{:sequence}`](#cancel-order) * [Get Account Orders - `GET /v1/accounts/{:address}/orders`](#get-account-orders) * [Get Order Book - `GET /v1/accounts/{:address}/order_book/{:base}/{:counter}`](#get-order-book) +* [Get Order Transaction - `GET /v1/accounts{:address}/orders/{:hash}`](#get-order) #### Trustlines #### @@ -239,22 +241,6 @@ openssl x509 -req -days 730 -in /etc/ssl/server.csr -signkey /etc/ssl/private/se ### Keeping the service running ### -To make sure that the Ripple-REST process remains active even if it crashes for some reason, use the [`forever`](https://www.npmjs.org/package/forever) Node module. Install `forever` using `sudo npm install -g forever`. - -Here is an example of running `ripple-rest` using `forever`: - -``` -forever start \ - --pidFile /var/run/ripple-rest/ripple-rest.pid \ - --sourceDir /opt/ripple-rest \ - -a -o /var/log/ripple-rest/ripple-rest.log \ - -e /var/log/ripple-rest/ripple-rest.err \ - -l /var/log/ripple-rest/ripple-rest.for \ - server.js -``` - -### Monitoring the service ### - Monitor `ripple-rest` using [`monit`](http://mmonit.com/monit/). On Ubuntu you can install `monit` using `sudo apt-get install monit`. Here is an example of a monit script that will restart the server if: @@ -276,7 +262,6 @@ check process ripple-rest with pidfile /var/run/ripple-rest/ripple-rest.pid - # Formatting Conventions # The `ripple-rest` API conforms to the following general behavior for [RESTful API](http://en.wikipedia.org/wiki/Representational_state_transfer): @@ -452,7 +437,7 @@ The fields of a Payment object are defined as follows: Submitted transactions can have additional fields reflecting the current status and outcome of the transaction, including: -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/payments.js#L346 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/lib/tx-to-rest-converter.js#L25 "Source") | Field | Type | Description | |-------|------|-------------| @@ -511,6 +496,18 @@ An order object describes an offer to exchange two currencies. Order objects are | immediate\_or\_cancel | Boolean | Whether the order should be [immediate or cancel](transactions.html#offercreate-flags). | | fill\_or\_kill | Boolean | Whether the order should be [fill or kill](transactions.html#offercreate-flags). | +## Order Change Objects ## + +An order change object describes the changes to to a Ripple account's open order due to a transaction. + +| Field | Value | Description | +|-------|-------|-------------| +| type | String (`buy` or `sell`) | Whether the order is to buy or sell. | +| taker\_pays | String ([Amount Object](#amount_object)) | The `value` of the amount is expressed as the difference between the final amount and original amount. | +| taker\_gets | String ([Amount Object](#amount_object)) | The `value` of the amount is expressed as the difference between the final amount and original amount. | +| sequence | Number | The sequence number of the transaction that created the order. Used in combination with account to uniquely identify the order. | +| status | String(`created`, `closed`, `canceled`, `open`) | The status of the order on the ledger. An order that is partially filled has the status `open`. | + ## Bid Objects ## @@ -601,7 +598,7 @@ The second step is [making a payment](#payments) of XRP to the new account addre ## Get Account Balances ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/balances.js#L9 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/balances.js#L34 "Source") Retrieve the current balances for the given Ripple account. @@ -732,7 +729,7 @@ The response contains a `settings` object, with the following fields: ## Update Account Settings ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/settings.js#L97 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/settings.js#L135 "Source") Modify the existing settings for an account. @@ -828,9 +825,8 @@ The response is a JSON object containing the following fields: `ripple-rest` provides access to `ripple-lib`'s robust transaction submission processes. This means that it will set the fee, manage the transaction sequence numbers, sign the transaction with your secret, and resubmit the transaction up to 10 times if `rippled` reports an initial error that can be solved automatically. - ## Prepare Payment ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/payments.js#L538 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/payments.js#L484 "Source") Get quotes for possible ways to make a particular payment. @@ -921,7 +917,7 @@ __NOTE:__ This command may be quite slow. If the command times out, please try i ## Submit Payment ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/payments.js#L43 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/payments.js#L52 "Source") Submit a payment object to be processed and executed. @@ -960,6 +956,7 @@ POST /v1/accounts/{address}/payments?validated=true } } ``` + [Try it! >](rest-api-tool.html#submit-payment) @@ -1017,7 +1014,7 @@ The response can take two formats, depending on the `validated` query parameter: ## Confirm Payment ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/payments.js#L232 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/payments.js#L270 "Source") Retrieve the details of a payment, including the current state of the transaction and the result of transaction processing. @@ -1099,7 +1096,7 @@ Processing a payment can take several seconds to complete, depending on the [con ## Get Payment History ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/master/api/payments.js#L460 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/a268d7058b9bf20d48a1b61d86093756e5274512/api/payments.js#L394 "Source") Retrieve a selection of payments that affected the specified account. @@ -1140,389 +1137,83 @@ Optionally, you can also include the following query parameters: "success": true, "payments": [ { - "client_resource_id": "", "payment": { - "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", + "source_account": "rBvktWhzs4MQDaFYScsqPCB5YufRDXwKDC", "source_tag": "", "source_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" + "value": "1166313.057", + "currency": "JPY", + "issuer": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN" }, "source_slippage": "0", - "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", + "destination_account": "rBvktWhzs4MQDaFYScsqPCB5YufRDXwKDC", "destination_tag": "", "destination_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "outgoing", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "9018940", - "hash": "FED24FB85E5682E5FD03D2FFA047E1CE9F284671BCD82007C64B3FE735DD69B0", - "timestamp": "2014-09-23T19:20:20.000Z", - "fee": "0.000012", - "source_balance_changes": [ - { - "value": "-0.000012", - "currency": "XRP", - "issuer": "" - }, - { - "value": "-1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ], - "destination_balance_changes": [ - { - "value": "1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "source_tag": "", - "source_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "source_slippage": "0", - "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "destination_tag": "", - "destination_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "outgoing", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "9018905", - "hash": "63BCCAFA0D6D56B2F914B5933D7FABCD25925450F0675179E836D12DFA530C28", - "timestamp": "2014-09-23T19:17:30.000Z", - "fee": "0.000012", - "source_balance_changes": [ - { - "value": "-0.000012", - "currency": "XRP", - "issuer": "" - }, - { - "value": "-1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ], - "destination_balance_changes": [ - { - "value": "1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "source_tag": "", - "source_amount": { - "value": "0.00001", - "currency": "XRP", - "issuer": "" - }, - "source_slippage": "0", - "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "destination_tag": "", - "destination_amount": { - "currency": "USD", - "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc", - "value": "0.01" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": true, - "direction": "outgoing", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "8924146", - "hash": "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E", - "timestamp": "2014-09-17T21:47:00.000Z", - "fee": "0.00001", - "source_balance_changes": [ - { - "value": "-0.00002", - "currency": "XRP", - "issuer": "" - } - ], - "destination_balance_changes": [ - { - "value": "5.08e-8", - "currency": "USD", - "issuer": "rsP3mgGb2tcYUrxiLFiHJiQXhsziegtwBc" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "source_tag": "", - "source_amount": { - "value": "1", - "currency": "XRP", - "issuer": "" - }, - "source_slippage": "0", - "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "destination_tag": "", - "destination_amount": { - "value": "1", + "value": "600000", "currency": "XRP", "issuer": "" }, "invoice_id": "", - "paths": "[]", + "paths": "[[{\"currency\":\"XRP\",\"type\":16,\"type_hex\":\"0000000000000010\"}]]", "no_direct_ripple": false, "partial_payment": false, - "direction": "incoming", - "state": "validated", + "direction": "passthrough", "result": "tesSUCCESS", - "ledger": "8889845", - "hash": "8496C20AEB453803CB80474B59AB1E8FAA26725561EFF5AF41BD588B325AFBA8", - "timestamp": "2014-09-15T20:01:40.000Z", - "fee": "0.000012", + "timestamp": "2015-02-06T03:59:30.000Z", + "fee": "0.012", "source_balance_changes": [ { - "value": "-1.000012", - "currency": "XRP", - "issuer": "" - } - ], - "destination_balance_changes": [ - { - "value": "1", - "currency": "XRP", - "issuer": "" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "source_tag": "", - "source_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "source_slippage": "0", - "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "destination_tag": "", - "destination_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "incoming", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "8889826", - "hash": "4C9FA63D9F87AFC7E1BBD7F2644A1D4BD7537E833B1A945E27E5EC19F3B4B271", - "timestamp": "2014-09-15T20:00:10.000Z", - "fee": "0.000012", - "source_balance_changes": [ - { - "value": "-0.000012", - "currency": "XRP", - "issuer": "" + "currency": "JPY", + "value": "-1164533.852420654", + "issuer": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN" }, { - "value": "-1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ], - "destination_balance_changes": [ - { - "value": "1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "source_tag": "", - "source_amount": { - "value": "30", - "currency": "XRP", - "issuer": "" - }, - "source_slippage": "0", - "destination_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "destination_tag": "", - "destination_amount": { - "value": "30", - "currency": "XRP", - "issuer": "" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "incoming", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "8889256", - "hash": "72549F0CB04C8C5F30F64256A4EBDE577B1943382AE44347F05FF70590FF7CCB", - "timestamp": "2014-09-15T19:14:50.000Z", - "fee": "0.000012", - "source_balance_changes": [ - { - "value": "-30.000012", "currency": "XRP", + "value": "599999.988", "issuer": "" } ], "destination_balance_changes": [ { - "value": "30", - "currency": "XRP", - "issuer": "" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "source_tag": "", - "source_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "source_slippage": "0", - "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "destination_tag": "", - "destination_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "outgoing", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "8803725", - "hash": "6A6E503211A32F7AB92FE747A8AD2759A1E597055CB8961F0B2FEDE3A53975AB", - "timestamp": "2014-09-10T23:22:20.000Z", - "fee": "0.000015", - "source_balance_changes": [ - { - "value": "-0.000015", - "currency": "XRP", - "issuer": "" + "currency": "JPY", + "value": "-1164533.852420654", + "issuer": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN" }, { - "value": "-1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ], - "destination_balance_changes": [ - { - "value": "1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" - } - ] - } - }, - { - "client_resource_id": "", - "payment": { - "source_account": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "source_tag": "", - "source_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "source_slippage": "0", - "destination_account": "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX", - "destination_tag": "", - "destination_amount": { - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn", - "value": "1" - }, - "invoice_id": "", - "paths": "[]", - "no_direct_ripple": false, - "partial_payment": false, - "direction": "outgoing", - "state": "validated", - "result": "tesSUCCESS", - "ledger": "8711125", - "hash": "82230B9D489370504B39BC2CE46216176CAC9E752E5C1774A8CBEC9FBB819208", - "timestamp": "2014-09-05T19:59:50.000Z", - "fee": "0.00001", - "source_balance_changes": [ - { - "value": "-0.00001", "currency": "XRP", + "value": "599999.988", "issuer": "" - }, - { - "value": "-1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" } ], - "destination_balance_changes": [ + "order_changes": [ { - "value": "1", - "currency": "USD", - "issuer": "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn" + "taker_pays": { + "currency": "JPY", + "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN", + "value": "-67605.3" + }, + "taker_gets": { + "currency": "XRP", + "counterparty": "", + "value": "-34300" + }, + "sequence": 3751, + "status": "closed" + } + ], + "memos": [ + { + "MemoType": "636C69656E74", + "MemoFormat": "7274312E332E31", + "parsed_memo_type": "client", + "parsed_memo_format": "rt1.3.1" } ] - } + }, + "client_resource_id": "", + "hash": "E485D1E18D946ACD410AD79F51E2C57E887CC206286E6CE0A1CA80FC75C24643", + "ledger": "11547185", + "state": "validated" } ] } @@ -1530,13 +1221,20 @@ Optionally, you can also include the following query parameters: If the length of the `payments` array is equal to `results_per_page`, then there may be more results. To get them, increment the `page` query paramter and run the request again. -*Note:* It is not more efficient to specify more filter values, because Ripple-REST has to retrieve the full list of payments from the `rippled` before it can filter them. +The `payment` objects include additional transactional metadata: +| Field | Type | Description | +|-------|------|-------------| +| source_balance_changes | Amount | The balance changes of the Ripple address that submitted the payment | +| destination_balance_changes | Amount | The balance changes of the Ripple address that received the payment | +| order_changes | Order | The changes in the orders of the perspective account | + +*Note:* It is not more efficient to specify more filter values, because Ripple-REST has to retrieve the full list of payments from the `rippled` before it can filter them. # ORDERS # ## Place Order ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L110 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/api/orders.js#L161 "Source") (New in [Ripple-REST v1.3.2](https://github.com/ripple/ripple-rest/releases/tag/1.3.2-rc4)) @@ -1619,8 +1317,7 @@ __DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER__ -- The secret key ``` ## Cancel Order ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L243 "Source") -(New in [Ripple-REST v1.3.2](https://github.com/ripple/ripple-rest/releases/tag/1.3.2-rc4)) +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/api/orders.js#L250 "Source") Deletes a previous order to exchange currencies. @@ -1680,11 +1377,9 @@ __DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER__ -- The secret key ``` ## Get Account Orders ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L20 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/api/orders.js#L38 "Source") -(New in [Ripple-REST v1.3.2](https://github.com/ripple/ripple-rest/releases/tag/1.3.2-rc4)) - -Retrieves all currency-exchange orders associated with the Ripple address. +Retrieves all open currency-exchange orders associated with the Ripple address.
@@ -1712,7 +1407,7 @@ Optionally, you can also include the following query parameters: | limit | String (Integer) | (Defaults to 200) Max results per response. Cannot be less than 10. Cannot be greater than 400. | | ledger | String | Ledger to request paged results from. Use the ledger's hash. | -*Note:* Pagination using `limit` and `marker` requires a consistent ledger version, so you must also provide the `ledger` query parameter to use pagination. +*Note:* Pagination using `limit` and `marker` requires a consistent ledger version, so you must also provide the `ledger` query parameter to use pagination. `marker` will be present in the response when there are additional pages to page through. #### Response #### @@ -1721,159 +1416,298 @@ The response is an object with a `orders` array, where each member is a [order o ```js { "success": true, - "marker": "DF5DE453A6531A542988861F250376A0C284C2C829DEE0ABC22D663EAFC270F9", - "limit": 10, - "ledger": 11082531, + "ledger": 11561783, "validated": true, - "orders": [{ - "taker_gets": { - "currency": "EUR", - "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "value": "2500" + "orders": [ + { + "type": "buy", + "taker_gets": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "11205.2494363431" + }, + "taker_pays": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "9933.731769807718" + }, + "sequence": 11, + "passive": false }, - "taker_pays": { - "currency": "USD", - "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "value": "3750" + { + "type": "sell", + "taker_gets": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "9229.29" + }, + "taker_pays": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "10447.55628" + }, + "sequence": 12, + "passive": false }, - "sequence": 105955, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "CHF", - "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "47" + { + "type": "buy", + "taker_gets": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "5600" + }, + "taker_pays": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "5000" + }, + "sequence": 13, + "passive": false }, + { + "type": "buy", + "taker_gets": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "4.7" + }, + "taker_pays": { + "currency": "XRP", + "counterparty": "", + "value": "997.876857" + }, + "sequence": 14, + "passive": false + }, + { + "type": "sell", + "taker_gets": { + "currency": "XRP", + "counterparty": "", + "value": "999" + }, + "taker_pays": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "4.74525" + }, + "sequence": 15, + "passive": false + }, + { + "type": "buy", + "taker_gets": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "5.35" + }, + "taker_pays": { + "currency": "XRP", + "counterparty": "", + "value": "998.134328" + }, + "sequence": 16, + "passive": false + }, + { + "type": "sell", + "taker_gets": { + "currency": "XRP", + "counterparty": "", + "value": "999" + }, + "taker_pays": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "5.96403" + }, + "sequence": 17, + "passive": false + }, + { + "type": "buy", + "taker_gets": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "1103.64" + }, + "taker_pays": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "976.6725663716827" + }, + "sequence": 18, + "passive": false + }, + { + "type": "sell", + "taker_gets": { + "currency": "USD", + "counterparty": "rDZBotqkN4MywSxm9HDtX4m7V6SRkFo7By", + "value": "986.89" + }, + "taker_pays": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "1116.17259" + }, + "sequence": 19, + "passive": false + }, + { + "type": "sell", + "taker_gets": { + "currency": "USD", + "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "2" + }, + "taker_pays": { + "currency": "CAD", + "counterparty": "rLr7umFScvEZnj3AJzzZjm25yCZYh3tMwc", + "value": "2" + }, + "sequence": 21, + "passive": false + } + ] +} + +``` + +## Get Order Transaction ## +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/api/orders.js#L505 "Source") + +Get the details of an order transaction. An order transaction either [places an order](#place-order) or [cancels an order](#cancel-order). + + +
+*REST* + +``` +GET /v1/accounts/{:address}/orders/{:hash} +``` +
+ +[Try it! >](rest-api-tool.html#get-order-transaction) + +The following URL parameters are required by this API endpoint: + +| Field | Value | Description | +|-------|-------|-------------| +| address | String | The Ripple account address whose orders to look up. | +| hash | String | The transaction hash for the order | + + +#### Response #### + +An example response for an order transaction to place an order: + +```js +{ + "success": true, + "hash": "D53A3B99AC0C3CAF35D72178390ACA94CD42479A98CEA438EEAFF338E5FEB76D", + "ledger": 11349675, + "validated": true, + "timestamp": "2015-01-26T17:49:30.000Z", + "fee": "0.012", + "action": "order_create", + "direction": "outgoing", + "order": { + "account": "rEQWVz1qN4DWw5J17s3DgXQzUuVYDSpK6M", "taker_pays": { "currency": "XRP", "counterparty": "", - "value": "4700" + "value": "10000000" }, - "sequence": 106858, - "passive": false, - "sell": false - }, { "taker_gets": { + "currency": "JPY", + "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN", + "value": "0.0001" + }, + "passive": false, + "immediate_or_cancel": false, + "fill_or_kill": false, + "type": "buy", + "sequence": 26 + }, + "balance_changes": [ + { + "counterparty": "", + "currency": "XRP", + "value": "-0.012" + } + ], + "order_changes": [ + { + "taker_pays": { + "currency": "XRP", + "counterparty": "", + "value": "10000000" + }, + "taker_gets": { + "currency": "JPY", + "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN", + "value": "0.0001" + }, + "sequence": 26, + "status": "created" + } + ] +} + +``` + +An example response for an order transaction that cancels an order: + +```js +{ + "success": true, + "hash": "3D948699072B40312AE313E7E8297EED83080C9A4D5B564BCACF0951ABF00AC5", + "ledger": 11236693, + "validated": true, + "timestamp": "2015-01-20T21:46:00.000Z", + "fee": "0.012", + "action": "order_cancel", + "direction": "outgoing", + "order": { + "account": "rEQWVz1qN4DWw5J17s3DgXQzUuVYDSpK6M", + "type": "cancel", + "sequence": 22, + "cancel_sequence": 20 + }, + "balance_changes": [{ + "counterparty": "", + "currency": "XRP", + "value": "-0.012" + }], + "order_changes": [{ + "taker_pays": { "currency": "XRP", "counterparty": "", - "value": "10996.534297" + "value": "0" }, - "taker_pays": { - "currency": "BTC", - "counterparty": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn", - "value": "0.99968493609091" - }, - "sequence": 105993, - "passive": false, - "sell": false - }, { "taker_gets": { - "currency": "BTC", - "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "value": "19.32" + "currency": "JPY", + "counterparty": "r94s8px6kSw1uZ1MV98dhSRTvc6VMPoPcN", + "value": "0" }, - "taker_pays": { - "currency": "BTC", - "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "21" - }, - "sequence": 106880, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "BTC", - "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "21" - }, - "taker_pays": { - "currency": "BTC", - "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "value": "22.47" - }, - "sequence": 106066, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "XRP", - "counterparty": "", - "value": "102058.710535" - }, - "taker_pays": { - "currency": "MXN", - "counterparty": "rG6FZ31hDHN1K5Dkbma3PSB5uVCuVVRzfn", - "value": "44373.35240666822" - }, - "sequence": 105962, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "XRP", - "counterparty": "", - "value": "450000" - }, - "taker_pays": { - "currency": "USD", - "counterparty": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", - "value": "15000" - }, - "sequence": 105963, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "XRP", - "counterparty": "", - "value": "17000" - }, - "taker_pays": { - "currency": "CAD", - "counterparty": "r3ADD8kXSUKHd6zTCKfnKT3zV9EZHjzp1S", - "value": "500" - }, - "sequence": 105964, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "XRP", - "counterparty": "", - "value": "28000" - }, - "taker_pays": { - "currency": "CAD", - "counterparty": "r3ADD8kXSUKHd6zTCKfnKT3zV9EZHjzp1S", - "value": "1000" - }, - "sequence": 105965, - "passive": false, - "sell": false - }, { - "taker_gets": { - "currency": "XRP", - "counterparty": "", - "value": "255000" - }, - "taker_pays": { - "currency": "USD", - "counterparty": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", - "value": "7500" - }, - "sequence": 105966, - "passive": false, - "sell": false + "sequence": 20, + "status": "canceled" }] } ``` +The response includes the original [`order`](#order-objects), if the `action` is `order_create`. +For transactions that cancel orders, the `order` object describes the transaction that canceled the original order. +The response also includes `balance_changes` and [`order changes`](order-change-objects) +for the perspective account (e.g., the Ripple account address used in the URI). + +The `direction` of the transaction is either `incoming`, `outgoing` or `unaffected`. Outgoing transactions are made by the perspective account. Incoming transactions affect the perspective account. ## Get Order Book ## -[[Source]
](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L20 "Source") +[[Source]
](https://github.com/ripple/ripple-rest/blob/59ea02d634ac4a308db2ba21781efbc02f5ccf53/api/orders.js#L38 "Source") Retrieves the top of the order book for a currency pair. diff --git a/js/apitool-rest.js b/js/apitool-rest.js index b3ec113051..d0d50890b9 100644 --- a/js/apitool-rest.js +++ b/js/apitool-rest.js @@ -237,7 +237,7 @@ Request("Cancel Order", { Request("Get Account Orders", { method: GET, path: "/v1/accounts/{:address}/orders?{:query_params}", - description: "Check the status of one or more orders attached to an account.", + description: "Get open currency-exchange orders associated with the Ripple address.", link: "#get-account-orders", params: { "{:address}": DEFAULT_ADDRESS_3, @@ -245,6 +245,17 @@ Request("Get Account Orders", { } }); +Request("Get Order Transaction", { + method: GET, + path: "/v1/accounts/{:address}/orders/{:hash}", + description: "Get the details of an order transaction.", + link: "#get-order-transaction", + params: { + "{:address}": "rEQWVz1qN4DWw5J17s3DgXQzUuVYDSpK6M", + "{:hash}": "D53A3B99AC0C3CAF35D72178390ACA94CD42479A98CEA438EEAFF338E5FEB76D" + } +}); + Request("Get Order Book", { method: GET, path: "/v1/accounts/{:address}/order_book/{:base}/{:counter}?{:query_params}", diff --git a/rest-api-tool.html b/rest-api-tool.html index 9a43944667..ba6e0e57d8 100644 --- a/rest-api-tool.html +++ b/rest-api-tool.html @@ -99,6 +99,7 @@
  • Place Order
  • Cancel Order
  • Get Account Orders
    • +
  • Get Order Transaction
  • Get Order Book

  • Get Trustlines