V2Ray Subscription Link Formats: What an App Needs to Parse
Your app imports a subscription URL, and the first panel you test returns something your parser has never seen. One server sends a base64 blob, another sends YAML, a third sends JSON, and opening the link in a browser shows a web page. So what does a v2ray subscription link return, and what must your app handle?
A v2ray subscription link is an HTTPS URL that returns a list of server configs, in a format that depends on the panel and on who is asking. Expect base64 text with one share link per line, Clash style YAML or sing-box JSON, plus response headers for usage and refresh timing. The sources read describe project specs and community proposals, not one standard, so the app has to parse defensively. This guide rests on documentation and source code read on 30 October 2026. Nothing was tested hands on.
What Is a Subscription URL, and Why Do Apps Use One?
The app fetches the URL, turns the response into server entries, and fetches again on a schedule. The URL usually carries a per user token, so the server can return the right servers, usage and expiry for that account. Operators can then add or retire servers without an app update.
sing-box documents the same idea as a remote profile: a configuration with a URL as its update source, which a graphical client is expected to refresh automatically (60 minutes by default) and to fetch with HTTP Basic authorization if needed. The 3x-ui subscription docs describe a separate subscription server, on port 2096 by default, that serves raw, JSON and Clash output. To choose the panel behind the URL, see our panel comparison. For the cores that consume these formats, see Xray vs sing-box, and for the other parts of a VPN product, see the six components of VPN app architecture.
Which Payload Formats Can the URL Return?
| Format | Body | Typical consumers | Pitfalls |
|---|---|---|---|
| Base64 share link list | One share link per line, whole body base64 encoded | Xray and v2ray style clients | Plain variants exist (3x-ui subEncrypt toggle, Hiddify /sub vs /sub64), so detect, do not assume |
| Clash or Mihomo YAML | A full profile with a proxy list | Clash family and Mihomo based clients | Mihomo provider interval is in seconds, headers use hours; 3x-ui’s legacy Clash endpoint returns 422 if nothing compatible exists |
| sing-box JSON | A sing-box configuration | sing-box based clients | Only outbound types the client’s core supports will work |
| Xray JSON | An array of full Xray configs, each optionally carrying a remarks name |
Xray core based clients | A community proposal; we found no sign it was adopted as a standard. Panels serve it to selected clients only |
| Outline JSON | Shadowsocks access data | Outline and Shadowsocks apps | Marzban serves it; we did not find it in the other three |
Remnawave’s docs add one useful note: the original Clash client and core are no longer maintained, and Mihomo is its de facto successor. Treat “Clash” as a family of formats and test against Mihomo.
Which Share Link Schemes Must the Parser Support?
| Scheme | Shape | Source | Caveat |
|---|---|---|---|
vless:// |
vless://uuid@host:port?params#remark, with parameters such as security, type, flow, sni, fp |
Xray discussion 716, a proposal | Maintainers say it may change; values must be escaped; the remark follows # |
vmess:// |
Base64 of a JSON object with keys such as ps, add, port, id, net, tls; the wiki’s example shows every value as a string |
v2rayN wiki | The 716 proposal defines a URI form instead and leaves out alterId, so support both |
trojan:// |
trojan://password@host:port, password URL encoded |
trojan-url README, “defined (not finalized)” | That README covers only password, host and port |
ss:// |
ss://userinfo@host:port/?plugin=...#tag |
SIP002 | Userinfo may be Base64URL for older ciphers, but must be percent encoded, not Base64URL, for 2022 ciphers (SIP022); ignore unknown query arguments |
hysteria2:// or hy2:// |
hysteria2://[auth@]host[:port]/?params#name |
Hysteria docs | Port defaults to 443; the port part may list ports and ranges for port hopping; parameters include obfs, obfs-password, sni, insecure, pinSHA256 |
Treat the fragment as display text only. The Hysteria docs say the name carries no connection information, and the same rule is safe for every scheme.
Which Response Headers Come With the Body?
| Header | Meaning | Gotcha |
|---|---|---|
Subscription-Userinfo |
upload, download, total in bytes and expire in Unix seconds |
total=0 can mean unlimited; Marzban, Hiddify and Remnawave send upload=0 and put all counted usage in download |
Profile-Update-Interval |
Refresh interval in hours | Defaults differ: 3x-ui 12, Marzban 12, Hiddify 1 |
Profile-Title |
Display name, often base64: plus base64 text |
Decode before showing |
Support-Url, Profile-Web-Page-Url, Announce |
Optional branding and a message | Untrusted text and links |
x-hwid, x-device-os, x-ver-os, x-device-model (request) |
Device identity the app sends, used by the HWID features of Remnawave and 3x-ui | Only x-hwid is required |
x-hwid-active, x-hwid-not-supported, x-hwid-max-devices-reached, x-hwid-limit (response) |
Device limit state, sent by Remnawave and 3x-ui | Present only when that feature is on |
These are conventions, not a standard. The 3x-ui docs call them standard headers that compatible apps read, and the Xray proposal names them for JSON subscriptions, but we did not find an RFC or standards document for them in the sources read. A comment in Remnawave’s source says part of its expiry handling should go away once “XTLS Standards” are published, and its HWID doc says the device header set was offered by one client app. Treat every header as optional, and match names without regard to case, because the projects capitalize them differently.
How Does the Server Decide Which Format to Send?
All four panels read choose the format from the request, through the User Agent, the URL path or both.
- Marzban matches the start of the User Agent against Clash and Mihomo names, sing-box app names such as
SFAorSFI, and Outline or Shadowsocks apps. An unrecognized User Agent gets a base64 list. Each format also has an explicit path suffix. - 3x-ui chooses mainly by path: raw, JSON and Clash or Mihomo each have their own path, plus explicit
/mihomo/and/clash-legacy/paths. User Agent matching for Clash and JSON exists as a setting that is off in the defaults we read, and its Clash matcher default is(?i)(clash|mihomo). - Hiddify sends a web page to browsers, sing-box JSON or Clash YAML to known families, and base64 links to other known clients. Explicit paths and an
/autopath also exist. - Remnawave detects the client and uses templates for four main families: Mihomo, Base64, Xray JSON and sing-box. Its Response Rules can match request headers and answer with a format, an HTTP 403, 404 or 451, or a dropped connection.
Three consequences follow for a branded app. First, a custom User Agent hits the fallback on Marzban and Hiddify, which is a list of share links, so agree the User Agent with whoever runs the panel, or use the explicit format path. Second, never send a browser like User Agent or Accept: text/html: the docs or code of all four panels show that browsers get an HTML page. Third, test the User Agent after every panel upgrade, because the matching rules belong to the panel, and operators of some panels can edit them.
What Should the App Do With the Response?
Parse and validate
- Detect the encoding: if the body contains
://on lines, it is plain; otherwise try base64; otherwise fail. - Split into lines, trim and skip blanks. Parse each scheme on its own, so one bad line never discards the rest.
- Check ports (1 to 65535), UUID shape, and required fields. Cap body size and entry count.
- Ignore unknown query parameters. SIP002 does not state a rule, but its example URI carries an argument named
unsupported-argumentswith the valueshould-be-ignored. - Refuse plain HTTP. The Xray JSON proposal requires an encrypted channel.
- Keep a sample file for every panel and format in your test suite.
Update intervals and caching
Normalize units on import: hours in the header, seconds in a Mihomo provider, minutes in a sing-box profile. Clamp the result to a minimum and maximum you choose, add jitter, and keep the last good profile with a timestamp. These bounds are editorial advice, not something the projects require.
Failure handling and safe fallbacks
- On a timeout or 5xx, keep the cached profile and back off.
- Do not treat every 404 as a network error. Marzban answers an invalid or revoked token with 404, and Remnawave and 3x-ui answer 404 when a device limit is on and no HWID header was sent.
- Expect 403, 451 or a dropped connection from Remnawave rules, and 422 from the 3x-ui legacy Clash endpoint.
- Hiddify can return a readable error configuration when rendering fails. A response that parses but contains no real servers is a failure, so keep the previous profile.
Showing usage and expiry
Show used data as upload + download, because of the upload=0 pattern. Treat total=0 as unlimited, and expire=0 or a missing value as no expiry: Marzban sends 0 when no limit or expiry is set, and Remnawave sends 0 for its far future placeholder date. If the header is absent, hide the usage display instead of showing zero.
How Should You Protect Subscription URLs?
A subscription URL works as a bearer credential. CWE-598 describes sensitive values in query strings leaking through browser history, referrer headers and web logs, and suggests headers or bodies instead. A subscription link cannot always follow that advice, and a token in the path, as Marzban uses, still appears in the full URL that servers log. So compensate with process:
- HTTPS only, with no plain HTTP fallback.
- No tokens in logs. Strip them from access logs, crash reports and analytics. What you collect also belongs in your privacy policy and store disclosures.
- Rate limit by token and by IP, and answer unknown tokens identically.
- Rotate both parts. The profile contains proxy credentials as well as the URL. Marzban’s revoke endpoint resets the link and the proxies. Remnawave’s revoke changes the credentials and, unless
revokeOnlyPasswordsis set, the short UUID that forms the URL. - Have a leak playbook: revoke, review the access history (Remnawave lists subscription requests per user), deliver the new URL through the authenticated app channel, purge logs that hold old tokens, and review device limits.
Some apps import the URL through a login or deep link and never show it. That is a design option that reduces casual sharing. It is not a security control and not a claim of secrecy, because the device and the network path still handle the URL. If you control both ends, sing-box’s HTTP Basic support is another option to evaluate.
FAQ
What is a v2ray subscription link?
It is a URL that a client fetches to get a list of server configs, usually with usage and refresh headers. The body is a base64 list of share links, Clash YAML, sing-box JSON or Xray JSON, depending on the server and the client.
Is Subscription-Userinfo an official standard?
We did not find a standard for it. The 3x-ui docs and the Xray proposal describe it, but we saw no RFC or standards document in the sources read, so treat it as a convention.
Do vless:// links have an official spec?
We did not find an official spec, only a community proposal in Xray discussion 716, and its maintainers say the format may change. Parse leniently and test against real panel output.
Should my app support Clash and sing-box formats too?
Only if you want users to import the link into other clients. A branded app can fetch one format and ignore the rest, but it must then send a User Agent or path that yields that format.
How often should the app refresh?
Follow Profile-Update-Interval within your own bounds. Panel defaults range from 1 hour (Hiddify) to 12 hours (3x-ui, Marzban), and sing-box’s default is 60 minutes.
Takeaway
Treat the subscription response as untrusted input in four formats, ask for the format explicitly, keep the last good profile, and rotate both the URL and the credentials when a link leaks.
Building an app that has to import subscriptions from a panel? Tell us which formats and clients you need on the contact page, and we will help you scope the parser, the backend and a test plan.
Last checked against the sing-box client docs, the Xray discussions 716 and 3765, the v2rayN wiki, SIP002, the Hysteria URI docs, CWE-598, and the 3x-ui, Marzban, Hiddify and Remnawave repositories and docs on 30 October 2026.