Static Residential API: Balance, Inventory, Orders, and IPs
Query balances, availability, business names, orders, and purchased IP records, including pagination and protocol fields.
Read account balances, static residential inventory, business names, your orders, and purchased IP records. All paths use the business API host shown in the web console and require Api-Token: YOUR_API_KEY.
Endpoints
| Method | Path | Scope |
|---|---|---|
| GET | /api/user/v1/account/balance | account:read |
| GET | /api/user/v1/static-residential/countries | static:inventory:read |
| GET | /api/user/v1/static-residential/cities | static:inventory:read |
| GET | /api/user/v1/static-residential/inventory | static:inventory:read |
| GET | /api/user/v1/static-residential/business-names | static:inventory:read |
| GET | /api/user/v1/static-residential/orders | static:ip:read |
| GET | /api/user/v1/static-residential/ips | static:ip:read |
| GET | /api/user/v1/static-residential/ips/{id} | static:ip:read |
Success uses {"code":0,"msg":"success","data":{...}}. Handle both HTTP errors and nonzero business codes.
1. Balance
GET /api/user/v1/account/balance takes no business parameters.
Field in data | Meaning |
|---|---|
user_uuid | Identifier of the calling account |
balance | Effective account balance |
gift_balance | Promotional balance |
commission_balance | Commission balance |
static_purchase_available_balance | Balance available for static purchases; currently the value of balance |
balance_source | self, or parent for a shared parent balance |
scopes | Permissions granted to the key |
currency | USD |
A balance read does not reserve funds or guarantee a price. Funds may change between quoting and purchasing.
2. Countries, cities, and inventory
The countries endpoint returns items, total, and cache_status. Each country contains country_code, country_name, country_name_cn, country_name_hk, and stock.
The cities endpoint requires a two-letter country_code, such as US. Its response contains country_code, items, total, and cache_status.
The inventory endpoint accepts:
| Parameter | Description |
|---|---|
country_code | Optional two-letter country code |
city_name | Optional substring filter for the city name |
page | Default 1; minimum 1 |
page_size | Default 20; range 1–100 |
Each city/inventory item contains continent_name, country_code, city_name, stock, monthly_price, and currency. Inventory responses contain items, pagination, and cache_status.
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user/v1/static-residential/inventory" \
-H "Api-Token: $DFIP_API_KEY" \
--data-urlencode 'country_code=US' \
--data-urlencode 'page=1' --data-urlencode 'page_size=20'
US illustrates the code format; use the current results to determine availability. Stock and monthly prices may be cached. Request a fresh quote before purchasing and preserve the returned city name exactly. Do not translate or correct its spelling, or substitute a city code from the dynamic location API.
3. Business names
GET /api/user/v1/static-residential/business-names takes no business parameters.
Each entry in data.items contains business_name, category, and is_hot. The response also provides data.default, currently other. Select a business_name from the current list when requesting a quote; do not invent or translate its API value.
4. Your static residential orders
GET /api/user/v1/static-residential/orders?page=1&page_size=20
This returns static residential orders belonging to the calling account. Each data.items entry includes:
| Field | Meaning |
|---|---|
order_id | Business order identifier; compare it with an operation's local_order_id |
total_amount, unit_price | Order amount and unit price |
ip_quantity | Number of IPs |
payment_status, order_type | Numeric order fields; these are not asynchronous operation statuses |
purchase_duration | Purchased duration field |
created_at, updated_at | Creation and update times |
An order record alone does not prove delivery. Wait for the purchase operation to reach completed, then verify the purchased IP records.
5. Purchased IPs and individual records
GET /api/user/v1/static-residential/ips
| Query parameter | Description |
|---|---|
status | active, expired, or all; omitting it also disables status filtering |
country_code | Optional two-letter country code |
city | Optional city substring; unlike inventory, this parameter is named city, not city_name |
ip_address | Optional IP address substring |
page, page_size | Standard pagination |
For GET /api/user/v1/static-residential/ips/{id}, use the positive integer id returned by the list. It is neither an IP address nor an order number. Results are restricted to static residential records currently owned by the calling account.
curl --silent --show-error --get \
"$DFIP_API_BASE/api/user/v1/static-residential/ips" \
-H "Api-Token: $DFIP_API_KEY" \
--data-urlencode 'status=active' \
--data-urlencode 'page=1' --data-urlencode 'page_size=20'
List entries in data.items[] and a detail response's data share this structure:
| Field | Meaning |
|---|---|
id, order_id, ip_address | Record ID, order identifier, and proxy address |
proxy_username, proxy_password | Proxy credentials; keep them private |
proxy_protocol | Protocol bitmask: 1=HTTP, 2=HTTPS, 4=SOCKS5, 5=HTTP+SOCKS5; distinct from the protocol names sent in a quote |
http_port, https_port, s5_port | Protocol ports; unavailable ports may be 0 or null; use only positive ports supported by the product; current static purchases support HTTP/SOCKS5 |
country_code, country, state, city | Location information |
status | active or expired; disabled or expired records are reported as expired |
is_renewable, is_auto_renew | Read-only renewal flags; their presence does not imply a mutation endpoint |
remark | Note |
expiry_at, created_at, updated_at | Expiry, creation, and update times |
Timestamp strings have no timezone offset. Confirm the service timezone before calculating exact expiry times; do not assume UTC.
Pagination and errors
pagination contains page, page_size, total, and total_pages. Empty results have total and total_pages equal to 0. Countries, cities, and business names do not use pagination.
Common codes: 40001 invalid country code; 40006 invalid IP record ID; 40007 invalid status filter; 40402 unavailable or inaccessible record; 50301 temporary inventory failure; 50302 business names unavailable. See the getting-started guide for authentication errors.