Documentación de la API

Autenticación

Envía tu clave en la cabecera Authorization como token bearer, o en la cabecera X-API-Key. Nunca pongas la clave en la URL.

Authorization: Bearer sk_live_your_key_here
# or
X-API-Key: sk_live_your_key_here

Las claves pueden llevar scopes: read (solo lectura) y trade (crear y renovar pedidos). Una clave sin scopes tiene acceso total.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/ping
# → {"ok":true,"service":"sotaproxy","version":"v1"}

Límites de peticiones

Los límites se aplican por clave API (por minuto):

• Lecturas (saldo, pedidos, proxies): 120 / min
• Catálogo y cotizaciones: 60 / min
• Pedidos y renovaciones: 20 / min

Superar un límite devuelve HTTP 429.

Idempotencia

Las peticiones que mueven dinero (crear un pedido, renovar un proxy) requieren una cabecera Idempotency-Key - cualquier cadena única por intento (máx. 128 caracteres). Si una petición se reintenta con la misma clave, se devuelve el resultado original en lugar de cobrar dos veces. La respuesta repetida incluye "idempotentReplay": true.

Errores

Los errores devuelven el estado HTTP correspondiente y un cuerpo JSON: {"error":{"code":"...","message":"..."}}.

Devuelve los productos a la venta con sus países y períodos de alquiler disponibles. Los precios dependen de la cuenta - usa /quote para el precio.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/products

{
  "products": [
    {
      "product": "ipv4",
      "unit": "proxy",
      "countries": [ { "id": 565, "name": "US", "alpha3": null }, ... ],
      "periods": [
        { "id": "1m", "name": "1 month",  "days": 30 },
        { "id": "2m", "name": "2 months", "days": 60 }, ...
      ]
    }
  ]
}

Devuelve el precio exacto para un producto, país, período y cantidad dados, sin comprar.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"product":"ipv4","countryId":565,"periodId":"1m","quantity":5}' \
  https://api.sotaproxy.com/api/v1/quote

{
  "product": "ipv4", "countryId": 565, "periodId": "1m", "quantity": 5,
  "unitPrice": 1.8, "total": 9, "currency": "USD",
  "balance": 42.5, "sufficientBalance": true
}

Compra y aprovisiona proxies, descontando de tu saldo. Requiere el scope trade y una cabecera Idempotency-Key. Campos opcionales del cuerpo: purpose (nota de uso) y protocol (HTTPS o SOCKS5).

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-id" \
  -d '{"product":"ipv4","countryId":565,"periodId":"1m","quantity":5}' \
  https://api.sotaproxy.com/api/v1/orders

{
  "order": {
    "id": "31307ef6-6ee4-4ec7-8a78-e5bd6ee52b9b",
    "product": "ipv4", "country": "US", "periodId": "1m",
    "quantity": 5, "total": 9, "currency": "USD",
    "status": "completed", "createdAt": "2026-07-24T23:11:03.617Z"
  },
  "idempotentReplay": false
}

Nota: los proxies de un pedido nuevo pueden tardar unos minutos en aparecer (sobre todo IPv6). Consulta /orders/{id}/proxies hasta que se devuelvan.

Lista tus pedidos (paginado: ?page, ?limit) o lee un pedido concreto por id.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/orders?limit=20"
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/orders/ORDER_ID

Devuelve los proxies emitidos de un pedido. Añade ?format=txt para líneas simples ip:port:login:password.

curl -H "Authorization: Bearer $KEY" \
  "https://api.sotaproxy.com/api/v1/orders/ORDER_ID/proxies?format=txt"

{
  "proxies": [
    {
      "id": "e8c2...", "product": "ipv4", "ip": "23.165.240.2",
      "portHttp": 11565, "portSocks": null,
      "login": "user", "password": "pass",
      "country": "US", "status": "active",
      "expiresAt": "2026-07-31T00:00:00.000Z"
    }
  ]
}

Devuelve todos los proxies activos de tu cuenta. Filtra por producto con ?product=ipv4.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/proxies?product=ipv4"

Devuelve el precio exacto de renovar el pedido de un proxy por un período dado sin cobrar - úsalo para mostrar el coste antes de confirmar. Como la propia renovación, opera a nivel de pedido: proxiesRenewed es el pedido completo y price los cubre todos. El query periodId es uno de 1m, 3m, 6m, 12m (por defecto 1m). No hace falta Idempotency-Key.

