{"id":15199945,"url":"https://github.com/fusion44/blitz_api","last_synced_at":"2025-10-28T14:30:54.713Z","repository":{"id":37014831,"uuid":"375806359","full_name":"fusion44/blitz_api","owner":"fusion44","description":"A management backend for the RaspiBlitz project written in Python / FastAPI","archived":false,"fork":false,"pushed_at":"2024-05-18T21:47:13.000Z","size":2388,"stargazers_count":17,"open_issues_count":64,"forks_count":18,"subscribers_count":4,"default_branch":"dev","last_synced_at":"2024-05-19T14:51:59.535Z","etag":null,"topics":["bitcoin","fastapi","lightning-network","python","raspiblitz"],"latest_commit_sha":null,"homepage":"","language":"Python","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/fusion44.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,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null}},"created_at":"2021-06-10T19:16:04.000Z","updated_at":"2024-05-27T22:56:50.466Z","dependencies_parsed_at":"2024-02-22T20:50:21.896Z","dependency_job_id":"43d5545f-f5d1-4467-8a43-3133f5b3a799","html_url":"https://github.com/fusion44/blitz_api","commit_stats":null,"previous_names":[],"tags_count":2,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusion44%2Fblitz_api","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusion44%2Fblitz_api/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusion44%2Fblitz_api/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/fusion44%2Fblitz_api/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/fusion44","download_url":"https://codeload.github.com/fusion44/blitz_api/tar.gz/refs/heads/dev","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":219859520,"owners_count":16556036,"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","fastapi","lightning-network","python","raspiblitz"],"created_at":"2024-09-28T02:21:59.919Z","updated_at":"2025-10-28T14:30:54.703Z","avatar_url":"https://github.com/fusion44.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Blitz API\n\n[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)\n\nA management backend for bitcoin and lightning node operators written in Python with FastAPI.\n\n## Beta Disclaimer\nThis software is still considered BETA and may contain bugs. Don't expose it to the open internet or use with a lot of funds.\n\n- [Blitz API](#blitz-api)\n  - [Beta Disclaimer](#beta-disclaimer)\n  - [Configuration](#configuration)\n    - [Dependencies](#dependencies)\n  - [Installation](#installation)\n    - [Linux / macOS](#linux--macos)\n    - [Windows](#windows)\n  - [Run the application](#run-the-application)\n    - [Linux / macOS](#linux--macos-1)\n    - [Windows](#windows-1)\n  - [Development](#development)\n      - [Using the nix package manager](#using-the-nix-package-manager)\n    - [Installation](#installation-1)\n    - [Sync changes to a RaspiBlitz](#sync-changes-to-a-raspiblitz)\n    - [Debugging code running on a remote machine via VSCode](#debugging-code-running-on-a-remote-machine-via-vscode)\n      - [Prepare local machine](#prepare-local-machine)\n      - [Prepare the RaspiBlitz](#prepare-the-raspiblitz)\n    - [Unit / Integration testing](#unit--integration-testing)\n      - [Run the tests with pytest](#run-the-tests-with-pytest)\n      - [Run tests and generate a coverage](#run-tests-and-generate-a-coverage)\n    - [Client libraries](#client-libraries)\n      - [Generating client libraries](#generating-client-libraries)\n    - [Before you commit](#before-you-commit)\n    - [Swagger / OpenAPI](#swagger--openapi)\n    - [Useful cURL commands to test the API](#useful-curl-commands-to-test-the-api)\n  - [Acknowledgements](#acknowledgements)\n\n## Configuration\n\nCreate a `.env` file with your `bitcoind` and `lnd` configuration. See the `.env_sample` file for all configuration options.\n\nThe `.env` file is expected to be at the project root folder by default.\nTo use a custom path, set the `BAPI_ENV_PATH` env variable to the `.env` file path.\n\n### Dependencies\n\n- [Python in version 3.7](https://www.python.org/downloads/)\n- [Redis](https://redis.io)\n- [Polar](https://github.com/jamaljsr/polar)\n  If you need an easy option to run a simple bitcoind \u0026 lnd client\n\n## Installation\n\n⚠️ To setup a development environment for BlitzAPI skip to the [Development](#Development) section.\n\n### Linux / macOS\n\n```sh\nmake install\n```\n\nor\n\n```sh\npython -m pip install -r requirements.txt\n```\n\n### Windows\n\n```sh\npy -m pip install -r requirements.txt\n```\n\n## Run the application\n\n### Linux / macOS\n\n```sh\nmake run\n```\n\nor\n\n```sh\npython -m uvicorn app.main:app --reload\n```\n\n### Windows\n\n```sh\npy -m uvicorn app.main:app --reload\n```\n\n## Development\n\nIt is recommended to have [python-poetry installed](\u003c(https://python-poetry.org/docs/master/#installation)\u003e).\n\nFrom within the `blitz_api` folder [open a poetry shell](https://python-poetry.org/docs/master/cli/#shell) via:\n\n```sh\npoetry shell\n```\n\n(To exit the poetry shell use: `exit`)\n\n#### Using the nix package manager\nBlitz API provides a [Nix](https://github.com/NixOS/nix) Flake file to create a development environment. Execute `nix develop` (make sure you have flakes enabled) to enter the environment.\n\nIn this environment a hidden folder `.venv` is created to install the python dependencies locally. If pyright can't find these dependencies create the following file in the root\nfolder of the project:\n```json\n{\n  \"venvPath\": \".\",\n  \"venv\": \".venv\"\n}\n```\n\n### Installation\n\n```\npoetry install\n```\n\nor\n\n```sh\nmake install-dev\n```\n\nIf python dependencies have been changed it's necessary to freeze all requirements to requirements.txt:\n\n```sh\npoetry export -f requirements.txt --output requirements.txt\n```\n\n\u003e ℹ️ This will skip all dev dependencies by default.\\\n\u003e This step is required to avoid having to install poetry for final deployment.\n\n### Sync changes to a RaspiBlitz\n\nCreate a file `/script/sync_to_blitz.personal.sh` (will be ignored by github) the SSH connection data to your RaspiBlitz.\n\nlocalIP=\"192.168.178.61\"\nsshPort=\"22\"\npasswordA=\"\"\n\nThen you can run always `make sync-to-blitz` to copy your latest code over to your RaspiBlitz. The script automatically restarts the backend API with the new code on your RaspiBlitz and shows you the logs.\n\nTo test the backend API then call the SwaggerUI: `http://[LOCALIP]/api/v1/docs` - to call protected endpoints run the `/system/login` endpoint first with HTTP POST body:\n```\n{\n  \"password\": \"[PASSWORDA]\"\n}\n```\nand then copy the JWT Auth string returned to `Authorize` in the top section of the SwaggerUI.\n\n*You can also now test the RaspiBlitz WebUI against the API by running it locally on your dev laptop when you configure it to use the backend API of your RaspiBlitz.*\n\n### Debugging code running on a remote machine via VSCode\nTo debug Python code that is running on another machine, like a RaspiBlitz, follow these steps.\n\n#### Prepare local machine\n* run `make install-dev`.\n* open the `.vscode/launch.json` file and change the host to your remote machines IP\n  * ```json\n      \"connect\": {\n        \"host\": \"192.168.1.49\",\n        \"port\": 5678\n      }\n      ```\n* open your `.env_sample` file and replace the line `# remote_debugging=false` with `remote_debugging=true`\n  \u003cdetails\u003e\n    This is necessary because we're going to synchronize the local source with the remote node. The blitz_api service will be restarted on the remote node. Any changes to the `.env' file will be overwritten by the setup script on the Blitz. This script will use the `.env_sample` file as a base and fill it with data. This way we can trick the Blitz into enabling this setting every time we change something without the Blitz explicitly supporting it.\n  \u003c/details\u003e\n* make sure you follow the steps in the [Sync changes to a RaspiBlitz](#sync-changes-to-a-raspiblitz) section\n* execute `make sync-to-blitz`\n* Make sure to chose `Attach` in the RUN AND DEBUG windows of VSCode\n* Hit F5 and voila you should be connected to your RaspiBlitz and debug code remotely\n\n#### Prepare the RaspiBlitz\n* SSH into the Blitz, and run `sudo -i -u blitzapi`\n* `cd blitz_api`\n* Finally run `make enable-remote-debugging`\n\n\nRefer to [this documentation](https://code.visualstudio.com/docs/python/debugging#_debugging-by-attaching-over-a-network-connection) to learn how to setup VSCode correctly.\n\n### Unit / Integration testing\n\nMake sure to include tests for important pieces of submitted code.\n\n#### Run the tests with pytest\n\n```sh\nmake test\n```\n\n#### Run tests and generate a coverage\n\n```sh\nmake coverage\n```\n\nThis will run tests and generate a coverage html file in this folder: `./htmlcov`\n\n### Client libraries\n\n\u003e ℹ️ The client libraries live in an extra repository:\nhttps://github.com/fusion44/blitz_api_client_libraries\n\n#### Generating client libraries\nInstall [OpenAPI Generator](https://openapi-generator.tech) and Java:\n\n\n```sh\nnpm install @openapitools/openapi-generator-cli -g\nsudo apt install default-jre\n```\n\n\nClone https://github.com/fusion44/blitz_api_client_libraries next to the blitz_api folder.\n\n```sh\nmake generate-client-libs\n```\n\u003e ⚠️ The first run requires `sudo` as it must download a Java .jar file to the system npm package folder.\n\n### [Swagger / OpenAPI](https://swagger.io)\n\nOnce the API is running swagger docs can be found here:\n\n```\nhttp://127.0.0.1:8000/latest/docs\n```\n\n### Useful cURL commands to test the API\n\n```sh\ncurl -N -H \"Authorization: Bearer JWT_TOKEN_HERE\" http://127.0.0.1:8000/sse/subscribe\n```\n\n```sh\ncurl -N -H \"Authorization: Bearer JWT_TOKEN_HERE\" http://127.0.0.1:8000/v1/bitcoin/getblockchaininfo\n```\n\n```sh\ncurl -X POST -N http://127.0.0.1:8000/v1/setup/type/1\n```\n\n```sh\ncurl --header \"Content-Type: application/json\" \\\n  --request POST \\\n  --data '{\"password\":\"12345678\"}' \\\n  http://127.0.0.1:8000/system/login\n```\n\n## Acknowledgements\n\nIntegrated Libraries:\n\n- [sse-starlette](https://github.com/sysid/sse-starlette)\n- [fastapi-versioning](https://github.com/DeanWay/fastapi-versioning)\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusion44%2Fblitz_api","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Ffusion44%2Fblitz_api","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Ffusion44%2Fblitz_api/lists"}