fedimint-clientd runs a fedimint client with Ecash, Lightning, and Onchain modules to let a server side application hold and use Bitcoin with Fedimint. It exposes a REST API & provides wrappers in typescript, python, and golang. It uses the multimint
crate to manages clients connected to multiple Federations from a single fedimint-clientd
instance.
This project is intended to be an easy-to-use starting point for those interested in adding Fedimint client support to their applications. Fedimint-clientd only exposes Fedimint's default modules, and any more complex Fedimint integration will require custom implementation using Fedimint's rust crates.
You can install the cli app with cargo install fedimint-clientd
or by cloning the repo and running cargo build --release
in the root directory.
fedimint-clientd
runs from the command line and takes a few arguments, which are also available as environment variables. Fedimint uses rocksDB, an embedded key-value store, to store its state. The --fm_db_path
argument is required and should be an absolute path to a directory where the database will be stored.
CLI USAGE:
fedimint-clientd \
--fm_db_path=/absolute/path/to/dir/to/store/database \
--password="some-secure-password-that-becomes-the-bearer-token" \
--addr="127.0.0.1:8080"
--mode="default"
ENV USAGE:
FEDIMINT_CLIENTD_DB_PATH=/absolute/path/to/dir/to/store/database
FEDIMINT_CLIENTD_PASSWORD="some-secure-password-that-becomes-the-bearer-token"
FEDIMINT_CLIENTD_ADDR="127.0.0.1:8080"
FEDIMINT_CLIENTD_MODE="default"
fedimint-clientd
supports the following endpoints (and has naive websocket support at /fedimint/v2/ws
, see code for details until I improve the interface. PRs welcome!). All the endpoints are authed with a Bearer token from the password (from CLI or env). You can hit the endpoints as such with curl, or use the python/typescript/golang wrappers:
curl http://localhost:3333/fedimint/v2/admin/info -H 'Authorization: Bearer some-secure-password-that-becomes-the-bearer-token'
/fedimint/v2/admin/info
: Display wallet info (holdings, tiers)./fedimint/v2/admin/backup
: Upload the (encrypted) snapshot of mint notes to federation./fedimint/v2/admin/discover-version
: Discover the common api version to use to communicate with the federation./fedimint/v2/admin/restore
: Restore the previously created backup of mint notes (withbackup
command)./fedimint/v2/admin/list-operations
: List operations./fedimint/v2/admin/module
: Call a module subcommand./fedimint/v2/admin/config
: Returns the client config.
/fedimint/v2/mint/reissue
: Reissue notes received from a third party to avoid double spends./fedimint/v2/mint/spend
: Prepare notes to send to a third party as a payment./fedimint/v2/mint/validate
: Verifies the signatures of e-cash notes, but not if they have been spent already./fedimint/v2/mint/split
: Splits a string containing multiple e-cash notes (e.g. from thespend
command) into ones that contain exactly one./fedimint/v2/mint/combine
: Combines two or more serialized e-cash notes strings.
/fedimint/v2/ln/invoice
: Create a lightning invoice to receive payment via gateway./fedimint/v2/ln/await-invoice
: Wait for incoming invoice to be paid./fedimint/v2/ln/pay
: Pay a lightning invoice or lnurl via a gateway./fedimint/v2/ln/await-pay
: Wait for a lightning payment to complete./fedimint/v2/ln/list-gateways
: List registered gateways./fedimint/v2/ln/switch-gateway
: Switch active gateway.
/fedimint/v2/onchain/deposit-address
: Generate a new deposit address, funds sent to it can later be claimed./fedimint/v2/onchain/await-deposit
: Wait for deposit on previously generated address./fedimint/v2/onchain/withdraw
: Withdraw funds from the federation.
/health
: health check endpoint./metrics
: exports API metrics using opentelemetry with prometheus exporter (num requests, latency, high-level metrics only)