API de proxy: pedidos, saldo e usuários

Como começo?

1Crie uma conta e entre no painel.
2Abra Connect e crie uma chave de API. A chave completa aparece só uma vez, então copie para um lugar seguro.
3Envie a chave no cabeçalho Authorization em toda requisição que precisar dela.
4Chame /account para confirmar que a chave funciona e depois faça pedidos com /orders.

Como funciona a autenticação?

Requisições da sua própria conta (account, orders, proxy-user) precisam de uma chave de API. Envie como token Bearer no cabeçalho Authorization. Preços, países e cotações são públicos e não precisam de chave.

Guardamos só um hash da chave. Se você perder, crie uma nova no painel e a chave antiga para de funcionar na hora. Não coloque a chave em código de navegador nem em repositórios públicos.

HTTP header

Authorization: Bearer rpk_your_api_key

URL base e formato

URL base: https://royalproxy.online/api/v1
Corpo da requisição e da resposta: application/json
Valores: Números em USD, por exemplo 807.90
Horário: ISO 8601 (UTC)

Há limite de chamadas?

Cada chave de API pode enviar até 60 requisições por minuto. Endpoints públicos permitem 60 requisições por minuto por IP. Acima do limite você recebe HTTP 429; espere um minuto e tente de novo.

Como são os erros?

Os erros usam o código de status HTTP e um corpo JSON com um código curto e uma mensagem.

Exemplo

{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}

HTTP	code	Significado
400	bad_requestHTTP 400Falta um valor ou ele não é permitido para este produto.	Falta um valor ou ele não é permitido para este produto.
401	unauthorizedHTTP 401A chave de API está ausente ou não é válida.	A chave de API está ausente ou não é válida.
402	insufficient_balanceHTTP 402O saldo é menor que o total do pedido. Nada foi cobrado.	O saldo é menor que o total do pedido. Nada foi cobrado.
404	not_foundHTTP 404Não há pedido com este id na sua conta.	Não há pedido com este id na sua conta.
429	rate_limitedHTTP 429Requisições demais em um minuto.	Requisições demais em um minuto.
500	server_errorHTTP 500Não foi possível concluir a requisição. Nada foi cobrado.	Não foi possível concluir a requisição. Nada foi cobrado.

Endpoints

Consultar sua conta

GET/api/v1/accountChave de API

Retorna seu saldo, host do proxy, portas, usuário e senha, e IPs permitidos.

Requisição

curl https://royalproxy.online/api/v1/account \
  -H "Authorization: Bearer rpk_your_api_key"

Resposta

{
  "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 produtos e preços

GET/api/v1/productsNão precisa de chave

Retorna todos os produtos com seus limites, faixas de preço e descontos. Os preços vêm da mesma tabela da página de preços.

Requisição

curl https://royalproxy.online/api/v1/products

Resposta

{
  "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 e cidades

GET/api/v1/countriesNão precisa de chave

Retorna os países disponíveis para um produto, com os valores de cidade que você pode colocar no usuário do proxy.

Campo	Tipo	Significado
`product`Opcional	string	unlimited, residential, isp ou datacenter. Padrão: residential.

Requisição

curl "https://royalproxy.online/api/v1/countries?product=datacenter"

Resposta

{
  "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"
        }
      ]
    }
  ]
}

Obter uma cotação

POST/api/v1/quoteNão precisa de chave

Calcula o total de um pedido sem cobrar nada. Use o mesmo corpo de quando faz um pedido.

Campo	Tipo	Significado
`product`Obrigatório	string	unlimited, residential, isp ou datacenter.
`quantity`Obrigatório	integer	Dias para unlimited (1~365), GB para residential (5~5,000), IPs para isp (1~1,000) ou datacenter (5~5,000).
`concurrency`Opcional	integer	Só para unlimited: 200, 500, 1000 ou 2000.
`bandwidth`Opcional	integer	Só para unlimited, em Mbps: 100, 200, 500 ou 1000.
`months`Opcional	integer	Só para isp e datacenter: 1, 3, 6 ou 12.
`country`Opcional	string	Só para isp e datacenter: código de país de duas letras, por exemplo jp. Veja /countries.

