> ## Documentation Index > Fetch the complete documentation index at: https://docs.eclipseproxy.com/llms.txt > Use this file to discover all available pages before exploring further. # Residential setup > Generate Residential proxies: gateways, ports, format, targeting (country/state/city/ASN/ISP), sticky vs rotating, exclusions, strict matching Residential is the most flexible product, with the most setup options. This page covers all of them. ## Generator [Unified Proxy Generator](https://www.eclipseproxy.com/dashboard/proxy-generator) — select **Residential** as the product. ## Gateways Pick the gateway closest to your traffic source. | Gateway | Region | | -------------------------- | ------------- | | `core.eclipseproxy.com` | Auto-routed | | `us.core.eclipseproxy.com` | United States | | `sg.core.eclipseproxy.com` | Singapore | ## Ports | Port | Protocol | Session | | ------- | -------- | -------- | | `9000` | HTTP | Rotating | | `10000` | HTTP | Sticky | | `11000` | SOCKS5 | Rotating | | `12000` | SOCKS5 | Sticky | ## Format Two equivalent formats: ``` core.eclipseproxy.com:10000:eclipse_yourname-country-kh-state-phnompenh-asn-38901-session-OaUE4kFO-lifetime-30:your_password_here ``` ``` http://eclipse_yourname-country-kh-state-phnompenh-asn-38901-session-OaUE4kFO-lifetime-30:your_password_here@core.eclipseproxy.com:10000 ``` For SOCKS5, swap `http://` for `socks5://`. ## Username segments The username encodes all your targeting and session settings, joined with `-`: ``` eclipse_yourname ← account -country-kh ← country (ISO 3166-1 alpha-2) -state-phnompenh ← state (lowercase, no spaces) -asn-38901 ← ASN (must pair with country) -session-OaUE4kFO ← sticky session ID -lifetime-30 ← lifetime in minutes -limit-500 ← per-session bandwidth cap, in MB ``` All segments after the account name are optional. The minimum valid username is just your account name. ## Targeting ### Country ISO 3166-1 alpha-2 codes: `us`, `gb`, `de`, `fr`, `it`, `es`, `br`, `in`, `kh`, etc. We cover 190+ countries. The dashboard generator dropdown is the source of truth for what's currently available. ``` -country-us ``` ### State / region Lowercased, no spaces: ``` -country-us-state-california -country-kh-state-phnompenh ``` ### City Lowercased, no spaces: ``` -country-us-city-losangeles ``` ### State OR city: not both **You can target either state OR city, not both at the same time.** This is a pool-level constraint. ``` -country-us-state-california ✓ -country-us-city-losangeles ✓ -country-us-state-california-city-losangeles ✗ ``` ### ASN Specific ISP networks. Must be paired with country: ``` -country-us-asn-7018 ``` ASN alone returns `{"proxy-error":"ASN should be used with country."}`. ### ISP ``` -country-us-isp- ``` ## Strict matching and fallback By default, if your targeting can't be satisfied (no IPs available for that combo), you get a `proxy-error`. Add `-strict-off` to opt into fallback: the system returns any available IP in the country. ``` -country-fr-asn-3215-strict-off ``` Use strict (default) when you'd rather an explicit error than the wrong geo. Use `-strict-off` when you'd rather any IP in the country than no IP. ### Errors | Error | Cause | | ---------------------------------------- | ---------------------------------------------------------------- | | `country-XX-asn-YY target was not found` | Strict matching, no IPs available. Try `-strict-off` or broaden. | | `ASN should be used with country.` | ASN without country. Add `-country-XX`. | ## Exclusions Use `-not.` flags to exclude rather than include. | Flag | Example | | -------------------- | ------------------------------- | | `-not.country-XX,YY` | `-not.country-us,ca,mx` | | `-not.state-NAME` | `-not.state-california,newyork` | | `-not.city-NAME` | `-not.city-charlotte,newyork` | | `-not.asn-NUMBER` | `-not.asn-31898,12345` | **Rule: one exclusion type per request.** Can't mix `-not.country-` with `-not.state-` in the same request. Combine exclusions with positive targeting: ``` -country-us-not.asn-31898 ← US IP, but not ASN 31898 -not.country-us,ca ← anywhere except US/Canada ``` ## Sticky vs rotating | | Rotating | Sticky | | --------------- | ------------------------------ | ----------------------------------------------- | | **IP behavior** | New IP per connection | Same IP for a duration | | **Port** | 9000 (HTTP) / 11000 (SOCKS5) | 10000 (HTTP) / 12000 (SOCKS5) | | **Username** | No `-session-` segment | `-session--lifetime-` | | **Use for** | Scraping, distributed crawling | Login, account management, multi-step workflows | ### Sticky session syntax ``` -session-abc123-lifetime-30 ``` * Same `session-abc123` returns the same IP across requests * After `lifetime-30` minutes, the session expires * Different session IDs return different IPs ### Lifetime values Common: 1, 5, 10, 30, 60, 120, 1000 minutes. For sticky beyond a few hours, the upstream residential IP may rotate before lifetime expires (out of our control). For guaranteed stability, use [ISP](/products/isp). ### Per-session bandwidth cap (`-limit-`) Add a `-limit-` segment to cap how much bandwidth a single session may consume. It's an optional control for keeping individual sessions from burning through more data than you intend. ``` -session-abc123-lifetime-30-limit-500 ← this session can use up to 500 MB ``` * **Units:** megabytes (MB). * **Scope:** per session. The cap applies to the specific `-session-` it's attached to, not your whole account. * **Behavior:** once the session transfers more than the limit, further requests on that session fail with [error 467](/errors/codes) (`Session bandwidth limit`). Switch to a new session ID to keep going. This is independent of your account-wide balance: running out of account bandwidth returns [error 466](/errors/codes) instead. ### "Why does session ID change when I change lifetime?" The dashboard generator regenerates a random session ID alongside any change. They aren't linked: to keep the same session ID with a different lifetime, copy the session ID manually. ## Authentication User:pass (default) or IP whitelist. See [Authentication](/setup/authentication). ## Pool basics * \~1 million IPs across 190+ countries * Pool changes constantly as residential users come online/offline * Threads unlimited on Residential * GB you buy never expires ## Things to watch for * **"All my generated proxies look the same"**: normal for rotating; each connection rotates at the gateway * **"Wrong country IP"**: usually a username typo or no inventory for that city; verify with `curl -x ... https://ipinfo.io`. See [Wrong country IP](/errors/common-issues#wrong-country-ip) * **"City has no inventory"**: try `-strict-off` or broaden to state/country * **"Protocol mismatch error"**: using HTTP creds on SOCKS port or vice versa; re-generate with correct port