SHKeeper: a self-hosted crypto payment processor that runs inside your own k3s cluster

What problem SHKeeper removes, and for whom

A merchant who wants to take bitcoin today usually has two options. Route payments through a hosted processor that holds the keys, charges a percentage, and may require identity checks, or build wallet scanning and confirmation tracking from scratch. SHKeeper targets the gap between those. It is described in the README as an open-source, self-hosted cryptocurrency payment processor that "uniquely serves as both a gateway and a merchant," meaning the same software creates the invoice and receives the funds, with no intermediary in the settlement path.

The intended user is visible in the feature list: non-custodial, multi-currency, no transaction fees and third parties, no KYC or AML. That combination points at merchants with an existing Kubernetes footprint, at operators in jurisdictions where hosted processors are awkward, and at businesses that already hold their own wallets and simply need an invoicing and callback layer on top. The ready-made modules for WHMCS, WooCommerce, Opencart 3 and Prestashop 8 suggest the project expects to be dropped into a shop that already exists rather than a greenfield application. Anyone without a Kubernetes cluster is not the target audience, and the installation section makes no attempt to hide that.

How the payment flow is actually wired

The README separates the system into two halves: a payment flow and an API. The payment flow is the part a customer touches. SHKeeper generates a deposit address for an invoice, watches the chain, and moves the invoice through states as confirmations arrive. The feature list names the edge cases explicitly: partial payments, overpayment credited to the balance, and auto-payments into a cold wallet. Those three behaviours are where most homegrown implementations break, because they require the gateway to keep a running per-invoice ledger rather than a single boolean paid flag.

On the API side, the surface is broader than a minimal gateway would need. There are endpoints to retrieve the list of available cryptocurrencies, create an invoice, retrieve created addresses, retrieve transactions by address, and look up a record by external_id or by the pair of transaction_id and external_id. That last pair matters for reconciliation: if your order system and SHKeeper disagree about a payment, you can query the intersection rather than guessing. A wallet encryption section describes entering a decryption_key via API, which implies the node wallets are stored encrypted and the key is supplied at runtime rather than baked into the chart. The payout endpoints are separate and include creating a payout task, creating a multipayout task, checking task status, fetching crypto balance, and fetching a fee deposit address. Multipayout is listed as a feature and has its own endpoint, so batch disbursement is a first-class path, not a script you write yourself.

Installation assumes k3s and Helm, not Docker Compose

The README's installation path is short and opinionated. It starts by installing k3s on a fresh server, tested on Ubuntu 22, then creates the kubeconfig symlink and installs Helm from the official script. Configuration is a values.yaml file with per-coin toggles. The README's example enables BTC, LTC, DOGE and Monero, with Monero also enabling a fullnode sub-key:

storageClassName: local-path btc: enabled: true monero: enabled: true fullnode: enabled: true

From there the chart is installed from the vsys-host Helm repository, with a dependency on mittwald/kubernetes-secret-generator installed first. The UI is then reachable on port 5000 at the server's IP. Optional TLS uses cert-manager v1.9.1 with installCRDs=true, plus a Certificate and a ClusterIssuer for Let's Encrypt production and a Traefik IngressRoute pointing at the shkeeper service on port 5000. The README instructs you to replace the demo domain and the ACME email address before applying.

Two details stand out. The chart does not bundle secret generation, so kubernetes-secret-generator is a hard prerequisite rather than an optional convenience. And the TLS example hardcodes the Traefik ingress class, so a cluster running nginx-ingress needs the manifest rewritten. Neither is a flaw, but both mean the copy-paste path only works on a cluster shaped like the author's.

Coins, chains, and the node burden you inherit

The README lists a wide asset set: BTC including Lightning Network, ETH, LTC, DOGE, XMR, XRP, TRX, BNB, SOL, MATIC, AVAX, FIRO, ARB, OP, TON and DAI, plus USDT and USDC across ERC20, TRC20, BEP-20, Polygon, Avalanche, Arbitrum, Optimism and TON, and PYUSD on ERC20 and Solana. That breadth is the headline number, and it is also the operational bill. Each enabled chain implies a node or an RPC dependency that you run and keep synced. The values.yaml example enables four coins; a merchant who enables fifteen has taken on fifteen upgrade calendars.

This is the trade-off the README does not spell out. The demo runs on testnet, which is a sensible way to evaluate the interface, but testnet tells you nothing about disk growth on a Monero or Bitcoin full node, or about what happens when a chain halts. The project claims increased privacy and security and no third parties, and that claim is only as strong as your node hygiene. If you enable a chain and let its node fall behind, invoices on that chain stop confirming. There is no hosted fallback described in the material.

