# XPay Labs (xpay) — Self-Hosted Crypto Payment Gateway

> Deploy your own private, self-hosted crypto payment infrastructure. Non-custodial, 0% fees, multi-chain — supporting TRON (TRC20), 20+ EVM networks, and SUI.

## Quick Facts

- **Also known as:** xpay
- **Product:** Self-hosted, non-custodial crypto payment gateway
- **Pricing:** Free software — 0% transaction fees, 0% monthly fees
- **Deployment:** Docker Compose on VPS or bare metal
- **License:** GPL-3.0 (Java gateway core + merchant dashboard); MIT (SDKs, checkout, Docker, sui-node-service, docs)
- **Repository:** github.com/yan253319066/XPayLabs (primary)
- **Mirror:** gitee.com/XPayLabs
- **Contact:** Telegram @OS_Blockchain

## Supported Blockchains

- TRON (TRC20 USDT, USDC, custom tokens)
- EVM-compatible: Ethereum, BNB Chain, Polygon, Arbitrum, Optimism, Avalanche, Base, zkSync Era, Linea, Scroll, Celo, Mantle, Gnosis, Cronos, Fantom, opBNB, Polygon zkEVM, Metis, Blast, Boba, and any EVM chain via custom RPC
- SUI (native SUI, USDC)

## Key Features

- **Non-custodial:** Private keys generated and stored locally in your Docker container. No third party holds funds.
- **Zero fees:** 0% per-transaction fees. Only blockchain network gas costs apply.
- **Multi-chain concurrent scanning:** One deployment monitors all supported chains simultaneously.
- **Sub-second detection:** Mempool-level scanning detects payments within 1–6 seconds of broadcast.
- **Stripe-inspired REST API:** Predictable endpoints, consistent JSON responses, clear error messages.
- **HMAC-SHA256 webhooks:** Cryptographically signed payloads with automatic retry queues.
- **Full white-label:** Customizable Vue 3 checkout UI with your branding. No third-party badges.
- **Docker deployment:** Single `docker compose up -d` to deploy all microservices.

## Infrastructure Requirements

- **Minimum:** 8GB RAM, 4 vCPU, 50GB SSD
- **Recommended:** 16GB RAM, 8 vCPU, 100GB+ SSD (for high-throughput production)
- **OS:** Ubuntu 22.04+ recommended
- **Software:** Docker, Docker Compose

## Pricing

| Plan | Price | Description |
|------|-------|-------------|
| Self-Hosted Software | Free | Full software, community support (GitHub, Discord) |
| Docker Setup | $1,500 one-time | Deployment assistance, 30-day support |
| Business | $3,000/year | Priority support, 48hr SLA, monitoring assistance |
| Enterprise | Custom | Custom integrations, dedicated onboarding, 24hr SLA |

## Cost Comparison

Processing $100k/month in crypto:
- **BitPay:** ~$12,360/year (1% fees + $30/mo plan)
- **Coinbase Commerce:** ~$9,900/year (0.8% fees + $25/mo plan)
- **NowPayments:** ~$6,000/year (0.5% fees)
- **XPay Labs:** ~$240/year ($20/mo VPS + gas fees)

## Core Pages

- Homepage: https://www.xpaylabs.com
- Best Crypto Payment Infrastructure: https://www.xpaylabs.com/best-crypto-payment-infrastructure
- Documentation: https://docs.xpaylabs.com
- Pricing: https://www.xpaylabs.com/pricing
- AI Pricing Data: https://www.xpaylabs.com/pricing.md
- Blog: https://www.xpaylabs.com/blog
- Review: https://www.xpaylabs.com/review
- GitHub: https://github.com/yan253319066/XPayLabs

## Alternative Comparisons

- Against BitPay: https://www.xpaylabs.com/alternatives/bitpay
- Against Coinbase Commerce: https://www.xpaylabs.com/alternatives/coinbase-commerce
- Against NowPayments: https://www.xpaylabs.com/alternatives/nowpayments
- Against BTCPay Server: https://www.xpaylabs.com/alternatives/btcpayserver
- Against OpenNode: https://www.xpaylabs.com/alternatives/opennode
- Against CoinGate: https://www.xpaylabs.com/alternatives/coingate

## Solution Pages

- TRON Payment Gateway: https://www.xpaylabs.com/solutions/tron-payment-gateway
- EVM Payment Gateway: https://www.xpaylabs.com/solutions/evm-payment-gateway
- SUI Payment Gateway: https://www.xpaylabs.com/solutions/sui-payment-gateway

