DEV Community: Neil Yan

Building an AI Visibility Scanner: Hybrid AI Analysis Architecture

Neil Yan — Tue, 16 Jun 2026 08:46:30 +0000

Building an AI Visibility Scanner: Hybrid AI Analysis Architecture

If you've been following the AI space, you've likely noticed the shift: users are no longer just "Googling it." They're asking ChatGPT, Perplexity, Claude, and Gemini directly. This changes everything about how content gets discovered — and it's a problem most site owners haven't even realized they have.

Traditional SEO metrics (backlinks, domain authority, keyword stuffing) have only a ~0.3 correlation with AI citation rates. A site that ranks #1 on Google can be completely invisible to ChatGPT. This is the gap Generative Engine Optimization (GEO) fills.

In this article, I'll walk through what GEO actually means from a technical perspective, then dive into a real implementation — using GetCiteFlow, the AI visibility scanner I built — with code, architecture decisions, and lessons learned.

1. Understanding GEO: The Technical Layer AI Search Cares About

When an AI like ChatGPT or Claude answers a user query, it doesn't "rank" pages the way Google does. Instead, it looks for signals that make content easy to cite, summarize, and attribute.

Through our analysis of thousands of sites, we found six dimensions that matter most:

Dimension	What It Measures
AI Visibility	Can the AI find and parse your content?
FAQ Coverage	Do you have structured FAQ schema?
Entity Clarity	Does the page clearly define what it is?
Authority	Is there original research or named authors?
Content Structure	Are lists, tables, and headings being used?
Summary Optimization	Is there a clear summary for AI to extract?

The key insight: AI search engines don't read pages the way humans do. They look for machine-readable signals — structured data, entity definitions, llms.txt files — not just keyword density.

2. Architecture Overview: Hybrid Analysis with AI + Deterministic Checks

GetCiteFlow uses a hybrid analysis architecture. Instead of relying solely on an LLM to evaluate a site (which can hallucinate), we combine two independent analysis layers:

User enters URL
      |
      v
  [1] Scrape site → extract signals (HTML parsing)
      |
      v
  [2] Format signals → send to AI (Gemini/OpenAI/Deepseek)
      |
      v
  [3] AI returns structured JSON (score, breakdown, suggestions)
      |
      v
  [4] Merge with deterministic checks (lists, meta length, etc.)
      |
      v
  [5] Cache result + render report

Here's the core orchestration function from lib/analyze.ts:

export async function analyzeSite(url: string): Promise<Record<string, unknown>> {
  const cacheKey = `report:${url}`;
  const cached = cacheGet<Record<string, unknown>>(cacheKey);
  if (cached) return { ...cached, cached: true };

  // Deduplicate concurrent requests to the same URL
  if (pendingCache.has(cacheKey)) {
    return pendingCache.get(cacheKey)!;
  }

  const analyze = async () => {
    const activeProvider = getProvider();
    const fn = providerFns[activeProvider];
    const report = await fn(url);

    // Merge AI results with deterministic signal detection
    const siteData = await getSiteData(url);
    const deterministicMissing = getDeterministicMissing(siteData);
    const aiMissing = (report.missing as string[]) || [];
    const mergedMissing = [...new Set([...aiMissing, ...deterministicMissing])];

    const result = { ...report, missing: mergedMissing };
    cacheSet(cacheKey, result, CACHE_TTL_MS);
    return result;
  };

  const promise = analyze();
  pendingCache.set(cacheKey, promise);
  return promise;
}

Why hybrid? LLMs are great at qualitative judgment but bad at counting. An AI might miss that a site has no <ul> tags, but a simple regex check won't. By combining both, we get the best of both worlds.

3. The Scraper: Extracting Deterministic Signals

The scraper (lib/scrape.ts) is a pure-HTTP fetcher — no headless browser. It fetches the HTML, parses structured signals using regex, and checks for critical static files.

async function extractFromHtml(html: string) {
  const titleMatch = /<title[^>]*>([^<]*)<\/title>/i.exec(html);
  const hasOpenGraph =
    /<meta[^>]+property=["']og:(title|description|image)["']/i.test(html);
  const hasFaqSchema = /* parses JSON-LD <script> blocks */;
  const hasOrderedLists = /<ol[\s>]/i.test(html);
  const avgParagraphLength = /* calculates from <p> tags */;
  const hasSummarySection =
    /\b(key takeaways?|executive summary|tldr|tl;dr)\b/i.test(bodyLower);

  return { title, hasOpenGraph, hasFaqSchema, hasOrderedLists, ... };
}

We also check three critical files in parallel:

const [hasRobotsTxt, hasSitemap, hasLlmstxt] = await Promise.all([
  checkStaticFile(resolvedOrigin, "/robots.txt"),
  checkStaticFile(resolvedOrigin, "/sitemap.xml"),
  checkStaticFile(resolvedOrigin, "/llms.txt"),
]);

The llms.txt check is particularly important — it's a relatively new standard (proposed by the llmstxt community) that creates a machine-readable site index specifically for AI crawlers. Sites with an llms.txt file get significantly better AI citation rates.

4. The AI Layer: Structured Output from Gemini

For the AI analysis, we use Google Gemini's native structured output support. This is critical — without it, parsing free-form JSON from an LLM is fragile and error-prone.

async function analyzeWithGemini(url: string) {
  const siteData = formatSiteData(url, await getSiteData(url));
  const response = await getAiClient().models.generateContent({
    model: "gemini-3-flash-preview",
    contents: ANALYZE_PROMPT(url, siteData),
    config: {
      temperature: 0,           // deterministic output
      responseMimeType: "application/json",
      responseSchema: {
        type: Type.OBJECT,
        required: ["score", "breakdown", "missing", "suggestions", "summary"],
        properties: {
          score: { type: Type.NUMBER },
          breakdown: {
            type: Type.OBJECT,
            properties: {
              aiVisibility: { type: Type.NUMBER },
              faqCoverage: { type: Type.NUMBER },
              entityClarity: { type: Type.NUMBER },
              authority: { type: Type.NUMBER },
              contentStructure: { type: Type.NUMBER },
              summaryOptimization: { type: Type.NUMBER },
            },
          },
          missing: { type: Type.ARRAY, items: { type: Type.STRING } },
          suggestions: { type: Type.ARRAY, items: { type: Type.STRING } },
          summary: { type: Type.STRING },
        },
      },
    },
  });

  return JSON.parse(response.text || "{}");
}

Key design decisions here:

temperature: 0 — We want deterministic, reproducible results. No creativity needed.
responseSchema — This tells Gemini exactly what JSON shape to return. Without this, you get parsing errors, missing fields, and inconsistent types.
We feed the actual scraped signals into the prompt. The AI doesn't guess — it evaluates what we found.

Here's the prompt template (lib/ai-provider.ts):

export const ANALYZE_PROMPT = (url: string, siteData?: string) =>
  `Analyze the AI visibility (GEO) of the website: ${url}.

${siteData ? `Here are the actual signals detected from the website:\n${siteData}\n\nBase your analysis on these real signals rather than guessing.` : ''}
Evaluate these factors specifically using the signals above:
- contentStructure (0-100): How well the content is structured for AI parsing...
- summaryOptimization (0-100): How optimized the page is for AI summarization...

Return ONLY a JSON object with these exact keys:
{ "score": <number 0-100>, "breakdown": { ... }, "missing": [...], "suggestions": [...], "summary": "..." }`;

We also support OpenAI and Deepseek as fallback providers, switched via the AI_PROVIDER_DEFAULT environment variable. The architecture makes adding new providers trivial — just implement the same function signature.

5. Caching: In-Memory with Deduplication

Since every analysis hits an LLM API (costly) and scrapes a site (slow), caching is essential. We use a simple in-memory Map with 1-hour TTL:

interface CacheEntry<T> {
  data: T;
  expiresAt: number;
}

const store = new Map<string, CacheEntry<unknown>>();
const CLEAN_INTERVAL = 60_000;
let lastClean = 0;

function clean() {
  const now = Date.now();
  if (now - lastClean < CLEAN_INTERVAL) return;
  lastClean = now;
  for (const [key, entry] of store) {
    if (now > entry.expiresAt) store.delete(key);
  }
}

export function cacheGet<T>(key: string): T | null {
  clean();
  const entry = store.get(key);
  if (!entry || Date.now() > entry.expiresAt) return null;
  return entry.data as T;
}

export function cacheSet<T>(key: string, data: T, ttlMs: number): void {
  store.set(key, { data, expiresAt: Date.now() + ttlMs });
}

We also use a pending cache (pendingCache in analyze.ts) to deduplicate concurrent requests for the same URL — so if two users submit the same URL simultaneously, only one analysis runs:

const pendingCache = new Map<string, Promise<Record<string, unknown>>>();
// ...
if (pendingCache.has(cacheKey)) {
  return pendingCache.get(cacheKey)!;  // wait for in-flight request
}

For production, you'd want Redis or another distributed cache. This in-memory approach works well for single-instance deployments (like Vercel's serverless functions with concurrency).

