Getting started
Everything speaks the standard HTTP proxy protocol, so any client you already use will work. Four steps to your first request.
Top up a balance
Pick a product on your billing page and buy the gigabytes you need. Each product keeps its own balance, and a request on an empty balance is refused with 403 AVO_QUOTA.
Point your client at the gateway
There is one endpoint for every product we sell, and they all use the same host. The product your proxy user belongs to sets what you are billed for and which targeting it accepts.
Host
gate.avocadoproxies.com
HTTP port
8080
SOCKS5 port
1080
Protocols
HTTP, HTTPS via CONNECT, SOCKS5
Proxy-Authorization header; nothing else about the setup changes, and socks5://USERNAME-cc-de:PASSWORD@gate.avocadoproxies.com:1080 is the whole configuration for most tools.socks5://, curl and Python’s requests resolve the destination name on your own machine and send us an address, so DNS answers follow your location instead of the exit’s. Use socks5h:// where the tool accepts it: the name then reaches the gateway unresolved, and the lookup happens from the exit. Some tools take the same choice as a setting called something like “resolve DNS through the proxy”.Create a proxy user
Open your dashboard and create a proxy user. You get a login and a password for that product. Create one per job or per teammate so you can disable a single proxy user without disturbing the rest. Each proxy user belongs to one product and draws from that product’s balance, so create one for every product you top up.
USERNAME and PASSWORD placeholders for exactly that reason.Send a request
Authenticate with standard Basic proxy authentication and add targeting keys to the username if you need them.
Authentication
The gateway uses Basic proxy authentication: your client sends the login and password in a Proxy-Authorization header, which every HTTP library builds for you when you put them in the proxy URL. Nothing else is required.
Proxy-Authorization: Basic base64("USERNAME-cc-de:PASSWORD")- A missing or malformed login returns
407 AVO_AUTHwith aProxy-Authenticate: Basicchallenge. - A disabled proxy user returns
403 AVO_DISABLED. - If you restricted a proxy user to specific addresses, requests from anywhere else return the same
407 AVO_AUTHas a wrong password, on purpose, so a leaked password cannot be tested against the allowlist. Your dashboard shows which addresses are permitted.
Your first request
Pick your language. Each example below routes one request through gate.avocadoproxies.com:8080 with German exit targeting; drop the -cc-de part and the gateway picks the exit country for you.
curl -x gate.avocadoproxies.com:8080 \
-U "USERNAME-cc-de:PASSWORD" \
https://example.comTargeting in one minute
Targeting is expressed in the username, appended after your login with single dashes. There are exactly five keys and each may appear once.
cc: country, two lowercase lettersst: state or region code, requiresccct: city, underscores instead of spaces, requiresstsid: sticky session id, 1 to 32 letters and digitsttl: session lifetime in minutes, requiressid
USERNAME rotating, country picked by the gateway
USERNAME-cc-de Germany
USERNAME-cc-us-st-ca-ct-los_angeles Los Angeles, California (Premium Residential only)
USERNAME-sid-a1b2c3-ttl-30 same address for 30 minutes
USERNAME-cc-de-sid-a1b2c3-ttl-30 Germany, held for 30 minutesThe full rules, including what each product supports, are on the targeting page.
Build a proxy string
The builder checks a username against the gateway’s parser and the limits of the product you pick, the ones listed under what each product supports. Whether the login exists, its IP allowlist and the remaining GB are checked when you connect.
Proxy string builder
Pick the product your proxy user belongs to, then fill in what you need. Empty fields are left out, which is how the gateway treats them, and anything the product does not offer is disabled. Leave the username and password blank to keep the USERNAME and PASSWORD placeholders in the strings below.
Country targeting · sessions up to 55 min
From your dashboard · 3–32 lowercase letters, digits or underscores
From your dashboard · checked when you connect, not here
Two letters
Not available on Residential
Not available on Residential
1 to 32 letters and digits
Minutes, 1 to 55. Needs a session
Host : port : username : password
gate.avocadoproxies.com:8080:USERNAME:PASSWORDURL form
http://USERNAME:PASSWORD@gate.avocadoproxies.com:8080Allowed destination ports
Tunnelled connections are permitted to the ports below. Anything else returns 403 AVO_PORT_NOT_ALLOWED.
On residential and mobile, use https:// destinations: a plain http:// request is answered with a redirect to the same address on https://, and a tunnel to port 80 is refused. Premium residential also carries plain http:// destinations.