> ## 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 REST API: Crypto Payment Endpoints Reference

> The XPayLabs API is a REST API with JSON request/response bodies secured by HMAC-SHA256 signing. 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 via the nginx gateway. The default external port is `180`:

```
http://your-server:180/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                          |

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

See the [Authentication](/api-reference/authentication) page for details on computing the `sign` value.

## Response Format

All responses use the standard `R<T>` envelope:

```json theme={null}
{
  "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

```json theme={null}
{
  "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 Bearer tokens or cookies involved. The merchant token is configured in your gateway and never transmitted over the network. See the [Authentication](/api-reference/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.