6. Rate Limiting: Graceful Degradation

We use Upstash Redis for rate limiting with a sliding window. The critical design choice: fail open when Redis is unavailable, not fail closed.

let ratelimit: Ratelimit | null = null;

try {
  const redis = Redis.fromEnv();
  ratelimit = new Ratelimit({
    redis,
    limiter: Ratelimit.slidingWindow(max, "1 h"),
    analytics: true,
    prefix: "@citeflow/ratelimit",
  });
} catch {
  // Redis init failed — fall through, rate limiting is degraded
}

export async function checkRateLimit(ip: string): Promise<RateLimitResult> {
  if (!ratelimit) {
    return { success: true };  // allow request when Redis is down
  }
  try {
    const { success } = await ratelimit.limit(ip);
    return success
      ? { success: true }
      : { success: false, reason: 'rate_limited' };
  } catch {
    return { success: false, reason: 'redis_unavailable' };
  }
}

Why fail open? Because the free-tier tool is meant to be accessible. Blocking all users because Redis is having a bad day is worse than temporarily bypassing rate limits for a few requests.

7. The Report Page: SSR with Edge OG Images

The report page at app/report/[domain]/page.tsx uses Server-Side Rendering (SSR) with maxDuration: 60 (Vercel's timeout for Pro plans). This is necessary because:

We need to scrape the target site (network I/O)
We need to call Gemini/OpenAI (API latency)
We need the full data before rendering

export const maxDuration = 60;

export default async function ReportPage({ params }) {
  const { domain } = await params;
  const ip = getClientIp(headers());

  const result = await getReport(domain, ip);

  if (!result.ok) {
    // Render error states: rate_limited, timeout, failed
    return <ErrorState reason={result.reason} />;
  }

  return <ReportView data={result.data} />;
}

We also generate dynamic OG images per report using the Edge runtime:

// app/api/og/route.tsx — runs on Vercel Edge
export const runtime = 'edge';
export const dynamic = 'force-dynamic';

This means every report page has a unique social preview showing the domain and score — critical for shareability on X/Twitter and LinkedIn.

8. Lessons Learned

8.1 AI Hallucination Is Real — Always Ground It

The first version of our AI analysis didn't feed real scraped signals into the prompt. The AI made up plausible-sounding but completely wrong assessments. Always provide ground-truth data in the prompt and instruct the model to base its analysis on that data.

8.2 Structured Output > JSON Prompting

Before Gemini supported responseSchema, we used "output valid JSON only" in the prompt. It worked ~70% of the time. With structured output, it's ~99.9%. Use native structured output whenever your provider supports it.

8.3 Cache Aggressively, Deduplicate Concurrently

LLM API calls are expensive ($0.15–$3.00 per million tokens) and slow (2–5 seconds). An in-memory cache with request deduplication eliminated redundant calls entirely. For Vercel deployments with multiple concurrent invocations, the pendingCache pattern is essential.

8.4 Deterministic Checks Catch What AI Misses

The AI often missed simple things like "no lists on the page" or "meta description is too short." These are trivial to detect with regex but easy for an LLM to gloss over. The hybrid approach catches both.

8.5 GEO Is Still Nascent — Standards Are Evolving

llms.txt is a proposed standard, not a W3C spec. FAQ Schema behavior in AI search changes monthly. Building this kind of tool means constantly iterating as the ecosystem evolves. We treat our signal detection as a pluggable layer that can be updated independently of the AI analysis.

The full source of this architecture is running at GetCiteFlow — feel free to test your own site and see how the analysis works end-to-end. The tech stack: Next.js 15 (App Router, SSR, Edge Functions), React 19 with Tailwind CSS 4 + shadcn/ui, Google Gemini for AI analysis (OpenAI/Deepseek fallbacks), Upstash Redis for rate limiting, deployed on Vercel.

GEO is still the early days — much like SEO was in 1998. The sites that optimize for AI search today will have a compound advantage as AI assistants become the primary interface for information discovery.

If you're building something in this space or have questions about the architecture, I'd love to hear from you. Leave a comment below or reach out on X/Twitter.

Built by GetCiteFlow — AI visibility analysis for the AI-search era.

Build Your Own Crypto Payment Gateway with XPayLabs (xpay): Architecture, SDKs, and Production Deployment

Neil Yan — Sun, 07 Jun 2026 16:25:25 +0000

Build Your Own Crypto Payment Gateway with XPayLabs (xpay): Architecture, SDKs, and Production Deployment

Accepting crypto payments doesn't have to mean paying 1% to BitPay or trusting Coinbase Commerce with your private keys. With modern tools, you can self-host a production-grade gateway that supports USDT, USDC, DAI, and BUSD across TRON, Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Base, and SUI — with zero transaction fees.

This article breaks down the architecture, SDK integration patterns, and production deployment of XPayLabs (often shortened to xpay), a self-hosted gateway with open-source SDKs and tools.

Architecture Overview

┌─────────────────────────────────────────┐
│           Docker Compose Stack          │
│  ┌────────┐  ┌────────┐  ┌──────────┐  │
│  │ MySQL  │  │ Redis  │  │ Gateway  │  │
│  │        │  │        │  │ (Java 17 │  │
│  │        │  │        │  │ Spring)  │  │
│  └────────┘  └────────┘  └────┬─────┘  │
│                                │        │
│  ┌─────────────────────────────┘        │
│  │  ┌──────────────┐ ┌──────────────┐  │
│  │  │  Scanner:    │ │  Scanner:    │  │
│  │  │  TRON        │ │  EVM Chains  │  │
│  │  └──────────────┘ └──────────────┘  │
│  │  ┌──────────────┐ ┌──────────────┐  │
│  │  │  Scanner:    │ │  Webhook     │  │
│  │  │  SUI         │ │  Dispatcher  │  │
│  │  └──────────────┘ └──────────────┘  │
└─────────────────────────────────────────┘

The gateway runs as multiple services in a Docker Compose stack:

Gateway API (Spring Boot 3.4+): REST API for order creation, status queries, and balance checks
Blockchain Scanners: Concurrent per-chain workers that monitor mempool and blocks
Webhook Dispatcher: Queue-backed delivery with exponential backoff
MySQL: Persistent storage for orders, addresses, and transactions
Redis: Caching, job queues, and nonce deduplication

1. HD Wallet Key Management

The gateway uses BIP-39 + BIP-44 hierarchical deterministic wallet derivation. One master seed generates every deposit address.

How It Works

// Conceptual example — HD wallet derivation
import { generateMnemonic, mnemonicToSeedSync } from 'bip39';
import { HDKey } from 'micro-bip32';

// Step 1: Generate or load a mnemonic (12 words)
const mnemonic = generateMnemonic(); // or load from env

// Step 2: Derive master key from seed
const seed = mnemonicToSeedSync(mnemonic);
const masterKey = HDKey.fromMasterSeed(seed);

// Step 3: Derive child key for a specific chain + index
// Path: m / 44' / coin_type' / 0' / 0 / address_index
// TRON coin_type = 195, EVM = 60, SUI = 9006
const childKey = masterKey.derive(`m/44'/195'/0'/0/${addressIndex}`);
const depositAddress = childKey.publicKey; // → TXYZ1234...

Security Model

The master seed is injected via XPAY_MASTER_SEED environment variable — never stored in the database
Only derivation paths (integers) are stored in MySQL
If the database is compromised, an attacker sees which addresses belong to you but cannot derive private keys
The seed should be generated offline and backed up physically

2. Multi-Chain Transaction Detection

Each blockchain scanner runs as an independent worker with chain-specific logic:

// ChainAdapter interface — implemented per blockchain
interface ChainAdapter {
  generateAddress(derivationPath: string): string;
  scanTransactions(
    addresses: string[],
    fromBlock: number,
    toBlock: number
  ): Promise<DetectedTransaction[]>;
  getConfirmationCount(txHash: string): Promise<number>;
  getLatestBlock(): Promise<number>;
}

TRON (TRC20) Scanner

TRON accounts for the majority of stablecoin volume globally. The scanner:

Polls TRON Grid API or a local node every 3 seconds
Uses getTransactionsToThis for tracked addresses
Filters by USDT/USDC contract address
Matches amounts with pending invoices (with small tolerance for gas deductions)

// TRON scanner pseudocode
async function scanTron(pendingAddresses: string[]) {
  const txs = await tronGrid.getTransactionsToThis(pendingAddresses, {
    onlyConfirmed: false, // mempool detection
    minTimestamp: Date.now() - 120_000 // last 2 minutes
  });

  for (const tx of txs) {
    if (tx.contractType === 'Transfer' &&
        tx.contractData.contractAddress === USDT_CONTRACT) {
      await processDetection('tron', tx);
    }
  }
}

EVM Scanner (Ethereum, BSC, Polygon, Arbitrum, etc.)

For EVM chains, we use eth_getLogs with the Transfer event signature:

event Transfer(address indexed from, address indexed to, uint256 value);

// EVM scanner pseudocode
async function scanEvm(chain: string, rpc: string, pendingAddresses: string[]) {
  const latestBlock = await getBlockNumber(rpc);
  const fromBlock = latestBlock - 200; // look back 200 blocks

  const logs = await ethGetLogs(rpc, {
    fromBlock: toHex(fromBlock),
    toBlock: toHex(latestBlock),
    address: USDT_CONTRACTS[chain],
    topics: [TRANSFER_EVENT_SIG, null, pendingAddresses.map(toPaddedHex)]
  });

  for (const log of logs) {
    const tx = decodeTransferLog(log);
    await processDetection(chain, tx);
  }
}

3. SDK Integration Patterns

XPayLabs (xpay) provides first-party SDKs in Node.js/TypeScript and Java with identical API surfaces.

Node.js SDK Installation

npm install @xpaylabs/node-sdk

import { XPay } from '@xpaylabs/node-sdk';

const xpay = new XPay({
  apiKey: process.env.XPAY_API_KEY,
  apiSecret: process.env.XPAY_API_SECRET,
  baseUrl: 'https://payments.example.com'
});

Create a Collection (Receive Payment)

const collection = await xpay.createCollection({
  amount: '100.00',
  symbol: 'USDT',
  chain: 'tron',
  orderId: 'order_20260601_001',
});


// collection.address: deposit address for customer
// collection.orderId: unique gateway order ID
// collection.expireAt: ISO timestamp after which the order expires

Create a Payout (Send Payment)

const payout = await xpay.createPayout({
  amount: '50.00',
  symbol: 'USDT',
  chain: 'tron',
  receiveAddress: 'TXYZ...recipient...',
  orderId: 'payout_20260601_001'
});

Webhook Verification

import express from 'express';

const app = express();
app.post('/webhooks/xpay', express.raw({ type: 'application/json' }), (req, res) => {
  try {
    const event = xpay.parseWebhook(
      req.body,
      req.headers['x-webhook-signature'] as string
    );

    switch (event.type) {
      case 'ORDER_SUCCESS':
        console.log(`Payment received: ${event.data.orderId}`);
        // Fulfill order, update database, send email
        break;
      case 'ORDER_FAILED':
        console.log(`Payment failed: ${event.data.orderId}`);
        // Notify customer, release inventory
        break;
    }

    res.status(200).json({ received: true });
  } catch (err) {
    res.status(401).json({ error: 'Invalid signature' });
  }
});

Java/Spring Boot SDK

<dependency>
    <groupId>io.xpay</groupId>
    <artifactId>xpay-java-sdk</artifactId>
    <version>0.1.0</version>
</dependency>

@Configuration
public class PaymentConfig {

    @Bean
    public XPay xPay(@Value("${xpay.api-key}") String apiKey,
                     @Value("${xpay.api-secret}") String apiSecret,
                     @Value("${xpay.base-url}") String baseUrl) {
        return new XPay(XPayConfig.builder()
            .apiKey(apiKey)
            .apiSecret(apiSecret)
            .baseUrl(baseUrl)
            .build());
    }
}

@Service
public class PaymentService {

    private final XPay xpay;

    public PaymentService(XPay xpay) {
        this.xpay = xpay;
    }

    public String createPayment(String orderId, BigDecimal amount) {
        CreateCollectionRequest request = CreateCollectionRequest.builder()
            .amount(amount.toPlainString())
            .symbol("USDT")
            .chain("tron")
            .orderId(orderId)
            .build();

        ApiResponse<CollectionData> response = xpay.createCollection(request);
        return response.getData().getAddress();
    }
}

4. HMAC-SHA256 Request Signing (Under the Hood)

One of the most important security features is how API requests are signed. Instead of sending a bearer token, every request includes a cryptographic signature:

function generateSignature(
  params: Record<string, string>,
  data: Record<string, string>,
  secret: string
): string {
  // 1. Serialize data as data={key=value,...} sorted by key
  const dataStr = 'data={' + Object.keys(data)
    .sort()
    .map(k => `${k}=${data[k]}`)
    .join(',') + '}';

  // 2. Append nonce and timestamp
  const allParams = { ...params, data: dataStr };
  const sorted = Object.keys(allParams)
    .sort()
    .map(k => `${k}=${allParams[k]}`)
    .join('&');

  // 3. HMAC-SHA256
  return crypto
    .createHmac('sha256', secret)
    .update(sorted)
    .digest('hex');
}

// Usage
const data = { amount: '100.00', symbol: 'USDT', chain: 'tron' };
const params = { timestamp: Date.now().toString(), nonce: crypto.randomUUID() };
};

