Residential Proxies

Residential proxies route your traffic through IP addresses assigned by real Internet Service Providers (ISPs) to ordinary households. Because these IPs are indistinguishable from everyday consumer traffic, they carry the highest trust scores on virtually every anti-bot platform — including Cloudflare, Akamai, Datadome, and Imperva.

NinjasProxy operates a peer-sourced residential network of 72 million+ IPs spanning 195 countries. All peers participate under explicit consent agreements in compliance with applicable data-protection regulations. The pool refreshes continuously, so IPs are fresh and active.

Endpoint & Port

Connect through one of two host modes depending on whether you need a rotating or sticky session:

ModeHostPort
Rotating (new IP per request)r.ninjasproxy.com8080
Sticky (fixed IP, session-based)r.ninjasproxy.com8080
Both rotating and sticky sessions use the same host. The session mode is controlled entirely by your username string — no separate endpoint is needed.

Authentication

Authenticate using your portal username and API key as HTTP proxy credentials (Proxy-Authorization header). The username also encodes your targeting parameters and session options using a dash-delimited suffix format.

Rotating (default)

Each request receives a fresh IP from the pool. No extra flags needed:

USERNAME:API_KEY

Sticky sessions

Append -session-<ID> to your username to pin requests to the same exit IP for up to 60 minutes. Use any alphanumeric string as the session ID — NinjasProxy maps it to a consistent peer for the duration of the session.

USERNAME-session-abc123:API_KEY

Sessions expire after 60 minutes of inactivity or when the underlying peer disconnects. Generate a new random ID to start a fresh session anytime.

Geo-Targeting

Country targeting

Append -country-XX using the two-letter ISO 3166-1 alpha-2 country code:

# United States exit node
USERNAME-country-US:API_KEY

# Germany exit node
USERNAME-country-DE:API_KEY

City targeting

Combine country and city for precise geo-location. City names use CamelCase with no spaces:

# New York City, US
USERNAME-country-US-city-NewYork:API_KEY

# London, UK
USERNAME-country-GB-city-London:API_KEY

# São Paulo, Brazil
USERNAME-country-BR-city-SaoPaulo:API_KEY
City availability varies by country. High-coverage cities include major metros in the US, EU, UK, AU, CA, and BR. Check the portal's geo-coverage map for a full list of supported city codes.

Sticky session + country

Combine targeting and session persistence freely — parameters are order-independent:

USERNAME-country-US-city-LosAngeles-session-sess42:API_KEY

Code Examples

curl

# Basic rotating residential request
curl --proxy "http://USERNAME:API_KEY@r.ninjasproxy.com:8080" \
     "https://api.ipify.org?format=json"

# Sticky session in the US
curl --proxy "http://USERNAME-country-US-session-mysess01:API_KEY@r.ninjasproxy.com:8080" \
     "https://api.ipify.org?format=json"

# City-level targeting — Chicago
curl --proxy "http://USERNAME-country-US-city-Chicago:API_KEY@r.ninjasproxy.com:8080" \
     "https://httpbin.org/ip"

Python (requests)

import requests
import random
import string

PROXY_HOST = "r.ninjasproxy.com"
PROXY_PORT = 8080
USERNAME   = "your_username"
API_KEY    = "your_api_key"

def make_session_id(length=10):
    return ''.join(random.choices(string.ascii_lowercase + string.digits, k=length))

# ── Rotating residential ────────────────────────────────────────
proxies = {
    "http":  f"http://{USERNAME}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
    "https": f"http://{USERNAME}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
}
r = requests.get("https://api.ipify.org?format=json", proxies=proxies, timeout=30)
print("Rotating IP:", r.json()["ip"])

# ── Sticky session — same IP for up to 60 min ──────────────────
session_id = make_session_id()
user_sticky = f"{USERNAME}-session-{session_id}"
proxies_sticky = {
    "http":  f"http://{user_sticky}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
    "https": f"http://{user_sticky}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
}
for i in range(3):
    r = requests.get("https://api.ipify.org?format=json", proxies=proxies_sticky, timeout=30)
    print(f"Request {i+1} IP (should be identical):", r.json()["ip"])

# ── Country + city targeting ───────────────────────────────────
user_geo = f"{USERNAME}-country-US-city-NewYork"
proxies_geo = {
    "http":  f"http://{user_geo}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
    "https": f"http://{user_geo}:{API_KEY}@{PROXY_HOST}:{PROXY_PORT}",
}
r = requests.get("https://api.ipify.org?format=json", proxies=proxies_geo, timeout=30)
print("New York IP:", r.json()["ip"])

Next Steps