How to set up a residential proxy, from your token to working code

What are the steps to set up a residential proxy?

You set up a residential proxy by getting a token, topping up your balance and copying the connection details. There is no software to install, and any tool that accepts an HTTP or SOCKS5 proxy takes the details right away.

1. 1Create an account on the sign up page and you get one access token. The token works as both your login and your proxy password.
2. 2Copy the token or download it as a .txt file and keep it somewhere safe. The server stores only a hash of the token and its last 4 characters, so keeping your own copy matters.
3. 3Top up your balance in the dashboard. Top-ups start from $20.
4. 4Open the connection builder in the dashboard and pick the product, country, city and session.
5. 5Copy the connection format that fits your tool.
6. 6Run the curl test command to check the IP and country.

The connection builder writes the username from your choices, so copying it as is gives the most accurate result at first. The sections below explain how to build the same details by hand, with examples for each tool.

What is the residential proxy gateway and connection format?

Every product connects through the single gateway gate.proxyour.com:7000, with your choices in the username and your account token as the password. HTTP and SOCKS5 are both supported.

The dashboard shows the same details in several formats. Use the first one when a tool asks for host, port, username and password in separate fields, and the second or third when it takes a single address line.

gate.proxyour.com:7000:user-country-us:YOUR_TOKEN
http://user-country-us:YOUR_TOKEN@gate.proxyour.com:7000
socks5://user-country-us:YOUR_TOKEN@gate.proxyour.com:7000

• host:port:username:password: fits proxy managers and browser extensions with separate fields.
• http://username:token@gateway: fits code that takes one address line, such as Python, Node.js and Scrapy.
• socks5://username:token@gateway: fits programs that take SOCKS5 only.

The token contains only letters, digits, underscores and hyphens, so it fits inside an address as is. Treat it like a password and keep it in an environment variable rather than in public repositories or shared screens.

Connecting with a SOCKS5 proxy

For SOCKS5, the gateway, username and token stay the same and only the start of the address changes to socks5. It is handy for programs that do not take an HTTP proxy.

curl -x socks5h://gate.proxyour.com:7000 -U "user-country-us:YOUR_TOKEN" https://ipinfo.io/json

# Python: pip install "requests[socks]"
proxy = "socks5h://user-country-us:YOUR_TOKEN@gate.proxyour.com:7000"
proxies = {"http": proxy, "https": proxy}

socks5h resolves domain names on the proxy side, which gives results based on the connected country. To use SOCKS5 in Python, install the socks extra for requests first.

How is a proxy username built?

A proxy username starts with user, and each option is added with a hyphen. Country, city, session and the mobile IP option all live inside the username.

user-country-us
user-country-us-city-new_york
user-country-us-city-new_york-session-shop1
user-type-mobile-country-jp

Leaving a part out widens the range. With only a country you get IPs inside that country, and without a session each request gets a different IP. Supported countries and cities are listed on the proxies by country page.

How do I test a residential proxy with curl?

The fastest check is to send a curl request to ipinfo.io and read the IP and country that come back. The dashboard shows the same test command, so you can paste it directly.

curl -x http://gate.proxyour.com:7000 -U "user-country-us:YOUR_TOKEN" https://ipinfo.io/json

-x sets the gateway, and -U passes the username and token joined by a colon. Put your token in place of YOUR_TOKEN, run it and you get the details of a US residential IP as JSON.

Run it twice and a changed IP shows that rotation works. curl is available by default on Windows, macOS and Linux, so it is a good way to confirm the connection before writing code.

How do I set up a residential proxy in Python?

In Python requests, put the same proxy address under both http and https in the proxies dictionary. The username and token go inside the proxy address.

Python requests example

import requests

proxy = "http://user-country-us:YOUR_TOKEN@gate.proxyour.com:7000"
proxies = {"http": proxy, "https": proxy}

r = requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30)
print(r.json())

The proxy address starts with http:// even for https sites. The link to the proxy is HTTP, and the traffic to the real site is encrypted inside it.

Scrapy example

In Scrapy, set the proxy value in the request meta and the built-in proxy middleware handles the credentials. It suits jobs that collect many pages, such as web scraping and market research.

import scrapy


class IpSpider(scrapy.Spider):
    name = "ipcheck"

    def start_requests(self):
        yield scrapy.Request(
            "https://ipinfo.io/json",
            meta={"proxy": "http://user-country-de:YOUR_TOKEN@gate.proxyour.com:7000"},
        )

    def parse(self, response):
        self.logger.info(response.text)

How do I connect a residential proxy in Node.js?

In Node.js, create an undici ProxyAgent and pass it as the dispatcher of a fetch request, and the request goes through the proxy. Authentication goes in the token option as a Basic value.

// npm install undici
import { ProxyAgent, fetch } from "undici";

const username = "user-country-jp";
const token = "YOUR_TOKEN";

const agent = new ProxyAgent({
  uri: "http://gate.proxyour.com:7000",
  token: "Basic " + Buffer.from(username + ":" + token).toString("base64"),
});

