Connection links
One VLESS, VMess, Trojan or Shadowsocks link per line. A UTF-8 list encoded as Base64 is also accepted.
Your service. One easy handoff.
Give your users a subscription link that brings their connections, provider name, support and usage information into Lodnet.
01 /
Start with an HTTPS endpoint.
Return the subscription itself from your endpoint, not an HTML landing page. Use UTF-8 and a valid HTTPS certificate. The example below uses fictional values; replace the host, credential and configuration with your own.
HTTP/1.1 200 OK
Content-Type: text/plain; charset=utf-8
Cache-Control: private, no-store
profile-title: Example Network
support-url: https://provider.example/support
subscription-userinfo: upload=1073741824; download=4294967296; total=107374182400; expire=1893456000
vless://00000000-0000-4000-8000-000000000001@node.provider.example:443?security=tls&type=tcp&sni=node.provider.example#Example%20LocationTreat each subscription URL as an access credential. Keep it out of analytics, public repositories and screenshots. Authenticate requests using your own access model; no Lodnet API key is needed for subscription import.
02 /
Choose a compatible format.
Xray JSON
A configuration object or an array of configurations. Send metadata as HTTP headers. Routing, DNS and outbound settings are imported within the supported Xray configuration model; test your exact configuration.
Size limits
Up to 2 MiB of decoded response text and up to 1,000 connection-link records. Malformed or unsupported links produce warnings; an entirely incompatible list is rejected.
Not accepted in this release
Clash YAML, arbitrary sing-box JSON, legacy VMess alterId values other than zero, and Shadowsocks plugins. Do not assume that every engine-specific extension is supported.
03 /
The headers Lodnet reads.
Header names are case-insensitive. Metadata may also appear as “# name: value” lines in a text subscription. An HTTP header takes precedence over the corresponding body field. For JSON, prefer HTTP headers.
profile-title
Provider name. Plain text or base64: followed by a Base64-encoded UTF-8 name. Lodnet keeps up to 80 Unicode characters and removes control characters. For non-ASCII names, use Base64 for reliable HTTP transport.
support-url
A public HTTPS support link, up to 2,048 characters, without embedded credentials. For Telegram use an https://t.me/ link. It opens provider support, not Lodnet app support.
subscription-userinfo
Upload, download and total traffic in bytes; expiry as Unix time in UTC seconds. See the field definitions below.
profile-update-url
An HTTPS replacement subscription URL. Lodnet asks the user to confirm the migration. It is not an automatic-update interval. x-lodnet-subscription-url is an accepted alias.
profile-title: base64:0J/RgNC40LzQtdGAINCh0LXRgtC4# profile-title: Example Network
# support-url: https://provider.example/support
vless://00000000-0000-4000-8000-000000000001@node.provider.example:443?security=tls&type=tcp&sni=node.provider.example#Example%20Location04 /
Make usage information useful.
| Field | Meaning |
|---|---|
upload | Bytes uploaded by the user. |
download | Bytes downloaded by the user. |
total | Positive traffic allowance in bytes. Omit it or send 0 when the limit is unknown or unlimited. |
expire | Positive Unix timestamp in seconds, not milliseconds. Omit it when no expiry is known. |
The example above represents 5 GiB used out of 100 GiB, expiring January 1, 2030 at 00:00 UTC. Lodnet calculates used traffic as upload + download. Values are non-negative integers. Missing metadata is shown as unknown, not a zero balance.
05 /
Let users open their subscription.
The universal option is a “Copy subscription link” button followed by paste in Lodnet. For a one-click browser handoff, the user must first enable browser import in the installed Windows app.
lodnet://import?url=https%3A%2F%2Fprovider.example%2Fsub%2FEXAMPLE_TOKENconst subscriptionUrl = 'https://provider.example/sub/EXAMPLE_TOKEN';
const link = 'lodnet://import?url=' + encodeURIComponent(subscriptionUrl);
// Assign link to an <a> href after authenticating the user.Encode the entire HTTPS subscription URL once. Use exactly one query parameter named url. The complete import link is limited to 8,192 characters. Browsers may ask for confirmation; always offer the copy-and-paste fallback.
Pasted happ://add/ wrappers are recognized by the import field. That does not mean Lodnet takes over the Happ browser protocol or supports all Happ-specific commands.
06 /
Shared conventions. Clear boundaries.
Requests currently include User-Agent: Happ/3.0.0 Lodnet/0.8.10. To identify Lodnet, check for the Lodnet/ token and allow the version to change. Do not require browser cookies or JavaScript challenges on the subscription endpoint.
These Happ fields are not applied in 0.8.10
profile-update-interval, profile-web-page-url, announce, provider-id, fallback-url, new-url and new-domain do not configure Lodnet. Unknown metadata does not change app settings. Users choose their own refresh interval in settings: off, 1, 3, 6, 12 or 24 hours.
For rate limiting or maintenance, return 429 or 503 with Retry-After (seconds or an HTTP date). 401 or 403 indicates an access problem. A failed refresh does not replace the saved list. Keep redirects short and HTTPS-only.
Related convention: Happ developer documentation07 /
Test your integration.
Import and display
Add a fresh subscription. Check the provider name, support link, locations, traffic bar and expiry. Repeat with a Cyrillic name encoded as Base64.
Refresh and recovery
Change the list and refresh. Then simulate a 503 response: the previous list must remain available. Test an expired token and a replacement URL.
Connect in both modes
Use your real test account to check Proxy and TUN. Add a second provider and verify that automatic selection stays within the selected subscription.