client3xui

package module
v1.0.5 Latest Latest
Warning

This package is not in the latest version of its module.

 Go to latest Published: Jul 17, 2025 License: Apache-2.0 Imports: 14 Imported by: 0

README

client3xui

Go report GoDoc License

3X-UI API wrapper in Go brought to you by:

Digilol offers managed hosting and software development

Examples

VMESS + TCP
package main

import (
        "context"
        "fmt"
        "log"

        "github.com/digilolnet/client3xui"
)

func main() {
        server := client3xui.New(client3xui.Config{
                Url:      "https://xrayserver.tld:8843",
                Username: "digilol",
                Password: "secr3t",
        })

        // Get server status
        status, err := server.ServerStatus(context.Background())
        if err != nil {
                log.Fatal(err)
        }
        fmt.Println(status)

        //Add new inbound
        inbound := client3xui.InboundSetting{
                Up:         "0",
                Down:       "0",
                Total:      "0",
                Remark:     "",
                Enable:     "true",
                ExpiryTime: "0",
                Listen:     "",
                Port:       "13337",
                Protocol:   "vmess",
        }

        proto := client3xui.VmessSetting{
                Clients: []client3xui.ClientOptions{
                        client3xui.ClientOptions{
                                ID:     uuid.NewString(),
                                Email:  "niceclient",
                                Enable: true,
                                SubId:  "dhgsyf6384j9u889hd89edhlj",
                        },
                },
        }

        tcp := client3xui.TcpStreamSetting{
                Network:  "tcp",
                Security: "none",
                TcpSettings: client3xui.TcpSetting{
                        Header: client3xui.HeaderSetting{
                                Type: "none",
                        },
                },
        }

        snif := client3xui.SniffingSetting{
                Enabled:      true,
                DestOverride: []string{"http", "tls", "quic", "fakedns"},
        }

        ret, err := client3xui.AddInbound(context.Background(), server, inbound, proto, tcp, snif)
        if err != nil {
                log.Fatal(err)
        }

        // Add new client
        clis := []client3xui.XrayClient{
                {ID: "fab5a8c0-89b4-43a8-9871-82fe6e2c8c8a",
                Email:  "fab5a8c0-89b4-43a8-9871-82fe6e2c8c8a",
                Enable: true},
        }
        resp, err := server.AddClient(context.Background(), 1, clis)
        if err != nil {
                log.Fatal(err)
        }
        fmt.Println(*resp)
}
VLESS + REALITY + XHTTP
package main

import (
        "context"
        "fmt"
        "log"

        "github.com/google/uuid"
        "github.com/digilolnet/client3xui"
)

