Skip to main content

Static Proxy

1. Overview​

The Static IP V2 API provides full management for static residential proxy IPs, including querying available resources, creating proxies, renewals, enabling/disabling auto-renewal, and paginated listing of the current user's active IPs.

2. List countries​

Method: GET /v2/static-residential/listCountry

Description: Returns the list of supported country codes.

Request parameters​

None

Response fields​

FieldTypeDescription
dataArray<String>Country code array, 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 supported cities for a given country code.

Request parameters​

ParameterTypeRequiredDescription
country_codeStringYesCountry code, e.g. US, UK

Response fields​

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

Response example​

Success:

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

4. List business names​

Method: GET /v2/static-residential/listBusiness

Description: Returns the list of available business names.

Request parameters​

None

Response fields​

FieldTypeDescription
dataArray<Object>Business name object array
data[].BusinessNameStringBusiness name, e.g. general, social_media, e_commerce

Response example​

Success:

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

5. Count idle IPs​

Method: POST /v2/static-residential/countIdleIP

Description: Returns the number of available IPs for the given filters.

Request parameters​

ParameterTypeRequiredDescriptionExample
country_codeStringYesCountry codeUS
city_nameStringNoCity name; empty means randomNew York
businessStringYesBusiness name from listBusinessgeneral
line_typeIntegerYesIP quality: 1 basic, 2 standard, 3 premium1
sell_modeIntegerNoSell mode: 1 dedicated, 2 shared; omit to use platform default2

Request example​

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

Response fields​

FieldTypeDescription
dataIntegerAvailable IP count

Response example​

Success:

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

6. Create static proxy IP​

Method: POST /v2/static-residential/newIP

Description: Creates a new static proxy IP order.

Permission: Customer access control required

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
country_codeStringYesCountry code-US
city_nameStringNoCity name; empty means random-New York
daysIntegerYesPurchase duration in daysAllowed: 30, 60, 90, 180, 36530
countIntegerYesNumber of proxies to purchase1–50010
line_typeIntegerYesIP quality: 1 basic, 2 standard, 3 premium1–31
is_udpIntegerNoUDP: 1 enabled, 0 disabled0–1, default 00
sell_modeIntegerNoSell mode: 1 dedicated, 2 shared; omit to use platform default1–22
businessStringYesBusiness type from listBusiness-general
customer_idStringNoTarget user ID (snowflake ID; prefer JSON string); null means yourself-null
auto_renewIntegerNoEnable auto-renew for delivered IPs of this order: 1 yes, 0/omit no; triggers 1 day before expiry, period equals purchase days0–11

Request example​

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

Response fields​

FieldTypeDescription
dataObjectCreate result object
data.order_idStringOrder ID
data.totalIntegerNumber of IPs created
data.amountDoubleOrder amount
data.currencyStringBilling currency
data.created_atStringCreated at (yyyy-MM-dd HH:mm:ss)
data.expired_atStringExpires at (yyyy-MM-dd HH:mm:ss)
data.allotsArray<Object>Allocated proxy list
data.allots[].ipStringExit IP address
data.allots[].node_domainStringProxy server domain
data.allots[].node_portIntegerProxy port
data.allots[].accountStringProxy username
data.allots[].passwordStringProxy password

Response example​

Success:

{
  "code": "200",
  "message": "操作成功",
  "data": {
    "order_id": "20240521174348201395",
    "total": 2,
    "amount": 15.5,
    "currency": "USD",
    "created_at": "2024-12-19 10:30:00",
    "expired_at": "2025-01-18 10:30:00",
    "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"
      }
    ]
  }
}

Failure (no IPs delivered, empty allots):

When the order flow ends without allocating any IP, the API returns failure (not 200). It does not return a success response with empty allots.

{
  "code": "2007",
  "message": "购买失败",
  "data": null
}

7. Renew static proxy​

Method: POST /v2/static-residential/renewIP

