├── README.md ├── examples ├── websocket_basic.html └── websocket_token_price_widget.html └── images ├── example_normal_open_prices.png └── example_open_prices_with_cf_flag.png /README.md: -------------------------------------------------------------------------------- 1 | # XRP Ledger Token Data API 2 | #### Powered by [`OnTheDEX.live`](https://onthedex.live/) 3 | ![OnTheDex Logo](https://onthedex.live/onthedex_logo_simple.svg) 4 | 5 | ## About this API 6 | This API offers accurate and up-to-date token trading data for all tokens traded on the XRP Ledger DEX. The data source is the XRP Ledger itself. This API is accessible to anyone. Particular use cases might include: 7 | * Cryptocurrency Aggregator sites such as CMC, CoinGecko, LiveCoinWatch and others. Such sites can use this API to secure a data feed for any and all tokens traded on the XRP Ledger. 8 | * Projects needing specific token data such as trading volume, current price, or historic OHLC price data. 9 | * Personal projects eg. importation of token data into your portfolio tracking spreadsheets using Excel or Google Sheets, for example. 10 | 11 | Methods are available for static data retrieval via HTTP `GET` and `POST` methods, and some data is also available streamed via `WEBSOCKET` connections. 12 | 13 | ## Endpoints for access 14 | The HTTP endpoint to use for `GET` and `POST` requests is: 15 | ``` 16 | https://api.onthedex.live/public/v1 17 | ``` 18 | 19 | The `WEBSOCKET` endpoint to use for websocket paths is: 20 | ``` 21 | wss://api.onthedex.live/public/v1 22 | ``` 23 | 24 | ## Things to know 25 | * All times in GMT. 26 | * All responses are JSON format unless specified otherwise. 27 | * Rate limits apply to all requests and are subject to fair use in our determination. Normal use of this API should not trigger rate limits on your application, but if you need higher levels of access, feel free to contact us: `info@onthedex.live`. 28 | 29 | 30 | ## API Error trapping 31 | Only return status codes of `200` are valid; any other status code returned means the API did not function as intended for your request. Additionally, having received a valid `200` return status code from your request, 32 | always check the root JSON return object for the `error` property. If set, this will be a string error code accompanied by a `message` property string explaining the error in more detail. Example: 33 | ```json 34 | { 35 | "error": "ERROR_MAINTENANCE", 36 | "message": "The system is under maintenance for a short period. Please try again later." 37 | } 38 | ``` 39 | 40 | 41 | ## Websocket specifics 42 | When using the websocket versions of some endpoint paths described below, there are 3 possible outcomes: 43 | - an error message with `error` property; or 44 | - a `ping` property with other details denoting current status at the server level of this channel; or 45 | - a proper data packet as described below for each websocket endpoint path. 46 | 47 | ### Websocket ping messages 48 | When there is no `error` and no changed data needing to be sent to you, a `ping` message will be sent to signify that the connection is still alive and the current status of the channel on watch at the server. 49 | (There is no need to send a ping request to the server from your client.) 50 | 51 | Property | Type | Description 52 | --- | --- | --- 53 | `ping` | Integer | Timestamp of ping event from server 54 | `channel` | String | Path of the channel this websocket is listening on for data 55 | `status` | String | Current status of this channel (for example: `watching`) means the channel is alive and watching for property changes to transmit to you 56 | `message` | String | Other descriptive data (for example: `no change`) means no change in the dataset was detected since you last received a valid dataset 57 | 58 | 59 | 60 | # Documentation 61 | Path | Methods | Description 62 | --- | --- | --- 63 | [`/ticker/:tokens_or_pairs`](#get-or-websocket-tickertokens_or_pairs) | `GET`, `WEBSOCKET` | Latest ticker information for a given token, pairing or group of pairs. 64 | [`/token/meta/:tokens`](#getpost-tokenmetatokens) | `GET`, `POST` | Metadata for a given token(s). 65 | [`/daily/tokens`](#get-dailytokens) | `GET` | Headline Daily Token Data for top 100 traded tokens by volume, market cap or number of trades. 66 | [`/daily/pairs`](#get-dailypairs) | `GET` | Headline Daily Traded Pair Data by volume or number of trades. 67 | [`/aggregator`](#getpost-aggregator) | `GET`, `POST` | Aggregator data for all tokens traded in the last rolling 24 hours, including token metrics, fiat USD equivalent pricing and volumes, and individual token pairing data. 68 | [`/ohlc`](#get-ohlc) | `GET` | Candlestick chart data including Open/High/Low/Close price data, base and quote volumes, for varying intervals. 69 | 70 | 71 | ## Examples 72 | The `examples` folder contains some Javascript code examples for certain endpoints. 73 | 74 | 75 | # Data Paths 76 | 77 | ## `GET` or `WEBSOCKET`: `/ticker/:tokens_or_pairs` 78 | Returns data for the specified tokens, pairs or (if `:token_or_pairs` is unspecified) a list of latest traded tokens within the last rolling 24 hours. 79 | 80 | If a single token is requested, either as a base (`/ticker/TOKEN.ISSUER`) or as a quote (`/ticker/:TOKEN.ISSUER`), the server will return all pairs traded against the token in the last 24 hours. 81 | 82 | If a specific pair (or pairs) is requested, those specific pair(s) are returned irrespective of whether they have traded in the last rolling 24 hours or not. 83 | The difference will be in the `volume_base` and `volume_quote` properties which will be 0 (zero) if not traded in the last 24 hours, together with a `time` property that represents a time earlier than 24 hours ago. 84 | 85 | #### Example `GET`: 86 | To return data for all pairs recently traded in the last rolling 24 hours... 87 | ``` 88 | // ...with SOLO as the base currency: 89 | https://api.onthedex.live/public/v1/ticker/SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz 90 | 91 | // ... with SOLO as the quote currency: 92 | https://api.onthedex.live/public/v1/ticker/:SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz 93 | 94 | // ... for all pairs (no specific token filter): 95 | https://api.onthedex.live/public/v1/ticker 96 | ``` 97 | 98 | To return a specific pair or pairs (returning most recent trade data even if outside of 24 hours): 99 | ``` 100 | // ...for CSC/XRP only: 101 | https://api.onthedex.live/public/v1/ticker/CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr:XRP 102 | 103 | // for XRP/CSC only: 104 | https://api.onthedex.live/public/v1/ticker/XRP:CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr 105 | 106 | // for SOLO/XRP and CSC/XRP (2 pairs in one request): 107 | https://api.onthedex.live/public/v1/ticker/CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr:XRP+SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz:XRP 108 | ``` 109 | 110 | Other options are available as specified below to format responses in a preferred way. 111 | 112 | 113 | #### Example `WEBSOCKET`: 114 | Websocket data is available as above except via the websocket endpoint beginning `wss://`. Data packets will be returned approximately every 4 seconds. 115 | ```javascript 116 | // create websocket instance 117 | var mySocket = new WebSocket("wss://api.onthedex.live/public/v1/ticker/CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr:XRP"); 118 | 119 | // add event listener for receiving data from the API 120 | mySocket.onmessage = function (event) { 121 | const token_data = JSON.parse(event.data); 122 | // always check there is no token_data.error first 123 | if (!token_data['error']) { 124 | // all good, so access .pairs array for the data on the token(s) requested 125 | token_data.pairs && token_data.pairs.forEach(pair => { 126 | const theBaseCurrency = (pair.b.c ? pair.b.c : pair.b); 127 | const theQuoteCurrency = (pair.q.c ? pair.q.c : pair.q); 128 | console.log('Token pair ' + theBaseCurrency + '/' + theQuoteCurrency + ' was last traded at a price of ' + pair.l + ' ' + theQuoteCurrency); 129 | }); 130 | } else { 131 | console.log('There was an error returned from the websocket API:', token_data.error, token_data.message); 132 | } 133 | }; 134 | ``` 135 | 136 | 137 | #### Parameters to specify: 138 | These parameters are valid for both `GET` and `WEBSOCKET` requests: 139 | 140 | Parameter | Specification | Description 141 | --- | --- | --- 142 | `by` | `volume` (traded volume in USD equivalent value, descending), `trades` (number of trades, descending), `base` (base currency code, ascending) | Sorts the returned pairs by the parameter specified. Default: `volume` 143 | `page` | Integer | Data page number to return. Default is page `1`. 144 | `per_page` | Integer | Maximum number of results to return for this page. Default (and max) is `100`. 145 | 146 | 147 | #### Returned properties: 148 | Remember to always check the `error` property first before attempting to process any of the below returned parameters. 149 | 150 | Property (`GET`) | Property (`WEBSOCKET`) | Type | Description 151 | --- | --- | --- | --- 152 | `pairs` | `pairs` | Array | List of pairings returned 153 | `pairs[].base` | `pairs[].b` | Object | If base currency is XRP, this contains the string `XRP`. In all other cases, an object is returned with `currency` and `issuer` properties 154 | `pairs[].base.currency` | `pairs[].b.c` | String | Currency code of the base token 155 | `pairs[].base.issuer` | `pairs[].b.i` |String | r-Address of the base token issuer 156 | `pairs[].quote` | `pairs[].q` | String **or** Object | If quote currency is XRP, this contains the string `XRP`. In all other cases, an object is returned with `currency` and `issuer` properties 157 | `pairs[].quote.currency` | `pairs[].q.c` | String | Currency code of the quote token 158 | `pairs[].quote.issuer` | `pairs[].q.i` | String | r-Address of the quote token issuer (not specified if quote = `XRP`) 159 | `pairs[].volume_base` | `pairs[].vb` | Float | Volume of the base token traded this pair in the last rolling 24 hours 160 | `pairs[].volume_quote` | `pairs[].vq` | Float | Volume of the quote token traded this pair in the last rolling 24 hours 161 | `pairs[].volume_usd` | `pairs[].vfx` | Float | Volume of USD equivalent value traded this pair in the last rolling 24 hours 162 | `pairs[].price_mid` | `pairs[].pm` | Float | Current mid price on the order books of this pairing. If no orders on both sides of the book for this pair, result is `null` 163 | `pairs[].price_hi` | `pairs[].ph` | Float | The highest price achieved across all trades of this pair in the last rolling 24 hours 164 | `pairs[].price_lo` | `pairs[].pl` | Float | The lowest price achieved across all trades of this pair in the last rolling 24 hours 165 | `pairs[].last` | `pairs[].l` | Float | The price achieved on most recent trade of the pair 166 | `pairs[].time` | `pairs[].t` | Integer, UNIX timestamp (seconds) | Time of most recent trade of the pair 167 | `pairs[].ago24` | `pairs[].a24` | Float | The price last traded from (rolling) 24 hours ago 168 | `pairs[].pc24` | `pairs[].pc24` | Float | The percentage change in price from (rolling) 24 hours ago to last traded 169 | `pairs[].trend` | `pairs[].tr` | String | Either `up` or `down` (or unspecified if new), reflecting the last trade direction from the trade immediately prior. If not determined, this property will be missing. 170 | `pairs[].num_trades` | `pairs[].n` | Integer | Total number of individual trades on this pairing in the last rolling 24 hours 171 | 172 | #### Websocket specifics: 173 | Websocket returned property names are shortened from their REST equivalents as detailed above. 174 | Websocket version will return a data packet every ledger close (approx every 4 seconds) and the returned data will vary depending if changes from the initial connecting request were detected. 175 | 176 | When connecting to the websocket version of this endpoint, be aware that the server will return a `pairs` array of data for any property that has changed since the last `pairs` packet - this may not necessarily be the `l` (`last`) price that has changed. 177 | It could be that the rolling 24 hours calculation has changed, for example, triggering the sending of a data packet to your connection. 178 | Any property that has changed will trigger data for the whole request to be sent to you (that is, a change in any property of 1 pair will mean data for all your requested pairs will be sent, not just for the changed pair). 179 | 180 | 181 | 182 | 183 | 184 | ## `GET`/`POST`: `/token/meta/:tokens` 185 | Returns any metadata known for the token(s) specified (for example, token official name and path to logo file). Single tokens can be requested by simple GET request. Multiple tokens can be requested either by concatenating tokens with `+` character or 186 | using `POST` method to submit array of strings or token objects (see below). 187 | 188 | #### GET Example (single token): 189 | ``` 190 | https://api.onthedex.live/public/v1/token/meta/CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr 191 | ``` 192 | 193 | #### POST Examples (multiple tokens): 194 | ```javascript 195 | // Pass array of token strings: 196 | const tokenData = await axios.post(`https://api.onthedex.live/public/v1/token/meta`, { 197 | tokens: [ 198 | 'rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr.CSC', 199 | 'SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz' 200 | ] 201 | }) 202 | 203 | // Or pass array of token objects with issuer and currency properties: 204 | const tokenData = await axios.post(`https://api.onthedex.live/public/v1/token/meta`, { 205 | tokens: [ 206 | { 207 | issuer: 'rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr', 208 | currency: 'CSC' 209 | }, 210 | { 211 | issuer: 'rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz', 212 | currency: 'SOLO' 213 | } 214 | ] 215 | }) 216 | ``` 217 | 218 | #### GET path to specify: 219 | The `:tokens` part of the path should be the currency code and issuer joined by a period `.` (see example above). Multiple tokens can be requested by separating tokens with a `+` character. 220 | 221 | #### Returned properties: 222 | Property | Type | Description 223 | --- | --- | --- 224 | `meta` | Array | List of tokens and their metadata found. 225 | `meta[].currency` | String | Requested currency code of the token 226 | `meta[].issuer` | String | Requested r-Address of the token issuer 227 | `meta[].token_name` | String | Official name of the token, if known 228 | `meta[].logo_file` | String | URL to scalable vector logo of the token, if known 229 | 230 | If the token has no name or logo, these properties will be missing from the returned results. Note: no check of token validity is made - if the token does not exist, your results will contain just the currency and issuer properties as requested. 231 | 232 | #### Example returned data: 233 | ```json 234 | { 235 | "meta":[ 236 | { 237 | "currency": "CSC", 238 | "issuer": "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr", 239 | "token_name": "CasinoCoin", 240 | "logo_file": "https://www.onthedex.live/tokens/logo/csc_rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr.svg" 241 | }, 242 | { 243 | "currency": "SOLO", 244 | "issuer": "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz", 245 | "token_name": "Sologenic", 246 | "logo_file": "https://www.onthedex.live/tokens/logo/solo_rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz.svg" 247 | } 248 | ] 249 | } 250 | ``` 251 | 252 | 253 | 254 | ## `GET`: `/daily/tokens` 255 | Returns a **list of tokens traded** on the XRP Ledger DEX at any time within the last rolling 24 hours, together with their key metrics. Max returned items is 100, which in combination with the `by` parameter, allows getting the top 100 by volume, market cap, or trade count. 256 | 257 | #### Example: 258 | ``` 259 | https://api.onthedex.live/public/v1/daily/tokens 260 | ``` 261 | 262 | #### GET parameters to specify: 263 | Parameter | Specification | Description 264 | --- | --- | --- 265 | `by` | `volume` (traded volume in USD equivalent value), `market_cap` (market capitalization, in USD), or `trades` (number of trades) | Sorts the returned token list by the parameter specified, in descending order. Default: `volume` 266 | `min_trades` | Integer | Filter the tokens returned to include only those tokens that have traded the specified number of times or more in the last 24 hours. Use to exclude illiquid tokens particularly when ordering `by`=`market_cap`. Default: `100`. To include all traded tokens, set to `1`. 267 | `page` | Integer | Data page number to return. Default is page `1`. 268 | `per_page` | Integer | Maximum number of results to return for this page. Default (and max) is `100`. 269 | 270 | 271 | 272 | #### Returned properties: 273 | Property | Type | Description 274 | --- | --- | --- 275 | `tokens` | Array | List of tokens returned 276 | `tokens[].currency` | String | Currency code of the token, eg. `USD` 277 | `tokens[].issuer` | String | r-Address of the token issuer 278 | `tokens[].token_name` | String | Official name of the token, if known 279 | `tokens[].market_cap` | Integer | Market capitalization of the token in USD based on current mid price and issued suppy of the token 280 | `tokens[].volume_token` | Float | The total volume of the token traded across all its pairs 281 | `tokens[].volume_usd` | Float | The USD equivalent volume traded across all its pairs at the time of each trade taking place 282 | `tokens[].price_mid_usd` | Float | The current mid price in USD equivalent based on the most liquid token pair (currently token/XRP) 283 | `tokens[].last_trade_at` | ISO Timestamp | Date and time (in GMT) of the last trade of this token across all its pairs 284 | `tokens[].num_trades` | Integer | Total number of individual trades on this token across all its pairs 285 | `tokens[].supply` | Float | Total number of tokens under supply obligation by the issuing account 286 | `tokens[].logo_file` | String | URL to scalable vector logo of the token, if known 287 | 288 | #### Example returned data: 289 | ```json 290 | { 291 | "tokens": [ 292 | { 293 | "currency": "USD", 294 | "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", 295 | "last_trade_at": "2022-05-10T15:05:42.000Z", 296 | "market_cap": 32878521, 297 | "num_trades": 768, 298 | "price_mid_usd": 1.0055049538537304, 299 | "supply": 32698516.82373998, 300 | "token_name": "Bitstamp USD", 301 | "volume_token": 774648.164521166, 302 | "volume_usd": 776031.2081952752, 303 | "logo_file": "https://www.onthedex.live/tokens/logo/usd_rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B.svg" 304 | }, 305 | { 306 | "currency": "SOLO", 307 | "issuer": "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz", 308 | "last_trade_at": "2022-05-10T15:14:52.000Z", 309 | "market_cap": 146978419, 310 | "num_trades": 2850, 311 | "price_mid_usd": 0.36781515699146133, 312 | "supply": 399598591.6977495, 313 | "token_name": "Sologenic", 314 | "volume_token": 1487728.1869581435, 315 | "volume_usd": 544250.4805697609, 316 | "logo_file": "https://www.onthedex.live/tokens/logo/solo_rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz.svg" 317 | }, 318 | ... 319 | ] 320 | } 321 | ``` 322 | 323 | 324 | ## `GET`: `/daily/pairs` 325 | Returns a **list of pairs (base / quote) traded** on the XRP Ledger DEX at any time within the last rolling 24 hours, together with their key metrics. 326 | 327 | #### Example: 328 | ``` 329 | https://api.onthedex.live/public/v1/daily/pairs?token=CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr 330 | ``` 331 | 332 | #### GET parameters to specify: 333 | Parameter | Specification | Description 334 | --- | --- | --- 335 | `token` | String, optional | When not specified, returns complete list of traded pairs. Note that this complete list includes inverted pairs (eg. TOKEN/USD.rhub and USD.rhub/TOKEN) with the same overall metrics for easier access to the pair you might want. Be sure not to double-count such entries where relevant in your use case. If `token` is specified as a concatenation of currency code and issuing account with a period `.` separator, returns only those pairs traded against the specified token. Examples: `CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr`, `XRP`. If `token` is set to be `XRP`, tokens are always returned as the base currency with XRP as the quote currency. If `token` is specified in conjuction with `quote` below, `token` is treated as the base currency request (including if set as XRP) and data will be returned in this configuration. 336 | `quote` | String, optional | If specified, must be used with `token` parameter and will limit the return data to be for this pairing only (`token`/`quote`). Examples: `SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz`, `XRP`. 337 | `by` | `volume` (traded volume in USD equivalent value), `trades` (number of trades) | Sorts the returned pairs by the parameter specified, in descending order. Default: `volume` 338 | `page` | Integer | Data page number to return. Default is page `1`. 339 | `per_page` | Integer | Maximum number of results to return for this page. Default (and max) is `100`. 340 | 341 | #### Returned properties: 342 | Property | Type | Description 343 | --- | --- | --- 344 | `pairs` | Array | List of tokens returned 345 | `pairs[].base` | Object | Base currency specified with `currency` and `issuer` properties 346 | `pairs[].base.currency` | String | Currency code of the base token 347 | `pairs[].base.issuer` | String | r-Address of the base token issuer 348 | `pairs[].quote` | String **or** Object | If quote currency is XRP, this contains the string `XRP`. In all other cases, an object is returned with `currency` and `issuer` properties 349 | `pairs[].quote.currency` | String | Currency code of the quote token 350 | `pairs[].quote.issuer` | String | r-Address of the quote token issuer (not specified if quote = `XRP`) 351 | `pairs[].volume_base` | Float | Volume of the base token traded this pair in the last rolling 24 hours 352 | `pairs[].volume_quote` | Float | Volume of the quote token traded this pair in the last rolling 24 hours 353 | `pairs[].volume_usd` | Float | Volume of USD equivalent value traded this pair in the last rolling 24 hours 354 | `pairs[].price_mid` | Float | Current mid price on the order books of this pairing. If no orders on both sides of the book for this pair, result is `null` 355 | `pairs[].price_hi` | Float | The highest price achieved across all trades of this pair in the last rolling 24 hours 356 | `pairs[].price_lo` | Float | The lowest price achieved across all trades of this pair in the last rolling 24 hours 357 | `pairs[].price_hi_usd` | Float | The highest USD equivalent price achieved across all trades of this pair in the last rolling 24 hours 358 | `pairs[].price_lo_usd` | Float | The lowest USD equivalent price achieved across all trades of this pair in the last rolling 24 hours 359 | `pairs[].last` | Float | The price achieved on most recent trade of the pair 360 | `pairs[].ago24` | Float | The price last traded from (rolling) 24 hours ago 361 | `pairs[].pc24` | Float | The percentage change in price from (rolling) 24 hours ago to last traded 362 | `pairs[].trend` | String | Either `up` or `down` (or unspecified if new), reflecting the last trade direction from the trade immediately prior 363 | 364 | 365 | 366 | 367 | `pairs[].num_trades` | Integer | Total number of individual trades on this pair 368 | 369 | #### Example returned data: 370 | ```json 371 | { 372 | "pairs": [ 373 | { 374 | "base":{ 375 | "currency":"USD", 376 | "issuer":"rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq" 377 | }, 378 | "quote": "XRP", 379 | "price_hi": 3.2871288176530022, 380 | "price_lo": 2.747280225147826, 381 | "price_hi_usd": 1.0121361553828967, 382 | "price_lo_usd": 0.9893297283245092, 383 | "volume_base": 696691.0645208354, 384 | "volume_quote": 2032756.865624, 385 | "volume_usd": 697858.4758794114, 386 | "num_trades": 524, 387 | "price_mid": 3.233545692446336, 388 | "ago24": 2.865329512893983, 389 | "pc24": 13.27, 390 | "last": 3.245452115401085, 391 | "trend": "down" 392 | }, 393 | ... 394 | ] 395 | } 396 | ``` 397 | 398 | 399 | 400 | ## `GET`/`POST`: `/aggregator` 401 | Returns a **list of aggregator data** for all tokens traded on the XRP Ledger DEX at any time within the last rolling 24 hours, together with each token's pairings and associated key metrics. 402 | 403 | #### GET Example: 404 | ``` 405 | GET https://api.onthedex.live/public/v1/aggregator 406 | ``` 407 | 408 | #### POST Example: 409 | ``` 410 | curl -d '{"tokens": [{"currency": "CSC", "issuer": "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"}, "SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz"]}' -X POST https://api.onthedex.live/public/v1/aggregator 411 | ``` 412 | 413 | #### GET/POST parameters to specify: 414 | Parameter | Specification | Description 415 | --- | --- | --- 416 | `token` | String, `GET` only | If specified, returns the aggregator just for the specified token. Example: `SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz` 417 | `tokens` | Array of Object or String, `POST` only | If specified, returns the aggregator for the specified token(s) only. The array can contain tokens in a mixture of formats: objects with `currency` and `issuer` properties, and/or strings with period-separated currency and issuer. Example: `[{"currency": "CSC", "issuer": "rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"}, "SOLO.rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz"]` 418 | 419 | #### Returned properties: 420 | Property | Type | Description 421 | --- | --- | --- 422 | `tokens` | Array | List of tokens returned 423 | `tokens[].currency` | String | Currency code of the base token 424 | `tokens[].issuer` | String | r-Address of the base token issuer 425 | `tokens[].name` | String | Official name of the token, if known 426 | `tokens[].supply` | Float | Total number of tokens under supply obligation by the issuing account 427 | `tokens[].market_cap` | Integer | Market capitalization of the token in USD based on current mid price and issued suppy of the token 428 | `tokens[].logo_file` | String | URL to scalable vector logo of the token, if known 429 | `tokens[].dex` | Object | Information on the DEX specific trades for this token 430 | `tokens[].dex.price` | Float | XRPL DEX current mid price in USD fiat equivalent for the token via most liquid pairing 431 | `tokens[].dex.pc24` | Float | USD fiat equivalent price change in percent from the price 24 hours ago (rolling) 432 | `tokens[].dex.fx24` | Float | USD fiat equivalent sum of all trades across all pairs for this token in the last rolling 24 hours 433 | `tokens[].dex.sum24` | Float | Total volume traded across all pairs for this token in the last rolling 24 hours 434 | `tokens[].dex.count24` | Integer | Number of trades across all pairs for this token in the last rolling 24 hours 435 | `tokens[].dex.pairs` | Array | List of pair data traded against this token in the last rolling 24 hours 436 | `tokens[].dex.pairs[].quote` | String | Currency code of the quote token 437 | `tokens[].dex.pairs[].issuer` | String | r-Address of the quote token issuer (not specified if quote = `XRP`) 438 | `tokens[].dex.pairs[].name` | String | Official name of the quote currency, if known 439 | `tokens[].dex.pairs[].vol_token` | Number | Volume of token currency traded in the period against this quote currency 440 | `tokens[].dex.pairs[].vol_quote` | Number | Volume of this quote currency traded in the period against the token currency 441 | `tokens[].dex.pairs[].last` | Float | Price achieved on most recent trade of the pair 442 | `tokens[].dex.pairs[].time` | Integer, UNIX timestamp (seconds) | Time of most recent trade of the pair 443 | `tokens[].dex.pairs[].ask` | Float | Current ask (sell) price of the pair on the order books 444 | `tokens[].dex.pairs[].bid` | Float | Current bid (buy) price of the pair on the order books 445 | `tokens[].dex.pairs[].mid` | Float | Current mid price of the pair on the order books 446 | `tokens[].dex.pairs[].spr` | Float | Current price spread between bid and ask prices 447 | `tokens[].dex.pairs[].hi24` | Float | Highest traded price of the pair within the period 448 | `tokens[].dex.pairs[].lo24` | Float | Lowest traded price of the pair within the period 449 | `tokens[].dex.pairs[].ago24` | Float | Price last traded 24 hours ago (rolling) 450 | `tokens[].dex.pairs[].pc24` | Float | Price change in percent from the price 24 hours ago (rolling) 451 | `tokens[].dex.pairs[].fx` | Float | USD fiat equivalent sum of all trades of this pair in the last rolling 24 hours 452 | `tokens[].dex.pairs[].count24` | Integer | Number of trades of this pair in the last rolling 24 hours 453 | 454 | 455 | 456 | #### Example returned data: 457 | ```json 458 | { 459 | "tokens": [ 460 | { 461 | "currency": "USD", 462 | "issuer": "rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B", 463 | "name": "Bitstamp USD", 464 | "supply": 66956924, 465 | "market_cap": 67369988, 466 | "logo_file": "https://www.onthedex.live/tokens/logo/usd_rvYAfWj5gh67oV6fW32ZzP3Aw4Eubs59B.svg", 467 | "dex": { 468 | "sum24": 3697128, 469 | "fx24": 3710229.4243013225, 470 | "price": 1.0061690928246487, 471 | "count24": 1049, 472 | "pairs": [ 473 | { 474 | "quote": "XRP", 475 | "vol_token": 3696703, 476 | "vol_quote": 9534078, 477 | "time": 1653582001, 478 | "last": 2.5152037780373253, 479 | "fx": 3709805.121005436, 480 | "bid": 2.5139844891, 481 | "ask": 2.5206369411, 482 | "mid": 2.5173107151, 483 | "spr": 0.006652452, 484 | "hi24": 2.6562030364266627, 485 | "lo24": 2.380952380952381, 486 | "ago24": 2.4876708046381366, 487 | "pc24": 1.11, 488 | "count24": 1045 489 | }, 490 | { 491 | "quote": "CNY", 492 | "issuer": "rKiCet8SdvWxPXnAgYarFUXMh1zCPz432Y", 493 | "name": "RippleFox CNY", 494 | "vol_token": 181, 495 | "vol_quote": 1205, 496 | "time": 1653580582, 497 | "last": 6.65999999999999, 498 | "fx": 180.91095660379398, 499 | "bid": 6.66, 500 | "ask": 6.82221, 501 | "mid": 6.741105, 502 | "spr": 0.16221, 503 | "hi24": 6.65999999999999, 504 | "lo24": 6.65999999999999, 505 | "ago24": 6.659999999999614, 506 | "count24": 2 507 | }, 508 | { 509 | "quote": "BTC", 510 | "issuer": "rchGBxcD1A1C2tdxF6papQYZ8kjRKMYcL", 511 | "name": "GateHub Bitcoin", 512 | "vol_token": 181, 513 | "vol_quote": 0.00621774, 514 | "time": 1653580582, 515 | "last": 0.0000343005035829973, 516 | "fx": 181.272593767661, 517 | "bid": 0.000010011212558065033, 518 | "ask": 0.00003398053545634613, 519 | "mid": 0.000015465917070579048, 520 | "spr": 0.00001419257292890581, 521 | "hi24": 0.0000343005035829973, 522 | "lo24": 0.0000343005035829973, 523 | "ago24": 0.000028184003834661707, 524 | "pc24": 17.83, 525 | "count24": 1 526 | }, 527 | { 528 | "quote": "USD", 529 | "issuer": "rhub8VRN55s94qWKDv6jmDy1pUykJzF3wq", 530 | "name": "GateHub USD", 531 | "vol_token": 62.12, 532 | "vol_quote": 62.12, 533 | "time": 1653579980, 534 | "last": 1, 535 | "fx": 62.119745515061, 536 | "bid": 1, 537 | "ask": 1.0102235143962908, 538 | "mid": 1.0050857600782255, 539 | "spr": 98.81372248693705, 540 | "hi24": 1, 541 | "lo24": 1, 542 | "count24": 1 543 | } 544 | ], 545 | "pc24":0.62 546 | } 547 | }, 548 | ... 549 | { 550 | "currency":"CSC", 551 | "issuer":"rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr", 552 | "name":"CasinoCoin", 553 | "supply":64992453166, 554 | "market_cap":43291147, 555 | "logo_file": "https://www.onthedex.live/tokens/logo/csc_rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr.svg", 556 | "dex":{ 557 | "sum24":24083073, 558 | "fx24":15730.828657375625, 559 | "price":0.0006660949774231682, 560 | "count24":518, 561 | "pairs":[ 562 | { 563 | "flags":1, 564 | "quote":"XRP", 565 | "vol_token":24083073, 566 | "vol_quote":39472, 567 | "time":1653581760, 568 | "last":0.0016393442622950817, 569 | "fx":15730.828657375625, 570 | "bid":0.0016393443, 571 | "ask":0.0016936304, 572 | "mid":0.0016664873, 573 | "spr":0.0000542861, 574 | "hi24":0.0017211531849988541, 575 | "lo24":0.0015850121596770262, 576 | "ago24":0.001585012125342759, 577 | "pc24":3.43, 578 | "count24":518 579 | } 580 | ], 581 | "pc24":4.34 582 | } 583 | }, 584 | ... 585 | ] 586 | } 587 | 588 | 589 | ``` 590 | 591 | 592 | 593 | 594 | 595 | ## `GET`: `/ohlc` 596 | Returns **Open/High/Low/Close price data** for a given token pairing for a given timeframe interval. 597 | 598 | #### Example: 599 | ``` 600 | https://api.onthedex.live/public/v1/ohlc?base=CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr"e=XRP&bars=100&interval=60 601 | ``` 602 | 603 | #### GET parameters to specify: 604 | Parameter | Specification | Description 605 | --- | --- | --- 606 | `base` | String | Concatenation of base currency code and issuing account with a period `.` separator. Examples: `CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr`, `XRP` 607 | `quote` | String | Concatenation of quote currency code and issuing account with a period `.` separator. Examples: `CSC.rCSCManTZ8ME9EoLrSHHYKW8PPwWMgkwr`, `XRP` 608 | `interval` | `5`, `15`, `60`, `240`, `D`, or `W` | Interval timeframe for which OHLC data is required. Integer values represent timeframe in minutes. Ignored when `marker` is specified. 609 | `tf` | `ISO` (optional) | Time format to return. Default is UNIX timestamp in seconds since epoch. Setting `ISO` returns string of ISO format time per bar instead. 610 | `ending` | String or Integer (optional) | A string timestamp, or UNIX timestamp in seconds, representing the last time bar to return. If not specified, current time is used. Ignored when `marker` is specified. Examples: `2021-12-25T14:00:00Z`, `2022-01-01`, `2022-03-15 12:00:00`, `1652054400` 611 | `bars` | Integer | Number of bars of data to return, starting from the `ending` time and moving backwards for this number of bars. Default varies depending on specified `tf`. Maximum returned bars is 5000 per call. Ignored when `marker` is specified. 612 | `cf` | `yes` (optional) | Flag for requesting the carry-forward open price. If set to `yes`, modifies the open `o` property returned for each time bar (see below) 613 | `fx` | `USD` (optional) | If set, returns the OHLC data converted to forex equivalent (USD equivalent only presently) to show this pairing relative to USD 614 | `marker` | String (optional) | If set and valid from a previous call, the next set of data backwards in time from the last call is returned. Mandatory parameters when `marker` is specified are: `base`, `quote`. Ignored parameters when `marker` is set are: `ending`, `interval`, `bars`. Other parameters should be specified identical to the original request where relevant. 615 | 616 | #### Returned properties: 617 | Property | Type | Description 618 | --- | --- | --- 619 | `spec` | Object | The interpreted specification from the passed parameters; what the API determined to be your request 620 | `spec.base` | String **or** Object | If base currency is XRP, this contains the string `XRP`. In all other cases, and object is returned with `currency` and `issuer` properties 621 | `spec.base.currency` | String | Currency code of the base token 622 | `spec.base.issuer` | String | r-Address of the base token issuer 623 | `spec.quote` | String **or** Object | If quote currency is XRP, this contains the string `XRP`. In all other cases, an object is returned with `currency` and `issuer` properties 624 | `spec.quote.currency` | String | Currency code of the quote token 625 | `spec.quote.issuer` | String | r-Address of the quote token issuer 626 | `spec.interval` | String | Interval timeframe 627 | `spec.ending` | Timestamp or String | The passed `ending` parameter 628 | `spec.bars` | Integer | The number of bars queried for. Should be equal to the number of `data.ohlc` items returned. 629 | `spec.cf` | String | The passed `cf` parameter 630 | `spec.fx` | String | The passed `fx` parameter 631 | `spec.tf` | String | The passed `tf` parameter 632 | `data` | Object | The main returned data object 633 | `data.marker` | String | The response includes a marker field when more data of the type requested in the original call exists. To retrieve the next block of data, call this path again with the `marker` field populated with this value. If no `marker` property is returned, there is no more data to retrieve. See `marker` parameter above. 634 | `data.ohlc[]` | Array | List of OHLC price bar data in ascending time order 635 | `data.ohlc[].t` | Integer or ISO Timestamp | UNIX Timestamp (default when `tf` not set) or ISO Timestamp (if `tf`=`ISO`) in GMT of the opening time of the price bar 636 | `data.ohlc[].o` | Float | Opening trading price of the time bar. If `cf` was set to `yes`, this property contains the closing price of the previous bar, and is distinct from the original pairing `o` price of this bar. It permits the representation of this time bar opening at the same price the previous bar closed at, effectively ensuring there are no price 'gaps' in data bar-to-bar due to illiquid price jumps. 637 | `data.ohlc[].h` | Float | Highest trading price within the time bar 638 | `data.ohlc[].l` | Float | Lowest trading price within the time bar 639 | `data.ohlc[].c` | Float | Closing trading price of the time bar 640 | `data.ohlc[].vb` | Float | Volume of base currency traded within the time bar 641 | `data.ohlc[].vq` | Float | Volume of quote currency traded within the time bar 642 | `data.ohlc[].vusd` | Float | Volume of USD equivalent traded within the time bar. Only returned if property `fx`=`USD` 643 | 644 | #### Example returned data: 645 | ```json 646 | { 647 | "spec": { 648 | "base": { 649 | "currency": "SOLO", 650 | "issuer": "rsoLo2S1kiGeCcn6hCUXVrCpGMWLrRrLZz" 651 | }, 652 | "quote": "XRP", 653 | "interval": "60", 654 | "ending": "2021-11-30 12:00:00", 655 | "bars": 100, 656 | "cf": "yes", 657 | "tf": "ISO" 658 | }, 659 | "data": { 660 | "ohlc": [ 661 | { 662 | "t": "2021-11-26T09:00:00.000Z", 663 | "vb": 137921.15374666537, 664 | "vq": 455238.8346539995, 665 | "o": 3.2729339999096463, 666 | "h": 3.4467817896389317, 667 | "l": 3.200000000379838, 668 | "c": 3.2729339999096463 669 | }, 670 | { 671 | "t": "2021-11-26T10:00:00.000Z", 672 | "vb": 97760.89569615627, 673 | "vq": 318993.3424850003, 674 | "o": 3.2729339999096463, 675 | "h": 3.390000000000026, 676 | "l": 3.182000000133979, 677 | "c": 3.295 678 | }, 679 | { 680 | "t": "2021-11-26T11:00:00.000Z", 681 | "vb": 85772.03223426663, 682 | "vq": 287311.8863329999, 683 | "o": 3.295, 684 | "h": 3.4482824387894633, 685 | "l": 3.1800000048945862, 686 | "c": 3.3300000323603123 687 | }, 688 | ... 689 | ] 690 | } 691 | } 692 | ``` 693 | 694 | #### Difference between `cf` open and normal open price: 695 | This first image below shows the effect of `cf` being unset, where the `o`pen price is unaffected by the previous bar values. Where price gaps exist bar-to-bar, they will be shown as a result: 696 | ![Normal Open Prices](/images/example_normal_open_prices.png?raw=true "Normal Open Prices on illiquid token or interval, showing gaps") 697 | 698 | This second image below shows the effect of specifying `cf`=`yes`, to close the gap between bars where there would otherwise be a gap. The previous bar's close price is carried forward to be the current bar's open price: 699 | ![Adjusted Open Prices](/images/example_open_prices_with_cf_flag.png?raw=true "Adjusted Open Prices with carried forward open price") -------------------------------------------------------------------------------- /examples/websocket_basic.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 73 | 74 | 75 | Open your console for messages too. 76 | 77 |

WebSocket example

78 | 79 | 80 | -------------------------------------------------------------------------------- /examples/websocket_token_price_widget.html: -------------------------------------------------------------------------------- 1 | 2 | 3 | 4 | 111 | 112 | 113 | 114 | 115 |

Token Price of is

116 |

117 | 118 | 119 | 120 | -------------------------------------------------------------------------------- /images/example_normal_open_prices.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OnTheDEX/xrpledger-token-data-api/afdfcfc0f4984f650030ad4524d6ea117467b3c9/images/example_normal_open_prices.png -------------------------------------------------------------------------------- /images/example_open_prices_with_cf_flag.png: -------------------------------------------------------------------------------- https://raw.githubusercontent.com/OnTheDEX/xrpledger-token-data-api/afdfcfc0f4984f650030ad4524d6ea117467b3c9/images/example_open_prices_with_cf_flag.png --------------------------------------------------------------------------------