# Everything you want from the exit, written into the username.

Country, US state, city, provider, session identity and lifetime. Six parameters, in any order, on both shared gateways.


## Syntax

Start with your username, then append `-key-value` pairs. Keys and values are lowercase; order does not matter; the password is unchanged. With no parameter at all the exit is chosen from any country and changes on every connection.

```text
USER-cc-us-state-tx-city-austin-sid-a1b2c3-ttl-30m:PASS
│    │     │        │           │          │
│    │     │        │           │          └─ hold it for 30 minutes
│    │     │        │           └─ session id: same id, same IP
│    │     │        └─ city (letters and digits only)
│    │     └─ US state (United States only)
│    └─ country, ISO 3166-1 alpha-2
└─ your username
```


## Parameters

| Parameter | Values | Meaning |
| --- | --- | --- |
| -cc- | Two-letter country code: `us`, `de`, `br`, `jp` | Exit from that country. 199 countries on residential; the mobile pool covers the countries listed at checkout. |
| -state- | US state code: `tx`, `ca`, `ny` | Exit from that state. Requires `-cc-us`; not available for other countries. |
| -city- | City name, lowercase, letters and digits only: `newyork`, `berlin`, `saopaulo` | Exit from that city. Requires `-cc-`. Each [country page](https://hodlproxy.com/locations) lists its available cities with the exact value. |
| -asn- | Autonomous system number without the `AS` prefix: `7922`, `3320` | Exit announced by that provider. Combine with `-cc-`. On the mobile pool this is how you pick a carrier. |
| -sid- | Letters and digits, up to 32 characters: `a1b2c3`, `job42` | Sticky session. Requests carrying the same id share one exit until the lifetime ends or the device goes offline. A new id means a new IP. |
| -ttl- | Minutes or hours, from `1m` to `24h`: `10m`, `2h` | Lifetime of a sticky session, counted from its first request. Default `10m` when `-sid-` is present without `-ttl-`. |


## Rotation and sessions

Without `-sid-` the gateway picks a new exit for **every new connection** it receives. Clients that keep a connection alive, or that send many requests through one `CONNECT` tunnel, keep the same exit for as long as that connection lives. To rotate on every request, disable keep-alive or close the connection after each call; to keep one IP across connections, use a session id.

- Same `-sid-` value, same IP, on any number of parallel connections. Run as many sessions at once as you need; there is no cap.
- When the lifetime expires or the household disconnects, the next request with that id gets a **new** IP that still matches the other parameters. Design for this: an IP change mid-flow is possible on any residential network.
- To force a change immediately, change the id. Ids are scoped to your account and cost nothing.
- Sticky sessions exist on the residential and mobile pools. Dedicated ISP, datacenter and mobile-device proxies are one fixed IP and ignore `-sid-` and `-ttl-`.


## Examples

| You want | Username |
| --- | --- |
| A new IP in any country on every connection | USER |
| A new United States IP on every connection | USER-cc-us |
| A Texas household | USER-cc-us-state-tx |
| Any IP in Berlin | USER-cc-de-city-berlin |
| One Berlin IP held for ten minutes | USER-cc-de-city-berlin-sid-7f3a9 |
| One Japanese IP held for two hours | USER-cc-jp-sid-tokyo1-ttl-2h |
| A Comcast subscriber (AS7922) | USER-cc-us-asn-7922 |
| Deutsche Telekom mobile customers, held 15 minutes | USER-cc-de-asn-3320-sid-m1-ttl-15m |
| Twenty parallel Brazilian sessions | USER-cc-br-sid-w01 … USER-cc-br-sid-w20 |


## City names

A city value is the city name in lowercase ASCII with spaces, hyphens, apostrophes and accents removed: `New York` becomes `newyork`, `São Paulo` becomes `saopaulo`, `Düsseldorf` becomes `dusseldorf`, `Frankfurt am Main` is listed as `frankfurt`. Use the value printed on the country page rather than guessing; that is the exact string the gateway matches.


## What happens when a parameter cannot be honoured

| Case | Response | What to do |
| --- | --- | --- |
| Unknown key or malformed value (`-country-us`, `-ttl-90x`) | `400 Bad Request` | Fix the string; the response body names the parameter. |
| `-city-` or `-state-` without `-cc-`, or `-state-` outside the US | `400 Bad Request` | Add `-cc-us` or drop the parameter. |
| No exit currently online for the combination (a small city plus one ASN, for instance) | `502 Bad Gateway` | Retry, then broaden: drop `-asn-`, then `-city-`. |
| Parameters sent to a dedicated address | Ignored | Nothing; the IP is fixed. |

> Tip: Start broad and narrow down. Country-level targeting has the deepest pools and the highest success rates; add city and ASN only when the job needs them, and keep sticky lifetimes as short as the flow allows.


Source: https://hodlproxy.com/docs/username-parameters