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

inc'd matt's feedback

Browse Source
This commit is contained in:
Jennifer Hasegawa
2019-01-02 14:12:35 -08:00
parent 3202e23030
commit 4b2ddd0b58
2 changed files with 58 additions and 45 deletions
Download Patch File Download Diff File Expand all files Collapse all files

101
content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md
View File

@@ -1,25 +1,29 @@
# List Your Exchange on XRP Charts
In addition to providing data about the XRP Ledger network and its accounts and transactions, XRP Charts also provides [XRP market data](https://xrpcharts.ripple.com/#/xrp-markets). ***TODO: Correct? Is this the area of the site that exchanges are asking to be listed in? Live Chart, Multi Markets, Active Accounts, XRP Markets?*** This tutorial describes how to have your exchange and its XRP trade and order book data listed on XRP Charts.
In addition to providing data about the XRP Ledger network and its accounts and transactions, XRP Charts also provides [XRP market data](https://xrpcharts.ripple.com/#/xrp-markets) from external exchanges. This tutorial describes how to have your exchange and its XRP trade and order book data listed on XRP Charts.
To enable XRP Charts to list your exchange, complete the following tasks:
1. Provide a [Get Recently Executed Trades](#provide-a-get-recently-executed-trades-endpoint) REST API endpoint.
1. [Provide a Get Recently Executed Trades REST API endpoint](#provide-a-get-recently-executed-trades-endpoint).
2. Provide a [Get Current Order Book](#provide-a-get-current-order-book-endpoint) REST API endpoint.
2. [Provide a Get Current Order Book REST API endpoint](#provide-a-get-current-order-book-endpoint).
3. [Send a listing request to XRP Charts](#send-a-listing-request-to-xrp-charts).
3. [Send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts).
If you have any questions about endpoint specifications, contact xxx@xxxxx.com. ***TODO: do we want to provide support? This will help avoid them guessing while building and then find out that their endpoint doesn't meet our specs only after they've requested listing.***
If you have any questions about endpoint specifications, contact xxx@xxxxx.com. ***TODO: do we want to provide a way for them to contact us for dev support?***
## Provide a Get Recently Executed Trades Endpoint
***TODO: Do we really mean "recently" only? If yes, how recent? last 500-1000 as described below?***
Provide a REST API endpoint that returns the most recent 500-1,000 individual trades executed in a particular XRP market.
Provide a REST API endpoint that returns data about individual trades executed in a particular market. ***TODO: is this about trades that involve XRP as a base or counter curr only? I see a wider variety of currencies listed on the site.***
XRP Charts will query this endpoint every 30 seconds or less, aiming to retrieve responses that contain an overlap in trade data. This will help ensure that XRP Charts does not miss any trades.
XRP Charts will query this endpoint at least every 15-30 seconds. The endpoint must be capable of returning 500-1,000 trades per response, but that number could be smaller when the `last_tid` query parameter is included. ***TODO: What is the purpose of this spec, just so I can better explain it? 500-1000 trades is a response without any query parameters. Does this mean that the endpoint doesn't have to be able to return anything older than the last 1,000 trades (since we specifically call this "get recently executed trades")? Or does the endpoint need to be able to respond to a request with a tid from 1 year ago - returning every trade since that tid - which could be more than 1000? Or is this saying that the endpoint needs to provide pagination that enables XRP Charts to request results in sets of 500 to 1,000 at a time -- with a query parameter of a tid from last year, for example?***
***TODO: is the following explanation of how the endpoint will be used - useful or overkill?***
For example, let's say that XRP Charts makes a request to your endpoint and receives trade IDs 1 - 1000 in the response. XRP Charts records data for trade IDs 1-1000. XRP Charts makes a second request 30 seconds later and receives trade IDs 800 - 1800 in the response. There is an overlap in data (and therefore no missed trades), but XRP Charts only records data for the unique trade IDs 1001 - 1800.
Alternatively, let's say that in its second request, XRP Charts receives trade IDs 1500-2500. There is no overlap and XRP Charts has missed some trades; trade IDs 1001-1499, to be exact. In this case, XRP Charts must query your endpoint more often to attempt to receive overlapping data and avoid missing any trades.
### Request Format
@@ -30,61 +34,70 @@ Provide a request format like the following:
GET {api_base_url}/v1/trades
```
***TODO: any authentication specs? or publicly accessible?***
#### Authentication
#### Query Parameters
We prefer to work with a publicly accessible endpoint.
Provide the following query parameters. XRP Charts will optionally use them to narrow the trades returned in the response. ***TODO: true? will XRP Charts always make this call with both query params present? Or also with just one or the other, or none?***
#### Parameters
Provide parameters that help XRP Charts filter trades returned in the response. Use of these exact parameter field names is optional. While having access to all of these parameters is useful, your endpoint isn't required to provide the ones marked as _(Optional)_.
| Field | Type | Description |
|:-----------|:--------|:------------------------------------------------------|
| `market` | String | Returns trades executed in a particular market. Valid values can include `XRPBTC` or `USDXRP`, for example. For fiat currencies, use [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency codes. For cryptocurrencies, see codes listed in the currency drop-down on XRP Charts [Markets page](https://xrpcharts.ripple.com/#/markets). For cryptocurrencies not listed in the drop-down, contact xxxxxx@xxxxxx.com. ***TODO: Is there a suggested format we want them to use for these market values -- such as <BASECURRENCY><COUNTERCURRENCY>? Is this currency code guidance okay? Who should they contact if they need guidance on a cryptocurrency code not already represented on XRP Charts?*** |
| `last_tid` | Integer | Returns trades executed after a specific trade ID. XRP Charts uses this parameter to get all trades after the last set of trades imported into site data, for example. The parameter also enables XRP Charts to ensure that it has recorded all trades. |
| `market` | String | Returns trades executed in a particular market in which XRP is either the base or counter currency. Use a suggested format of `<basecurrency>_<countercurrency>` to provide valid values like `xrp_btc`, `btc_xrp`, `xrp_usd`, or `usd_xrp`, for example. |
| `last_tid` | Integer | _(Optional)_ Returns trades executed after a specific trade ID. For example, XRP Charts can use this parameter to get all trades after the last set of trades recorded in site data, ensuring that it has recorded all trades. |
| `limit` | Integer | _(Optional)_ Returns no more than a specific number of trades in a response. |
### Response Format
A successful response must be a JSON array of objects, one for each trade. Each trade must be described using the following fields. ***TODO: must or should? how strict are we being about field names, etc?***
A successful response must be a JSON array of objects, one for each trade. Use of these exact field names is optional. While having access to all of these fields would be useful, your endpoint isn't required to provide the ones marked as _(Optional)_.
***TODO: `tid` should be required, is that right? Or is there some other way to determine uniqueness?***
| Field | Type | Description |
|:------------|:-----------------|:--------------------------------------------|
| `tid` | Integer | Unique identifier of the trade. Ideally, this is a sequential integer. ***TODO: ideally, or required?*** |
| `type` | String | Valid values include `buy` and `sell`. |
| `price` | String or Number | Exchange rate of the trade. |
| `amount` | String or Number | Amount of XRP bought or sold. |
| `size` | String or Number | Amount of counter currency traded. |
| `timestamp` | String | Time at which the trade was executed in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. ***TODO: Type correct? If ISO 8601, the type can be `date-time`. But b/c Unix time, must be string?*** |
| `timestamp` | String | Time at which the trade was executed in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. |
| `tid` | Integer | _(Optional)_ Unique identifier of the trade. Ideally, make this a sequential integer. |
| `type` | String | _(Optional)_ Type of trade. For example, valid values can include `buy` and `sell`. |
| `size` | String or Number | _(Optional)_ Amount of counter currency traded. |
| `count` | Integer | _(Optional)_ Number of trade objects returned in the response. |
### Example
### Examples
#### Request
***TODO: examples below okay - esp use of `limit` in URL and `count` in response message?***
#### Example Request
```
GET https://api.example.com/v1/trades?market=XRPBTC&last_tid=75208825
GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500
```
#### Response
#### Example Response
```json
[
{
"tid":75208827,
"tid":75209326,
"type":"buy",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:41:16.000Z"
"timestamp":"2018-10-01T12:35:11.000Z"
},
...
{
"tid":75208826,
"type":"sell",
"price":"0.57201",
"amount":"4954.0744",
"size":"2833.7801",
"timestamp":"2018-10-01T12:41:16.000Z"
},
...
"timestamp":"2018-10-01T12:31:16.000Z"
}
"count":"500"
]
```
@@ -105,37 +118,39 @@ Provide a request format like the following:
GET {exchange_base_url}/v1/orderbook
```
***TODO: any authentication specs? or publicly accessible?***
#### Authentication
#### Query Parameter
We prefer to work with a publicly accessible endpoint.
Provide the following query parameter. ***TODO: Will XRP Charts always make this call with the market query param present?***
#### Parameter
Provide the following parameter. Use of this exact parameter field name is optional.
| `Field` | Type | Description |
|:---------|:-------|:---------------------------------------------------------|
| `market` | String | Returns the current order book in a particular market. Valid values can include `XRPBTC`, `USDXRP`, or `BTCXRP`, for example. For fiat currencies, use [ISO 4217](https://www.iso.org/iso-4217-currency-codes.html) currency codes. For cryptocurrencies, see codes listed in the currency drop-down on XRP Charts [Markets page](https://xrpcharts.ripple.com/#/markets). For cryptocurrencies not listed in the drop-down, contact xxxxxx@xxxxxx.com. ***TODO: Is there a suggested format we want them to use for these market values -- such as <BASECURRENCY><COUNTERCURRENCY>? Is this currency code guidance okay? Who should they contact if they need guidance on a cryptocurrency code not already represented on XRP Charts?*** |
| `market` | String | Returns the current order book in which XRP is either the base or counter currency. Use a suggested format of `<basecurrency>_<countercurrency>` to provide valid values like `xrp_btc`, `btc_xrp`, `xrp_usd`, or `usd_xrp`, for example. |
### Response Format
A successful response must be a JSON object that includes a timestamp and arrays of current bids and asks. The response does not need to provide the entire order book, but rather just enough data to provide a good idea of the current liquidity available in the market.
A successful response must be a JSON object that includes a timestamp and arrays of current bids and asks. The response does not need to provide the entire order book, but rather just enough data to provide a good idea of the current liquidity available in the market. Use of these exact field names is optional.
| Field | Type | Description |
|:------------|:-----------------|:--------------------------------------------|
| `timestamp` | String | Time at which the response was sent in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. ***TODO: Not sure about the description - okay? Data type correct? If ISO 8601, the type can be `date-time`. But b/c Unix time, must be string?*** |
| `timestamp` | String | Time at which the response was sent in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) or [Unix time](https://en.wikipedia.org/wiki/Unix_time) format. |
| `bids` | Array of objects | Bids in the order book. Each object in the array must provide the offered `price` and `amount` of XRP available at that price. |
| `asks` | Array of objects | Asks in the order book. Each object in the array must provide the offered `price` and `amount` of XRP available at that price. |
### Example
### Examples
#### Request
#### Example Request
```
GET https://api.example.com/v1/orderbook?market=XRPBTC
GET https://api.example.com/v1/orderbook?market=xrp_btc
```
#### Response
#### Example Response
```json
{
@@ -173,14 +188,12 @@ GET https://api.example.com/v1/orderbook?market=XRPBTC
## Send a Listing Request to XRP Charts
## Send an Exchange Listing Request to XRP Charts
Contact xxx@xxxxx.com to request that your exchange be listed on XRP Charts.
Contact xxx@xxxxx.com to request that your exchange be listed on XRP Charts. ***TODO: alternatively, do we want to just have them submit everything via a Google Form like this one, for example? https://docs.google.com/forms/d/e/1FAIpQLScszfq7rRLAfArSZtvitCyl-VFA9cNcdnXLFjURsdCQ3gHW7w/viewform***
In the request be sure to include: ***TODO: what do we need to know about them? do we want them to include links to their endpoints?***
In the request be sure to include:
- ABC
- A link to your API documentation
- XYZ
***TODO: alternatively, do we want to just have them submit everything via a Google Form like this one, for example? https://docs.google.com/forms/d/e/1FAIpQLScszfq7rRLAfArSZtvitCyl-VFA9cNcdnXLFjURsdCQ3gHW7w/viewform***
- ***TODO: Anything else we want them to provide?***

2
dactyl-config.yml
View File

@@ -863,7 +863,7 @@ pages:
funnel: Docs
doc_type: Tutorials
category: XRP Ledger Businesses
blurb: This tutorial describes how to list your exchange on XRP Charts.
blurb: This tutorial describes how to have your exchange and its XRP trade and order book data listed on XRP Charts.
targets:
- local