API оплаты за ГБ

Пулы с оплатой за ГБ (PPG), значения геотаргетинга и баланс аккаунта.

Пулы#

GET /api/v1/pay-per-gb/pools
Authorization: Bearer lit_...

Полный список: каждый пул, который может выбрать аккаунт, всегда с page.nextCursor: null. Параметры limit и 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 — единственный идентификатор пула, который отдаёт этот API, и значение, которое нужно указать в логине прокси; внутренний ID каталога не возвращается. pricePerGb — десятичная строка по основанию 10, уже скорректированная с учётом скидки по тарифу аккаунта. Это полная эффективная ставка, а не округлённая цена для отображения, поэтому списание можно воспроизвести по тарифицируемым байтам и этому значению. httpPort и socks5Port — порты входа для типа прокси этого пула. udp равно true, когда пул пропускает UDP через эндпоинт SOCKS5; HTTP-прокси передают только TCP. hubs перечисляет хабы, через которые может маршрутизироваться этот пул. geoLevels перечисляет уровни, которые этот пул поддерживает для геотаргетинга, начиная с самого широкого, или [], когда у пула нет геотаргетинга.

Примеры идентификаторов и хабов в этой документации приведены для иллюстрации.

Гео#

GET /api/v1/pay-per-gb/geo
Authorization: Bearer lit_...

Постраничный список значений геотаргетинга: значения страны, региона или города, которые на самом деле поддерживает набор пулов, чтобы запрос через прокси, заблокированный по гео (параметр country/region/city, который Litport не распознаёт или для которого у него нет выходных мощностей), можно было исправить, а не гадать снова.

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 — пересечение значений, которые поддерживает каждый запрошенный пул на заданном level, поэтому возвращённое значение гарантированно можно использовать со всеми этими пулами одновременно. value каждого варианта — точный слаг в нижнем регистре, который нужно отправить как соответствующий параметр country, region или city в логине прокси; label — отображаемое название, а варианты уровня страны могут также содержать emoji. q фильтрует data по подстроке без учёта регистра и знаков препинания в value или label.

Варианты городов также содержат region и regionLabel — штат города. В логине для нацеливания на город нужен этот region рядом с city, например _country-de_region-berlin_city-berlin, потому что слаги городов повторяются в разных штатах. Без параметра region значение level=city перечисляет все города страны; с ним — только города этого штата.

Ошибки гео#

Чтобы избежать двух ошибок GEO_, сначала проверьте geoLevels пула.

Баланс#

GET /api/v1/pay-per-gb/balance
Authorization: Bearer lit_...

Используйте это, чтобы объяснить запрос через прокси, завершившийся ошибкой недостаточный баланс (код 13), не гадая о причине.

{
  "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 и unitsAvailable — десятичные строки по основанию 10, поэтому клиенты не теряют точность из-за округления чисел с плавающей запятой. unitsReserved неотрицательно и сейчас удерживается выполняющимися транзакциями тарификации, ещё не окончательными. unitsAvailable равно unitsActive минус unitsReserved и имеет знак: оно становится отрицательным, когда резервы превышают активный баланс или когда завершившийся запуск пришлось списать сверх доступного баланса. Считайте, что запрос под угрозой ошибки недостаточного баланса, когда unitsAvailable равно нулю или близко к нему. unitsExpireAt — метка времени того активного баланса, который истекает раньше всех, или null, когда истечение ни для какого не запланировано.

plan.id — идентификатор активного тарифа, или null, когда у аккаунта нет активного тарифа. plan.expiresAt — метка времени окончания этого тарифа, или null, когда активного тарифа нет.

Этот эндпоинт возвращает только баланс. Он не возвращает email, имя и никакие другие поля профиля аккаунта.

Токены с оплатой за ГБ#

poolSelection токена PPG (см. Токены) называет его закреплённый пул или сообщает, что пул должен выбрать логин прокси. Список PPG-токенов аккаунта можно получить запросом GET /tokens?type=ppg. Полную грамматику логина, включая то, как сочетаются параметры пула, гео и сессии, см. в разделе Прокси с оплатой за ГБ.