Proxy Setup Guide: How to Connect Residential Proxies

Create an account on the sign-up page and you receive one access token in the format pm_XXXXXXXX-XXXXXXXX-XXXXXXXX-XXXXXXXX. The same token logs you in to the site and works as your proxy password.

The server keeps only a hash of the token and its last 4 characters. Store it in a password manager or another safe place before you leave the page.

A lost token cannot be recovered. In code, read it from an environment variable so it never ends up in a repository.

You can create up to 3 accounts per IP address, and login allows 10 tries per 10 minutes.

Proxies draw from your balance, so top up first. One balance covers Rotating residential proxies, Static ISP proxies, Datacenter proxies and Mobile proxies.

Rotating residential traffic starts at $0.80/GB and mobile traffic at $4.00/GB, charged for what you use. For example, $100 spent on rotating residential buys $100 divided by $0.80/GB in traffic. See top-up amounts and bonuses on the plans page.

The username starts with user and adds optional parts joined by -. The password is always your access token. With no parts added, you get a rotating residential IP with no country set.

Writing the parts in the order type, country, city, session keeps them readable. user-country-jp-city-tokyo-session-shop1 means a Tokyo IP held under the session name shop1.

Mobile proxies target by country only, so leave city out when you use type-mobile. Country codes and city lists are on the coverage page.

HTTP and SOCKS5 share the same host gate.proxymay.com and port 7000. Pick whichever of these three formats your tool accepts.

http://user-country-jp:[email protected]:7000
socks5://user-country-jp:[email protected]:7000
gate.proxymay.com:7000:user-country-jp:YOUR_TOKEN

The dashboard builds the same strings for you to copy. The first two lines are URL formats; the last one is for tools that expect host:port:user:password.

Before writing code, test from a terminal. It narrows down problems fast. Check that ip, country and city in the response match your username.

curl -x http://user-country-us:[email protected]:7000 https://ipinfo.io/json

# Same check over SOCKS5
curl -x socks5h://user-country-us:[email protected]:7000 https://ipinfo.io/json

With socks5h, DNS lookups also go through the proxy.

In requests, put the same URL under http and https in the proxies dict. This example keeps a Japanese IP under session shop1.

import requests

proxy = "http://user-country-jp-session-shop1:[email protected]:7000"
proxies = {"http": proxy, "https": proxy}

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

For SOCKS5, run pip install requests[socks] and change the scheme to socks5h://.

In Scrapy, set proxy in the request meta and the built-in middleware handles authentication. Give each request its own session name if you want a different IP per page.

import scrapy

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

    def start_requests(self):
        proxy = "http://user-country-gb:[email protected]:7000"
        yield scrapy.Request("https://ipinfo.io/json", meta={"proxy": proxy})

    def parse(self, response):
        yield response.json()

On Node.js 18 or later, pass undici's ProxyAgent as the fetch dispatcher. If you use axios, hand the same URL to the https-proxy-agent package.

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

const agent = new ProxyAgent("http://user-country-de:[email protected]:7000");
const res = await fetch("https://ipinfo.io/json", { dispatcher: agent });
console.log(await res.json());

Browser automation tools take the server and the credentials separately. Put your targeting parts in the username and your token in the password.

// Playwright
const { chromium } = require("playwright");

const browser = await chromium.launch({
  proxy: {
    server: "http://gate.proxymay.com:7000",
    username: "user-country-fr-city-paris-session-web1",
    password: "YOUR_TOKEN",
  },
});
const page = await browser.newPage();
await page.goto("https://ipinfo.io/json");

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

For jobs that stay logged in, add a session name so every page opens from the same IP.

Without a session part, every request gets a new IP. That suits independent requests such as rank checks or price collection.

Logins, carts and multi-step flows can break when the IP changes. Add session-name to keep the same IP for up to 120 minutes.

• Give each task its own session name (for example cart1, cart2).
• To switch IPs, just change the session name.
• If you need the same IP for a whole month, Static ISP proxies are the better fit.

• 407 Proxy Authentication Required: the username format or the token is wrong. Check that it starts with user, that parts are separated by -, and that the token has no extra spaces.
• Connection refused or timeout: recheck host gate.proxymay.com and port 7000, and make sure a firewall is not blocking outbound connections to that port. Also confirm you have balance left.
• Wrong country shown: check that the country code has two letters and the city is lowercase with _. Run the curl check first, then look for caching or another proxy setting in your code.
• Session changed after 120 minutes: this is expected, because a sticky session lasts up to 120 minutes. Split the work to fit that window or start again with a new session name.

More answers are collected in the FAQ.

Use ProxyMay for public data collection, ad verification, SEO rank checks, price monitoring, website and localization testing, and managing your own accounts. Unauthorized access to other people's accounts, spam, fraud, attacks, illegal content and anything that violates the law or a target site's rights are forbidden.

Pacing your requests and respecting each site's rules also keeps your jobs running smoothly. The full rules are in the terms of service.