dero-pay
Overview

DeroPay Overview

DeroPay is a full payment processing SDK for DERO — invoices, payment monitoring, webhooks, escrow, and a merchant dashboard. Think "Stripe for DERO" but self-hosted and privacy-preserving.

No actively maintained payment processor exists for current DERO (HE/Stargate). DeroPay is the first.

Features

  • Invoice Engine — Create invoices with unique integrated addresses, track payments, manage lifecycle
  • Payment Monitor — Polls the DERO wallet for incoming transactions, tracks confirmations
  • Webhook Dispatcher — HMAC-signed HTTP POST notifications on payment state changes
  • Pluggable Storage — In-memory (dev) and SQLite (production) backends, or bring your own
  • x402 Payment Guard — Protect API routes with HTTP 402 Payment Required; clients pay DERO and retry with a signed receipt
  • Autonomous Agent Payer — dero-pay/agent settles x402 challenges under a deny-by-default spend policy, so AI agents can pay for APIs and MCP tools without a facilitator
  • Escrow System — On-chain smart contract with full escrow lifecycle (deposit, release, refund, dispute, arbitration), with a PREMINT keeper that keeps checkout latency off the hot path
  • React Components — Drop-in <PayWithDero>, <InvoiceView>, <PaymentStatus> components
  • Next.js Integration — Ready-made API route handlers and middleware
  • XSWD Client — Browser-side wallet connection for "pay from wallet" UX
  • Self-Hosted Dashboard — Admin UI for invoice management, payment history, wallet status

How It Works

Invoice States

created → pending → confirming → completed
                  ↘ expired
                  ↘ partial (underpaid, still waiting)
StateDescription
createdInvoice generated, not yet displayed to customer
pendingAwaiting payment, timer running
confirmingTransaction detected, waiting for confirmations (default: 3)
completedFully paid and confirmed
expiredPayment window closed (default TTL: 900s / 15 min)
partialSome DERO received but less than required amount

Architecture

dero-pay/
├── core/        # Types, payment ID generation, pricing utilities
├── rpc/         # Wallet & Daemon RPC clients (HTTP JSON-RPC)
├── monitor/     # Payment polling engine with confirmation tracking
├── webhook/     # HMAC-signed webhook dispatcher with retry
├── store/       # Pluggable storage (memory, SQLite)
├── server/      # Invoice engine orchestrator
├── client/      # Browser XSWD client + payment session
├── react/       # React components (Provider, PayWithDero, InvoiceView)
├── next/        # Next.js API handlers + middleware
├── x402/        # Framework-agnostic HTTP 402 primitives + guard
├── agent/       # Autonomous agent-side payer (spend policy, paying-fetch, MCP)
├── escrow/      # On-chain escrow contract wrapper + lifecycle manager
├── router/      # Payment router contract wrapper + manager
├── gateway/     # Standalone gateway server building blocks
└── bridge/      # Shared bridge utilities

Package Exports

Import PathDescription
dero-payCore types, payment ID generation, pricing utilities (deroToAtomic, formatDero)
dero-pay/rpcWallet and Daemon RPC clients
dero-pay/serverInvoice engine, storage, monitor, webhooks
dero-pay/clientBrowser-side XSWD payment client
dero-pay/reactReact components and provider
dero-pay/nextNext.js API route handlers and middleware
dero-pay/x402Framework-agnostic x402 primitives (withX402, build402Response) + dero-pay/x402/{types,server,client,next}
dero-pay/agentAutonomous agent-side payer — spend policy, paying-fetch, MCP paid-tool guards
dero-pay/escrowEscrow contract wrapper and lifecycle manager
dero-pay/routerPayment router contract wrapper and manager
dero-pay/gatewayHTTP client for external platforms to talk to a gateway
dero-pay/bridgeOutbound-only daemon for durable, at-least-once payment webhooks

Every subpath is published dual-format — an ESM build for import and a CommonJS build for require — so CommonJS backends (e.g. a Medusa plugin) can consume the SDK directly.

Next Steps

Merchant DashboardQuick Start