func main() {
        server := client3xui.New(client3xui.Config{
                Url:      "https://xrayserver.tld:8843/panelpath",
                Username: "digilol",
                Password: "secr3t",
        })


        // Get server status
        status, err := server.ServerStatus(context.Background())
        if err != nil {
                log.Fatal(err)
        }
        fmt.Println(status)

        // Get new X25519 certificate for Reality
        cert, err := server.GetNewX25519Cert(context.Background())
        if err != nil {
                log.Fatal(err)
        }

        // Add new inbound
        inbound := client3xui.InboundSetting{
                Up:         "0",
                Down:       "0",
                Total:      "0",
                Remark:     "",
                Enable:     "true",
                ExpiryTime: "0",
                Listen:     "",
                Port:       "10600",
                Protocol:   "vless",
        }

        proto := client3xui.VlessSetting{
                Clients: []client3xui.ClientOptions{
                        {
                                ID:     uuid.NewString(),
                                Flow:   "",
                                Email:  "realityclient",
                                Enable: true,
                                SubId:  "81h6cr12m5w0wm6i",
                        },
                },
                Decryption: "none",
                Fallbacks:  []client3xui.FallbackOptions{},
        }

        stream := client3xui.XhttpStreamSetting{
                Network:       "xhttp",
                Security:     "reality",
                ExternalProxy: []string{},
                RealitySettings: client3xui.RealitySettings{
                        Show:        false,
                        Xver:        0,
                        Dest:        "yahoo.com:443",
                        ServerNames: []string{"yahoo.com", "www.yahoo.com"},
                        PrivateKey:  cert.Obj.PrivateKey,
                        MinClient:   "",
                        MaxClient:   "",
                        MaxTimediff: 0,
                        ShortIds:    []string{client3xui.GenerateShortId(14), client3xui.GenerateShortId(2), client3xui.GenerateShortId(16)},
                        Settings: client3xui.RealitySettingsInner{
                                PublicKey:   cert.Obj.PublicKey,
                                Fingerprint: "chrome",
                                ServerName:  "",
                                SpiderX:     "/",
                        },
                },
                XhttpSettings: client3xui.XhttpSetting{
                        Path:               "/",
                        Host:               "",
                        Headers:            map[string]string{},
                        ScMaxBufferedPosts: 30,
                        ScMaxEachPostBytes: "1000000",
                        NoSSEHeader:        false,
                        XPaddingBytes:      "100-1000",
                        Mode:               "auto",
                },
        }

        snif := client3xui.SniffingSetting{
                Enabled:      false,
                DestOverride: []string{"http", "tls", "quic", "fakedns"},
                MetadataOnly: false,
                RouteOnly:    false,
        }

        ret, err := client3xui.AddInbound[client3xui.VlessSetting, client3xui.XhttpStreamSetting](
                context.Background(),
                server,
                inbound,
                proto,
                stream,
                snif,
        )
        if err != nil {
                log.Fatal(err)
        }
        log.Printf("%v", ret)
}
Development process
Method Path Action Done
GET "/list" Get all inbounds ✅
GET "/get/:id" Get inbound with inbound.id ✅
GET "/getClientTraffics/:email" Get Client Traffics with email ⛔️
GET "/getClientTrafficsById/:id" Get client's traffic By ID ⛔️
GET "/createbackup" Telegram bot sends backup to admins ⛔️
POST "/add" Add inbound ✅
POST "/del/:id" Delete Inbound ✅
POST "/update/:id" Update Inbound ⛔️
POST "/clientIps/:email" Client Ip address ⛔️
POST "/clearClientIps/:email" Clear Client Ip address ⛔️
POST "/addClient" Add Client to inbound ✅
POST "/:id/delClient/:clientId" Delete Client by clientId* ✅
POST "/updateClient/:clientId" Update Client by clientId* ✅
POST "/:id/resetClientTraffic/:email" Reset Client's Traffic ⛔️
POST "/resetAllTraffics" Reset traffics of all inbounds ⛔️
POST "/resetAllClientTraffics/:id" Reset traffics of all clients in an inbound ⛔️
POST "/delDepletedClients/:id" Delete inbound depleted clients (-1: all) ⛔️
POST "/onlines" Get Online users ( list of emails ) ✅

Documentation

Index

Constants

This section is empty.

Variables

This section is empty.

Functions

func GenerateShortId 

func GenerateShortId(length int) string

Specified in hex strings, with the length as multiples of 2. Cannot be longer than 16 characters.

Types

type AddClientRequest 

type AddClientRequest struct {
	// Inbound ID
	ID uint `json:"id"`

	// See ClientSettings. This is it marshaled into an escaped JSON string.
	Settings string `json:"settings"`
}

type ApiResponse 

type ApiResponse struct {
	Success bool            `json:"success"`
	Msg     string          `json:"msg"`
	Obj     json.RawMessage `json:"obj"`
}

Generic API response

func AddInbound 

func AddInbound[T VlessSetting | VmessSetting, K TcpStreamSetting | QuicStreamSetting | XhttpStreamSetting](ctx context.Context, c *Client, inOpt InboundSetting, pOpt T, strOpt K, sniOpt SniffingSetting) (*ApiResponse, error)

type Client 

type Client struct {
	// contains filtered or unexported fields
}

func New 

func New(c Config) *Client

func (*Client) AddClient 

func (c *Client) AddClient(ctx context.Context, inboundId uint, clients []XrayClient) (*ApiResponse, error)

Add client to an inbound.

func (*Client) DeleteClient 

func (c *Client) DeleteClient(ctx context.Context, inboundId uint, clientUuid string) (*ApiResponse, error)

Add client to an inbound.

func (*Client) Do 

func (c *Client) Do(ctx context.Context, method, path string, in, out interface{}) error

func (*Client) DoForm 

func (c *Client) DoForm(ctx context.Context, method, path string, form url.Values, out interface{}) error

func (*Client) DoRaw 

func (c *Client) DoRaw(ctx context.Context, method, baseurl, path, contentType string, body []byte) ([]byte, error)

func (*Client) EditPanelSettings 

