API proxy: ordini, saldo e nomi utente

Come inizio?

1Registrati e accedi alla dashboard.
2Apri Connetti e crea una chiave API. La chiave completa viene mostrata una sola volta, quindi copiala in un posto sicuro.
3Invia la chiave nell'header Authorization con ogni richiesta che la richiede.
4Chiama /account per verificare che la chiave funzioni, poi fai ordini con /orders.

Come funziona l'autenticazione?

Le richieste sul tuo account (account, orders, proxy-user) richiedono una chiave API. Inviala come token Bearer nell'header Authorization. Prezzi, paesi e preventivi sono pubblici e non richiedono chiave.

Conserviamo solo un hash della chiave. Se la perdi, creane una nuova nella dashboard e la vecchia smette subito di funzionare. Non mettere la chiave nel codice del browser o in repository pubblici.

HTTP header

Authorization: Bearer rpk_your_api_key

URL base e formato

URL di base: https://royalproxy.online/api/v1
Corpo di richiesta e risposta: application/json
Importi: Numeri in USD, ad esempio 807.90
Orario: ISO 8601 (UTC)

C'è un limite di chiamate?

Ogni chiave API può inviare fino a 60 richieste al minuto. Gli endpoint pubblici permettono 60 richieste al minuto per IP. Oltre il limite ricevi HTTP 429: aspetta un minuto e riprova.

Come sono fatti gli errori?

Gli errori usano il codice di stato HTTP e un corpo JSON con un codice breve e un messaggio.

Esempio

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

HTTP	code	Significato
400	bad_requestHTTP 400Manca un valore o non è consentito per questo prodotto.	Manca un valore o non è consentito per questo prodotto.
401	unauthorizedHTTP 401La chiave API manca o non è valida.	La chiave API manca o non è valida.
402	insufficient_balanceHTTP 402Il saldo è inferiore al totale dell'ordine. Non è stato addebitato nulla.	Il saldo è inferiore al totale dell'ordine. Non è stato addebitato nulla.
404	not_foundHTTP 404Nessun ordine con questo id sul tuo account.	Nessun ordine con questo id sul tuo account.
429	rate_limitedHTTP 429Troppe richieste in un minuto.	Troppe richieste in un minuto.
500	server_errorHTTP 500Non è stato possibile completare la richiesta. Non è stato addebitato nulla.	Non è stato possibile completare la richiesta. Non è stato addebitato nulla.

Endpoint

Dati dell'account

GET/api/v1/accountChiave API

Restituisce saldo, host del proxy, porte, nome utente e password, e IP autorizzati.

Richiesta

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

Risposta

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

Elenco di prodotti e prezzi

GET/api/v1/productsNessuna chiave necessaria

Restituisce ogni prodotto con limiti, fasce di prezzo e sconti. I prezzi vengono dalla stessa tabella della pagina dei prezzi.

Richiesta

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

Risposta

{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

Elenca paesi e città

GET/api/v1/countriesNessuna chiave necessaria

Restituisce i paesi disponibili per un prodotto, con i valori delle città da inserire nel nome utente del proxy.

Campo	Tipo	Significato
`product`Facoltativo	string	unlimited, residential, isp o datacenter. Predefinito residential.

Richiesta

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

Risposta

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

Ottieni un preventivo

POST/api/v1/quoteNessuna chiave necessaria

Calcola il totale di un ordine senza addebitare nulla. Usa lo stesso corpo della richiesta di ordine.

Campo	Tipo	Significato
`product`Obbligatorio	string	unlimited, residential, isp o datacenter.
`quantity`Obbligatorio	integer	Giorni per unlimited (1~365), GB per residential (5~5,000), IP per isp (1~1,000) o datacenter (5~5,000).
`concurrency`Facoltativo	integer	Solo unlimited: 200, 500, 1000 o 2000.
`bandwidth`Facoltativo	integer	Solo unlimited, in Mbps: 100, 200, 500 o 1000.
`months`Facoltativo	integer	Solo isp e datacenter: 1, 3, 6 o 12.
`country`Facoltativo	string	Solo isp e datacenter: codice paese di due lettere, ad esempio jp. Vedi /countries.

Richiesta

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

Risposta

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

Effettua un ordine

POST/api/v1/ordersChiave API

Scala il totale dal saldo e crea l'ordine. I nuovi ordini partono come pending (in attivazione) e passano ad active quando sono pronti. Se un ordine non può essere attivato diventa refunded e l'intero importo torna sul saldo. Restituisce 402 se il saldo è insufficiente.

Campo	Tipo	Significato
`product`Obbligatorio	string	unlimited, residential, isp o datacenter.
`quantity`Obbligatorio	integer	Giorni per unlimited (1~365), GB per residential (5~5,000), IP per isp (1~1,000) o datacenter (5~5,000).
`concurrency`Facoltativo	integer	Solo unlimited: 200, 500, 1000 o 2000.
`bandwidth`Facoltativo	integer	Solo unlimited, in Mbps: 100, 200, 500 o 1000.
`months`Facoltativo	integer	Solo isp e datacenter: 1, 3, 6 o 12.
`country`Facoltativo	string	Solo isp e datacenter: codice paese di due lettere, ad esempio jp. Vedi /countries.

Richiesta

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

Risposta

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

Elenco dei tuoi ordini

GET/api/v1/ordersChiave API

Restituisce i tuoi ultimi 100 ordini, dal più recente.

Campo	Tipo	Significato
`status`Facoltativo	string	pending, active o refunded. Omettilo per vederli tutti.

Richiesta

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

Risposta

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

Dettagli di un ordine

GET/api/v1/orders/{id}Chiave API

Restituisce un ordine tramite il suo id, ad esempio per verificare se è attivo.

Campo	Tipo	Significato
`id`Obbligatorio	string	L'id dell'ordine, ad esempio RP-7KQ2M-X4HTD.

Richiesta

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

Risposta

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

Crea un nome utente proxy

GET/api/v1/proxy-userChiave API

Restituisce un nome utente del proxy con le tue opzioni e gli URL del proxy HTTP e SOCKS5 pronti. Senza session l'IP ruota a ogni richiesta.

Campo	Tipo	Significato
`product`Facoltativo	string	unlimited, residential, isp o datacenter. Predefinito unlimited.
`country`Facoltativo	string	Codice paese di due lettere, ad esempio jp.
`city`Facoltativo	string	Valore della città da /countries, ad esempio tokyo. Richiede country.
`session`Facoltativo	string	Da 1 a 32 lettere o numeri a scelta. Le richieste con la stessa session mantengono lo stesso IP.
`ttl`Facoltativo	integer	Minuti per cui mantenere l'IP della sessione, 1~60. Predefinito 30.

Richiesta

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"

Risposta

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

Esempi completi

Questi esempi controllano il prezzo, ordinano dal saldo e si connettono tramite un IP giapponese.

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

Gli ordini fatti tramite API sono uguali a quelli dalla dashboard e compaiono in Cronologia. Sostituisci rpk_your_api_key con la tua chiave.

Documentazione API dei proxy

Come inizio?

Come funziona l'autenticazione?

URL base e formato

C'è un limite di chiamate?

Come sono fatti gli errori?

Dati dell'account

Elenco di prodotti e prezzi

Elenca paesi e città

Ottieni un preventivo

Effettua un ordine

Elenco dei tuoi ordini

Dettagli di un ordine

Crea un nome utente proxy

Esempi completi

Collega RoyalProxy al tuo sistema