Proxy API Docs: Orders, Balance and Usernames

How do I start?

1Sign up and log in to the dashboard.
2Open Connect and create an API key. The full key is shown only once, so copy it to a safe place.
3Send the key in the Authorization header with every request that needs it.
4Call /account to check that the key works, then place orders with /orders.

How does authentication work?

Requests for your own account (account, orders, proxy-user) need an API key. Send it as a Bearer token in the Authorization header. Prices, countries and quotes are public and need no key.

We store only a hash of the key. If you lose it, create a new one in the dashboard and the old key stops working at once. Keep the key out of browser code and public repositories.

HTTP header

Authorization: Bearer rpk_your_api_key

Base URL and format

Base URL: https://royalproxy.online/api/v1
Request and response body: application/json
Money: USD numbers, for example 807.90
Time: ISO 8601 (UTC)

Is there a rate limit?

Each API key can send up to 60 requests per minute. Public endpoints allow 60 requests per minute per IP. Above the limit you get HTTP 429, so wait a minute and try again.

What do errors look like?

Errors use the HTTP status code and a JSON body with a short code and a message.

Example

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

HTTP	code	Meaning
400	bad_requestHTTP 400A value is missing or not allowed for this product.	A value is missing or not allowed for this product.
401	unauthorizedHTTP 401The API key is missing or not valid.	The API key is missing or not valid.
402	insufficient_balanceHTTP 402The balance is lower than the order total. Nothing was charged.	The balance is lower than the order total. Nothing was charged.
404	not_foundHTTP 404No order with this id on your account.	No order with this id on your account.
429	rate_limitedHTTP 429Too many requests in one minute.	Too many requests in one minute.
500	server_errorHTTP 500The request could not be completed. Nothing was charged.	The request could not be completed. Nothing was charged.

Endpoints

Get your account

GET/api/v1/accountAPI key

Returns your balance, proxy host, ports, username and password, and allowed IPs.

Request

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

Response

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

List products and prices

GET/api/v1/productsNo key needed

Returns every product with its limits, price tiers and discounts. Prices come from the same table as the pricing page.

Request

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

Response

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

List countries and cities

GET/api/v1/countriesNo key needed

Returns the countries available for a product, with the city values you can put in the proxy username.

Field	Type	Meaning
`product`Optional	string	unlimited, residential, isp or datacenter. Default residential.

Request

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

Response

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

Get a price quote

POST/api/v1/quoteNo key needed

Calculates the total for an order without charging anything. Use the same body as for placing an order.

Field	Type	Meaning
`product`Required	string	unlimited, residential, isp or datacenter.
`quantity`Required	integer	Days for unlimited (1~365), GB for residential (5~5,000), IPs for isp (1~1,000) or datacenter (5~5,000).
`concurrency`Optional	integer	Unlimited only: 200, 500, 1000 or 2000.
`bandwidth`Optional	integer	Unlimited only, in Mbps: 100, 200, 500 or 1000.
`months`Optional	integer	isp and datacenter only: 1, 3, 6 or 12.
`country`Optional	string	isp and datacenter only: two-letter country code, for example jp. See /countries.

Request

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

Response

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

Place an order

POST/api/v1/ordersAPI key

Takes the total from your balance and creates the order. New orders start as pending (activating) and change to active when ready. If an order cannot be activated it becomes refunded and the full amount returns to your balance. Returns 402 when the balance is too low.

Field	Type	Meaning
`product`Required	string	unlimited, residential, isp or datacenter.
`quantity`Required	integer	Days for unlimited (1~365), GB for residential (5~5,000), IPs for isp (1~1,000) or datacenter (5~5,000).
`concurrency`Optional	integer	Unlimited only: 200, 500, 1000 or 2000.
`bandwidth`Optional	integer	Unlimited only, in Mbps: 100, 200, 500 or 1000.
`months`Optional	integer	isp and datacenter only: 1, 3, 6 or 12.
`country`Optional	string	isp and datacenter only: two-letter country code, for example jp. See /countries.

Request

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

Response

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

List your orders

GET/api/v1/ordersAPI key

Returns your latest 100 orders, newest first.

Field	Type	Meaning
`status`Optional	string	pending, active or refunded. Leave it out to get all.

Request

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

Response

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

Get one order

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

Returns one order by its id, for example to check whether it is active.

Field	Type	Meaning
`id`Required	string	The order id, for example RP-7KQ2M-X4HTD.

Request

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

Response

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

Build a proxy username

GET/api/v1/proxy-userAPI key

Returns a proxy username with your options plus ready HTTP and SOCKS5 proxy URLs. Without session the IP rotates on every request.

Field	Type	Meaning
`product`Optional	string	unlimited, residential, isp or datacenter. Default unlimited.
`country`Optional	string	Two-letter country code, for example jp.
`city`Optional	string	City value from /countries, for example tokyo. Needs country.
`session`Optional	string	Any 1~32 letters or numbers. Requests with the same session keep the same IP.
`ttl`Optional	integer	Minutes to keep the session IP, 1~60. Default 30.

Request

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"

Response

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

Full examples

These examples check the price, order from the balance and connect through a Japanese IP.

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

Orders placed through the API are the same as orders from the dashboard and appear in History. Replace rpk_your_api_key with your own key.

Proxy API documentation

How do I start?

How does authentication work?

Base URL and format

Is there a rate limit?

What do errors look like?

Get your account

List products and prices

List countries and cities

Get a price quote

Place an order

List your orders

Get one order

Build a proxy username

Full examples

Connect RoyalProxy to your own system