func (c *Client) EditPanelSettings(ctx context.Context, settings PanelSettings) error

func (*Client) GetClientByEmail added in v1.0.5 

func (c *Client) GetClientByEmail(ctx context.Context, email string) (*ClientStat, error)

func (*Client) GetInbound 

func (c *Client) GetInbound(ctx context.Context, inbound_id uint) (*GetInboundResponse, error)

func (*Client) GetInbounds 

func (c *Client) GetInbounds(ctx context.Context) (*GetInboundsResponse, error)

func (*Client) GetNewX25519Cert 

func (c *Client) GetNewX25519Cert(ctx context.Context) (*X25519Response, error)

Get keys for use in inbound creation

func (*Client) GetOnlineClients 

func (c *Client) GetOnlineClients(ctx context.Context) ([]string, error)

Get online clients. Returns a slice of client IDs/emails.

func (*Client) GetPanelSettings 

func (c *Client) GetPanelSettings(ctx context.Context) (*PanelSettingsResponse, error)

func (*Client) GetSubJson 

func (c *Client) GetSubJson(ctx context.Context, subID string) ([]byte, error)

func (*Client) RestartPanel 

func (c *Client) RestartPanel(ctx context.Context) (*ApiResponse, error)

func (*Client) ServerStatus 

func (c *Client) ServerStatus(ctx context.Context) (*ServerStatusResponse, error)

func (*Client) UpdateClient 

func (c *Client) UpdateClient(ctx context.Context, inboundId uint, clientId string, clients []XrayClient) (*ApiResponse, error)

Update client in inbound.

type ClientOptions 

type ClientOptions struct {
	ID         string `json:"id"`
	Flow       string `json:"flow"`
	Email      string `json:"email"`
	LimitIp    int    `json:"limitIp"`
	TotalGb    int    `json:"totalGB"`
	ExpiryTime int    `json:"expiryTime"`
	Enable     bool   `json:"enable"`
	TgId       string `json:"tgId"`
	SubId      string `json:"subId"`
	Reset      int    `json:"reset"`
}

type ClientSettings 

type ClientSettings struct {
	Clients []XrayClient `json:"clients"`
}

type ClientStat 

type ClientStat struct {
	ID         int    `json:"id"`
	InboundID  int    `json:"inboundId"`
	Enable     bool   `json:"enable"`
	Email      string `json:"email"`
	Up         int    `json:"up"`
	Down       int    `json:"down"`
	ExpiryTime int    `json:"expiryTime"`
	Total      int    `json:"total"`
	Reset      int    `json:"reset"`
}

type Config 

type Config struct {
	Url, SubUrl, Host  string
	Username, Password string
	Client             *http.Client
}

type FallbackOptions 

type FallbackOptions struct {
	Name string `json:"name"`
	Alpn string `json:"alpn"`
	Path string `json:"path"`
	Dest string `json:"dest"`
	Xver int    `json:"xver"`
}

type GetClientResponse added in v1.0.5 

type GetClientResponse struct {
	Success bool       `json:"success"`
	Msg     string     `json:"msg"`
	Obj     ClientStat `json:"obj"`
}

type GetInboundResponse 

type GetInboundResponse struct {
	Success bool    `json:"success"`
	Msg     string  `json:"msg"`
	Obj     Inbound `json:"obj"`
}

type GetInboundsResponse 

type GetInboundsResponse struct {
	Success bool      `json:"success"`
	Msg     string    `json:"msg"`
	Obj     []Inbound `json:"obj"`
}

type HeaderSetting 

type HeaderSetting struct {
	Type string `json:"type"`
}

type Inbound 

type Inbound struct {
	ID             int          `json:"id"`
	Up             int          `json:"up"`
	Down           int          `json:"down"`
	Total          int          `json:"total"`
	Remark         string       `json:"remark"`
	Enable         bool         `json:"enable"`
	ExpiryTime     int          `json:"expiryTime"`
	ClientStats    []ClientStat `json:"clientStats"`
	Listen         string       `json:"listen"`
	Port           int          `json:"port"`
	Protocol       string       `json:"protocol"`
	Settings       string       `json:"settings"`
	StreamSettings string       `json:"streamSettings"`
	Tag            string       `json:"tag"`
	Sniffing       string       `json:"sniffing"`
}

type InboundSetting 

type InboundSetting struct {
	Up, Down, Total, Remark, Enable, ExpiryTime, Listen, Port, Protocol string
}

