浏览端点

ProxyWing 开发者 API

住宅

按 GB 购买住宅流量，通过您自己的网关主机名提供服务，并获取用量报告。通过子用户转售在单独的章节中介绍。

GET /residential/products

列出住宅代理等级

返回可购买的住宅代理等级。住宅流量按 GB 销售；批量折扣会在结算时自动应用。

验证 · Bearer

请求 GET /residential/products

curl -X GET "https://api.proxywing.com/v1/residential/products" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tiers": [
    {
      "tier": "premium",
      "per_gb": 6
    },
    {
      "tier": "standard",
      "per_gb": 2.5
    }
  ]
}

POST /residential/orders

订购住宅流量

使用账户余额在所选套餐上购买住宅代理流量（以 GB 计）。这是一次性购买——没有计费周期或定期扣费；流量会保留在服务中直至用完。账单总额由计费系统计算——批量折扣会自动应用，因此较大的订单费用可能低于 gb × per_gb。支付后，服务立即开通并显示在 GET /residential/services 中。请提供 Idempotency-Key 请求头，这样重试绝不会重复扣费。响应中的 order_id 是后续所有针对该资源的调用所使用的 ID，且仅在订单开通后才可获知——订单仍处于 awaiting_payment 状态时，该值为 null。请先支付账单，然后重新读取余额结清订单的响应，或轮询相应的列表端点以获取该资源。此端点必须提供 Idempotency-Key——省略将返回 400，且不会产生任何扣费。

验证 · Bearer Idempotency-Key

请求体参数

tier string 必填

"premium" 或 "standard"，取自 GET /residential/products。
gb integer 必填

要购买的流量 GB 数（1–1000）。
promo_code string 可选

可选的优惠码。通过 API 仅可使用折扣低于 100% 的百分比折扣优惠码（会使总额归零的优惠码将被拒绝）。

请求 POST /residential/orders

curl -X POST "https://api.proxywing.com/v1/residential/orders" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"tier":"standard","gb":5}'

响应 200 · application/json

{
  "order_id": "resi_100001",
  "invoice_id": "inv_200004",
  "tier": "standard",
  "gb": 5,
  "status": "paid"
}

POST /residential/services/{svc_id}/top-up

为服务增加带宽

为现有住宅服务添加 GB 流量——无需新订单或新凭据，额外流量会计入同一服务。系统会为新增的 GB 创建一张账单（适用批量折扣，因此充值越多，每 GB 费用越低），如果余额足够，将自动支付，流量立即到账。如果余额不足，账单将保持未结状态（awaiting_payment），可在控制面板中结清。请提供 Idempotency-Key 请求头，这样重试绝不会重复购买。此端点必须提供 Idempotency-Key——省略将返回 400，且不会产生任何扣费。

验证 · Bearer Idempotency-Key

路径参数

svc_id string 必填

住宅服务 ID，例如 resi_100001，取自 GET /residential/services。

请求体参数

gb integer 必填

要添加的流量 GB 数（1–10000）。

请求 POST /residential/services/{svc_id}/top-up

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/top-up" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Idempotency-Key: b3f2a1c4-7e9d-4a2b-8c6f-1d5e9a0b3c7f" \
  -H "Content-Type: application/json" \
  -d '{"gb":5}'

响应 200 · application/json

{
  "service_id": "resi_100001",
  "gb_added": 5,
  "old_gb": 3,
  "new_gb": 8,
  "invoice_id": "inv_200020",
  "total": 11.25,
  "status": "paid"
}

GET /residential/services

列出住宅服务

返回账户中所有有效的住宅服务，以及其等级和所连接的网关主机名。

验证 · Bearer

请求 GET /residential/services

curl -X GET "https://api.proxywing.com/v1/residential/services" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "services": [
    {
      "id": "resi_100001",
      "tier": "standard",
      "status": "active",
      "gateway": "quality.proxywing.com"
    },
    {
      "id": "resi_100002",
      "tier": "premium",
      "status": "active",
      "gateway": "premium.proxywing.com"
    }
  ]
}

GET /residential/services/{svc_id}/credentials

获取连接凭据

返回住宅服务的网关、可用端口以及用户名/密码。在您手动构建代理字符串时，targeting_field 会告诉您哪个凭据承载地理定位和会话令牌——如需自动构建，请使用 POST /residential/services/{svc_id}/generate-proxy-list。

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001，可从 GET /residential/services 获取。

