Username tag scheme

A ColdProxy proxy username encodes geo-targeting, session behavior, and (on the IPv6 plans) IP pinning, so a single static endpoint can serve thousands of distinct routing configurations with no per-request API calls. You build the username from hyphen-delimited key-value segments, pair it with your service password, and authenticate over HTTP Basic or SOCKS5 auth. This page is the reference for that proxy username format and grammar; for the dimension-by-dimension details see Geo-targeting and Sticky vs rotating sessions.

#The grammar

The username starts with your service's proxy username from the client area (the tag examples on this page use user as a sample username; the -identifier- example copies the client area's format and uses USERNAME), followed by key/value pairs joined by hyphens. The password is supplied separately by your auth layer:

user-key-value-key-value-...:PASSWORD

Four parsing rules to build against:

• Values must not contain hyphens. The gateway splits the whole username on hyphens and pairs the pieces, so a hyphen inside a value shifts every segment after it (for example city-new-york parses as city=new, and every segment after it is misread). Letters, digits, and underscores are safe: write city-newyork.
• Segment order does not matter. user-country-us-session-481516-time-10m and user-session-481516-time-10m-country-us are equivalent.
• Unknown keys are ignored. A misspelled key does not error; the segment is silently skipped, so double-check spelling when a tag seems to have no effect.
• Invalid session and time values are refused. Unlike an unknown key, a -session- or -time- tag with an invalid value is not skipped: the request fails with 400 Bad Request (SOCKS5: reply 0x01). See Session and time value rules.

The full proxy string ColdProxy issues looks like this:

gw-2312.coldproxy.com:PORT:USERNAME:PASSWORD

which is equivalent to the inline form:

USERNAME:PASSWORD@gw-2312.coldproxy.com:PORT

Here 2312 is your service/package ID, and PORT is any port in your plan's range 30000-34999. A plain authenticated request with no targeting tags looks like this:

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

#Tag reference

The segments below are the available dimensions. They fall into three groups: geo-targeting, proxy session control, and connection options.

#Session and time value rules

• session must be digits only, for example 481516. An empty value or one with any other character is refused.
• time must be a positive whole number, optionally followed by s, m, h, or d, for example 600, 600s, 10m, 1h, or 1d. A bare number means seconds, and units work in either case (10M equals 10m). An empty value, 0, a decimal such as 1.5h, another unit such as 10min, or FOREVER is refused.

With HTTP or HTTPS, a refused value gets 400 Bad Request; with SOCKS5, it gets reply 0x01 (general failure). Your login was accepted, so correct the tag, not your credentials. A valid time above your plan's maximum is not refused: it is shortened to the maximum. A time of 1 to 4 seconds is not refused either: it is raised to 5 seconds.

#Older usernames with -package-

Proxy lists generated earlier can carry one more segment, -package-, for example -package-ipv6dc. The gateway still accepts it, so those lists keep working; keep the segment exactly as issued. Proxy lists from the client area and the Customer Plan API no longer add it, because the gateway identifies your plan from your username and password.

#Worked examples

#Session control: US sticky IP for 10 minutes

Keep the same US exit IP for a 10-minute window by combining a -session- value with a -time- value. Both are required; see Sticky vs rotating sessions. The -session- value must be numeric (digits only); any other value is refused (see Session and time value rules).

# Username: user + country=us + session=481516 + time=10m
curl -x "http://user-country-us-session-481516-time-10m:PASSWORD@gw-2312.coldproxy.com:30000" \
  https://api.vipv6proxy.com/api/checker/my-ip

Every request reusing session-481516 within the 10-minute window resolves to the same US IP while that IP works; if the exit IP stops working, the session's IP may change. The window is fixed from the first request (activity does not extend it); when it ends, the next request with that session ID is assigned a new IP.

#City-targeted rotating IPs

Omit -session-/-time- to rotate (a fresh Chicago IP per request while staying in-city):

import requests

proxy = "http://user-country-us-city-chicago:PASSWORD@gw-2312.coldproxy.com:30000"
proxies = {"http": proxy, "https": proxy}

for _ in range(3):
    r = requests.get("https://api.vipv6proxy.com/api/checker/my-ip", proxies=proxies, timeout=30)
    print(r.json()["ip"], r.json().get("city"))
# Each iteration prints a different Chicago-area exit IP

#Deterministic IP pin with -identifier-

On Residential IPv6 and Datacenter IPv6, the -identifier- value your client area generates pins a consistent exit IP without holding any session state. The value works like the IP's ID, so the same identifier always maps to the same IP; copy it exactly as issued. This is distinct from -session-/-time- sticky; see Deterministic IP pinning. The Residential IPv4 plans do not support -identifier-, so hold an IP there with a sticky session of up to 24 hours.

The example uses a Datacenter IPv6 username in the format the client area generates, where USERNAME is your service username and the identifier value stays as issued. It checks the exit IP with the IPv6 echo endpoint, because both IPv6 plans exit over IPv6:

// Same identifier => same exit IP, across processes and restarts
import fetch from "node-fetch";
import { HttpsProxyAgent } from "https-proxy-agent";

const username = "USERNAME-identifier-mumcgy8tafa7dj0";
const agent = new HttpsProxyAgent(
  `http://${username}:PASSWORD@gw-2312.coldproxy.com:30000`
);

fetch("https://api6.vipv6proxy.com/api/checker/my-ip", { agent })
  .then((r) => r.json())
  .then((d) => console.log(d.ip));

#SOCKS5 and the username

The same username grammar applies to SOCKS5 connections. Use socks5h:// so DNS resolves through the proxy:

curl -x "socks5h://user-country-us-session-481516-time-10m:PASSWORD@gw-2312.coldproxy.com:30000" \
  https://api.vipv6proxy.com/api/checker/my-ip

#Related reading

• Geo-targeting — every geo dimension in depth
• Sticky vs rotating sessions — why sticky needs two tags
• Deterministic IP pinning — stateless IP pinning on the IPv6 plans
• Proxy authentication: IP whitelisting vs username/password
• Glossary: sticky session, geo-targeting, rotating proxy