V2Ray Subscription Formats: Base64, Native JSON, and Share Links

1. Subscription URLs, encoding, and node configs are different layers

“V2Ray subscription” isn’t a single, standardized file format. A client first requests the subscription URL, then parses the response body. Common responses contain multiple share links, either as plain lines or Base64-encoded as a whole. Some services return JSON instead. An HTTPS URL only describes how the content is retrieved; it doesn’t guarantee that a particular importer can read the response.

JSON is a syntax, not a configuration type. A VMess share object with add, id, and net can pass JSON syntax checks, but it can’t run directly as a complete Xray config. Conversely, Base64-encoding a complete config doesn’t automatically turn it into a node subscription supported by a client.

2. Base64 subscriptions: decode first, then parse each line

Traditional node subscriptions often join multiple share links with newline characters, then encode the entire UTF-8 text. The client decodes the response back into text and parses each line by protocol. A VMess link may also contain another layer of Base64 within the individual link, so successfully decoding the outer subscription doesn’t mean the inner node fields are valid.

1. Retrieve the response: Make sure you received subscription content, not a login page, access restriction notice, or server error page.
2. Check the outer layer: If the response already starts with a share link, treat it as plain text. Don’t decode it again blindly.
3. Decode the content: After decoding the outer Base64 layer, check that the result contains one link per line.
4. Parse the nodes: Identify the protocol on each line, then check the server address, port, user ID, and transport parameters.

Standard Base64 commonly uses + and /, and may end with = padding. Some sources use the URL-safe variant with - and _, or omit the trailing padding. Importers vary in how tolerant they are: missing equals signs alone don’t mean a subscription is corrupted, and Base64 should not be treated as URL percent-encoding.

// Local JavaScript example: input is the retrieved text containing multiple share links.
// TextEncoder / TextDecoder preserve Chinese node names.
function encodeSubscription(text) {
  const bytes = new TextEncoder().encode(text);
  let binary = "";
  for (const byte of bytes) {
    binary += String.fromCharCode(byte);
  }
  return btoa(binary);
}

function decodeSubscription(encoded) {
  let normalized = encoded.replace(/\s/g, "")
    .replace(/-/g, "+")
    .replace(/_/g, "/");
  normalized += "=".repeat((4 - normalized.length % 4) % 4);
  const binary = atob(normalized);
  const bytes = Uint8Array.from(binary, char => char.charCodeAt(0));
  return new TextDecoder("utf-8", { fatal: true }).decode(bytes);
}

This code converts text only; it doesn’t fetch subscriptions or check whether nodes can connect. If decoding fails, first check whether the content was truncated or copied along with explanatory text. Even after successful decoding, a client that supports the relevant protocol must parse the result. Calling btoa() directly on Chinese text in a browser may throw an error, so this example converts the text to UTF-8 bytes first.

3. VMess and VLESS share links: map the fields

A common vmess:// share-link format appends a Base64-encoded JSON object to the protocol prefix. The example below shows the object before encoding. It follows a common sharing convention and is not a complete core config. The domain and UUID illustrate the structure only; they aren’t usable node details.

{
  "v": "2",
  "ps": "Example VMess WS",
  "add": "node.example.org",
  "port": "443",
  "id": "2d1e7e18-49f4-4ab7-8b63-c929d11c5e29",
  "aid": "0",
  "scy": "auto",
  "net": "ws",
  "type": "none",
  "host": "node.example.org",
  "path": "/proxy",
  "tls": "tls",
  "sni": "node.example.org"
}

v identifies the share-object format, not the client version. ps is the remark; add and port specify the connection target; and net, host, and path describe the transport. The aid value here is zero; don’t infer that VLESS has a parameter with the same name. Share-link implementations may omit fields, so check the node editor after importing.

VLESS share links commonly use a URI structure: the user ID comes before @, the server and port follow it, query parameters describe transport and security settings, and the remark comes after #. The example below uses the same parameters as the JSON example later in this guide.

vless://[email protected]:443?encryption=none&security=tls&type=ws&host=node.example.org&path=%2Fproxy&sni=node.example.org#Example-WS

