V2Ray Subscription Formats Explained: Base64, Native JSON, and Share-Link Conversion

Separate subscriptions, share links, and runtime configs first

A “subscription” usually means a URL that can be requested periodically. After the client accesses it, the server returns a set of nodes and the client stores them locally. The subscription URL itself is not a node; it is an ever-changing data source. The same URL might return 8 nodes today and 10 after the next update.

A “share link” represents a single node. Common links begin with vmess:// or vless:// and carry the server address, port, user ID, transport, and TLS parameters. Multiple share links can be placed one per line and encoded as a subscription response, but an individual link cannot update itself.

“Native JSON” usually means a runtime configuration readable by the V2Ray or Xray core. It contains objects such as inbounds, outbounds, routing, and dns, describing not only remote nodes but also local listening ports, traffic entry points, and routing behavior. Importing a complete runtime config as a regular subscription may not let the client extract a node list.

How to identify and decode a Base64 subscription

Traditional V2Ray subscription responses often join multiple share links with newlines and then Base64-encode the complete UTF-8 text. When opened directly in a browser, the subscription URL may show a long string made up of letters, numbers, plus signs, slashes, and equals signs. Only after decoding the outer layer do line-by-line vmess:// or vless:// links appear.

Do not judge solely by whether a string “looks like Base64.” Plain text, compressed data, and some URL-safe encodings can look similar. A reliable approach is to inspect the response content type and first few characters, then try decoding. The result should be valid UTF-8 text, with a recognizable protocol prefix on every non-empty line. If decoding still produces encoded text, check for double encoding instead of decoding repeatedly without verification.

Typical structure after outer decoding

vmess://encoded single-node data
vless://[email protected]:443?encryption=none&security=tls&type=ws&path=%2Fedge#A-WS
vless://[email protected]:443?encryption=none&security=reality&type=tcp&flow=xtls-rprx-vision#B-TCP

The examples above show the structure only and do not provide usable credentials. In practice, split the response on newline characters and support both Unix LF and Windows CRLF. Empty lines can be ignored, but trim leading and trailing spaces first. If the server response does not end with a newline, the final link must still be parsed.

Base64 has standard and URL-safe alphabets. The standard form uses plus and slash, while the URL-safe form uses hyphens and underscores; trailing equals padding may also be omitted. Mature clients usually handle these differences, but manual processing should normalize the alphabet and restore padding first. If the encoded length leaves a remainder of 2 when divided by 4, add two equals signs; if the remainder is 3, add one; a remainder of 1 usually means the text is truncated.

• The HTTP status should indicate success; if the request redirects to a login or error page, do not treat the HTML as subscription content.
• Decode the result as UTF-8; an incorrect character set can garble Chinese node remarks.
• Put exactly one share link on each line; do not insert manual line breaks inside a link.
• If an update changes the node count from 12 to 0, preserve the original group first, then check whether the response is empty.
• A subscription URL should be treated as sensitive data. Do not paste it into public pages or uncontrolled conversion services.

VMess and VLESS share-link fields

VMess and VLESS share links use different encoding methods. A common VMess link places a Base64-encoded JSON object after vmess://. The object may contain fields such as add, port, id, net, path, host, tls, and sni. Some older formats also include v, ps, and aid; the commonly used config version is 2, while aid is usually 0 in modern deployments.

A VLESS share link is closer to a standard URI: the user ID occupies the username area, the server address and port occupy the host area, transport and security parameters go in the query string, and the node remark appears in the fragment after the hash. For example, type=ws means WebSocket, security=tls means TLS, and path=%2Fedge decodes to /edge. Parameter order usually does not affect meaning, but names and values must be URL-encoded correctly.

Conversion is not just a prefix change

VMess and VLESS are different protocols, so you cannot simply change vmess:// to vless://. Even when the server address, port, and transport layer match, the server must provide an inbound for the target protocol and the user authentication method must match. More precisely, “conversion” maps shared connection parameters to another link structure when the server is known to support the target protocol.

Transport fields must be mapped by meaning. For example, net=ws in VMess JSON can map to type=ws in VLESS, and path=/edge must become a URL-encoded query parameter. However, the public key, short ID, fingerprint, and Flow required by Reality do not exist in a traditional VMess + TLS link, so a converter cannot invent them.

How to organize native JSON and share links

When extracting a share link from native JSON, first locate an outbound in outbounds whose protocol is VMess or VLESS, then read its server, port, and user fields. Next inspect streamSettings: network determines the transport type, security determines TLS or Reality, and the specific WebSocket, gRPC, or TCP settings are stored in the corresponding child object.

When generating JSON in the opposite direction, a share link can restore only the remote outbound and its transport parameters. It usually cannot provide a local SOCKS port, HTTP port, DNS servers, log level, or complete routing rules. After converting a share link to JSON, the client or config generator must supply the local section. A common local setup uses a SOCKS listener at 127.0.0.1:10808 and an HTTP listener at 127.0.0.1:10809; use the ports configured by the current client.

{
  "log": {
    "loglevel": "warning"
  },
  "inbounds": [
    {
      "listen": "127.0.0.1",
      "port": 10808,
      "protocol": "socks"
    }
  ],
  "outbounds": [
    {
      "protocol": "vless",
      "settings": {
        "vnext": [
          {
            "address": "node.example",
            "port": 443,
            "users": [
              {
                "id": "example value hidden",
                "encryption": "none"
              }
            ]
          }
        ]
      }
    }
  ]
}

