From a81abed071e00ffbdaddf525af386b8b79faaf6b Mon Sep 17 00:00:00 2001 From: Bo Chen Date: Mon, 8 Dec 2014 11:48:17 -0800 Subject: [PATCH] [DOC] add documentation for placing, canceling, and retrieving account orders --- content/ripplerest_api.md | 228 +++++++++++++++++++++++++++++++++++++- js/apitool-rest.js | 56 ++++++++++ rest-api-tool.html | 4 + 3 files changed, 287 insertions(+), 1 deletion(-) diff --git a/content/ripplerest_api.md b/content/ripplerest_api.md index 712df65405..79dc8bee12 100644 --- a/content/ripplerest_api.md +++ b/content/ripplerest_api.md @@ -21,6 +21,11 @@ We recommend Ripple-REST for users just getting started with Ripple, since it pr * [Confirm Payment - `GET /v1/accounts/{:address}/payments/{:id}`](#confirm-payment) * [Get Payment History - `GET /v1/accounts/{:address}/payments`](#get-payment-history) +#### Orders #### +* [Place Order - `POST /v1/accounts/{:source_address}/orders`](#place-order) +* [Cancel Order - `DELETE /v1/accounts/{:source_address}/orders/{:sequence}`](#cancel-order) +* [Get Account Orders - `GET /v1/accounts/{:address}/orders`](#get-account-orders) + #### Trustlines #### * [Get Trustlines - `GET /v1/accounts/{:address}/trustlines`](#get-trustlines) @@ -470,6 +475,19 @@ Example of the memos field: ] ``` +## Order Objects ## + +An order object describes an offer to exchange two currencies + +| Field | Value | Description | +|-------|-------|-------------| +| type | String (`buy` or `sell`) | Whether the order is to buy or sell. | +| taker_pays | String ([Amount Object](#amount_object)) | The amount the taker must pay to consume this order. | +| taker_gets | String ([Amount Object](#amount_object)) | The amount the taker will get once the order is consumed. | +| passive | Boolean | Whether the order should be [passive](https://ripple.com/build/transactions/#offercreate-flags). | +| immediate_or_cancel | Boolean | Whether the order should be [immediate or cancel](https://ripple.com/build/transactions/#offercreate-flags). | +| fill_or_kill | Boolean | Whether the order should be [fill or kill](https://ripple.com/build/transactions/#offercreate-flags). | + ## Trustline Objects ## 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. @@ -791,7 +809,7 @@ The following URL parameters are required by this API endpoint: |-------|------|-------------| | `address` | String | The Ripple address for the account that would send the payment. | | `destination_account` | String | The Ripple address for the account that would receive the payment. | -| `destination_amount` | String ([URL-formatted Amount](#amounts-in-urls) | The amount that the destination account should receive. | +| `destination_amount` | String ([URL-formatted Amount](#amounts-in-urls)) | The amount that the destination account should receive. | Optionally, you can also include the following as a query parameter: @@ -1435,7 +1453,215 @@ If the length of the `payments` array is equal to `results_per_page`, then there *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") + +Places an order on the ripple network. + +
+*REST* + +``` +POST /v1/accounts/{:address}/orders?validated=true +{ + "secret": "sneThnzgBgxc3zXPG....", + "order": { + "type": "sell", + "taker_pays": { + currency: "JPY", + issuer: "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6", + value: "4000" + }, + "taker_gets": { + currency: "USD", + issuer: "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", + value: ".25" + } + } +} +``` +
+ +[Try it! >](rest-api-tool.html#place-order) + +The following parameters are required in the JSON body of the request: + +| Field | Value | Description | +|-------|-------|-------------| +| secret | String | A secret key for your Ripple account. This is either the master secret, or a regular secret, if your account has one configured. | +| order | Object ([Order](#order-objects)) | The order to place. | + +Optionally, you can include the following as a URL query parameter: + +| Field | Type | Description | +|-------|------|-------------| +| validated | String | `true` or `false`. When set to `true`, will force the request to wait until the trustline transaction has been successfully validated by the server. A validated transaction will have the `state` attribute set to `"validated"` in the response. | + +__DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER__ -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts. + +#### Response #### + +```js +{ + "success": true, + "order": { + "hash": "71AE74B03DE3B9A06C559AD4D173A362D96B7D2A5AA35F56B9EF21543D627F34", + "ledger": "9592219", + "state": "validated", + "account": "sneThnzgBgxc3zXPG....", + "taker_pays": { + currency: "JPY", + issuer: "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6", + value: "4000" + }, + "taker_gets": { + currency: "USD", + issuer: "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", + value: ".25" + } + "fee": "0.012", + "type": "sell", + "sequence": 99 + } +} +``` + +## Cancel Order ## +*REST* + +``` +DELETE /v1/accounts/{:address}/orders?validated=true +{ + "secret": "sneThnzgBgxc3zXPG...." +} +``` + + +[Try it! >](rest-api-tool.html#cancel-order) + +The following parameters are required in the JSON body of the request: + +| Field | Value | Description | +|-------|-------|-------------| +| secret | String | A secret key for your Ripple account. This is either the master secret, or a regular secret, if your account has one configured. | + +Optionally, you can include the following as a URL query parameter: + +| Field | Type | Description | +|-------|------|-------------| +| validated | String | `true` or `false`. When set to `true`, will force the request to wait until the trustline transaction has been successfully validated by the server. A validated transaction will have the `state` attribute set to `"validated"` in the response. | + +__DO NOT SUBMIT YOUR SECRET TO AN UNTRUSTED REST API SERVER__ -- The secret key can be used to send transactions from your account, including spending all the balances it holds. For the public server, only use test accounts. + +#### Response #### + +```js +{ + "success": true, + "order": { + "hash": "71AE74B03DE3B9A06C559AD4D173A362D96B7D2A5AA35F56B9EF21543D627F34", + "ledger": "9592219", + "state": "validated", + "account": "sneThnzgBgxc3zXPG....", + "fee": "0.012", + "offer_sequence": 99, + "sequence": 100 + } +} +``` + +## Get Account Orders ## +[[Source]
](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L20 "Source") + +Retrieves all orders associated with the Ripple address. + +
+*REST* + +``` +GET /v1/accounts/{:address}/orders +``` +
+ +[Try it! >](rest-api-tool.html#get-account-orders) + +The following URL parameters are required by this API endpoint: + +| Field | Value | Description | +|-------|-------|-------------| +| address | String | The Ripple account address whose trustlines to look up. | + +Optionally, you can also include the following query parameters: + +| Field | Value | Description | +|-------|-------|-------------| +| marker | String | Start position in response paging. | +| 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. + +#### Response #### + +The response is an object with a `orders` array, where each member is a [order object](#order-objects). + +```js +{ + "success": true, + "marker": "0C812C919D343EAE789B29E8027C62C5792C22172D37EA2B2C0121D2381F80E1", + "limit": 100, + "ledger": 9592219, + "validated": true, + "orders": [ + { + "flags": 0, + "seq": 719930, + "taker_gets": { + "currency": "EUR", + "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "17.70155237781915" + }, + "taker_pays": { + "currency": "USD", + "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "1122.990930900328" + } + }, + { + "flags": 0, + "seq": 757002, + "taker_gets": { + "currency": "USD", + "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "18.46856867857617" + }, + "taker_pays": { + "currency": "USD", + "issuer": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2", + "value": "19.50899530491766" + } + }, + { + "flags": 0, + "seq": 756999, + "taker_gets": { + "currency": "USD", + "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "19.11697137482289" + }, + "taker_pays": { + "currency": "EUR", + "issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q", + "value": "750" + } + } + ] +} +``` + +*Note:* `marker` will be present in the response when there are additional pages to page through. # TRUSTLINES # diff --git a/js/apitool-rest.js b/js/apitool-rest.js index c3f9a6dfe2..a55ac914b8 100644 --- a/js/apitool-rest.js +++ b/js/apitool-rest.js @@ -63,6 +63,7 @@ $(commands).click(function() { var DEFAULT_ADDRESS_1 = "rf1BiGeXwwQoi8Z2ueFYTEXSwuJYfV2Jpn"; var DEFAULT_ADDRESS_2 = "ra5nK24KXen9AHvsdFTKHSANinZseWnPcX"; +var DEFAULT_ADDRESS_3 = "rJnZ4YHCUsHvQu7R6mZohevKJDHFzVD6Zr"; var DEFAULT_HASH = "9D591B18EDDD34F0B6CF4223A2940AEA2C3CC778925BABF289E0011CD8FA056E"; Request('Generate Wallet', { @@ -187,6 +188,61 @@ Request("Get Payment History", { } }); +Request("Place Order", { + method: POST, + path: "/v1/accounts/{:address}/orders?{:query_params}", + description: "Place an order on the ripple network.", + link: "#place-order", + test_only: true, + params: { + "{:address}": DEFAULT_ADDRESS_1, + "{:query_params}": "validated=true" + }, + body: { + "secret": "sneThnzgBgxc3zXPG....", + "order": { + "type": "sell", + "taker_pays": { + "currency": "JPY", + "value": "4000", + "issuer": "rMAz5ZnK73nyNUL4foAvaxdreczCkG3vA6" + }, + "taker_gets": { + "currency": "USD", + "value": ".25", + "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B" + }, + "immediate_or_cancel": true + } + } +}); + +Request("Cancel Order", { + method: DELETE, + path: "/v1/accounts/{:address}/orders?{:query_params}", + description: "Cancel an order on the ripple network.", + link: "#cancel-order", + test_only: true, + params: { + "{:address}": DEFAULT_ADDRESS_1, + "{:query_params}": "validated=true" + }, + body: { + "secret": "sneThnzgBgxc3zXPG...." + } +}); + +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.", + link: "#get-account-orders", + params: { + "{:address}": DEFAULT_ADDRESS_3, + "{:query_params}": "ledger=10399192&limit=15" + } +}); + Request("Get Trustlines", { method: GET, path: "/v1/accounts/{:address}/trustlines?{:query_params}", diff --git a/rest-api-tool.html b/rest-api-tool.html index e87da3775c..1f0f8cc007 100644 --- a/rest-api-tool.html +++ b/rest-api-tool.html @@ -90,6 +90,10 @@
  • Confirm Payment
  • Get Payment History

    • +
  • Place Order
    • +
  • Cancel Order
    • +
  • Get Account Orders
    • +
  • Get Trustlines
  • Grant Trustline