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

References general file structure (methods)

Browse Source
This commit is contained in:
mDuo13
2018-05-03 15:28:40 -07:00
parent c072b2622c
commit 48391ba3d5
99 changed files with 297 additions and 324 deletions
Download Patch File Download Diff File Expand all files Collapse all files

184
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/book_offers.md Normal file
View File

@@ -0,0 +1,184 @@
## book_offers
[[Source]<br>](https://github.com/ripple/rippled/blob/develop/src/ripple/rpc/handlers/BookOffers.cpp "Source")
The `book_offers` method retrieves a list of offers, also known as the [order book](http://www.investopedia.com/terms/o/order-book.asp), between two currencies. If the results are very large, a partial result is returned with a marker so that later requests can resume from where the previous one left off.
#### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 4,
"command": "book_offers",
"taker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"taker_gets": {
"currency": "XRP"
},
"taker_pays": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
},
"limit": 10
}
```
*JSON-RPC*
```
{
"method": "book_offers",
"params": [
{
"taker": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"taker_gets": {
"currency": "XRP"
},
"taker_pays": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
},
"limit": 10
}
]
}
```
*Commandline*
```
#Syntax: book_offers taker_pays taker_gets [taker [ledger [limit] ] ]
rippled book_offers 'USD/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B' 'EUR/rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B'
```
<!-- MULTICODE_BLOCK_END -->
[Try it! >](ripple-api-tool.html#book_offers)
The request includes the following parameters:
| `Field` | Type | Description |
|:---------------|:-------------------------------------------|:-------------------------------|
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) |
| `limit` | Unsigned Integer | _(Optional)_ If provided, the server does not provide more than this many offers in the results. The total number of results returned may be fewer than the limit, because the server omits unfunded offers. |
| `marker` | [(Not Specified)](#markers-and-pagination) | _(Optional)_ Value from a previous paginated response. Resume retrieving data where that response left off. |
| `taker` | String | _(Optional)_ The [Address][] of an account to use as a perspective. [Unfunded offers](reference-transaction-format.html#lifecycle-of-an-offer) placed by this account are always included in the response. (You can use this to look up your own orders to cancel them.) |
| `taker_gets` | Object | Specification of which currency the account taking the offer would receive, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts](#specifying-currency-amounts). |
| `taker_pays` | Object | Specification of which currency the account taking the offer would pay, as an object with `currency` and `issuer` fields (omit issuer for XRP), like [currency amounts](#specifying-currency-amounts). |
#### Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 11,
"status": "success",
"type": "response",
"result": {
"ledger_current_index": 7035305,
"offers": [
{
"Account": "rM3X3QSr8icjTGpaF52dozhbT2BZSXJQYM",
"BookDirectory": "7E5F614417C2D0A7CEFEB73C4AA773ED5B078DE2B5771F6D55055E4C405218EB",
"BookNode": "0000000000000000",
"Flags": 0,
"LedgerEntryType": "Offer",
"OwnerNode": "0000000000000AE0",
"PreviousTxnID": "6956221794397C25A53647182E5C78A439766D600724074C99D78982E37599F1",
"PreviousTxnLgrSeq": 7022646,
"Sequence": 264542,
"TakerGets": {
"currency": "EUR",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "17.90363633316433"
},
"TakerPays": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "27.05340557506234"
},
"index": "96A9104BF3137131FF8310B9174F3B37170E2144C813CA2A1695DF2C5677E811",
"quality": "1.511056473200875"
},
{
"Account": "rhsxKNyN99q6vyYCTHNTC1TqWCeHr7PNgp",
"BookDirectory": "7E5F614417C2D0A7CEFEB73C4AA773ED5B078DE2B5771F6D5505DCAA8FE12000",
"BookNode": "0000000000000000",
"Flags": 131072,
"LedgerEntryType": "Offer",
"OwnerNode": "0000000000000001",
"PreviousTxnID": "8AD748CD489F7FF34FCD4FB73F77F1901E27A6EFA52CCBB0CCDAAB934E5E754D",
"PreviousTxnLgrSeq": 7007546,
"Sequence": 265,
"TakerGets": {
"currency": "EUR",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "2.542743233917848"
},
"TakerPays": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "4.19552633596446"
},
"index": "7001797678E886E22D6DE11AF90DF1E08F4ADC21D763FAFB36AF66894D695235",
"quality": "1.65"
}
]
}
}
```
*JSON-RPC*
```
200 OK
{
"result": {
"ledger_current_index": 8696243,
"offers": [],
"status": "success",
"validated": false
}
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
| `Field` | Type | Description |
|:-----------------------|:-------------------------------------------|:------------------------------------------|
| `ledger_current_index` | Integer | (Omitted if ledger version provided) Sequence number of the ledger version used when retrieving this data. |
| `ledger_index` | Integer | (Omitted if ledger\_current\_index provided instead) Sequence number, provided in the request, of the ledger version that was used when retrieving this data. |
| `ledger_hash` | String | (May be omitted) Hex hash, provided in the request, of the ledger version that was used when retrieving this data. |
| `marker` | [(Not Specified)](#markers-and-pagination) | (May be omitted) Server-defined value indicating the response is paginated. Pass this to the next call to resume where this call left off. Omitted when there are no pages of information after this one. |
| `offers` | Array | Array of offer objects, each of which has the fields of an [OfferCreate transaction](reference-transaction-format.html#offercreate) |
In addition to the standard Offer fields, the following fields may be included in members of the `offers` array:
| `Field` | Type | Description |
|:--------------------|:---------------------------------|:--------------------|
| `owner_funds` | String | Amount of the TakerGets currency the side placing the offer has available to be traded. (XRP is represented as drops; any other currency is represented as a decimal value.) If a trader has multiple offers in the same book, only the highest-ranked offer includes this field. |
| `taker_gets_funded` | String (XRP) or Object (non-XRP) | (Only included in partially-funded offers) The maximum amount of currency that the taker can get, given the funding status of the offer. |
| `taker_pays_funded` | String (XRP) or Object (non-XRP) | (Only included in partially-funded offers) The maximum amount of currency that the taker would pay, given the funding status of the offer. |
| `quality` | Number | The exchange rate, as the ratio `taker_pays` divided by `taker_gets`. For fairness, offers that have the same quality are automatically taken first-in, first-out. (In other words, if multiple people offer to exchange currency at the same rate, the oldest offer is taken first.) |
#### Possible Errors
* Any of the [universal error types](#universal-errors).
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `lgrNotFound` - The ledger specified by the `ledger_hash` or `ledger_index` does not exist, or it does exist but the server does not have it.
* `srcCurMalformed` - The `taker_pays` field in the request is not formatted properly.
* `dstAmtMalformed` - The `taker_gets` field in the request is not formatted properly.
* `srcIsrMalformed` - The `issuer` field of the `taker_pays` field in the request is not valid.
* `dstIsrMalformed` - The `issuer` field of the `taker_gets` field in the request is not valid.
* `badMarket` - The desired order book does not exist; for example, offers to exchange a currency for itself.

579
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/path_find.md Normal file
View File

@@ -0,0 +1,579 @@
## path_find
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp "Source")
*WebSocket API only!* The `path_find` method searches for a [path](concept-paths.html) along which a transaction can possibly be made, and periodically sends updates when the path changes over time. For a simpler version that is supported by JSON-RPC, see [`ripple_path_find`](#ripple-path-find). For payments occurring strictly in XRP, it is not necessary to find a path, because XRP can be sent directly to any account.
There are three different modes, or sub-commands, of the path_find command. Specify which one you want with the `subcommand` parameter:
* `create` - Start sending pathfinding information
* `close` - Stop sending pathfinding information
* `status` - Get the information of the currently-open pathfinding request
Although the `rippled` server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths. Due to server load, pathfinding may not find the best results. Additionally, you should be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results. (**Note:** A server returning less-than-optimal results is not necessarily proof of malicious behavior; it could also be a symptom of heavy server load.)
### path_find create
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L38 "Source")
The `create` subcommand of `path_find` creates an ongoing request to find possible paths along which a payment transaction could be made from one specified account such that another account receives a desired amount of some currency. The initial response contains a suggested path between the two addresses that would result in the desired amount being received. After that, the server sends additional messages, with `"type": "path_find"`, with updates to the potential paths. The frequency of updates is left to the discretion of the server, but it usually means once every few seconds when there is a new ledger version.
A client can only have one pathfinding request open at a time. If another pathfinding request is already open on the same connection, the old request is automatically closed and replaced with the new request.
#### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 8,
"command": "path_find",
"subcommand": "create",
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_amount": {
"value": "0.001",
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
}
}
```
<!-- MULTICODE_BLOCK_END -->
[Try it! >](ripple-api-tool.html#path_find)
The request includes the following parameters:
| `Field` | Type | Description |
|:----------------------|:-----------------|:----------------------------------|
| `subcommand` | String | Use `"create"` to send the create subcommand |
| `source_account` | String | Unique address of the account to find a path from. (In other words, the account that would be sending a payment.) |
| `destination_account` | String | Unique address of the account to find a path to. (In other words, the account that would receive a payment.) |
| `destination_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the destination account would receive in a transaction. **Special case:** [New in: rippled 0.30.0][] You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency amount](#specifying-currency-amounts) that would be spent in the transaction. Not compatible with `source_currencies`. [New in: rippled 0.30.0][] |
| `paths` | Array | _(Optional)_ Array of arrays of objects, representing [payment paths](concept-paths.html) to check. You can use this to keep updated on changes to particular paths you already know about, or to check the overall cost to make a payment along a certain path. |
The server also recognizes the following fields, but the results of using them are not guaranteed: `source_currencies`, `bridges`. These fields should be considered reserved for future use.
#### Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 1,
"status": "success",
"type": "response",
"result": {
"alternatives": [
{
"paths_computed": [
[
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "r9vbV3EHvXWjSkeQ6CAcYVPGeq7TuiXY2X",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": "251686"
},
{
"paths_computed": [
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "BTC",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.000001541291269274307"
}
},
{
"paths_computed": [
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "CHF",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.0009211546262510451"
}
},
{
"paths_computed": [
[
{
"account": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "razqQKzJRdB4UxFPWf5NEpEG3WMkmwgcXA",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "CNY",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.006293562"
}
},
{
"paths_computed": [
[
{
"account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rGwUWgN5BEg3QGNY3RX2HfYowjUTZdid3E",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rMwjYedjc7qqtKYVLiAccJSmCwih4LnE2q",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "DYM",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.0007157142857142858"
}
},
{
"paths_computed": [
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "EUR",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.0007409623616236163"
}
},
{
"paths_computed": [
[
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
},
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": {
"currency": "JPY",
"issuer": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"value": "0.103412412"
}
}
],
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_amount": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "0.001"
},
"id": 1,
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"full_reply": false
}
}
```
<!-- MULTICODE_BLOCK_END -->
The initial response follows the [standard format](#response-formatting), with a successful result containing the following fields:
| `Field` | Type | Description |
|:----------------------|:-----------------|:----------------------------------|
| `alternatives` | Array | Array of objects with suggested [paths](concept-paths.html) to take, as described below. If empty, then no paths were found connecting the source and destination accounts. |
| `destination_account` | String | Unique address of the account that would receive a transaction |
| `destination_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the destination would receive in a transaction |
| `id` | (Various) | (WebSocket only) The ID provided in the WebSocket request is included again at this level. |
| `source_account` | String | Unique address that would send a transaction |
| `full_reply` | Boolean | If `false`, this is the result of an incomplete search. A later reply may have a better path. If `true`, then this is the best path found. (It is still theoretically possible that a better path could exist, but `rippled` won't find it.) Until you close the pathfinding request, `rippled` continues to send updates each time a new ledger closes. [New in: rippled 0.29.0][] |
Each element in the `alternatives` array is an object that represents a path from one possible source currency (held by the initiating account) to the destination account and currency. This object has the following fields:
| `Field` | Type | Description |
|:-----------------|:-----------------|:---------------------------------------|
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](concept-paths.html) |
| `source_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path for the destination to receive the desired amount |
#### Possible Errors
* Any of the [universal error types](#universal-errors).
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `noEvents` - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See [ripple\_path\_find](#ripple-path-find) for a pathfinding method that _is_ compatible with JSON-RPC.)
#### Asynchronous Follow-ups
In addition to the initial response, the server sends more messages in a similar format to update on the status of [payment paths](concept-paths.html) over time. These messages include the `id` of the original WebSocket request so you can tell which request prompted them, and the field `"type": "path_find"` at the top level to indicate that they are additional responses. The other fields are defined in the same way as the initial response.
If the follow-up includes `"full_reply": true`, then this is the best path that rippled can find as of the current ledger.
Here is an example of an asychronous follow-up from a path_find create request:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 1,
"type": "path_find",
"alternatives": [
/* paths omitted from this example; same format as the initial response */
],
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_amount": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "0.001"
},
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59"
}
```
<!-- MULTICODE_BLOCK_END -->
### path_find close
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L46 "Source")
The `close` subcommand of `path_find` instructs the server to stop sending information about the current open pathfinding request.
#### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 57,
"command": "path_find",
"subcommand": "close"
}
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
| `Field` | Type | Description |
|:-------------|:-------|:-------------------------------------------|
| `subcommand` | String | Use `"close"` to send the close subcommand |
#### Response Format
If a pathfinding request was successfully closed, the response follows the same format as the initial response to [`path_find create`](#path-find-create), plus the following field:
| `Field` | Type | Description |
|:---------|:--------|:--------------------------------------------------------|
| `closed` | Boolean | The value `true` indicates this reply is in response to a `path_find close` command. |
If there was no outstanding pathfinding request, an error is returned instead.
#### Possible Errors
* Any of the [universal error types](#universal-errors).
* `invalidParams` - If any fields are specified incorrectly, or any required fields are missing.
* `noEvents` - If you tried to use this method on a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See [ripple\_path\_find](#ripple-path-find) for a pathfinding method that _is_ compatible with JSON-RPC.)
* `noPathRequest` - You tried to close a pathfinding request when there is not an open one.
### path_find status
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/PathFind.cpp#L57 "Source")
The `status` subcommand of `path_find` requests an immediate update about the client's currently-open pathfinding request.
#### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 58,
"command": "path_find",
"subcommand": "status"
}
```
<!-- MULTICODE_BLOCK_END -->
The request includes the following parameters:
| `Field` | Type | Description |
|:-------------|:-------|:---------------------------------------------|
| `subcommand` | String | Use `"status"` to send the status subcommand |
#### Response Format
If a pathfinding request is open, the response follows the same format as the initial response to [`path_find create`](#path-find-create), plus the following field:
| `Field` | Type | Description |
|:---------|:--------|:--------------------------------------------------------|
| `status` | Boolean | The value `true` indicates this reply is in response to a `path_find status` command. |
If there was no outstanding pathfinding request, an error is returned instead.
#### Possible Errors
* Any of the [universal error types](#universal-errors).
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `noEvents` - You are using a protocol that does not support asynchronous callbacks, for example JSON-RPC. (See [ripple\_path\_find](#ripple-path-find) for a pathfinding method that _is_ compatible with JSON-RPC.)
* `noPathRequest` - You tried to check the status of a pathfinding request when there is not an open one.

341
content/references/rippled-api/public-rippled-methods/path-and-order-book-methods/ripple_path_find.md Normal file
View File

@@ -0,0 +1,341 @@
## ripple_path_find
[[Source]<br>](https://github.com/ripple/rippled/blob/master/src/ripple/rpc/handlers/RipplePathFind.cpp "Source")
The `ripple_path_find` method is a simplified version of [`path_find`](#path-find) that provides a single response with a [payment path](concept-paths.html) you can use right away. It is available in both the WebSocket and JSON-RPC APIs. However, the results tend to become outdated as time passes. Instead of making multiple calls to stay updated, you should use [`path_find`](#path-find) instead where possible.
Although the `rippled` server tries to find the cheapest path or combination of paths for making a payment, it is not guaranteed that the paths returned by this method are, in fact, the best paths.
**Caution:** Be careful with the pathfinding results from untrusted servers. A server could be modified to return less-than-optimal paths to earn money for its operators. A server may also return poor results when under heavy load. If you do not have your own server that you can trust with pathfinding, you should compare the results of pathfinding from multiple servers run by different parties, to minimize the risk of a single server returning poor results.
#### Request Format
An example of the request format:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 8,
"command": "ripple_path_find",
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"source_currencies": [
{
"currency": "XRP"
},
{
"currency": "USD"
}
],
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_amount": {
"value": "0.001",
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B"
}
}
```
*JSON-RPC*
```
{
"method": "ripple_path_find",
"params": [
{
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_amount": {
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"value": "0.001"
},
"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"source_currencies": [
{
"currency": "XRP"
},
{
"currency": "USD"
}
]
}
]
}
```
*Commandline*
```
#Syntax ripple_path_find json ledger_index|ledger_hash
rippled ripple_path_find '{"source_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "source_currencies": [ { "currency": "XRP" }, { "currency": "USD" } ], "destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59", "destination_amount": { "value": "0.001", "currency": "USD", "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B" } }'
```
<!-- MULTICODE_BLOCK_END -->
[Try it! >](ripple-api-tool.html#ripple_path_find)
The request includes the following parameters:
| `Field` | Type | Description |
|:----------------------|:---------------------------|:------------------------|
| `source_account` | String | Unique address of the account that would send funds in a transaction |
| `destination_account` | String | Unique address of the account that would receive funds in a transaction |
| `destination_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the destination account would receive in a transaction. **Special case:** [New in: rippled 0.30.0][] You can specify `"-1"` (for XRP) or provide -1 as the contents of the `value` field (for non-XRP currencies). This requests a path to deliver as much as possible, while spending no more than the amount specified in `send_max` (if provided). |
| `send_max` | String or Object | _(Optional)_ [Currency amount](#specifying-currency-amounts) that would be spent in the transaction. Cannot be used with `source_currencies`. [New in: rippled 0.30.0][] |
| `source_currencies` | Array | _(Optional)_ Array of currencies that the source account might want to spend. Each entry in the array should be a JSON object with a mandatory `currency` field and optional `issuer` field, like how [currency amounts](#specifying-currency-amounts) are specified. Cannot contain more than **18** source currencies. By default, uses all source currencies available up to a maximum of **88** different currency/issuer pairs. |
| `ledger_hash` | String | _(Optional)_ A 20-byte hex string for the ledger version to use. (See [Specifying a Ledger](#specifying-ledgers)) |
| `ledger_index` | String or Unsigned Integer | _(Optional)_ The sequence number of the ledger to use, or a shortcut string to choose a ledger automatically. (See [Specifying a Ledger](#specifying-ledgers)) |
#### Response Format
An example of a successful response:
<!-- MULTICODE_BLOCK_START -->
*WebSocket*
```
{
"id": 8,
"status": "success",
"type": "response",
"result": {
"alternatives": [
{
"paths_canonical": [],
"paths_computed": [
[
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rLpq4LgabRfm1xEX5dpWfJovYBH6g7z99q",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rrpNnNLKrartuEqfJGpqyDwPj1AFPg9vn1",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rPuBoajMjFoDjweJBrtZEBwUMkyruxpwwV",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": "256987"
}
],
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_currencies": [
"015841551A748AD2C1F76FF6ECB0CCCD00000000",
"JOE",
"DYM",
"EUR",
"CNY",
"MXN",
"BTC",
"USD",
"XRP"
]
}
}
```
*JSON-RPC*
```
200 OK
{
"result": {
"alternatives": [
{
"paths_canonical": [],
"paths_computed": [
[
{
"currency": "USD",
"issuer": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rpDMez6pm6dBve2TJsmDpv7Yae6V5Pyvy2",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rfDeu7TPUmyvUrffexjMjq3mMcSQHZSYyA",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rLEsXccBGNR3UPuPu2hUXPjziKC3qKSBun",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "raspZSGNiTKi5jmvFxUYCuYXPv1V8WhL5g",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
],
[
{
"currency": "USD",
"issuer": "rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT",
"type": 48,
"type_hex": "0000000000000030"
},
{
"account": "rpHgehzdpfWRXKvSv6duKvVuo1aZVimdaT",
"type": 1,
"type_hex": "0000000000000001"
},
{
"account": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B",
"type": 1,
"type_hex": "0000000000000001"
}
]
],
"source_amount": "207414"
}
],
"destination_account": "r9cZA1mLK5R5Am25ArfXFmqgNwjZgnfk59",
"destination_currencies": [
"USD",
"JOE",
"BTC",
"DYM",
"CNY",
"EUR",
"015841551A748AD2C1F76FF6ECB0CCCD00000000",
"MXN",
"XRP"
],
"status": "success"
}
}
```
<!-- MULTICODE_BLOCK_END -->
The response follows the [standard format](#response-formatting), with a successful result containing the following fields:
| `Field` | Type | Description |
|:-------------------------|:-------|:-----------------------------------------|
| `alternatives` | Array | Array of objects with possible paths to take, as described below. If empty, then there are no paths connecting the source and destination accounts. |
| `destination_account` | String | Unique address of the account that would receive a payment transaction |
| `destination_currencies` | Array | Array of strings representing the currencies that the destination accepts, as 3-letter codes like `"USD"` or as 40-character hex like `"015841551A748AD2C1F76FF6ECB0CCCD00000000"` |
Each element in the `alternatives` array is an object that represents a path from one possible source currency (held by the initiating account) to the destination account and currency. This object has the following fields:
| `Field` | Type | Description |
|:-----------------|:-----------------|:---------------------------------------|
| `paths_computed` | Array | Array of arrays of objects defining [payment paths](concept-paths.html) |
| `source_amount` | String or Object | [Currency amount](#specifying-currency-amounts) that the source would have to send along this path for the destination to receive the desired amount |
The following fields are deprecated, and may be omitted: `paths_canonical`, and `paths_expanded`. If they appear, you should disregard them.
#### Possible Errors
* Any of the [universal error types](#universal-errors).
* `tooBusy` - The server is under too much load to calculate paths. Not returned if you are connected as an admin.
* `invalidParams` - One or more fields are specified incorrectly, or one or more required fields are missing.
* `srcActMissing` - The `source_account` field is omitted from the request.
* `srcActMalformed` - The `source_account` field in the request is not formatted properly.
* `dstActMissing` - The `destination_account` field is omitted from the request.
* `dstActMalformed` - The `destination_account` field in the request is not formatted properly.
* `srcCurMalformed` - The `source_currencies` field is not formatted properly.
* `srcIsrMalformed` - The `issuer` field of one or more of the currency objects in the request is not valid.