For VPN providers

Piko is not affiliated with any provider. Working with Piko is not an endorsement, and we don't list or recommend providers.

Add-to-Piko links

Put a button on your website, in your bot or in your emails that opens Piko and adds the subscription. Piko always shows a confirmation sheet before it saves anything.

piko://install-sub?url=https%3A%2F%2Fsub.example.com%2Fs%2Fabc123&name=Example

url: the subscription address, percent-encoded. Use https://; for an http:// address Piko warns the user that it is not encrypted.
name: optional. The name shown until your profile-title header arrives.

Also understood:

piko://add?url=…&name=… and piko://install-config?url=…, the same as above;
piko://add/<address> with the subscription address as it is (the Happ-style form);
piko://import?data=… with percent-encoded or base64 share links, to add single servers.

A piko:// link opens the app only where Piko is installed, so also show the plain subscription address for users to copy. When users paste or scan them, Piko also understands happ://add/<address> and v2rayng://install-sub?url=… links.

What Piko sends

Piko fetches a subscription with a plain GET request and these headers:

Header	Example	Meaning
`User-Agent`	`Piko/0.1.0/Android/36`	`Piko/<app version>/<system>/<system version>`. The `Piko/` prefix is stable, so you can match it to serve the right format. Piko never sends a browser User-Agent.
`x-hwid`	32 hex characters	A device ID made for your domain only. The same device gives other providers a different value.
`x-device-os`	`Android`, `iOS`	The operating system.
`x-ver-os`	`16`	The system version.
`x-device-model`	`Pixel 9`, `iPhone17,3`	The device model (never the name the user gave the device).

The device headers go only to your subscription's own host and to the addresses you name in new-url, new-domain or fallback-url. They are dropped on redirects to other hosts. In rare cases, for example on iOS before the first unlock after a restart, Piko sends none of them.

Supported formats

A plain or base64-encoded list of share links: vless://, vmess://, trojan://, ss:// (including Shadowsocks 2022) and hysteria2:// (hy2://).
A full Xray JSON configuration. Piko removes local listeners, log files and other settings that don't belong in a phone app.
Transports: TCP (RAW), WebSocket, gRPC, HTTPUpgrade, XHTTP (SplitHTTP) and mKCP. Security: TLS, REALITY and XTLS Vision.
Not supported: sing-box JSON, Clash YAML, WireGuard, TUIC, AnyTLS, NaiveProxy, ShadowTLS and other protocols outside Xray, the removed h2 and QUIC transports, ss:// plugins, and Hysteria2 with insecure=1. Plain-text VLESS to a public server is refused.

Use servers that encrypt the connection: TLS, REALITY, Shadowsocks 2022 or Hysteria2. App store rules require VPN apps to encrypt traffic to the server, so Piko may refuse servers that don't.

Headers Piko honours

Send these as response headers. The same names also work as #key: value lines at the top of the body (Happ style). If both are present, the header wins.

Header	What Piko does
`subscription-userinfo`	`upload=…; download=…; total=…; expire=…` in bytes and Unix time (0 means unlimited or never). Piko shows the traffic used and the days left, and on Android reminds the user before expiry.
`profile-title`	The subscription's name, as plain text or `base64:…`. Without it, Piko uses the file name from `content-disposition`.
`profile-update-interval`	How often to update, in hours. The default is 4.
`support-url`	A support link (`https://`, `tg:` or `mailto:`), shown under “From your provider”.
`profile-web-page-url`	Your website or account page.
`support-email`	A support email address.
`announce`	A message to show, as plain text or `base64:…`.
`announce-url`	A link to your announcements (`https://` or `tg:`).
`sub-info-text`, `sub-info-button-text`, `sub-info-button-link`	A banner with an optional button (Happ format).
`routing`, `routing-enable`	A routing profile as a routing link (Happ format, for example `piko://routing/add/<base64>`). Piko applies it only after the user agrees. `routing-enable: 0` switches it off.
`new-url`, `new-domain`	Your subscription has moved. Piko fetches the new address and keeps it if it works. Only `https://` addresses on public hosts are accepted.
`fallback-url`	A mirror that Piko uses when the main address fails, without changing the user's link.
`check-url-via-proxy`	An `https://` address that Piko requests through your servers for latency tests of Xray JSON configurations.
`x-hwid-active`, `x-hwid-not-supported`, `x-hwid-max-devices-reached`, `x-hwid-limit`	Device-limit status (`true` or `1`). Piko explains a refusal to the user and shows your support link.

Entries in your server list that are really messages (for example a “server” called “Expires in 5 days”) are shown as messages, not as servers.

Protected links

Piko can open piko://crypt1/… links that hide the subscription address from casual copying: Piko never shows, copies or exports an address added this way. This is obfuscation, not DRM: the key is inside the app. The tool to create these links will be available to providers with Piko's public release. To be notified, write to support@pikonet.io.

Testing and questions

Add a test subscription in Piko and check its details: name, traffic, expiry and your messages. If your panel doesn't work with Piko, write to support@pikonet.io with the panel's name and version. Please send a test subscription, never a real customer's.