const res = await fetch("https://ipinfo.io/json", { dispatcher: agent });
console.log(await res.json());

This example is an ES module, so name the file .mjs or add "type": "module" to package.json. If you need different countries per request, create a separate ProxyAgent with a different username.

How do I set a proxy in Puppeteer and Playwright?

In Puppeteer, pass the gateway with --proxy-server in the launch args and the username and token with page.authenticate. In Playwright, put server, username and password together in the launch proxy option.

Puppeteer example

import puppeteer from "puppeteer";

const browser = await puppeteer.launch({
  args: ["--proxy-server=http://gate.proxyour.com:7000"],
});
const page = await browser.newPage();
await page.authenticate({ username: "user-country-fr", password: "YOUR_TOKEN" });

await page.goto("https://ipinfo.io/json");
console.log(await page.evaluate(() => document.body.innerText));
await browser.close();

Playwright example

import { chromium } from "playwright";

const browser = await chromium.launch({
  proxy: {
    server: "http://gate.proxyour.com:7000",
    username: "user-country-br",
    password: "YOUR_TOKEN",
  },
});
const page = await browser.newPage();
await page.goto("https://ipinfo.io/json");
console.log(await page.textContent("body"));
await browser.close();

Browser automation fits work that needs the real screen, such as ad verification, SEO rank tracking and e-commerce page checks. One page sends many requests, so adding a session name keeps them on one IP for a steadier result.

How do I set a proxy in a browser or operating system?

In a browser or operating system, enter the host and port in the proxy settings and fill in the username and token when the sign in prompt appears. In the gate.proxyour.com:7000 address, the part before the colon is the host and the part after it is the port.

1. 1Install a proxy extension that supports authentication, or open the manual proxy section in your operating system network settings.
2. 2Choose HTTP or SOCKS5 as the protocol.
3. 3Split the gateway into the host and port fields.
4. 4Enter a value such as user-country-us as the username and your token as the password.
5. 5Save, then open ipinfo.io to check the IP and country.

Chrome follows the operating system proxy settings by default, so an extension is easier when you want only the browser on the proxy. With a system setting, other apps also send traffic through the proxy and add to GB usage, so keep it on only while you need it.

How do I check that the proxy IP and country are right?

You can confirm the connection by reading the ip, city and country values from ipinfo.io/json. If country matches the code in your username, country targeting works.

{
  "ip": "...",
  "city": "New York",
  "region": "New York",
  "country": "US",
  ...
}

• country: the 2-letter country code. A country-us request returns US.
• city: shows the city name when you set a city.
• ip: changes on every request with rotation, and stays the same during a session.

City data can differ a little between IP lookup services, so use the country value as the main check. Checking that the target site shows the local language, currency and search results makes it even clearer.

How do I set up a sticky session that keeps the same IP?

A sticky session adds session-name to the username, and while you use the same name the connection keeps the same IP for up to 120 minutes. Changing the session name gives you a new IP.

# same session name: the same IP is kept (up to 120 minutes)
curl -x http://gate.proxyour.com:7000 -U "user-country-us-city-new_york-session-shop1:YOUR_TOKEN" https://ipinfo.io/json
curl -x http://gate.proxyour.com:7000 -U "user-country-us-city-new_york-session-shop1:YOUR_TOKEN" https://ipinfo.io/json

# new session name: a new IP
curl -x http://gate.proxyour.com:7000 -U "user-country-us-city-new_york-session-shop2:YOUR_TOKEN" https://ipinfo.io/json

Splitting sessions in Python

import requests

def session_proxy(name):
    url = "http://user-country-us-session-" + name + ":YOUR_TOKEN@gate.proxyour.com:7000"
    return {"http": url, "https": url}

s = requests.Session()
s.proxies = session_proxy("cart1")
print(s.get("https://ipinfo.io/json", timeout=30).json()["ip"])
print(s.get("https://ipinfo.io/json", timeout=30).json()["ip"])  # same IP

Use sessions for work where the IP must not change midway, such as carts, logins and multi step pages. If you need the same address for a whole month, a static residential proxy fits better.

How do I fix a residential proxy that will not connect?

Most connection problems are solved by checking the username, token, country code or balance. Go through the list below one item at a time.

• 407 Proxy Authentication Required: the token or username is wrong. Check for spaces around the token and that the username starts with user.
• Country code: country is followed by a 2-letter lowercase code. Also check that the country is supported.
• Balance: a low balance stops connections, so check the balance in the dashboard and top up.
• City name: check it is lowercase, with underscores for spaces and no accents (for example city-sao_paulo).
• Timeouts: retry with a new session name to connect through a different IP. Add retries and a generous timeout in your code.
• Format: in a single line address, check there is a colon between username and token and an @ between token and gateway.

If a problem continues, copy fresh connection details from the connection builder in the dashboard to rule out typos. Other questions are answered in the FAQ.