XPayLabs REST API Reference — Concepts & Structure

The XPayLabs API is a REST API with JSON request/response bodies secured by HMAC-SHA256 signing. Learn about the base URL, request format, response shape, and rate limits.

XPayLabs exposes a RESTful API over HTTP. Every request uses a standard signed envelope format (ReqPayload), and every response follows a consistent structure (R<T>). This page covers the foundational concepts that apply across all endpoints.

Base URL

All API requests target your self-hosted gateway. The default port is 3010:

http://your-server:3010/v1

If you are running behind a reverse proxy (Nginx, Caddy), use your configured HTTPS domain.

Request Format

Every POST request must use the standard ReqPayload<T> envelope:

Field	Type	Description
sign	string	HMAC-SHA256 signature of the stringified data object
timestamp	integer	Unix timestamp (seconds)
nonce	string	Unique request identifier
data	object	The actual request parameters

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

See the Authentication page for details on computing the sign value.

Response Format

All responses use the standard R<T> envelope:

{
  "code": 200,
  "msg": "success",
  "data": { ... }
}

Field	Type	Description
code	integer	HTTP status code (200 on success)
msg	string	Status message ("success" or error description)
data	object	The response payload (varies by endpoint)

Error Response

{
  "code": 400,
  "msg": "The amount cannot be left blank.",
  "data": null
}

Authentication

All requests must be signed with your merchant token using HMAC-SHA256. There are no API keys, Bearer tokens, or cookies involved. The merchant token is configured in your gateway and never transmitted over the network. See the Authentication page for the full signing reference.

HTTP Methods

Method	Use
POST	Create a resource (collection, payout)
GET	Retrieve a resource or list

Rate Limits

Rate limits are configurable per merchant in the gateway configuration. Defaults:

Endpoint	Limit
POST /v1/order/createCollection	100 requests per 10 seconds
POST /v1/order/createPayout	100 requests per 10 seconds
GET /v1/order/status/{orderId}	1000 requests per 10 seconds
GET /v1/order/pay	2 requests per second per orderId
GET /v1/order/getOrderStatus	2 requests per second per orderId
GET /v1/symbol/supportSymbols	50 requests per 10 seconds

Exceeding the limit returns a 429 Too Many Requests response.

Amounts

All monetary amounts are expressed as string-formatted decimals (e.g., "100.00" for 100 USDT). The number of decimal places depends on the token’s configured decimals — USDT uses 2 decimal places on most chains (shown as "100.00"), while the internal representation uses the token’s native decimals.