Residential setup

Residential is the most flexible product, with the most setup options. This page covers all of them.

Generator

Unified Proxy Generator — select Residential as the product.

Gateways

Pick the gateway closest to your traffic source.

Ports

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:[email protected]: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 213 countries and territories. 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-<name>

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

Exclusions

Use -not. flags to exclude rather than include.

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

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.

Per-session bandwidth cap (-limit-)

Add a -limit-<MB> 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-<id> 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 (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 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.

Choose a network

By default Eclipse picks the best available network for every request. If you want to stay on one, add -pool- and a network code to the end of your username:

acme-country-us-pool-vega

You can allow more than one by separating them with a comma, and Eclipse will use whichever is best at the time:

acme-country-us-pool-orion,vega

Sticky sessions stay on the network they started on. Leave the code out to go back to automatic.

Rules:

• -pool- must be the last segment in the username. Anything after it is read as part of the network code and the request fails.
• Only the codes above are accepted. An unknown code is refused (HTTP 503 Service Unavailable, SOCKS5 network unreachable), never silently redirected, so a typo shows up immediately in testing.
• In the dashboard generator, tick the networks you want under Advanced Options → Network. Tick more than one to allow a mix; tick Automatic to clear them.

Authentication

User:pass (default) or IP whitelist. See Authentication.

Pool basics

• ~2.3 million IPs online at any one time, across 213 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
• "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