# City proxy API and gateway docs

> Banyan Proxies docs: gateway host and ports, username segments for country, city, ASN and sessions, error codes, and tested curl, Python and Node.js samples.

- URL: https://banyanproxies.com/docs/
- Last updated: 2026-10-18
- Publisher: Banyan Proxies (https://banyanproxies.com)

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](https://banyanproxies.com/docs/api/).

**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.

| Segment | Example | Meaning |
| --- | --- | --- |
| `-country-<cc>` | `-country-id` | Two-letter ISO country code, lowercase |
| `-city-<name>` | `-city-surabaya` | City name, lowercase, underscores for spaces |
| `-asn-<number>` | `-asn-7713` | ISP network number, without "AS" |
| `-session-<id>` | `-session-cart2` | Ties requests to one sticky IP |
| `-ttl-<minutes>` | `-ttl-20` | Sticky duration, up to 30 minutes |

## Which host, ports and authentication do I use?

| Attribute | Value |
| --- | --- |
| Host | `gw.banyanproxies.com` |
| HTTP / HTTPS port | 7777 |
| SOCKS5 port | 7778 |
| Authentication | 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 |
| Rotation | Each 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 sessions | up to 30 minutes (the IP can change earlier) |
| Blocked | Banking, 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](https://banyanproxies.com/targeting/city/) and the [sticky sessions guide](https://banyanproxies.com/guides/sticky-sessions/) have more.

*curl over SOCKS5: a Wellington IP*

```bash
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*

```python
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*

```javascript
// 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*

```python
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 symptom | Likely cause | What to do |
| --- | --- | --- |
| 407 Proxy Authentication Required | Wrong username, password or segment syntax | Copy credentials again; check hyphens and underscores |
| Timeout on connect | Wrong port or a firewall | Use 7777 for HTTP, 7778 for SOCKS5 |
| Errors for one city only | Few home devices online there now | Retry later, use a nearby city, or drop the city segment |
| 403 or 429 from the target | The target refuses or rate-limits | Slow down; respect the site's terms and robots.txt |
| Connection refused to a bank or SMTP port | Blocked target | These targets are blocked by policy |

## Where is the rest of the documentation?

- **[API docs](https://banyanproxies.com/docs/api/)** — Account, top-ups, orders, usage and API keys over HTTPS.
- **[City targeting](https://banyanproxies.com/targeting/city/)** — Spelling rules and examples for every city.
- **[ASN targeting](https://banyanproxies.com/targeting/asn/)** — Network numbers of the main home ISPs.
- **[Getting started](https://banyanproxies.com/guides/getting-started/)** — From top-up to first request.

## Where do I go when something fails?

Check the [service status](https://banyanproxies.com/status/) first, then the [proxy city checker](https://banyanproxies.com/guides/verify-proxy-city/) for location doubts and the [glossary](https://banyanproxies.com/glossary/) for terms. Write to support from the [contact page](https://banyanproxies.com/contact/).

## 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.

---

Banyan Proxies: Banyan Proxies is a residential proxy provider for cities across South and Southeast Asia and Oceania, paid in crypto with no ID upload: home IPs targeted by city in Mumbai, Jakarta, Manila, Bangkok, Karachi, Sydney and more, billed per GB.