DEV Community: Neil Yan

AI-Ready Websites in 2026: What Actually Works

Neil Yan — Sun, 05 Jul 2026 16:39:17 +0000

AI-Ready Websites: A Practical Guide to What Actually Works in 2026

TL;DR: The race to make websites "AI-ready" has spawned a flood of new standards, file formats, and optimization techniques. But which ones actually matter? We analyzed the data across structured data, FAQ Schema, llms.txt, entity optimization, and AI crawler configurations. The results are surprisingly clear: most of the buzz is noise. Here's what actually moves the needle — and what you can safely ignore.

If you manage a website in 2026, you've probably been told you need an llms.txt file. And a robots.txt tuned for AI crawlers. And FAQ Schema on every page. And structured data, entity definitions, content summaries, and a dozen other things that "AI search engines look for."

The problem: most of this advice isn't backed by data. It's extrapolation, wishful thinking, and a fair amount of SEO tool marketing.

At GetCiteFlow, we've spent months analyzing how AI systems actually discover, parse, and cite web content. We've scanned thousands of sites, cross-referenced AI citation patterns, and dug through every public study we could find. This guide shares what we've learned — the honest version, including where the data is still thin.

The AI-Ready Stack: A Framework

Before diving into individual techniques, let's organize them into layers. Not all layers are equally important.

Layer 4: Future Bets        ← llms.txt, AI agent protocols
Layer 3: Entity Signals     ← Brand entity definitions, SameAs links
Layer 2: Structure Signals  ← FAQ Schema, HowTo Schema, semantic HTML
Layer 1: Access Signals     ← robots.txt, crawlability, content accessibility

The pattern we've observed: Layer 1 and Layer 2 consistently correlate with AI citation. Layer 3 shows promise but lacks conclusive data. Layer 4 is, as of mid-2026, largely unproven.

Let's walk through each layer with the actual data.

Layer 1: Access Signals — The Foundation

robots.txt for AI Crawlers

This is the most basic, most overlooked signal. If an AI crawler can't access your content, nothing else matters.

The major AI crawlers you need to account for:

Crawler	User-Agent Token	Purpose
GPTBot	`GPTBot`	OpenAI's web crawler
ClaudeBot / anthropic-ai	`ClaudeBot`	Anthropic's web crawler
Google-Extended	`Google-Extended`	Controls inclusion in Gemini/Vertex AI
PerplexityBot	`PerplexityBot`	Perplexity's crawler
OAI-SearchBot	`OAI-SearchBot`	OpenAI's search crawler

What the data says: This is table stakes. A site that blocks GPTBot and ClaudeBot in robots.txt cannot be cited by ChatGPT or Claude, period. Yet our scans found roughly 18% of SaaS websites block at least one major AI crawler — usually unintentionally, as part of blanket bot-blocking rules from years ago.

What to do:

Audit your robots.txt for blanket User-agent: * rules that might affect AI crawlers
Explicitly allow or disallow each major AI crawler based on your strategy
Use Google-Extended to control Gemini training without affecting Google Search indexing

This is the one thing on this list where the data is unequivocal. Get it right.

Layer 2: Structure Signals — Where the ROI Lives

FAQ Schema (JSON-LD)

FAQ Schema is the closest thing we have to a proven AI visibility lever. The KDD 2024 GEO paper (Aggarwal et al.) tested nine optimization strategies across 10,000 queries and found that adding FAQ sections — with clear question-and-answer pairs — consistently improved citation rates.

Why it works: AI systems that use RAG (Retrieval-Augmented Generation) retrieve content chunks based on semantic similarity to the user's query. A well-structured FAQ maps directly to this retrieval pattern — the question matches the user's query, and the answer provides a clean, extractable snippet.

What the data says:

KDD 2024: FAQ-style content boosted visibility by up to 40% in certain categories
Our own scans: Sites with FAQ Schema markup score 2-3x higher on AI visibility metrics than structurally similar sites without it
Independent studies consistently show structured data correlates with AI citation more strongly than traditional SEO signals like backlink count

What to do:

Add FAQ Schema (JSON-LD format) to any page that answers common questions
Make questions match natural language queries ("How does X work?" not "X mechanism")
Keep answers concise — 2-4 sentences is ideal for AI extraction

Semantic HTML

AI crawlers don't "see" your page. They parse a DOM tree and extract text. Clean, semantic HTML makes this easier.

Specifically:

Use proper heading hierarchy (h1 → h2 → h3, no skipped levels)
Wrap main content in <main>, navigation in <nav>, sidebars in <aside>
Use <article> for self-contained content pieces