const sign = generateSignature(params, apiSecret);

// POST /v1/order/createCollection
// Body: { sign, timestamp: params.timestamp, nonce: params.nonce, data: {...} }

The gateway validates:

Signature: Recomputes HMAC on the server side
Timestamp: Rejects if more than 30 seconds old
Nonce: Rejects if already seen (Redis-backed deduplication)

5. Docker Compose Production Deployment

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: xpay_gateway
    volumes:
      - mysql_data:/var/lib/mysql
    healthcheck:
      test: ["CMD", "mysqladmin", "ping", "-h", "localhost"]

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    healthcheck:
      test: ["CMD", "redis-cli", "ping"]

  gateway:
    image: ghcr.io/xpaylabs/gateway:latest
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/xpay_gateway
      SPRING_DATASOURCE_USERNAME: xpay
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
      SPRING_REDIS_PASSWORD: ${REDIS_PASSWORD}
      XPAY_MASTER_SEED: ${XPAY_MASTER_SEED}
      XPAY_WEBHOOK_SECRET: ${XPAY_WEBHOOK_SECRET}
      XPAY_API_KEY: ${XPAY_API_KEY}
      XPAY_API_SECRET: ${XPAY_API_SECRET}
      XPAY_CHAINS: tron,eth,bsc,polygon,arbitrum,base
    depends_on:
      mysql: { condition: service_healthy }
      redis: { condition: service_healthy }

