Connection and IP change

The first sections are about Residential. Fixed addresses connect differently: a separate section below.

Connection line

The response of POST /api/v1/packages/{id}/proxies carries host, port, username, password.

The login is a ready-made string: targeting and mode are encoded in it, you cannot build it yourself.

The port encodes the mode and protocol and cannot be changed.

residential.ipv.rent:10000:USERNAME:PASSWORD          # antidetect browsers, proxy managers
http://USERNAME:[email protected]:10000   # curl, requests, Node, Go
socks5://USERNAME:[email protected]:12000

curl -x 'http://USERNAME:[email protected]:10000' https://api.ipify.org

Modes and protocols

Mode	Behavior
rotating	a new address on every connection
sticky	the address is held for ttl_minutes: 3..1440, 60 by default

The port of each (mode, protocol) pair comes in connection_options of the package card:

Mode	HTTP	SOCKS5
rotating	9000	11000
sticky	10000	12000

Mail protocols (SMTP, IMAP, POP3) and UDP are not supported.

Targeting

{
  "count": 10,
  "geo": {
    "country": "us",
    "state": "california",
    "city": "los angeles"
  }
}

The values are codes from the geo catalog.

• The levels are optional: without geo - the global pool.
• state, city and asn require country.
• Below the country level, targeting is best effort: if the requested region, city or carrier has no free addresses, the exit is given from another location in the same country.

A value outside the catalog, an unknown key or narrowing without a country - 422 invalid_targeting with field and value.

IP change

In rotating mode the address changes by itself.

Every sticky line has its own rotation_url link: a GET on it releases the current address, and the next connection gets a different one. No authorization needed.

curl -s https://ipv.rent/r/9f3c1e...

HTTP	status	Meaning
200	ok	the address is released
200	not_in_use	no active session; the next connection gives a new address anyway
200	unconfirmed	the request was sent, no confirmation
404	not_found	the link is not valid
410	expired	the link’s resource has expired; does not happen for traffic packages
429	rate_limited	too often
503	error	the address could not be changed

Limits: 20 requests per minute per address, 120 per package, 300 per caller IP. A single link cannot be revoked - POST /api/v1/packages/{id}/rotation-secret invalidates all of them at once.

Fixed addresses

An IPv4 package is a ready list of addresses. There are no lines to build: everything is in the card GET /api/v1/packages/{id}.

What	Where to get it
addresses	addresses[].host
HTTP port	addresses[].port_http
SOCKS5 port	addresses[].port_socks
login and password	credentials - one for all addresses of the package

198.51.100.11:10010:USERNAME:PASSWORD             # antidetect browsers, proxy managers
http://USERNAME:[email protected]:10010      # curl, requests, Node, Go
socks5://USERNAME:[email protected]:10011

curl -x 'http://USERNAME:[email protected]:10010' https://api.ipify.org

• The exit address is the address from the list itself, it does not change for the whole term.
• UDP works over SOCKS5 - for games, calls and QUIC-based services.
• There is no targeting and no change-IP links: the country and location are chosen at purchase.
• New addresses can be obtained by replacement - of all addresses of the package at once, once every 30 days.
• Mail protocols (SMTP, IMAP, POP3) are not supported.

If it does not work

Symptom	Cause
authentication fails after building a set	the package password was reissued
stopped working for all workers at once	the volume is used up, check traffic.left_gb
the address is not from the requested geo	the requested location has no free addresses, another location in the same country was given; the geo catalog marks such countries pool: thin - go one level up
422 package_unavailable when building a set	the package is not issued yet (wait for status: active), ttl_minutes outside 3..1440, or the mode or protocol is not supported by the package
fixed addresses do not answer right after purchase	issuing the package takes up to 2 minutes
fixed addresses all stopped answering at once	the term has ended: status: expired, extend the package
authentication fails on fixed addresses	the password was reissued, or the package was extended after the term ended and a new password was issued - take credentials from the card
old fixed addresses do not work	the addresses were replaced: replacement.state: done, the new ones are in addresses