API de pago por GB

Pools de pago por GB (PPG), valores de segmentación geográfica y saldo de la cuenta.

Pools#

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

Una lista completa: todos los pools que la cuenta puede seleccionar, siempre con page.nextCursor: null. No admite limit ni 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 es el único identificador de pool que expone esta API y el valor que se debe poner en el usuario del proxy; no se devuelve ningún ID interno del catálogo. pricePerGb es una cadena decimal en base 10 ya ajustada al descuento del plan de la cuenta. Es la tarifa efectiva completa, no un precio redondeado para mostrar, de modo que un cobro se puede reproducir a partir de los bytes cobrados y este valor. httpPort y socks5Port son los puertos de entrada para el tipo de proxy de ese pool. udp es true cuando el pool transporta UDP a través del endpoint SOCKS5; los proxies HTTP transportan solo TCP. hubs enumera los hubs por los que se puede enrutar este pool. geoLevels enumera los niveles que este pool admite para la segmentación geográfica, del más amplio al más específico, o [] cuando el pool no tiene segmentación geográfica.

Los identificadores y hubs de ejemplo de esta documentación son ilustrativos.

Segmentación geográfica#

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

Una lista paginada de valores de segmentación geográfica: los valores de país, región o ciudad que un conjunto de pools admite realmente, para poder corregir una solicitud de proxy bloqueada por la geografía (un parámetro country/region/city que Litport no reconoce o para el que no tiene capacidad de salida) en lugar de volver a adivinar.

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 es la intersección de los valores que admite cada pool solicitado en el level indicado, por lo que se garantiza que un valor devuelto se puede usar con todos ellos a la vez. El value de cada opción es el slug exacto en minúsculas que se debe enviar como el parámetro country, region o city correspondiente del usuario del proxy; label es un nombre para mostrar, y las opciones de nivel país también pueden incluir emoji. q filtra data con una coincidencia de subcadena contra value o label, sin distinguir mayúsculas ni signos de puntuación.

Las opciones de ciudad también incluyen region y regionLabel, el estado de la ciudad. El usuario del proxy que apunta a una ciudad necesita ese region junto al city, por ejemplo _country-de_region-berlin_city-berlin, porque los slugs de ciudades se repiten entre estados. Sin el parámetro region, level=city enumera todas las ciudades del país; con él, solo las ciudades de ese estado.

Errores de segmentación geográfica#

Revisa primero los geoLevels de un pool para evitar los dos errores GEO_.

Saldo#

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

Úsalo para explicar una solicitud de proxy que falló con saldo insuficiente (código 13) sin adivinar la causa.

{
  "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 y unitsAvailable son cadenas decimales en base 10, para que los clientes nunca pierdan precisión por el redondeo de punto flotante. unitsReserved no es negativo y está retenido actualmente por transacciones de facturación en curso, aún no definitivas. unitsAvailable es unitsActive menos unitsReserved y lleva signo: pasa a ser negativo cuando las reservas superan el saldo activo, o cuando hubo que cobrar una ejecución terminada por encima del saldo disponible. Considera que una solicitud corre riesgo de un error de saldo insuficiente cuando unitsAvailable es cero o está cerca de cero. unitsExpireAt es la marca de tiempo del saldo activo que caduca primero, o null cuando no hay ninguno programado para caducar.

plan.id es el identificador del plan activo, o null cuando la cuenta no tiene un plan activo. plan.expiresAt es la marca de tiempo de caducidad de ese plan, o null cuando no hay un plan activo.

Este endpoint informa solo el saldo. No devuelve el correo electrónico, el nombre ni ningún otro campo del perfil de la cuenta.

Tokens de pago por GB#

El poolSelection de un token PPG (consulta Tokens) indica su pool fijo, o informa que el usuario del proxy debe seleccionar uno. Enumera los tokens PPG de una cuenta con GET /tokens?type=ppg. Consulta Proxies de pago por GB para ver la gramática completa del usuario, incluido cómo se combinan los parámetros de pool, ubicación y sesión.