volumes:
  mysql_data:
  redis_data:

Environment Variables

Variable	Description
`XPAY_MASTER_SEED`	BIP-39 mnemonic (generate offline!)
`XPAY_API_KEY`	Public API identifier
`XPAY_API_SECRET`	HMAC signing secret
`XPAY_WEBHOOK_SECRET`	HMAC secret for webhook payloads
`XPAY_CHAINS`	Comma-separated chain names to activate

Startup

# One command to deploy
docker compose up -d

# Verify
curl http://localhost:8080/v1/symbol/supportSymbols

Cost Comparison

	BitPay	Coinbase Commerce	Self-Hosted
Setup fee	$0–$300	$0	$0 (Docker)
Per-transaction	0.5–1%	1%	$0 (gas only)
Monthly (100k volume)	$1,000+	$1,000+	~$30–50 server
Key custody	Theirs	Theirs	Yours
White-label	Premium	No	Yes
Annual savings vs BitPay	—	$360–$3,600	$11,500+

Summary

Self-hosting a crypto payment gateway is more accessible than most developers think. The key components are:

HD wallet derivation for deterministic, scalable address generation
Per-chain scanners with chain-specific detection logic
HMAC-signed API with SDKs in Node.js and Java
Docker Compose deployment for operational simplicity

xpay SDKs (Node.js and Java), checkout UI, and documentation are open-source under MIT at github.com/yan253319066/XPayLabs. The core gateway engine is source-available under the XPay Enterprise License.

SDK packages:

npm (Node.js)
Maven Central (Java)

If you're processing $5,000+/month in crypto, the self-hosted approach will save you significant fees — and you'll never have to trust a third party with your keys.

Building a Self-Hosted Crypto Payment Gateway: Architecture, Security, and SDK Design

Neil Yan — Mon, 01 Jun 2026 15:26:54 +0000

# Building a Self-Hosted Crypto Payment Gateway: Architecture, Security, and SDK Design

If you've ever integrated a crypto payment gateway like BitPay or Coinbase Commerce, you know the drill: redirect the customer, wait for block confirmations, listen for webhooks. It works. But there's a cost — not just the 0.5–1% per transaction, but the loss of control over your keys, your uptime, and your customer experience.

