firo-shkeeper

A Docker Compose setup for running SHKeeper with Firo (FIRO) including Spark address support.

This repo provides a missing firod node that is missing from the SHKeeper documentation — there is no published firo-shkeeper Docker image and the Helm chart assumes you run a bundled firod version.

This setup allows you to connect SHKeeper to an existing firod node and includes a working CoinMarketCap rate source, since FIRO is missing from the exchanges supported by SHKeeper's built-in rate sources.

Features

• FIRO and FIRO-SPARK (Lelantus Spark) payment support
• Connects to an existing firod node via RPC
• CryptoCompare rate source (no API key required)
• CoinMarketCap as an alternative (free tier API key or higher required)
• Persistent SHKeeper database
• Compatible with SHKeeper 2.5.13+

Requirements

• Docker and Docker Compose
• A fully synced firod node accessible via RPC
• A SHKEEPER_BACKEND_KEY for webhook authentication
• A CoinMarketCap API key (if preferred as a rate source)

Setup

1. Clone the repo

git clone https://github.com/nexusocean/firo-shkeeper.git
cd firo-shkeeper

2. Configure environment

cp .env.example .env
nano .env

Fill in your values — see .env.example for all required variables.

3. Build and start

docker compose build
docker compose up -d
docker compose logs -f

On first start, firod will rescan the blockchain to initialize the shkeeper wallet. This takes a about few hours - 1 day depending on chain height. Monitor progress with:

docker compose logs -f firod

4. Access the dashboard

SHKeeper is available at http://localhost:5000 by default. Change add the default credentials after being prompted for the password at first login. You will then have the options for encrypting your wallet as well as adding 2fa (both recommended).

5. Configure rate source

In the SHKeeper dashboard, go to Rates and set the rate source for both FIRO and FIRO-SPARK. Two rate sources are included:

• cryptocompare — no API key required
• coinmarketcap — requires a CoinMarketCap API key, free within limits

FIRO is not supported by built-in rate sources.

6. Reverse proxy (optional)

If you want to expose SHKeeper via HTTPS, configure nginx to proxy 127.0.0.1:5000. Example nginx config:

server {
    listen 443 ssl;
    server_name your.domain.com;

    ssl_certificate /etc/letsencrypt/live/your.domain.com/fullchain.pem;
    ssl_certificate_key /etc/letsencrypt/live/your.domain.com/privkey.pem;

    location / {
        proxy_pass http://127.0.0.1:5000;
        proxy_set_header Host $host;
        proxy_set_header X-Real-IP $remote_addr;
        proxy_set_header X-Forwarded-For $proxy_add_x_forwarded_for;
        proxy_set_header X-Forwarded-Proto $scheme;
        proxy_http_version 1.1;
        proxy_set_header Upgrade $http_upgrade;
        proxy_set_header Connection "upgrade";
        proxy_read_timeout 86400;
    }
}

Environment Variables

Variable	Description
RPC_USER	firod RPC username
RPC_PASSWORD	firod RPC password
SHKEEPER_BACKEND_KEY	Secret key for walletnotify callbacks
CMC_API_KEY	CoinMarketCap API key (optional, but required if using coinmarketcap)

API Usage

SHKeeper exposes a REST API for creating payment requests.

• Example:

curl -X POST https://your.domain.com/api/v1/FIRO/payment_request \
  -H "X-Shkeeper-API-Key: YOUR_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "order-123",
    "fiat": "USD",
    "amount": 10.00,
    "callback_url": "https://your-backend.com/webhook/firo"
  }'

• Response:

{
"amount":"11.0841631",
"display_name":"Firo",
"exchange_rate":"0.9021880959",
"id":1,
"recalculate_after":0,
"status":"success",
"wallet":"aM2y6nhTc8RWZEU23soypwM4wGKSGoeP2m"
}

Use FIRO-SPARK instead of FIRO for Spark addresses.

Notes

• The vsyshost/shkeeper:latest Docker image is outdated (March 2023) and does not include FIRO support. Pin to 2.5.13 or later.
• FIRO is not supported by SHKeeper's built-in rate sources. Two working rate sources are included: cryptocompare.py (no API key needed) and coinmarketcap.py (API key required).
• The Dockerfile wraps firoorg/firod:latest to add curl and the walletnotify script required by SHKeeper.
• If you already have a firod node running, point the compose file at it and skip the bundled node, but the required RPC port for SHKeeper is 8332.

Related

• Firo

• SHKeeper