type PanelSettings 

type PanelSettings struct {
	WebListen        string `json:"webListen"`
	WebDomain        string `json:"webDomain"`
	WebPort          int    `json:"webPort"`
	WebCertFile      string `json:"webCertFile"`
	WebKeyFile       string `json:"webKeyFile"`
	WebBasePath      string `json:"webBasePath"`
	SessionMaxAge    int    `json:"sessionMaxAge"`
	PageSize         int    `json:"pageSize"`
	ExpireDiff       int    `json:"expireDiff"`
	TrafficDiff      int    `json:"trafficDiff"`
	RemarkModel      string `json:"remarkModel"`
	TgBotEnable      bool   `json:"tgBotEnable"`
	TgBotToken       string `json:"tgBotToken"`
	TgBotProxy       string `json:"tgBotProxy"`
	TgBotChatId      string `json:"tgBotChatId"`
	TgRunTime        string `json:"tgRunTime"`
	TgBotBackup      bool   `json:"tgBotBackup"`
	TgBotLoginNotify bool   `json:"tgBotLoginNotify"`
	TgCpu            int    `json:"tgCpu"`
	TgLang           string `json:"tgLang"`
	TimeLocation     string `json:"timeLocation"`
	SecretEnable     bool   `json:"secretEnable"`
	SubEnable        bool   `json:"subEnable"`
	SubListen        string `json:"subListen"`
	SubPort          int    `json:"subPort"`
	SubPath          string `json:"subPath"`
	SubDomain        string `json:"subDomain"`
	SubCertFile      string `json:"subCertFile"`
	SubKeyFile       string `json:"subKeyFile"`
	SubUpdates       int    `json:"subUpdates"`
	SubEncrypt       bool   `json:"subEncrypt"`
	SubShowInfo      bool   `json:"subShowInfo"`
	SubURI           string `json:"subURI"`
	SubJsonPath      string `json:"subJsonPath"`
	SubJsonURI       string `json:"subJsonURI"`
	SubJsonFragment  string `json:"subJsonFragment"`
	SubJsonMux       string `json:"subJsonMux"`
	SubJsonRules     string `json:"subJsonRules"`
	Datepicker       string `json:"datepicker"`
}

type PanelSettingsResponse 

type PanelSettingsResponse struct {
	Success bool           `json:"success"`
	Msg     string         `json:"msg"`
	Obj     *PanelSettings `json:"obj"`
}

type ProcessState 

type ProcessState string
const (
	Running ProcessState = "running"
	Stop    ProcessState = "stop"
	Error   ProcessState = "error"
)

type QuicSetting 

type QuicSetting struct {
	Security string        `json:"security"`
	Key      string        `json:"key"`
	Header   HeaderSetting `json:"header"`
}

QUIC was deprecated in favor of XHTTP in Xray-core v24.9.30

type QuicStreamSetting 

type QuicStreamSetting struct {
	Network       string      `json:"network"`
	Security      string      `json:"security"`
	ExternalProxy []string    `json:"externalProxy"`
	QuicSettings  QuicSetting `json:"quicSettings"`
}

type RealitySettings 

type RealitySettings struct {
	Show        bool                 `json:"show"`
	Xver        int                  `json:"xver"`
	Dest        string               `json:"dest"`
	ServerNames []string             `json:"serverNames"`
	PrivateKey  string               `json:"privateKey"`
	MinClient   string               `json:"minClient"`
	MaxClient   string               `json:"maxClient"`
	MaxTimediff int                  `json:"maxTimediff"`
	ShortIds    []string             `json:"shortIds"`
	Settings    RealitySettingsInner `json:"settings"`
}

type RealitySettingsInner 

type RealitySettingsInner struct {
	PublicKey   string `json:"publicKey"`
	Fingerprint string `json:"fingerprint"`
	ServerName  string `json:"serverName"`
	SpiderX     string `json:"spiderX"`
}

type ServerStatusResponse 