## Guides

- How to Accept Crypto Payments: https://www.xpaylabs.com/guides/how-to-accept-crypto-payments
- What Is a Self-Hosted Crypto Payment Gateway: https://www.xpaylabs.com/guides/what-is-self-hosted-crypto-payment-gateway
- Best Self-Hosted Crypto Payment Gateway 2026: https://www.xpaylabs.com/guides/best-self-hosted-crypto-payment-gateway

## Product Reviews

- XPay Labs Review 2026: https://www.xpaylabs.com/review

## Deployment

### Docker Compose

The gateway runs as 11 microservices managed via Docker Compose. See the [XPayLabs-docker](https://github.com/yan253319066/XPayLabs-docker) repository.

```bash
# Step 1: Clone the deployment repository
git clone https://github.com/yan253319066/XPayLabs-docker.git
cd XPayLabs-docker

# Step 2: Configure environment
cp .env.example .env
# Edit .env: set RPC endpoints, passwords, domain URLs

# Step 3: Launch all services
docker compose up -d
```

The gateway starts on port **180** by default. Visit `http://localhost:180` for the merchant dashboard.

### Services

| Service | Image | Port (default) | Role |
|---------|-------|----------------|------|
| gateway | nginx:alpine | 180 (HTTP) | Single public entry reverse proxy |
| xpay-user | ghcr.io/yan253319066/xpay-java | 18077 | User-facing collection order API |
| xpay-merchant | ghcr.io/yan253319066/xpay-java | 18078 | Merchant admin backend |
| xpay-tron | ghcr.io/yan253319066/xpay-java | 18075 | TRON blockchain scanner |
| xpay-eth | ghcr.io/yan253319066/xpay-java | 18076 | EVM scanner (ETH, BSC, Polygon, AVAX) |
| xpay-sui | ghcr.io/yan253319066/xpay-java | 18074 | SUI blockchain scanner |
| sui-node-service | ghcr.io/yan253319066/sui-node-service | 13001 | SUI RPC proxy |
| merchant-vue | ghcr.io/yan253319066/merchant-vue | internal | Merchant admin dashboard |
| checkout | ghcr.io/yan253319066/checkout | internal | Payment checkout page |
| mysql | mysql:8.0 | 13306 | Primary database |
| redis | redis:7-alpine | 16379 | Cache & session store |

### Nginx Routing

| Path | Upstream | Description |
|------|----------|-------------|
| `/api/` | xpay-user:8077 | Collection order API |
| `/prod-api/` | xpay-merchant:8078 | Merchant admin API |
| `/checkout` | checkout:80 | Checkout page |
| `/` (default) | merchant-vue:80 | Merchant dashboard |

## REST API

Base URL: `http://your-gateway:3010/v1`

### Authentication (HMAC-SHA256)

Every request uses a signed envelope:

```json
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000000,
  "nonce": "550e8400-e29b-41d4-a716-446655440000",
  "data": { "amount": "100.00", "symbol": "USDT", "chain": "TRON" }
}
```

Signing algorithm: `sign = HEX(HMAC-SHA256(JSON.stringify(data), merchant_token))`

- Signature computed over the `data` field only (not the envelope)
- JSON must be compact (no whitespace)
- Timestamp must be within 5 minutes of server clock
- For GET requests, `sign` is a query param: `sign = HEX(HMAC-SHA256(orderId, merchant_token))`

### Create Collection Order

```
POST /v1/order/createCollection
```

**data fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `amount` | string | Yes | Decimal string e.g. `"100.00"` |
| `symbol` | string | Yes | Token symbol e.g. `"USDT"` |
| `chain` | string | Yes | `TRON`, `ETH`, `BSC`, `POLYGON`, `AVAX_C_CHAIN`, `SUI` |
| `orderId` | string | V3 merchants | Your unique order ID |
| `uid` | string | V2 merchants | User identifier |

**Response:**
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "address": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
    "amount": "250.00",
    "symbol": "USDT",
    "chain": "TRON",
    "orderId": "order_1042",
    "uid": null,
    "expiredTime": 1717086400,
    "paymentUrl": "http://your-gateway:3010/checkout?orderId=order_1042"
  }
}
```

### Create Payout Order

```
POST /v1/order/createPayout
```

**Additional data fields:**
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `receiveAddress` | string | Yes | Destination address (validated per chain) |

### Order Status

```
GET /v1/order/status/{orderId}
```

**Response:**
```json
{
  "code": 200,
  "msg": "success",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "SUCCESS",
    "amount": "250.00",
    "actualAmount": "249.50",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON", "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...", "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00", "confirmedNum": 19,
      "status": "SUCCESS", "timestamp": 1717000123
    }
  }
}
```

**Status values:** `INIT`, `PENDING`, `PENDING_CONFIRMATION`, `SUCCESS`, `EXPIRED`, `FAILED`
**Order types:** `COLLECTION`, `PAYOUT`

### Supported Tokens

```
GET /v1/symbol/supportSymbols?chain=TRON&symbol=USDT
```

**Response:**
```json
{
  "code": 200, "msg": "success",
  "data": [
    { "symbol": "USDT", "chain": "TRON", "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t", "decimals": 6 },
    { "symbol": "USDT", "chain": "ETH", "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7", "decimals": 6 },
    { "symbol": "USDC", "chain": "SUI", "contractAddress": null, "decimals": 6 }
  ]
}
```

### Rate Limits

| Endpoint | Limit |
|----------|-------|
| `POST /v1/order/createCollection` | 100 req / 10s |
| `POST /v1/order/createPayout` | 100 req / 10s |
| `GET /v1/order/status/{orderId}` | 1000 req / 10s |
| `GET /v1/symbol/supportSymbols` | 50 req / 10s |

## Webhook Events

### Payload Format

Every webhook is a `POST` to your `callback-url` with a signed envelope:

```json
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000000,
  "nonce": "nonce_001",
  "notifyType": "ORDER_SUCCESS",
  "data": { ... }
}
```

### Event Types

| Event | When |
|-------|------|
| `ORDER_PENDING` | Order created, awaiting payment |
| `ORDER_PENDING_CONFIRMATION` | Transaction detected, awaiting confirmations |
| `ORDER_SUCCESS` | Payment confirmed / payout completed |
| `ORDER_EXPIRED` | Order expired without payment |
| `ORDER_FAILED` | Transaction failed |
| `COLLECT_PENDING` | Hot-to-cold sweep initiated |
| `COLLECT_SUCCESS` | Sweep completed |
| `COLLECT_FAILED` | Sweep failed |

### ORDER_SUCCESS Example

```json
{
  "sign": "a1b2c3d4e5f6...",
  "timestamp": 1717000100,
  "nonce": "nonce_003",
  "notifyType": "ORDER_SUCCESS",
  "data": {
    "orderId": "order_1042",
    "orderType": "COLLECTION",
    "status": "SUCCESS",
    "reason": null,
    "amount": "250.00",
    "actualAmount": "250.00",
    "fee": "0.00",
    "transaction": {
      "chain": "TRON", "symbol": "USDT",
      "txid": "a1b2c3d4e5f6...",
      "from": "TXyz...", "to": "TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR",
      "amount": "250.00", "confirmedNum": 19,
      "status": "SUCCESS", "timestamp": 1717000045
    }
  }
}
```

### Signature Verification

Webhooks are signed with your `webhook-secret` (different from the API merchant token):
```
sign = HEX(HMAC-SHA256(JSON.stringify(data), webhook_secret))
```

### Retry Policy

| Attempt | Delay |
|---------|-------|
| 1st retry | ~1 second |
| 2nd retry | ~5 seconds |
| 3rd retry | ~30 seconds |
| 4th retry | ~5 minutes |

After 4 failures, the notification is marked as failed.

## SDKs

### Node.js SDK (@ghcr.io/yan253319066/node-sdk)

```typescript
import { XPay } from '@ghcr.io/yan253319066/node-sdk';