• security=tls means TLS is used for transport security. encryption=none is a VLESS parameter; the two settings don’t contradict each other.
• type=ws specifies WebSocket; path=%2Fproxy decodes to /proxy.
• host is the hostname in the WebSocket request header, while sni specifies the TLS server name. They may be the same, but shouldn’t be substituted for each other without checking.
• IPv6 addresses need square brackets in URIs. Encode remarks containing spaces, non-ASCII characters, or special symbols according to URI rules.

4. Native JSON: runtime settings beyond node parameters

A native Xray config describes how the entire process runs. Inbounds define where local applications connect; outbounds define how requests reach servers; routing and DNS control traffic selection and name resolution. The minimal config below illustrates the fields and uses VLESS, WebSocket, and TLS. Its example address does not provide a working service.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "tag": "local-socks",
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks",
      "settings": {
        "auth": "noauth",
        "udp": true
      }
    }
  ],
  "outbounds": [
    {
      "tag": "proxy",
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "node.example.org",
            "port": 443,
            "users": [
              {
                "id": "2d1e7e18-49f4-4ab7-8b63-c929d11c5e29",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "ws",
        "security": "tls",
        "tlsSettings": {
          "serverName": "node.example.org"
        },
        "wsSettings": {
          "path": "/proxy",
          "headers": {
            "Host": "node.example.org"
          }
        }
      }
    }
  ]
}

These ports serve different purposes. 10808 binds to the local loopback address; it’s only an example, not a setting used on every device. 443 is the remote listening port and must match the server. If another process is already listening on the same local address and port, a second config may fail to start.

• Link to JSON: Map the node parameters to an outbound, then explicitly add inbounds, DNS, and routing; share links usually don’t include these local settings.
• JSON to link: Extract parameters from an outbound that can be represented as a node. Multiple outbounds usually need to be handled separately; don’t assume they can be combined into one node.
• Preserve policies: routing, dns, inbound listeners, and logging settings usually don’t carry over to single-node share links.
• Core compatibility: Xray and V2Fly differ in supported fields and protocols. v2rayNG uses Xray, while v2flyNG uses V2Fly. The fact that both accept JSON doesn’t mean their configs are interchangeable.

5. v2rayN and v2rayNG: choose the right import option

Menu labels can vary by client version and interface language. The steps below use common menu names. Before importing, identify whether the clipboard contains a subscription URL, a single-node link, or a complete JSON config. In particular, don’t import an HTTPS subscription URL as a regular node link.

v2rayN: import subscription groups and individual nodes separately

1. Add a subscription group

   In the main window, go to “Subscription Group” → “Subscription Group Settings.” Select “Add,” enter a remark and subscription URL, then save. Keep all query parameters in the URL intact.

2. Update subscriptions

   Return to the “Subscription Group” menu and choose to update the current subscription or all subscriptions. If the menu offers updates through or without a proxy, choose based on what your current network can reach, then check the update log.

3. Import a single node

   Copy the complete vmess:// or vless:// link, then in the main window choose “Server” → “Import bulk URL from clipboard.” The common shortcut is Ctrl+V.

4. Check the connection settings

   Open the node editor and check the address, port, UUID, transport type, path, and TLS server name. A successful import means the link was parsed; it doesn’t mean the server is reachable.

v2rayNG: subscription groups and clipboard imports

• Subscription URL: Open the top-right menu → “Subscription Group Settings” → “+”, then enter a remark and URL. After saving, return to the main screen and select “Update Subscription” from the menu.
• Share links: Copy one or more links, then on the main screen tap “+” → “Import from clipboard.” Check the number of nodes and their remarks afterward.
• Complete JSON: Use the custom config import option available in your current version; don’t substitute the regular node editor. Android works differently from a desktop setup using a local SOCKS inbound, so don’t assume that copying the desktop inbound will route app traffic.

6. Conversion options: choose what to preserve

“Successful conversion” can mean at least three things: the text decodes, the client imports it, and the connection behaves as expected. Even when the first two succeed, routing, DNS, fingerprints, or extended transport parameters may be lost. Decide what needs to move first; that usually saves more troubleshooting time than hunting for a conversion button.

After migration, check the logs for config parsing or listener errors, then test an actual connection with a node. On desktop, also make sure the system proxy or app-level proxy points to the correct inbound. On Android, confirm the connection service has started and grant VPN interface permission when prompted. A speed test result and browser traffic routed through the proxy are two different checks.

7. Import and conversion FAQs