Provider documentation

SMProxy App is a free cross-platform client for Vless/Reality, VMess, Trojan, Shadowsocks, Socks, WireGuard and AmneziaWG, built on the Xray core. The app does not provide servers and is not a VPN service — the user imports a subscription (config) from a provider and connects. Available on iOS, iPadOS, macOS, Apple TV, Android, Android TV, Windows and Linux.

It's a universal client: it imports a config and connects. Everything else — branding, routing, expiry, statistics — is determined by what the provider returns in the subscription response and by the provider account settings.

Three import methods:

The subscription body can be a list of vless://…, base64links, a base64 blob or JSON configs. All routing, branding and expiry arrive in the response headers (section 04).

Encryption uses a shared AES-256-GCM key; addhw binds a link to a single device (anti-sharing). Tapping a link goes through the deep-link handler; pasting into the add form accepts the same forms.

Other clients' links, pasted or scanned. The forms above are accepted with any scheme when the link is pasted into the add form or scanned with the in-app camera: happ://add/<url>, incy://import/<data>, v2raytun://import/<url>, streisand://import/<url>, <anything>://install-sub?url=…, sub://<base64 url> (Shadowrocket). Encrypted links of other clients (happ://crypt4/, incy://crypt1/) cannot be decoded — the app says so. The app does not claim happ:// / incy:// system-wide on Android, iOS or macOS; on Windows and Linux it registers them only when no other handler is installed, so an installed Happ or INCY keeps its links.

The subscription endpoint response is the body (server list) plus metadata (branding, expiry, updates). Metadata can be delivered two ways, and the client reads both.

Live subscription updates

A provider can change a subscription's bypass settings and routing without waiting for the next subscription re-fetch: changes made in the provider account reach online devices within minutes and are applied without reconnecting — new values take effect on the next connect. The same rules apply as for the HTTP headers above — in particular, they are honored only while the provider is active. The delivery mechanism is internal to the app: nothing needs to be implemented on the subscription endpoint.

Body line syntax

• •Starts with # , then a key [A-Za-z0-9-]+ , then the value.
• •The colon is optional — #profile-title My VPN also works.
• •The key is case-insensitive.
• •The first occurrence of a key wins; duplicates are ignored.
• •The body is scanned both as-is and after full base64 decoding — it works for plain text and for a single base64 blob (the usual vless-link format).
• •Only the keys in the table below are read from the body; lines with other keys are ignored.

Keys

Each key works both as a header Key: value and as a body line #key: value. All free.

Provider banner — banner-*

A banner on the subscription card, shown only while the provider id is active (INCY-compatible). Colors must be #RRGGBB — anything else is ignored and the app's own theme color is used. The button caption color is picked automatically from the button's brightness, so it stays readable on light and dark backgrounds alike.

Bypass parameters at a glance

A summary of the four bypass headers — the detailed reference for each is in section 08.

Compatibility with INCY / Happ header names

If you already configure another client, the app also understands their atomic keys and folds them into the equivalent setting. Our s-* header always wins — the keys below are read only when the matching s-* header is absent. *-enable: 0 means explicitly off.

noises-rand: <n> becomes type=rand;packet=<n>. noises-rand-range is not supported.

Where a value can come from, and what wins: 1) the HTTP response header — highest priority; 2) a #key: value line in the body (and, for routing commands, a bare *://routing/… line) — used when the header is absent; 3) the app's own setting — when the provider sends nothing. For the four bypass headers the provider's value wins over the user's toggle, off included.

Text values accept plain UTF-8 or a base64: prefix; any header value may also arrive crypt1/-encrypted.

Compatibility aliases (Happ / INCY)

Headers other clients use are read as their SMProxy counterparts when the SMProxy header is absent — a panel written for Happ or INCY works without changes. Aliases are accepted both in HTTP headers and in the #key: value body form.

The SMProxy header always wins when both are present.

A per-server caption shown under the server name instead of the default protocol label (VLESS | TCP | Reality). Use it to say something the label can't — Netflix / streaming, for gaming, 10 Gbps. Unlike the keys above it is not sent per subscription: it rides with each individual server.

In share links

Inside the #fragment, after the title, separated by ?:

The same syntax works for vless://, trojan://, ss:// and socks://.

In vmess links

A field inside the base64-encoded JSON body:

In JSON configs

Inside a meta object next to remarks — here the value is plain text, not base64:

