XTLS Subscription Standards

[jomertix]

Dear community members,

I’m pleased to invite you to an open discussion of the new XTLS Subscription Standards.

This document proposes to structure and generalize existing solutions into a unified set of specifications for:

• Representing subscriptions in JSON format
• Defining request and response headers
• Specifying device identification (HWID) (optional)

FAQ:

Q: There is already the “XRAY-JSON Subscription | Proposal” - why do we need separate standards?
A: The original "XRAY-JSON Subscription | Proposal" was published some time ago, and much has changed since then. Several new headers - now supported by many Xray‑based clients - were not covered in the proposal. Moreover, the old proposal allowed ambiguities in certain headers and doesn’t address the evolving needs of both clients and service providers.

Q: What’s new compared to the old proposal?
A: Unlike the original proposal, the new standard introduces HWID headers for device identification and formalizes the use of the User-Agent request header. It also standardizes several server‑response headers: content-disposition, content-type, announce, and support-url and clarifies the handling of subscription-userinfo. All headers are now case‑insensitive, response parsing gives priority to the content-type header, and HTTP redirect behavior is explicitly defined.

Original repository: https://github.com/jomertix/xtls-subscription-standards/

---

Unified XTLS Subscription Standards

This specification defines a unified JSON‑based subscription format and accompanying HTTP headers for distributing XTLS
proxy configurations. It standardizes request/response semantics, device identification (HWID), and redirect handling to
improve interoperability across client implementations.

Table of Contents

1. Overview
2. Conventions & Scope
3. JSON Subscription Specification
4. Headers Specification
5. Device Identification (HWID) Specification

1. Overview

This specification consolidates existing XTLS subscription formats into a single, consistent JSON schema and a
standardized set of HTTP headers, with explicit rules for HTTPS,
content‑type, and redirects. It describes the key principles and requirements, provides usage examples of this
configuration distribution format, and defines
the behavior of client-side proxy applications when encountering this method of configuration delivery.

2. Conventions & Scope

2.1 Use of HTTPS

The client application MUST only process subscriptions if they are delivered over an encrypted channel (HTTPS).
If the proxy client receives such content in plain text (HTTP), it must reject it and return an error.

2.2 Case Sensitivity

All parameter names, header names, and string literals within the specification are case‑insensitive. Clients must
treat Key, key, and KEY as the same values.

2.3 Content‑Type Handling

When processing a subscription response, the client application must give priority to the format indicated by the HTTP
content-type header.
If the header is present and correctly specifies the response format (e.g., application/json, text/plain), the
client should parse accordingly.

Note: If content-type is missing, unrecognized, or inconsistent, the client should fall back to legacy parsing
logic for backward compatibility.

2.4 HTTP Redirect Semantics

Upon receiving a 301 or 308 response, clients MUST update the stored URL to the one in location and use it for all
subsequent requests.
Clients should also correctly handle other 3xx codes per the HTTP spec. For further details,
see MDN’s Redirection Messages reference

3. JSON Subscription Specification

Summary:
Defines the structure and semantics of the subscription JSON payload.

4. Headers Specification

Summary:
Outlines standard headers used for passing metadata and configuration context.

5. Device Identification (HWID) Specification

Summary:
Describes headers related to client and device identification.

Please note that the HWID proposal is optional and its implementation is left to the discretion of application
developers; however, if implemented, clients must fully adhere to all specified principles.

---

JSON Subscription Specification

1.1 General Structure

A subscription is defined as a JSON array of connection objects. Each object represents a complete, valid configuration based on the xray-core specification, and may include additional fields described in this document.

The HTTP response that delivers the subscription must include the header:
Content-Type: application/json
This ensures that the client correctly interprets the response body as a JSON structure.

The client application must expect the subscription to be structured as follows:

[
    {/* Configuration 1 */},
    {/* Configuration 2 */},
    {/* Configuration 3 */}
]

⚠️ Note: Configuration parameters defined within each connection object override any default values or global client settings.

Example:

[
    {
        "remarks": "CONNECT_1" ,
        "dns": {},
        "routing": {},
        "inbounds": [],
        "outbounds": [],
        // ... (Other configuration parameters) 
    },
    {
        "remarks": "CONNECT_2" ,
        "dns": {},
        "routing": {},
        "inbounds": [],
        "outbounds": [],
        // ... (Other configuration parameters) 
    }	
]

---

1.2 Connection Object

As we defined earlier, this array includes at least one or more elements. In our agreement, each individual element is a separate, isolated connection. Each element (connection) must comply with the requirements set forth in the xray-core documentation.

Example:

