3x-ui Node.js SDK

The 3x-ui is a JavaScript library designed to facilitate communication with the 3x-ui panel, which runs Xray Core for proxy services. This SDK empowers JavaScript developers to create bots and websites for both commercial and non-commercial uses, providing simplicity, abstraction around the API, caching for improved performance, and mutex for asynchronous safety.

This package is developed based on MHSanaei Postman Collection and you can check it out for more information.

Features

• ✅ Simplicity: Designed with simplicity in mind to streamline the process of interacting with the 3x-ui panel.
• ✅ Abstraction: Provides an abstraction layer around the 3x-ui API to simplify finding clients by email, uuid (vmess, vless) or password (trojan).
• ✅ Proxy: Utilizes an underlying proxy agent for communication with the panel if needed.
• ✅ Caching: Caches responses for improved performance.
• ✅ Mutex: Provides a mutex, a lock mechanism, to ensure asynchronous safety and prevent race conditions.
• ✅ Debug Mode: Enables debug mode for detailed logging.
• ✅ TTL: Allows you to set the cache time in seconds.

Installation

To install the 3x-ui SDK, use npm:

npm install 3x-ui

Usage

First, import the SDK:

import { XuiApi } from "3x-ui";

Initialize the SDK with the URL of your 3x-ui panel:

const api = new XuiApi("http://username:password@localhost:2053");
api.debug = true; // Enables debug mode - defualt is false
api.stdTTL = 60; // Cache time in seconds - default is 10s

Then, you can utilize the SDK functions:

const inbounds = await api.getInbounds();
const clientStat = await api.getClient("email or clientId");
const clientOptions = await api.getClientOptions("email or clientId");
const onlines = await api.getOnlineClients();

Proxy

The SDK uses an underlying proxy agent to connect to the panel. You can specify the proxy settings using environment variables such as HTTP_PROXY and HTTPS_PROXY. Refer to the proxy-agent documentation for more information.

HTTP_PROXY="http://proxy-server-over-tcp.com:3128"
HTTPS_PROXY="https://proxy-server-over-tls.com:3129"

API

Inbounds

• getInbounds(): Returns an array of all inbounds.
• getInbound(id: number): Returns the inbound with the specified ID.
• addInbound(options: InboundOptions): Adds a new inbound with the provided options.
• updateInbound(id: number, options: Partial<InboundOptions>): Updates the inbound with the specified ID using the provided options.
• resetInboundsStat(): Resets statistics for all inbounds.
• resetInboundStat(id: number): Resets statistics for the inbound with the specified ID.
• deleteInbound(id: number): Deletes the inbound with the specified ID.

Clients

• getClient(clientId: string): Returns a client with the given email or clientId.
• getClientIps(clientId: string): Returns all client's IPs with the given email or clientId.
• getClientOptions(clientId: string): Returns all client's options with the given email or clientId.
• addClient(inboundId: number, options: ClientOptions): Adds a new client with the given options.
• updateClient(clientId: string, options: Partial<ClientOptions>): Updates a client with the given email or clientId.
• resetClientIps(clientId: string): Resets all client's IPs with the given email or clientId.
• resetClientStat(clientId: string): Resets a client's stat with the given email or clientId.
• deleteClient(clientId: string): Deletes a client with the given email or clientId.
• deleteDepletedClients(): Deletes all clients that have depleted their traffic.
• deleteInboundDepletedClients(inboundId: number): Deletes all clients of an inbound that have depleted their traffic.
• getOnlineClients(): Returns all online clients.

Other Functions

• sendBackup(): send backup file via Telegram bot.

Example

For more examples, check out the test directory on our GitHub repository.