In links, a value that isn't valid base64, or decodes to nothing, is ignored — the server keeps its protocol label rather than showing broken text.

Provider ID links a subscription to a provider account so the provider can see usage statistics for their subscription. It restricts nothing — the app works fully without it. Free.

Statistics only work when the app knows your Provider ID. If a build does not send it — an older release, a client you do not control, a config imported by hand — those check-ins land nowhere and you lose sight of your own users.

Verify the domain your subscriptions are served from, and check-ins without a Provider ID are attributed to you automatically, based on the subscription URL the app reports.

What it covers

Subdomains are included. Verifying example.com covers sub.example.com, eu.sub.example.com and any other depth — you do not need to add them separately.

Matching is done on the registrable domain, so multi-level suffixes behave correctly: example.co.uk is a domain you can own, co.uk is not, and evil-example.com never matches example.com.

A domain belongs to one provider. If someone else has already verified it, adding it again is refused.

Priority — Provider ID wins

Domain verification never overrides an explicit Provider ID — it only fills the gap when one is missing or unusable.

Where the domain shows up

• •Statistics — a Subscription domains breakdown showing how many devices use each host, and the host under each device's subid. Full hosts are shown, so you can tell sub.example.com from sub3.example.com.
• •Messages — you can target a message at a domain: *.example.com for the domain and all its subdomains, or a single host for just its users.

Only the host is ever displayed — subscription tokens in the URL are never shown.

Your subscription domain gets blocked, or you simply move to a new one. Both cases are handled from the portal — you do not have to change anything in your panel, and users do not have to re-add their subscription.

Both rules are keyed on the domain the request arrived at, so you can run several at once — one per subdomain — and remove them individually.

Migration — new-domain

Open provider.smproxy.io/provider/domains, press Move next to a verified domain and pick:

• •From — *.example.com to move subscriptions from the whole domain including its subdomains, or a single host such as sub.example.com to move only that one.
• •To — the new host. It has to be verified in the same account, so nobody can point your users at a domain they do not own.

From then on, every subscription request that arrives at the old host gets a new-domain header, and the app rewrites the address itself. Each user keeps their own path and token:

Backup hosts — fallback-domains

Press Backups next to a domain and list the hosts to fall back to, one per line. Every entry must be a verified domain of yours. The list is sent as fallback-domains for requests to that domain, and the app walks it in order if the main host stops answering.

Use a migration when you have actually moved; use backups when the main address may become unreachable and you want the app to find its own way through.

Two delivery channels

Both rules reach the app in two independent ways:

• •Subscription response headers — new-domain / fallback-domains, as described above. Requires the request to still reach one of your domains.
• •The app's own service channel — the app also picks up the new-domain / fallback-domains you configured for your domain over its own service connection, without fetching the subscription. They are applied on the next subscription refresh: new-domain re-points the stored URL permanently, backup hosts are saved and tried whenever the main host stops answering.

The second channel matters when your subscription domain is already unreachable: it runs over the app's own service endpoints, so existing users still receive the migration or the backup list even though they cannot fetch the subscription itself.

Requires an app build from late August 2026 or newer; older builds keep using headers only.

What it solves. When you hand a user a new subscription URL — a domain migration, a re-issued token, a move to another panel — the app has no way to tell it is the same subscription. It adds a second entry and the user ends up with two copies of the same thing.

Send a subid and that stops happening: the app treats a matching subid as the same subscription, replaces its URL with the new one and refreshes its servers in place.

subid is optional. Without it everything works exactly as before — duplicates are detected by URL only. Sending it is simply a way to keep control of your users' entries when your addresses change.

Pick a value that never changes for a given user's subscription. It doesn't have to be secret — it is only compared with what the app already has — but it must be stable and unique per subscription. A UUID or your internal subscription id are both fine.

Available on all platforms: iOS, Android, macOS, Windows, Linux and Apple TV.

A provider can send users in-app messages. They arrive inside the Provider ID check response and land in the app inbox (bell icon + unread counter), optionally triggering a system notification.

Each message has: id, title, body, optionally date, type (info/update/promo/warning), url, notify and targeting. Read status is stored locally per device.

Targeting

Compose messages in the provider portal. By default a message goes to everyone; each filter below narrows that down, and they combine.

Platform and app build

Tick the platforms that should receive the message. Leave the build field empty to reach every version of that platform, or set a condition (<, ≤, =, ≥, >) to reach only some of them.

