Developer FAQ

Quick, self-contained answers to the questions developers ask most when integrating ColdProxy: gateway and port setup, HTTP/HTTPS and SOCKS5, user:pass and IP authentication, geo-targeting, sticky versus rotating proxy sessions, the proxy API options, and how to test a proxy. For deeper walkthroughs, follow the links into the docs, the glossary, and the blog. Each answer below stands on its own.

#What is the gateway host format?

Connect through gw-{service-id}.coldproxy.com, where {service-id} is your service or package ID from the client area (examples use gw-2312.coldproxy.com). A full proxy string is gw-2312.coldproxy.com:PORT:USERNAME:PASSWORD, equivalently USERNAME:PASSWORD@gw-2312.coldproxy.com:PORT. A "Use Hostname instead of IP" toggle in the client area switches the gateway to a direct IP if you prefer connecting by IP.

curl -x "http://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000" https://api.vipv6proxy.com/api/checker/my-ip

#What port range do I use?

All ColdProxy traffic runs on ports 30000-34999, and the same range serves every protocol: HTTP, HTTPS, and SOCKS5. Use any port in that range (examples here use 30000). A connection refused on a port outside 30000-34999 is the most common port mistake. Plans allocate from 1 up to 5,000 unique ports.

#HTTP or SOCKS5 — which should I use?

ColdProxy supports HTTP, HTTPS (TCP), and SOCKS5 (TCP and UDP), and the protocol is auto-detected, so you do not need separate endpoints. Use HTTP/HTTPS for standard web requests. Use SOCKS5 when you need UDP or want the proxy to resolve DNS for you; specify socks5h where your client supports it so the target hostname is resolved remotely through the proxy. See SOCKS5 vs HTTPS proxies and TCP vs UDP proxies.

curl -x "socks5h://USERNAME:PASSWORD@gw-2312.coldproxy.com:30000" https://api.vipv6proxy.com/api/checker/my-ip

#User:pass or IP authentication?

Both, and you can run them at the same time. With user:pass you send HTTP Basic or SOCKS5 credentials on each request, which lets you encode geo and session tags in the username. With IP Authentication you whitelist up to 50 IPs and connect without credentials; proxies are then issued in IP:PORT form. IP-auth defaults geo to Worldwide unless you configure SuperPorts. See IP whitelisting vs username/password.

#How do I make a session sticky?

A sticky session needs both a session tag and a time tag in the username, together, for example user-key-myjob-session-1-time-10m. The session keeps the same exit IP for its time window while that IP works. If the exit IP stops working, the session's IP may change. A valid session or time tag on its own does not make a session: the proxy rotates per request. The session ID must be digits only, and the time must be a positive whole number with an optional s, m, h, or d unit. The proxy refuses an invalid value with 400 Bad Request (SOCKS5: reply 0x01); your login was accepted, so correct the tag. Sticky duration is 5s to 24h on the Residential IPv4 plans (a longer time is shortened to 24h) and 5s to FOREVER on both IPv6 plans; a time of 1s to 4s is raised to 5s. FOREVER is not a time value (-time-FOREVER is refused): it is the client area's -identifier- pin, available on the IPv6 plans only. The exact tag prefixes are set per product, so confirm them in your client area. Full troubleshooting in Sticky session not holding.

#How do I geo-target a country, state, or city?

Two paths. With user:pass, add geo tags to the username following the user-key-value-... grammar (geo-target plans support country, state, and city targeting where the plan exposes them). With IP-auth, configure SuperPorts to bind a country/state/city to a port range so requests through those ports inherit the location automatically. Confirm the exact tag prefixes for your product in the client area. See Geo-targeting with proxies and /glossary/#geo-targeting.

#How many ports and whitelisted IPs do I get?

Plans provision from 1 up to 5,000 unique ports (5,000 is the configurable ceiling, not a default). For IP authentication you can whitelist up to 50 IPs, managed through the Authorized IPs commands in your plan settings (add one, delete one, list, or replace the full list). Read your current IP to whitelist with My IP.

#How do I set up a rotating proxy?

Rotation is the default: without a session-plus-time pair, each request through a rotating proxy gets a fresh exit IP from the pool. To rotate deliberately, just omit the sticky tags. If you need the same IP across a sequence of requests, add both session and time tags. On Residential IPv6 and Datacenter IPv6, the identifier your client area generates keeps the same IP with no session to hold; see IP pinning on IPv6 plans. See rotating and sticky proxies explained.

#How do I test a proxy to confirm it works?

Use the free tools. The Proxy Checker reports IPv4/IPv6 reachability, the exit IP, and location for a single proxy. My IP shows your own IP for whitelisting and the exit IP through a proxy. Before buying an IPv6 plan, run your target through the IPv6 Checker: it should publish IPv6 addresses or be served by a supported CDN, and if you are unsure, test on the shortest paid billing window. For code-based checks, route an IP-echo request through the proxy; see Verify your proxy.

#Is there an API?

Yes, two. Each service has a self-service Customer Plan API (Plan Info, Usage, proxy lists in user:pass or IP:Port form, country/state/city and ISP lookups, Authorized IP management, password change, speed tier upgrades, reboot on the speed-tier plans, and renew). Separately, the B2B Reseller API at https://members.coldproxy.com/modules/addons/coldproxy_product_reseller/api/ provisions and manages services programmatically (TestConnection, TestCreate, Create, Suspend, Unsuspend, ChangePassword, Renew, and more). For broader patterns, see Proxy automation & API integration and Reseller program infrastructure.

#Why are my proxies not working right after I ordered?

Residential IPv4 (GB Based) and Residential IPv6 activate instantly after payment clears. Residential IPv4 (Unmetered) and Datacenter IPv6 start automatic setup after payment clears; allow up to 10 minutes and connect as soon as setup completes. A 407 or refused connection does not tell you whether setup is still running. Check your credentials, authentication mode, allocated port, and service status, then recheck with the Proxy Checker. See Activation and setup times for the support next step if the service is not ready.

#Is there a free trial?

Free trials may be available after individual review. Tell us what you want to test and the capacity you need through our contact channels; we assess each request and confirm availability and trial terms before providing access. Eligible plans also provide short paid validation windows so you can test on real traffic before committing. Residential IPv4 (Unmetered) and Residential IPv6 support hourly buying where available; Datacenter IPv6 starts at daily billing; and Residential IPv4 (GB Based) uses monthly traffic packs. Daily plans are non-refundable; weekly and monthly plans are refundable only for a verified technical issue on ColdProxy's side. Compare options on /pricing/.