Ir al contenido
royalproxy
Empezar

Documentación de la API de proxies

Usa la API REST de RoyalProxy para leer tu saldo y tus datos de conexión, consultar precios, hacer pedidos con tu saldo y generar usuarios del proxy desde tu propio código.

Crear una clave de APIVer endpoints

¿Cómo empiezo?

  1. 1Regístrate e inicia sesión en el panel.
  2. 2Abre Connect y crea una clave de API. La clave completa se muestra solo una vez, así que cópiala en un lugar seguro.
  3. 3Envía la clave en el encabezado Authorization en cada solicitud que la necesite.
  4. 4Llama a /account para comprobar que la clave funciona y luego haz pedidos con /orders.

¿Cómo funciona la autenticación?

Las solicitudes sobre tu propia cuenta (account, orders, proxy-user) necesitan una clave de API. Envíala como token Bearer en el encabezado Authorization. Los precios, países y cotizaciones son públicos y no necesitan clave.

Solo guardamos un hash de la clave. Si la pierdes, crea una nueva en el panel y la clave anterior deja de funcionar al instante. No pongas la clave en código del navegador ni en repositorios públicos.

HTTP header
Authorization: Bearer rpk_your_api_key

URL base y formato

URL base
https://royalproxy.online/api/v1
Cuerpo de solicitud y respuesta
application/json
Dinero
Números en USD, por ejemplo 807.90
Hora
ISO 8601 (UTC)

¿Hay un límite de llamadas?

Cada clave de API puede enviar hasta 60 solicitudes por minuto. Los endpoints públicos permiten 60 solicitudes por minuto por IP. Si superas el límite recibes HTTP 429; espera un minuto y vuelve a intentarlo.

¿Cómo son los errores?

Los errores usan el código de estado HTTP y un cuerpo JSON con un código corto y un mensaje.

Ejemplo
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}
code
bad_requestHTTP 400Falta un valor o no está permitido para este producto.
unauthorizedHTTP 401La clave de API falta o no es válida.
insufficient_balanceHTTP 402El saldo es menor que el total del pedido. No se cobró nada.
not_foundHTTP 404No hay ningún pedido con este id en tu cuenta.
rate_limitedHTTP 429Demasiadas solicitudes en un minuto.
server_errorHTTP 500No se pudo completar la solicitud. No se cobró nada.

Endpoints

Obtener tu cuenta

GET/api/v1/accountClave de API

Devuelve tu saldo, el host del proxy, los puertos, el usuario y la contraseña, y las IP permitidas.

Solicitud
curl https://royalproxy.online/api/v1/account \
  -H "Authorization: Bearer rpk_your_api_key"
Respuesta
{
  "username": "royal_user",
  "balance_usd": 1300,
  "proxy": {
    "host": "gate.royalproxy.online",
    "http_port": 6100,
    "socks5_port": 6200,
    "username": "rpexample1",
    "password": "your_password"
  },
  "allowed_ips": [
    "203.0.113.10"
  ]
}

Listar productos y precios

GET/api/v1/productsNo necesita clave

Devuelve todos los productos con sus límites, tramos de precio y descuentos. Los precios salen de la misma tabla que la página de precios.

