> ## 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.

# Send Crypto Payouts: XPayLabs Payout API Guide

> Send crypto payments from your gateway wallet to external blockchain addresses using the XPayLabs payout API. Supports TRON, EVM chains, and SUI.

Send crypto payments from your XPayLabs gateway wallet to any external blockchain address using the payout API. Supports USDT, USDC, and other stablecoins on TRON, EVM chains, and SUI.

## How to create a payout

Call `POST /v1/order/createPayout` with the destination address, amount, symbol, and chain:

```javascript theme={null}
import crypto from "crypto";

const GATEWAY_URL = "http://your-gateway:180";
const MERCHANT_TOKEN = process.env.XPAYLABS_TOKEN;

function signRequest(data) {
  return crypto
    .createHmac("sha256", MERCHANT_TOKEN)
    .update(JSON.stringify(data), "utf8")
    .digest("hex");
}

async function createPayout({ amount, symbol, chain, receiveAddress, orderId }) {
  const data = {
    amount,
    symbol,
    chain,
    receiveAddress,
    orderId,
  };

  const payload = {
    sign: signRequest(data),
    timestamp: Math.floor(Date.now() / 1000),
    nonce: crypto.randomUUID(),
    data,
  };

  const response = await fetch(`${GATEWAY_URL}/v1/order/createPayout`, {
    method: "POST",
    headers: { "Content-Type": "application/json" },
    body: JSON.stringify(payload),
  });

  const result = await response.json();
  if (result.code !== 200) throw new Error(result.msg);

  return result.data;
}

// Send 50 USDT on TRON to an external address
const payout = await createPayout({
  amount: "50.00",
  symbol: "USDT",
  chain: "TRON",
  receiveAddress: "TYourExternalAddress...",
  orderId: "payout_001",
});

console.log(`Payout created: ${payout.orderId}`);
```

### Request Parameters

| Parameter        | Required | Description                                |
| ---------------- | -------- | ------------------------------------------ |
| `amount`         | Yes      | Amount as decimal string (e.g., `"50.00"`) |
| `symbol`         | Yes      | Token symbol (e.g., `"USDT"`)              |
| `chain`          | Yes      | Blockchain network                         |
| `receiveAddress` | Yes      | Destination blockchain address             |
| `orderId`        | No       | Your identifier for this payout            |
| `uid`            | No       | Your user identifier                       |

### Address Validation

The gateway validates the `receiveAddress` format for the specified chain before processing:

| Chain                   | Address Format          | Example                                                              |
| ----------------------- | ----------------------- | -------------------------------------------------------------------- |
| TRON                    | Base58, starts with `T` | `TWkKZkmuB8DpVeiMoHiKf99ZoFHzk73CqR`                                 |
| EVM (ETH, BSC, POLYGON) | Hex, starts with `0x`   | `0x05E833cF6a895a9ABe408FD6a8d5e0d3DB2Fec5A`                         |
| SUI                     | Hex, starts with `0x`   | `0x24f672b38299ae651f7598f4994ade780c38aeffa4e595c79ab73d3d176543cd` |

If the address format is invalid, the API returns `"ReceiveAddress error"`.

***

## How to track payout status

After creating a payout, track its status using the order status endpoint:

```javascript theme={null}
async function getPayoutStatus(orderId, token) {
  const response = await fetch(
    `${GATEWAY_URL}/v1/order/status/${orderId}`,
    { headers: { "Content-Type": "application/json" } }
  );
  const result = await response.json();
  return result.data;
}

// Poll until completed
const status = await getPayoutStatus("payout_001");
console.log(status.status); // "PENDING", "PENDING_CONFIRMATION", "SUCCESS", "FAILED"
if (status.transaction) {
  console.log(`TxID: ${status.transaction.txid}`);
}
```

## What payout statuses are there?

| Status                 | Description                                |
| ---------------------- | ------------------------------------------ |
| `PENDING`              | Payout created, awaiting processing        |
| `PENDING_CONFIRMATION` | Transaction submitted to blockchain        |
| `SUCCESS`              | Payout confirmed on-chain                  |
| `FAILED`               | Payout failed (insufficient balance, etc.) |

***

## What webhook events do payouts trigger?

Payouts also trigger webhook events:

| Event                        | When                      |
| ---------------------------- | ------------------------- |
| `ORDER_PENDING`              | Payout order created      |
| `ORDER_PENDING_CONFIRMATION` | Transaction submitted     |
| `ORDER_SUCCESS`              | Payout confirmed on-chain |
| `ORDER_FAILED`               | Payout failed             |

***

## Important security notes

<Warning>
  * Blockchain transactions are irreversible. Double-check the `receiveAddress` before submitting.
  * The gateway validates address format but cannot verify the address is owned by the intended recipient.
  * Payouts consume blockchain gas fees (TRX for TRON, ETH gas for EVM chains).
  * Ensure your hot wallet has sufficient balance (including gas tokens) before initiating payouts.
</Warning>