Two proxy frontends, both authenticated with the same SOCKS5-style username + password from the Tunnel credentials tab.

The username embeds your account ID, a sticky session ID, the country you want to egress through, and (optionally) the streaming service. Same session = same residential exit IP. The binding lasts until you explicitly rotate or discard it — there is no fixed expiry while traffic keeps flowing (see § 6 for the exact lifetime rules).

vela-{customer_id}-session-{session_id}-country-{cc}[-service-{svc}]

# Examples
vela-u_abc123-session-s_0001-country-uk
vela-u_abc123-session-s_0001-country-uk-service-bbc
vela-u_abc123-session-s_0001-country-it-service-netflix

Drop-in usage. Replace USER / PASS with the values from the Tunnel credentials tab.

# curl via SOCKS5
curl --proxy "socks5h://USER:PASS@gateway.vela.watch:1080" https://www.bbc.co.uk/iplayer

# Python (requests)
import requests
proxies = { "https": "socks5h://USER:PASS@gateway.vela.watch:1080" }
r = requests.get("https://www.bbc.co.uk/iplayer", proxies=proxies, timeout=30)

# Firefox / Chrome → Network settings → Manual proxy → SOCKS v5
# Host: gateway.vela.watch   Port: 1080   Auth: USER / PASS

Only branded streaming hostnames pass the gateway policy. Everything else is rejected (and not billed). Request additions from support.

REST API at the same origin as this dashboard. All endpoints are authenticated with your JWT or HTTP Basic + API key.

The session token in the SOCKS5 username is a stable opaque string you control. Pick one per logical "user" or "scrape job" and reuse it for as long as you want the same exit IP. The gateway pins (customer, session, country, service) → one residential node and keeps that binding alive under the following rules:

What this means in practice: there is no hidden 30-minute or 1-hour expiry. The gateway will keep sending you out the same residential IP indefinitely as long as you keep using the same session and the upstream stays healthy. The only ways the IP changes are: (1) you call rotate/discard, (2) the node disappears server-side, or (3) you stop sending traffic for more than 7 days. Rotating IPs has a cost — destinations see a new TLS + cookie handshake and many treat that as a re-login, so don't rotate inside an active video stream.

Each request you send through the gateway is mapped to one residential exit IP by the following deterministic pipeline. Understanding this is the difference between a working scraper and a banned account.

┌─ STEP 1 ─ Username parse ──────────────────────────────────────┐
│ The gateway splits your username on the wire:                  │
│   vela-{customer}-session-{session}-country-{cc}-service-{svc} │
│   ↑           ↑                ↑              ↑                │
│   identity    stickiness key   pool filter    optional filter  │
└────────────────────────────────────────────────────────────────┘

┌─ STEP 2 ─ Sticky lookup (Redis) ───────────────────────────────┐
│ Key:   sticky:{customer}:{session}:{country}:{service}         │
│ If hit → reuse the SAME upstream IP from last time.            │
│ Idle TTL refreshes on every flow (rolling, default 7 days).    │
│ Active traffic = effectively no expiry.                        │
└────────────────────────────────────────────────────────────────┘

┌─ STEP 3 ─ Pool selection (cache miss only) ────────────────────┐
│ Filter the residential pool down to nodes where:               │
│   node.country == requested country, AND                       │
│   node.healthy == true, AND                                    │
│   (no -service- given OR node.capabilities contains it)        │
│ Hash-pick deterministically: hash(customer+session) % len(pool)│
│ → Same session always lands on the same node while it exists.  │
└────────────────────────────────────────────────────────────────┘

┌─ STEP 4 ─ Persist + dial ──────────────────────────────────────┐
│ Write the choice back to Redis with sticky TTL.                │
│ Dial the destination through that node (SOCKS5 or HTTP CONNECT)│
│ Tunnel the bytes, meter both directions, decrement wallet.     │
└────────────────────────────────────────────────────────────────┘

Choosing the right pattern

Important: rotating IPs has a cost. A new sticky session triggers a fresh TLS + cookie handshake at the destination, and many streaming services interpret it as a suspicious re-login. Don't rotate inside a video stream — only between scrape jobs.

Three endpoints let you take direct control of which residential exit your session lands on. Pool-wide listing is never exposed — you only ever see the IPs you've actually been routed through.

What you see vs what stays hidden

# list current assignments
curl -H "Authorization: Bearer $JWT" https://vela.watch/v1/b2b/proxy/assigned

# rotate (same session keeps working, lands on a new IP)
curl -X POST -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"session":"scrape-001","country":"UK"}' \
  https://vela.watch/v1/b2b/proxy/rotate

# discard the bad IP, blacklist it for this account
curl -X POST -H "Authorization: Bearer $JWT" -H "Content-Type: application/json" \
  -d '{"session":"scrape-001","country":"UK"}' \
  https://vela.watch/v1/b2b/proxy/discard

Lifetime, exactly: the binding has no fixed expiry. It survives every TCP connect/disconnect cycle of your SOCKS5 client and every minute of active traffic. The only timer is a 7-day idle TTL — i.e. if you send no traffic at all for 7 consecutive days the binding rolls off. Active traffic resets that timer on every flow. So in practice: you keep the same IP until you call /rotate, /discard, or stop using the session entirely. Override the default 7-day idle ceiling at the deployment level with STICKY_TTL_SECONDS.

Our policy filter inspects the destination hostname, not the post-DNS IP. SOCKS5 supports two address types: ATYP=1 (IPv4) and ATYP=3 (domain). Pick the right one or every request gets denied even with valid credentials.

Why we enforce ATYP=3: a hostname is the only thing we can match against the streaming allowlist without trusting the client's DNS. If we accepted ATYP=1 we'd have to do a reverse-DNS or re-resolution — both lossy, both spoofable. Sending the hostname through the proxy also means DNS itself egresses through the upstream node, not your machine — important if you don't want your home ISP seeing every streaming query.

# Correct
curl --socks5-hostname USER:PASS@gateway.vela.watch:1080 https://www.netflix.com/
curl --proxy socks5h://USER:PASS@gateway.vela.watch:1080 https://www.bbc.co.uk/iplayer

# Wrong — denied
curl --socks5 USER:PASS@gateway.vela.watch:1080 https://www.netflix.com/
curl --proxy socks5://USER:PASS@gateway.vela.watch:1080 https://www.bbc.co.uk/iplayer