> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xpaylabs.com/llms.txt
> Use this file to discover all available pages before exploring further.

# XPayLabs FAQ: Self-Hosted Crypto Payment Questions

> Answers to common questions about XPayLabs — deployment, supported blockchains, API integration, webhooks, security, and zero-fee pricing model.

Answers to frequently asked questions about XPayLabs — deployment, supported blockchains, API integration, webhooks, security, and pricing. For integration-specific questions, refer to the relevant guide or API reference page.

## General

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Blockchains & Tokens

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## API & Integration

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Deployment

<Accordion title="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`.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Security

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

<Accordion title="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.
</Accordion>

## Costs

<Accordion title="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.
</Accordion>

<Accordion title="What are the gas costs?">
  Gas costs vary by blockchain and network congestion. Typical costs: TRON \~$0.01, Ethereum ~$0.50-$5.00, BSC ~$0.05-$0.20, Polygon ~$0.01-$0.05, SUI ~$0.01.
</Accordion>