API Trả theo GB
Các pool trả theo GB (PPG), giá trị chọn theo vị trí và số dư tài khoản.
Pool#
GET /api/v1/pay-per-gb/pools
Authorization: Bearer lit_...
Danh sách đầy đủ: mọi pool mà tài khoản có thể chọn, luôn kèm page.nextCursor: null. Không nhận limit hay cursor.
{
"data": [
{
"name": "Residential",
"proxiesType": "residential",
"authKey": "residential-main",
"pricePerGb": "4.50",
"httpPort": 1337,
"socks5Port": 5337,
"udp": true,
"hubs": [
{ "id": "us-11", "name": "New York, NY", "hostname": "hub-us-11-1.litport.net" },
{ "id": "eu-1", "name": "Amsterdam", "hostname": "hub-eu-1.litport.net" }
],
"geoLevels": ["country", "region", "city"]
}
],
"page": { "nextCursor": null }
}
authKey là định danh pool duy nhất mà API này công khai, và là giá trị cần đặt vào tên người dùng của proxy; không có ID danh mục nội bộ nào được trả về. pricePerGb là chuỗi số thập phân cơ số 10 đã được điều chỉnh theo mức giảm giá của gói cước của tài khoản. Đó là mức giá hiệu lực đầy đủ, không phải giá hiển thị đã làm tròn, nên một khoản thu phí có thể được tính lại từ số byte đã tính phí và giá trị này. httpPort và socks5Port là các cổng đầu vào cho loại proxy của pool đó. udp là true khi pool truyền UDP qua endpoint SOCKS5; proxy HTTP chỉ truyền TCP. hubs liệt kê các hub mà pool này có thể được định tuyến qua. geoLevels liệt kê các cấp mà pool này hỗ trợ cho chọn theo vị trí, từ rộng nhất, hoặc [] khi pool không hỗ trợ chọn theo vị trí.
Nếu tài khoản đã bật Dùng địa chỉ trung lập, hostname và authKey là các tên trung lập, và pool bạn gửi được chấp nhận ở cả hai dạng. Với proxy HTTPS, hãy dùng httpsHostname: chứng chỉ được cấp cho tên đó. Trường này có ở mọi hub và bằng hostname, trừ khi tài khoản dùng địa chỉ trung lập.
Các định danh và hub ví dụ trong tài liệu này chỉ mang tính minh họa.
Vị trí địa lý#
GET /api/v1/pay-per-gb/geo
Authorization: Bearer lit_...
Danh sách phân trang các giá trị chọn theo vị trí: các giá trị quốc gia, vùng hoặc thành phố mà một tập hợp pool thực sự hỗ trợ, để một yêu cầu proxy bị chặn theo vị trí (tham số country/region/city mà Litport không nhận ra hoặc không có năng lực đầu ra) có thể được sửa thay vì đoán lại.
| Tham số | Kiểu | Quy tắc |
|---|---|---|
pool |
string, comma-separated | Bắt buộc, không để trống. Mỗi giá trị là authKey của một pool trả theo GB mà khách hàng có thể chọn. Khóa không xác định hoặc không thể chọn sẽ trả về INVALID |
level |
string | Bắt buộc. Một trong các giá trị country, region hoặc city. |
country |
string | Slug vị trí viết thường. Bắt buộc khi level là region hoặc city. |
region |
string | Slug vị trí viết thường. Tùy chọn; với level city, thu hẹp danh sách trong một bang. |
q |
string | Văn bản tìm kiếm tùy chọn, được cắt khoảng trắng hai đầu và giới hạn 80 ký tự. |
limit |
integer | Số nguyên 1-100; mặc định 50. |
cursor |
string | page |
curl --get 'https://litport.net/api/v1/pay-per-gb/geo' \
-H "Authorization: Bearer $LITPORT_API_KEY" \
--data-urlencode 'pool=residential-main' \
--data-urlencode 'level=region' \
--data-urlencode 'country=us' \
--data-urlencode 'limit=50'
{
"data": [
{ "value": "california", "label": "California" },
{ "value": "new-york", "label": "New York" }
],
"page": { "nextCursor": null }
}
data là giao của các giá trị mà mọi pool được yêu cầu đều hỗ trợ ở level đã cho, nên một giá trị được trả về chắc chắn dùng được với tất cả các pool đó cùng lúc. value của mỗi tùy chọn là slug chữ thường chính xác để gửi làm tham số country, region hoặc city tương ứng trong tên người dùng của proxy; label là tên hiển thị, và các tùy chọn cấp quốc gia cũng có thể kèm emoji. q lọc data bằng so khớp chuỗi con với value hoặc label, không phân biệt chữ hoa chữ thường và dấu câu.
Các tùy chọn thành phố cũng kèm region và regionLabel, tức bang của thành phố. Tên người dùng nhắm tới một thành phố cần region đó bên cạnh city, ví dụ _country-de_region-berlin_city-berlin, vì slug thành phố bị trùng giữa các bang. Khi không có tham số region, level=city liệt kê mọi thành phố trong quốc gia; khi có, chỉ liệt kê các thành phố của bang đó.
Lỗi vị trí địa lý#
Hãy kiểm tra geoLevels của pool trước để tránh hai lỗi GEO_.
| Trạng thái | Mã | Ý nghĩa |
|---|---|---|
400 |
INVALID_POOL |
pool bị thiếu, không tồn tại hoặc tài khoản này không thể chọn. |
400 |
INVALID |
level không phải country, region hay city. |
400 |
INVALID |
region cần country; city cần country. |
400 |
GEO |
Một pool được yêu cầu đã tắt chọn theo vị trí. |
400 |
GEO |
Một pool được yêu cầu không hỗ trợ level này. |
400 |
INVALID / INVALID |
limit không nằm trong khoảng 1–100, hoặc cursor không phải là giá trị mà danh sách này đã trả về. |
Số dư#
GET /api/v1/pay-per-gb/balance
Authorization: Bearer lit_...
Dùng endpoint này để giải thích một yêu cầu proxy thất bại với số dư không đủ (mã 13) mà không phải đoán nguyên nhân.
{
"data": {
"balance": {
"unitsActive": "12.345678901234",
"unitsReserved": "0.5",
"unitsAvailable": "11.845678901234",
"unitsExpireAt": "2026-12-01T00:00:00.000Z"
},
"plan": {
"id": "pro-monthly",
"expiresAt": "2026-10-01T00:00:00.000Z"
}
}
}
unitsActive, unitsReserved và unitsAvailable là các chuỗi số thập phân cơ số 10 để client không bao giờ mất độ chính xác do làm tròn số dấu phẩy động. unitsReserved không âm và hiện đang được giữ bởi các giao dịch thanh toán đang xử lý, chưa chốt. unitsAvailable bằng unitsActive trừ unitsReserved và có dấu: giá trị này âm khi khoản giữ chỗ vượt quá số dư đang hoạt động, hoặc khi một lượt chạy đã kết thúc phải bị thu phí vượt quá số dư khả dụng. Hãy coi một yêu cầu là có nguy cơ gặp lỗi số dư không đủ khi unitsAvailable bằng hoặc gần bằng 0. unitsExpireAt là mốc thời gian của số dư đang hoạt động hết hạn sớm nhất, hoặc null khi không có khoản nào được lên lịch hết hạn.
plan.id là định danh của gói cước đang hoạt động, hoặc null khi tài khoản không có gói cước đang hoạt động. plan.expiresAt là mốc thời gian hết hạn của gói cước đó, hoặc null khi không có gói cước đang hoạt động.
Endpoint này chỉ báo số dư. Nó không trả về email, tên hay bất kỳ trường hồ sơ tài khoản nào khác. Cùng số dư đó thanh toán cho các gói không giới hạn trong bảng điều khiển; API đọc được số dư nhưng không thể chi tiêu nó.
Token trả theo GB#
poolSelection của một token PPG (xem Tokens) nêu pool cố định của token, hoặc báo rằng tên người dùng của proxy phải chọn một pool. Liệt kê các token PPG của tài khoản bằng GET /tokens?type=ppg. Xem proxy trả theo GB để biết đầy đủ cú pháp tên người dùng, gồm cách các tham số pool, vị trí và phiên kết hợp với nhau.