ARCHIVE/xrpl-dev-portal
1
0
Fork 0
mirror of https://github.com/XRPLF/xrpl-dev-portal.git synced 2025-11-29 16:15:48 +00:00
Code Issues Packages Projects Releases Wiki Activity

[DOC] add documentation for placing, canceling, and retrieving account orders

Browse Source
This commit is contained in:
Bo Chen
2014-12-08 11:48:17 -08:00
parent 12483174e3
commit a81abed071
3 changed files with 287 additions and 1 deletions
Download Patch File Download Diff File Expand all files Collapse all files

228
content/ripplerest_api.md
View File

@@ -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]<br>](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L110 "Source")
Places an order on the ripple network.
<div class='multicode'>
*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"
}
}
}
```
</div>
[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...."
}
```
</div>
[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]<br>](https://github.com/ripple/ripple-rest/blob/develop/api/orders.js#L20 "Source")
Retrieves all orders associated with the Ripple address.
<div class='multicode'>
*REST*
```
GET /v1/accounts/{:address}/orders
```
</div>
[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 #