X-Pay Node.js SDK

https://github.com/x-pay-official/xpay-node-sdk
Admin
Official Node.js SDK for the X-Pay cryptocurrency payment gateway, providing methods to create...
Tokens:4,417
Snippets:23
Trust Score:2.8
License:MIT
Update:4 months ago
Show doc for...
Tokens:
Raw
### Install X-Pay Node.js SDK

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Install the SDK using npm or yarn. This is the first step before using any SDK functionalities.

```bash
npm install x-pay-sdk-official
# or
yarn add x-pay-sdk-official
```

--------------------------------

### Get Supported Symbols

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Retrieve a list of all supported cryptocurrencies and their associated chain details. This is useful for determining valid parameters for orders.

```typescript
// Get all supported symbols
const allSymbols = await xpay.getSupportedSymbols();

// Response structure
{
  code: 200,
  msg: 'Success',
  data: [
    {
      symbol: 'USDT',
      chain: 'TRON',
      decimals: 6,
      contract: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
      minAmount: 1,
      maxAmount: 100000
    },
    // Other supported symbols...
  ]
}
```

--------------------------------

### Create Payout Order and Response Structure

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Example of creating a payout order and the expected response structure. The response includes order details and status.

```typescript
const payout = await xpay.createPayout({
  amount: 100,
  symbol: 'USDT',
  chain: 'TRON',
  orderId: 'order-123', // Optional order ID
  uid: 'user123', // Required user ID
  receiveAddress: 'TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp' // User's wallet address
});

// Response structure
{
  code: 200,
  msg: 'Success',
  data: {
    orderId: 'order-123',
    status: 'PENDING',
    amount: '100.00000000',
    symbol: 'USDT',
    chain: 'TRON',
    uid: 'user123',
    receiveAddress: 'TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp'
  }
}
```

--------------------------------

### Handle SDK Errors

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

This example shows how to catch and log detailed errors thrown by the SDK during operations like creating a payout. It logs the error message, status, code, and data.

```typescript
try {
  const payout = await xpay.createPayout({
    // ...payout details
  });
} catch (error) {
  console.error(`Error: ${error.message}`);
  console.error(`Status: ${error.status}`);
  console.error(`Code: ${error.code}`);
  console.error(`Data: ${JSON.stringify(error.data)}`);
}
```

--------------------------------

### Get Supported Symbols

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Retrieves a list of all cryptocurrencies and their supported chains, including details like decimals, contract address, and min/max amounts.

```APIDOC
## getSupportedSymbols

### Description
Fetches a list of all supported cryptocurrency symbols and their associated chain details, including contract addresses and transaction limits.

### Method
`GET` (inferred from SDK method usage)

### Endpoint
`/v1/symbols` (inferred from SDK method usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
None

### Request Example
(No explicit request body or query parameters shown for this method in the source)

### Response
#### Success Response (200)
- **code** (number) - The status code of the response.
- **msg** (string) - A message indicating the success or failure of the operation.
- **data** (array) - An array of objects, where each object represents a supported symbol and its chain details.
  - **symbol** (string) - The cryptocurrency symbol (e.g., 'USDT').
  - **chain** (string) - The blockchain network (e.g., 'TRON').
  - **decimals** (number) - The number of decimal places for the cryptocurrency.
  - **contract** (string) - The smart contract address on the specified chain.
  - **minAmount** (number) - The minimum transaction amount allowed.
  - **maxAmount** (number) - The maximum transaction amount allowed.

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": [
    {
      "symbol": "USDT",
      "chain": "TRON",
      "decimals": 6,
      "contract": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "minAmount": 1,
      "maxAmount": 100000
    }
    // Other supported symbols...
  ]
}
```
```

--------------------------------

### Get Order Status

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Retrieves the status of a specific order using its order ID. Provides details about the order and its transaction if applicable.

```APIDOC
## getOrderStatus

### Description
Retrieves the current status and details of a previously created order using its unique order ID.

### Method
`GET` (inferred from SDK method usage)

### Endpoint
`/v1/orders/{orderId}` (inferred from SDK method usage)

### Parameters
#### Path Parameters
- **orderId** (string) - Required - The unique identifier of the order to retrieve.

#### Query Parameters
None

#### Request Body
None

### Request Example
(No explicit request body or query parameters shown for this method in the source)