请求 GET /residential/services/{svc_id}/credentials

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/credentials" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "id": "resi_100001",
  "tier": "standard",
  "gateway": "quality.proxywing.com",
  "http_ports": [
    8888,
    7000,
    7001,
    7002,
    7003,
    7004,
    7005
  ],
  "socks5_ports": [
    1080,
    6000,
    6001,
    6002,
    6003,
    6004,
    6005
  ],
  "username": "pkg-private2",
  "password": "sample_password",
  "targeting_field": "username"
}

GET /residential/services/{svc_id}/traffic

获取流量用量

返回住宅服务的流量余额，单位为 GB。某一等级未跟踪的字段为 null。

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001。

请求 GET /residential/services/{svc_id}/traffic

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/traffic" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "standard",
  "total_gb": 20,
  "used_gb": 1.21,
  "available_gb": 18.79
}

GET /residential/services/{svc_id}/usage-report

获取用量报告

返回住宅服务在某一日期范围内按主机名统计的流量用量。数值采用请求的 unit 单位；total 为所有行的合计。

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001。

查询参数

date_from string 必填

开始日期，YYYY-MM-DD。
date_to string 必填

结束日期，YYYY-MM-DD。
unit string 可选

数据值的计量单位："B"、"KB"、"MB" 或 "GB"（默认 GB）。

请求 GET /residential/services/{svc_id}/usage-report

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/usage-report" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "standard",
  "date_from": "2026-06-01",
  "date_to": "2026-07-01",
  "unit": "GB",
  "total": 3.42,
  "rows": [
    {
      "date": "2026-06-15",
      "hostname": "example.com",
      "data": 2.1,
      "requests": 1840
    },
    {
      "date": "2026-06-16",
      "hostname": "api.example.com",
      "data": 1.32,
      "requests": 910
    }
  ]
}

GET /residential/access

列出国家和城市

根据您的需要，有两种调用方式。国家：只发送 tier——GET /residential/access?tier=premium。城市：添加 country——GET /residential/access?tier=premium&country=US。每个条目都包含一个 code 和一个用于显示的 name，要传入的是 `code`，即作为 generate-proxy-list 的 city / country（应为 losangeles，而不是 "Los angeles"）。不同等级的覆盖范围差异很大，因此请查询您实际销售的等级：losangeles 和 sanfrancisco 在高级版中存在，但在标准版中不存在；高级版覆盖 2030 个美国城市，而标准版为 534 个。列表中没有的城市会生成网关拒绝的凭据，因此请在此处解析名称，而不要猜测。ASN 没有列表端点——您需要自行提供 AS 号（例如 Comcast 为 7922）；请参阅 generate-proxy-list 的 isp 参数。

验证 · Bearer

查询参数

tier string 必填

"premium" 或 "standard"。
country string 可选

ISO 国家代码，例如 US。设置后，返回该国家的城市，而不是国家列表。输入不区分大小写；响应中的 `code` 值为小写。

请求 GET /residential/access

curl -X GET "https://api.proxywing.com/v1/residential/access" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "premium",
  "countries": [
    {
      "code": "us",
      "name": "United States"
    },
    {
      "code": "gb",
      "name": "United Kingdom"
    },
    {
      "code": "de",
      "name": "Germany"
    }
  ]
}

GET /residential/services/{svc_id}/access

列出某项服务的国家和城市

与 GET /residential/access 相同的地理目录，但限定于您的某项服务，因此您无需知道或发送其等级。不带参数发送可获取所有可用国家；添加 country 可获取该国家的城市——下方示例展示的是城市形式。code 值为小写，即作为 generate-proxy-list 的 city / country 传入的值。具有读取范围权限的密钥即可满足要求。

验证 · Bearer

路径参数

svc_id string 必填

住宅服务 ID，可从 GET /residential/services 获取。

查询参数

country string 可选

ISO 国家代码，例如 US。设置后，返回该国家的城市，而不是国家列表。

请求 GET /residential/services/{svc_id}/access

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/access" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "standard",
  "country": "US",
  "cities": [
    {
      "code": "chicago",
      "name": "Chicago"
    },
    {
      "code": "dallas",
      "name": "Dallas"
    }
  ]
}

GET /residential/services/{svc_id}/auto-topup

获取自动充值设置

返回住宅服务的自动充值配置。启用后，一旦剩余余额低于阈值，账户将自动购买更多流量。

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001。

请求 GET /residential/services/{svc_id}/auto-topup

curl -X GET "https://api.proxywing.com/v1/residential/services/{svc_id}/auto-topup" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "service_id": "resi_100001",
  "enabled": true,
  "threshold_gb": 2,
  "amount_gb": 5,
  "payment_source": "balance",
  "last_topup_at": null
}

PUT /residential/services/{svc_id}/auto-topup

设置自动充值

