Skip to main content

Static Proxy

1. Overview​

The Static IP V2 API provides full lifecycle management for static residential proxies: list resources, create proxies, renew, query inventory, and more.

2. List countries​

Method: GET /v2/static-residential/listCountry

Description: Returns supported country codes.

Request parameters​

None.

Response format​

FieldTypeDescription
dataArray<String>Country codes, e.g. ["US","UK","CA"]

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": ["US", "UK", "CA", "AU", "DE", "FR"]
}

3. List cities​

Method: GET /listCity

Description: Returns cities for a given country.

Request parameters​

NameTypeRequiredDescription
country_codeStringYesCountry code, e.g. US, UK

Response format​

FieldTypeDescription
dataArray<String>City names, e.g. ["New York","Los Angeles"]

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": ["New York", "Los Angeles", "Chicago", "Houston"]
}

4. List business types​

Method: GET /listBusiness

Description: Returns available business/use-case names.

Request parameters​

None.

Response format​

FieldTypeDescription
dataArray<Object>Business objects
data[].BusinessNameStringe.g. general, social_media, e_commerce, YouTube

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": [
    { "BusinessName": "YouTube" },
    { "BusinessName": "TikTok" },
    { "BusinessName": "other" }
  ]
}

5. Count available IPs​

Method: POST /countIdleIP

Description: Returns available IP count for the given filters.

Request parameters​

NameTypeRequiredDescriptionExample
country_codeStringYesCountry codeUS
city_nameStringNoCity; empty = randomNew York
businessStringYesFrom listBusinessgeneral
line_typeIntegerYesQuality: 1 basic, 2 standard, 3 premium1

Request example​

{
  "country_code": "US",
  "city_name": "New York",
  "business": "YouTube",
  "line_type": 1
}

Response format​

FieldTypeDescription
dataIntegerAvailable count

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": 1250
}

6. Create static proxy IPs​

Method: POST /newIP

Description: Create a new static proxy order.

Permission: Customer access control required.

Request parameters​

NameTypeRequiredDescriptionConstraintsExample
country_codeStringYesCountry code—US
city_nameStringNoCity; empty = random—New York
daysIntegerYesLease duration (days)1, 7, 15, 30, 60, 90, 36530
countIntegerYesQuantity1–50010
line_typeIntegerYesQuality: 1–31–31
is_udpIntegerNoUDP: 1 on, 0 off0–1, default 00
businessStringYesFrom listBusiness—general
customer_idIntegerNoOrder on behalf of user; null = self—null

Request example​

{
  "country_code": "US",
  "city_name": "New York",
  "days": 30,
  "count": 10,
  "line_type": 1,
  "is_udp": 0,
  "business": "YouTube",
  "customer_id": null
}

Response format​

FieldTypeDescription
dataObjectOrder result
data.order_idStringOrder ID
data.totalIntegerIPs created
data.amountDoubleOrder amount
data.currencyStringCurrency
data.created_atDateCreated at
data.expired_atDateExpires at
data.allotsArray<Object>Allocated proxies
data.allots[].ipStringExit IP
data.allots[].node_domainStringProxy host
data.allots[].node_portIntegerProxy port
data.allots[].accountStringUsername
data.allots[].passwordStringPassword

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_id": "20240521174348201395",
    "total": 2,
    "amount": 15.5,
    "currency": "USD",
    "created_at": "2024-12-19T10:30:00Z",
    "expired_at": "2025-01-18T10:30:00Z",
    "allots": [
      {
        "ip": "192.168.1.100",
        "node_domain": "proxy1.example.com",
        "node_port": 8080,
        "account": "user123",
        "password": "pass456"
      }
    ]
  }
}

7. Renew static proxy​

Method: POST /renewIP

Description: Renew an existing static proxy IP.

Permission: Customer access control required.

Request parameters​

NameTypeRequiredDescriptionConstraintsExample
ipStringYesIP to renew—192.168.1.100
daysIntegerYesRenewal days1, 7, 15, 30, 60, 90, 36530

Request example​

{
  "ip": "192.168.1.100",
  "days": 30
}

Response format​

Same structure as create order (data.order_id, data.allots, etc.).

Response example​

Success:

{
  "code": 200,
  "msg": "操作成功",
  "data": {
    "order_id": "20240521174348201395",
    "total": 1,
    "amount": 7.75,
    "currency": "USD",
    "created_at": "2024-12-19T10:30:00Z",
    "expired_at": "2025-02-18T10:30:00Z",
    "allots": [
      {
        "ip": "192.168.1.100",
        "node_domain": "proxy1.example.com",
        "node_port": 8080,
        "account": "user123",
        "password": "pass456"
      }
    ]
  }
}

8. List purchasable IP segments​

Method: POST /availableIpSegments

Description: Returns remaining purchasable quantity per IP segment for the authenticated user (no extra user fields in body).

Request parameters​

NameTypeRequiredDescriptionExample
country_codeStringYesCountry/region codeHK
city_nameStringNoCity; empty = randomHongKong
line_typeIntegerNoQuality 1–3; default 11

Request example​

{
  "country_code": "HK",
  "city_name": "HongKong",
  "line_type": 1
}

Response format​

FieldTypeDescription
dataObjectResult
data.total_quantityIntegerTotal available across segments
data.segmentsArray<Object>Per-segment inventory
data.segments[].ip_segmentStringCIDR, e.g. 62.72.182.0/24
data.segments[].quantityIntegerAvailable in segment