### Response
#### Success Response (200)
- **code** (number) - The status code of the response.
- **msg** (string) - A message indicating the success or failure of the operation.
- **data** (object) - Contains details of the order.
  - **orderId** (string) - The unique identifier for the order.
  - **orderType** (string) - The type of the order (e.g., 'PAYOUT', 'COLLECTION').
  - **status** (string) - The current status of the order (e.g., 'SUCCESS', 'PENDING').
  - **reason** (string) - Any reason provided for the order status.
  - **transaction** (object) - Details of the associated transaction, if available.
    - **chain** (string) - The blockchain network.
    - **symbol** (string) - The symbol of the cryptocurrency.
    - **blockNum** (number) - The block number where the transaction was confirmed.
    - **txid** (string) - The transaction ID.
    - **contractAddress** (string) - The contract address involved in the transaction.
    - **from** (string) - The sender's address.
    - **to** (string) - The recipient's address.
    - **amount** (string) - The transaction amount.
    - **timestamp** (number) - The timestamp of the transaction.
    - **txGas** (number) - The gas cost of the transaction.
    - **confirmedNum** (number) - The number of confirmations.
    - **status** (string) - The status of the transaction.

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": {
    "orderId": "order-123",
    "orderType": "PAYOUT",
    "status": "SUCCESS",
    "reason": "",
    "transaction": {
      "chain": "TRON",
      "symbol": "USDT",
      "blockNum": 73971843,
      "txid": "938d4d20f049bfe45f429f1c3cb62de7c57d3f7505ae691b79aa9a024f23ef87",
      "contractAddress": "TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t",
      "from": "TGyjjt1esfqJWrPncpygq3QA43epY46V8D",
      "to": "TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp",
      "amount": "100.00000000",
      "timestamp": 1752573867000,
      "txGas": 27.35985,
      "confirmedNum": 196573,
      "status": "SUCCESS"
    }
  }
}
```
```

--------------------------------

### Get Order Status

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Retrieve the status of a specific order using its order ID. The response includes detailed transaction information if available.

```typescript
const orderDetails = await xpay.getOrderStatus('order-123');

// Response structure
{
  code: 200,
  msg: 'Success',
  data: {
    orderId: 'order-123',
    orderType: 'PAYOUT',
    status: 'SUCCESS',
    reason: '',
    transaction: {
      chain: 'TRON',
      symbol: 'USDT',
      blockNum: 73971843,
      txid: '938d4d20f049bfe45f429f1c3cb62de7c57d3f7505ae691b79aa9a024f23ef87',
      contractAddress: 'TR7NHqjeKQxGTCi8q8ZY4pL8otSzgjLj6t',
      from: 'TGyjjt1esfqJWrPncpygq3QA43epY46V8D',
      to: 'TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp',
      amount: '100.00000000',
      timestamp: 1752573867000,
      txGas: 27.35985,
      confirmedNum: 196573,
      status: 'SUCCESS'
    }
  }
}
```

--------------------------------

### Initialize X-Pay SDK

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Initialize the SDK with your API key and secret. The base URL is optional and defaults to the production API.

```typescript
import { XPay } from 'xpay-sdk';

// Initialize the SDK with your API credentials
const xpay = new XPay({
  apiKey: 'your-api-token',
  apiSecret: 'your-api-secret',
  baseUrl: 'https://api.x-pay.fun', // Optional, defaults to production API
});
```

--------------------------------

### Configure SDK with Timeout

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Configure the SDK with an optional request timeout in milliseconds. This can prevent requests from hanging indefinitely.

```typescript
const xpay = new XPay({
  apiKey: 'your-api-token',
  apiSecret: 'your-api-secret',
  baseUrl: 'https://api.x-pay.fun', // Optional, defaults to production API
  timeout: 30000, // Optional, request timeout in milliseconds
});
```

--------------------------------

### Create Payout Order

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Create a payout order where the merchant sends cryptocurrency to a user. Ensure the user's receive address is correctly provided.

```typescript
async function createPayout() {
  try {
    const payout = await xpay.createPayout({
      amount: 100,
      symbol: 'USDT',
      chain: 'TRON',
      orderId: `order-${Date.now()}`, // Optional order ID
      uid: 'user123', // Required user ID
      receiveAddress: 'TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp' // User's wallet address
    });
    
    console.log('Payout created successfully:');
    console.log('- Code:', payout.code);
    console.log('- Message:', payout.msg);
    console.log('- Order ID:', payout.data?.orderId);
    
    return payout;
  } catch (error) {
    console.error('Error creating payout:', error);
  }
}
```

--------------------------------

### Create Payout Order

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Creates a cryptocurrency payout order, allowing merchants to send crypto to users. Requires amount, symbol, chain, user ID, and the user's receive address.