为住宅服务启用或停用自动充值。启用时，threshold_gb 和 amount_gb 均为必填项，充值费用从账户余额中支付。（使用银行卡支付的自动充值需在控制面板中配置。）

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001。

请求体参数

enabled boolean 必填

true 表示启用自动充值，false 表示停用。
threshold_gb number 可选

当剩余流量低于此 GB 数时充值（1–10000）。启用时必填。
amount_gb number 可选

每次购买的 GB 数（1–10000）。启用时必填。

请求 PUT /residential/services/{svc_id}/auto-topup

curl -X PUT "https://api.proxywing.com/v1/residential/services/{svc_id}/auto-topup" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"enabled":true,"threshold_gb":2,"amount_gb":5}'

响应 200 · application/json

{
  "service_id": "resi_100001",
  "enabled": true,
  "threshold_gb": 2,
  "amount_gb": 5,
  "payment_source": "balance",
  "last_topup_at": null
}

POST /residential/services/{svc_id}/generate-proxy-list

生成代理列表

按您指定的地理定位和会话行为，为住宅服务生成即用型代理字符串。轮换会话在每次请求时获得新的出口 IP；粘性会话在会话生存时间（TTL）内保持同一出口 IP。此端点仅格式化凭据——绝不会从账户扣费。

验证 · Bearer

路径参数

svc_id string 必填

服务 ID，例如 resi_100001。

请求体参数

count integer 可选

要生成的代理字符串数量，1–1000。默认 10。
protocol string 可选

"http"（默认）、"socks5" 或 "mix"。"mix" 仅限标准版套餐——同一端口同时响应 HTTP 和 SOCKS5；在高级版上请求该值将返回 400。
format string 可选

输出格式。可选值之一："hostname:port:username:password"（默认）、"hostname:port@username:password"、"username:password@hostname:port"、"username:password:hostname:port"。
port integer 可选

要使用的特定网关端口。必须是该协议已公布的端口之一——高级版接受 102 HTTP 和 102 SOCKS5 端口，标准版接受 111 HTTP、112 SOCKS5，以及用于 "mix" 的 5555。默认根据 `session` 使用该套餐的轮换端口或粘性端口（"mix" 为 5555）。
country string 可选

要定位的 ISO 国家代码，例如 "US"，或使用 "US,GB" 组成多国家池。省略则随机选择。
city string 可选

要定位的城市。要求恰好指定一个 `country`——若使用逗号分隔的多国家值，城市将被忽略。两种套餐均可用；可通过 `GET /residential/services/{svc_id}/access?country=US` 查询有效名称（高级版覆盖的城市远多于标准版）。空格会被移除，因此 "Los angeles" 将以 `LosAngeles` 发送。
isp string 可选

要定位的 ASN，例如 Comcast 为 `7922`。与 `city` 一样，要求恰好指定一个 `country`，并可与其组合以同时锁定两者（芝加哥的 Comcast）。高级版接受 AS 号或提供商名称；标准版需要 AS 号。没有 ASN 查询端点——请自行提供 AS 号。
session string 可选

"rotating"（默认）或 "sticky"。
session_ttl string 可选

粘性会话保持同一出口 IP 的时长，例如 "30s"、"10m"、"2h"、"1d"。
ipv4 boolean 可选

仅限标准版套餐：限定使用仅 IPv4 的 IP 池。默认 true。
streaming boolean 可选

仅限高级版套餐：使用高端流媒体 IP 池。默认 false。
direct boolean 可选

仅限高级版套餐：直连模式，适用于 IMAP 等不适合默认路径的协议。默认 false。
skip_static_isp boolean 可选

仅限高级版套餐：跳过静态 ISP 出口。默认 false。
host string 可选

输出原始入口 IP，而非 DNS 网关主机名。必须是该套餐已公布的入口 IP 之一，或该套餐的网关名称；其他任何值都将返回 400。除非确有需要，否则请勿设置——网关主机名按地理位置路由，固定 IP 会使使用该字符串的所有用户都被发送到同一区域。可用 IP 由子用户凭据端点以 `entry_ips` 返回。

请求 POST /residential/services/{svc_id}/generate-proxy-list

curl -X POST "https://api.proxywing.com/v1/residential/services/{svc_id}/generate-proxy-list" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"count":2,"protocol":"http","country":"US","session":"sticky","session_ttl":"10m"}'

响应 200 · application/json

{
  "gateway": "quality.proxywing.com",
  "port": 8888,
  "protocol": "http",
  "count": 2,
  "proxies": [
    "quality.proxywing.com:8888:pkg-private2-pool-onlyipv4-country-US-session-a1b2c3d4-ttl-10:sample_password",
    "quality.proxywing.com:8888:pkg-private2-pool-onlyipv4-country-US-session-e5f6g7h8-ttl-10:sample_password"
  ]
}

