Improving currencyrate plugin

.msggen.json

@@ -1425,7 +1425,8 @@
             "CurrencyConvert.msat": 1
         },
         "CurrencyrateRequest": {
-            "CurrencyRate.currency": 1
+            "CurrencyRate.currency": 1,
+            "CurrencyRate.source": 2
         },
         "CurrencyrateResponse": {
             "CurrencyRate.rate": 1
@@ -6339,6 +6340,10 @@
             "added": "v26.04",
             "deprecated": null
         },
+        "CurrencyRate.source": {
+            "added": "v26.06",
+            "deprecated": null
+        },
         "Datastore": {
             "added": "pre-v0.10.1",
             "deprecated": null

contrib/msggen/msggen/schema.json

@@ -7458,11 +7458,24 @@
       "$schema": "../rpc-schema-draft.json",
       "type": "object",
       "rpc": "currencyrate",
-      "title": "Command to determine a reasonable rate of conversion for a given currency",
+      "title": "Command to determine a reasonable BTC exchange rate for a given currency",
       "added": "v26.04",
       "description": [
-        "The **currencyrate** RPC command provides the conversion of one BTC into the given currency",
-        "It uses the median of the available exchange-rate sources for the requested currency."
+        "The **currencyrate** RPC command returns the exchange rate of one BTC in the given currency.",
+        "Rates are rounded to 3 decimal places as specified by ISO 4217.",
+        "",
+        "Without the optional *source* argument the command returns the median rate across all",
+        "configured exchange-rate sources.",
+        "",
+        "With *source* specified, the rate reported by that specific source is returned.",
+        "The list of active source names can be obtained via **listcurrencyrates**.",
+        "",
+        "To add or disable sources see the *currencyrate-add-source* and *currencyrate-disable-source*",
+        "options in **lightningd-config(5)**.",
+        "",
+        "EXAMPLE USAGE:",
+        "Get the median USD rate: `lightning-cli currencyrate USD`",
+        "Get the Binance USD rate: `lightning-cli currencyrate USD binance`"
       ],
       "request": {
         "required": [
@@ -7473,8 +7486,18 @@
           "currency": {
             "type": "string",
             "description": [
-              "The ISO-4217 currency code (e.g. USD) to convert to.",
-              "The plugin normalizes this value to uppercase before querying sources."
+              "The ISO 4217 currency code (e.g. USD) to convert to.",
+              "The plugin normalises this value to uppercase before querying sources."
+            ]
+          },
+          "source": {
+            "added": "v26.06",
+            "type": "string",
+            "description": [
+              "The name of a specific exchange-rate source to query.",
+              "If omitted, the median across all available sources is returned.",
+              "An error is returned if the source name is not recognised or has no",
+              "cached data for the requested currency."
             ]
           }
         }
@@ -7488,7 +7511,9 @@
           "rate": {
             "type": "number",
             "description": [
-              "The median value of one BTC, computed using the median result from the available sources."
+              "The number of currency units per 1 BTC, rounded to 3 decimal places (ISO 4217).",
+              "When *source* is omitted this is the median across all available sources.",
+              "When *source* is specified this is the rate reported by that source."
             ]
           }
         }
@@ -7497,10 +7522,45 @@
         "daywalker90 is mainly responsible."
       ],
       "see_also": [
-        "lightning-listcurrencyrates(7)"
+        "lightning-listcurrencyrates(7)",
+        "lightning-currencyconvert(7)",
+        "lightningd-config(5)"
       ],
       "resources": [
         "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
+      ],
+      "examples": [
+        {
+          "description": [
+            "Get the median BTC/USD rate across all configured sources:"
+          ],
+          "request": {
+            "id": "example:currencyrate#1",
+            "method": "currencyrate",
+            "params": {
+              "currency": "USD"
+            }
+          },
+          "response": {
+            "rate": 67889.825
+          }
+        },
+        {
+          "description": [
+            "Get the BTC/USD rate from the Binance source only:"
+          ],
+          "request": {
+            "id": "example:currencyrate#2",
+            "method": "currencyrate",
+            "params": {
+              "currency": "USD",
+              "source": "binance"
+            }
+          },
+          "response": {
+            "rate": 67931.9
+          }
+        }
       ]
     },
     "datastore.json": {

doc/schemas/currencyrate.json

@@ -2,11 +2,24 @@
   "$schema": "../rpc-schema-draft.json",
   "type": "object",
   "rpc": "currencyrate",
-  "title": "Command to determine a reasonable rate of conversion for a given currency",
+  "title": "Command to determine a reasonable BTC exchange rate for a given currency",
   "added": "v26.04",
   "description": [
-    "The **currencyrate** RPC command provides the conversion of one BTC into the given currency",
-    "It uses the median of the available exchange-rate sources for the requested currency."
+    "The **currencyrate** RPC command returns the exchange rate of one BTC in the given currency.",
+    "Rates are rounded to 3 decimal places as specified by ISO 4217.",
+    "",
+    "Without the optional *source* argument the command returns the median rate across all",
+    "configured exchange-rate sources.",
+    "",
+    "With *source* specified, the rate reported by that specific source is returned.",
+    "The list of active source names can be obtained via **listcurrencyrates**.",
+    "",
+    "To add or disable sources see the *currencyrate-add-source* and *currencyrate-disable-source*",
+    "options in **lightningd-config(5)**.",
+    "",
+    "EXAMPLE USAGE:",
+    "Get the median USD rate: `lightning-cli currencyrate USD`",
+    "Get the Binance USD rate: `lightning-cli currencyrate USD binance`"
   ],
   "request": {
     "required": [
@@ -17,8 +30,18 @@
       "currency": {
         "type": "string",
         "description": [
-          "The ISO-4217 currency code (e.g. USD) to convert to.",
-          "The plugin normalizes this value to uppercase before querying sources."
+          "The ISO 4217 currency code (e.g. USD) to convert to.",
+          "The plugin normalises this value to uppercase before querying sources."
+        ]
+      },
+      "source": {
+        "added": "v26.06",
+        "type": "string",
+        "description": [
+          "The name of a specific exchange-rate source to query.",
+          "If omitted, the median across all available sources is returned.",
+          "An error is returned if the source name is not recognised or has no",
+          "cached data for the requested currency."
         ]
       }
     }
@@ -32,7 +55,9 @@
       "rate": {
         "type": "number",
         "description": [
-          "The median value of one BTC, computed using the median result from the available sources."
+          "The number of currency units per 1 BTC, rounded to 3 decimal places (ISO 4217).",
+          "When *source* is omitted this is the median across all available sources.",
+          "When *source* is specified this is the rate reported by that source."
         ]
       }
     }
@@ -41,9 +66,44 @@
     "daywalker90 is mainly responsible."
   ],
   "see_also": [
-    "lightning-listcurrencyrates(7)"
+    "lightning-listcurrencyrates(7)",
+    "lightning-currencyconvert(7)",
+    "lightningd-config(5)"
   ],
   "resources": [
     "Main web site: [https://github.com/ElementsProject/lightning](https://github.com/ElementsProject/lightning)"
+  ],
+  "examples": [
+    {
+      "description": [
+        "Get the median BTC/USD rate across all configured sources:"
+      ],
+      "request": {
+        "id": "example:currencyrate#1",
+        "method": "currencyrate",
+        "params": {
+          "currency": "USD"
+        }
+      },
+      "response": {
+        "rate": 67889.825
+      }
+    },
+    {
+      "description": [
+        "Get the BTC/USD rate from the Binance source only:"
+      ],
+      "request": {
+        "id": "example:currencyrate#2",
+        "method": "currencyrate",
+        "params": {
+          "currency": "USD",
+          "source": "binance"
+        }
+      },
+      "response": {
+        "rate": 67931.9
+      }
+    }
   ]
 }

