Proxy Username Format for Country, Session and Rotation
How the gateway reads a psx_ proxy username: pool, country, sid, rotation, TTL, failover and geo tokens, plus the silent repairs that change routing.
By Proxies.sx Team. Reviewed .
Write psx_<account>-<pool>-<country>, then add optional token-value pairs such as -sid-job1 or -rot-sticky. The gateway lowercases the string, splits it on hyphens and repairs most mistakes without telling you, so a typo changes routing instead of failing. Check each username once before you scale it.
In this guide
The format
The username carries your account and every routing choice. The password is your proxy password or a pak_ access key and carries no routing.
psx_<account>-<pool>-<country>[-<token>-<value> ...]| Username | Result |
|---|---|
psx_ab12cd-peer-us | Peer device in the United States, rotating every 10 minutes |
psx_ab12cd-mbl-gb-rot-sticky-sid-shop1 | Mobile modem in the United Kingdom, held for session shop1 |
psx_ab12cd-peer-br-city-curitiba | Peer device in Brazil recorded in Curitiba |
psx_ab12cd-any-any | Any pool, any country |
The same username works on both listeners: http://gw.proxies.sx:7000 and socks5h://gw.proxies.sx:7001. With SOCKS5, the h in socks5h makes the proxy resolve the target hostname, and the SOCKS5 vs SOCKS5h article explains why that changes which DNS server sees your lookups.
curl -x http://gw.proxies.sx:7000 \
-U 'psx_ab12cd-peer-us-rot-sticky-sid-test1:YOUR_PROXY_PASSWORD' \
https://api.ipify.org
curl --proxy 'socks5h://gw.proxies.sx:7001' \
-U 'psx_ab12cd-peer-us-rot-sticky-sid-test1:YOUR_PROXY_PASSWORD' \
https://api.ipify.orgPool and country
| Pool | What it selects |
|---|---|
mbl | Carrier modems in six countries: us, gb, fr, nl, pl and ge. ge is Georgia, not Germany. |
peer | Residential and mobile devices from the opt-in peer network. Countries vary with what is online, and the stock endpoint lists them. |
any | Either pool. best is also accepted and, in the gateway build checked on 19 October 2026, selects the same way as any. |
The country is a two-letter ISO 3166 code such as us, br or de, or any. A small set of names is translated: usa to us, uk to gb, germany to de, georgia to ge. A word the gateway does not recognize becomes any silently, so -peer-brasil routes to any country.
mbl-de always fails with E_NO_STOCK_COUNTRY, because the mobile pool has no German modems. Use peer-de. Any two-letter code is accepted, so a valid code with nothing online fails the same way. Check counts before a run.
Price per GB depends on the country's tier, not on the pool. The pricing page lists the tiers and reads them from the same stock endpoint. Residential coverage is described on the residential proxies page.
# Endpoint counts per pool for one country, read from the live stock endpoint
curl -s https://api.proxies.sx/v1/gateway/pool/stock \
| jq '{peer: .pools.peer.br, mobile: .pools.mbl.br, generatedAt, stale}'Optional tokens
Tokens follow the country in any order. Each one is a name and a value separated by a hyphen.
| Token | Values | Effect |
|---|---|---|
sid | Up to 64 characters from a-z, 0-9 and _ | Names a session. Connections with the same sid, pool and country share an endpoint. |
rot | auto5 auto10 auto20 auto60 sticky hard ondemand | Rotation. Default auto10. hard pins like sticky. See the sticky session guide. |
ttl | Seconds, 60 to 2,592,000 | How long a session lives after its last use. Default 3,600. |
failover | samecountry samecarrier any strict | Where a session moves when its endpoint goes away. Default samecountry. |
carrier | Carrier name in lowercase letters and digits, for example tmobile | Only endpoints whose carrier or ISP name matches, ignoring punctuation and suffixes such as US or Inc |
city | City key in lowercase letters and digits, for example curitiba | Only peer endpoints recorded in that city. Modems are never matched by city, so mbl with a city returns no stock. |
state | US state code, for example ny | Only peer endpoints recorded in that state. Modems are never matched by state. |
iptype | mobile or residential | Only endpoints of that class |
isp | Part of an ISP name in lowercase letters and digits | Only endpoints whose ISP name contains the value |
Each filter narrows the set of candidate endpoints. When nothing matches, the request fails with E_NO_STOCK_COUNTRY and the message names the filters it applied, for example matching isp=claro city=curitiba. Remove filters one at a time until requests succeed.
City keys are the city name with everything except a-z and 0-9 removed, and accented letters are dropped rather than converted. São Paulo is sopaulo, not saopaulo. Read the exact keys and their counts from the facets endpoint, or pick them in the username builder.
curl -s 'https://api.proxies.sx/v1/gateway/pool/stock/facets?country=br&pool=peer' \
| jq '.cities[:5]'The gateway parses a few more tokens than this table lists. The ones above are those we document for customer use.
Repairs the parser makes without telling you
The parser is built to route rather than reject. Apart from a missing username or one longer than 256 characters (E_USERNAME_PARSE, HTTP 400), every mistake is repaired or skipped. We log the repairs on our side, and your client receives no warning.
| You wrote | The gateway used | Effect |
|---|---|---|
-mobile-us | -mbl-us | Alias, works as intended |
-rot-static | -rot-sticky | Alias, works as intended |
-rot-auto15 | -rot-auto10 | Snapped to the nearest supported interval |
-rot-sticy | -rot-auto10 | Typo falls back to the default, so the session rotates |
-peer-brasil | -peer-any | Unknown country becomes any |
-region-ca | nothing | Unknown tokens are skipped |
-sid-job-7 | -sid-job | The hyphen ends the value, so every job shares one session |
-sid-Job.7 | -sid-job7 | Lowercased, the dot removed |
-iptype-cell | -iptype-mobile | Alias, works as intended |
Spaces anywhere in the username are removed before parsing. A trailing space copied from a spreadsheet therefore does not change the country.
Characters, encoding and length
No token value may contain a hyphen, because the parser splits on hyphens. Use underscores inside session ids.
When you put credentials into a proxy URL, percent-encode reserved characters in the password. The URL syntax allows only a limited set of characters in the user information part (RFC 3986, section 3.2.1), and curl URL-decodes the user and password it finds in a proxy string, so an @ in a password must be written %40. Passing credentials separately, with -U in curl or the username and password fields of your library, avoids encoding entirely.
HTTP Basic authentication splits user and password at the first colon (RFC 7617). Our usernames contain no colons, so this only bites when a colon ends up in the username by mistake. The gateway rejects usernames longer than 256 characters. Over SOCKS5 the protocol itself caps the username at 255 bytes (RFC 1929).
Build usernames in code
A small helper prevents most of the silent repairs above. It rejects values the parser would change instead of letting the gateway rewrite them. The username builder does the same in a browser, and the format converter turns a username and password into the formats other tools expect.
import re
POOLS = {"mbl", "peer", "any"}
VALUE = re.compile(r"[a-z0-9_]{1,64}")
def gateway_username(account, pool="peer", country="us", **tokens):
"""Build a Pool Gateway username, failing where the gateway would silently repair."""
if pool not in POOLS:
raise ValueError(f"unknown pool {pool!r}")
if not (country == "any" or re.fullmatch(r"[a-z]{2}", country)):
raise ValueError(f"country must be a two-letter code or 'any', got {country!r}")
parts = [account, pool, country]
for name, value in tokens.items():
value = str(value)
if not VALUE.fullmatch(value):
raise ValueError(f"{name}={value!r}: use 1-64 of a-z, 0-9 and _")
parts += [name, value]
return "-".join(parts)
print(gateway_username("psx_ab12cd", "mbl", "gb", rot="sticky", sid="checkout_7"))
# psx_ab12cd-mbl-gb-rot-sticky-sid-checkout_7Common questions
Why is my country token ignored?
The gateway turns a country word it does not recognize into any, without an error. Use the two-letter ISO code, for example br rather than brasil.
Can I use uppercase letters?
Yes, but the gateway lowercases the whole username, so session ids that differ only in case become the same session.
Do I need a new password for each country or session?
No. Routing lives in the username. One proxy password works with every username built from your account.
Sources and test scope
Standards and vendor documentation checked on 19 October 2026. Gateway responses on these pages were observed with test requests or read from the gateway build running that day, and the client examples were run against local test servers. They do not establish current stock in a country or how a website will respond.
Connect your application to Proxies.sx
Use the username builder for gateway routing fields and the format converter for existing connection lists. Review Pool Gateway documentation, then check current mobile stock before buying traffic.
For agent-driven workflows, the agent service index lists the supported APIs. A configured HTTP client still needs to validate its task's response.
Proxy error and troubleshooting guides
Start from the symptom table, or open the guide for the error you saw.