Build numbers are per-platform — iOS 200 and Android 200 are unrelated releases — so a condition is always tied to a platform. Ticking nothing means “all platforms”; as soon as you tick one, the others receive nothing. That is how you reach users still on an old iOS build without touching Android:

Subscription domain

Pick a verified domain to reach only the users whose subscription is served from it — *.example.com for the domain and all its subdomains, or a single host such as sub.example.com for that host alone. The portal shows how many devices are currently on each host.

Requires a verified domain — see Domain verification (section 05a).

A single device

Paste a HWID to send the message to exactly one device — useful when you are walking one user through a problem.

The Geo rules the tunnel uses live inside the imported Xray config and are resolved against the geoip.dat / geosite.dat databases. The app ships with built-in databases and can download updated ones from the geoipurl / geositeurl headers (supported on iOS, Android and desktop OSes); a freshly downloaded database replaces the built-in one for the engine.

A routing profile is a full rule set: what goes straight out, what goes through the tunnel and what is blocked, plus optional split-DNS. It answers “my subscription is a single vless:// link, so there is no routing inside it” — the profile carries routing separately from the servers.

The profile

Rules are applied in the order block → direct → proxy, and they sit ahead of any rules that came with the server config.

GlobalProxy and FakeDNS are accepted both as JSON booleans and as the strings "true" / "false" that Happ and INCY emit. Fields other clients add for their own UI — RouteOrder, UseChunkFiles — are ignored: SMProxy always applies rules in the order block → direct → proxy.

Split-DNS fields

How the resolvers are used:

• •Which resolver answers what. Remote — names that go through the tunnel, domestic — names routed direct (DirectSites). The remote resolver is queried through the tunnel, the domestic one over the physical network.
• •RemoteDNSDomain is also the client's own resolver for its service requests (subscription refresh, profile download) when the subscription sends no s-resolve. A routing profile therefore sets DNS for everything, not just for traffic inside the tunnel.
• •Bootstrap. The ;ip=… suffix of s-resolve does not work inside RemoteDNSDomain — there is no parsing there, the address would go out with junk at the end. Put the bootstrap address into RemoteDNSIP.
• •Fallback chain. The profile's resolvers go first, then the DNS servers from the connection config itself (their own domains / skipFallback splits are kept). If every profile resolver is unreachable, resolution falls through to the config's servers.
• •Client support for arrays: SMProxy from Android 411 / iOS, macOS, tvOS 305 / Windows, Linux 193. Happ, INCY and older SMProxy builds read only the string form — send a string unless you know your users are updated.

String or array — an SMProxy extension. RemoteDNSDomain, RemoteDNSIP, DomesticDNSDomain and DomesticDNSIP each accept a single string (the classic form, compatible with Happ/INCY) or an array of strings:

Order = priority: the core queries resolvers top-down, so the second entry is the fallback for the first. *DNSIP[i] is the bootstrap address for *DNSDomain[i]; an IP without a paired domain acts as a plain resolver.

Version guard — LastUpdated

When a profile with the same Name arrives automatically (subscription headers, an UpdateUrl refresh, a link), it replaces the stored one only if its LastUpdated is greater. If either side has no timestamp, the profile is replaced unconditionally. Bump the value whenever you change the profile. Manual imports from the app UI always apply.

Handing a profile to the user

By link — the natural way: from a browser, a message or a QR code.

The payload may also be passed as ?data=<base64>. A URL may return the profile JSON, its base64, or another smproxy:// link — all three are accepted.

By subscription header — the profile arrives with the subscription itself.

A profile arriving from a subscription is added to the list but not switched on — the choice stays with the user. These keys work with or without a Provider ID.