{
    "remarks":"Connect1",
    "routing": {
        "rules": [
            {
                "ip": [
                    "geoip:cn"
                ],
                "outboundTag": "direct"
            }
        ]
    },
    "inbounds": [
        {
            "listen": "127.0.0.1",
            "port": 10808,
            "protocol": "socks"
        },
        {
            "listen": "127.0.0.1",
            "port": 10809,
            "protocol": "http"
        }
    ],
    "outbounds": [
        {
            "protocol": "vless",
            "settings": {
                "vnext": [
                    {
                        "address": "",
                        "port": 443,
                        "users": [
                            {
                                "id": "name", 
                                "encryption": "none",
                                "flow": "xtls-rprx-vision"
                            }
                        ]
                    }
                ]
            },
            "streamSettings": {
                "network": "tcp",
                "security": "reality",
                "realitySettings": {
                    "fingerprint": "chrome",
                    "serverName": "www.lovelive-anime.jp", 
                    "publicKey": "Z84J2IelR9ch3k8VtlVhhs5ycBUlXA7wHBWcBrjqnAw", 
                    "shortId": "6ba85179e30d4fc2" 
                }
            },
            "tag": "proxy"
        },
        {
            "protocol": "freedom",
            "tag": "direct"
        }
    ]
}

---

1.2.1 remarks Field

To improve user experience, each element of the configuration array can contain a remark field:

remarks: string
Connection name

Each connection object may include a remarks field to provide a human-readable label for the client UI.

⚠️ Note: If this parameter is present, the proxy client must set the corresponding connection name in the GUI.

⚠️ Note: If this parameter is absent or its value is declared as NULL, the client is free to set the connection name at its own discretion.

---

Headers Specification

The article is organized into two sections: the first details the HTTP headers the client sends when performing a subscription-retrieval request, and the second lists the headers the server returns in its response, which may include additional meta-information headers allowing the user interface and client behavior to be extended without modifying the configuration file itself.

1 Client Request Headers

1.1 User-Agent

The User-Agent header identifies the client application making the request to help servers tailor responses or analytics. It’s recommended to follow the product/version syntax and include your app’s name, version, and OS details in the parentheses for clarity and compatibility. For more details, see the User-Agent header on MDN

2 Server Response Headers

2.1 content-disposition

This header is primarily intended for web browsers and similar clients that render or download content directly. It instructs the browser to prompt the user to download the file with a suggested filename. However, application-level clients (such as mobile or desktop apps) typically do not need to use or rely on this header — they should handle filenames and downloads programmatically. Therefore, content-disposition is mostly relevant in HTTP contexts involving human interaction, such as when a user clicks a download link in a browser.

This header is required.

---

2.2 content-type

The content-type header indicates the media type of the resource being sent. It helps the client understand how to process the content (e.g., application/json, text/plain, and etc.).

This header is required.

---

2.3 profile-title

profile-title: string
Profile name in base64 UTF8 encoding

Example:

profile-title: base64:0YXRg9C5

Note:
If this header is present, the client should set this value as the name of the subscription/group in the GUI.

Note:
If the value of this header is NULL, the client can set the name of the subscription/group at its own discretion.

This header is preferably required.

---

2.4 profile-update-interval

profile-update-interval: int
Automatic configuration file update interval in hours

Example:

profile-update-interval: 1

Note:
If this header is present, the client should set this automatic update interval for the subscription.

Note:
If the header is absent, the client is free to set the value at its own discretion.

This header is preferably required.

---

2.5 subscription-userinfo

Information about the group's traffic and expiration date. Each field is optional. For example, if the upload field is missing, the client application should not display it. The same rule applies to any other field.

Supported fields:
upload – number of bytes uploaded
download – number of bytes downloaded
total – total number of bytes
expire – date in Unix timestamp format (note: 0 does not mean “unlimited” or anything similar. 0 is a technically valid timestamp that refers to 00:00:00 UTC on January 1, 1970. In this case, the absence of the expire field means that the subscription has no expiration date.)

Example:

subscription-userinfo: upload=0; download=4460105213; total=2147483648; expire=1710442799

This header is preferably required.

---

2.6 profile-web-page-url

Header containing the subscription link

Example:

profile-web-page-url: https://example.com/sub

This header is optional.

---

2.7 announce

announce: string
Announce in base64 UTF8 encoding

The announce header is used to announce, broadcast an event, action, or deliver any other text message.

This header is optional.

Example:

announce: base64:0JLQn9CdINCd0JAg0KLQldCb0JXQktCY0JfQntCgINCh0KDQntCn0J3Qng==

This header is optional.

---

2.8 support-url

A link to the support or help page.

Example:

support-url: https://example.com/faq

This header is optional.

---

Device Info Headers Specification

When a subscription is requested, the client sends a set of HTTP headers that provide information about the device. These headers help the server identify and adapt to the client environment.

1.1 x-hwid

x-hwid: string
Unique device identifier (maximum length: 36 characters).

Example:

x-hwid: 4139def9-6877-4771-b313-49e3119ba158

This header is required.

---

1.2 x-device-os

x-device-os: string
Specifies the operating system of the device on which the client is running.

Example:

x-device-os: iOS

This header is optional.

---

1.3 x-ver-os

x-ver-os: string
The version of the device's operating system.

Example:

x-ver-os: 17.3.1

This header is optional.

---

1.4 x-device-model

x-device-model: string
The model name or identifier of the client device.

Example:

x-device-model: iPhone 15

This header is optional.