Minimalist, Non-Custodial Crypto Payment Infrastructure
Accept Bitcoin, Ethereum & stablecoins without ever touching private keys.
Version License pnpm Node.js CI
Quick Start • Integration • Docs • Self-Hosting • Contributing
KnotEngine is an open-source crypto payment gateway that lets you accept crypto payments without custody. Every invoice generates a unique on-chain address — funds flow directly to your wallet, never through our servers.
┌─────────────┐ ┌──────────────┐ ┌─────────────────┐
│ Customer │────▶│ Checkout UI │────▶│ Blockchain │
│ (Browser) │ │ (Port 5051) │ │ (BTC/ETH/etc) │
└─────────────┘ └──────────────┘ └────────┬────────┘
│
┌─────────────┐ ┌──────────────┐ ┌────────▼────────┐
│ Merchant │◀────│ Dashboard │◀────│ API Engine │
│ (Wallet) │ │ (Port 5052) │ │ (Port 5050) │
└─────────────┘ └──────────────┘ └─────────────────┘
You keep your keys. We handle the rest.
| Category | Feature |
|---|---|
| 🔐 Security | HD Wallet derivation (BIP44), 2FA (TOTP), HMAC-signed webhooks |
| ⚡ Real-time | Mempool detection, Socket.io push notifications, instant alerts |
| 🚥 Reliability | Dual-provider monitoring (Tatum + Alchemy) with automatic failover |
| 📊 Dashboard | Analytics, payment history, webhook logs, merchant settings |
| 🔌 Developer | Typed SDK (@qodinger/knot-sdk), full TypeScript support |
| 🏠 Self-Host | One-command deploy on any VPS with Docker Compose |
| ✉️ Email | Hybrid engine: Resend (prod) + Gmail SMTP (dev) |
| 🧹 Auto-Cleanup | 30-day TTL on notifications and webhook events |
- Node.js ≥ 20
- pnpm (
npm install -g pnpm) - Docker (for MongoDB & Redis)
git clone https://github.com/qodinger/knotengine.git
cd knotengine
pnpm installcp .env.example .env
Edit .env with your keys:
| Variable | Description |
|---|---|
DATABASE_URL |
MongoDB connection string |
TATUM_API_KEY |
Primary blockchain monitor |
ALCHEMY_API_KEY |
EVM failover provider |
INTERNAL_SECRET |
API ↔ Dashboard shared secret |
AUTH_SECRET |
NextAuth session secret |
GMAIL_USER |
Email sender (dev) |
GMAIL_APP_PASSWORD |
Gmail app password (dev) |
RESEND_API_KEY |
Email API (production) |
pnpm docker:up # Start MongoDB & Redis pnpm dev # Start all apps (API, Checkout, Dashboard)
Everything runs locally:
| Service | URL | Port |
|---|---|---|
| API Engine | http://localhost:5050 |
5050 |
| Checkout UI | http://localhost:5051 |
5051 |
| Dashboard | http://localhost:5052 |
5052 |
Stop: Press
Ctrl+Cto stop apps, thenpnpm docker:downfor infrastructure.
npm install @qodinger/knot-sdk
# or
pnpm add @qodinger/knot-sdkimport { KnotClient } from "@qodinger/knot-sdk"; const knot = new KnotClient({ apiKey: "knot_sk_your_api_key", baseUrl: "http://localhost:5050", }); const invoice = await knot.createInvoice({ amount_usd: 49.99, currency: "BTC", metadata: { orderId: "order_abc123" }, }); // Redirect customer to checkout console.log(invoice.checkout_url);
app.post("/webhooks/knot", (req, res) => { const signature = req.headers["x-knot-signature"]; const rawBody = JSON.stringify(req.body); if (!knot.verifyWebhook(rawBody, signature)) { return res.status(401).send("Invalid signature"); } const { event, invoice_id } = req.body; if (event === "invoice.confirmed") { // Fulfill order console.log(`Payment confirmed: ${invoice_id}`); } res.status(200).send("OK"); });
| Method | Description |
|---|---|
createInvoice() |
Create a new payment invoice |
listInvoices() |
List all invoices with filters |
cancelInvoice() |
Cancel a pending invoice |
resolveInvoice() |
Manually mark as paid |
getMerchant() |
Get merchant profile |
updateMerchant() |
Update merchant settings |
rotateApiKey() |
Rotate API key securely |
rotateWebhookSecret() |
Rotate webhook signing secret |
sendTestWebhook() |
Test webhook endpoint |
getAssetConfig() |
Get supported currencies |
getMerchantStats() |
Get merchant analytics |
| Resource | Description |
|---|---|
| API Reference | All endpoints, schemas, examples |
| Integration Guide | Step-by-step payment flow |
| SDK README | Full SDK API reference |
| Contributing | Dev setup & PR guidelines |
| Changelog | Version history |
Deploy on any VPS with one command:
curl -fsSL https://raw.githubusercontent.com/qodinger/knotengine/main/scripts/install.sh | bash| Resource | Minimum | Recommended |
|---|---|---|
| CPU | 1 vCPU | 2 vCPU |
| RAM | 1 GB | 2 GB |
| Disk | 10 GB | 20 GB |
| OS | Ubuntu 24.04 / Debian 12 | Alpine Linux |
git clone https://github.com/qodinger/knotengine.git cd knotengine cp .env.production.example .env # fill in your secrets docker compose up -d --build
| Service | Port | Notes |
|---|---|---|
| API | 5050 | Core engine + WebSocket |
| Dashboard | 5052 | Merchant console |
| Checkout | 5051 | Customer payment page |
| MongoDB | 27017 | Internal only |
| Redis | 6379 | Internal only |
docker compose logs -f api # View logs docker compose restart dashboard # Restart service git pull && docker compose up -d --build # Update docker compose down # Stop all
knotengine/
├── apps/
│ ├── api/ # Fastify payment engine (5050)
│ ├── checkout/ # Next.js customer UI (5051)
│ └── dashboard/ # Next.js merchant console (5052)
├── packages/
│ ├── crypto/ # BIP32/BIP44 HD wallet derivation
│ ├── database/ # Mongoose models + TTL cleanup
│ ├── types/ # Shared TypeScript definitions
│ └── sdk/ # @qodinger/knot-sdk
├── docs/ # API reference & guides
├── scripts/ # Deploy & utility scripts
└── .github/ # CI/CD workflows
We welcome contributions! Please follow Conventional Commits:
git checkout -b feat/lightning-network # ... make changes ... git commit -m "feat(api): add Lightning Network support" git push origin feat/lightning-network
Open a PR to main. CI runs lint, tests, and Docker build automatically.
AGPL-3.0 — Free to use, modify, and self-host.