HTTP Proxies¶

Sometimes the direct path doesn't work — corporate firewalls, IP-based rate limits, APIs that expect traffic from a specific network. Route your outbound requests through a proxy and pretend you're somewhere else.

The proxy option accepts a full URL with protocol, host, port, and optional credentials. Point it at your infrastructure and go.

How to use a proxy¶

await HTTP.get("https://api.example.com/data", {
  proxy: "http://proxy.example.com:8080"
})

Store credentials in ENV variables, not in script source:

await HTTP.get("https://api.example.com/data", {
  proxy: process.env.MY_PROXY_URL
})

Supported protocols¶

Any other protocol throws a validation error before the request is sent. No surprises mid-flight.

URL format¶

protocol://[username:password@]hostname[:port]

Examples¶

// HTTP — no auth
proxy: "http://proxy.example.com:8080"

// HTTP — with auth
proxy: "http://user:[email protected]:8080"

// HTTPS proxy
proxy: "https://secure-proxy.example.com:443"

// SOCKS5
proxy: "socks5://socks.example.com:1080"

// SOCKS5 with credentials
proxy: "socks5://myuser:[email protected]:1080"

// SOCKS4
proxy: "socks4://proxy.example.com:1080"

HTTP vs SOCKS — which to use?¶

For most bot integrations with REST APIs, http:// or https:// is enough. SOCKS is for when you need to get fancy.

Proxy vs cfProxy¶

Use proxy when you already have a proxy service. Use cfProxy when you want a free, self-hosted Cloudflare edge router.

When cfProxy is set, proxy is ignored — cfProxy handles routing instead.

Try it — copy-paste examples¶

Rotating through your own proxy pool¶

let proxies = process.env.PROXY_POOL.split(",")
let proxy = proxies[user.id % proxies.length]

await HTTP.get("https://api.example.com/data", { proxy })

POST through a corporate HTTP proxy¶

await HTTP.post("https://internal-api.company.com/report", {
  proxy: "http://corp-proxy.internal:3128",
  body: { bot_id: bot.id, event: "daily_stats" },
  headers: { "X-Internal-Key": process.env.INTERNAL_KEY }
})

SOCKS5 for APIs that check egress IP¶

await HTTP.get("https://partner-api.com/v1/status", {
  proxy: process.env.SOCKS5_PROXY,
  timeout: 15000
})

With other request options¶

Proxy works alongside every other HTTP option:

let res = await HTTP.post("https://api.example.com/submit", {
  proxy: process.env.PROXY_URL,
  body: { event: "signup", user_id: user.id },
  headers: { Authorization: "Bearer " + process.env.API_TOKEN },
  timeout: 10000,
  responseType: "json",
  success: "/onSubmitDone",
  error: "/onSubmitFailed"
})

Behaviour notes¶

• Proxy agents are cached internally for 5 minutes to improve performance on repeated requests to the same proxy
• When proxy is set, it takes priority over any platform default routing
• Proxy URLs are validated before the request fires — invalid format throws immediately
• Failed proxy connections return res.ok === false with connection details in res.error

Troubleshooting¶

See Limits & Timeouts for timeout and response size caps.