GET /residential/gateways

列出您的网关主机名

您的白标网关主机名，每个等级一个，并附带其实时 DNS 状态。如果未配置任何主机名，则使用平台默认值，一切行为与之前完全相同。

验证 · Bearer

请求 GET /residential/gateways

curl -X GET "https://api.proxywing.com/v1/residential/gateways" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "gateways": [
    {
      "tier": "premium",
      "hostname": "gw.yourdomain.com",
      "status": "active",
      "in_use": true,
      "resolves_to": [
        "149.51.212.54"
      ],
      "expected_ips": [
        "149.51.212.54"
      ],
      "last_checked_at": "2026-07-26T08:17:01Z",
      "error": null
    }
  ],
  "defaults": {
    "premium": "premium.proxywing.com",
    "standard": "quality.proxywing.com"
  }
}

GET /residential/gateways/{tier}/target

获取要发布的 DNS 记录

返回为您自己的主机名创建所需的确切 DNS 记录。请使用 CNAME，而不是 A 记录：网关采用地理路由，会根据请求的来源返回不同的地址，因此您的每个客户都能连接到就近的入口点。固定的 A 记录会把所有客户锁定到单一区域，并且一旦这些地址变更就会失效。

验证 · Bearer

路径参数

tier string 必填

premium 或 standard 之一。

请求 GET /residential/gateways/{tier}/target

curl -X GET "https://api.proxywing.com/v1/residential/gateways/{tier}/target" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "premium",
  "record_type": "CNAME",
  "target": "premium.proxywing.com",
  "ttl_hint": 300,
  "example": "gw.yourdomain.com.  IN  CNAME  premium.proxywing.com."
}

PUT /residential/gateways/{tier}

设置网关主机名

将某一套餐指向您自有域名下的主机名，使您交给客户的凭据和代理字符串显示您的品牌，而非我们的品牌。我们会立即检查 DNS：status 为 active 表示已生效，此后所有凭据和代理列表响应都将返回您的主机名；pending 表示记录尚不正确，error 字段会说明原因——在记录正确之前，我们会继续提供默认网关，因此错误配置的记录绝不会让您的客户拿到失效的代理。各套餐相互独立。如果其他账户已占用该主机名，将返回 409 hostname_unavailable。

验证 · Bearer

路径参数

tier string 必填

premium 或 standard 之一。

请求体参数

hostname string 必填

您所控制的域名下的主机名，例如 gw.yourdomain.com。

请求 PUT /residential/gateways/{tier}

curl -X PUT "https://api.proxywing.com/v1/residential/gateways/{tier}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX" \
  -H "Content-Type: application/json" \
  -d '{"hostname":"gw.yourdomain.com"}'

响应 200 · application/json

{
  "tier": "premium",
  "hostname": "gw.yourdomain.com",
  "status": "active",
  "in_use": true,
  "resolves_to": [
    "149.51.212.54"
  ],
  "expected_ips": [
    "149.51.212.54"
  ],
  "last_checked_at": "2026-07-26T08:17:01Z",
  "error": null
}

POST /residential/gateways/{tier}/verify

重新检查网关 DNS

立即重新检查此等级的 DNS，而无需等待后台巡检。请在更正记录后使用。我们也会自行持续重新验证：如果一个原本正常的主机名不再解析到我们的网关，我们会将其标记为 drifted，新生成的字符串将回退到默认网关，待记录恢复正确后再自动恢复该主机名。

验证 · Bearer

路径参数

tier string 必填

premium 或 standard 之一。

请求 POST /residential/gateways/{tier}/verify

curl -X POST "https://api.proxywing.com/v1/residential/gateways/{tier}/verify" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "premium",
  "hostname": "gw.yourdomain.com",
  "status": "active",
  "in_use": true,
  "resolves_to": [
    "149.51.212.54"
  ],
  "expected_ips": [
    "149.51.212.54"
  ],
  "last_checked_at": "2026-07-26T08:29:12Z",
  "error": null
}

DELETE /residential/gateways/{tier}

移除您的网关主机名

将此等级恢复为平台默认网关。只要您的 DNS 记录保持不变，您已在自己的主机名上签发的代理字符串就会继续有效。

验证 · Bearer

路径参数

tier string 必填

premium 或 standard 之一。

请求 DELETE /residential/gateways/{tier}

curl -X DELETE "https://api.proxywing.com/v1/residential/gateways/{tier}" \
  -H "Authorization: Bearer pk_live_XXXXXXXX"

响应 200 · application/json

{
  "tier": "premium",
  "hostname": null,
  "serving": "premium.proxywing.com"
}