Solicitud
curl https://royalproxy.online/api/v1/products
Respuesta
{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

Listar países y ciudades

GET/api/v1/countriesNo necesita clave

Devuelve los países disponibles para un producto, con los valores de ciudad que puedes poner en el usuario del proxy.

CampoSignificado
productOpcionalunlimited, residential, isp o datacenter. Por defecto residential.
Solicitud
curl "https://royalproxy.online/api/v1/countries?product=datacenter"
Respuesta
{
  "product": "datacenter",
  "countries": [
    {
      "code": "us",
      "name": "United States",
      "region": "americas",
      "datacenter": true,
      "cities": [
        {
          "name": "New York",
          "value": "new_york"
        },
        {
          "name": "Los Angeles",
          "value": "los_angeles"
        }
      ]
    }
  ]
}

Obtener una cotización

POST/api/v1/quoteNo necesita clave

Calcula el total de un pedido sin cobrar nada. Usa el mismo cuerpo que para hacer un pedido.

CampoSignificado
productObligatoriounlimited, residential, isp o datacenter.
quantityObligatorioDías para unlimited (1~365), GB para residential (5~5,000), IP para isp (1~1,000) o datacenter (5~5,000).
concurrencyOpcionalSolo unlimited: 200, 500, 1000 o 2000.
bandwidthOpcionalSolo unlimited, en Mbps: 100, 200, 500 o 1000.
monthsOpcionalSolo isp y datacenter: 1, 3, 6 o 12.
countryOpcionalSolo isp y datacenter: código de país de dos letras, por ejemplo jp. Consulta /countries.
Solicitud
curl -X POST https://royalproxy.online/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
Respuesta
{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.97,
  "unit": "day",
  "total_usd": 269.1
}

Hacer un pedido

POST/api/v1/ordersClave de API

Descuenta el total de tu saldo y crea el pedido. Los pedidos nuevos empiezan como pending (activando) y pasan a active cuando están listos. Si un pedido no se puede activar, pasa a refunded y el importe completo vuelve a tu saldo. Devuelve 402 cuando el saldo no alcanza.

CampoSignificado
productObligatoriounlimited, residential, isp o datacenter.
quantityObligatorioDías para unlimited (1~365), GB para residential (5~5,000), IP para isp (1~1,000) o datacenter (5~5,000).
concurrencyOpcionalSolo unlimited: 200, 500, 1000 o 2000.
bandwidthOpcionalSolo unlimited, en Mbps: 100, 200, 500 o 1000.
monthsOpcionalSolo isp y datacenter: 1, 3, 6 o 12.
countryOpcionalSolo isp y datacenter: código de país de dos letras, por ejemplo jp. Consulta /countries.
Solicitud
curl -X POST https://royalproxy.online/api/v1/orders \
  -H "Authorization: Bearer rpk_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
Respuesta
{
  "order": {
    "id": "RP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.97,
    "total_usd": 269.1,
    "status": "pending",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:12:44.120Z"
  },
  "balance_usd": 1030.9
}

Listar tus pedidos

GET/api/v1/ordersClave de API

Devuelve tus últimos 100 pedidos, del más reciente al más antiguo.

CampoSignificado
statusOpcionalpending, active o refunded. Omítelo para obtener todos.
Solicitud
curl "https://royalproxy.online/api/v1/orders?status=pending" \
  -H "Authorization: Bearer rpk_your_api_key"
Respuesta
{
  "orders": [
    {
      "id": "RP-7KQ2M-X4HTD",
      "product": "unlimited",
      "quantity": 30,
      "months": null,
      "concurrency": 1000,
      "bandwidth_mbps": 200,
      "country": null,
      "unit_price_usd": 8.97,
      "total_usd": 269.1,
      "status": "pending",
      "created_at": "2026-10-31T09:12:44.120Z",
      "updated_at": "2026-10-31T09:12:44.120Z"
    }
  ]
}

Obtener un pedido

GET/api/v1/orders/{id}Clave de API

Devuelve un pedido por su id, por ejemplo para comprobar si ya está activo.

CampoSignificado
idObligatorioEl id del pedido, por ejemplo RP-7KQ2M-X4HTD.
Solicitud
curl https://royalproxy.online/api/v1/orders/RP-7KQ2M-X4HTD \
  -H "Authorization: Bearer rpk_your_api_key"
Respuesta
{
  "order": {
    "id": "RP-7KQ2M-X4HTD",
    "product": "unlimited",
    "quantity": 30,
    "months": null,
    "concurrency": 1000,
    "bandwidth_mbps": 200,
    "country": null,
    "unit_price_usd": 8.97,
    "total_usd": 269.1,
    "status": "active",
    "created_at": "2026-10-31T09:12:44.120Z",
    "updated_at": "2026-10-31T09:40:02.511Z"
  }
}

Armar un usuario de proxy

GET/api/v1/proxy-userClave de API

Devuelve un usuario del proxy con tus opciones y URL de proxy HTTP y SOCKS5 listas para usar. Sin session, la IP rota en cada solicitud.

CampoSignificado
productOpcionalunlimited, residential, isp o datacenter. Por defecto unlimited.
countryOpcionalCódigo de país de dos letras, por ejemplo jp.
cityOpcionalValor de ciudad de /countries, por ejemplo tokyo. Requiere country.
sessionOpcionalDe 1~32 letras o números cualesquiera. Las solicitudes con la misma session mantienen la misma IP.
ttlOpcionalMinutos que se mantiene la IP de la sesión, 1~60. Por defecto 30.
Solicitud
curl "https://royalproxy.online/api/v1/proxy-user?product=residential&country=jp&city=tokyo&session=job42&ttl=30" \
  -H "Authorization: Bearer rpk_your_api_key"
Respuesta
{
  "username": "rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30",
  "password": "your_password",
  "http": "http://rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.royalproxy.online:6100",
  "socks5": "socks5h://rpexample1-zone-res-cc-jp-city-tokyo-sid-job42-ttl-30:your_password@gate.royalproxy.online:6200"
}

Ejemplos completos

Estos ejemplos consultan el precio, hacen un pedido con el saldo y se conectan a través de una IP de Japón.

Python (requests)
import requests

API = "https://royalproxy.online/api/v1"
HEAD = {"Authorization": "Bearer rpk_your_api_key"}

# 1) Check the price first
plan = {"product": "residential", "quantity": 100}
print(requests.post(f"{API}/quote", json=plan).json())

# 2) Order from your balance
r = requests.post(f"{API}/orders", json=plan, headers=HEAD)
order = r.json()["order"]
print(order["id"], order["status"])

# 3) Get a username for Japanese IPs
u = requests.get(f"{API}/proxy-user", headers=HEAD,
                 params={"product": "residential", "country": "jp"}).json()
proxies = {"http": u["http"], "https": u["http"]}
print(requests.get("https://ipinfo.io/json", proxies=proxies, timeout=30).json())
Node.js 18+
const API = "https://royalproxy.online/api/v1";
const HEAD = { Authorization: "Bearer rpk_your_api_key", "Content-Type": "application/json" };

// Check the balance
const acc = await fetch(`${API}/account`, { headers: HEAD }).then((r) => r.json());
console.log(acc.balance_usd);

// Order 7 days of unlimited
const res = await fetch(`${API}/orders`, {
  method: "POST",
  headers: HEAD,
  body: JSON.stringify({ product: "unlimited", quantity: 7, concurrency: 500, bandwidth: 100 }),
});
if (res.status === 402) console.log("Top up first");
else console.log((await res.json()).order.id);

Los pedidos hechos por la API son iguales a los del panel y aparecen en History. Sustituye rpk_your_api_key por tu propia clave.

Conecta RoyalProxy a tu propio sistema

Crea una cuenta y luego genera una clave de API en el panel.

Crear una cuentaConfiguración