From c61c87fc96a2c0078cce3c3ca1c5ec90b1001197 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Tue, 18 Dec 2018 12:33:38 -0800 Subject: [PATCH 1/7] first draft --- .../list-your-exchange-on-xrp-charts.md | 186 ++++++++++++++++++ 1 file changed, 186 insertions(+) create mode 100644 content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md new file mode 100644 index 0000000000..0f8d5058b1 --- /dev/null +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -0,0 +1,186 @@ +# 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. + +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. + +2. Provide a [Get Current Order Book](#provide-a-get-current-order-book-endpoint) REST API endpoint. + +3. [Send a listing request to XRP Charts](#send-a-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.*** + + +## 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 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 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?*** + + +### Request Format + +Provide a request format like the following: + +``` +GET {api_base_url}/v1/trades +``` + +***TODO: any authentication specs? or publicly accessible?*** + +#### Query Parameters + +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?*** + +| 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 ? 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. | + + +### 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?*** + +| 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?*** | + + +### Example + +#### Request + +``` +GET https://api.example.com/v1/trades?market=XRPBTC&last_tid=75208825 +``` + +#### Response + +```json +[ + { + "tid":75208827, + "type":"buy", + "price":"0.57201", + "amount":"4954.0744", + "size":"2833.7801", + "timestamp":"2018-10-01T12:41:16.000Z" + }, + { + "tid":75208826, + "type":"sell", + "price":"0.57201", + "amount":"4954.0744", + "size":"2833.7801", + "timestamp":"2018-10-01T12:41:16.000Z" + }, + ... +] +``` + + + +## Provide a Get Current Order Book Endpoint + +Provide a REST API endpoint that returns data about the current order book in a particular market. + +XRP Charts will query this endpoint about every 30 seconds. + + +### Request Format + +Provide a request format like the following: + +``` +GET {exchange_base_url}/v1/orderbook +``` + +***TODO: any authentication specs? or publicly accessible?*** + +#### Query Parameter + +Provide the following query parameter. ***TODO: Will XRP Charts always make this call with the market query param present?*** + +| `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 ? Is this currency code guidance okay? Who should they contact if they need guidance on a cryptocurrency code not already represented on XRP Charts?*** | + + +### 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. + +| 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?*** | +| `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 + +#### Request + +``` +GET https://api.example.com/v1/orderbook?market=XRPBTC +``` + +#### Response + +```json +{ + "timestamp":"2018-10-01T12:41:16.000Z", + "bids":[ + { + "price":0.00007103, + "amount":140 + }, + { + "price":0.000071, + "amount":135 + }, + { + "price":0.00007092, + "amount":5266 + } + ], + "asks":[ + { + "price":0.00007108, + "amount":140 + }, + { + "price":0.00007109, + "amount":84 + }, + { + "price":0.0000711, + "amount":10650 + } + ] +} +``` + + + +## Send a Listing Request to XRP Charts + +Contact xxx@xxxxx.com to request that your exchange be listed on XRP Charts. + +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?*** + +- ABC + +- 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*** From 3202e230304ff628f9c0a6418b9db1a2e0cd1ad8 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Tue, 18 Dec 2018 12:44:04 -0800 Subject: [PATCH 2/7] add changed to config --- dactyl-config.yml | 9 +++++++++ 1 file changed, 9 insertions(+) diff --git a/dactyl-config.yml b/dactyl-config.yml index a67e7f9e90..76fdca66c2 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -858,6 +858,15 @@ pages: targets: - local + - md: tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md + html: list-your-exchange-on-xrp-charts.html + funnel: Docs + doc_type: Tutorials + category: XRP Ledger Businesses + blurb: This tutorial describes how to list your exchange on XRP Charts. + targets: + - local + - md: tutorials/xrp-ledger-businesses/become-an-xrp-ledger-gateway.md html: become-an-xrp-ledger-gateway.html funnel: Docs From 4b2ddd0b58ff4fc74a41bbc1617293645dc52dc0 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Wed, 2 Jan 2019 14:12:35 -0800 Subject: [PATCH 3/7] inc'd matt's feedback --- .../list-your-exchange-on-xrp-charts.md | 101 ++++++++++-------- dactyl-config.yml | 2 +- 2 files changed, 58 insertions(+), 45 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index 0f8d5058b1..6df0216b77 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -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 ? 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 `_` 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 ? 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 `_` 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?*** diff --git a/dactyl-config.yml b/dactyl-config.yml index 76fdca66c2..5e6b8d0443 100644 --- a/dactyl-config.yml +++ b/dactyl-config.yml @@ -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 From 071b0a9612fc30c7d692ab1547f891f88176536d Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Fri, 4 Jan 2019 17:26:02 -0800 Subject: [PATCH 4/7] inc ry feedback --- .../list-your-exchange-on-xrp-charts.md | 38 +++++++++---------- 1 file changed, 18 insertions(+), 20 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index 6df0216b77..df133f8898 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -4,26 +4,24 @@ In addition to providing data about the XRP Ledger network and its accounts and To enable XRP Charts to list your exchange, complete the following tasks: -1. [Provide a Get Recently Executed Trades REST API endpoint](#provide-a-get-recently-executed-trades-endpoint). +1. [Provide a Recently Executed Trades RESTful API endpoint](#provide-a-recently-executed-trades-endpoint). -2. [Provide a Get Current Order Book REST API endpoint](#provide-a-get-current-order-book-endpoint). +2. [Provide a Current Order Book RESTful API endpoint](#provide-a-current-order-book-endpoint). 3. [Send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts). +Your exchange may already provide RESTful API endpoints that can deliver data in the formats described in this document. If so, there may be little to no development required on your part. + 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 +## Provide a Recently Executed Trades Endpoint -Provide a REST API endpoint that returns the most recent 500-1,000 individual trades executed in a particular XRP market. +Provide a RESTful API endpoint that returns the most recent 500-1,000 individual trades executed in a particular XRP market. -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. +To ensure that it doesn't miss a trade, XRP Charts queries the endpoint frequently, between every 5 and 30 seconds, aiming to get responses that have overlapping trade data. -***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. +XRP Charts records unique trade data only, even if it gets overlapping trades. XRP Charts adjusts its query frequency if it doesn't get overlapping trades. XRP Charts respects any rate limit enforced by your endpoint, but the limit must not block XRP Charts from querying at the frequency needed to get the required data set. ***TODO: okay to state this? If we can't get the data set needed without exceeding their rate limit - then we need them to increase the rate limit or provide the last_tid parameter, correct?*** ### Request Format @@ -40,7 +38,7 @@ We prefer to work with a publicly accessible endpoint. #### 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)_. +Provide parameters that help XRP Charts filter trades returned in the response. The parameter field names are examples. You can use other names. Your endpoint doesn't have to provide the optional parameters, but they are useful. | Field | Type | Description | |:-----------|:--------|:------------------------------------------------------| @@ -51,7 +49,7 @@ Provide parameters that help XRP Charts filter trades returned in the response. ### Response Format -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)_. +A successful response must be a JSON array of objects, one for each trade. The parameter field names are examples. You can use other names. Your endpoint doesn't have to provide the optional parameters, but they are useful. ***TODO: `tid` should be required, is that right? Or is there some other way to determine uniqueness?*** @@ -59,7 +57,7 @@ A successful response must be a JSON array of objects, one for each trade. Use o |:------------|:-----------------|:--------------------------------------------| | `price` | String or Number | Exchange rate of the trade. | | `amount` | String or Number | Amount of XRP bought or sold. | -| `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. | +| `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: just making sure - either format okay?*** | | `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. | @@ -103,11 +101,11 @@ GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500 -## Provide a Get Current Order Book Endpoint +## Provide a Current Order Book Endpoint -Provide a REST API endpoint that returns data about the current order book in a particular market. +Provide a RESTful API endpoint that returns data about the current order book in a particular market. -XRP Charts will query this endpoint about every 30 seconds. +XRP Charts will query this endpoint about every 30 seconds. ***TODO: does this frequency vary based on data retrieved?*** ### Request Format @@ -115,7 +113,7 @@ XRP Charts will query this endpoint about every 30 seconds. Provide a request format like the following: ``` -GET {exchange_base_url}/v1/orderbook +GET {api_base_url}/v1/orderbook ``` #### Authentication @@ -124,7 +122,7 @@ We prefer to work with a publicly accessible endpoint. #### Parameter -Provide the following parameter. Use of this exact parameter field name is optional. +Provide the following parameter. The parameter field name is an example. You can use another name. | `Field` | Type | Description | |:---------|:-------|:---------------------------------------------------------| @@ -133,11 +131,11 @@ Provide the following parameter. Use of this exact parameter field name is optio ### 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. Use of these exact field names is optional. +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. The parameter field names are examples. You can use other names. | 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. | +| `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: just making sure - either format okay?*** | | `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. | From 7e74bae61e1b0c8a37aefea136a88939030efdcf Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Mon, 7 Jan 2019 10:46:29 -0800 Subject: [PATCH 5/7] adj rate limit text --- .../list-your-exchange-on-xrp-charts.md | 6 +++--- 1 file changed, 3 insertions(+), 3 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index df133f8898..30da4f4cf2 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -10,7 +10,7 @@ To enable XRP Charts to list your exchange, complete the following tasks: 3. [Send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts). -Your exchange may already provide RESTful API endpoints that can deliver data in the formats described in this document. If so, there may be little to no development required on your part. +Your exchange may have existing RESTful API endpoints that can deliver data in the formats described in this document. If so, there may be little to no development effort required on your part to complete tasks 1 and 2. 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?*** @@ -19,9 +19,9 @@ If you have any questions about endpoint specifications, contact xxx@xxxxx.com. Provide a RESTful API endpoint that returns the most recent 500-1,000 individual trades executed in a particular XRP market. -To ensure that it doesn't miss a trade, XRP Charts queries the endpoint frequently, between every 5 and 30 seconds, aiming to get responses that have overlapping trade data. +To ensure that it doesn't miss a trade, XRP Charts queries the endpoint frequently, between every 5 and 30 seconds, aiming to get responses that have overlapping trade data. Ensure that any rate limit enforced by your endpoint can accommodate this query frequency. XRP Charts records unique trade data only, even if it gets overlapping trades. -XRP Charts records unique trade data only, even if it gets overlapping trades. XRP Charts adjusts its query frequency if it doesn't get overlapping trades. XRP Charts respects any rate limit enforced by your endpoint, but the limit must not block XRP Charts from querying at the frequency needed to get the required data set. ***TODO: okay to state this? If we can't get the data set needed without exceeding their rate limit - then we need them to increase the rate limit or provide the last_tid parameter, correct?*** +If XRP Charts needs to query your endpoint at a frequency that exceeds your rate limit, XRP Charts may request that you adjust the rate limit or provide the `last_tid` parameter. ***TODO: okay to state this? accurate?*** ### Request Format From c483f19589657507748827b403484b61cad2304e Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Wed, 9 Jan 2019 14:54:23 -0800 Subject: [PATCH 6/7] inc'd feedback --- .../list-your-exchange-on-xrp-charts.md | 68 +++++++++---------- 1 file changed, 32 insertions(+), 36 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index 30da4f4cf2..ac26b93df7 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -2,15 +2,13 @@ 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: +To enable XRP Charts to list your exchange, you'll need to make the following data available. Your exchange may have existing RESTful API endpoints that can deliver this data. If so, there may be little to no development effort required on your part to complete tasks 1 and 2. 1. [Provide a Recently Executed Trades RESTful API endpoint](#provide-a-recently-executed-trades-endpoint). 2. [Provide a Current Order Book RESTful API endpoint](#provide-a-current-order-book-endpoint). -3. [Send an exchange listing request to XRP Charts](#send-an-exchange-listing-request-to-xrp-charts). - -Your exchange may have existing RESTful API endpoints that can deliver data in the formats described in this document. If so, there may be little to no development effort required on your part to complete tasks 1 and 2. +Then, you'll need to [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 a way for them to contact us for dev support?*** @@ -21,7 +19,7 @@ Provide a RESTful API endpoint that returns the most recent 500-1,000 individual To ensure that it doesn't miss a trade, XRP Charts queries the endpoint frequently, between every 5 and 30 seconds, aiming to get responses that have overlapping trade data. Ensure that any rate limit enforced by your endpoint can accommodate this query frequency. XRP Charts records unique trade data only, even if it gets overlapping trades. -If XRP Charts needs to query your endpoint at a frequency that exceeds your rate limit, XRP Charts may request that you adjust the rate limit or provide the `last_tid` parameter. ***TODO: okay to state this? accurate?*** +If XRP Charts needs to query your endpoint at a frequency that exceeds your rate limit, XRP Charts may request that you adjust the rate limit or provide the `last_tid` parameter. ### Request Format @@ -34,7 +32,7 @@ GET {api_base_url}/v1/trades #### Authentication -We prefer to work with a publicly accessible endpoint. +XRP Charts prefers to work with a publicly accessible endpoint. #### Parameters @@ -51,13 +49,11 @@ Provide parameters that help XRP Charts filter trades returned in the response. A successful response must be a JSON array of objects, one for each trade. The parameter field names are examples. You can use other names. Your endpoint doesn't have to provide the optional parameters, but they are useful. -***TODO: `tid` should be required, is that right? Or is there some other way to determine uniqueness?*** - | Field | Type | Description | |:------------|:-----------------|:--------------------------------------------| | `price` | String or Number | Exchange rate of the trade. | | `amount` | String or Number | Amount of XRP bought or sold. | -| `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: just making sure - either format okay?*** | +| `timestamp` | String | Time at which the trade was executed in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time format 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. | @@ -66,8 +62,6 @@ A successful response must be a JSON array of objects, one for each trade. The p ### Examples -***TODO: examples below okay - esp use of `limit` in URL and `count` in response message?*** - #### Example Request ``` @@ -77,26 +71,28 @@ GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500 #### Example Response ```json -[ - { - "tid":75209326, - "type":"buy", - "price":"0.57201", - "amount":"4954.0744", - "size":"2833.7801", - "timestamp":"2018-10-01T12:35:11.000Z" - }, - ... - { - "tid":75208826, - "type":"sell", - "price":"0.57201", - "amount":"4954.0744", - "size":"2833.7801", - "timestamp":"2018-10-01T12:31:16.000Z" - } +{ + "trades":[ + { + "tid":75209326, + "type":"buy", + "price":"0.57201", + "amount":"4954.0744", + "size":"2833.7801", + "timestamp":"2018-10-01T12:35:11.000Z" + }, + ... + { + "tid":75208826, + "type":"sell", + "price":"0.57201", + "amount":"4954.0744", + "size":"2833.7801", + "timestamp":"2018-10-01T12:31:16.000Z" + } + ], "count":"500" -] +} ``` @@ -105,7 +101,7 @@ GET https://api.example.com/v1/trades?market=xrp_btc&last_tid=75208825&limit=500 Provide a RESTful API endpoint that returns data about the current order book in a particular market. -XRP Charts will query this endpoint about every 30 seconds. ***TODO: does this frequency vary based on data retrieved?*** +XRP Charts will query this endpoint about every 30 seconds. ### Request Format @@ -118,7 +114,7 @@ GET {api_base_url}/v1/orderbook #### Authentication -We prefer to work with a publicly accessible endpoint. +XRP Charts prefers to work with a publicly accessible endpoint. #### Parameter @@ -131,13 +127,13 @@ Provide the following parameter. The parameter field name is an example. You can ### 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. The parameter field names are examples. You can use other names. +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 XRP liquidity available in the market. The parameter field names are examples. You can use other names. | 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: just making sure - either format okay?*** | -| `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. | +| `timestamp` | String | Time at which the response was sent in [ISO 8601](https://www.iso.org/iso-8601-date-and-time-format.html) date-time format 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` 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` available at that price. | ### Examples From a692314e3daeba8d139bf45f8f3ed6a916df3280 Mon Sep 17 00:00:00 2001 From: Jennifer Hasegawa Date: Thu, 10 Jan 2019 14:41:51 -0800 Subject: [PATCH 7/7] added email support address --- .../list-your-exchange-on-xrp-charts.md | 10 +++------- 1 file changed, 3 insertions(+), 7 deletions(-) diff --git a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md index ac26b93df7..c502a3ab96 100644 --- a/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md +++ b/content/tutorials/xrp-ledger-businesses/list-your-exchange-on-xrp-charts.md @@ -10,7 +10,7 @@ To enable XRP Charts to list your exchange, you'll need to make the following da Then, you'll need to [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 a way for them to contact us for dev support?*** +If you have any questions about endpoint specifications, contact . ## Provide a Recently Executed Trades Endpoint @@ -184,10 +184,6 @@ GET https://api.example.com/v1/orderbook?market=xrp_btc ## Send an Exchange Listing Request to 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*** +Contact to request that your exchange be listed on XRP Charts. -In the request be sure to include: - -- A link to your API documentation - -- ***TODO: Anything else we want them to provide?*** +In the request, be sure to include a link to your API documentation