zeldhash-api

zeldhash-api is a REST API exposing ZeldHash database over HTTP. It reads from the SQLite database produced by the zeldhash-parser 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)
• zeldhash-parser collector running to populate both the SQLite stats database (expected filename: zeldstats.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/zeldhash/zeldhash-parser application (e.g. ~/.local/share/zeldhash-parser on Linux). You can override the location with the CLI flag or environment variable below.

Quickstart

cargo build --release
./target/release/zeldhash-api \
  --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 (zeldhash-api.toml is read automatically when present).

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=&sort= — Paginated rewards list (default order: newest blocks, then reward, then zero count). Pass sort=zero_count to surface the highest zero_count first.
• GET /rewards/:txid — Rewards for a specific transaction id.
• GET /addresses/:address/rewards?offset=&limit=&sort= — Paginated rewards for a specific address.
• 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 "http://localhost:3000/addresses/1A1zP1eP5QGefi2DMPTfTL5SLmv7DivfNa/rewards" | 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.