type ServerStatusResponse struct {
	Success bool   `json:"success"`
	Msg     string `json:"msg"`
	Obj     *struct {
		Cpu         float64 `json:"cpu"`
		CpuCores    int     `json:"cpuCores"`
		CpuSpeedMhz float64 `json:"cpuSpeedMhz"`
		Mem         struct {
			Current uint64 `json:"current"`
			Total   uint64 `json:"total"`
		} `json:"mem"`
		Swap struct {
			Current uint64 `json:"current"`
			Total   uint64 `json:"total"`
		} `json:"swap"`
		Disk struct {
			Current uint64 `json:"current"`
			Total   uint64 `json:"total"`
		} `json:"disk"`
		Xray struct {
			State    ProcessState `json:"state"`
			ErrorMsg string       `json:"errorMsg"`
			Version  string       `json:"version"`
		} `json:"xray"`
		Uptime   uint64    `json:"uptime"`
		Loads    []float64 `json:"loads"`
		TcpCount int       `json:"tcpCount"`
		UdpCount int       `json:"udpCount"`
		NetIO    struct {
			Up   uint64 `json:"up"`
			Down uint64 `json:"down"`
		} `json:"netIO"`
		NetTraffic struct {
			Sent uint64 `json:"sent"`
			Recv uint64 `json:"recv"`
		} `json:"netTraffic"`
		PublicIP struct {
			IPv4 string `json:"ipv4"`
			IPv6 string `json:"ipv6"`
		} `json:"publicIP"`
		AppStats struct {
			Threads uint32 `json:"threads"`
			Mem     uint64 `json:"mem"`
			Uptime  uint64 `json:"uptime"`
		} `json:"appStats"`
	} `json:"obj"`
}

type SniffingSetting 

type SniffingSetting struct {
	Enabled      bool     `json:"enabled"`
	DestOverride []string `json:"destOverride"`
	MetadataOnly bool     `json:"metadataOnly"`
	RouteOnly    bool     `json:"routeOnly"`
}

type TcpSetting 

type TcpSetting struct {
	AcceptProxyProtocol bool          `json:"acceptProxyProtocol"`
	Header              HeaderSetting `json:"header"`
}

type TcpStreamSetting 

type TcpStreamSetting struct {
	Network       string     `json:"network"`
	Security      string     `json:"security"`
	ExternalProxy []string   `json:"externalProxy"`
	TcpSettings   TcpSetting `json:"tcpSettings"`
}

type UpdateClientRequest 

type UpdateClientRequest struct {
	// Inbound ID
	ID uint `json:"id"`

	// See ClientSettings. This is it marshaled into an escaped JSON string.
	Settings string `json:"settings"`
}

type VlessSetting 

type VlessSetting struct {
	Clients    []ClientOptions   `json:"clients"`
	Decryption string            `json:"decryption"`
	Fallbacks  []FallbackOptions `json:"fallbacks"`
}

type VmessSetting 

type VmessSetting struct {
	Clients []ClientOptions `json:"clients"`
}

type X25519Response 

type X25519Response struct {
	Success bool   `json:"success"`
	Msg     string `json:"msg"`
	Obj     struct {
		PrivateKey string `json:"privateKey"`
		PublicKey  string `json:"publicKey"`
	} `json:"obj"`
}

type XhttpSetting 

type XhttpSetting struct {
	Path               string            `json:"path"`
	Host               string            `json:"host"`
	Headers            map[string]string `json:"headers"`
	ScMaxBufferedPosts int               `json:"scMaxBufferedPosts"`
	ScMaxEachPostBytes string            `json:"scMaxEachPostBytes"`
	NoSSEHeader        bool              `json:"noSSEHeader"`
	XPaddingBytes      string            `json:"xPaddingBytes"`
	Mode               string            `json:"mode"`
}

type XhttpStreamSetting 

type XhttpStreamSetting struct {
	Network         string          `json:"network"`
	Security        string          `json:"security"`
	ExternalProxy   []string        `json:"externalProxy"`
	RealitySettings RealitySettings `json:"realitySettings"`
	XhttpSettings   XhttpSetting    `json:"xhttpSettings"`
}

type XrayClient 

type XrayClient struct {
	ID         string `json:"id"`
	AlterID    uint   `json:"alter_id,omitempty"`
	Email      string `json:"email"`
	LimitIP    uint   `json:"limitIp"`
	TotalGB    uint64 `json:"totalGB"`
	ExpiryTime int64  `json:"expiryTime"`
	Enable     bool   `json:"enable"`
	TgID       uint   `json:"tgId"`
	SubID      string `json:"subId"`
	Flow       string `json:"flow"`
}

Source Files

View all Source files

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
y or Y : Canonical URL
go.dev uses cookies from Google to deliver and enhance the quality of its services and to analyze traffic. Learn more.