curl -H "Authorization: Bearer $KEY" \
  "https://api.sotaproxy.com/api/v1/proxies/PROXY_ID/renew-quote?periodId=1m"

{
  "proxyId": "2364b03b-...", "periodId": "1m",
  "proxiesRenewed": 10, "price": 2, "currency": "USD",
  "newExpiresAt": "2026-10-01T00:00:00.000Z"
}

Extiende un proxy - la renovación es a nivel de pedido: renovar un proxy renueva todos los proxies comprados en el mismo pedido, y el cargo los cubre todos. Requiere el scope trade y una Idempotency-Key. El campo periodId del cuerpo es uno de 1m, 3m, 6m, 12m.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: renew-unique-id" \
  -d '{"periodId":"1m"}' \
  https://api.sotaproxy.com/api/v1/proxies/PROXY_ID/renew

{
  "proxyId": "2364b03b-...", "newExpiresAt": "2026-10-01T00:00:00.000Z",
  "amountCharged": 2, "proxiesRenewed": 10, "currency": "USD",
  "idempotentReplay": false
}

Los residenciales funcionan distinto a los productos por período: compras un paquete de tráfico en GB y luego creas dentro de él uno o más endpoints. Cada endpoint fija una segmentación geo opcional (país / región / ciudad / ISP) y la rotación, y devuelve credenciales de gateway listas para usar. El tráfico se descuenta del paquete a medida que se usan los endpoints.

1. Planes - GET /residential/plans lista los paquetes de GB con los precios de tu cuenta (el precio por GB de contrato se aplica automáticamente).

2. Catálogo geo - GET /residential/locations devuelve países; añade ?country=AT para regiones, ciudades e ISP.

3. Compra un paquete - requiere el scope trade y una Idempotency-Key:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: res-unique-id" \
  -d '{"planId":"ind_3gb"}' \
  https://api.sotaproxy.com/api/v1/residential/orders

{
  "package": { "id": "81cdc5d0-...", "plan": "3 GB", "trafficGb": 3,
    "pricePerGb": 2, "totalPrice": 6, "trafficLeftGb": 3,
    "active": true, "expiresAt": "2026-08-22T23:59:59.000Z" },
  "amountCharged": 6, "currency": "USD", "idempotentReplay": false
}

4. Crea un endpoint (aquí se fija la geo) - la respuesta trae credenciales que puedes conectar directamente a cualquier cliente:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"packageId":"81cdc5d0-...","name":"Austria sticky","country":"AT","rotation":-1}' \
  https://api.sotaproxy.com/api/v1/residential/lists

{
  "list": { "id": "d7e8cbf4-...", "country": "AT", "rotation": -1, ... },
  "proxy": {
    "host": "proxy.sotaproxy.com", "portHttp": 10000, "portSocks": 10000,
    "login": "3c4d8398...", "password": "fTYRr2CH...",
    "httpUrl": "http://login:password@proxy.sotaproxy.com:10000",
    "socksUrl": "socks5://login:password@proxy.sotaproxy.com:10000"
  }
}

rotation: 0 = IP nueva por petición, -1 = sesión sticky, 1–3600 = segundos entre rotaciones. Gestiona los endpoints con GET /residential/lists, DELETE /residential/lists/{id}; controla el consumo con GET /residential/packages.

Los proxies móviles se venden por módem desde un catálogo fijo de tarifas (país + operador + período de alquiler). Elige una tarifa, compra N unidades - después el pedido se comporta como cualquier otro: GET /orders/{id}/proxies devuelve las credenciales.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/mobile/tariffs?country=DE"

{
  "tariffs": [
    { "id": "mt_f1098dbc7be7a1b0", "country": "DE", "carrier": "Vodafone Germany",
      "periodId": "day", "period": "1 day", "unitPrice": 8.64,
      "dedicated": true, "stock": 16 }
  ],
  "currency": "USD"
}

Compra - requiere el scope trade y una Idempotency-Key:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mob-unique-id" \
  -d '{"tariffId":"mt_f1098dbc7be7a1b0","quantity":1}' \
  https://api.sotaproxy.com/api/v1/mobile/orders

La disponibilidad de tarifas depende del stock - comprueba siempre stock antes de pedir. Los proxies móviles también aparecen en GET /proxies?product=mobile.

