Installing the command-line executable

Assuming you have Rust/Cargo installed, run this command in a terminal:

cargo install mhinapi

It will make the mhinapi command available in your PATH if you've allowed the PATH to be modified when installing Rust. cargo uninstall mhinapi uninstalls.

Back to the crate overview.

Readme

mhinapi

mhinapi is a REST API exposing My Hash Is Nice database over HTTP. It reads from the SQLite database produced by the mhinparser collector and uses a rollblock server to fetch UTXO balances while also querying an Electrum-compatible API for address data.

Requirements

Rust 1.81+ (Edition 2021)
mhinparser collector running to populate both the SQLite stats database (expected filename: mhinstats.sqlite3) and the rollblock store
Access to a rollblock server (host/port/user/password)
Network access to an Electrum-compatible API (default: https://mempool.space/api/)

By default the SQLite file is looked up in the platform data directory for the org/myhashisnice/mhinparser application (e.g. ~/.local/share/mhinparser on Linux). You can override the location with the CLI flag or environment variable below.

Quickstart

cargo build --release
./target/release/mhinapi \
  --data-dir /path/to/data \
  --rollblock-host 127.0.0.1 \
  --rollblock-port 9443 \
  --electr-url https://mempool.space/api/ \
  --server-host 0.0.0.0 \
  --server-port 3000

Configuration

All options can be set via CLI flags, environment variables, or a config file parsed by the config crate (mhinapi.toml is read automatically when present).

Purpose	CLI flag	Env var	Default
Data directory	`--data-dir`	`MHINAPI_DATA_DIR`	platform user data dir
Rollblock host	`--rollblock-host`	`MHINAPI_ROLLBLOCK_HOST`	`localhost`
Rollblock port	`--rollblock-port`	`MHINAPI_ROLLBLOCK_PORT`	`9443`
Rollblock user	`--rollblock-user`	`MHINAPI_ROLLBLOCK_USER`	`mhin`
Rollblock password	`--rollblock-password`	`MHINAPI_ROLLBLOCK_PASSWORD`	`mhin`
Electrum API URL	`--electr-url`	`MHINAPI_ELECTR_URL`	`https://mempool.space/api/`
HTTP bind host	`--server-host`	`MHINAPI_SERVER_HOST`	`0.0.0.0`
HTTP bind port	`--server-port`	`MHINAPI_SERVER_PORT`	`3000`

API overview

GET / — Health check; verifies the SQLite pool is available.
GET /blocks — Latest cumulative statistics from the stats table.
GET /blocks/:block_height — Block-level stats plus rewards for the given height.
GET /rewards?offset=&limit= — Paginated list of rewards sorted by reward and block height.
GET /addresses/:address/utxos — Returns confirmed UTXOs for an address with rollblock balances.
GET /utxos/:txid:vout — Balance for a single outpoint.
POST /utxos — Batch balances for up to 100 outpoints.

Example:

curl http://localhost:3000/blocks/840000 | jq
curl "http://localhost:3000/rewards?limit=10&offset=0" | jq
curl -X POST http://localhost:3000/utxos \
  -H "Content-Type: application/json" \
  -d '{"utxos":["<txid>:0","<txid2>:1"]}'

The API returns 500 responses for rollblock/SQLite failures and 400 for malformed inputs; missing resources return 404.

Development

Run tests: cargo test
Format: cargo fmt

License

Licensed under either of

Apache License, Version 2.0
MIT license

at your option.