Packages

Everything you buy becomes a package. A traffic package (family: traffic_gateway) is a volume of gigabytes from which connections are built. A fixed address package (family: dedicated) is N addresses for a term with one login and password. The routes on this page, except the last section, are shared by both kinds.

POST /api/v1/quote

Price quote. Charges nothing. Scope catalog:read. The body is the same as for the purchase.

curl -X POST https://ipv.rent/api/v1/quote \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{
      "product": "ipv4",
      "country": "us",
      "operator": "united-states",
      "period": "month",
      "quantity": 10
    }'

{
  "unit": "1.49",
  "unit_label": "per_ip",
  "quantity": 10,
  "discount": "0.00",
  "discount_percent": "0.00",
  "total": "14.90",
  "currency": "USD"
}

unit_label: per_gb for traffic, per_ip for fixed addresses.
total = unit * quantity - discount; discount is the discount in money, discount_percent the same discount in percent, both as strings.
The quoted amount is exactly what will be charged for a purchase with the same body.

POST /api/v1/packages

Purchase. Scope packages:write, the Idempotency-Key header is required. The purchase completes within the request: the 201 response carries order_id, package_id and status: completed.

Which fields are needed depends on the product:

Field	Residential	IPv4	Meaning
`product`	yes	yes	slug from the catalog
`volume`	yes	not allowed	whole gigabytes, integer or string
`country`	-	yes	country code from the options
`operator`	-	yes	location from the options
`period`	-	yes	`week`, `2_weeks`, `month`, `2_months`, `3_months` - from the country’s periods
`quantity`	not allowed	no, 1	how many addresses; all of them become one package
`plan`	-	no	plan; needed only if the country has several
`auto_renew`	-	no, `true`	renew the package automatically
`client_reference`	no	no	your label up to 64 characters; not unique

A field that does not belong to the product, and connection settings (count, geo, protocol, ttl_minutes and the like), are rejected by name: 422 unsupported_field with a field key.

curl -X POST https://ipv.rent/api/v1/packages \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Idempotency-Key: 550e8400-e29b-41d4-a716-446655440000' \
  -H 'Content-Type: application/json' \
  -d '{
      "product": "residential",
      "volume": 25,
      "client_reference": "deal-8891"
    }'

{
  "order_id": 128,
  "package_id": 42,
  "status": "completed",
  "price": "50.00",
  "client_reference": "deal-8891"
}

For fixed addresses the response has three more fields:

{
  "order_id": 131,
  "package_id": 57,
  "status": "completed",
  "price": "14.90",
  "client_reference": null,
  "package_ids": [57],
  "requested": 10,
  "fulfilled": 10
}

requested - how many addresses were ordered, fulfilled - how many were issued. If fewer were issued, the difference has already been returned to the balance.

Errors:

400 - invalid_body (no volume for traffic; no country, period or operator for addresses; body is not JSON), validation_failed, unknown_product
409 - idempotency_in_progress
422 - invalid_volume, invalid_quantity, country_unavailable, unknown_plan, unknown_operator, unknown_period, out_of_stock, type_unavailable, insufficient_balance, unsupported_field, purchase_refunded (money returned, retry as a new purchase), idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed (money untouched, a retry with the same key is safe), order_needs_attention (money charged, handled manually, do not retry), operation_indeterminate (a retry with the key of an operation whose outcome is undetermined)

GET /api/v1/packages

The key owner’s packages, newest first. Scope packages:read. Parameters: offset, limit (here 200 by default), family, product.

Parameter	Meaning
`family`	`traffic_gateway` or `dedicated`; an unknown value means no filter
`product`	slug: `residential`, `ipv4`; a slug you have no packages of gives an empty list

Card field	Meaning
`family`, `product`	kind and product of the package
`status`	`provisioning`, `active`; traffic also has `exhausted`, addresses have `expired`, `closed`, `suspended`
`name`	`tag` if set, otherwise built from the product: `residential · 25 GB`, `ipv4 · US · United States · x10`
`traffic`	traffic balance; `null` for addresses
`expires_at`	end of the term; `null` for traffic - traffic does not expire
`auto_renew`	for addresses: whether the package renews itself
`endpoint`	for addresses: `country`, `operator`, `addresses_count`; `null` for traffic

GET /api/v1/packages/{id}

The package and access to it. Scope packages:read.

Traffic package:

{
  "id": 42,
  "order_id": 128,
  "product": "residential",
  "family": "traffic_gateway",
  "tag": null,
  "name": "residential · 25 GB",
  "status": "active",
  "traffic": {
    "purchased_gb": "25.000",
    "used_gb": "2.566",
    "left_gb": "22.434",
    "synced_at": "..."
  },
  "expires_at": null,
  "created_at": "...",
  "endpoint": null,
  "credentials": {
    "username": "...",
    "password": "..."
  },
  "connection_options": [
    {
      "mode": "rotating",
      "protocol": "http",
      "host": "residential.ipv.rent",
      "port": 9000
    },
    {
      "mode": "rotating",
      "protocol": "socks5",
      "host": "residential.ipv.rent",
      "port": 11000
    },
    {
      "mode": "sticky",
      "protocol": "http",
      "host": "residential.ipv.rent",
      "port": 10000
    },
    {
      "mode": "sticky",
      "protocol": "socks5",
      "host": "residential.ipv.rent",
      "port": 12000
    }
  ],
  "limits": {
    "lifetime_min_minutes": 3,
    "lifetime_max_minutes": 1440,
    "lifetime_default_minutes": 60,
    "modes": ["rotating", "sticky"],
    "protocols": ["http", "socks5"]
  }
}

