套餐

你购买的一切都会成为套餐。流量套餐（family: traffic_gateway）是一定量的 GB 流量，连接由它生成。固定地址套餐（family: dedicated）是按期限租用的 N 个地址，共用一组登录名和密码。本页除最后一节外，所有路由对两类套餐通用。

POST /api/v1/quote

计算价格。不扣款。权限 catalog:read。请求体与购买相同。

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，固定地址为 per_ip。
total = unit * quantity - discount；discount - 折扣金额，discount_percent - 同一折扣的百分比，两者均为字符串。
计算出的金额就是用相同请求体购买时实际扣除的金额。

POST /api/v1/packages

购买。权限 packages:write，Idempotency-Key 请求头必填。购买在请求内完成： 201 响应包含 order_id、package_id 和 status: completed。

需要哪些字段取决于产品：

字段	Residential	IPv4	含义
`product`	是	是	目录中的 slug
`volume`	是	不允许	整数 GB，integer 或 string
`country`	-	是	参数中的国家代码
`operator`	-	是	参数中的位置
`period`	-	是	`week`, `2_weeks`, `month`, `2_months`, `3_months` - 取自该国家的周期
`quantity`	不允许	否，1	地址数量；它们将组成一个套餐
`plan`	-	否	资费方案；仅当该国家有多个方案时需要
`auto_renew`	-	否，`true`	自动续期套餐
`client_reference`	否	否	你的标记，最长 64 个字符；不要求唯一

与产品无关的字段以及连接设置（count、geo、protocol、 ttl_minutes 等）会按名称被拒绝：422 unsupported_field，附带 field 字段。

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"
}

固定地址的响应中还有三个字段：

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

requested - 订购的地址数量，fulfilled - 实际交付的数量。如果交付数量较少，差额已退回余额。

错误：

400 - invalid_body（流量缺少 volume；地址缺少 country、period 或 operator；请求体不是 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（资金已退回，请作为新购买重试）， idempotency_key_required, idempotency_key_invalid, idempotency_key_reused
500 - order_failed（资金未动，使用同一个键重试是安全的）， order_needs_attention（资金已扣除，正在人工处理，请勿重试）， operation_indeterminate（使用了一个结果未确定的操作的键重试）

GET /api/v1/packages

密钥所有者的套餐，最新的在前。权限 packages:read。参数：offset、limit（此处默认 200）、 family、product。

参数	含义
`family`	`traffic_gateway` 或 `dedicated`；未知值视为不筛选
`product`	slug：`residential`、`ipv4`；你没有的 slug 返回空列表

详情字段	含义
`family`, `product`	套餐的类型和产品
`status`	`provisioning`、`active`；流量另有 `exhausted`，地址另有 `expired`、`closed`、`suspended`
`name`	如果设置了 `tag` 则为 `tag`，否则由产品生成：`residential · 25 GB`、`ipv4 · US · United States · x10`
`traffic`	流量余额；地址为 `null`
`expires_at`	到期时间；流量为 `null` - 流量不过期
`auto_renew`	地址：套餐是否自动续期
`endpoint`	地址：`country`、`operator`、`addresses_count`；流量为 `null`

GET /api/v1/packages/{id}

套餐及其访问凭证。权限 packages:read。

流量套餐：

{
  "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 和 limits 同时为 null。现成的连接字符串请通过 POST /api/v1/packages/{id}/proxies 获取。

固定地址套餐：

{
  "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"
      },
      "..."
    ]
  }
}

固定地址各字段的含义见固定地址页面。

错误：404 not_found。

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

重新生成密码，两类套餐通用。权限 packages:write。登录名不变。

旧密码立即失效；applies_in_seconds - 新密码开始生效所需时间的上限。

错误：404 not_found；422 package_unavailable（套餐尚未交付）、package_expired（地址已到期 - 请先续期）；500 package_failed。

流量套餐操作

以下路由仅适用于 Residential。在固定地址套餐上它们返回 422 unsupported_capability。

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

生成连接。权限 packages:write，无需幂等键。请求体可选。

字段	类型	默认值	含义
`count`	integer 1..500	1	生成的字符串数量
`mode`	`rotating` \| `sticky`	`rotating`	会话模式
`protocol`	`http` \| `socks5`	`http`	协议
`ttl_minutes`	integer \| null	60	`sticky` 模式下地址保持的时长，3..1440
`geo.country`, `geo.state`, `geo.city`, `geo.asn`	string	-	地理目录中的代码；`state`、`city`、`asn` 需要 `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"
      }
    }'

在 sticky 模式下，每个字符串都带有自己的会话标签，即对应一个独立的出口地址，并且各自有自己的 rotation_url。

在 rotating 模式下各字符串相同：每次连接都会选择地址，因此 N 个字符串对应 N 个不同的出口，且没有换 IP 链接。

缺失的字段取默认值，而不是上一次调用的值。之前生成的字符串继续有效。

错误：

400 - invalid_body（字段类型或取值范围不对）
404 - not_found
422 - invalid_targeting（附带 field 和 value：值不在目录中、未知的 geo 键、未指定 country 就细分），package_unavailable（套餐尚未交付、ttl_minutes 超出 limits、模式或协议不受支持），unsupported_capability

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

加购流量。权限 packages:write，Idempotency-Key 必填。请求体：{"volume": 10}。

响应为 202 和套餐详情：新的流量在详情中立即可见，按新限额的流量大约两分钟后开始生效。

加购会创建一个带有 applied_to_package_id 的单独订单。

错误：

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（资金未扣除，可以重试），order_needs_attention （已扣款，不可重试），operation_indeterminate（使用了一个结果未确定的操作的键重试）

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

重新生成换 IP 链接的密钥。权限 packages:write。立即使所有 /r/{token} 链接失效；无法单独吊销某一个。响应为完整的套餐。

错误：404 not_found；422 unsupported_capability。