{"id":25716336,"url":"https://github.com/interledgerjs/ilp-price","last_synced_at":"2026-06-07T20:32:35.578Z","repository":{"id":57271871,"uuid":"130742638","full_name":"interledgerjs/ilp-price","owner":"interledgerjs","description":"Fetch price info for currency-agnostic apps on Interledger","archived":false,"fork":false,"pushed_at":"2018-07-02T16:26:50.000Z","size":101,"stargazers_count":1,"open_issues_count":0,"forks_count":1,"subscribers_count":3,"default_branch":"master","last_synced_at":"2024-04-14T10:12:59.527Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/interledgerjs.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null}},"created_at":"2018-04-23T18:56:05.000Z","updated_at":"2024-04-14T10:12:59.528Z","dependencies_parsed_at":"2022-08-25T00:11:15.114Z","dependency_job_id":null,"html_url":"https://github.com/interledgerjs/ilp-price","commit_stats":null,"previous_names":["sharafian/ilp-price"],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Filp-price","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Filp-price/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Filp-price/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Filp-price/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interledgerjs","download_url":"https://codeload.github.com/interledgerjs/ilp-price/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":240690860,"owners_count":19841955,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2025-02-25T14:53:02.209Z","updated_at":"2026-06-07T20:32:35.477Z","avatar_url":"https://github.com/interledgerjs.png","language":"JavaScript","funding_links":[],"categories":[],"sub_categories":[],"readme":"# ILP Price\n\u003e Fetch price info for currency-agnostic apps on Interledger\n\n- [Overview](#overview)\n- [Specify Your Own Landmarks](#specify-your-own-landmarks)\n  - [JSON Format](#json-format)\n    - [Prefix Map](#prefix-map)\n    - [Currency Map](#currency-map)\n    - [Landmark List](#landmark-list)\n  - [As Environment Variable](#environment-variable)\n  - [As File](#file)\n- [Examples](#examples)\n- [TODOs](#todos)\n\n## Overview\n\nWhen you're writing an application on Interledger, you shouldn't make any\nassumptions about what currency the user has.\n\nTheir ledger may be in a commonly known currency like USD, a cryptocurrency\nlike XRP or BTC, or it may even be a completely alien currency, with no rates\navailable.\n\nFetching rates from an outside source introduces a point of failure and may not\neven have the right rates.\n\n`ilp-price` solves this problem by keeping a list of \"landmarks,\" which are\nreceivers _within the Interledger network_ that represent a realisticly liquid\npath to a given currency. By sending a probing payment to these landmarks, you\ncan discover a conversion rate to their currencies.\n\nThis module will include some defaults, but these can be overridden with\nenvironment variables or a config file.\n\n## Specify Your Own Landmarks\n\n### JSON Format\n\nLandmarks for `ilp-price` are specified in the following format:\n\n```js\n{\n  \"g.\": {\n    \"XRP\": [\n      \"$xrp-landmark.example.com\",\n      \"$other.example.com\",\n      \"https://raw-spsp-endpoint.example.com\",\n      // ...\n    ],\n    \"USD\": [\n      \"$usd-landmark.example.com\",\n      // ...\n    ],\n    // ...\n  },\n  \"test.\": {\n    \"XRP\": [\n      \"$spsp.ilp-test.com\"\n    ]\n  },\n  // ...\n}\n```\n\nThe landmark specification is made up of three levels.\n\n- Prefix map\n- Currency map\n- Landmark list\n\n#### Prefix Map\n\nThe outermost object contains ILP address prefixes. When you ask for a price,\nan [ILDCP](https://github.com/interledgerjs/ilp-protocol-ildcp) lookup is made,\nand the address is compared against the keys of this map.\n\nThe longest key which is a prefix of the address is selected. The value under\nthat key is then used as the currency map.\n\nIf no keys are prefixes of your ILP address, an error should be thrown.\n\n#### Currency Map\n\nThe currency map maps currency codes to landmark lists. A simple lookup is done\nwith the desired currency of your price lookup. The value associated with that\ncurrency code is used as the landmark list.\n\nIf the desired currency code is not present, an error should be thrown.\n\n#### Landmark List\n\nThe landmark lists are lists of [SPSP\nreceivers](https://github.com/interledger/rfcs/blob/master/0009-simple-payment-setup-protocol/0009-simple-payment-setup-protocol.md).\nThese receivers can be listed as raw HTTP(s) endpoints, or as [Payment\nPointers](https://github.com/interledger/rfcs/blob/master/0026-payment-pointers/0026-payment-pointers.md)\n\nThe landmark list is used to fetch an actual exchange rate by using the\nInterledger network and a transport protocol. If the rate cannot be retrieved\nthrough one landmark, then another one is tried.\n\nIf all landmarks return errors, an error is thrown.\n\n### Merging Landmarks\n\nBecause landmarks are loaded from many sources, there needs to be a way to\nmerge this information.  The [prefix maps](#prefix-map) and [currency\nmaps](#currency-map) are merged, but the [landmark lists](#landmark-list) are\nnot.\n\nFor example, let's say we have two landmark specifications.\n\nLandmark spec A:\n\n```js\n{\n  \"g.\": {\n    \"XRP\": [\n      \"$a.example\",\n      \"$b.example\"\n    ],\n    \"USD\": [\n      \"$c.example\",\n      \"$d.example\",\n      \"$e.example\"\n    ]\n  },\n  \"test.\": {\n    \"XRP\": [\n      \"$f.example\"\n    ]\n  }\n}\n```\n\nLandmark spec B:\n\n```\n{\n  \"g.\": {\n    \"XRP\": [\n      \"$g.example\"\n    ]\n  },\n  \"private.\": {\n    \"XRP\": [\n      \"$localhost\"\n    ]\n  }\n}\n```\n\nIf we merge landmark spec B into landmark spec A, we get the following result:\n\n```js\n{\n  \"g.\": {\n    \"XRP\": [\n      \"$g.example\"\n    ],\n    \"USD\": [\n      \"$c.example\",\n      \"$d.example\",\n      \"$e.example\"\n    ]\n  },\n  \"test.\": {\n    \"XRP\": [\n      \"$f.example\"\n    ]\n  },\n  \"private.\": {\n    \"XRP\": [\n      \"$localhost\"\n    ]\n  }\n}\n```\n\n### As Environment Variable\n\nYou can pass in an alternative landmark specification via the environment variable\n`ILP_PRICE_LANDMARKS`. This variable should be a string containing JSON, [in the\nformat specified above](#json-format).\n\nExample:\n\n```\nexport ILP_PRICE_LANDMARKS='{\"g.\":{\"XRP\":[\"$xrp-landmark.example.com\",\"$other.example.com\",\"https://raw-spsp-endpoint.example.com\"],\"USD\":[\"$usd-landmark.example.com\"]}}'\n```\n\nIf provided, this list will be [merged](#merging-landmarks) into the default\nlandmarks.\n\n### As File\n\nYou can also specify an alternate list by pointing to a JSON file. You can\nspecify this file via the environment variable `ILP_PRICE_LANDMARKS_FILE`.  It\nshould contain a string with the file's path. If this path is relative, then it\nis read relative to the current working directory.\n\nExample:\n\n```\nexport ILP_PRICE_LANDMARKS_FILE='/home/bob/my_price_infomation_file.json'\n```\n\nThis file will be [merged](#merging-landmarks) into the default landmarks. If `ILP_PRICE_LANDMARKS` is specified,\nit will be merged into the result of that operation.\n\nThe order of application goes:\n\n```\ndefault -\u003e ILP_PRICE_LANDMARKS_FILE -\u003e ILP_PRICE_LANDMARKS -\u003e constructor\n```\n\n## Examples\n\n```js\nconst Price = require('ilp-price')\n\n// Landmarks can be passed in explicitly; this is applied after the defaults\n// and after all environment variables. This is generally not a good idea,\n// though, unless you're populating the list from a source that can be updated\n// over time.\nconst customPrice1 = new Price({\n  landmarks: {\n    \"XRP\": [\n      \"$xrp-landmark.example.com\",\n      \"$other.example.com\",\n      \"https://raw-spsp-endpoint.example.com\"\n    ],\n    \"USD\": [\n      \"$usd-landmark.example.com\"\n    ]\n  }\n})\n\n// You can pass a plugin into the Price constructor. However, `ilp-plugin` is\n// used by default so this example below is redundant.\nconst plugin = require('ilp-plugin')()\nconst customPrice2 = new Price({\n  plugin\n})\n\n// The ordinary way to instantiate a Price helper.\nconst price = new Price()\n\n;(async function run () {\n\n  // Loads rate from:\n  //   - ILDCP (in case we already have USD)\n  //   - Landmarks under 'USD', in order. If one fails it falls back to the\n  //   next.\n\n  const twoCents = await price.fetch('USD', 0.02)\n  const oneXrp = await price.fetch('XRP', 1)\n\n  // You can bind price.fetch to create a convenience function, if you plan to\n  // do everything in one currency.\n\n  const toUsd = price.fetch.bind(price, 'USD')\n\n})()\n```\n\n## TODOs\n\n- [x] Handle livenet vs. testnet vs. others\n- [ ] Use up-to-date transport protocol\n- [ ] More landmarks for more currencies\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterledgerjs%2Filp-price","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterledgerjs%2Filp-price","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterledgerjs%2Filp-price/lists"}