{"id":13622902,"url":"https://github.com/interledgerjs/moneyd","last_synced_at":"2025-07-27T14:41:48.582Z","repository":{"id":45675416,"uuid":"118285855","full_name":"interledgerjs/moneyd","owner":"interledgerjs","description":"Connect your machine to the Interledger","archived":false,"fork":false,"pushed_at":"2023-12-15T08:21:27.000Z","size":622,"stargazers_count":112,"open_issues_count":55,"forks_count":51,"subscribers_count":21,"default_branch":"master","last_synced_at":"2025-04-09T16:04:35.808Z","etag":null,"topics":["connector","ilp","interledger","local","payment","payment-channel","xrp"],"latest_commit_sha":null,"homepage":"","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":"CODE_OF_CONDUCT.md","threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2018-01-20T22:27:52.000Z","updated_at":"2024-11-30T15:27:59.000Z","dependencies_parsed_at":"2024-06-12T07:22:53.536Z","dependency_job_id":"de8b29f0-b711-411f-aa39-bb79950253f8","html_url":"https://github.com/interledgerjs/moneyd","commit_stats":{"total_commits":123,"total_committers":17,"mean_commits":7.235294117647059,"dds":0.6016260162601625,"last_synced_commit":"6b221946b4b9d425752fc3bb790cf835bcf532e6"},"previous_names":[],"tags_count":37,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Fmoneyd","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Fmoneyd/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Fmoneyd/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/interledgerjs%2Fmoneyd/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/interledgerjs","download_url":"https://codeload.github.com/interledgerjs/moneyd/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":248065290,"owners_count":21041871,"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":["connector","ilp","interledger","local","payment","payment-channel","xrp"],"created_at":"2024-08-01T21:01:25.549Z","updated_at":"2025-04-09T16:04:42.385Z","avatar_url":"https://github.com/interledgerjs.png","language":"JavaScript","funding_links":[],"categories":["JavaScript"],"sub_categories":[],"readme":"# Moneyd\n\n[![Greenkeeper badge](https://badges.greenkeeper.io/interledgerjs/moneyd.svg)](https://greenkeeper.io/)\n\n\u003e ILP-enable your machine!\n\n- [Interledger Networks](#interledger-networks)\n- [Quickstart](#quick-start)\n  - [Test Network](#test-network)\n  - [Community Network](#community-network)\n  - [Local Test Network](#local-test-network)\n  - [Cloud Test Network](#cloud-test-network)\n- [Description](#description)\n- [Uplinks](#uplinks)\n- [Writing ILP Applications](#writing-ilp-applications)\n  - [How Does \"ilp-plugin\" Work?](#how-does-ilp-plugin-work)\n- [Advanced Usage](#advanced-usage)\n  - [Command-Line Options](#command-line-options)\n  - [Environment Variables](#environment-variables)\n  - [Remote Deploy](#remote-deploy)\n  - [Reconciliation](#reconciliation)\n  - [Account Info](#account-info)\n  - [Clean Up Channels](#clean-up-channels)\n  - [Multiple Instances](#multiple-instances)\n- [Sending Payments](#sending-payments)\n- [Connector List](#connector-list)\n\n## Interledger Networks\n\nWhen moneyd was created, what we referred to as the _Interledger livenet_ was a community-run network for research and development\npurposes. Today there is a well-established Interledger network based around wallet providers such as\n[Gatehub](https://gatehub.net), [XRPTipBot](https://xrptipbot.com), and [Stronghold](https://stronghold.co/) which we call the Interledger livenet.\n\nToday's Interledger livenet makes it easy for anyone to get a payment pointer to receive Interledger payments, and\nhas handled billions of micropayments. However, the wallets which now make up the livenet have not yet exposed\nmoneyd-like direct Interledger access.\n\nAs a result, moneyd will only connect to a community network of connectors, not the Interledger livenet. The community network uses real money, but is not connected to Interledger-enabled wallets and businesses so we're not currently recommending it for production use-cases. However, Moneyd is still a useful tool for experimenting with Interledger for education and experimentation.\n\n## Quick Start\n\nIf you haven't already, read the [Interledger Networks](#interledger-networks)\nsection above. **Moneyd does not currently connect to the Interledger livenet.**\n\nIf you already have an XRP account with 35 XRP or more, use the [community network](#community-network) instructions.\nOtherwise, you can still follow the [Testnet](#test-network) instructions. For development in an offline\nenvironment, you can run your own [Local Testnet](#local-test-network).\n\n### Test Network\n\nYou'll need:\n\n- Node v8.9.4 or higher.\n- Permissions to install global node modules.\n\n```sh\nnpm install -g moneyd moneyd-uplink-xrp\nmoneyd --testnet xrp:configure\nmoneyd --testnet xrp:start\n```\n\nGive it a minute to initialize a channel, then you're done! A configuration\nfile will be created in `~/.moneyd.test.json`.\n\nSo long as that command is running, you'll have access to ILP via port 7768.\nTo try it out, follow the [Sending Payments](#sending-payments) section, and\nuse the alternate endpoints listed for the testnet.\n\n### Community Network\n\nYou'll need:\n\n- Node v8.9.4 or higher.\n- Permissions to install global node modules.\n- An XRP secret (with more than 35 XRP to cover reserve and channel funding).\n\nJust run:\n\n```sh\nnpm install -g moneyd moneyd-uplink-xrp\nmoneyd xrp:configure\nmoneyd xrp:start\n```\n\nYour XRP secret (or \"seed\") is the base58-encoded string that starts with an 's'.\n\nGive it a minute to initialize a channel, then you're done! A configuration\nfile will be created in `~/.moneyd.json`.\n\n\nSo long as that command is running, you'll have access to ILP's community\nnetwork via port 7768.  For some commands you can do, look at [Sending\nPayments](#sending-payments).  For more advanced usage of the moneyd command,\nlook at [Advanced Usage](#advanced-usage).\n\n### Local Test Network\n\nIf you're just doing local development, you may not care about being connected\nto any network.  Moneyd allows you to run an isolated local test network for\nthis scenario. Run:\n\n```\nnpm install -g moneyd\nmoneyd local\n```\n\nThis exposes ILP access via port 7768, but any application connected to this\nport will only be able to pay other applications on the same machine.\n\n### Cloud Test Network\n\nA publically accessible test network can be created by deploying moneyd to Heroku. Use the button below to deploy\nan instance of moneyd running in local mode. Prior to completing the app deployment, Heroku will ask for two required fields: Setting the asset code (i.e, XRP, USD) and setting the asset scale.\n\n[![Deploy](https://www.herokucdn.com/deploy/button.svg)](https://heroku.com/deploy)\n\nOnce deployed, Heroku will provide you with a url to connect to your cloud moneyd which has the form heroku-app-name.herokuapp.com\n\nA local moneyd instance can then be set up to connect to the Heroku instance using the following commands:\n\n```sh\nmoneyd --testnet btp:configure\n```\n\nFollow the command-line prompts to configure the connection. When prompted for the `BTP host of parent connector`, enter the url provided by Heroku (heroku-app-name.herokuapp.com without the https://).\nOnce the uplink has been configured, run the local moneyd instance\n\n```sh\nmoneyd --testnet btp:start\n```\n\n## Description\n\nThis repo contains an experimental ILP provider, allowing all applications on\nyour computer to use funds on a community ILP network.\n\nIt works by creating a payment channel to an Interledger connector, and then\nrunning `ilp-plugin-mini-accounts` locally. Any plugin can connect to this\nmini-accounts instance by generating a random secret and authenticating via BTP\nto `localhost:7768`. By default, only connections from localhost are accepted.\n(See [Environment Variables](#environment-variables).)\n\nThe `ilp-plugin` repo is already designed to do this, so `ilp-curl` and many\nother tools will work right out of the box.\n\nBecause it's in early stages, don't use it\nwith a ripple account that has too much money.\n\n## Uplinks\n\nAn uplink module wraps ILP plugins for Moneyd's use. They provide additional features such as payment channel management and configuration construction. At least one uplink must be installed to use Moneyd.\n\nExample uplink modules:\n\n  * [moneyd-uplink-xrp](https://github.com/interledgerjs/moneyd-uplink-xrp)\n  * (more to come)\n\n### moneyd-uplink-btp\nThis uplink comes packaged with moneyd by default. It is used to create a data only link (no settlement) to a parent connector instance that accepts connections using `ilp-plugin-mini-accounts` (such as another moneyd). The following commands are used to configure and run moneyd using the moneyd-uplink-btp:\n\n```sh\nmoneyd btp:configure\nmoneyd btp:start\n```\n\n(See [Cloud Test Network](#cloud-test-network) for example.)\n\n## Writing ILP Applications\n\nOne of the biggest reasons to run moneyd is that it lets you develop your own\napplications that run on top of Interledger. Connecting to Moneyd is as easy as\ninstalling [`ilp-plugin`](https://www.npmjs.com/package/ilp-plugin) and adding\na single line of code to your project:\n\n```\nconst plugin = require('ilp-plugin')()\n```\n\nThis Interledger\n[Plugin](https://github.com/interledger/rfcs/blob/master/0024-ledger-plugin-interface-2/0024-ledger-plugin-interface-2.md)\nis a connection to your Moneyd instance. You can then pass it into other\nmodules to send payments through your Moneyd.\n\n### How Does \"ilp-plugin\" Work?\n\n`ilp-plugin` has very simple default behavior. If you run\n`require('ilp-plugin')()`, it creates an instance of [ILP Plugin\nBTP](https://github.com/interledgerjs/ilp-plugin-btp) that connects to port\n7768 on your local machine.\n\nYou can also customize the behavior of `ilp-plugin` using [environment\nvariables](https://en.wikipedia.org/wiki/Environment_variable#Unix).\n\n- `ILP_CREDENTIALS` - A JSON object that contains the parameters to be passed into your plugin's constructor. Default: `'{\"server\":\"btp+ws://:\u003cRANDOM_SECRET\u003e@localhost:7768\"}'`.\n- `ILP_PLUGIN` - An NPM module name for the plugin you want to use. Default: `'ilp-plugin-btp'`.\n\n## Advanced Usage\n\n### Command-Line Options\n\nFor any of the commands below, you can use a config file in a non-standard\nlocation with `-c`. If you have configured your moneyd instance with\n`--testnet`, then you should also add the `--testnet` flag to any commands\nspecified in this section.\n\nTo view a complete list of the moneyd flags, run:\n\n```\nmoneyd help\n```\n\nIf you want to see the options for a specific command, pass `--help`. For example:\n\n```\nmoneyd xrp:configure --help\n```\n\n### Environment Variables\n\nYou can customize the behavior of `moneyd` using [environment\nvariables](https://en.wikipedia.org/wiki/Environment_variable#Unix).\n\n- `MONEYD_BIND_IP` - A string specifying the IP address on which the moneyd websocket server listens. Default: `localhost`.\n- `MONEYD_BIND_PORT` - A string specifying the PORT on which the moneyd websocket server listens. Default: `7768`.\n- `MONEYD_ASSET_CODE` - A string specifying the ASSET CODE that moneyd is configured with when running in LOCAL mode. Default: `XRP`.\n- `MONEYD_ASSET_SCALE` - A number specifying the ASSET SCALE that moneyd is configured with when running in LOCAL mode. Default: `9`.\n- `MONEYD_ILP_ADDRESS` - A string specifying the ilp address that moneyd is configured with when running in LOCAL mode. Default: `private.moneyd`.\n- `SET_ASSET_CODE` - A string specifying which Moneyd asset code to use\n- `SET_ASSET_SCALE` - A number specifying the Moneyd asset scale to be configured with\n### Remote Deploy\n\nIf you did the previous step on your remote server, then you don't need to run any\nspecial software to get moneyd on your local machine. Not only that, but you can\ngrant access to Interledger to as many machines as you want!\n\nJust forward the moneyd port `7768` to any machine where you want ILP access by\nusing SSH local port forwarding:\n\n```sh\nssh -N -L 7768:localhost:7768 user@example.com\n```\n\nReplace the `user@example.com` with the server on which you're running moneyd.\n\n### Reconciliation\n\nIf you crash or encounter a bug, you might find that your moneyd instance forgot\nto send a claim to its parent connector. This results in the parent connector thinking\nyou owe it money, and refusing to forward any of your packets.\n\nTo fix this, just stop moneyd and run:\n\n```\nmoneyd xrp:topup --amount 1000\n```\n\nYou can adjust the amount if you need to reconcile more. The amount is\nrepresented in XRP drops; 1000000 is a single XRP so these amounts are\ntypically kept quite small.\n\n### Account Info\n\nYou can get information about your XRP account's balance and outstanding\npayment channels. To access this information, run:\n\n```\nmoneyd xrp:info\n```\n\n### Clean Up Channels\n\nSometimes you want to get your money back out of a payment channel. Moneyd\nprovides a tool to do this.\n\nClosing a channel happens in two phases. First you mark the channel for closing.\nThis sets an expiry on the channel. Next, once the expiry has passed, you can send another\nclose transaction to get your funds back and delete the channel.\n\nTo mark channels for closing, run:\n\n```\nmoneyd xrp:cleanup\n```\n\nSelect the channels you'd like to close with `\u003cspace\u003e` and then hit `\u003center\u003e`.\nIf you run `moneyd xrp:info` you'll see that the channels now have expiries set.\n\nExpect it to take an hour for the channel to be ready for closing; this gives\nthe counterparty a chance to submit their best claim.\n\nOnce the hour is up, run cleanup again:\n\n```\nmoneyd xrp:cleanup\n```\n\nThis time, the channels should say `ready to close`. Mark them for closing, and\nthis time they'll go away for good. Your XRP account will be credited the total channel\ncapacity minus the current channel balance.\n\nIf you start moneyd and its previous channel is closing or closed, you need to\nset a new `name` to force a new channel to be opened. Follow the instructions\non [Multiple Instances](#multiple-instances) to accomplish this.\n\n## Multiple Instances\n\nSometimes you want to run several instances of moneyd with for the same XRP\naccount and parent connector.\n\nIn order to distinguish your instances of moneyd, set a unique `\"name\"` when you\nconfigure your uplink. This `\"name\"` will be a segment of your ILP address, so\nit must only use `[A-Za-z0-9\\-_~]`. The `\"name\"` must be unique per parent BTP\nhost.\n\nYou'll have to configure in advanced mode to prompt for the name. Don't forget\nto back up your old `~/.moneyd.json` first. Then run configure for the currency\nyou're using. For example, with XRP, run:\n\n```\nmoneyd xrp:configure --advanced\n```\n\nAnd then when you're prompted for `\"name\"`, put in the unique name that you want.\nThis will force a fresh channel to be opened.\n\nYou can use as many different `\"name\"`s as you want. If you run out of XRP from\nopening up channels, just follow [Clean Up Channels](#clean-up-channels) to\nreclaim it.\n\n## Sending Payments\n\nNow that you have moneyd running, you can test it out by uploading a file to unhash.\nUnhash is a simple content-addressed file upload service based on ILP.\n\nYou'll use [ILP Curl](https://github.com/interledgerjs/ilp-curl), which will connect\nto moneyd and send money to the unhash host.\n\n```sh\nnpm install -g ilp-curl\necho \"This is my example file\" \u003e example.txt\n\n# use \"https://unhash.ilp-test.com\" if you're on the testnet\"\nilp-curl -X POST https://alpha.unhash.io --data @example.txt\n# --\u003e {\"digest\":\"ff5574cef56e644f3fc4d0311b15a3e95f115080bcc029889f9e32121fd60407\"}\n\ncurl https://alpha.unhash.io/ff5574cef56e644f3fc4d0311b15a3e95f115080bcc029889f9e32121fd60407\n# --\u003e \"This is my example file\"\n```\n\nNow you've successfully sent an ILP payment to pay for a file upload!  Another\nway to use ILP is with SPSP, the simple payment setup protocol. This next\nexample will send a micropayment to `$sharafian.com`.\n\n```sh\nnpm install -g ilp-spsp\n\n# use \"$spsp.ilp-test.com\" if you're on the testnet\nilp-spsp send --receiver \\$sharafian.com --amount 100\n\n# --\u003e paying 100 to \"$sharafian.com\"...\n# --\u003e sent!\n```\n\nYou can browse [Interledgerjs on Github](https://github.com/interledgerjs) to\nfind more use cases.\n\n## Connector List\n\n(Submit a PR to add your own connector here)\n\n- `client.scyl.la` - N. Virginia\n- `ilsp.openafricanetwork.org` - W. Europe (waiting for AWS to host instances in Africa...)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterledgerjs%2Fmoneyd","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Finterledgerjs%2Fmoneyd","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Finterledgerjs%2Fmoneyd/lists"}