neopay-sdk (v1.0.3)

Stateless & Self-Hosted Multi-Crypto Payment SDK for Node.js / TypeScript

neopay-sdk is an open-source, database-independent, and cron-free TypeScript SDK designed for self-hosted cryptocurrency payment processing. It derives payment addresses directly from HD Wallet extended keys (XPUB, ZPUB, TPUB, DGUB, Monero Subaddress), converts fiat amounts into live crypto values using real-time exchange rates, and performs pure on-chain balance verification—without relying on third-party payment processors.

📌 Key Features

• ⚡ Stateless & Zero-Storage: No internal database connections or schemas required. Order indices, amounts, and configurations are passed parametrically.
• 🕒 Cron-Free Pure Execution: No background worker threads or timers. Provides pure synchronous/asynchronous methods (createPaymentRequest and verifyPaymentStatus) that integrate seamlessly into your existing API or queue architecture.
• 🔒 Self-Hosted HD Wallet Derivation: Direct address generation from master public keys. No private keys are ever required or stored on your servers.
• 🌐 Mainnet & Testnet Support: Switch between live production networks and test networks (network: 'testnet') with a single configuration flag.
• 🛡️ Financial Security Guarantee: Default payment tolerance is 0% (Strict 100% full amount required). Prevents unexpected underpayment losses unless explicitly configured by the merchant.
• 🔌 Pluggable Dependency Injection: Built-in fallbacks for exchange rates (CoinGecko / Binance) and balance checking (Mempool, Litecoinspace, Blockcypher, Dogechain, TronGrid, Monero Daemon); fully overrideable per-coin via customPriceProviders and customBalanceFetchers.
• 🛰️ Proxy & Custom Fetch Support: Route all HTTP requests through SOCKS5/HTTP proxies (proxyUrl) or supply a customFetch handler.

🚀 Supported Cryptocurrencies

| Coin | Symbol | Address Type | Master Keys | Default Balance Source | | :--- | :--- | :--- | :--- | :--- | | Bitcoin | BTC | Native SegWit (bc1q... / tb1q...) | XPUB, ZPUB, TPUB, VPUB | Mempool.space API | | Litecoin | LTC | Native SegWit (ltc1q... / tltc1q...) | XPUB, ZPUB, LTPUB, TPUB | Litecoinspace.org & Blockcypher API | | TRON USDT | USDT_TRON / USDT | TRC-20 Contract (T...) | TRON XPUB | TronGrid RPC API (Mainnet & Nile) | | Dogecoin | DOGE / DOGECOIN | P2PKH (D... / n...) | XPUB, DGUB, ZPUB, TPUB | Blockcypher ➡️ Dogechain ➡️ SoChain | | Monero | XMR | Subaddress (8... / 9...) | Primary Address + View Key | Monero Daemon RPC Nodes |

📦 Installation

Install via npm:

npm install neopay-sdk

Install via yarn:

yarn add neopay-sdk

Install via pnpm:

pnpm add neopay-sdk

💡 Quick Start Guide

1. Configure Client (src/config/NeoPayConfig.ts)

import { NeoPayEngine } from 'neopay-sdk';

export const neopay = new NeoPayEngine({
  keys: {
    BTC: { xpub: process.env.BTC_XPUB },
    USDT_TRON: { xpub: process.env.TRON_XPUB, apiKey: process.env.TRONGRID_API_KEY },
    LTC: { xpub: process.env.LTC_XPUB },
    DOGE: { xpub: process.env.DOGE_XPUB },
    XMR: { primaryAddress: process.env.XMR_ADDRESS, privateViewKey: process.env.XMR_VIEW_KEY },
  },
  options: {
    network: 'mainnet',               // 'mainnet' (default) or 'testnet'
    defaultExpirationMinutes: 60,      // Optional order timeout
    defaultTolerancePercentage: 0,     // Optional underpayment margin (0% default = strict 100%)
  },
});

2. Generate Payment Request

const paymentRequest = await neopay.createPaymentRequest({
  coin: 'BTC',
  index: 42,           // Order derivation index
  fiatAmount: 15000,   // Order amount in fiat
  fiatCurrency: 'TRY', // Currency symbol ('TRY', 'USD', 'EUR', etc.)
});

console.log(paymentRequest);
/*
Output:
{
  address: "bc1qzerztyq69g5kf9fu444s52dqq0p4c4xq5x6elw",
  cryptoType: "BTC",
  expectedCryptoAmount: 0.00491803,
  exchangeRate: 3050000,
  fiatAmount: 15000,
  fiatCurrency: "TRY",
  explorerUrl: "https://mempool.space/address/bc1qzerztyq69g5kf9fu444s52dqq0p4c4xq5x6elw",
  derivationIndex: 42
}
*/

3. Verify Payment Status

const statusResult = await neopay.verifyPaymentStatus({
  coin: 'BTC',
  address: paymentRequest.address,
  expectedCryptoAmount: paymentRequest.expectedCryptoAmount,
  createdAt: new Date(),   // Optional: required only if expiration check is enabled
  expirationMinutes: 60,  // Optional
  tolerancePercentage: 1,  // Optional (allows 1% underpayment margin)
});

console.log(statusResult);
/*
Output:
{
  status: "PAID",          // 'PENDING' | 'PAID' | 'PARTIALLY_PAID' | 'EXPIRED'
  currentBalance: 0.005,
  paidAmount: 0.005,
  isPaid: true
}
*/

🔌 Custom Dependency Injections

Custom Price Provider

Override exchange rate fetching globally or per-coin using your own cache or oracle service:

const neopay = new NeoPayEngine({
  keys: { ... },
  options: {
    customPriceProviders: {
      BTC: async (coin, fiatCurrency) => {
        // e.g. Fetch rate from local Redis cache or private exchange service
        return 3050000;
      },
    },
  },
});

Custom Balance Fetcher

Query on-chain balances directly from your own self-hosted Full Node RPC:

const neopay = new NeoPayEngine({
  keys: { ... },
  options: {
    customBalanceFetchers: {
      BTC: async (coin, address) => {
        // e.g. Query your Bitcoin Core node RPC
        return 0.005;
      },
    },
  },
});

🛠 Running the Interactive Demo

Try the built-in demo script:

npm run demo

📄 License

Distributed under the MIT License. See LICENSE for more information.