No KYC — no ID, no selfie, no documents · City targeting on every plan · Paid in crypto
Language: English
Get started

Docs · HTTP, HTTPS, SOCKS5

City proxy API and gateway docs

Everything you need to connect: one gateway, one username format, and tested samples you can paste. The account and order API is documented under API docs.

Last updated: · 4 min read

Quick answer

How do I connect to Banyan Proxies residential proxies?

Connect to gw.banyanproxies.com, port 7777 for HTTP and HTTPS or 7778 for SOCKS5, with your proxy password and a username built from segments: USERNAME-country-in-city-pune-asn-24560-session-a1-ttl-15. Use only the segments you need. Every plan, from $1.88 for 1 GB, includes city and ASN targeting.

Which username segments can I use?

Full format: USERNAME-country-{cc}-city-{city}-asn-{asn}-session-{id}-ttl-{minutes}. Keep the order; omit what you do not need.

SegmentExampleMeaning
-country-<cc>-country-idTwo-letter ISO country code, lowercase
-city-<name>-city-surabayaCity name, lowercase, underscores for spaces
-asn-<number>-asn-7713ISP network number, without "AS"
-session-<id>-session-cart2Ties requests to one sticky IP
-ttl-<minutes>-ttl-20Sticky duration, up to 30 minutes

Which host, ports and authentication do I use?

Hostgw.banyanproxies.com
HTTP / HTTPS port7777
SOCKS5 port7778
AuthenticationUsername and password on every plan, or an IP allowlist (up to 10 IPs). Sub-users with their own credentials and traffic cap. API keys you can revoke at any time
RotationEach new connection gets an IP from the pool, usually a different one; to get a new IP on every request, send one request per connection (turn off keep-alive)
Sticky sessionsup to 30 minutes (the IP can change earlier)
BlockedBanking, government and payment-portal sites, plus SMTP (email-sending) ports 25, 465 and 587

Which code samples can I copy?

Each sample requests one IP and prints what a lookup service sees. Replace USERNAME and PASSWORD. The city targeting page and the sticky sessions guide have more.

curl over SOCKS5: a Wellington IP
curl --socks5-hostname gw.banyanproxies.com:7778 \
  -U "USERNAME-country-nz-city-wellington:PASSWORD" \
  https://ipinfo.io/json
Python (httpx): retry with a new session when an IP fails
import uuid

import httpx

HOST = "gw.banyanproxies.com"
PORT = 7777


def fetch(url, city="lahore", country="pk", tries=3):
    for _ in range(tries):
        sid = uuid.uuid4().hex[:8]
        user = f"USERNAME-country-{country}-city-{city}-session-{sid}-ttl-10"
        proxy = f"http://{user}:PASSWORD@{HOST}:{PORT}"
        try:
            with httpx.Client(proxy=proxy, timeout=30) as client:
                r = client.get(url)
                r.raise_for_status()
                return r.text
        except httpx.HTTPError as exc:
            print("retrying with a new IP:", exc)
    return None


print(fetch("https://ipinfo.io/json"))
Node.js (undici): one Ho Chi Minh City IP
// npm install undici
const { ProxyAgent, fetch } = require("undici");

const user = "USERNAME-country-vn-city-ho_chi_minh_city";
const token = "Basic " + Buffer.from(`${user}:PASSWORD`).toString("base64");
const dispatcher = new ProxyAgent({
  uri: "http://gw.banyanproxies.com:7777",
  token,
});

async function main() {
  const res = await fetch("https://ipinfo.io/json", { dispatcher });
  const info = await res.json();
  console.log(info.ip, info.city, info.region);
}

main().catch((err) => console.error(err.message));
Playwright (Python): a browser with a Sydney IP and matching time zone
from playwright.sync_api import sync_playwright

PROXY = {
    "server": "http://gw.banyanproxies.com:7777",
    "username": "USERNAME-country-au-city-sydney-session-syd1-ttl-15",
    "password": "PASSWORD",
}

with sync_playwright() as p:
    browser = p.chromium.launch(proxy=PROXY)
    context = browser.new_context(
        timezone_id="Australia/Sydney",
        locale="en-AU",
    )
    page = context.new_page()
    page.goto("https://ipinfo.io/json")
    print(page.inner_text("body"))
    browser.close()

What do common error codes mean?

Code or symptomLikely causeWhat to do
407 Proxy Authentication RequiredWrong username, password or segment syntaxCopy credentials again; check hyphens and underscores
Timeout on connectWrong port or a firewallUse 7777 for HTTP, 7778 for SOCKS5
Errors for one city onlyFew home devices online there nowRetry later, use a nearby city, or drop the city segment
403 or 429 from the targetThe target refuses or rate-limitsSlow down; respect the site's terms and robots.txt
Connection refused to a bank or SMTP portBlocked targetThese targets are blocked by policy

Where is the rest of the documentation?

Where do I go when something fails?

Check the service status first, then the proxy city checker for location doubts and the glossary for terms. Write to support from the contact page.

What else do developers ask?

Do I need a special endpoint per country or city?

No. One gateway serves every location; the username decides where the IP is.

Can I use an IP allowlist instead of a password?

Username and password on every plan, or an IP allowlist (up to 10 IPs). Sub-users with their own credentials and traffic cap. API keys you can revoke at any time.

Are the samples tested?

Each Python sample is compiled and each JavaScript sample syntax-checked before publication. Install the libraries they name first: httpx, undici or Playwright.

1 GB $1.88 · city targeting · no KYC

Get started