credentials, connection_options and limits are null together until the package is issued. Take ready connection lines from POST /api/v1/packages/{id}/proxies.

Fixed address package:

{
  "id": 57,
  "order_id": 131,
  "product": "ipv4",
  "family": "dedicated",
  "name": "ipv4 · US · United States · x2",
  "status": "active",
  "traffic": null,
  "expires_at": "2026-11-04T12:00:00+00:00",
  "created_at": "...",
  "auto_renew": true,
  "endpoint": {
    "country": "us",
    "operator": "United States",
    "addresses_count": 2,
    "...": "..."
  },
  "credentials": {
    "username": "...",
    "password": "..."
  },
  "addresses": [
    {
      "host": "198.51.100.11",
      "port_http": 10010,
      "port_socks": 10011
    },
    {
      "host": "198.51.100.12",
      "port_http": 10012,
      "port_socks": 10013
    }
  ],
  "capabilities": ["prolong", "credentials", "replace", "fingerprint", "renewal"],
  "credentials_retired": false,
  "extendable_until": "2026-12-11T12:00:00+00:00",
  "replace_available_at": null,
  "replacement": null,
  "renewal": {
    "enabled": true,
    "period": "month",
    "next_charge_at": "2026-11-03T12:00:00+00:00",
    "next_charge_amount": "2.98",
    "last_failure": null,
    "disabled_at": null
  },
  "fingerprint": {
    "profile": null,
    "profiles": [
      {
        "value": "windows_chrome",
        "label": "Windows 11 · Chrome"
      },
      "..."
    ]
  }
}

What each fixed address field means - on the Fixed addresses page.

Errors: 404 not_found.

POST /api/v1/packages/{id}/password

Password reissue, for both kinds. Scope packages:write. The login does not change.

The old password stops working immediately; applies_in_seconds is the upper bound on how long it takes for the new one to be accepted.

Errors: 404 not_found; 422 package_unavailable (the package is not issued yet), package_expired (the address term has ended - extend first); 500 package_failed.

Traffic package operations

The routes below are for Residential only. On a fixed address package they answer 422 unsupported_capability.

POST /api/v1/packages/{id}/proxies

Build connections. Scope packages:write, idempotency not needed. The body is optional.

Field	Type	Default	Meaning
`count`	integer 1..500	1	how many lines to build
`mode`	`rotating` \| `sticky`	`rotating`	session mode
`protocol`	`http` \| `socks5`	`http`	protocol
`ttl_minutes`	integer \| null	60	how long an address is held in `sticky`, 3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	codes from the geo catalog; `state`, `city`, `asn` require `country`

curl -X POST https://ipv.rent/api/v1/packages/42/proxies \
  -H 'Authorization: Bearer YOUR_API_KEY' -H 'Content-Type: application/json' \
  -d '{
      "count": 3,
      "mode": "sticky",
      "protocol": "http",
      "ttl_minutes": 30,
      "geo": {
        "country": "us"
      }
    }'

In sticky mode each line of the set carries its own session label, that is, it gives a separate exit address, and each has its own rotation_url.

In rotating mode the lines are identical: the address is chosen on every connection, so N lines give N different exits, and there are no change-IP links.

A missing field takes the default, not the value from the previous call. Lines issued earlier keep working.

Errors:

400 - invalid_body (field type or range)
404 - not_found
422 - invalid_targeting (with field and value: a value outside the catalog, an unknown geo key, narrowing without country), package_unavailable (the package is not issued yet, ttl_minutes outside limits, mode or protocol not supported), unsupported_capability

POST /api/v1/packages/{id}/topup

Add volume. Scope packages:write, Idempotency-Key is required. Body: {"volume": 10}.

The response is 202 and the package card: the new volume shows in the card immediately, traffic under the new limit starts passing in about two minutes.

A top-up creates a separate order with applied_to_package_id.

Errors:

400 - invalid_body
404 - not_found
409 - idempotency_in_progress
422 - invalid_volume, type_unavailable, insufficient_balance, package_unavailable, unsupported_capability, purchase_refunded, idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - package_failed (money not charged, a retry is appropriate), order_needs_attention (the charge went through, do not retry), operation_indeterminate (a retry with the key of an operation whose outcome is undetermined)

POST /api/v1/packages/{id}/rotation-secret

Reissue the secret of the change-IP links. Scope packages:write. Invalidates all /r/{token} links at once; a single one cannot be revoked. The response is the whole package.

Errors: 404 not_found; 422 unsupported_capability.