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 -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.
| Product | Delivery | Access | Protocols |
|---|---|---|---|
| Residential Lite | Rotating gateway | Username and password | HTTP + SOCKS5 |
| Shared ISP · USA (Plan #3) | Rotating gateway | Username and password | HTTP + SOCKS5 |
| Datacenter IPv4 (Plan #2) | Proxy list | Username and password, or whitelisted IP | HTTP + SOCKS5 |
| IPv6 Residential | Rotating gateway | Username and password | HTTP + SOCKS5 |
| IPv6 Datacenter | Rotating gateway | Username and password | HTTP + SOCKS5 |
| Dedicated ISP Pool | Proxy list | Username and password | HTTP |
| Dedicated ISP | Proxy list | Username and password | HTTP |
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:
{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.
USERNAME USERNAME-country-us USERNAME-country-us-state-california-city-losangeles USERNAME-country-de-asn-3320 USERNAME-country-us-zip-10001-session-a1b2c3
| Key | Filter | What it does | Format | Example | Products |
|---|---|---|---|---|---|
| country | Country | Exit from one country. | Two-letter code | -country-us | Resi LiteISP USAIPv6 ResiIPv6 DC |
| state | State or region | Narrows the country to one state or region. Needs a country. | Name, no spaces | -state-california | Resi LiteISP USAIPv6 ResiIPv6 DC |
| city | City | Narrows the country to one city. Needs a country. | Name, no spaces | -city-losangeles | Resi LiteISP USAIPv6 ResiIPv6 DC |
| asn | ASN | Exit from one network operator, by autonomous system number. Needs a country. | Number | -asn-7922 | Resi LiteISP USAIPv6 ResiIPv6 DC |
| zip | ZIP or postal code | Narrows the country to one postal area. Needs a country. | Letters and digits | -zip-90012 | Resi LiteISP USAIPv6 ResiIPv6 DC |
| ip | Pinned exit IP | Sends every request through one exit IP picked from the live rotation. | Dots become underscores | -ip-203_0_113_24 | ISP USA |
| session | Sticky session | Requests with the same label reuse the same exit. Leave it out to rotate. | 1 to 32 letters or digits | -session-a1b2c3 | Resi 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.
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.
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.
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)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());const browser = await chromium.launch({
proxy: {
server: "http://HOST:HTTP_PORT",
username: "USERNAME-country-us-session-run7",
password: "PASSWORD",
},
});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.
Build a username visually in the generator, or compare products on the pricing page.