V2Ray Subscription Formats: Base64, Native JSON, and vmess:// Links

1. Subscription URLs, Base64, and JSON are different layers

A subscription URL copied into a client is usually an HTTPS URL. The client retrieves the node list or configuration only after accessing it. A .json suffix does not determine the format; the same endpoint may return different content depending on request parameters or the client identifier. Check the actual response when troubleshooting, not just the filename.

A common Base64 subscription is made by placing multiple share links on separate lines and Base64-encoding the resulting UTF-8 text. This does not turn the nodes into a different protocol or provide confidentiality. Anyone who obtains the content can usually recover server addresses and authentication details, so treat the subscription URL as a credential.

2. vmess://: Base64 wrapper and inner node JSON

A common VMess share link consists of vmess:// followed by a Base64 string that decodes to a node description object. The example below shows the decoded content. The domain and UUID are for illustration only and will not connect to a server. The value "2" for v identifies the share format version, not the core version.

{
  "v": "2",
  "ps": "Sample VMess WS",
  "add": "node.example.net",
  "port": "443",
  "id": "e7c3a416-5c9e-4f2b-9d81-73d14a9b8620",
  "aid": "0",
  "scy": "auto",
  "net": "ws",
  "type": "none",
  "host": "node.example.net",
  "path": "/gateway",
  "tls": "tls",
  "sni": "node.example.net"
}

This JSON is not a configuration that can be passed directly to the core. It lacks a complete outbounds hierarchy, and its field names are shortened for the share-link format. To convert it to a native config, map add to the server address, put the user information in the appropriate protocol user array, and build the transport and TLS settings separately.

3. vless://: UUID, query parameters, and labels

VLESS share links usually use a URI format rather than wrapping an entire JSON object in Base64. The example below demonstrates VLESS over TCP + TLS. It does not use REALITY or configure Vision flow control.

vless://[email protected]:443?encryption=none&security=tls&type=tcp&sni=node.example.net#VLESS%20TLS%20Example

• The UUID comes after vless:// and before @; the server address and port follow @. IPv6 addresses must be enclosed in square brackets in a URI.
• encryption=none means VLESS does not encrypt the payload at this layer. This example still protects the connection with TLS via security=tls.
• type=tcp specifies the transport type, and sni sets the TLS server name. Transport names may appear differently across client and core versions.
• The display label follows #, and %20 represents a space. The label is not used for server authentication.
• Use flow=xtls-rprx-vision only when the server, transport combination, and core all support it. It is not a parameter to add to every VLESS link.

For a REALITY node, check security=reality, pbk, sid, fp, and sni in the link individually. These values cannot be derived from the UUID or server address, nor can they be filled in automatically by converting VMess to VLESS. Use the target client and core version as the authority for the resulting core fields.

4. Decode and re-encode a Base64 subscription locally

A subscription may contain access tokens and valid UUIDs. When handling real data, use a local text editor or the developer tools in a blank browser page. Do not upload it to an unknown conversion site. The function below only converts the input string; it makes no network requests and does not require you to paste a subscription URL.

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

function encodeBase64Utf8(input) {
  const bytes = new TextEncoder().encode(input);
  let binary = "";
  for (const byte of bytes) binary += String.fromCharCode(byte);
  return btoa(binary);
}

const demoLink =
  "vless://[email protected]:443" +
  "?encryption=none&security=tls&type=tcp&sni=node.example.net#Example";

const subscription = encodeBase64Utf8(demoLink + "\n");
console.log(subscription);
console.log(decodeBase64Utf8(subscription));

This code supports common Base64URL character substitutions and restores missing padding. UTF-8 conversion is needed to handle labels containing non-ASCII characters correctly; calling btoa() directly on such text may throw an error. Read and understand the code before running it, and avoid leaving real credentials in the console history on a shared device.

1. After retrieving the subscription response body, check whether it already starts with vmess:// or vless://. If it contains plain-text links, there is no need to decode an outer layer.
2. If the content is Base64, decode it once and split it by line breaks. Remove blank lines, but do not delete valid characters within a URI or change the case of a case-sensitive path.
3. For each vmess:// link, remove the prefix, call the decoding function on that link alone, then use JSON.parse() to inspect the object structure.
4. To rebuild a list subscription, join the complete share links with line breaks and encode the result. Do not encode the node names shown in the interface.

If the response starts with <!DOCTYPE html>, check whether you are signed in, whether the URL has expired, or whether the endpoint returned an error page. If decoding produces valid JSON, determine whether it is an error message, a node array, or a complete core configuration. Successful Base64 decoding only proves that the content can be recovered; it does not prove that it will connect.

5. Build native Xray JSON from a share link

The VLESS TLS example above is converted below into a minimal runtime configuration to illustrate its structure. It binds a SOCKS inbound to 127.0.0.1:10808 and connects to the example domain on port 443. No service is available at that address, so this config is for inspecting fields only. Before running it, replace the values with parameters provided by your server.

{
  "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.net",
            "port": 443,
            "users": [
              {
                "id": "e7c3a416-5c9e-4f2b-9d81-73d14a9b8620",
                "encryption": "none"
              }
            ]
          }
        ]
      },
      "streamSettings": {
        "network": "tcp",
        "security": "tls",
        "tlsSettings": {
          "serverName": "node.example.net",
          "allowInsecure": false
        }
      }
    }
  ]
}

This example does not define a separate routing section; requests use the first outbound by default. It also does not include routing rules or system proxy settings. Starting a SOCKS listener does not make every application on the system use it automatically. If 10808 is already in use by a desktop client, stop the duplicate instance or change the port.

“Native JSON” does not mean the format works across all cores. Xray and V2Fly share some configuration structures, but their protocol support and field development are not identical. For example, an Xray config that uses REALITY cannot be made compatible with V2Fly simply by changing the filename. A converter should clearly specify the input format, target core, and which parameters it covers.

6. Import into v2rayN: use separate steps for subscription URLs and clipboard links

The steps below refer to common menus in the Chinese-language interface of v2rayN 7.x; punctuation and menu locations may vary between minor versions. First identify whether you have an HTTPS subscription URL, a single share link, or a complete configuration file, then choose the matching import option. Pasting a webpage URL into the node import dialog often results in a message such as “No valid content.”

1. Add a subscription URL: Open “Subscription Group” → “Subscription Group Settings,” create a group, enter a label and the subscription URL provided by your provider, save it, then select the group.
2. Fetch the node list: From the “Subscription Group” menu, choose the option to update the current subscription. If a direct connection works, update without using a proxy first. If it times out but an existing proxy is available, try updating through the proxy.
3. Import a single link: Copy the complete vmess:// or vless:// link and choose “Servers” → “Import bulk URLs from clipboard.” Put multiple links on separate lines and keep each link intact.
4. Import a complete configuration: Find the custom configuration import option in the Servers menu, select a local JSON file, and choose the required core. Do not expect it to be split automatically into regular nodes that you can edit individually.
5. Verify that it runs: Set the node as active and reload. Check the logs for configuration parsing errors, port conflicts, or TLS handshake failures, then make a real web request.

A manually imported node is usually just a snapshot. If the provider later changes the address or UUID, the copied link will not update automatically. Updating a subscription may replace nodes in its group. Keep manual changes in a separate group to avoid mixing them with subscription-managed entries.

7. Subscription parsing and conversion FAQs

After conversion, verify in this order: the content parses, the fields map correctly, the core starts, and requests get through. Keep the original subscription or configuration for reference and make changes only to a copy. For more field details, see the configuration reference; for protocol names and transport terms, see the glossary.