> ## 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: Open-Source Multi-Tenant Crypto Payment Gateway

> XPayLabs is a self-hosted, non-custodial crypto payment gateway. Deploy on your own servers to accept stablecoin payments across TRON, EVM chains, and SUI with zero gateway fees. Multi-tenant — host unlimited merchants and collect fees.

XPayLabs (often called **xpay**) is an open-source, self-hosted crypto payment infrastructure that lets you accept and manage stablecoin payments across multiple blockchains through a single API. **Multi-tenant by design** — a single deployment can host unlimited merchants, each with isolated API credentials and independent configuration. Set your own fee structure and earn from every transaction.

Unlike hosted payment gateways, XPayLabs runs entirely on your infrastructure — your private keys stay on your servers, your funds go directly to your wallets, and you pay zero gateway fees. Process up to 100 transactions per second per gateway instance with no per-transaction fees — only blockchain gas costs ($0.01–$0.50 per transaction).

<Info title="x402 Protocol — AI Agent Micropayments">
  XPayLabs is the **first self-hosted gateway** to support the [x402 protocol](/guides/x402-overview) for AI agent micropayments. Enable **pay-per-call USDC billing** for LLM APIs, AI agents, and any HTTP-based service — no API key management required. This is a capability no hosted competitor (BitPay, Coinbase Commerce, NowPayments) offers.
</Info>

<CardGroup cols={2}>
  <Card title="Quick Start" icon="rocket" href="/quickstart">
    Deploy your payment gateway and create your first collection in minutes
  </Card>

  <Card title="Authentication" icon="key" href="/authentication">
    Generate merchant tokens and sign your requests securely
  </Card>

  <Card title="API Reference" icon="code" href="/api-reference/overview">
    Explore every endpoint, parameter, and response field
  </Card>

  <Card title="Guides" icon="book-open" href="/guides/accept-payments">
    Step-by-step walkthroughs for collection and payout flows
  </Card>
</CardGroup>

## Supported Blockchains

XPayLabs natively supports the following blockchain networks:

| Chain                 | Type   | Stablecoins      |
| --------------------- | ------ | ---------------- |
| **TRON**              | TRC20  | USDT, USDC       |
| **Ethereum**          | ERC20  | USDT, USDC, DAI  |
| **BNB Chain**         | BEP20  | USDT, USDC, BUSD |
| **Polygon**           | ERC20  | USDT, USDC, DAI  |
| **Arbitrum**          | ERC20  | USDT, USDC       |
| **Optimism**          | ERC20  | USDT, USDC       |
| **Base**              | ERC20  | USDT, USDC       |
| **Avalanche C-Chain** | ERC20  | USDT, USDC       |
| **SUI**               | Native | USDC             |

## Architecture

XPayLabs runs as 11 Docker containers orchestrated via Docker Compose. A single Nginx gateway serves as the public entry point, routing requests to backend services and frontend UIs.

```mermaid architecture theme={null}
graph TD
    GATEWAY["nginx:alpine<br/>Gateway :180"]
    MYSQL[("MySQL 8.0<br/>:13306")]
    REDIS[("Redis 7<br/>:16379")]

    GATEWAY -->|"/api/"| USER["xpay-user :8077<br/>Collection API"]
    GATEWAY -->|"/prod-api/"| MERCHANT["xpay-merchant :8078<br/>Admin API"]
    GATEWAY -->|"/checkout"| CHECKOUT["checkout :80<br/>Vue 3"]
    GATEWAY -->|"/"| DASHBOARD["merchant-vue :80<br/>Dashboard"]

    USER --> MYSQL
    USER --> REDIS
    MERCHANT --> MYSQL
    MERCHANT --> REDIS

    subgraph Blockchain Scanners
        ETH["xpay-eth :8076<br/>EVM Scanner"]
        TRON["xpay-tron :8075<br/>TRON Scanner"]
        SUI["xpay-sui :8074<br/>SUI Scanner"]
    end

    ETH --> MYSQL
    TRON --> MYSQL
    SUI --> MYSQL
    SUI -->|RPC| SUI_PROXY["sui-node-service<br/>:13001"]
```

*11 microservices: 1 gateway, 2 data stores, 3 blockchain scanners, 1 SUI RPC proxy, 2 backend APIs, 2 frontend UIs.*

## How does XPayLabs process payments?

<Steps>
  <Step title="Deploy the gateway">
    Run `docker compose up -d` on your server. All services start together — Java backends (xpay-user, xpay-merchant, xpay-eth, xpay-tron, xpay-sui), blockchain scanners, webhook dispatcher, and the checkout UI.
  </Step>

  <Step title="Generate API credentials">
    Configure your merchant token in the gateway dashboard. This token is used to sign every API request with HMAC-SHA256.
  </Step>

  <Step title="Create a collection">
    Send a `POST /v1/order/createCollection` request with amount, symbol, and chain. XPayLabs returns a unique deposit address and checkout URL.
  </Step>

  <Step title="Listen for webhooks">
    Register your callback URL. When the blockchain scanner detects the incoming transaction, XPayLabs delivers a signed webhook notification.
  </Step>
</Steps>

## Key Concepts

| Concept        | Description                                                             |
| -------------- | ----------------------------------------------------------------------- |
| **Collection** | A request for payment that generates a unique deposit address           |
| **Payout**     | A funds transfer from your gateway wallet to an external address        |
| **Settlement** | Automatic sweep of received funds from hot wallets to your cold storage |
| **Webhook**    | An HTTP callback triggered by order or collection status changes        |
| **Scanner**    | A blockchain indexer that monitors incoming transactions in real-time   |

<Tip>
  Since XPayLabs is self-hosted, you have complete control over your funds. No third party holds your private keys, and no gateway fees are deducted from your transactions — you only pay blockchain network gas fees.
</Tip>