This JSON snippet illustrates the hierarchy only. A real configuration also needs streamSettings matching the node and may require additional direct and block outbounds. If you import a config without transport settings while the server actually uses WebSocket + TLS, the core will attempt a mismatched default transport; logs usually show a closed connection or handshake failure.

Exporting a single-node link from a complete config also exposes information that cannot be represented. Domain routing, GeoIP, GeoSite, process rules, and DNS query policies belong to the runtime configuration, not to a single-node URI. The correct approach is to migrate nodes and routing separately: import nodes through share links, then restore routing through the client’s backup or import function, or configure it manually.

1. Check that the JSON top level contains outbounds, then confirm the target outbound’s protocol name.
2. Read the server address, port, and user parameters; do not copy examples or expired records.
3. Extract the transport, security layer, SNI, path, and service name from streamSettings.
4. Generate a share link for the target protocol and URL-encode the path, remark, and query parameters.
5. After importing into the client, open the details page and verify the port, transport, TLS, SNI, and user ID field by field.
6. Test one node first, then add nodes in bulk to the subscription response so incorrect parameters do not spread across the entire group.

Import coverage and steps for three clients

v2rayN is a desktop client that manages subscription groups, single-node links, and custom configurations. Using the 7.x interface as an example, add a subscription URL via “Subscription groups” → “Subscription group settings,” create a group, enter and save the URL, then choose “Subscription groups” → “Update all subscriptions.” If the clipboard contains multiple share links, use “Servers” → “Import bulk URLs from clipboard.”

v2rayNG uses the Xray core to handle common VMess and VLESS nodes. On Android, open the top-left menu to reach “Subscription group settings,” use the add button in the top-right to save the URL, then return to the main screen and update. For one or more share links, copy them to the clipboard and use the top-right “+” to select “Import from clipboard.” Wording may vary slightly across minor versions, but the entry points remain centered on subscription groups and the add button.

v2flyNG uses the v2fly core and is suited to setups centered on VMess and V2Ray-compatible configurations. Its subscription and clipboard import flow resembles common Android layouts, but supported protocols depend on the core. If a subscription includes a security method or transport combination implemented only by another core, the links may parse and appear while still failing at runtime.

Six parameters to verify after import

• Address and port: The port must be a valid integer. 443 is common for TLS entry points, but do not automatically rewrite other ports.
• User ID: Check for spaces before and after the value; line wrapping in chat tools can truncate it.
• Transport: TCP, WebSocket, and gRPC must match the server.
• Path or service name: A WebSocket path usually starts with a slash; gRPC uses a service name, so do not force a slash into it.
• Security parameters: Match TLS, Reality, SNI, fingerprint, and Flow individually; do not judge by the link prefix alone.
• Local proxy ports: In v2rayN, open “Settings” → “Parameter settings” and confirm that no other program is using the local SOCKS or HTTP port.

How to troubleshoot failed conversions, empty subscriptions, and garbled text

Conversion failures usually occur at one of three stages: fetching the subscription response, decoding the outer container, or parsing individual nodes. Troubleshoot in that order instead of changing protocol parameters first. If the subscription request returned an error page, later Base64 decoding and node import cannot produce a valid result.

Start by recording three concrete values: HTTP status, response size in bytes, and the number of non-empty lines after decoding. For example, a successful status, an 18 KB response, and 24 decoded lines indicate that fetching and outer decoding are essentially complete. If the client shows only 20 nodes, inspect the protocol prefixes or field formats of the remaining 4 lines.

Use logs to locate field-level errors

If the node starts but cannot establish a connection, check the client core log first. DNS resolution failures usually point to the domain or DNS settings; connection timeouts are more likely related to the address, port, or network path; TLS handshake failures call for checking the SNI, system time, and security layer. A configuration-field error during startup requires checking the JSON hierarchy or whether the current core recognizes the field.

Local port conflicts can also cause a configuration to import correctly but remain unusable. For example, if the SOCKS port is set to 10808 while another instance is already listening on it, the core may fail to start. In v2rayN, open “Settings” → “Parameter settings” to check the port and close duplicate instances; on Android, stop the current connection before starting the target configuration again.

Secure migration and long-term maintenance

A subscription URL may provide access to a node list and should be managed as sensitive configuration. Save it in the client’s subscription group rather than exposing the complete URL in screenshots, public documents, or chat logs. For cross-device migration, prefer the client’s own config export function and delete temporary files afterward.

Do not use online conversion pages to process real subscriptions. Base64 is an encoding, not a confidentiality mechanism; any service that can read the decoded text can obtain its node parameters. For structural checks, make a local copy, remove the user ID and subscription query parameters first, and then analyze the format.

For long-term maintenance, keep the node source separate from local policy. The subscription updates nodes; the client controls the system proxy, TUN, DNS, and routing. This way, changes to the subscription list will not accidentally overwrite local direct-routing domains, block rules, or listening ports.

1. Create separate subscription groups for different sources instead of merging every node into one untraceable list.
2. Record the node count before updating, then compare additions, removals, and name changes afterward.
3. Keep a verified working copy of at least one node so a temporary subscription problem does not disable every configuration.
4. After each conversion, spot-check at least one VMess and one VLESS node and verify the transport fields.
5. After upgrading the client, verify subscription updates, node startup, and local ports before restoring the automatic update schedule.