Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/blockonomics/wallet_service
Self hosted bitcoin wallet service
https://github.com/blockonomics/wallet_service
bitcoin python3 rest-api wallet-service
Last synced: 19 days ago
JSON representation
Self hosted bitcoin wallet service
- Host: GitHub
- URL: https://github.com/blockonomics/wallet_service
- Owner: blockonomics
- Created: 2022-01-10T11:54:27.000Z (almost 3 years ago)
- Default Branch: master
- Last Pushed: 2024-04-27T19:05:51.000Z (7 months ago)
- Last Synced: 2024-10-11T00:48:20.857Z (about 1 month ago)
- Topics: bitcoin, python3, rest-api, wallet-service
- Language: Python
- Homepage: https://youtu.be/GpN6B7ca5-I
- Size: 109 KB
- Stars: 13
- Watchers: 5
- Forks: 9
- Open Issues: 16
-
Metadata Files:
- Readme: readme.md
Awesome Lists containing this project
README
# Self hosted bitcoin wallet service
This is a lightweight bitcoin wallet service that is easy to install and can be run on a 5$ VPS.
## Features
- Complete self custody of funds
- Automatic batching of send transactions to minimize fee
- Easy to use REST API interface
- Internally uses electrum library to work as an SPV wallet
- Gets up running instantly [no requirement for waiting days to sync with network]
## Architecture and Magic Sauce
This is a service built on top of electrum-4.2.1 wallet library. So funds/private keys are in your own custody and security of wallet is guaranteed by robustness of [electrum source code](https://electrum.org/#download)
The frequent problem faced with sending bitcoin is that if you just send BTC directly you may end up paying high fee for withdraw (which is exaggerated for low amounts). If you wait and batch all withdraws, recepients end up waiting a long time and get irritated. This is what this service does:
- Never immediately send bitcoin. Adds all send requests to a queue
- Batches send requests currently kept in queue and attempt to send them periodicially. Send is done only when (fee/total send amount) is less than a given percent (fa_ratio_limit)
- To avoid recepients waiting for a long time, fa_ratio_limit increases as sends wait in a queue
## Installation
Use virtual environment (python >=3.8)
1. Packages:
* Libsec package is needed `sudo apt install libsecp256k1-dev`
* Rust compiler may need to be installed depending on current server config: `sudo apt install rustc`
2. Electrum:
* `pip install cryptography pyqt5`
* `wget https://download.electrum.org/4.2.1/Electrum-4.2.1.tar.gz`
* `tar -xvf Electrum-4.2.1.tar.gz`
* `pip install -e Electrum-4.2.1/.`
3. Wallet Service:
* Clone the repository: `git clone https://github.com/blockonomics/wallet_service.git`
* Install required python packages: `pip install sqlalchemy requests sanic cryptocode`
4. Change directory `cd wallet_service`
5. Init DB `python db_model.py`
6. Do basic config
* `cp config.ini.sample config.ini`
* `python wallet_service_cli.py setapiconfig use_testnet `
* `python wallet_service_cli.py createwallet `
* `python wallet_service_cli.py setapiconfig api_password `
7. Start the service (default port is localhost:8080)
* `python wallet_service_api.py`
8. (Optional) Setup supervisor to run Wallet Service
* `sudo apt install supervisord`
* Edit `wallet_service_supervisor.conf` to match system configurations
* `cp wallet_service_supervisor.conf /etc/supervisor/conf.d/`
* `sudo supervisorctl reread`
* `sudo supervisorctl update`
* `sudo supervisorctl start wallet_service`
## API Documentation
#### POST /api/presend
Estimate transaction fee, dry run of send.
**Parameters:**
`{addr, btc_amount, wallet_id, wallet_password, api_password}`
**Response:**
```
estimated_fee : Estimated fee for this send
error: 500 HTTP Status / “Error msg”
```
#### POST /api/send
Schedules the transaction to be sent when threshold is met.
**Parameters:**
`{addr, btc_amount, wallet_id, wallet_password, api_password}`
**Response:**
```
estimated_fee: Estimated weighted fee for this send
sr_id: send request id (unique internal id to track this send)
error: 500 HTTP Status / “Error msg”
```
#### GET /api/detail/
**Response:**
```
tx_id: Bitcoin transaction id of this send if it has been sent
sr_timestamp: Timestamp of this send request (in unix milliseconds)
tx_timestamp: Timestamp of actual bitcoin tx (in unix milliseconds)
addr: Bitcoin Address to send payment to
amount: Amount of bitcoin to send
tx_fee: Actual weighted network fee taken by this send
```
#### GET /api/history?limit=1
Return the history of completed sends
**Response:**
Array of (tx_timestamp, sr_id, tx_id) dicts sorted in descending order of tx_timestamp.
#### GET /api/queue
Return the current status of send queue
**Response:**
{sr_ids: list of queued send requests, amount: total btc amount scheduled to be sent, fee: current fee required for send, fa_ratio: current fee to amount ratio, fa_ratio_limit: fa_ratio must be below this for send to complete, next_send_attempt_in: Time in seconds when next send will be attempted}
#### POST /api/get_balance
Syncs wallet to network and returns current wallet confirmed and unconfirmed balance
**Parameters:**
`{wallet_id, wallet_password, api_password}`
**Response:**
```
confirmed: Confirmed wallet balance
unconfirmed: Unconfirmed wallet balance
error: 500 HTTP Status / “Error msg”
```
## Command Line
Various admin functions like creating wallet, getting balance can performed to CLI which can be acessed via
```
python wallet_service_cli.py -h
Available commands:
getapiconfig
setapiconfig
listwallets
createwallet
getinfo
getbalance
gethistory
sendtoaddress
getunusedaddress
```
## API Config
Use CLI to get current values of config or change them:
```
python wallet_service_cli.py getapiconfig
python wallet_service_cli.py setapiconfig
```
Available configs are:
* **wallet_dir**: Directory to store bitcoin wallet keys
* **use_testnet**: True/False. Use to switch between bitcoin mainnet/testnet
* **fee_level**: Fee rate levels used for sending. Use high level for more fee (but faster confirmation)
* **api_password**: Password to be used for HTTP API calls
* **fa_ratio_min** : Minimum tolerable fee to send amount ratio - default 5%
* **fa_ratio_max** : Maximum tolerable fee to send amount ratio - default 50%
* **send_frequency** : Send is attempted regularly with this frequency - default 5 minutes