```APIDOC
## createPayout

### Description
Creates a cryptocurrency payout order where the merchant sends crypto to a user.

### Method
`POST` (inferred from SDK method usage)

### Endpoint
`/v1/payouts` (inferred from SDK method usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The amount of cryptocurrency to send.
- **symbol** (string) - Required - The symbol of the cryptocurrency (e.g., 'USDT').
- **chain** (string) - Required - The blockchain network (e.g., 'TRON').
- **orderId** (string) - Optional - A unique identifier for the order.
- **uid** (string) - Required - The user ID.
- **receiveAddress** (string) - Required - The user's wallet address to receive the funds.

### Request Example
```json
{
  "amount": 100,
  "symbol": "USDT",
  "chain": "TRON",
  "orderId": "order-123",
  "uid": "user123",
  "receiveAddress": "TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp"
}
```

### Response
#### Success Response (200)
- **code** (number) - The status code of the response.
- **msg** (string) - A message indicating the success or failure of the operation.
- **data** (object) - Contains details of the created payout order.
  - **orderId** (string) - The unique identifier for the order.
  - **status** (string) - The current status of the order (e.g., 'PENDING').
  - **amount** (string) - The amount of cryptocurrency in the order.
  - **symbol** (string) - The symbol of the cryptocurrency.
  - **chain** (string) - The blockchain network.
  - **uid** (string) - The user ID.
  - **receiveAddress** (string) - The recipient's wallet address.

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": {
    "orderId": "order-123",
    "status": "PENDING",
    "amount": "100.00000000",
    "symbol": "USDT",
    "chain": "TRON",
    "uid": "user123",
    "receiveAddress": "TXmVthgn6yT1kANGJHTHcbEGEKYDLLGJGp"
  }
}
```
```

--------------------------------

### Create Collection Order

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Create a collection order where the merchant receives cryptocurrency from a user. An order ID and user ID are required.

```typescript
const collection = await xpay.createCollection({
  amount: 50,
  symbol: 'USDT',
  chain: 'TRON',
  orderId: 'order-123', // Optional order ID
  uid: 'user123', // Required user ID
});

// Response structure
{
  code: 200,
  msg: 'Success',
  data: {
    orderId: 'order-123',
    address: 'TW8ArYLg5PuwYugmYM8QSux5oXxfUbXA8c',
    amount: '50.00000000',
    symbol: 'USDT',
    chain: 'TRON',
    uid: 'user123',
    expiredTime: 1753380643035
  }
}
```

--------------------------------

### Create Collection Order

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

Creates a cryptocurrency collection order, allowing merchants to receive crypto from users. Requires amount, symbol, chain, user ID, and an optional order ID.

```APIDOC
## createCollection

### Description
Creates a cryptocurrency collection order where the merchant receives crypto from a user. The response includes a unique address for the user to send funds to.

### Method
`POST` (inferred from SDK method usage)

### Endpoint
`/v1/collections` (inferred from SDK method usage)

### Parameters
#### Path Parameters
None

#### Query Parameters
None

#### Request Body
- **amount** (number) - Required - The amount of cryptocurrency to collect.
- **symbol** (string) - Required - The symbol of the cryptocurrency (e.g., 'USDT').
- **chain** (string) - Required - The blockchain network (e.g., 'TRON').
- **orderId** (string) - Optional - A unique identifier for the order.
- **uid** (string) - Required - The user ID.

### Request Example
```json
{
  "amount": 50,
  "symbol": "USDT",
  "chain": "TRON",
  "orderId": "order-123",
  "uid": "user123"
}
```

### Response
#### Success Response (200)
- **code** (number) - The status code of the response.
- **msg** (string) - A message indicating the success or failure of the operation.
- **data** (object) - Contains details of the created collection order.
  - **orderId** (string) - The unique identifier for the order.
  - **address** (string) - The unique wallet address generated for the user to send funds to.
  - **amount** (string) - The amount of cryptocurrency to be collected.
  - **symbol** (string) - The symbol of the cryptocurrency.
  - **chain** (string) - The blockchain network.
  - **uid** (string) - The user ID.
  - **expiredTime** (number) - The timestamp when the collection address expires.

#### Response Example
```json
{
  "code": 200,
  "msg": "Success",
  "data": {
    "orderId": "order-123",
    "address": "TW8ArYLg5PuwYugmYM8QSux5oXxfUbXA8c",
    "amount": "50.00000000",
    "symbol": "USDT",
    "chain": "TRON",
    "uid": "user123",
    "expiredTime": 1753380643035
  }
}
```
```

--------------------------------

### Verify and Parse Webhook with Express.js

Source: https://github.com/x-pay-official/xpay-node-sdk/blob/main/README.md

This snippet demonstrates how to verify and parse incoming webhook events using Express.js. It checks the signature and timestamp before processing the event data.

```typescript
app.post('/webhook', express.json(), (req, res) => {
  const webhookData = req.body;
  const signature = webhookData.sign;
  const timestamp = webhookData.timestamp.toString();
  const body = JSON.stringify(webhookData);
  
  const event = xpay.parseWebhook(body, signature, timestamp);
  
  if (!event) {
    return res.status(400).send('Invalid webhook signature or timestamp expired');
  }
  
  // Process the webhook event
  switch (event.notifyType) {
    case 'ORDER_SUCCESS':
      // Handle order success notification
      const orderData = event.data;
      console.log(`Order ${orderData.orderId} completed successfully!`);
      break;
    case 'COLLECT_SUCCESS':
      // Handle collection success notification
      const collectData = event.data;
      console.log(`Collection completed successfully! Amount: ${collectData.collectAmount}`);
      break;
    // Handle other notification types...
  }
  
  res.status(200).send('Webhook received');
});
```
Tokens:
Raw