Headers take deep-link commands too. The value of routing / autorouting may be a deep-link command — the same forms as the clickable links, with any scheme word (smproxy://, happ://, yourapp://): inside a header the word before :// does not matter.

The payload may be crypt1/<base64>-encrypted, like any other header value.

The same commands are also accepted as a bare line in the subscription body, right among the server links (INCY-compatible):

A real HTTP header, or an explicit #routing: body header, takes precedence over a bare line.

Global vs per-subscription

The user picks one active profile in Settings — the global choice. A subscription can override it: if it names a profile (in its own settings, or via the routing-profile header), connecting to that subscription's server uses that profile instead. Both are switchable off: globally in Settings (or with routing/off), and per subscription with “Do not apply”.

Which profile wins

When a subscription refreshes, several of the headers above can arrive at once. They are resolved in this order:

A name that matches nothing changes nothing. If routing-profile: Corporate arrives and no profile by that name exists on the device, the subscription keeps the routing settings it already had. The client will not fall back to some other profile, and it will not clear the setting — a typo in the header can't silently reroute your users' traffic.

The global choice is never touched. Everything above sets the profile for that subscription. The profile the user picked in Settings stays as it is, and keeps applying to every other subscription. To change what a subscription uses, use routing-profile; there is no header that repoints the user's global selection.

Changes apply on the next connect. Profiles are read when the tunnel config is built, so a profile that arrives while connected takes effect after a reconnect — refreshing the subscription mid-session does not reroute live traffic.

DPI systems often block by SNI (the destination domain) read from the TLS ClientHello — the first packet of every TLS/Reality handshake. Fragmentation splits that ClientHello into many tiny TCP segments with micro-delays, so DPI can't reassemble the SNI → can't see the domain → can't cut by domain. It runs entirely on the stock Xray core (a freedom outbound with fragment settings) — with no extra server or infrastructure.

The four parameters below solve different problems and are often used together.

08.1 · s-fragment — TLS fragmentation

Enabling — the s-fragment

Sent as the HTTP response header s-fragment: or as a body comment line #s-fragment: packets=tlshello;length=50-100;interval=10-20.

Parameters

Defaults suit most networks. Tune for a specific DPI: harder blocking → smaller length and/or larger interval; slower speed → larger length and smaller interval.

Parameter names are case-insensitive (maxsplit and maxSplit are the same key), and the packets key is plural — packets=, not packet=. packet= belongs to s-noise, where it means the payload.

08.2 · s-noise — noise packets

Junk traffic sent ahead of the connection so DPI can't recognise its start. It works alongside fragmentation — they share the same egress, and together they cover both the start of the connection and what's inside it.

Values: on / 1 uses the defaults (rand, packet 50-100, delay 10-20); off / 0 disables it. Full form is type=rand;packet=50-100;delay=10-20, or positional rand,50-100,10-20; type accepts rand, str or hex.

Both spellings of the header are accepted — s-noise and s-noises.

08.3 · s-resolve — pre-resolving the server address

Resolves the server address over DoH before the tunnel comes up. Use it where the local DNS returns a forged answer for your node's domain: without it the client gets a wrong IP and simply never connects.

Values: on / 1 uses the default resolver (dnsforge.de); off / 0 disables it; a URL sets your own.

Where even the resolver's own domain is poisoned, add a bootstrap IP with ;ip=… — for example https://dnsforge.de/dns-query;ip=49.12.67.122. The original domain stays as SNI, so TLS/Reality still validate. If the resolver doesn't answer within a second and a half the normal lookup is used — the parameter can only help, never block the connection.

Several resolvers can be listed, separated by commas, each with its own bootstrap IP — they are tried in order until one answers. A single address behaves exactly as before: it is the same format without commas.

A list beats the app's built-in set: you name the resolvers you know work on your users' networks, which the built-in list cannot know. It also can't be switched on by a header at all — only by the user's own toggle.

08.4 · s-dns — DNS-over-HTTPS in the tunnel

Encrypts ordinary DNS queries inside the tunnel. Values: on / 1 enables the built-in default resolver (dnsforge.de); a URL such as https://dnsforge.de/dns-query sets your own; off / 0 disables it. Resolved DNS travels through the tunnel, not the physical network.

WireGuard and AmneziaWG servers behave like any others: they sit in the same list next to VLESS/Trojan/Shadowsocks and the user picks them the same way. There is no separate mode and no extra setup. It runs on the stock Xray core (a wireguard outbound) — nothing new is required on the provider side beyond the config itself.

Option A — in a JSON subscription

A normal Xray config whose outbound has "protocol": "wireguard":

The server address shown in the app comes from peers[0].endpoint. WireGuard has no vnext or servers block — the endpoint string is the only place the host lives.

AmneziaWG fields. The same outbound accepts obfuscation parameters — add them next to the usual ones. They are only for AmneziaWG; for plain WireGuard leave them out entirely (any zero value is ignored and the connection behaves exactly as before).

Server version — 3.1 and older. The app is built on the AmneziaWG 3.1 branch and stays compatible with every earlier one, so there is nothing to upgrade on your side. Send only the parameters your server actually uses; anything you leave out keeps its default and is ignored.

A 3.1-only parameter sent to an older server is simply not understood by it, so keep the two sides in step: configure the client with exactly what the server runs.

Option B — a wireguard:// link

wireguard://<base64 of a standard .conf> — the base64 holds an ordinary WireGuard configuration file, exactly the text you hand to the official client. An optional #Name anchor sets the displayed title:

The decoded payload is simply:

This form works everywhere the other share links do: pasting into the add form, inside an encrypted crypt1 link, or as a line in the subscription body.

Keys are passed to the core as-is — the app does not re-encode them.

Client-side import

From Android 379, iOS/macOS 2.0.3 (277+) and desktop 169 the add screen takes a WireGuard/AmneziaWG config in four ways — you can hand configs to users in any of them:

AmneziaWG obfuscation parameters (Jc, Jmin, Jmax, S1, S2, H1–H4) are picked up from [Interface] in all four. Older builds accept the scheme link and QR only.

C. AmneziaWG — WireGuard with obfuscation

AmneziaWG is the same WireGuard plus obfuscation: junk packets and rewritten header types that keep DPI from recognising a WireGuard handshake.

Link schemes. wireguard://, amneziawg://, awg:// and wg:// are all accepted and parsed the same way — the payload is base64 of a standard .conf, with an optional #Name fragment.

Obfuscation parameters live in [Interface] of that .conf, next to the usual keys:

Leave them out and you get plain WireGuard — the app and the core behave exactly as before. The same applies field by field: send only what your server runs. Any AmneziaWG version works, 3.1 and older — see the version table in section A.

Several locations in one file. A subscription URL may return a JSON container instead of links:

type is accepted as amneziawg, awg, wireguard or wg. A malformed entry is skipped without taking the rest of the list down with it.

Notes for operators

• IPv6 endpoints are supported, written the standard way: [2606:4700:d0::a29f:c001]:2408.
• keepAlive (seconds) — persistent keepalive. Set it if your clients are behind NAT: without it the translation expires and the tunnel goes quiet in one direction.
• MTU in the config controls what the client sends. What the server sends is set by the MTU of the wg0 interface on the node — configure both, otherwise a path that can't carry full-size packets will pass the handshake and then stall.
• Routing on the node matters: ip route get <client ip> must resolve via wg0. If it points at the default gateway the handshake still succeeds (the daemon answers it directly) but data never reaches the client. Looks like blocking — it isn't.

Everything the client accepts, in one place. All schemes are case-insensitive.

Server links

Base64 is read leniently — standard and URL-safe alphabets, with or without padding.

A #fragment sets the display name (percent-encoded). It may also carry a server description — see section 04a.

What “View config” shows

The client applies one simple rule: if the link carries base64, it shows the decoded content; otherwise it shows the link as it is. So wireguard://<base64> displays the readable .conf, while vless://uuid@host:443?… stays a link — there is nothing to decode. JSON payloads are pretty-printed.

Subscriptions

A subscription URL may return:

type is accepted as amneziawg, awg, wireguard or wg. A broken entry is skipped rather than failing the whole subscription.

Encrypted header values

Header values can be sent in a closed form, so links and settings don't travel around in the open. Any subscription header may carry its value encrypted, using the same crypt1/ prefix as the deep links:

The client strips the prefix, decrypts the payload and then treats the result exactly as if it had arrived in the clear. Without the prefix nothing changes — existing subscriptions keep working untouched. Encryption is optional and per-header: a single response can freely mix encrypted and plain values.

The encryption is exactly the one used by smproxy://crypt1/… links — AES-256-GCM, nonce || ciphertext || tag, base64-encoded, under the same shared key. A panel that already issues those links needs no new code: encrypt the value, prefix it with crypt1/, and put it in the header.

To get an encrypted value without writing any code, use the same generator that produces the links — it returns smproxy://crypt1/<encrypted>; take everything after smproxy://, that is crypt1/<base64>, exactly what the header expects.

Both separators are accepted — crypt1/<base64> and crypt1:<base64> — but use the slash: it matches the deep links, so there is one format to remember.

Deep links

Two schemes are accepted: smproxy:// (current) and smartvpn:// (pre-rename, kept working for links already handed out). That applies to clickable links only — the OS hands a link to the app registered for its scheme. Inside the routing / autorouting headers any scheme word is accepted (section 07a).

The payload may also be passed as ?data=<base64>. For routing links the target may hold the profile JSON, its base64, or another smproxy:// link — all three resolve.

Self-service at provider.smproxy.io — registration, statistics, messages and link generators.