Description: Renews an existing static proxy IP.

Permission: Customer access control required

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
ipStringYesIP address to renew-192.168.1.100
daysIntegerYesRenewal duration in daysAllowed: 30, 60, 90, 180, 36530

Request example​

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

Response fields​

FieldTypeDescription
dataObjectRenewal result object
data.order_idStringRenewal order ID
data.totalIntegerNumber of IPs renewed
data.amountDoubleRenewal amount
data.currencyStringBilling currency
data.created_atStringCreated at (yyyy-MM-dd HH:mm:ss)
data.expired_atStringNew expiry (yyyy-MM-dd HH:mm:ss)
data.allotsArray<Object>Renewed proxy list
data.allots[].ipStringRenewed IP address
data.allots[].node_domainStringProxy server domain
data.allots[].node_portIntegerProxy port
data.allots[].accountStringProxy username
data.allots[].passwordStringProxy password

Response example​

Success:

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

7.1 Enable / disable auto-renewal​

Method: POST /v2/static-residential/setAutoRenew

Description: Enable or disable auto-renewal for a given exit IP. When enabled, the system renews from wallet balance before expiry; when disabled, the auto-renew config is removed. If renewal period is not provided, it defaults to the IP's current purchase period.

Permission: Customer access control required (API whitelist)

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
ipStringYesExit IP-192.168.1.100
auto_renewIntegerYes1 enable/update, 0 disable0–11
renew_before_daysIntegerNoDays before expiry to trigger; only when enabling; default 11–301
customer_idStringNoTarget user ID for agent ops (snowflake ID; prefer JSON string); omit=self-null

Request example​

{
  "ip": "192.168.1.100",
  "auto_renew": 1,
  "renew_before_days": 1
}

Response fields​

FieldTypeDescription
dataObjectResult object
data.ipStringExit IP
data.auto_renewIntegerCurrent status: 1 on / 0 off

Response example​

{
  "code": "200",
  "message": "操作成功",
  "data": {
    "ip": "192.168.1.100",
    "auto_renew": 1
  }
}

8. List active user static IPs​

Method: GET /v2/static-residential/listUserIP

Description: Paginated list of the current Token user's active static IPs (not expired, enabled, not deleted). Optional filters: exit IP, proxy account, country/city, sell mode, line type, UDP, and remark. Parameters are passed as Query string (no JSON body).

Permission: Customer access control required (API whitelist)

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
page_indexIntegerNoPage number from 1; defaults to 1 when omitted≥ 11
page_sizeIntegerNoPage size; defaults to 20 when omitted1–10020
ipStringNoExit IP fuzzy match-1.2.3
accountStringNoProxy account fuzzy match-user
country_codeStringNoCountry code (exact)e.g. USUS
city_nameStringNoCity name; unresolved name returns a parameter error; prefer with country_code-Los Angeles
sell_modeIntegerNoSell mode: 1 dedicated, 2 shared1–21
line_typeIntegerNoIP quality: 1 basic, 2 standard, 3 premium1–31
is_udpIntegerNoUDP: 1 enabled, 0 disabled0–10
statusIntegerNoIP status: 1 available (default), 0 unavailable0–11
auto_renewIntegerNoAuto-renew: 1 on, 0 off; omit to skip filter0–11
remarkStringNoUser remark fuzzy match-keyword

Request example​

GET /v2/static-residential/listUserIP?page_index=1&page_size=20&ip=1.2.3&account=user&country_code=US&city_name=Los%20Angeles&sell_mode=1&line_type=1&is_udp=0&remark=keyword

Response fields​