What the data says: Indirect but strong. Every AI citation analysis we've run shows that pages with clean semantic structure are cited more often than visually identical pages with div-soup markup. The effect is smaller than FAQ Schema but consistent.

Layer 3: Entity Signals — The Emerging Frontier

Brand Entity Definitions

When an AI is asked "who are the leaders in [your industry]," it doesn't search for your brand name. It searches for entities — nodes in a knowledge graph that represent companies, products, people, and concepts.

Entity optimization is about making sure your brand exists as a well-defined entity that AI systems can recognize and connect.

What the data says: The case for entity optimization is strong in theory but thin on quantitative evidence. We know that:

Google's Knowledge Graph and similar systems use entity extraction extensively
KDD 2024 research identifies "cite sources" and "statistics" as high-impact signals, which are forms of entity association
Anecdotally, brands with well-maintained Wikidata entries, consistent Schema.org Organization markup, and Wikipedia mentions appear more frequently in AI answers

But we don't yet have a controlled study that isolates entity optimization as a variable and measures AI citation changes. This is where honest practitioners will say "the data is still coming in."

What to do (pragmatic approach):

Implement Organization or LocalBusiness Schema.org markup with sameAs links to Wikipedia, Wikidata, Crunchbase, LinkedIn
Ensure your brand name, description, and category are consistent across all platforms
This is low-effort, low-risk — there's no downside to doing it

Layer 4: Future Bets — Honest Talk About llms.txt

The Promise vs. The Reality

Proposed by Jeremy Howard in September 2024, llms.txt is a Markdown file placed at the root of a domain that provides a curated, human-readable index of a site's most important pages for LLM consumption. Think of it as a "sitemap for AI."

In theory, it's elegant. In practice, the data tells a different story.

What the data actually says:

Ahrefs analyzed 137,000 domains (May 2026): 97% of llms.txt files received zero requests from any bot or human
Of the 3% that were fetched, AI search/retrieval bots accounted for only 1.1% of requests
Search Engine Land tracked 10 sites before/after implementing llms.txt: 8 saw no change, 1 declined, and 2 grew — but both had concurrent PR campaigns that explained the growth
SE Ranking analyzed 300,000 domains (Nov 2025): No correlation between llms.txt presence and AI citation rates
Google has explicitly stated they do not use and do not plan to use llms.txt for search or rankings

Where llms.txt does show value:

AI coding assistants (Cursor, Claude Code, Continue) actively consume it when pointed at documentation sites
It forces content teams to articulate what matters most — the exercise itself is valuable
It's a cheap future bet: if major platforms eventually adopt it, early adopters win

Our recommendation: Implement llms.txt if you maintain developer documentation or an API reference. For general AI search visibility, spend your time on Layer 1 and Layer 2 first. The $0 cost is appealing, but the opportunity cost of prioritizing this over proven techniques is real.

What We Can't Tell You Yet

Good guides tell you what they don't know. Here are the open questions:

Does entity optimization independently drive AI citations? We suspect yes, but controlled data doesn't exist yet.
Will llms.txt become a de facto standard? Adoption is growing (8.8× year-over-year), but consumption by AI search engines has barely moved. The market will decide.
How much does content freshness matter for AI citation? Early evidence suggests AI systems prefer recent content, but the effect size and decay curve aren't well understood.

We're tracking all three and will publish updates as the data clarifies.

The Actionable Checklist

If you only have an afternoon, do these things — ranked by likely impact:

Priority	Action	Estimated Time	Evidence Strength
1	Audit `robots.txt` for AI crawler access	15 min	Strong
2	Add FAQ Schema to key pages	2-4 hours	Strong
3	Clean up HTML semantics (headings, landmarks)	2-3 hours	Moderate
4	Implement `Organization` Schema.org markup	30 min	Moderate
5	Create `llms.txt` (if you maintain docs/API ref)	1 hour	Weak
6	Add structured data for products, articles, breadcrumbs	4-6 hours	Moderate

Key Takeaways

Access is the foundation. Fix your robots.txt before anything else — blocking AI crawlers makes everything else irrelevant.
FAQ Schema is the most proven lever. KDD 2024 and independent research both point to structured Q&A content as the highest-ROI optimization for AI visibility.
Semantic HTML matters more than most people think. Clean heading hierarchy and landmark elements help AI parsers extract your content accurately.
llms.txt is cheap infrastructure, not a growth lever. Ship it if it's easy, but don't expect it to move your AI citation numbers.
Be skeptical of AI visibility advice that doesn't cite data. This space is young, and most "best practices" are extrapolation. Demand numbers.

Want to know where your site stands? Run a free scan at getciteflow.ai — it checks all of the above and gives you a prioritized action plan in under 2 minutes.

