You built an AI agent that browses the web. The moment it hits a real website, it gets blocked, CAPTCHA’d, or rate-limited. Your prompts are fine. Your logic is fine. The IP your requests come from is the problem.
This guide covers setting up SOCKS5 proxies for AI agents in Python, Node.js, and via MCP (Model Context Protocol). Your agent will route traffic through clean residential IPs and handle rotation, errors, and provisioning without you.
Step 1: Get Proxy Credentials Programmatically
Your agent should provision its own proxy access. If a human logs into a dashboard and copy-pastes credentials, the pipeline is not autonomous. ProxyBase exposes a headless API so your agent can do this itself:
# 1. Register your agent (no auth required)
curl -X POST https://api.proxybase.xyz/v1/agents
→ { "agent_id": "agt_abc123", "api_key": "pk_xyz789" }
# 2. List available proxy packages
curl -H "X-API-Key: pk_xyz789" https://api.proxybase.xyz/v1/packages
# 3. Create order and pay
curl -X POST https://api.proxybase.xyz/v1/orders \
-H "X-API-Key: pk_xyz789" \
-d {"package_id":"res_5gb","pay_currency":"usdcsol"}
# 4. Poll until proxy is provisioned
curl -H "X-API-Key: pk_xyz789" \
https://api.proxybase.xyz/v1/orders/ord_def456/status
Step 2: Python — httpx with SOCKS5
Python is the most common language for AI agent development. Here’s how to route an agent’s HTTP traffic through a SOCKS5 proxy using httpx:
# Install dependencies
pip install httpx[socks]
# agent_proxy.py
import httpx
import asyncio
PROXY_URL = "socks5://username:password@api.proxybase.xyz:1080"
TARGET_URL = "https://httpbin.org/ip"
async def fetch_via_proxy(url):
async with httpx.AsyncClient(proxy=PROXY_URL) as client:
try:
response = await client.get(url, timeout=30.0)
response.raise_for_status()
return response.json()
except httpx.HTTPStatusError as e:
if e.response.status_code == 403:
print("IP blocked — rotate and retry")
# Call POST /v1/orders/{order_id}/rotate here
raise
raise
asyncio.run(fetch_via_proxy(TARGET_URL))
Step 2 (Alternative): Python — requests with SOCKS5
If you prefer the synchronous requests library:
pip install requests[socks] pysocks
import requests
proxies = {
"http": "socks5://username:password@api.proxybase.xyz:1080",
"https": "socks5://username:password@api.proxybase.xyz:1080",
}
r = requests.get("https://httpbin.org/ip", proxies=proxies, timeout=30)
print(r.json())
# { "origin": "72.45.123.89" } ← residential IP, not your server
Step 3: Node.js — fetch with SOCKS5
npm install socks-proxy-agent
import { SocksProxyAgent } from "socks-proxy-agent";
const proxyUrl = "socks5://username:password@api.proxybase.xyz:1080";
const agent = new SocksProxyAgent(proxyUrl);
async function agentFetch(url) {
try {
const res = await fetch(url, { agent, signal: AbortSignal.timeout(30000) });
if (res.status === 403) {
console.error("IP blocked, rotate and retry");
// Call POST /v1/orders/{order_id}/rotate here
return null;
}
return res.json();
} catch (err) {
console.error("Request failed:", err.message);
return null;
}
}
Step 4: MCP — Let Your LLM Manage Proxies Natively
If your agent uses the Model Context Protocol (Claude, GPT, or any MCP-compatible LLM), ProxyBase ships an MCP server that lets the LLM manage proxies directly — no code required:
# claude_desktop_config.json or .mcp.json
{
"mcpServers": {
"proxybase": {
"command": "npx",
"args": ["-y", "@proxybasehq/mcp-server"]
}
}
}
# Your LLM can now call these tools directly:
# - register_agent: Create a new agent identity
# - list_packages: See available proxy packages and pricing
# - create_order: Purchase proxy bandwidth
# - check_order_status: Poll for proxy credentials
# - rotate_proxy: Swap to a fresh IP mid-task
# - topup_order: Add bandwidth when running low
Step 5: IP Rotation — Don’t Let a Burned IP Kill Your Agent
Every IP eventually gets rate-limited or blocked. Your agent needs to detect this and rotate automatically. Here’s the pattern:
MAX_RETRIES = 3
BLOCKED_STATUSES = {403, 429, 503}
BLOCKED_PATTERNS = ["captcha", "access denied", "unusual traffic"]
async def agent_request_with_rotation(url, order_id, api_key, retries=0):
response = await fetch_via_proxy(url)
# Check if blocked
is_blocked = (
response.status_code in BLOCKED_STATUSES or
any(p in response.text.lower() for p in BLOCKED_PATTERNS)
)
if is_blocked and retries < MAX_RETRIES:
print(f"IP blocked (attempt {retries + 1}), rotating...")
# Rotate to a fresh IP
await rotate_proxy(order_id, api_key)
await asyncio.sleep(1) # Brief cooldown
return await agent_request_with_rotation(url, order_id, api_key, retries + 1)
return response
Geo-Targeting: Route Through Specific Countries
Need your agent to appear from Japan, Germany, or Brazil? ProxyBase supports geo-targeting via SOCKS5 auth tags — you specify the country in your proxy credentials:
# US residential IP
socks5://jwt|country_US|type_residential@api.proxybase.xyz:1080
# German mobile (4G/5G) IP
socks5://jwt|country_DE|type_mobile@api.proxybase.xyz:1080
# Japan residential, auto-rotate on connection
socks5://jwt|country_JP|type_residential|rotate@api.proxybase.xyz:1080
The Full Stack: Putting It Together
A production AI agent needs the full loop: provision, connect, request, detect block, rotate, retry. Here’s the architecture:
- On startup, the agent registers via API, gets credentials, and checks its bandwidth.
- Per task, the agent requests a proxy from the pool with the right geo and carrier tags.
- Traffic routes through SOCKS5 with automatic retry on failure.
- On a 403 or CAPTCHA, the agent rotates its IP and retries with exponential backoff.
- When bandwidth runs low, the agent tops up via API. No human checks a dashboard.
If you build agents that browse the live web, proxy infrastructure is not optional. A demo works on localhost without it. A production system doesn’t. For more, see our guide on why AI agents need proxies and the full proxy for AI agents reference.
Proxy Infrastructure Built for AI Agents
Residential SOCKS5 proxies, headless API, MCP server included. No KYC, pay-as-you-go, credits never expire. Your agent provisions its own access in under 60 seconds.