FieldTypeDescription
dataObjectPage result
data.totalLongTotal count
data.page_indexIntegerCurrent page
data.page_sizeIntegerPage size
data.rowsArray<Object>Rows on this page
data.rows[].ipStringExit IP
data.rows[].expired_atStringExpiry (yyyy-MM-dd HH:mm:ss)
data.rows[].accountStringProxy username
data.rows[].passwordStringProxy password
data.rows[].portIntegerProxy port
data.rows[].sell_modeIntegerSell mode: 1 dedicated, 2 shared
data.rows[].country_codeStringCountry code
data.rows[].state_nameStringState/province (English preferred)
data.rows[].city_nameStringCity name (English preferred)
data.rows[].line_typeIntegerIP quality: 1 / 2 / 3
data.rows[].is_udpIntegerUDP: 1 / 0
data.rows[].statusIntegerStatus: 1 available, 0 unavailable
data.rows[].auto_renewIntegerAuto-renew: 1 on, 0 off
data.rows[].bandwidth_limitNumberBandwidth limit (Mbps)
data.rows[].conn_limitIntegerConnection limit
data.rows[].remarkStringUser remark

Response example​

Success:

{
  "code": "200",
  "message": "操作成功",
  "data": {
    "total": 123,
    "page_index": 1,
    "page_size": 20,
    "rows": [
      {
        "ip": "1.2.3.4",
        "expired_at": "2026-12-01 12:00:00",
        "account": "user01",
        "password": "******",
        "port": 10000,
        "sell_mode": 1,
        "country_code": "US",
        "state_name": "California",
        "city_name": "Los Angeles",
        "line_type": 1,
        "is_udp": 0,
        "status": 1,
        "auto_renew": 0,
        "bandwidth_limit": 50,
        "conn_limit": 100,
        "remark": "customer note"
      }
    ]
  }
}

9. List remaining purchasable IP segments​

Method: POST /availableIpSegments

Description: Returns remaining purchasable IP segments and quantities for the given filters. User identity comes from authentication; do not pass it in the body.

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
country_codeStringYesCountry/region codee.g. HK, USHK
city_nameStringNoCity name; empty means random-HongKong
line_typeIntegerNoIP quality: 1 basic, 2 standard, 3 premium1–3, default 11
sell_modeIntegerNoSell mode: 1 dedicated, 2 shared; omit to use platform default1–22
businessStringNoBusiness type from listBusiness-other

Request example​

{
  "country_code": "HK",
  "city_name": "HongKong",
  "line_type": 1,
  "sell_mode": 2,
  "business": "other"
}

Response fields​

FieldTypeDescription
dataObjectQuery result
data.total_quantityIntegerTotal remaining purchasable IPs across all segments
data.segmentsArray<Object>Segments and remaining quantities
data.segments[].ip_segmentStringIP segment in CIDR, e.g. 62.72.182.0/24
data.segments[].quantityIntegerRemaining quantity for that 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 }
    ]
  }
}

10. Batch purchase by IP segment​

Method: POST /batchPurchaseBySegment

Description: Specify multiple IP segment prefixes (e.g. starting with 66.92.226, 66.93.86) plus a total count. Allocation follows the prefix order until the count is reached. Limited to the authenticated user. Returns order ID, allocated count, and expiry.

Permission: Customer access control required (reseller accounts)

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
country_codeStringYesCountry/region codee.g. HK, USHK
city_nameStringNoCity name; empty means random-HongKong
line_typeIntegerNoIP quality: 1 basic, 2 standard, 3 premium1–3, default 12
businessStringNoBusiness type from listBusinessDefault otherother
ip_segment_prefixesArray<String>YesIP segment prefixes, allocated in order. e.g. ["66.92.226","66.93.86"] means allocate from 66.92.226.x first, then 66.93.86.x-["66.92.226","66.93.86"]
countIntegerYesTotal purchase count (allocated in order from selected segments until this count)1–50020
daysIntegerYesPurchase duration in days1, 7, 15, 30, 60, 90, 36530
is_udpIntegerNoUDP: 1 enabled, 0 disabled0–1, default 00
sell_modeIntegerNoSell mode: 1 dedicated, 2 shared; omit to use platform default1–22

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,
  "sell_mode": 2
}