Built by GetCiteFlow — Enterprise AI Brand Service. The free scanner is just the diagnosis; we help enterprise brands build systemic AI visibility through brand entity construction, content strategy, and ongoing optimization.

XPayLabs Deployment Guide: Run Your Own Multi-Chain Crypto Payment Gateway

Neil Yan — Sat, 20 Jun 2026 07:31:24 +0000

XPayLabs Deployment Guide: Run Your Own Multi-Chain Crypto Payment Gateway

XPayLabs is a production-ready, self-hosted cryptocurrency payment gateway with multi-chain support and multi-tenant architecture. This guide walks through deploying the complete stack — from prerequisites to production go-live.

What You're Deploying

XPayLabs consists of 11 services running in Docker containers:

Service	Role	Technology
`mysql`	Persistent database	MySQL 8.0
`redis`	Cache, queue, nonce store	Redis 7 Alpine
`sui-node-service`	SUI blockchain RPC proxy	Express (Node.js)
`xpay-tron`	TRON blockchain scanner	Spring Boot 3.4 (Java 17)
`xpay-sui`	SUI blockchain scanner	Spring Boot 3.4 (Java 17)
`xpay-eth`	EVM scanner (ETH, BSC, Polygon, Avalanche)	Spring Boot 3.4 (Java 17)
`xpay-user`	User & collection order API	Spring Boot 3.4 (Java 17)
`xpay-merchant`	Merchant backend API	Spring Boot 3.4 (Java 17)
`merchant-vue`	Merchant admin dashboard	Vue 3 + Element Plus (Nginx)
`checkout`	Payment checkout page	Vue 3 + Vite 7 (Nginx)
`gateway`	Reverse proxy (single entry point)	Nginx Alpine

All Java services use the same base image (ghcr.io/yan253319066/xpay-java) — different JARs are launched via the command directive.

Prerequisites