I spent the last few months building [XPayLabs](https://github.com/yan253319066/XPayLabs), a self-hosted alternative with open-source SDKs and tools. In this article, I want to walk through the three technical pillars that make it work: **non-custodial key management**, **multi-chain transaction detection**, and **API/SDK design for developer experience**.

---

## 1. Non-Custodial Key Management with HD Wallets

The first question anyone asks about a self-hosted payment gateway is: "Where are the private keys?"

The answer matters because it determines who can touch your funds. In a custodial model, the gateway provider generates and holds the keys. You trust them not to lose them, freeze them, or go out of business with your money.

In a non-custodial model, the keys never leave your infrastructure. Here's how we approached it.

### BIP-44 HD Wallet Derivation

Rather than generating a new random wallet for every invoice (imagine managing millions of private keys), we use **hierarchical deterministic (HD) wallet derivation** per BIP-44. A single master seed generates an unlimited tree of child addresses:

m / purpose' / coin_type' / account' / change / address_index


For a TRON USDT deposit address, the derivation path looks like:

m / 44' / 195' / 0' / 0 / 0


The coin_type index follows SLIP-44: `195` for TRON, `60` for Ethereum and EVM chains, `9006` for SUI. This means you back up **one seed phrase**, and every address ever generated is recoverable.

### Key Generation Flow

When the gateway starts up, it:

1. Reads the master seed from the environment variable (`XPAY_MASTER_SEED`)
2. Derives a master private key using BIP-39 + BIP-32
3. On each invoice creation, derives the next unused address from the chain-specific path
4. Stores the derivation index (not the private key) in the database
5. Monitors all derived addresses for incoming transactions

The critical security property is that the gateway only stores derivation paths in the database — never the master seed, never private keys in plaintext. If the database is breached, an attacker learns which addresses belong to you but cannot derive the corresponding private keys.

### Why This Matters

Most hosted gateways generate addresses server-side and manage keys themselves. With HD wallets, you get:

- **Deterministic recovery**: Lose your server? Restore from seed + blockchain history.
- **Key separation**: Each invoice gets its own address. Customers cannot see each other's on-chain activity.
- **Single backup**: One seed phrase, not one per address.

---

## 2. Multi-Chain Transaction Detection

A crypto payment gateway's core job is to detect when a customer sends funds. Simple in theory, complex in practice when you support 8+ blockchains with different block times, finality guarantees, and API semantics.

### Detection Strategies by Chain

We use a hybrid approach: **mempool-level detection where possible, block polling everywhere else**.

| Chain | Detection Method | Typical Latency | Confirmations Needed |
|-------|-----------------|-----------------|---------------------|
| TRON (TRC20) | TRON Grid API polling | 1–6 seconds | 1–2 |
| Ethereum (ERC20) | JSON-RPC `eth_getLogs` | 12–15 seconds | 12–30 |
| BNB Chain (BEP20) | JSON-RPC polling | 3–5 seconds | 15–30 |
| Polygon | JSON-RPC polling | 2–4 seconds | 30–100 |
| Arbitrum | JSON-RPC polling | 1–3 seconds | 10–20 |
| SUI | SUI RPC polling | 2–5 seconds | 5–10 |

### The Scanner Architecture

Each chain runs as an independent scanner that polls its node/RPC provider at a configurable interval. The scanner:

1. **Fetches the latest block** (or ledger version for SUI)
2. **Extracts all `Transfer` events** involving tracked addresses
3. **Matches events to pending invoices** by address + amount
4. **Updates invoice status** and enqueues a webhook delivery

typescript
// Simplified scanner loop — each chain runs one of these
async function scannerLoop(chain: ChainAdapter, store: Store) {
let lastBlock = await chain.getLatestBlock();

setInterval(async () => {
const currentBlock = await chain.getLatestBlock();
if (currentBlock <= lastBlock) return;

const pendingAddresses = await store.getPendingAddresses(chain.name);
const txs = await chain.scanTransactions(pendingAddresses, lastBlock + 1, currentBlock);

for (const tx of txs) {
  await store.markDetected(tx);
}

lastBlock = currentBlock;

}, chain.pollIntervalMs);
}


### Confirmation Strategy

Different assets need different confirmation counts. The risk model is straightforward:

- **Small payments (<$100)**: 1 confirmation is usually safe. The cost of a reorg attack exceeds the payment value.
- **Large payments ($100–$10,000)**: Wait for chain-specific recommended confirmations (e.g., 12 for Ethereum, 30 for BSC).
- **Whale-sized (>$10,000)**: Consider additional safeguards like waiting for "safe" confirmation counts or requiring multiple confirmations across separate monitoring nodes.

We expose this as a configurable `minConfirmations` parameter per chain so merchants can dial the risk/reward balance themselves.

---

## 3. API & SDK Design: Stripe-Inspired, Crypto-Native

The third pillar is developer experience. If the API is painful, nobody will use it, no matter how secure the key management is.

### Request Signing with HMAC-SHA256

Instead of simple bearer tokens, every API request is signed using an HMAC-SHA256 envelope:

json
{
"sign": "a1b2c3d4e5f6...",
"timestamp": 1717000000,
"nonce": "7c9e5a24-1d4f-4b3a-8e7d-3f2c6b1a9e5d",
"data": { ... }
}


The signature is computed over the `data` object serialized as `data={key=value,...}` with `nonce` and `timestamp` appended via `&`. For example: `data={amount=100.00,chain=tron,symbol=USDT}&nonce=...&timestamp=...`. This is deterministic across all SDKs. The server validates:

- **Signature match**: Proves the request came from someone holding the API secret.
- **Timestamp within 30 seconds**: Prevents replay attacks.
- **Nonce uniqueness**: Ensures each request is executed at most once.

### SDK Design Patterns

We maintain first-party SDKs in **Node.js/TypeScript** and **Java/Spring Boot**, with identical API surfaces. Here's the philosophy:

**Node.js SDK:**

typescript
import { XPay } from '@xpaylabs/node-sdk';

const xpay = new XPay({
apiKey: process.env.XPAY_API_KEY,
apiSecret: process.env.XPAY_API_SECRET,
baseUrl: 'https://payments.example.com'
});

// Create a collection (receive funds)
const order = await xpay.createCollection({
amount: '100.00',
symbol: 'USDT',
chain: 'tron',
orderId: 'order_12345'
});

// Verify incoming webhook
const event = xpay.parseWebhook(payload, signature);


**Java SDK:**

java
XPay xpay = new XPay(XPayConfig.builder()
.apiKey(apiKey)
.apiSecret(apiSecret)
.baseUrl(gatewayUrl)
.build());

CreateCollectionRequest request = CreateCollectionRequest.builder()
.amount("100.00")
.symbol("USDT")
.chain("tron")
.orderId("order_12345")
.build();

ApiResponse response = xpay.createCollection(request);
CollectionData result = response.getData();


Both SDKs handle:
- Request signing and nonce generation
- Response parsing with typed models
- Webhook signature verification
- Error handling with structured exceptions

### Webhook System

Webhooks are the backbone of payment notification. Our system uses:

1. **HMAC-SHA256 signing**: Each webhook payload includes an `X-Webhook-Signature` header.
2. **Queue-backed delivery**: Failed deliveries retry with exponential backoff (1s → 5s → 30s → 5min → 30min → 2h → 6h → 24h).
3. **Idempotency keys**: Each event includes an `id` for deduplication.

typescript
// Webhook verification in Node.js
app.post('/webhooks/xpay', express.raw({type: 'application/json'}), (req, res) => {
const event = xpay.parseWebhook(req.body, req.headers['x-webhook-signature']);

switch (event.type) {
case 'ORDER_SUCCESS':
await fulfillOrder(event.data.orderId);
break;
case 'ORDER_FAILED':
await notifyCustomer(event.data.orderId);
break;
}

res.status(200).json({ received: true });
});


---

## Putting It Together: The Cost Case

Here's what the economics look like for a merchant doing $100,000/month in crypto volume:

| Item | BitPay | Coinbase Commerce | Self-Hosted (XPayLabs) |
|------|--------|-------------------|----------------------|
| Transaction fees | $1,000/mo | $1,000/mo | $0 |
| Monthly platform fee | $30–300/mo | $0 | $0 |
| Server + RPC costs | $0 | $0 | ~$30–50/mo |
| **Annual cost** | **$12,360–15,600** | **$12,000** | **~$360–600** |

The trade-off is operational responsibility: you manage the server, the database backups, the security patches. But for any merchant doing meaningful volume, the savings are orders of magnitude — and you never give up custody of your keys.

---

## Final Thoughts

Building a self-hosted crypto payment gateway is a rewarding architectural challenge. The three pillars I covered — HD wallet key management, multi-chain transaction detection, and clean API/SDK design — form the foundation of a system that can rival hosted solutions in reliability while exceeding them in cost efficiency and sovereignty.

If you're evaluating whether to build or adopt a self-hosted solution, start with these questions:

- **Can you generate and protect a seed phrase offline?** If yes, the key management problem is solved.
- **Which chains does your user base actually use?** 80%+ of stablecoin volume is on TRON and a handful of EVM chains — you probably don't need all 20.
- **Do you have the DevOps bandwidth?** Docker Compose makes deployment straightforward, but you still need to monitor, back up, and patch.

The SDKs (Node.js and Java), checkout UI, and documentation are open-source under MIT at [github.com/yan253319066/XPayLabs](https://github.com/yan253319066/XPayLabs). The core gateway engine is source-available under the XPay Enterprise License — deploy it via Docker to keep full control of your keys.

Find the SDKs on [npm](https://www.npmjs.com/package/@xpaylabs/node-sdk) and [Maven Central](https://central.sonatype.com/artifact/io.xpay/xpay-java-sdk).

Integrating Crypto Payments into Your Web Application: A Step-by-Step Guide

Neil Yan — Fri, 29 May 2026 14:28:16 +0000

Integrating Crypto Payments into Your Web Application: A Step-by-Step Guide

Adding cryptocurrency payment support to a web application has historically meant either integrating with a third-party gateway (and paying their fees) or building blockchain transaction handling from scratch (a massive engineering effort). There's a middle path that's increasingly viable: self-hosted payment gateways with clean REST APIs.

In this tutorial, I'll walk through integrating crypto payments into a Vue.js e-commerce application backed by a self-hosted payment gateway. The same patterns apply to React, Angular, or any other framework — the API layer is framework-agnostic.

Prerequisites

A running self-hosted payment gateway instance (I'll show the Docker setup briefly)
Node.js 18+ for the demo backend
Basic familiarity with Vue.js or any frontend framework
curl or Postman for testing API calls

Step 1: Deploy the Gateway (Quick Setup)

I'm going to use Docker Compose because it's the fastest way to get a production-grade gateway running. Create a docker-compose.yml:

version: '3.8'

services:
  mysql:
    image: mysql:8.0
    environment:
      MYSQL_ROOT_PASSWORD: ${DB_ROOT_PASSWORD}
      MYSQL_DATABASE: payment_gateway
      MYSQL_USER: gateway
      MYSQL_PASSWORD: ${DB_PASSWORD}
    volumes:
      - mysql_data:/var/lib/mysql
    restart: always

  redis:
    image: redis:7-alpine
    command: redis-server --requirepass ${REDIS_PASSWORD}
    volumes:
      - redis_data:/data
    restart: always

  gateway:
    image: ghcr.io/xpaylabs/gateway:latest
    ports:
      - "8080:8080"
    environment:
      SPRING_DATASOURCE_URL: jdbc:mysql://mysql:3306/payment_gateway
      SPRING_DATASOURCE_USERNAME: gateway
      SPRING_DATASOURCE_PASSWORD: ${DB_PASSWORD}
      SPRING_REDIS_HOST: redis
      SPRING_REDIS_PASSWORD: ${REDIS_PASSWORD}
      XPAY_MASTER_SEED: ${XPAY_MASTER_SEED}
      XPAY_WEBHOOK_SECRET: ${WEBHOOK_SECRET}
      XPAY_API_KEY: ${API_KEY}
      XPAY_CHAINS: tron,eth,bsc,polygon
    depends_on:
      - mysql
      - redis
    restart: always

volumes:
  mysql_data:
  redis_data:

Create a .env file:

DB_ROOT_PASSWORD=changeme_root_password
DB_PASSWORD=changeme_db_password
REDIS_PASSWORD=changeme_redis_password
XPAY_MASTER_SEED="abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon abandon about"
XPAY_WEBHOOK_SECRET=whsec_your_webhook_secret
API_KEY=xpay_api_key_for_internal_use

Security warning: The seed phrase above is the BIP-39 test vector. NEVER use it on mainnet. Generate a real seed offline for production use.

Then deploy:

docker compose up -d

After about 30 seconds, the gateway should be available at http://localhost:8080.

Step 2: Understand the API Model

The gateway follows a Stripe-inspired API design. The core resource is an invoice:

interface Invoice {
  id: string;              // Unique invoice ID
  amount: string;          // Amount in fiat (e.g., "100.00")
  currency: string;        // Fiat currency code (e.g., "USD")
  chain: string;           // Blockchain (e.g., "tron", "eth", "bsc")
  settlementAsset: string; // Stablecoin (e.g., "USDT", "USDC")
  depositAddress: string;  // Address where funds should be sent
  status: InvoiceStatus;   // "pending" | "confirmed" | "failed" | "expired"
  checkoutUrl: string;     // Hosted checkout page URL
  metadata: Record<string, string>; // Your custom data
  createdAt: string;
  expiresAt: string;
}

The lifecycle is straightforward:

Your backend creates an invoice via the API
The gateway generates a unique deposit address and returns a checkout URL
Your customer pays by sending crypto to that address
The gateway detects the transaction and updates the invoice status
A webhook is fired to your backend on status changes

Step 3: Backend Integration (Node.js/Express)

Let's build a simple Express backend that creates invoices and handles webhooks.

First, install dependencies:

npm install express @xpaylabs/node-sdk dotenv

Create the server:

import express from 'express';
import crypto from 'crypto';
import { XPayClient } from '@xpaylabs/node-sdk';

const app = express();
app.use(express.json());

const xpay = new XPayClient({
  apiKey: process.env.XPAY_API_KEY,
  gatewayUrl: process.env.GATEWAY_URL || 'http://localhost:8080'
});

// Create an invoice for an order
app.post('/api/create-payment', async (req, res) => {
  try {
    const { orderId, amount, currency, chain } = req.body;

    const invoice = await xpay.createInvoice({
      amount: amount.toString(),
      currency: currency || 'USD',
      chain: chain || 'tron',
      settlementAsset: 'USDT',
      description: `Order #${orderId}`,
      metadata: { orderId },
      successUrl: `${process.env.APP_URL}/order/success/${orderId}`,
      cancelUrl: `${process.env.APP_URL}/order/${orderId}`,
      notifyUrl: `${process.env.APP_URL}/api/webhooks/xpay`
    });

    res.json({
      invoiceId: invoice.id,
      checkoutUrl: invoice.checkoutUrl,
      amount: invoice.amount,
      depositAddress: invoice.depositAddress
    });
  } catch (error) {
    console.error('Failed to create invoice:', error);
    res.status(500).json({ error: 'Payment creation failed' });
  }
});

// Webhook handler for payment status updates
app.post('/api/webhooks/xpay', express.raw({ type: 'application/json' }), (req, res) => {
  const signature = req.headers['x-webhook-signature'];
  const expectedSig = crypto
    .createHmac('sha256', process.env.XPAY_WEBHOOK_SECRET)
    .update(req.body)
    .digest('hex');

  if (signature !== expectedSig) {
    console.warn('Invalid webhook signature detected');
    return res.status(401).send('Invalid signature');
  }

  const event = JSON.parse(req.body.toString());

  switch (event.type) {
    case 'invoice.confirmed': {
      const { orderId } = event.data.metadata;
      console.log(`Order ${orderId} payment confirmed`);
      // Release the order, send download links, update database
      break;
    }
    case 'invoice.failed': {
      console.log(`Invoice ${event.data.id} payment failed`);
      break;
    }
    case 'invoice.expired': {
      console.log(`Invoice ${event.data.id} expired unpaid`);
      break;
    }
  }

  res.status(200).send('OK');
});

app.listen(3001, () => {
  console.log('Backend running on port 3001');
});

Key points about this implementation:

The webhook endpoint uses express.raw() because we need the raw body for HMAC verification. If you use express.json(), the body is consumed before we can verify the signature.
Webhook verification is mandatory in production. Without it, anyone who discovers your endpoint URL could forge payment confirmations.
The gateway implements exponential backoff for webhook delivery, so even if your handler is down temporarily, you won't miss events.

Step 4: Frontend Integration (Vue 3)

Now let's build the customer-facing payment experience. I'll show a Vue 3 component, but the logic is identical in React or any other framework.

<template>
  <div class="payment-page">
    <div v-if="loading" class="loading">
      Creating payment invoice...
    </div>

    <div v-else-if="invoice" class="payment-details">
      <div class="payment-header">
        <h2>Complete Your Payment</h2>
        <div class="amount-display">
          <span class="fiat-amount">{{ invoice.amount }} {{ invoice.currency }}</span>
          <span class="crypto-amount">{{ displayAmount }} USDT on {{ displayChain }}</span>
        </div>
      </div>

      <div class="qr-section">
        <img :src="qrCodeUrl" alt="Payment QR Code" />
        <p class="instruction">Scan with your wallet app to pay</p>
      </div>

      <div class="address-section">
        <label>Send to this address:</label>
        <div class="address-row">
          <code>{{ invoice.depositAddress }}</code>
          <button @click="copyAddress" class="btn-copy">
            {{ copied ? 'Copied!' : 'Copy' }}
          </button>
        </div>
      </div>

      <div class="status-section">
        <div v-if="status === 'pending'" class="status-pending">
          <div class="spinner"></div>
          <span>Waiting for payment...</span>
        </div>
        <div v-else-if="status === 'confirmed'" class="status-confirmed">
          ✓ Payment Confirmed!
        </div>
        <div v-else-if="status === 'expired'" class="status-expired">
          ✗ Invoice Expired
          <button @click="createNewInvoice" class="btn-retry">Try Again</button>
        </div>
      </div>
    </div>
  </div>
</template>

<script setup>
import { ref, onMounted, onUnmounted } from 'vue';

const props = defineProps({
  orderId: String,
  amount: Number,
  chain: { type: String, default: 'tron' }
});

const API_BASE = import.meta.env.VITE_API_BASE || 'http://localhost:3001';

const loading = ref(true);
const invoice = ref(null);
const status = ref('pending');
const copied = ref(false);
const qrCodeUrl = ref('');
const displayAmount = ref('');
const displayChain = ref('');

let pollingInterval = null;

const chainDisplayNames = {
  tron: 'TRON (TRC20)',
  eth: 'Ethereum (ERC20)',
  bsc: 'BNB Chain (BEP20)',
  polygon: 'Polygon'
};

async function createInvoice() {
  loading.value = true;
  try {
    const res = await fetch(`${API_BASE}/api/create-payment`, {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        orderId: props.orderId,
        amount: props.amount,
        chain: props.chain
      })
    });
    const data = await res.json();

    invoice.value = data;
    displayAmount.value = data.amount;
    displayChain.value = chainDisplayNames[props.chain] || props.chain;
    qrCodeUrl.value = `${API_BASE}/qr?address=${data.depositAddress}&amount=${data.amount}`;
    loading.value = false;

    startPolling(data.invoiceId);
  } catch (err) {
    console.error('Failed to create invoice:', err);
    loading.value = false;
  }
}

async function checkStatus(invoiceId) {
  try {
    const res = await fetch(`${API_BASE}/api/invoice/${invoiceId}`);
    const data = await res.json();
    status.value = data.status;

    if (data.status === 'confirmed' || data.status === 'expired') {
      stopPolling();
    }
  } catch (err) {
    console.error('Status check failed:', err);
  }
}

function startPolling(invoiceId) {
  pollingInterval = setInterval(() => checkStatus(invoiceId), 2000);
}

function stopPolling() {
  if (pollingInterval) {
    clearInterval(pollingInterval);
    pollingInterval = null;
  }
}

async function copyAddress() {
  await navigator.clipboard.writeText(invoice.value.depositAddress);
  copied.value = true;
  setTimeout(() => { copied.value = false; }, 2000);
}

onMounted(() => createInvoice());
onUnmounted(() => stopPolling());
</script>

The polling interval of 2 seconds is aggressive but appropriate — TRON transactions are detectable in 1-6 seconds. For Ethereum-based chains, you might increase this to 5-10 seconds. Some gateways also support WebSocket-based status updates, which is more efficient for higher volumes.

Step 5: The Checkout Flow

Putting it all together, here's what the complete payment flow looks like:

Customer clicks "Pay with Crypto"
        │
        ▼
Your backend creates an invoice
        │
        ▼
Customer sees checkout page with:
  - Amount in USDT/USDC
  - Deposit address
  - QR code
        │
        ▼
Customer sends crypto from their wallet
        │
        ▼
Gateway detects transaction (1-60s depending on chain)
        │
        ▼
Gateway fires webhook → your backend
        │
        ▼
Your backend releases the order
        │
        ▼
Checkout page shows "Payment Confirmed"
        │
        ▼
Redirect to success page

The entire flow is synchronous from the customer's perspective — they scan the QR code, confirm the transaction in their wallet, and within seconds see the confirmation on screen.

Step 6: Multi-Currency Pricing with Oracle Support

A common requirement is showing prices in fiat but settling in stablecoins. The gateway handles the conversion internally, but for transparency you might want to show the exchange rate:

// Estimate the USDT equivalent
async function getEstimatedAmount(fiatAmount, fiatCurrency, chain) {
  const response = await fetch(
    `${GATEWAY_URL}/api/v1/estimate?amount=${fiatAmount}&from=${fiatCurrency}&chain=${chain}&asset=USDT`
  );
  const data = await response.json();
  return data.estimatedAmount; // e.g., "100.50" USDT
}

The gateway uses aggregated price feeds to determine the conversion rate, applying a small buffer to cover price volatility during the transaction window.

Step 7: Handling Expired Invoices

Invoices have a configurable expiry time (default is 30 minutes). If the customer doesn't pay within that window, the invoice expires. Your webhook handler receives an invoice.expired event.

The deposit address can be reused for a new invoice, but each invoice should generate a fresh address for privacy and tracking purposes. HD wallet derivation makes this trivial — the next unused address index is always deterministic.

Production Considerations

Rate Limiting

When the gateway polls for transactions, it's making RPC calls to blockchain nodes. Rate limit your invoice creation endpoints to prevent abuse. A malicious actor could otherwise cause rapid address consumption:

import rateLimit from 'express-rate-limit';

const invoiceLimiter = rateLimit({
  windowMs: 60 * 1000, // 1 minute
  max: 10,              // 10 invoices per minute per IP
  message: { error: 'Too many payment requests. Please try again.' }
});

app.post('/api/create-payment', invoiceLimiter, async (req, res) => {
  // ...
});

Webhook Idempotency

Network issues can cause duplicate webhook deliveries. Make your webhook handler idempotent:

// Track processed webhook IDs to avoid double-processing
const processedEvents = new Set();

app.post('/api/webhooks/xpay', express.raw({ type: 'application/json' }), (req, res) => {
  const event = JSON.parse(req.body.toString());

  if (processedEvents.has(event.id)) {
    return res.status(200).send('Already processed');
  }
  processedEvents.add(event.id);

  // Process event...
});

For production, use a database or Redis to track processed event IDs rather than an in-memory Set.

Webhook Retry Backoff

The gateway retries failed webhook deliveries on this schedule:

Attempt	Delay
1st retry	10 seconds
2nd retry	30 seconds
3rd retry	60 seconds
4th retry	5 minutes
5th retry	30 minutes
6th retry	2 hours
7th retry	6 hours
8th retry	24 hours

After 8 failed attempts, the event is marked as permanently failed and logged for manual review. This means you have a full day to fix a downed webhook handler before events are truly lost.

Testing Your Integration

Most gateways provide a testnet mode. Set the gateway to testnet, and use testnet tokens:

# For TRON testnet (Shasta or Nile)
XPAY_TRON_NETWORK=shasta

# For Ethereum testnet (Sepolia)
XPAY_ETH_NETWORK=sepolia

Testnet faucets provide free tokens. Walk through the full flow:

Create an invoice via the API
Open the checkout URL in a browser
Send testnet tokens to the deposit address
Verify the webhook fires
Confirm the order is released in your system

Conclusion

Integrating crypto payments into a web application doesn't require deep blockchain expertise. A self-hosted gateway with a clean REST API abstracts away the chain-specific complexity — HD wallet derivation, transaction scanning, confirmation handling, and webhook delivery — behind familiar HTTP endpoints.

The integration pattern is the same one you'd use for Stripe or PayPal: create an invoice server-side, handle a webhook to confirm payment. The difference is that your gateway runs on your infrastructure, your keys never leave your control, and there are no per-transaction fees beyond blockchain gas costs.

For the frontend, a polling-based checkout page with QR code display provides a smooth user experience. Add real-time status updates, address copying, and clear error states, and your customers won't notice they're interacting with a self-hosted infrastructure rather than Stripe.

If you're building a Vue, React, or vanilla JS application and want to add crypto payments without the overhead of direct blockchain integration, this pattern gives you the best of both worlds: developer productivity and full financial sovereignty.

为什么 Web2 商户越来越需要加密货币支付？

Neil Yan — Tue, 09 Sep 2025 02:37:36 +0000

为什么 Web2 商户越来越需要加密货币支付？

过去几年，跨境电商、独立游戏、虚拟商品的规模在快速增长。
与此同时，一个趋势正在加速：越来越多的海外用户，更愿意使用 USDT 等加密货币进行支付。

但是，Web2 商户在收款时，往往会遇到很多问题。

❌ 传统支付渠道的痛点

PayPal 风险高
独立站卖家和跨境电商经常遭遇账户冻结，资金被长期扣留。

手续费昂贵
跨境支付多层中转，手续费普遍 3%~5%，利润被严重压缩。

覆盖范围有限
Stripe、PayPal 在东南亚、非洲、拉美等地区无法使用，用户想付钱也付不了。

到账慢
跨境结算通常需要 2~5 天，影响订单体验与商户资金周转。

✅ 为什么选择加密货币支付？

加密货币支付正在成为跨境收款的新通道：

全球化：无国界，用户只需要一个钱包即可完成支付。

低成本：USDT 转账手续费远低于传统支付方式。

快速到账：几秒到几分钟即可确认，体验接近支付宝/微信。

抗封锁：不依赖传统银行网络，资金更安全自主。

🚀 我们的解决方案：XPay

我们的团队研发了 XPay 加密货币支付系统，目标是让 Web2 商户可以用最少的成本接入 Web3 支付。

XPay 的核心能力：

🛠 快速接入：提供标准 API，适配电商、游戏、SaaS 等场景

⚡ 实时到账：用户支付后，系统秒级监听并回调通知商户

🔄 自动归集：资金自动转入主钱包，降低人工操作风险

🌍 多链支持：目前支持 TRC20 USDT，后续扩展 ETH、BSC、BTC

👨‍💻 适用人群

独立站 / 跨境电商卖家

游戏开发团队

SaaS / 工具类项目方

需要数字货币收款的创业团队

无论是个人项目还是商业级应用，XPay 都能帮助商户轻松搭建加密支付通道。

🔗 立即体验

👉 官网：www.x-pay.fun

如果你正在寻找一套简单、快速、安全的加密货币支付解决方案，欢迎联系我们，立即试用 XPay。
我们也在开放首批商户入驻，欢迎合作。

🚀 从 0 构建一个通用加密货币支付系统：XPay 项目实践分享

Neil Yan — Sun, 20 Jul 2025 16:10:43 +0000

🚀 从 0 构建一个通用加密货币支付系统：XPay 项目实践分享
支持 USDT、ETH、TRX，秒级到账、自动归集、回调通知，专为 Web2 游戏、电商、SaaS 项目设计。

👋 背景：为什么我要做这个项目？
作为一个 Web3 领域的独立开发者，我发现很多 Web2 项目（比如小游戏、电商独立站、小工具型 SaaS）有这样的痛点：

想支持 USDT / ETH 等加密支付，但没有成熟方案

使用第三方平台收款不稳定、限制多、手续高

Web3 支付方案复杂，动不动就需要合约、钱包、前端集成

于是，我花了几周时间开发了 XPay，一个轻量级的加密货币支付系统。

🎯 XPay 是什么？
XPay 是一个针对 Web2 场景设计的加密支付解决方案，主要功能包括：

✅ 支持的支付币种/网络
TRC20-USDT

ERC20-USDT

BEP20-USDT

支持任意链上代币拓展（后续支持 BTC）

✅ 商户能力
📬 提供唯一地址收款（基于地址池或 HD 钱包）

⚙️ 实时监听到账事件（基于 TronGrid、Web3j）

🧾 提供 webhook 回调（POST 订单状态）

🔄 自动归集到账户地址

🖥️ 后台可视化（开发中）

项目官网 👉 https://www.xpaylabs.com

🧱 技术架构
本项目采用 Spring Boot + MyBatis Plus 开发，前端为 Vue 3 + Vite，部署在 Cloudflare Pages，监听模块使用多线程支持 ETH/BSC/TRON：

监听模块：根据支付地址队列 + RPC/TronGrid 实时扫描

地址池系统：支持助记词生成 HD 地址，并批量入库

归集机制：通过 SDK 自动签名并广播归集交易

回调通知：成功入账后通过 webhook 通知商户系统

技术栈如下：

模块技术栈
后端 Spring Boot 3.4.6、JDK 17、MyBatis Plus
前端 Vue 3、Element Plus、Vite
钱包 TronJ、Web3j、BTC hdwallet
存储 MySQL
部署 Cloudflare Pages + Docker

🔌 如何接入 XPay？
集成流程很简单（以 TRC20 为例）：

创建订单：调用后端接口，系统分配一个地址（绑定订单）

用户付款：用户扫码/复制地址发送 TRC20-USDT

监听到账：监听模块识别该地址入账

状态更新：修改订单状态为成功，并回调商户系统

自动归集：将用户地址上的资金归集至主钱包

你只需要集成 HTTP API，就能完成加密支付接入。

💡 为什么说它适合 Web2 开发者？
对大部分 Web2 商户来说，他们不想：

跑智能合约

管理复杂的钱包体系

使用陌生的钱包工具

XPay 的定位就是「Web2 友好」：

不依赖钱包前端

不需要 MetaMask

所有功能都通过 API 调用完成

支持私有部署，也可用托管服务

🧪 示例场景
🎮 小型 HTML5 游戏接入 USDT 支付

🛒 跨境电商独立站支持 USDT 结算

🧰 工具类 SaaS（如 GPT 助手）支持数字货币订阅

👨‍💻 承接代付项目，接入多商户管理后台（企业版）

🧭 项目进展和计划
已完成：

✅ 商户创建 + 地址分配

✅ USDT 到账监听（TRON / ETH）

✅ 支持自动归集 + 回调通知

✅ 网站 + 接入文档上线（docs.xpaylabs.com）

开发中：

📊 商户可视化后台（Vue3）

🧩 支持 BTC、SOL 等链接入

🛍️ Shopify / WordPress 插件（开放合作）

🆓 发布 GitHub 开源版本（计划 MIT 协议）

🤝 谁适合用？
Web2 游戏、电商、SaaS 项目想要接入 USDT 支付

不想自建监听和归集系统

想提供稳定的收款体验给海外用户

想用 Java/Vue 技术栈快速集成

📮 如何试用或合作？
欢迎你访问官网 www.xpaylabs.com

🔧 开发者对接文档正在完善中（也可联系我直接对接）

🤖 Telegram 群即将上线（欢迎内测）

📮 有项目合作或插件需求也欢迎私聊我

🧑‍💻 最后
这是一个典型的「个人独立开发者 + 商业化工具项目」，欢迎你来试用、提建议，甚至合作开源扩展。

如果你觉得这个项目有用，欢迎点赞、转发，或加我微信/Telegram 交流 😄

👨‍💻 项目地址：https://www.xpaylabs.com
📢 TG 频道/群：即将上线，欢迎留言