Response fields​

FieldTypeDescription
dataObjectOrder info
data.order_idStringOrder ID
data.totalIntegerAllocated count
data.expired_atStringExpiry time (ISO 8601)

Response example​

Success:

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

11. List allocated IPs by order ID​

Method: GET /orderAllots

Description: Returns all allocated IPs for an order (no pagination). Limited to the authenticated user's own orders. Does not return the order ID; returns the allocation list only.

Permission: Customer access control required

Request parameters​

ParameterTypeRequiredDescriptionConstraintExample
order_idStringYesOrder IDQuery paramSO202401010001

Example: GET /orderAllots?order_id=SO202401010001

Response fields​

data is an array of allocated IPs for the order.

FieldTypeDescription
dataArrayAllocated IP list (see rows below)
data[].ipStringExit IP
data[].node_domainStringProxy server domain
data[].node_portIntegerProxy port
data[].accountStringProxy username
data[].passwordStringProxy password
data[].expired_atStringExpiry time (ISO 8601)

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

12. Debugging​

You can test the APIs with the following commands.

List countries​

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

List cities​

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

List business names​

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

Count idle IPs​

curl -X POST "http://api.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,
       "sell_mode": 2
     }'

Create static proxy IP​

curl -X POST "http://api.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,
       "sell_mode": 1,
       "business": "YouTube",
       "customer_id": null
     }'

Renew static proxy​

curl -X POST "http://api.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 active user static IPs​

curl -G "http://api.ipweb.cc/prod-api/v2/static-residential/listUserIP" \
     -H "Token: your_access_token_here" \
     --data-urlencode "page_index=1" \
     --data-urlencode "page_size=20" \
     --data-urlencode "ip=1.2" \
     --data-urlencode "account=user"

List remaining purchasable IP segments​

curl -X POST "http://api.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,
       "sell_mode": 2,
       "business": "other"
     }'

Batch purchase by IP segment​

curl -X POST "http://api.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,
       "sell_mode": 2
     }'

List allocated IPs by order ID​

curl -X GET "http://api.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. Postman or another API client is recommended for testing.

13. Error codes​

Possible error codes for static IP APIs:

Static IP business error codes​

CodeDescriptionResolution
2001Invalid parameter (including line_type, sell_mode, etc.)Check request parameters against constraints
2004Static IP renewal failedCheck account balance and renewal parameters
2006Static IP / order not foundThe specified IP or order does not exist
2007Purchase failed (no IPs delivered)newIP returned empty allots; check inventory or contact support
2008No permission for this APIConfirm the account has API whitelist access
2009Non-reseller accessSegment purchase APIs require reseller identity
2010Invalid customerIdWhen ordering for a customer, customer_id must be a sub-user
2099Business operation failede.g. insufficient balance; see message for details
2100Invalid days parameterDays must be one of: 30, 60, 90, 180, 365
2101Renewal days limited for this IPThis IP only supports renewal of: 30, 60, 90, 180, 365 days

14. Error response examples​

Invalid sell_mode example​

{
  "code": "2001",
  "message": "sell_mode参数无效",
  "data": null
}

newIP purchase failed (no IPs delivered) example​

{
  "code": "2007",
  "message": "购买失败",
  "data": null
}

Insufficient static IP inventory example​

{
  "code": "2001",
  "message": "所选IP段库存不足",
  "data": null
}

No permission example​

{
  "code": "2008",
  "message": "无权限访问此接口",
  "data": null
}

Static IP not found example​

{
  "code": "2006",
  "message": "IP不存在或不属于当前用户",
  "data": null
}

Invalid days parameter example​

{
  "code": "2100",
  "message": "days参数无效",
  "data": null
}

Renewal days limited example​

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

© 2024 Static IP V2 API Documentation — Version 1.13.0

Last updated: October 28, 2026