General
What is XPayLabs?
What is XPayLabs?
XPayLabs (often called xpay) is a self-hosted, non-custodial crypto payment infrastructure. It enables businesses to accept, process, and settle stablecoin payments on TRON, EVM chains, and SUI without relying on a third-party payment processor. You deploy it on your own servers, your private keys stay in your infrastructure, and you pay no gateway fees — only blockchain gas costs.
Is XPayLabs self-hosted or hosted?
Is XPayLabs self-hosted or hosted?
Fully self-hosted. You deploy the gateway on your own infrastructure using Docker Compose. XPayLabs does not operate a hosted SaaS platform. All data, keys, and funds stay within your control.
Is XPayLabs non-custodial?
Is XPayLabs non-custodial?
Yes. Private keys are generated and stored exclusively within your Docker containers. No third party can access or move your funds. The gateway software never transmits keys over the network.
What are the system requirements?
What are the system requirements?
Recommended minimum: 8GB RAM / 4 vCPU. For high-concurrency or clustered deployments: 16GB RAM / 8 vCPU. The gateway requires Docker and Docker Compose. Ubuntu 22.04+ is recommended.
Blockchains & Tokens
Which blockchains are supported?
Which blockchains are supported?
XPayLabs natively supports TRON (TRC20), Ethereum, BNB Chain, Polygon, Avalanche C-Chain, and SUI. Testnets (TRON Shasta, ETH Sepolia, BSC Testnet, Polygon Amoy, Avalanche Fuji, SUI Testnet) are supported for development.
Which tokens are supported?
Which tokens are supported?
USDT and USDC are supported out of the box on most chains. Additional ERC20/TRC20/BEP20 tokens can be configured by declaring their smart contract addresses in the gateway configuration.
Can I add custom tokens?
Can I add custom tokens?
Yes. Add any standard-compliant token by specifying its contract address, symbol, and decimals in the gateway’s asset type configuration. The scanner monitors the contract’s
Transfer event logs for incoming transactions.API & Integration
What authentication does the API use?
What authentication does the API use?
All requests are authenticated using HMAC-SHA256 request signing. You configure a merchant token in the gateway, and each API request includes a signature computed over the request payload. No merchant tokens are transmitted over the network.
How do I create a payment?
How do I create a payment?
Call
POST /v1/order/createCollection with the amount, symbol, and chain. The gateway returns a unique deposit address. Your customer sends funds to that address, and the blockchain scanner detects the payment automatically.How do webhooks work?
How do webhooks work?
Configure a callback URL in the gateway. When order or collection status changes, the gateway sends a signed
POST request with a NotifyPayload containing the event type and order data. Verify the HMAC-SHA256 signature using your webhook secret.Can I poll for order status instead of using webhooks?
Can I poll for order status instead of using webhooks?
Yes. Use
GET /v1/order/getOrderStatus?orderId=...&sign=... or GET /v1/order/status/{orderId} to retrieve the current order status. However, webhooks are recommended for production use.Deployment
How do I deploy XPayLabs?
How do I deploy XPayLabs?
Clone the repository and run
docker compose up -d. Configure your blockchain RPC endpoints, generate a wallet seed phrase, and set up your merchant account in the gateway dashboard. Access the API via the gateway on port 180.Do I need blockchain RPC endpoints?
Do I need blockchain RPC endpoints?
Yes. The gateway requires RPC endpoints for each blockchain you want to support. You can use public RPC providers (e.g., Trongrid, Infura) or run your own nodes.
Can I use a reverse proxy?
Can I use a reverse proxy?
Yes. It is recommended to place XPayLabs behind Nginx or Caddy for TLS termination and domain routing. The Java backends serve on internal ports (xpay-user:8077, xpay-merchant:8078), and the nginx gateway routes external traffic.
Security
Where are my private keys stored?
Where are my private keys stored?
Private keys are generated and stored in your Docker container’s memory and encrypted storage. They never leave your infrastructure. The wallet seed is derived from a mnemonic phrase you configure in the gateway.
What happens if my server goes down?
What happens if my server goes down?
Since XPayLabs is non-custodial, funds always stay on the blockchain — there is no risk of fund loss during downtime. When the gateway restarts, the blockchain scanner replays missed blocks and detects any transactions that occurred during the outage.
How do I secure the gateway?
How do I secure the gateway?
- Place the gateway behind a firewall, accepting only necessary traffic on port 180.
- Use a reverse proxy with TLS for all external-facing endpoints.
- Restrict dashboard access to your internal network or VPN.
- Regularly backup your wallet seed phrase offline.
Costs
What fees does XPayLabs charge?
What fees does XPayLabs charge?
Zero gateway fees. You pay only blockchain network gas fees (e.g., TRON bandwidth/energy, Ethereum gas). There are no per-transaction fees, monthly fees, or percentage-based fees.
What are the gas costs?
What are the gas costs?
Gas costs vary by blockchain and network congestion. Typical costs: TRON ~0.50-0.05-0.01-0.01.