IPxSS Proxy Documentation

English

简体中文

English

简体中文

Theme

Wallet, Whitelist, and Query Endpoints ​

This page summarizes the general query endpoints currently available. They are suitable for account status synchronization, whitelist management, and region data retrieval.

Wallet Endpoints ​

Wallet Balance ​

bash
POST /v1/wallet/balance

Purpose: Query the current wallet balance for the account.

Key response field:

  1. balance: current available balance

Response example:

json
{
	"code": 0,
	"data": {
		"balance": 125.5
	},
	"msg": "success",
	"timestamp": 1747037000
}

Wallet Transaction History ​

bash
POST /v1/wallet/usage_record

Purpose: Query wallet spending records and transaction details.

Request parameters:

  1. page: page number, default 1
  2. limit: items per page, default 10, maximum 100

Key response fields:

  1. count: total record count
  2. list: transaction list
  3. list[].money: absolute transaction amount
  4. list[].type: 0 means incoming funds, 1 means outgoing spending
  5. list[].pay_status: 1 means completed

Request example:

json
{
	"page": 1,
	"limit": 10
}

Whitelist Endpoints ​

The current whitelist endpoints are used to manage whitelist IPs for residential products.

Add to Whitelist ​

bash
POST /v1/white_list/add

Common parameters:

  1. product: currently use 1, which represents residential
  2. ip: the IPv4 address to add
  3. remark: optional remark

Request example:

json
{
	"product": 1,
	"ip": "1.2.3.4",
	"remark": "office"
}

Whitelist List ​

bash
POST /v1/white_list/list

Purpose: View whitelist entries configured under the current account.

Optional filter parameters:

  1. product: currently pass 1
  2. ip: exact match filter for a single IP
  3. lock: pass 0 or 1
  4. start_time: start time, format YYYY-MM-DD HH:MM:SS
  5. end_time: end time, format YYYY-MM-DD HH:MM:SS

Key response fields:

  1. total: total number of entries
  2. list[].id: whitelist record ID
  3. list[].mark_ip: original IP string
  4. list[].ip: integer representation of the IP
  5. list[].mark: remark information
  6. list[].status: 1 means enabled

Response example:

json
{
	"code": 0,
	"data": {
		"list": [
			{
				"id": "7c9f2d5d-1111-2222-3333-444444444444",
				"uid": "user-id",
				"mark_ip": "1.2.3.4",
				"ip": 16909060,
				"status": 1,
				"lock": false,
				"mark": "office",
				"created_at": 1747037000,
				"updated_at": 1747037000
			}
		],
		"total": 1
	},
	"msg": "success",
	"timestamp": 1747037000
}

Delete from Whitelist ​

bash
POST /v1/white_list/del

Common parameters:

  1. product: currently pass 1
  2. ips: required; supports batch deletion with comma-separated values, for example 1.1.1.1,2.2.2.2

Request example:

json
{
	"product": 1,
	"ips": "1.1.1.1,2.2.2.2"
}

Update Remark ​

bash
POST /v1/white_list/remark

Purpose: Update the remark for a whitelist entry.

Common parameters:

  1. product: currently pass 1
  2. id: whitelist record ID
  3. remark: new remark

Request example:

json
{
	"product": 1,
	"id": "7c9f2d5d-1111-2222-3333-444444444444",
	"remark": "server-room"
}

Dynamic Residential Query Endpoints ​

Country/Region Query ​

bash
POST /v1/proxy/domestic_dynamic_area

Purpose: Query available countries and regions for residential proxies.

Optional parameters:

  1. search_word: search by country name or country code

Key response fields:

  1. continent: mapping of continent codes to continent names
  2. country: country list grouped by continent
  3. country[].list[].code: country code
  4. country[].list[].ip_num: current number of available regions

Request example:

json
{
	"search_word": "us"
}

City Query ​

bash
POST /v1/proxy/city_by_code

Purpose: Query cities by country or region code.

Request parameters:

  1. code: country code, such as us or hk

State/Province Query ​

bash
POST /v1/proxy/region_by_city

Purpose: Query state and province information by city.

Request parameters:

  1. code: country code
  2. region: city name

Carrier Query ​

bash
POST /v1/proxy/city_isp

Purpose: Query available carriers within a city.

Request parameters:

  1. code: country code

Residential Traffic Balance ​

bash
POST /v1/residential_flow/balance

Key response fields:

  1. balance: remaining traffic, in bytes
  2. expire_time: earliest expiration timestamp

Response example:

json
{
	"code": 0,
	"data": {
		"balance": 5368709120,
		"expire_time": 1749632000
	},
	"msg": "success",
	"timestamp": 1747037000
}

Residential Consumption Log ​

bash
POST /v1/residential_flow/consume_log

Request parameters:

  1. start_time: start time, format YYYY-MM-DD HH:MM:SS
  2. end_time: end time, format YYYY-MM-DD HH:MM:SS

Key response fields:

  1. list[].use: traffic consumed on that day, in bytes
  2. list[].day: timestamp aggregated by day
  3. list[].balance: current remaining traffic snapshot

Request example:

json
{
	"start_time": "2026-04-01 00:00:00",
	"end_time": "2026-04-08 23:59:59"
}

Dynamic ISP Query Endpoints ​

ISP Region Query ​

bash
POST /v1/proxy/isp_data_area

Key response fields:

  1. country[].code: available region code
  2. country[].node: display name of the region

ISP Traffic Balance ​

bash
POST /v1/isp_flow/balance

The response fields are the same as those for residential traffic balance.

ISP Consumption Log ​

bash
POST /v1/isp_flow/consume_log

The request parameters are the same as those for the residential consumption log.

Current Limitations ​

  1. white_list product=5 is still reserved and is not currently available
  2. Dynamic Residential and Dynamic ISP currently mainly provide query capabilities; write endpoints will continue to be added later
  3. The whitelist deletion endpoint currently deletes by ips rather than by id

IPxSS Proxy Infrastructure

Copyright © IPxSS