hmnpay Beta

Self-hosted · non-custodial · open source

Paid means final.

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.

Coin
USDT (BEP-20) on BNB Smart Chain. Other networks and USDC are planned, not available.
Keys
Stay in your wallet. Never give hmnpay a private key or a seed phrase: it refuses them.
Runs as
One static Go binary with the web interface inside, or a Docker image. One instance serves one merchant.
Paid when
The chain has finalised the transfer’s block: about 15 to 25 seconds on mainnet, typically 17.
Tells you
By signed webhook, retried for about 22 hours. Or poll the API.
Licence
GPL-3.0-or-later, with additional terms.
/pay/<payment id>hosted checkout
The hosted checkout on a phone, as a payer sees it: Northwind Digital, Pro plan, annual, 149.00 USDT on BNB Smart Chain, the deposit address with a copy button, an Open in wallet button, and the status Watching for your payment.
Pl. 00The checkout on a phone. A screenshot of the real interface.

01Seventeen seconds, typically.

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

Three measurements against real third-party USDT transfers, on the same scale
RunTransfer’s block to paidRangeMedian
114.7 – 24.2 s18.0 s
214.1 – 20.0 s16.6 s
314.3 – 19.1 s16.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.

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.

It fails closed

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.

Ship on one event

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.

02What it does

Your keys stay in your wallet

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.

One address per order

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.

Two endpoints, cross-checked

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.

Signed webhooks

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.

One binary, one directory

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.

Payment links, without code

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.

03What the payer sees, what you see

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.

/pay/<payment id>checkout · the payer
The hosted checkout a customer sees: amount, QR code and deposit address, waiting for the payment.
Pl. 01The hosted checkout: amount, QR code and deposit address, waiting for the payment. Amounts are shown exactly as the API states them.
/pay/<payment id>checkout · paid
The hosted checkout on a phone once the payment is paid: Payment complete, Northwind Digital has received your payment, with the amount paid, the time, the order and the transaction hash.
Pl. 01The same checkout once the payment is paid. The transaction hash is the payer’s proof of payment.
/dashboard · the operator
The dashboard overview: volume, payments that need attention, recent payments.
Pl. 02The dashboard overview: volume, payments that need attention, recent payments. Payment links, webhooks, API keys and the node status live beside it.
/dashboard · the operator
Two cards of the dashboard overview. Needs attention: an order with late funds and three payments whose webhook is being retried. Outcomes of the last 30 days: 17 payments created, 7 paid, 3 in progress, 3 expired, 4 needing attention.
Pl. 02Two cards of the dashboard overview, at their real size: the payments that need attention, and how the last 30 days’ payments ended.

04Quick start

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

Wallet
Your wallet’s xpub: the extended public key of an account (m/44'/60'/0') of a wallet you control.
Endpoints
At least two independent BNB Smart Chain RPC endpoints, at least two of which serve eth_getLogs. Setup tests each one for you.
Address
For production, a domain with TLS in front of hmnpay. For trying it out, localhost is enough.
To run it
Docker with Compose, or to build it from source Go 1.26+, Node.js 22 with pnpm 12, git and make.
With Docker Compose
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'
From source
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.

05Integrate it with your shop

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.

  1. Create an API key in the dashboard. The secret is shown once; keep it on your server.
  2. Create a payment when the customer checks out. With the same Idempotency-Key a retry gets the same payment back instead of a second one.
  3. Send the customer to checkout_url. The checkout shows the amount, the address and a QR code, and follows the payment live.
  4. Fulfil the order on the webhook. Verify the Hmnpay-Signature header against the raw request body before you trust it.
Create a payment
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"}'
The webhook you ship on
{"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.

06What it trusts, and where it stops

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.

EndpointsForge a paymentRevert a reported paymentHide an incoming paymentExpire an invoice earlyConfirm too early
1possiblepossiblepossiblepossiblepossible
2+, only one serves logspreventedpreventedpossible, if the faulty one is the log endpointprevented, except through such a hidden paymentprevented
2+, two or more serve logspreventedpreventeddelayed, alerted; found late while the address is watchedpreventedprevented

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

  • Not a hosted service, and not an exchange.
  • It does no currency conversion or refunds on your behalf.
  • It holds no keys, and one instance serves one merchant.
  • What can still take back a payment reported as paid is a reorganisation that replaces a finalised block: a failure of the chain’s consensus.

Checked, by the project itself

  • Six rounds of adversarial review, run by the project itself — not independent.
  • Fuzzing of the parsers and of the chain watcher’s checkpoint.
  • Randomised models of lying and failing endpoints, reorganisations, stalled finality, crashes and wrong clocks: 30,000 histories of each model before a release.
  • End-to-end tests of the web interface against the real binary and a local chain, on macOS and Linux.
  • The whole flow exercised on BSC mainnet with small amounts and against public RPC providers.

That reduces risk; it does not remove it.

Read the source, then run it yourself.