{"id":13499296,"url":"https://github.com/ElementsProject/lightning-charge","last_synced_at":"2025-03-29T04:30:59.496Z","repository":{"id":47165678,"uuid":"110874262","full_name":"ElementsProject/lightning-charge","owner":"ElementsProject","description":"A simple drop-in solution for accepting lightning payments","archived":false,"fork":false,"pushed_at":"2023-10-28T04:09:44.000Z","size":1206,"stargazers_count":556,"open_issues_count":16,"forks_count":81,"subscribers_count":30,"default_branch":"master","last_synced_at":"2025-03-24T02:12:19.134Z","etag":null,"topics":["bitcoin","lightning","lightning-charge","lightning-payments","micropayments"],"latest_commit_sha":null,"homepage":null,"language":"JavaScript","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/ElementsProject.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":"LICENSE","code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null}},"created_at":"2017-11-15T19:02:33.000Z","updated_at":"2025-02-11T15:49:53.000Z","dependencies_parsed_at":"2022-09-03T21:01:02.511Z","dependency_job_id":"15672c39-5d13-4cb3-a46b-ea04c363b767","html_url":"https://github.com/ElementsProject/lightning-charge","commit_stats":{"total_commits":387,"total_committers":6,"mean_commits":64.5,"dds":"0.023255813953488413","last_synced_commit":"c54f065c527eeb8f8cc0ab0f6efa8450b1e8edd5"},"previous_names":[],"tags_count":54,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning-charge","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning-charge/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning-charge/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/ElementsProject%2Flightning-charge/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/ElementsProject","download_url":"https://codeload.github.com/ElementsProject/lightning-charge/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":246140565,"owners_count":20729797,"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":["bitcoin","lightning","lightning-charge","lightning-payments","micropayments"],"created_at":"2024-07-31T22:00:31.972Z","updated_at":"2025-03-29T04:30:58.923Z","avatar_url":"https://github.com/ElementsProject.png","language":"JavaScript","readme":"# Lightning Charge\n\n[![build status](https://api.travis-ci.org/ElementsProject/lightning-charge.svg)](https://travis-ci.org/ElementsProject/lightning-charge)\n[![npm release](https://img.shields.io/npm/v/lightning-charge.svg)](https://www.npmjs.com/package/lightning-charge)\n[![docker release](https://img.shields.io/docker/pulls/shesek/lightning-charge.svg)](https://hub.docker.com/r/shesek/lightning-charge/)\n[![MIT license](https://img.shields.io/github/license/elementsproject/lightning-charge.svg)](https://github.com/ElementsProject/lightning-charge/blob/master/LICENSE)\n[![Pull Requests Welcome](https://img.shields.io/badge/PRs-welcome-brightgreen.svg)](http://makeapullrequest.com)\n[![IRC](https://img.shields.io/badge/chat-on%20freenode-brightgreen.svg)](https://webchat.freenode.net/?channels=lightning-charge)\n\n\nA drop-in solution for accepting lightning payments, built on top of [c-lightning](https://github.com/ElementsProject/lightning).\n\n- Simple HTTP REST API, optimized for developer friendliness and ease of integration. Near-zero configuration.\n\n- Supports invoice metadata, fiat currency conversion, long polling, web hooks, websockets and server-sent-events.\n\n- Built-in checkout page, can be iframed or redirected to.\n\n:zap: radically low fees :zap: nano payments :zap: instant confirmations :zap:\n\n## Getting Started\n\nSetup [c-lightning](https://github.com/ElementsProject/lightning#getting-started) and nodejs (v7.6 or newer), then:\n\n```bash\n$ npm install -g lightning-charge\n\n$ charged --api-token mySecretToken # defaults: --ln-path ~/.lightning/testnet --db-path ./charge.db --port 9112\n\n```\n\n\u003e Note: if you're running into permission issues, try following\n[these instructions](https://docs.npmjs.com/getting-started/fixing-npm-permissions#option-two-change-npms-default-directory).\n\nThat's it! The Lightning Charge REST API is now running and ready to process payments.\nYou can access it at `http://localhost:9112` using the API access token configured with `--api-token`.\n\nConfiguration options may alternatively be provided using environment variables:\n\n```bash\n$ LN_PATH=~/.lightning/testnet DB_PATH=charge.db API_TOKEN=mySecretToken PORT=9112 charged\n```\n\nListens for connections on `127.0.0.1` by default. Set `-i 0.0.0.0` to bind on all available interfaces.\nNote that Charge does not have TLS encryption and should not normally be exposed directly to the public\ninternet. For remote access, you should setup an SSH tunnel or a TLS-enabled reverse proxy like nginx.\n\nSee `$ charged --help` for the full list of available options.\n\n### Deploy with Docker\n\nTo deploy Lightning Charge with Docker, run these commands:\n\n```bash\n$ mkdir data # make sure to create the folder _before_ running docker\n$ docker run -it -u `id -u` -v `pwd`/data:/data -p 9735:9735 -p 9112:9112 \\\n             shesek/lightning-charge --api-token mySecretToken\n```\n\nThis will start `bitcoind`, `lightningd` and `charged` and hook them up together.\nYou will then be able to access the REST API at `http://localhost:9112` using `mySecretToken`.\n\nRuns in `testnet` mode by default, set `NETWORK` to override.\n\nIf you want to experiment in `regtest` mode and don't care about persisting data, this should do:\n\n```bash\n$ docker run -it -e NETWORK=regtest -p 9112:9112 shesek/lightning-charge --api-token mySecretToken\n```\n\nTo connect to an existing `lightningd` instance running on the same machine,\nmount the lightning data directory to `/etc/lightning` (e.g. `-v $HOME/.lightning:/etc/lightning`).\nConnecting to remote lightningd instances is currently not supported.\n\nTo connect to an existing `bitcoind` instance running on the same machine,\nmount the bitcoin data directory to `/etc/bitcoin` (e.g. `-v $HOME/.bitcoin:/etc/bitcoin`).\nTo connect to a remote bitcoind instance, set `BITCOIND_URI=http://[user]:[pass]@[host]:[port]`\n(or use `__cookie__:...` as the login for cookie-based authentication).\n\n### Deploy to Azure\n\n[One-click deployment on Azure](https://github.com/NicolasDorier/lightning-charge-azure)\n(by [@NicolasDorier](https://github.com/NicolasDorier)).\n\nAn instructional video is [available here](https://www.youtube.com/watch?v=D4RqULSA4uU).\n\n## Client libraries\n\nClients libraries are available for [JavaScript](https://github.com/ElementsProject/lightning-charge-client-js)\nand [PHP](https://github.com/ElementsProject/lightning-charge-client-php).\nFor other languages, you can use the REST API directly using a standard HTTP library.\n\n## LApps\n\nBelow are example LApps built on top of Lightning Charge:\n\n- [FileBazaar](https://github.com/ElementsProject/filebazaar): an ecommerce tool for content creators that produce digital files like photos, videos, or music.\n\n- [Lightning Publisher](https://github.com/ElementsProject/wordpress-lightning-publisher): accept bitcoin payments for content on WordPress blogs.\n\n- [nanotip](https://github.com/ElementsProject/nanotip): a simple web server for accepting lightning donations (a lightning tip jar).\n\n- [paypercall](https://github.com/ElementsProject/paypercall): easily charge for HTTP APIs on a pay-per-call basis.\n\n- [nanopos](https://github.com/ElementsProject/nanopos): a simple point-of-sale system for physical stores.\n\n- [ifpaytt](https://github.com/ElementsProject/ifpaytt): trigger IFTTT actions with lightning payments.\n\n- [WooCommerce Lightning](https://github.com/ElementsProject/woocommerce-gateway-lightning): a lightning gateway for the WooCommerce e-commerce software.\n\n- [Lightning Jukebox](https://github.com/ElementsProject/lightning-jukebox): a lightning powered jukebox. Pay with Bitcoin to choose your music.\n\nThird party Lapps:\n\n- [Satoshi's Place](https://github.com/LightningK0ala/satoshis.place): a collaborative art board, pay with lightning to draw on a pixel grid. (live on [satoshis.place](https://satoshis.place/))\n\n- [Pollo feed](https://github.com/j-chimienti/pollofeed): a lightning powered chicken feeder. (live on [pollofeed.com](https://pollofeed.com/))\n\n- [lightning-captive-portal](https://github.com/poperbu/lightning-captive-portal/): Wi-Fi access through a nodogsplash captive portal with Lightning payments.\n\n## REST API\n\nAll endpoints accept and return data in JSON format.\n\nAuthentication is done using HTTP basic authentication headers, with `api-token` as the username and\nthe api token (configured with `--api-token`/`-t` or using the `API_TOKEN` environment variable) as the password.\n\nInvoices have the following properties: `id`, `msatoshi`, `msatoshi_received`, `quoted_currency`, `quoted_amount`, `rhash`, `payreq`, `description`, `created_at`, `expires_at`, `paid_at`, `metadata` and `status` (one of `unpaid|paid|expired`).\n\nThe code samples below assume you've set `CHARGE=http://api-token:mySecretToken@localhost:9112`.\n\n### `GET /info`\n\nGet information about the c-lightning node.\n\n```bash\n$ curl $CHARGE/info\n{\"id\":\"032c6ba19a2141c5fee6ac8b6ff6cf24456fd4e8e206716a39af3300876c3a4835\",\"port\":42259,\"address\":[],\"version\":\"v0.5.2-2016-11-21-1937-ge97ee3d\",\"blockheight\":434,\"network\":\"regtest\"}\n```\n\n### `POST /invoice`\n\nCreate a new invoice.\n\n*Body parameters*: `msatoshi`, `currency`, `amount`, `description`, `expiry`, `metadata` and `webhook`.\n\nYou can specify the amount as `msatoshi` (1 satoshi = 1000 msatoshis),\nor provide a `currency` and `amount` to be converted according to the current exchange rates (via bitcoinaverage).\nIf a currency and amount were provided, they'll be available under `quoted_{currency|amount}`.\n\n`expiry` sets the invoice expiry time in seconds (defaults to one hour).\n`metadata` may contain arbitrary invoice-related meta-data.\n`description` is embedded in the payment request and presented by the user's wallet (keep it short).\n\n`webhook` may contain a URL to be registered as a webhook\n(see [`POST /invoice/:id/webhook`](https://github.com/ElementsProject/lightning-charge#post-invoiceidwebhook)).\n\nReturns `201 Created` and the invoice on success.\n\n```bash\n$ curl -X POST $CHARGE/invoice -d msatoshi=10000\n{\"id\":\"KcoQHfHJSx3fVhp3b1Y3h\",\"msatoshi\":\"10000\",\"status\":\"unpaid\",\"rhash\":\"6823e46a08f50...\",\n \"payreq\":\"lntb100n1pd99d02pp...\",\"created_at\":1515369962,\"expires_at\":1515373562}\n\n# with fiat-denominated amounts\n$ curl -X POST $CHARGE/invoice -d currency=EUR -d amount=0.5\n{\"id\":\"OYwwaOQAPMFvg039gj_Rb\",\"msatoshi\":\"3738106\",\"quoted_currency\":\"EUR\",\"quoted_amount\":\"0.5\",...}\n\n# without amount (accept all payments)\n$ curl -X POST $CHARGE/invoice\n{\"id\":\"W8CF0UqY7qfAHCfnchqk9\",\"msatoshi\":null,...}\n\n# with metadata as application/json\n$ curl -X POST $CHARGE/invoice -H 'Content-Type: application/json' \\\n  -d '{\"msatoshi\":7000,\"metadata\":{\"customer_id\":9817,\"products\":[593,182]}}'\n{\"id\":\"PLKV1f8B7sth7w2OeDOt_\",\"msatoshi\":\"7000\",\"metadata\":{\"customer_id\":9817,\"products\":[593,182]},...}\n\n# with metadata as application/x-www-form-urlencoded\n$ curl -X POST $CHARGE/invoice -d msatoshi=5000 -d metadata[customer_id]=9817 -d metadata[product_id]=7189\n{\"id\":\"58H9eoerBpKML9FvnMQtG\",\"msatoshi\":\"5000\",\"metadata\":{\"customer_id\":\"9817\",\"product_id\":\"7189\"},...}\n```\n\n### `GET /invoices`\n\nList all invoices.\n\n```bash\n$ curl $CHARGE/invoices\n[{\"id\":\"KcoQHfHJSx3fVhp3b1Y3h\",\"msatoshi\":\"10000\",...},{\"id\":\"PLKV1f8B7sth7w2OeDOt_\",\"msatoshi\":\"7000\"},...]\n```\n\n### `GET /invoice/:id`\n\nGet the specified invoice.\n\n```bash\n$ curl $CHARGE/invoice/OYwwaOQAPMFvg039gj_Rb\n{\"id\":\"OYwwaOQAPMFvg039gj_Rb\",\"msatoshi\":\"3738106\",\"quoted_currency\":\"EUR\",\"quoted_amount\":\"0.5\",\"status\":\"unpaid\",...}\n```\n\n### `DELETE /invoice/:id`\n\nDelete the specified invoice.\n\n*Body parameters:* `status`\n\nThe current status of the invoice needs to be specified in the request body.\n\n```bash\n$ curl -X DELETE $CHARGE/invoice/OYwwaOQAPMFvg039gj_Rb -d status=unpaid\n204 No Content\n```\n\n### `GET /invoice/:id/wait?timeout=[sec]`\n\nLong-polling invoice payment notification.\n\nWaits for the invoice to be paid, then returns `200 OK` and the updated invoice.\n\nIf `timeout` (defaults to 30s) is reached before the invoice is paid, returns `402 Payment Required`.\n\nIf the invoice is expired and can no longer be paid, returns `410 Gone`.\n\n```bash\n$ curl $CHARGE/invoice/OYwwaOQAPMFvg039gj_Rb/wait?timeout=60\n# zZZZzzZ\n{\"id\":\"OYwwaOQAPMFvg039gj_Rb\",\"msatoshi\":\"3738106\",\"status\":\"paid\",\"paid_at\":1515371152,...}\n```\n\n### `POST /invoice/:id/webhook`\n\nRegister a URL as a web hook to be notified once the invoice is paid.\n\n*Body parameters:* `url`.\n\nReturns `201 Created` on success. Once the payment is made, a POST request with the updated invoice will be made to the provided URL.\n\nIf the invoice is already paid, returns `405 Method Not Allowed`. If the invoice is expired, returns `410 Gone`.\n\nWebhooks can also be registered during invoice creation using the `webhook` parameter.\n\nFor security reasons, the provided `url` should contain a secret token used to verify the authenticity of the request\n(see an example HMAC-based implementation at woocommerce-gateway-lightning\n[here](https://github.com/ElementsProject/woocommerce-gateway-lightning/blob/84592d7bcfc41db129b02d1927a6060a05c5c11e/woocommerce-gateway-lightning.php#L214-L225),\n[here](https://github.com/ElementsProject/woocommerce-gateway-lightning/blob/84592d7bcfc41db129b02d1927a6060a05c5c11e/woocommerce-gateway-lightning.php#L131-L134)\nand [here](https://github.com/ElementsProject/woocommerce-gateway-lightning/blob/84592d7bcfc41db129b02d1927a6060a05c5c11e/woocommerce-gateway-lightning.php#L109-L115)).\n\n```bash\n$ curl -X POST $CHARGE/invoice/OYwwaOQAPMFvg039gj_Rb/webhook -d url=http://example.com/callback\nCreated\n```\n\n### `GET /payment-stream`\n\nSubscribe to payment updates as a [server-sent events](https://streamdata.io/blog/server-sent-events/) stream.\n\n```bash\n$ curl $CHARGE/payment-stream\n# zzZZzZZ\ndata:{\"id\":\"OYwwaOQAPMFvg039gj_Rb\",\"msatoshi\":\"3738106\",\"status\":\"paid\",\"paid_at\":1515371152,...}\n# zZZzzZz\ndata:{\"id\":\"KcoQHfHJSx3fVhp3b1Y3h\",\"msatoshi\":\"10000\",\"status\":\"paid\",\"paid_at\":1515681209,...}\n# zZZzzzz...\n```\n\nOr via JavaScript:\n\n```js\nconst es = new EventSource('http://api-token:[TOKEN]@localhost:9112/payment-stream')\n\nes.addEventListener('message', msg =\u003e {\n  const inv = JSON.parse(msg.data)\n  console.log('Paid invoice:', inv)\n})\n```\n\n(`EventSource` is natively available in modern browsers,\nor via the [`eventsource` library](https://github.com/EventSource/eventsource) in nodejs)\n\n## WebSocket API\n\n### `GET /ws`\n\nSubscribe to payment updates over WebSocket.\n\n```javascript\nconst ws = new WebSocket('http://api-token:[TOKEN]@localhost:9112/ws')\n\nws.addEventListener('message', msg =\u003e {\n  const inv = JSON.parse(msg.data)\n  console.log('Paid invoice:', inv)\n})\n```\n\n## Tests\n\nRequires `bitcoind`, `bitcoin-cli`, `lightningd`, `lightning-cli`\nand [`jq`](https://stedolan.github.io/jq/download/) to be in your `PATH`.\n\n```bash\n$ git clone https://github.com/ElementsProject/lightning-charge.git\n$ cd lightning-charge\n$ npm install\n$ npm test\n```\n\nThis will setup a temporary testing environment with a bitcoind regtest node\nand two c-lightning nodes with a funded channel,\nthen start the Lightning Charge server and run the unit tests\n(written with [mocha](https://mochajs.org/) and [supertest](https://github.com/visionmedia/supertest)).\n\nTo run in verbose mode, set the `VERBOSE` environment variable: `$ VERBOSE=1 npm test`.\n\nTo pass arguments to mocha, use `$ npm test -- [mocha opts]`.\n\nTo prevent the test environment files from being deleted after completing the tests, set `KEEP_TMPDIR=1`.\n\nTo setup a testing environment without running the tests, run `$ npm run testenv`.\nThis will display information about the running services and keep them alive for further inspection.\n\nTests can also be run using docker: `$ docker build --build-arg TESTRUNNER=1 -t charge . \u0026\u0026 docker run -it --entrypoint npm charge test`\n\n## License\n\nMIT\n","funding_links":[],"categories":["Developer Resources"],"sub_categories":["Libraries"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElementsProject%2Flightning-charge","html_url":"https://awesome.ecosyste.ms/projects/github.com%2FElementsProject%2Flightning-charge","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2FElementsProject%2Flightning-charge/lists"}