Consulta tu saldo prepagado, o la cuenta y los scopes a los que pertenece una clave.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/balance
# → {"balance":42.5,"currency":"USD"}

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/me
# → {"accountId":"...","scopes":["read","trade"]}

Un socio con su propia plataforma mantiene a sus usuarios, sus registros y sus saldos de su lado. Lo que necesita de nosotros es poder repartir el stock que ya compró: crear un cliente, asignarle una cantidad, emitir credenciales y leer el consumo para su propia facturación.

Requiere is_reseller en la cuenta. Las escrituras requieren el scope trade. Las mismas operaciones existen en el panel, y ambas superficies llaman al mismo servicio.

El ciclo completo

Cinco llamadas llevan a un cliente del registro a la factura. El tráfico se devuelve siempre en ambas unidades: {"mb": 1024, "gb": 1}.

# 1. how much can I hand out right now
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/stock

# 2. a new client signed up on your platform
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"acme-corp"}' https://api.sotaproxy.com/api/v1/reseller/clients
# → {"client":{"id":"<clientId>", ...}}

# 3. they paid you for 10 GB
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8412" \
  -d '{"trafficGb":10}' https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/traffic

# 4. issue their credentials
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"main","ports":5,"rotation":-1,"country":"US"}' \
  https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/access
# → login/password + host + portFrom..portTo + readyInSeconds

# 5. bill them: poll usage on your schedule
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/usage

Los proxies estáticos funcionan distinto

El tráfico se divide, una dirección no. IPv4, IPv6 e ISP solo pueden asignarse a un cliente, nunca repartirse. Tú sigues siendo el propietario y quien paga, así que las renovaciones y la renovación automática siguen saliendo de tu saldo y la relación con el cliente nunca nos toca. Retirar la asignación devuelve el proxy a tu grupo libre intacto.

# what is free to hand out right now
curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/reseller/proxies?filter=free&type=ipv4"

# pin two of them to a client
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"proxyIds":["<id1>","<id2>"]}' https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/proxies
# → {"requested":2,"assigned":2}

# what that client holds, with credentials to hand over
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/proxies

Notas que ahorran un ticket de soporte

• ·Las credenciales necesitan unos 90 segundos antes de autenticar, porque la red superior las registra de forma asíncrona. Hasta entonces las conexiones responden 407. La respuesta de emisión incluye readyInSeconds para que retrases mostrárselas a tu usuario.
• ·`rotation`: -1 mantiene una sesión fija, 0 da una IP nueva por petición, cualquier otro valor son los segundos antes de que cambie la IP.
• ·Puertos: una credencial abarca portFrom..portTo, y cada puerto es una sesión independiente con su propia IP. Un mismo puerto sirve HTTP y SOCKS5.
• ·La asignación está limitada por el margen real, no por el remanente bruto: el tráfico ya entregado a otros clientes se resta antes.
• ·La jerarquía es de un solo nivel. Un cliente no puede tener clientes propios, y tus clientes no reciben acceso a nuestro panel. Tus usuarios viven en tu plataforma, que es el sentido de esta API.
• ·assigned informa de lo que ocurrió realmente al asignar proxies. Los ids que no son tuyos, o que ya no existen, se omiten en lugar de tumbar la llamada entera, así que compáralo con requested si necesitas reaccionar.

Conecta SotaProxy a Claude (o a cualquier asistente de IA compatible con MCP) y gestiona proxies simplemente chateando: «cómprame 5 proxies ISP de EE. UU. por un mes», «consigue 3 GB de tráfico residencial con geo Austria», «¿cuál es mi saldo?». El asistente siempre te muestra el precio exacto y pide confirmación antes de gastar nada. Guía completa de MCP con las 18 herramientas →

https://api.sotaproxy.com/mcp?key=sk_live_YOUR_KEY

claude mcp add --transport http sotaproxy https://api.sotaproxy.com/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

{
  "mcpServers": {
    "sotaproxy": {
      "url": "https://api.sotaproxy.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Solución de problemas: un error de autenticación significa que la clave es incorrecta o fue revocada - crea una nueva en el panel. Si la compra falla con un error de scope, a la clave le falta trade. Las compras se descuentan de tu saldo prepagado - recárgalo primero en el panel. Las claves en URLs son sensibles: usa la cabecera cuando sea posible y revoca las claves que ya no uses.