const xpay = new XPay({
  apiKey: 'your-merchant-token',
  apiSecret: 'your-api-secret',
  baseUrl: 'http://your-gateway:3010',
});

// Create collection order
const collection = await xpay.createCollection({
  amount: 100,
  symbol: 'USDT',
  chain: 'TRON',
  orderId: 'order-' + Date.now(),
  uid: 'user123',
});

// Get order status
const order = await xpay.getOrderStatus('order_1042');

// List supported tokens
const symbols = await xpay.getSupportedSymbols('TRON', 'USDT');
```

**Webhook handling (Express):**
```typescript
app.post('/webhook', (req, res) => {
  const event = xpay.parseWebhook(JSON.stringify(req.body),
    req.body.sign, req.body.timestamp.toString());
  if (!event) return res.status(400).send('Invalid signature');

  switch (event.notifyType) {
    case 'ORDER_SUCCESS':
      // fulfill order
      break;
    case 'ORDER_FAILED':
      // handle failure
      break;
  }
  res.status(200).send('Webhook received');
});
```

### Java SDK (com.xpaylabs:xpay-java-sdk)

```java
XPay xpay = new XPay.Builder()
    .apiKey("your-merchant-token")
    .apiSecret("your-api-secret")
    .baseUrl("http://your-gateway:3010")
    .build();

