Documentation

Connecting to your plan

Every purchase creates a plan with its own credentials. This page covers how each product is delivered, how to describe an exit in the username, and how to keep a plan running.

01Quick start

Buying a plan creates it with its own credentials. Open it from your plans in the dashboard: the plan page shows the username and password, and either the gateway host with its HTTP and SOCKS5 ports or a proxy list to download. Point any proxy-aware client at the host and port shown there.

curl
curl -x "http://USERNAME:PASSWORD@HOST:PORT" https://api.ipify.org
Host
The host shown on your plan page.
Ports
Gateway products show one HTTP port and one SOCKS5 port. Proxy lists carry a port on every line.
Auth
Basic proxy authentication with the plan's username and password. Datacenter IPv4 (Plan #2) can also skip the password: requests from a whitelisted IP are let in without credentials.

02Gateway or proxy list

Products reach you in one of two shapes. Gateway products (Residential Lite, Shared ISP · USA (Plan #3), IPv6 Residential and IPv6 Datacenter) give you one host: each request can leave from a different IP, and targeting and sessions go in the username. List products (Datacenter IPv4 (Plan #2), Dedicated ISP Pool and Dedicated ISP) give you individual proxies, one host and port per line, which you can copy or download as a text file from the plan page.

ProductDeliveryAccessProtocols
Residential LiteRotating gatewayUsername and passwordHTTP + SOCKS5
Shared ISP · USA (Plan #3)Rotating gatewayUsername and passwordHTTP + SOCKS5
Datacenter IPv4 (Plan #2)Proxy listUsername and password, or whitelisted IPHTTP + SOCKS5
IPv6 ResidentialRotating gatewayUsername and passwordHTTP + SOCKS5
IPv6 DatacenterRotating gatewayUsername and passwordHTTP + SOCKS5
Dedicated ISP PoolProxy listUsername and passwordHTTP
Dedicated ISPProxy listUsername and passwordHTTP

03Username targeting

On Residential Lite, Shared ISP · USA (Plan #3), IPv6 Residential and IPv6 Datacenter, you describe the exit by appending key and value pairs to the plan's username. Keep the keys in this order and leave out any you don't need:

grammar
{username}-country-{cc}-state-{state}-city-{city}-asn-{n}-zip-{zip}-ip-{a_b_c_d}-session-{id}
  • Values are lower-case letters and digits with no spaces. The username is split on hyphens, so no value may contain one: Los Angeles becomes losangeles.
  • State, city, ASN and ZIP narrow a country, so they need a country first.
  • The values each product accepts come from its live catalog. The generator lists them and builds the username for you.
examples
USERNAME
USERNAME-country-us
USERNAME-country-us-state-california-city-losangeles
USERNAME-country-de-asn-3320
USERNAME-country-us-zip-10001-session-a1b2c3
KeyFilterWhat it doesFormatExampleProducts
countryCountryExit from one country.Two-letter code-country-usResi LiteISP USAIPv6 ResiIPv6 DC
stateState or regionNarrows the country to one state or region. Needs a country.Name, no spaces-state-californiaResi LiteISP USAIPv6 ResiIPv6 DC
cityCityNarrows the country to one city. Needs a country.Name, no spaces-city-losangelesResi LiteISP USAIPv6 ResiIPv6 DC
asnASNExit from one network operator, by autonomous system number. Needs a country.Number-asn-7922Resi LiteISP USAIPv6 ResiIPv6 DC
zipZIP or postal codeNarrows the country to one postal area. Needs a country.Letters and digits-zip-90012Resi LiteISP USAIPv6 ResiIPv6 DC
ipPinned exit IPSends every request through one exit IP picked from the live rotation.Dots become underscores-ip-203_0_113_24ISP USA
sessionSticky sessionRequests with the same label reuse the same exit. Leave it out to rotate.1 to 32 letters or digits-session-a1b2c3Resi LiteISP USAIPv6 ResiIPv6 DC

Products lists where a key can work. The exact keys and values a plan accepts come from that product's live catalog, and the generator in your dashboard only offers those.

04Sticky sessions

Without a session key, each request can leave from a different IP. Add -session- with a label of 1 to 32 letters or digits and every request carrying that label reuses the same exit. Change the label when you want a new IP, and give each worker its own label to run sessions in parallel. Sessions are available on Residential Lite, Shared ISP · USA (Plan #3), IPv6 Residential and IPv6 Datacenter.

same label, same exit
curl -x "http://USERNAME-country-gb-session-job42:PASSWORD@HOST:PORT" https://api.ipify.org
curl -x "http://USERNAME-country-gb-session-job42:PASSWORD@HOST:PORT" https://api.ipify.org

An exit is a real connection and can go offline, so build a retry into long jobs. The generator can give every line of a bulk export its own label.

05IP pinning

On Shared ISP · USA (Plan #3), you can send every request through one exit IP from the live rotation. Add -ip- with the address, dots replaced by underscores. The generator on the plan page lists the IPs you can pin to right now; if the one you chose leaves the rotation, pick another from that list.

pin one exit
USERNAME-ip-203_0_113_24

06IP allowlists

Extra lock
On Residential Lite, Shared ISP · USA (Plan #3), IPv6 Residential and IPv6 Datacenter, you can add an IP allowlist on top of the username and password from the plan page, so the plan only works from addresses you list.
Instead of a password
On Datacenter IPv4 (Plan #2), whitelisted IPv4 addresses connect without credentials (1 slot, or 5 with the extra IP authentication add-on). The username and password keep working from anywhere.
Not used
Dedicated ISP Pool and Dedicated ISP authenticate by username and password only.

To find the public IP of a machine, run curl https://api.ipify.org on it without a proxy.

07Extending a plan

Top up
Residential Lite: add gigabytes to the same plan from its page. The volume rate applies to the top-up, and gigabytes stay usable for 180 days from purchase.
Renew
Shared ISP · USA (Plan #3), IPv6 Residential, IPv6 Datacenter, Dedicated ISP Pool and Dedicated ISP: renew from the plan page to add another term to the same plan straight away.
Renew ahead
Datacenter IPv4 (Plan #2): renew from the plan page before it ends. You pay now, and the same plan continues for another term of the same length when the current one ends, with the same credentials and whitelist. If the renewal can't go through, the payment goes back to your balance.

Nothing renews or charges on its own. You add funds in crypto, and each order is paid from your balance.

08Client examples

Replace HOST and the ports with the values on your plan page.

python · requests
import requests

proxy = "http://USERNAME-country-de-session-a1b2:PASSWORD@HOST:HTTP_PORT"
r = requests.get(
    "https://api.ipify.org",
    proxies={"http": proxy, "https": proxy},
    timeout=30,
)
print(r.text)
node · undici
import { ProxyAgent, fetch } from "undici";

const dispatcher = new ProxyAgent("http://USERNAME-country-gb:PASSWORD@HOST:HTTP_PORT");
const res = await fetch("https://api.ipify.org", { dispatcher });
console.log(await res.text());
playwright
const browser = await chromium.launch({
  proxy: {
    server: "http://HOST:HTTP_PORT",
    username: "USERNAME-country-us-session-run7",
    password: "PASSWORD",
  },
});
curl · socks5
curl -x "socks5h://USERNAME:PASSWORD@HOST:SOCKS_PORT" https://api.ipify.org

09Errors

407 Proxy Authentication Required
Usually a wrong username or password, or a targeting key or value the product doesn't accept. Build the username in the generator, which only offers what your plan supports.
Refused from a new machine
If the plan has an IP allowlist, or authenticates by IP, add that machine's public IP on the plan page.
Connection refused or closed
Often a plan that has expired or run out of data. The plan page shows what's left; top up or renew, then retry.
Slow first byte
Very tight filters take longer to satisfy. Drop the ZIP or city if a quick match matters more than precision.

Still stuck? Open a ticket with the plan and the exact username you used, minus the password.

Next

Build a username visually in the generator, or compare products on the pricing page.