Callbacks and signature verification are where integrations fail

The README links a dedicated guide for webhook signature verification using HMAC-SHA256, with Python, Flask and PHP examples, and explicitly says to use it when implementing or updating a custom payment module. That sentence is doing real work. A callback endpoint that credits an order without validating the signature is an open door: anyone who learns the URL can post a fake payment confirmation. The documentation treats verification as a prerequisite for custom modules rather than an advanced topic, which is the right framing.

The API authentication model splits along the same lines. ApiKey is the general mechanism, while Basic auth is noted as used only for Payout. So the credential that creates invoices is not the credential that moves funds out, which limits the blast radius of a leaked key from a web front end. The material does not describe key rotation, scoping or expiry, so treat those as unverified. If you are writing a module, the sequence to confirm before going live is: create an invoice, receive the callback, verify the HMAC-SHA256 signature against the shared secret, and only then mark the order paid.

Where SHKeeper is the wrong tool

SHKeeper is not a fiat product. Nothing in the material mentions conversion to bank currency, card rails, refunds or chargebacks. A merchant whose customers expect to pay by card and see a euro amount settled in a euro account gets nothing from this. Crypto payments here are final and push-based, and the feature list treats that as the point rather than a gap.

It is also a poor fit for teams without container orchestration experience. The install path is k3s, Helm, a secret-generator dependency and optional cert-manager CRDs. A single-server Docker Compose deployment is not offered in the README. If nobody on the team can debug a pod that will not schedule or a node that will not sync, the first chain reorg or disk-full event becomes an outage with no vendor to escalate to. And because the licence is GPL-3.0, anyone distributing a modified version, for example shipping a customized SHKeeper inside a commercial product, takes on the obligations that licence carries. That is a distribution question, not a usage question, and it deserves a lawyer's read rather than a summary here.

How it differs from a hosted processor like BTCPay Server's model

The obvious comparison is BTCPay Server, another self-hosted, non-custodial payment processor. The difference is scope rather than philosophy. BTCPay Server grew out of the Bitcoin ecosystem and its chain coverage reflects that heritage. SHKeeper's README advertises a broader altcoin and stablecoin set, including TRON, Solana, TON, Arbitrum and Optimism alongside Bitcoin and Monero, and it ships merchant modules for WHMCS, WooCommerce, Opencart 3 and Prestashop 8 as part of the repository rather than as a separate plugin directory.

The deployment model diverges too. SHKeeper's documented install is a Helm chart into k3s, which suits teams already running Kubernetes and gives them declarative per-coin toggles in values.yaml. An operator who wants a single VPS with Docker and no cluster is better served by the other project. An operator who already has a cluster and needs TRC20 USDT alongside BTC has a reason to look here. Neither choice removes the node operations, so the decision is really about which packaging matches the infrastructure you already run.

Maintenance cadence and what upgrading costs

Release history shows a steady patch rhythm: v2.5.30 in late July, v2.5.31 in mid August, v2.5.32 at the end of August, all in the same 2.5.x line. Frequent patch releases on a payment system usually mean bug fixes and dependency bumps rather than feature work, and that is a reasonable signal that the project is maintained. It is not a signal about upgrade safety, and the README does not document a migration procedure, a database schema version, or a rollback path.

Because deployment is a Helm chart, the upgrade command is a helm upgrade against the same values.yaml, and the practical risk sits in two places: whether the chart's bundled node images change in a way that requires a resync, and whether the wallet encryption key handling changed. The README's decryption_key endpoint implies keys are supplied at runtime, so a botched upgrade that loses that key is a fund-access problem, not a downtime problem. Back up the values file and confirm you can still supply the decryption key before pulling a new chart version. The GPL-3.0 licence places no fee on running SHKeeper for your own business; it constrains redistribution, so if your plan is to embed it in something you ship to customers, the licence text is the document to read first.

Editorial conclusion

Adopt SHKeeper if you already run Kubernetes, want settlement to land in wallets you control, and are prepared to operate full nodes for every chain you enable. Do not adopt it if you need fiat off-ramp, chargeback handling, or a vendor to call when a chain upgrade breaks your node. Before committing, verify two things on your own hardware: that the coin set you need is listed in section 2 of the README, and that a testnet invoice reaches your callback URL with a signature your code validates against the HMAC-SHA256 guide.

Official sources

1. License: GPL-3.0
2. Project website
3. README
4. Releases
5. vsys-host/shkeeper.io on GitHub