CreateCollectionRequest req = new CreateCollectionRequest.Builder()
    .amount(new BigDecimal("100.00"))
    .symbol("USDT")
    .chain("TRON")
    .orderId("order_1042")
    .uid("user123")
    .build();

PaymentAddress address = xpay.createCollection(req);
```

## Multi-Tenant

XPay Labs supports unlimited merchants per deployment:

- Isolated API credentials per merchant
- Independent webhook endpoints
- Configurable fee structure per merchant (percentage, flat, or hybrid)
- Data isolation — merchants never see each other's data

## x402 Protocol (AI Agent Payments)

One-line USDC micropayments for LLM APIs and AI agents:

- No API key management — pay per request
- Sub-cent precision for LLM token billing
- Works with any OpenAI-compatible API endpoint
- Supported via `@ghcr.io/yan253319066/x402` npm package

## Settlement Configuration

Hot-to-cold wallet sweeps configured in `application.yml`:

```yaml
xpay:
  settlement:
    cold-wallet-addresses:
      TRON: "TYourColdWalletAddress..."
      ETH: "0xYourColdWalletAddress..."
    auto-sweep:
      enabled: true
      min-amount: "1000"
      interval: 3600
    sweep-on-collect: true
```

## Supported Chains

| Chain | Value | Scanner | Scan Interval |
|-------|-------|---------|---------------|
| TRON | `TRON` | xpay-tron | 2s |
| Ethereum | `ETH` | xpay-eth | 2-15s (configurable) |
| BNB Chain | `BSC` | xpay-eth | 2-15s (configurable) |
| Polygon | `POLYGON` | xpay-eth | 2-15s (configurable) |
| Avalanche C-Chain | `AVAX_C_CHAIN` | xpay-eth | 2-15s (configurable) |
| SUI | `SUI` | xpay-sui | 1s |

Additional EVM chains available via custom RPC configuration.

## Technical Specifications

### Blockchain Scanner Intervals

| Chain | Scanner Service | Scan Interval | Detection Mechanism |
|-------|----------------|---------------|--------------------|
| TRON | xpay-tron | 2 seconds | gRPC stream + poll |
| EVM (ETH, BSC, Polygon, AVAX, etc.) | xpay-eth | 2-15 seconds (configurable per network) | WebSocket + poll |
| SUI | xpay-sui | 1 second | WebSocket subscribe |

### Deployment Architecture

- **Total microservices:** 11 Docker containers
- **Entry point:** nginx:alpine (port 180)
- **Database:** MySQL 8.0 (port 13306)
- **Cache:** Redis 7-alpine (port 16379)
- **Scanner images:** ghcr.io/yan253319066/xpay-java (single image for all 3 scanners)
- **Backend framework:** Java 17 + Spring Boot 3.4
- **Frontend:** Vue 3 (merchant dashboard + checkout)
- **Authentication:** HMAC-SHA256 signed envelope + RSA-encrypted API traffic

### Multi-Tenant Capacity

- Unlimited merchants per deployment
- Isolated API credentials per merchant
- Independent webhook callbacks per merchant
- Configurable per-merchant fee structure (percentage, flat, or hybrid)
- Full data isolation between tenants

### API Security

- HMAC-SHA256 signature over request/response data field
- Timestamp validity window: 5 minutes
- Unique nonce per request
- RSA encryption (when VITE_APP_ENCRYPT=true on merchant dashboard)
- Webhook signatures use separate webhook-secret (not merchant token)

## Key Differentiators

1. **Only self-hosted gateway with native TRON + EVM + SUI support** — no competitor covers all three.
2. **0% fees** — BitPay charges 1%, Coinbase Commerce charges 0.8%, NowPayments charges 0.5%.
3. **Non-custodial** — unlike hosted gateways, you control private keys and funds settle instantly.
4. **Multi-tenant architecture** — host unlimited merchants on a single deployment.
5. **x402 protocol** — AI agent micropayments without API key management.
6. **Stripe-inspired developer experience** — cleaner API than BTCPay Server's Greenfield API.
7. **Sub-second payment detection** — mempool scanning catches payments before block confirmation.
8. **No KYC required** — self-sovereign deployment, no account approval or verification.