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 /v2/static-residential/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 /v2/static-residential/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 /v2/static-residential/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 /v2/static-residential/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 basic, 2 standard, 3 premium1–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"
      },
      {
        "ip": "192.168.1.101",
        "node_domain": "proxy2.example.com",
        "node_port": 8080,
        "account": "user124",
        "password": "pass457"
      }
    ]
  }
}

7. Renew static proxy​

Method: POST /v2/static-residential/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​

FieldTypeDescription
dataObjectRenewal result
data.order_idStringRenewal order ID
data.totalIntegerIPs renewed
data.amountDoubleRenewal amount
data.currencyStringCurrency
data.created_atDateRenewed at
data.expired_atDateNew expiry time
data.allotsArray<Object>Renewed proxies
data.allots[].ipStringRenewed 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": 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: Query remaining purchasable IP list by filters. Returns only each IP segment and its available quantity. User info is taken from authentication; no need to pass it in the request.

Request parameters​

NameTypeRequiredDescriptionConstraintsExample
country_codeStringYesCountry/region codee.g. HK, USHK
city_nameStringNoCity; empty = random—HongKong
line_typeIntegerNoQuality: 1 basic, 2 standard, 3 premium1–3, default 11

Request example​

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

Response format​

FieldTypeDescription
dataObjectQuery result
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: Specify multiple IP segment prefixes (e.g. 66.92.226, 66.93.86) plus a total count; allocate in segment order until the count is met. Authenticated user only. Returns order ID, allocated count, and expiry time.

Permission: Customer access control required (agent users).

Request parameters​

NameTypeRequiredDescriptionConstraintsExample
country_codeStringYesCountry/regione.g. HK, USHK
city_nameStringNoCity; empty = random—HongKong
line_typeIntegerNoQuality: 1 basic, 2 standard, 3 premium1–3, default 12
businessStringNoFrom listBusinessdefault otherother
ip_segment_prefixesArray<String>YesPrefix list in allocation order. e.g. ["66.92.226","66.93.86"] allocates from 66.92.226.x first, then 66.93.86.x if needed—["66.92.226","66.93.86"]
countIntegerYesTotal IPs to allocate from selected segments1–50020
daysIntegerYesLease days1, 7, 15, 30, 60, 90, 36530
is_udpIntegerNoUDP: 1 on, 0 off0–1, 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
dataObjectOrder info
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 allocated IPs for an order (no pagination). Authenticated user can only query their own orders. Does not return order ID; returns allocation list only.

Permission: Customer access control required.

Request parameters​

NameTypeRequiredDescriptionConstraintsExample
order_idStringYesOrder IDQuery paramSO202401010001

Example: GET /orderAllots?order_id=SO202401010001

Response format​

data is an array of all allocated IPs for the order.

FieldTypeDescription
dataArrayAllocation list (see fields below)
data[].ipStringExit IP
data[].node_domainStringProxy host
data[].node_portIntegerPort
data[].accountStringUsername
data[].passwordStringPassword
data[].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​

You can use the following examples to test the API:

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 static proxy​

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

List purchasable IP 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
     }'

List allocated IPs by order ID​

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. We recommend using Postman or another API testing tool.

12. Error codes​

The following error codes may be returned by static IP APIs:

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