Confirmations are a floor
A transfer is never reported paid on confirmations alone, nor for being deep. The finalised block is the highest one that two of your endpoints attest; one endpoint that claims a higher one is not believed about it.
Self-hosted · non-custodial · open source
hmnpay is a payment gateway for stablecoin payments that you run on your own server. It gives each order its own deposit address in your wallet, watches the chain until the money has arrived and is final, and tells your shop by webhook.
It only ever sees your wallet’s extended public key, so it cannot move funds. This beta supports USDT (BEP-20) on BNB Smart Chain only.
Beta. hmnpay has not had an independent third-party security audit. Read the known limits first, and start with amounts you can afford to have delayed.
A payment is paid when the money has arrived, the transfer has the configured confirmations (15 by default), and the chain has finalised the block that holds it, as two of your RPC endpoints attest. On BNB Smart Chain mainnet that takes about 15 to 25 seconds after the transfer’s block. Until then the payment is confirming.
Status
| Run | Transfer’s block to paid | Range | Median |
|---|---|---|---|
| 1 | 14.7 – 24.2 s | 18.0 s | |
| 2 | 14.1 – 20.0 s | 16.6 s | |
| 3 | 14.3 – 19.1 s | 16.5 s |
Measured on BNB Smart Chain mainnet with 0.45 s blocks and two public endpoints that both serve logs: paid came 30 to 50 blocks after the transfer’s block. The bar above replays one typical payment at its real speed.
A transfer is never reported paid on confirmations alone, nor for being deep. The finalised block is the highest one that two of your endpoints attest; one endpoint that claims a higher one is not believed about it.
When finality stalls, or the endpoints disagree about it, payments stay confirming, with all their confirmations, and do not expire. Nothing is lost while it waits, and the node status says why.
payment.confirming is sent when the full amount is on the chain; payment.paid follows only once the block is final. Ship on payment.paid or payment.overpaid, never on payment.confirming.
hmnpay only ever sees your wallet’s xpub. Funds go straight to addresses whose private keys stay in your wallet. The database holds no private keys: losing it loses the payment records, never the funds.
Deposit addresses are derived below your xpub in the standard layout, m/44'/60'/0'/0/n. Setup shows the first derived addresses so you can compare them with your wallet before you take a payment.
hmnpay learns about payments only from the JSON-RPC endpoints you configure, so it asks for at least two independent ones and compares what they say. Nothing is reported on one endpoint’s word.
Every event is a POST of JSON, signed in the Hmnpay-Signature header with HMAC-SHA256. Failed deliveries are retried for about 22 hours; you can also poll the API instead.
A static Go binary with one data directory. No database server, no Redis, no Node.js: the dashboard, the setup wizard, the hosted checkout and the API are served on one port, and all state is one SQLite database.
A fixed or customer-chosen price at /l/<slug>, which anybody can open. Or create payments from your backend over the REST API under /api/v1, with an idempotency key.
Everything an operator and a payer see is in the binary. The checkout follows the payment live and updates on its own; the dashboard follows the instance’s event log, so it updates while you watch.
Either way you end on the first-run setup page, which asks for a setup token the server prints at start, then for your account, the RPC endpoints, the xpub and your business name.
What you need
m/44'/60'/0') of a wallet you control.eth_getLogs. Setup tests each one for you.localhost is enough.git and make.git clone https://github.com/lubluniky/hmnpay.git
cd hmnpay
cp .env.example .env
docker compose up -d --build
docker compose logs hmnpay | grep -A2 'enter this setup token'
git clone https://github.com/lubluniky/hmnpay.git
cd hmnpay
corepack enable # once per machine: the pnpm version package.json pins
make build # the web interface, then ./hmnpay with it inside
HMNPAY_LISTEN=127.0.0.1:8080 ./hmnpay
Then open http://localhost:8080/setup and enter the token. With Compose the port is published on 127.0.0.1 only; read Docker Compose in production before you expose it. The commands are the README’s; the README is the authority.
Once setup is done, your backend talks to the REST API under /api/v1 with an API key, and your customers pay on the hosted checkout.
Idempotency-Key a retry gets the same payment back instead of a second one.checkout_url. The checkout shows the amount, the address and a QR code, and follows the payment live.Hmnpay-Signature header against the raw request body before you trust it.curl https://pay.example.com/api/v1/payments \
-H "Authorization: Bearer $HMNPAY_API_KEY" \
-H "Content-Type: application/json" \
-H "Idempotency-Key: order-1001" \
-d '{"amount": "49.00", "order_id": "ORD-1001", "description": "Pro plan",
"redirect_url": "https://shop.example.com/orders/1001"}'
{"id":"evt_…","type":"payment.paid","created_at":"…","data":{…payment…},"seq":1234}
The answer to the first request is the payment: its id, status (awaiting), the deposit address, amount, expires_at and the checkout_url. Deduplicate webhooks on the event id and order them by seq. A tested Node.js verifier is in the README.
The endpoints you configure are part of your trust base. This is what one faulty or malicious endpoint can do, with the others honest and reachable. It is shortened from the table in the README, which has the exceptions.
| Endpoints | Forge a payment | Revert a reported payment | Hide an incoming payment | Expire an invoice early | Confirm too early |
|---|---|---|---|---|---|
| 1 | possible | possible | possible | possible | possible |
| 2+, only one serves logs | prevented | prevented | possible, if the faulty one is the log endpoint | prevented, except through such a hidden payment | prevented |
| 2+, two or more serve logs | prevented | prevented | delayed, alerted; found late while the address is watched | prevented | prevented |
A single endpoint must be trusted completely: it can hide, invent or mis-time what it reports. With exactly two endpoints, one of them can stall payments (alerted); nothing is lost while they wait.
Not checked
hmnpay has not had an independent third-party security audit.
What it is not
Checked, by the project itself
That reduces risk; it does not remove it.