Response example​

Success:

{
  "code": "200",
  "message": "操作成功",
  "data": {
    "total_quantity": 506,
    "segments": [
      { "ip_segment": "62.72.182.0/24", "quantity": 253 },
      { "ip_segment": "178.94.169.0/24", "quantity": 253 }
    ]
  }
}

9. Batch purchase by IP segment​

Method: POST /batchPurchaseBySegment

Description: Purchase a total count across multiple segment prefixes in order until the count is met. Authenticated agent users only.

Permission: Customer access control (agent).

Request parameters​

NameTypeRequiredDescriptionExample
country_codeStringYesCountry/regionHK
city_nameStringNoCity; empty = randomHongKong
line_typeIntegerNoQuality 1–3; default 12
businessStringNoFrom listBusiness; default otherother
ip_segment_prefixesArray<String>YesPrefix list in allocation order["66.92.226","66.93.86"]
countIntegerYesTotal IPs to allocate20
daysIntegerYesLease days30
is_udpIntegerNoUDP 1/0; default 00

Request example​

{
  "country_code": "HK",
  "city_name": "HongKong",
  "line_type": 2,
  "business": "other",
  "ip_segment_prefixes": ["66.92.226", "66.93.86"],
  "count": 20,
  "days": 30,
  "is_udp": 0
}

Response format​

FieldTypeDescription
data.order_idStringOrder ID
data.totalIntegerAllocated count
data.expired_atStringISO 8601 expiry

Response example​

Success:

{
  "code": "200",
  "message": "操作成功",
  "data": {
    "order_id": "SO202401010001",
    "total": 20,
    "expired_at": "2024-01-31T12:00:00.000+00:00"
  }
}

10. List allocated IPs by order ID​

Method: GET /orderAllots

Description: Returns all IPs for an order (no pagination). Authenticated user’s orders only.

Permission: Customer access control required.

Request parameters​

NameTypeRequiredDescriptionExample
order_idStringYesQuery paramSO202401010001

Example: GET /orderAllots?order_id=SO202401010001

Response format​

data is an array of allocations:

FieldTypeDescription
ipStringExit IP
node_domainStringProxy host
node_portIntegerPort
accountStringUsername
passwordStringPassword
expired_atStringISO 8601 expiry

Response example​

Success:

{
  "code": "200",
  "message": "操作成功",
  "data": [
    {
      "ip": "178.93.111.1",
      "node_domain": "proxy.example.com",
      "node_port": 1080,
      "account": "user001",
      "password": "xxx",
      "expired_at": "2024-01-31T12:00:00.000+00:00"
    }
  ]
}

11. Debug / test​

Use the examples below or tools such as Postman.

List countries​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listCountry" \
     -H "Token: your_access_token_here"

List cities​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listCity?country_code=US" \
     -H "Token: your_access_token_here"

List business types​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/listBusiness" \
     -H "Token: your_access_token_here"

Count idle IPs​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/countIdleIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "US",
       "city_name": "New York",
       "business": "YouTube",
       "line_type": 1
     }'

Create static proxies​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/newIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "US",
       "city_name": "New York",
       "days": 30,
       "count": 1,
       "line_type": 1,
       "is_udp": 0,
       "business": "YouTube",
       "customer_id": null
     }'

Renew​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/renewIP" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "ip": "192.168.1.100",
       "days": 30
     }'

Available segments​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/availableIpSegments" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "HK",
       "city_name": "HongKong",
       "line_type": 1
     }'

Batch purchase by segment​

curl -X POST "http://user.ipweb.cc/prod-api/v2/static-residential/batchPurchaseBySegment" \
     -H "Token: your_access_token_here" \
     -H "Content-Type: application/json" \
     -d '{
       "country_code": "HK",
       "city_name": "HongKong",
       "line_type": 2,
       "business": "other",
       "ip_segment_prefixes": ["66.92.226", "66.93.86"],
       "count": 20,
       "days": 30,
       "is_udp": 0
     }'

Order allocations​

curl -X GET "http://user.ipweb.cc/prod-api/v2/static-residential/orderAllots?order_id=SO202401010001" \
     -H "Token: your_access_token_here"

Note: Replace your_access_token_here with your real token.

12. Error codes​

Static IP business errors​

CodeDescriptionResolution
2000Static IP not under this accountVerify IP ownership
2001Insufficient static IP inventoryTry another region or retry later
2002Static IP already in useChoose another IP
2003Static IP configuration failedCheck parameters and retry
2004Static IP renewal failedCheck balance and renewal parameters
2005Static IP expiredPurchase or renew
2006Static IP does not existIP released or invalid
2100Allowed days: 1, 7, 15, 30, 60, 90, 365Use an allowed days value
2101This IP only supports renewal: 30, 60, 90, 365Use supported renewal period

13. Error response examples​

Insufficient inventory​

{
  "code": 2001,
  "msg": "静态IP库存不足",
  "data": null
}

IP not found​

{
  "code": 2006,
  "msg": "静态IP不存在",
  "data": null
}

Invalid days​

{
  "code": 2100,
  "msg": "可选天数: 1、7、15、30、60、90、365天",
  "data": null
}

Renewal days restriction​

{
  "code": 2101,
  "msg": "当前IP仅支持: 30、60、90、365天",
  "data": null
}

© 2024 Static IP V2 API — v1.10.0

Last updated: February 25, 2026