plugins/currencyrate-plugin/README.md

@@ -0,0 +1,74 @@
+# cln-currencyrate plugin
+
+A Core Lightning plugin that provides Bitcoin currency conversion using multiple price sources. It queries all configured sources in parallel, caches results for one hour, and returns the median rate for conversions.
+
+## Options
+
+These options can be set in your `lightning.conf` config file or passed directly when starting the plugin.
+
+### `currencyrate-add-source=NAME,URL,MEMBERS`
+
+Add a custom price source. The format is `NAME,URL,MEMBERS` where:
+
+- `NAME` — a unique identifier for the source
+- `URL` — the API endpoint; use `{currency}` and `{currency_lc}` as placeholders for the plain currency (i.e. dollar, euro, etc.) and currency code respectively
+- `MEMBERS` — comma-separated keys to traverse the JSON response to reach the price value; use `{currency}` and `{currency_lc}` as placeholders where needed
+
+For example, if the API response is `{"rates": {"usd": 95000.0}}`, the `lightning.conf` entry would be:
+
+```
+currencyrate-add-source=currencyrateapi,https://currencyrateapi.com/api/latest?base=BTC&codes={currency_lc},rates,{currency_lc}
+```
+
+Can be specified multiple times to add multiple sources.
+
+### `currencyrate-disable-source=NAME`
+
+Disable a source by name (including default ones). Can be specified multiple times.
+
+For example, to disable bitstamp:
+
+```
+currencyrate-disable-source=bitstamp
+```
+
+## Default Sources
+
+| Source | Notes |
+|---|---|
+| coingecko | "The world's most comprehensive cryptocurrency API" |
+| kraken | |
+| blockchain.info | "The World's Most Popular Way to Buy, Hold, and Use Crypto" |
+| bitstamp | "The original global crypto exchange." — disabled when a Tor proxy is configured |
+| coindesk | "Powered by CoinDesk: https://www.coindesk.com/price/bitcoin" |
+| coinbase | "The easiest place to buy, sell, and manage your cryptocurrency portfolio." |
+
+## Configuring Sources Without Restarting the Node
+
+Because the plugin is dynamic, you can stop and restart it with updated options without restarting `lightningd`. This lets you add or disable sources on the fly.
+
+> **Warning:** while the plugin is stopped, any events that require a currency rate (e.g. invoice creation with a fiat amount) will fail or return missing data.
+
+**1. Stop the plugin:**
+
+```bash
+lightning-cli plugin stop cln-currencyrate
+```
+
+**2.a Restart it with a new source:**
+
+```bash
+lightning-cli plugin -k subcommand=start \
+  plugin=/path/to/cln-currencyrate \
+  currencyrate-add-source="currencyrateapi,https://currencyrateapi.com/api/latest?base=BTC&codes={currency_lc},rates,{currency_lc}"
+```
+
+**2.b Restart it with a source disabled:**
+
+```bash
+lightning-cli plugin -k subcommand=start \
+  plugin=/path/to/cln-currencyrate \
+  currencyrate-disable-source="bitstamp"
+```
+
+For persistent configuration, add the options to your `lightning.conf` instead.