{"id":21110019,"url":"https://github.com/cashubtc/nutshell","last_synced_at":"2026-01-16T13:39:31.250Z","repository":{"id":59312052,"uuid":"535160981","full_name":"cashubtc/nutshell","owner":"cashubtc","description":"Chaumian ecash wallet and mint for Bitcoin","archived":false,"fork":false,"pushed_at":"2026-01-11T10:05:41.000Z","size":25063,"stargazers_count":459,"open_issues_count":140,"forks_count":139,"subscribers_count":16,"default_branch":"main","last_synced_at":"2026-01-11T15:03:12.973Z","etag":null,"topics":["bitcoin","ecash","lightning-network","privacy"],"latest_commit_sha":null,"homepage":"https://docs.cashu.space","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/cashubtc.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":"CONTRIBUTING.md","funding":".github/FUNDING.yml","license":"LICENSE.md","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,"zenodo":null,"notice":null,"maintainers":null,"copyright":null,"agents":null,"dco":null,"cla":null},"funding":{"custom":"https://docs.cashu.space/contribute"}},"created_at":"2022-09-11T01:26:19.000Z","updated_at":"2026-01-11T10:05:46.000Z","dependencies_parsed_at":"2023-09-25T20:37:07.497Z","dependency_job_id":"d816b79c-53c9-4fc8-9dc8-46986449ae5e","html_url":"https://github.com/cashubtc/nutshell","commit_stats":{"total_commits":508,"total_committers":11,"mean_commits":46.18181818181818,"dds":0.04527559055118113,"last_synced_commit":"258de87a9a53f68cfef14ffc4db4c2972c8a94eb"},"previous_names":["cashubtc/nutshell","cashubtc/cashu"],"tags_count":31,"template":false,"template_full_name":null,"purl":"pkg:github/cashubtc/nutshell","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cashubtc%2Fnutshell","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cashubtc%2Fnutshell/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cashubtc%2Fnutshell/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cashubtc%2Fnutshell/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/cashubtc","download_url":"https://codeload.github.com/cashubtc/nutshell/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/cashubtc%2Fnutshell/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":286080680,"owners_count":28479033,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2026-01-16T11:59:17.896Z","status":"ssl_error","status_checked_at":"2026-01-16T11:55:55.838Z","response_time":107,"last_error":"SSL_read: unexpected eof while reading","robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":false,"can_crawl_api":true,"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","ecash","lightning-network","privacy"],"created_at":"2024-11-20T00:57:42.456Z","updated_at":"2026-01-16T13:39:31.240Z","avatar_url":"https://github.com/cashubtc.png","language":"Python","funding_links":["https://docs.cashu.space/contribute"],"categories":["Wallets"],"sub_categories":[],"readme":"# Cashu Nutshell\n\n**Nutshell is a Chaumian Ecash wallet and mint for Bitcoin Lightning based on the Cashu protocol.**\n\n\u003ca href=\"https://pypi.org/project/cashu/\"\u003e\u003cimg alt=\"Release\" src=\"https://img.shields.io/pypi/v/cashu?color=black\"\u003e\u003c/a\u003e \u003ca href=\"https://pepy.tech/project/cashu\"\u003e \u003cimg alt=\"Downloads\" src=\"https://pepy.tech/badge/cashu\"\u003e\u003c/a\u003e \u003ca href=\"https://app.codecov.io/gh/cashubtc/nutshell\"\u003e\u003cimg alt=\"Coverage\" src=\"https://img.shields.io/codecov/c/gh/cashubtc/nutshell\"\u003e\u003c/a\u003e\n\nCashu is a free and open-source [Ecash protocol](https://github.com/cashubtc/nuts) based on David Wagner's variant of Chaumian blinding called [Blind Diffie-Hellman Key Exchange](https://cypherpunks.venona.com/date/1996/03/msg01848.html) scheme written down [here](https://gist.github.com/RubenSomsen/be7a4760dd4596d06963d67baf140406).\n\n\u003cp align=\"center\"\u003e\n\u003ca href=\"#the-cashu-protocol\"\u003eCashu protocol\u003c/a\u003e ·\n\u003ca href=\"#easy-install-nutshell-wallet\"\u003eQuick Install\u003c/a\u003e ·\n\u003ca href=\"#manual-install-poetry\"\u003eManual install\u003c/a\u003e ·\n\u003ca href=\"#configuration\"\u003eConfiguration\u003c/a\u003e ·\n\u003ca href=\"#using-cashu\"\u003eUsing Cashu\u003c/a\u003e ·\n\u003ca href=\"#running-a-mint\"\u003eRun a mint\u003c/a\u003e\n\u003c/p\u003e\n\n### Feature overview\n\n- Bitcoin Lightning support (LND, CLN, et al.)\n- Full support for the Cashu protocol [specifications](https://github.com/cashubtc/nuts)\n- Standalone CLI wallet and mint server\n- Wallet and mint library you can include in other Python projects\n- PostgreSQL and SQLite\n- Wallet with builtin Tor\n- Use multiple mints in a single wallet\n\n### Advanced features\n\n- Deterministic wallet with seed phrase backup ([NUT-13](https://github.com/cashubtc/nuts/blob/main/13.md))\n- Programmable ecash: P2PK and HTLCs ([NUT-10](https://github.com/cashubtc/nuts/blob/main/10.md))\n- Wallet and mint support for keyset rotations\n- DLEQ proofs for offline transactions ([NUT-12](https://github.com/cashubtc/nuts/blob/main/12.md))\n- Optional caching using Redis ([NUT-19](https://github.com/cashubtc/nuts/blob/main/19.md))\n- Optional authentication using Keycloak ([NUT-21](https://github.com/cashubtc/nuts/blob/main/21.md))\n\n## The Cashu protocol\n\nDifferent Cashu clients and mints use the same protocol to achieve interoperability. See the [documentation page](https://docs.cashu.space/) for more information on other projects. If you are interested in developing on your own Cashu project, please refer to the [protocol specs](https://github.com/cashubtc/nuts).\n\n## Easy Install: Nutshell wallet\n\nThe easiest way to use Cashu is to install the package via pip:\n\n```bash\npip install cashu\n```\n\nTo update Cashu, use `pip install cashu -U`.\n\nIf you have problems running the command above on Ubuntu, run `sudo apt install -y pip pkg-config` and `pip install wheel`. On macOS, you might have to run `pip install wheel` and `brew install pkg-config`.\n\nYou can skip the entire next section about Poetry and jump right to [Using Cashu](#using-cashu).\n\n## Easy Install: Nutshell mint\n\nThe easiest way to get a mint running is through Docker.\n\nYou can build the image yourself by running the following command. Make sure to adjust the environment variables in `docker-compose.yaml`.\n\n```bash\ndocker compose up mint\n```\n\n**Note:** If you have a local `.env` file, it will be copied into the container and may override docker-compose environment variables. To ensure the mint is accessible from your host machine, either:\n\n- Set `MINT_LISTEN_HOST=0.0.0.0` in your `.env` file, or\n- Use the pre-built Docker image command in the [Running a mint](#running-a-mint) section which sets environment variables directly.\n\n## Manual install: Poetry\n\nThese steps help you install Python via pyenv and Poetry. If you already have Poetry running on your computer, you can skip this step and jump right to [Poetry: Install Cashu Nutshell](#poetry-install-cashu-nutshell).\n\n#### Poetry: Prerequisites\n\n```bash\n# on ubuntu:\nsudo apt install -y build-essential pkg-config libffi-dev libpq-dev zlib1g-dev libssl-dev python3-dev libsqlite3-dev ncurses-dev libbz2-dev libreadline-dev lzma-dev liblzma-dev\n\n# install python using pyenv\ncurl https://pyenv.run | bash\n\n# !! follow the instructions of pyenv init to setup pyenv !!\npyenv init\n\n# restart your shell (or source your .rc file), then install python:\npyenv install 3.10.4\n\n# install poetry\ncurl -sSL https://install.python-poetry.org | python3 - --version 1.8.5\necho export PATH=\\\"$HOME/.local/bin:$PATH\\\" \u003e\u003e ~/.bashrc\nsource ~/.bashrc\n```\n\n#### Poetry: Install Cashu Nutshell\n\n```bash\n# install nutshell\ngit clone https://github.com/cashubtc/nutshell.git nutshell\ncd nutshell\ngit checkout \u003clatest_tag\u003e\npyenv local 3.10.4\npoetry install\n```\n\n#### Poetry: Update Cashu\n\nTo update Cashu to the newest version enter\n\n```bash\ngit pull \u0026\u0026 poetry install\n```\n\n#### Poetry: Using the Nutshell wallet\n\nCashu should be now installed. To execute the following commands, activate your virtual Poetry environment via\n\n```bash\npoetry shell\n```\n\nIf you don't activate your environment, just prepend `poetry run` to all following commands.\n\n## Configuration\n\n```bash\nmv .env.example .env\n# edit .env file\nvim .env\n```\n\nTo use the wallet with the [public test mint](#test-instance), you need to change the appropriate entries in the `.env` file.\n\n#### Test instance\n*Warning: this instance is just for demonstration purposes and development only. The satoshis are not real.*\n\nChange the appropriate `.env` file settings to\n\n```bash\nMINT_URL=https://testnut.cashu.space\n```\n\n# Using Cashu\n\n```bash\ncashu info\n```\n\nThis command shows information about your wallet.\n\n#### Check balance\n\n```bash\ncashu balance\n```\n\n#### Generate a Lightning invoice\n\nThis command will return a Lightning invoice that you need to pay to mint new ecash tokens.\n\n```bash\ncashu invoice 420\n```\n\nThe client will check every few seconds if the invoice has been paid. If you abort this step but still pay the invoice, you can use the command `cashu invoice \u003camount\u003e --id \u003cid\u003e`.\n\n#### Pay a Lightning invoice\n\n```bash\ncashu pay lnbc120n1p3jfmdapp5r9jz...\n```\n\n#### Send tokens\n\nTo send tokens to another user, enter\n\n```bash\ncashu send 69\n```\n\nYou should see the encoded token. Copy the token and send it to another user such as via email or a messenger. The token looks like this:\n\n```bash\ncashuBo2F0gaJhaUgA2...\n```\n\n#### Receive tokens\n\nTo receive tokens, another user enters:\n\n```bash\ncashu receive cashuBo2F0gaJhaUgA2...\n```\n\n# Running a mint\n\nThis command runs the mint on your local computer. Skip this step if you want to use the [public test mint](#test-instance) instead.\n\n## Docker\n\nRun the mint using the pre-built Docker image. This method sets environment variables directly and works reliably regardless of local `.env` files:\n\n```bash\ndocker run -d -p 3338:3338 --name nutshell -e MINT_BACKEND_BOLT11_SAT=FakeWallet -e MINT_LISTEN_HOST=0.0.0.0 -e MINT_LISTEN_PORT=3338 -e MINT_PRIVATE_KEY=TEST_PRIVATE_KEY cashubtc/nutshell:0.18.2 poetry run mint\n```\n\n## From this repository\n\nBefore you can run your own mint, make sure to enable a Lightning backend in `MINT_BACKEND_BOLT11_SAT` and set `MINT_PRIVATE_KEY` in your `.env` file.\n\n```bash\npoetry run mint\n```\n\nFor testing, you can use Nutshell without a Lightning backend by setting `MINT_BACKEND_BOLT11_SAT=FakeWallet` in the `.env` file.\n\n### NUT-19 Caching with Redis\n\nTo cache HTTP responses ([NUT-19](https://github.com/cashubtc/nuts/blob/main/19.md)), you can either install Redis manually or use the docker compose file in `docker/redis/docker-compose.yaml` to start Redis in a container.\n\nEdit the `.env` file and uncomment the Redis lines:\n\n```bash\nMINT_REDIS_CACHE_ENABLED=TRUE\nMINT_REDIS_CACHE_URL=redis://localhost:6379\n```\n\n### NUT-21 Authentication with Keycloak\n\nCashu supports clear and blind authentication as defined in [NUT-21](https://github.com/cashubtc/nuts/blob/main/21.md) and [NUT-22](https://github.com/cashubtc/nuts/blob/main/22.md) to limit the use of a mint to a registered set of users. Clear authentication is supported via an OIDC provider such as Keycloak. You can set up and run Keycloak instance using the docker compose file `docker/keycloak/docker-compose.yml` in this repository.\n\n### Migrate SQLite mint DB to Postgres\n\nUse the standalone tool at `cashu/mint/sqlite_to_postgres.py` to migrate a mint database from SQLite to Postgres.\n\n```bash\n# 1) optionally reset the target Postgres database (DROPS ALL DATA)\npsql -U \u003cuser\u003e -h \u003chost\u003e -p \u003cport\u003e -d \u003cdatabase\u003e -c \"DROP SCHEMA public CASCADE; CREATE SCHEMA public; GRANT ALL PRIVILEGES ON SCHEMA public TO \u003cuser\u003e;\"\n\n# 2) run migration (inside poetry env)\npoetry run python cashu/mint/sqlite_to_postgres.py \\\n  --sqlite data/mint/mint.sqlite3 \\\n  --postgres postgres://\u003cuser\u003e:\u003cpass\u003e@\u003chost\u003e:\u003cport\u003e/\u003cdatabase\u003e \\\n  --batch-size 2000\n```\n\n- The tool aborts if the Postgres DB appears populated and prints the exact reset command with your connection details.\n- After copying, it verifies row counts and compares the `balance` view across both databases.\n\n# Running tests\n\nTo run the tests in this repository, first install the dev dependencies with\n\n```bash\npoetry install --with dev\n```\n\nThen, make sure to set up your mint's `.env` file to use a fake Lightning backend and disable Tor:\n\n```bash\nMINT_BACKEND_BOLT11_SAT=FakeWallet\nTOR=FALSE\n```\n\nYou can run the tests with\n\n```bash\npoetry run pytest tests\n```\n\n# Contributing\n\nDevelopers are invited to contribute to Nutshell. Please see the [contribution guide](CONTRIBUTING.md).\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcashubtc%2Fnutshell","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fcashubtc%2Fnutshell","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fcashubtc%2Fnutshell/lists"}