Docker 24+ and Docker Compose v2+
A Linux server (4 GB RAM minimum, 8 GB recommended)
Domain names for the merchant dashboard and checkout page
SSL certificate (Let's Encrypt or commercial)
RPC endpoints for each blockchain you intend to support

Step 1: Clone the Deployment Repository

git clone https://github.com/yan253319066/XPayLabs-docker.git
cd XPayLabs-docker

This repository contains everything needed for deployment: docker-compose.yml, nginx configs, SQL init scripts, and the .env template.

Step 2: Configure Environment Variables

cp .env.example .env

Edit .env with your own values. Here's what each section means:

Database & Cache

MYSQL_ROOT_PASSWORD=<strong-random-password>
DB_USERNAME=root
DB_PASSWORD=<same-or-different-password>
REDIS_PASSWORD=<optional-redis-password>

MySQL is initialized automatically on first startup — the ./sql/init.sql script is mounted to the container's init directory. Redis password is optional; leave empty for no auth.

Encryption Keys (Critical)

ENCRYPTION_KEY=<exactly-32-characters>
JWT_SECRET_KEY=<random-string>
SKIP_SIGN_SECRET=<64-char-hex-secret>

ENCRYPTION_KEY: AES-256-CBC key, must be exactly 32 characters. Used by sui-node-service and xpay-sui for encrypting SUI private keys at rest.
JWT_SECRET_KEY: Used by xpay-merchant for signing JWT tokens for merchant dashboard sessions.
SKIP_SIGN_SECRET: HMAC-SHA256 secret used by the SkipSign feature for internal request signing between services.

Public Domains

XPAY_PAY_DOMAIN=https://pay.your-domain.com/checkout
XPAY_API_DOMAIN=https://api.your-domain.com

These are used by the Java services to construct callback URLs and checkout redirects. They must be publicly accessible URLs after you configure DNS.

Blockchain RPC Configuration

EVM chains (ETH, BSC, Polygon, Avalanche):

ETH_NETWORKS=ETH,ETH_SEPOLIA,BSC,BSC_TEST,POLYGON,POLYGON_AMOY,AVAX_C_CHAIN,AVAX_FUJI_TEST
RPC_ETH=https://0xrpc.io/eth,https://rpc.flashbots.net
SCAN_ETH=15

ETH_NETWORKS: Comma-separated list of active networks
RPC_*: Comma-separated RPC URLs (the scanner tries each in order for fault tolerance)
SCAN_*: Polling interval in seconds between block scans

You can use public RPC endpoints for testnets. For mainnet, consider:

Commercial RPC providers (Alchemy, Infura, QuickNode) for reliability
Running your own node for maximum sovereignty

TRON:

TRON_NETWORKS=TRON,TRON_TEST
NODE_TRON=grpc.trongrid.io:50051
SOLIDITY_TRON=grpc.trongrid.io:50052
APIKEY_TRON=<your-trongrid-api-key>

TRON uses gRPC (not JSON-RPC). The scanner connects to a full node and a solidity node. An API key from trongrid.io is required for production use.

SUI:

SUI does not require direct RPC configuration in .env. The xpay-sui scanner communicates with sui-node-service (an Express-based RPC proxy running in the same Docker network) via http://sui-node-service:3001.

Port Mappings

HOST_PORT_GATEWAY_HTTP=180
HOST_PORT_MYSQL=13306
HOST_PORT_REDIS=16379
HOST_PORT_XPAY_USER=18077
HOST_PORT_XPAY_MERCHANT=18078
HOST_PORT_XPAY_ETH=18076
HOST_PORT_XPAY_TRON=18075
HOST_PORT_XPAY_SUI=18074
HOST_PORT_SUI_NODE=13001

Only port 180 (the Nginx gateway) needs to be exposed to the internet. The other ports are for internal communication and optional direct access.

Step 3: Launch the Stack

docker compose up -d

Docker Compose starts services in dependency order:

mysql and redis start first
Blockchain scanners (xpay-tron, xpay-eth, xpay-sui + sui-node-service) start after MySQL is healthy
xpay-user starts after scanners
xpay-merchant starts after xpay-user
Frontend services (merchant-vue, checkout) start after their backends
gateway (Nginx) starts last

Verify the Deployment

# Check all services are running
docker compose ps

# Check logs for each service
docker compose logs xpay-user
docker compose logs xpay-eth

# Test the API
curl http://localhost:180/api/symbol/supportSymbols

Step 4: Configure DNS and SSL

DNS Records

Point your domains to the server's public IP:

merchant.your-domain.com A <server-ip>
pay.your-domain.com       A <server-ip>
api.your-domain.com       A <server-ip>

The Nginx gateway routes traffic based on path prefixes:

/checkout/* → checkout service (payment page)
/api/* → xpay-user API
/prod-api/* → xpay-merchant API
/* → merchant-vue dashboard (default)

SSL with Let's Encrypt

Obtain certificates:

docker run -it --rm -p 80:80 -v "$(pwd)/certs:/etc/letsencrypt" certbot/certbot certonly --standalone -d merchant.your-domain.com -d pay.your-domain.com

Copy the certificates:

cp certs/live/merchant.your-domain.com/fullchain.pem certs/merchant.crt
cp certs/live/merchant.your-domain.com/privkey.pem certs/merchant.key

Enable SSL in docker-compose.yml:

gateway:
  ports:
    - "180:80"
    - "1443:443"   # uncomment this
  volumes:
    - ./nginx/gateway.conf:/etc/nginx/conf.d/default.conf
    # Replace with:
    # - ./nginx/gateway-ssl.conf:/etc/nginx/conf.d/default.conf
    - ./certs:/etc/nginx/certs   # uncomment this

Update HOST_PORT_GATEWAY_HTTPS=1443 in .env
Restart the gateway:

docker compose restart gateway

Step 5: Create the First Merchant

Access the merchant dashboard at http://localhost:180 (or your domain). The registration flow:

Register — Create a merchant account with email and password
API Credentials — After login, navigate to Settings → API Keys to generate an API key and secret
Webhook URL — Configure the callback URL for payment notifications
Deposit Addresses — The system automatically generates deposit addresses per order using HD wallet derivation — no manual setup needed

Using the API

With your API key and secret:

curl -X POST https://api.your-domain.com/v1/collection/create \
  -H "Content-Type: application/json" \
  -d '{
    "sign": "<hmac-signature>",
    "timestamp": 1717000000000,
    "nonce": "<uuid>",
    "data": {
      "amount": "100.00",
      "symbol": "USDT",
      "chain": "tron",
      "orderId": "order_001"
    }
  }'

SDKs handle signing automatically:

Node.js: npm install @xpaylabs/node-sdk
Java: Maven Central com.xpaylabs:xpay-java-sdk

Architecture Deep Dive

Multi-Tenant Design

XPayLabs is designed as a platform operator model. A single deployment hosts unlimited merchants, each with:

Isolated data (scoped by merchant_id)
Separate API credentials (HMAC key pairs)
Independent webhook configuration
Configurable fee schedules (you set the rates)

HD Wallet Key Management

The gateway uses BIP-44 hierarchical deterministic wallet derivation:

m / 44' / coin_type' / 0' / 0 / address_index

Master seed is set via XPAY_MASTER_SEED (not exposed in this Docker setup — the HD wallet key is embedded in the scanner services)
Database stores only the derivation index, never private keys
Recovery: restore the seed phrase and replay blockchain history

Blockchain Scanner Architecture

Each blockchain has an independent scanner service that:

Polls its RPC node at a configurable interval (2-15 seconds)
Fetches Transfer events involving tracked deposit addresses
Matches events to pending collection orders
Updates order status and enqueues webhook delivery
Waits for chain-specific confirmation count before marking as success

Chain	Detection Method	Block Time	Recommended Confirmations
TRON	TRON Grid gRPC API	~3s	1-2
Ethereum	JSON-RPC `eth_getLogs`	~12s	12-30
BSC	JSON-RPC polling	~3s	15-30
Polygon	JSON-RPC polling	~2s	30-100
Avalanche	JSON-RPC polling	~2s	10-20
Arbitrum	JSON-RPC polling	~1s	10-20
SUI	SUI RPC (via sui-node-service)	~2s	5-10

Production Operations

Monitoring

Check service health: docker compose ps
View logs: docker compose logs -f --tail=100 <service>
Log files are persisted in ./logs/ with per-service subdirectories
Consider adding Uptime Kuma or a similar monitoring tool to watch the gateway endpoint

Database Backups

# Manual backup
docker exec xpay-mysql mysqldump -u root -p xpaylabs > backup_$(date +%Y%m%d).sql

# Automated backup with crontab
0 3 * * * docker exec xpay-mysql mysqldump -u root -p$MYSQL_ROOT_PASSWORD xpaylabs > /backups/xpaylabs_$(date +\%Y\%m\%d).sql

Updating Services

docker compose pull        # Pull latest images
docker compose up -d       # Restart with new images

The ghcr.io/yan253319066/xpay-java image contains all Java JARs. Update the image tag in docker-compose.yml when a new version is released.

Scaling

The current architecture uses a single-instance deployment. For horizontal scaling:

Read replicas: Add MySQL read replicas for query-heavy workloads
Multiple scanners: Run additional scanner instances with different RPC providers for redundancy
Load balancing: Place multiple gateway instances behind a TCP load balancer

Troubleshooting

"pull access denied" for ghcr.io images

The images are hosted on a public GitHub Container Registry — no authentication required. Common causes:

Network/firewall blocking ghcr.io — try configuring a Docker proxy or mirror
ghcr.io rate limiting — wait and retry

If pulling consistently fails, build the images from source:

# Build Java services
cd XPayLabs-java
mvn clean install -P prod -DskipTests
docker build -t ghcr.io/yan253319066/xpay-java .

# Build frontend services
cd XPayLabs-checkout
docker build -t ghcr.io/yan253319066/checkout .
cd XPayLabs-merchant-vue
docker build -t ghcr.io/yan253319066/merchant-vue .

Then update docker-compose.yml to use pull_policy: never and build directives, or tag your local images to match the image names.

MySQL connection refused

MySQL takes ~30-60 seconds to initialize on first run (especially the init SQL). Check health:

docker compose logs mysql
docker compose exec mysql mysqladmin ping -h localhost

Scanner not detecting transactions

Check the scanner logs for RPC errors
Verify the RPC endpoint is reachable from the container
Confirm the deposit address derivation path matches the chain
Check that TRON_NETWORKS or ETH_NETWORKS includes the correct network name

Port conflicts

If port 180 is already in use on the host, change HOST_PORT_GATEWAY_HTTP in .env to any available port (e.g., 8080). All internal service ports can also be remapped.

Cost Analysis for Operators

Running XPayLabs as a payment platform operator:

Item	Monthly Cost
Server (4 GB RAM, 2 vCPU)	~$20-40
RPC endpoints (mainnet)	~$50-200 (depending on chains)
Domain + SSL	~$1-5
Total	~$70-250/mo

If you charge merchants 0.5% per transaction and process $500,000/month:

Revenue Stream	Monthly
Transaction fees (0.5%)	$2,500
Server cost	-$70-250
Net profit	~$2,250-2,430/mo

Summary

XPayLabs gives you a complete multi-chain crypto payment infrastructure in a single docker compose up command. The key operational responsibilities are:

Secure the master seed — Generate it offline, store it in a hardware wallet or encrypted vault
Monitor service health — Watch scanner logs and gateway uptime
Back up the database — Regular MySQL dumps
Keep RPC endpoints healthy — Use reliable providers with failover

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

SDKs: npm | Maven Central

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.xpaylabs.com

如果你正在寻找一套简单、快速、安全的加密货币支付解决方案，欢迎联系我们，立即试用 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 频道/群：即将上线，欢迎留言