Requisição

curl -X POST https://royalproxy.online/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'

Resposta

{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.97,
  "unit": "day",
  "total_usd": 269.1
}

Fazer um pedido

POST/api/v1/ordersChave de API

Desconta o total do seu saldo e cria o pedido. Pedidos novos começam como pending (ativando) e mudam para active quando ficam prontos. Se um pedido não puder ser ativado, ele passa a refunded e o valor total volta para o seu saldo. Retorna 402 quando o saldo é insuficiente.

Campo	Tipo	Significado
`product`Obrigatório	string	unlimited, residential, isp ou datacenter.
`quantity`Obrigatório	integer	Dias para unlimited (1~365), GB para residential (5~5,000), IPs para isp (1~1,000) ou datacenter (5~5,000).
`concurrency`Opcional	integer	Só para unlimited: 200, 500, 1000 ou 2000.
`bandwidth`Opcional	integer	Só para unlimited, em Mbps: 100, 200, 500 ou 1000.
`months`Opcional	integer	Só para isp e datacenter: 1, 3, 6 ou 12.
`country`Opcional	string	Só para isp e datacenter: código de país de duas letras, por exemplo jp. Veja /countries.

Requisição

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}'

Resposta

{
  "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 seus pedidos

GET/api/v1/ordersChave de API

Retorna seus últimos 100 pedidos, do mais recente para o mais antigo.

Campo	Tipo	Significado
`status`Opcional	string	pending, active ou refunded. Omita para receber todos.

Requisição

curl "https://royalproxy.online/api/v1/orders?status=pending" \
  -H "Authorization: Bearer rpk_your_api_key"

Resposta

{
  "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"
    }
  ]
}

Consultar um pedido

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

Retorna um pedido pelo id, por exemplo para verificar se está ativo.

Campo	Tipo	Significado
`id`Obrigatório	string	O id do pedido, por exemplo RP-7KQ2M-X4HTD.

Requisição

curl https://royalproxy.online/api/v1/orders/RP-7KQ2M-X4HTD \
  -H "Authorization: Bearer rpk_your_api_key"

Resposta

{
  "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"
  }
}

Montar um usuário de proxy

GET/api/v1/proxy-userChave de API

Retorna um usuário do proxy com suas opções e URLs de proxy HTTP e SOCKS5 prontas. Sem session, o IP rotaciona a cada requisição.

Campo	Tipo	Significado
`product`Opcional	string	unlimited, residential, isp ou datacenter. Padrão: unlimited.
`country`Opcional	string	Código de país de duas letras, por exemplo jp.
`city`Opcional	string	Valor de cidade de /countries, por exemplo tokyo. Exige country.
`session`Opcional	string	Qualquer combinação de 1~32 letras ou números. Requisições com a mesma session mantêm o mesmo IP.
`ttl`Opcional	integer	Minutos para manter o IP da sessão, 1~60. Padrão: 30.

Requisição

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"

Resposta

{
  "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"
}

Exemplos completos

Estes exemplos consultam o preço, fazem um pedido com o saldo e conectam por um IP do Japão.

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);

Pedidos feitos pela API são iguais aos pedidos feitos no painel e aparecem no Histórico. Substitua rpk_your_api_key pela sua própria chave.

Documentação da API de proxy

Como começo?

Como funciona a autenticação?

URL base e formato

Há limite de chamadas?

Como são os erros?

Consultar sua conta

Listar produtos e preços

Listar países e cidades

Obter uma cotação

Fazer um pedido

Listar seus pedidos

Consultar um pedido

Montar um usuário de proxy

Exemplos completos

Conecte a RoyalProxy ao seu próprio sistema