Chuyển đến nội dung
royalproxy
Bắt đầu

Tài liệu API proxy

Dùng REST API của RoyalProxy để đọc số dư và thông tin kết nối, xem giá, đặt hàng từ số dư và tạo tên người dùng proxy từ code của bạn.

Tạo khóa APIXem các endpoint

Bắt đầu thế nào?

  1. 1Đăng ký và đăng nhập vào bảng điều khiển.
  2. 2Mở mục Connect và tạo khóa API. Khóa đầy đủ chỉ hiện một lần, nên hãy sao chép và cất ở nơi an toàn.
  3. 3Gửi khóa trong header Authorization với mọi yêu cầu cần đến nó.
  4. 4Gọi /account để kiểm tra khóa hoạt động, rồi đặt hàng bằng /orders.

Xác thực hoạt động thế nào?

Các yêu cầu cho tài khoản của bạn (account, orders, proxy-user) cần khóa API. Gửi khóa dưới dạng Bearer token trong header Authorization. Giá, quốc gia và báo giá là công khai, không cần khóa.

Chúng tôi chỉ lưu mã băm của khóa. Nếu làm mất, hãy tạo khóa mới trong bảng điều khiển, khóa cũ sẽ ngừng hoạt động ngay. Đừng đặt khóa trong code chạy trên trình duyệt hay kho code công khai.

HTTP header
Authorization: Bearer rpk_your_api_key

Base URL và định dạng

Base URL
https://royalproxy.online/api/v1
Nội dung yêu cầu và phản hồi
application/json
Tiền
Số USD, ví dụ 807.90
Thời gian
ISO 8601 (UTC)

Có giới hạn tần suất gọi không?

Mỗi khóa API gửi được tối đa 60 yêu cầu mỗi phút. Endpoint công khai cho phép 60 yêu cầu mỗi phút cho mỗi IP. Vượt giới hạn sẽ nhận HTTP 429, hãy đợi một phút rồi thử lại.

Lỗi trông như thế nào?

Lỗi trả về mã trạng thái HTTP và phần thân JSON gồm một mã ngắn và thông báo.

Ví dụ
{
  "error": {
    "code": "insufficient_balance",
    "message": "Your balance is too low for this order. Top up in the dashboard."
  }
}
code
bad_requestHTTP 400Thiếu giá trị hoặc giá trị không được phép cho sản phẩm này.
unauthorizedHTTP 401Thiếu khóa API hoặc khóa không hợp lệ.
insufficient_balanceHTTP 402Số dư thấp hơn tổng đơn hàng. Chưa bị trừ tiền.
not_foundHTTP 404Không có đơn hàng với id này trong tài khoản của bạn.
rate_limitedHTTP 429Quá nhiều yêu cầu trong một phút.
server_errorHTTP 500Không thể hoàn tất yêu cầu. Chưa bị trừ tiền.

Endpoint

Lấy thông tin tài khoản

GET/api/v1/accountKhóa API

Trả về số dư, host proxy, cổng, tên người dùng, mật khẩu và các IP được phép.

Yêu cầu
curl https://royalproxy.online/api/v1/account \
  -H "Authorization: Bearer rpk_your_api_key"
Phản hồi
{
  "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"
  ]
}

Danh sách sản phẩm và giá

GET/api/v1/productsKhông cần khóa

Trả về mọi sản phẩm cùng giới hạn, các mức giá và giảm giá. Giá lấy từ cùng bảng với trang bảng giá.

Yêu cầu
curl https://royalproxy.online/api/v1/products
Phản hồi
{
  "currency": "USD",
  "prices_as_of": "2026-10-31",
  "products": [
    {
      "id": "unlimited",
      "unit": "day",
      "quantity": {
        "meaning": "days",
        "min": 1,
        "max": 365
      },
      "...": "..."
    },
    {
      "id": "residential",
      "unit": "gb",
      "...": "..."
    }
  ]
}

Danh sách quốc gia và thành phố

GET/api/v1/countriesKhông cần khóa

Trả về các quốc gia có sẵn cho một sản phẩm, kèm giá trị thành phố bạn có thể đặt vào tên người dùng proxy.

TrườngÝ nghĩa
productKhông bắt buộcunlimited, residential, isp hoặc datacenter. Mặc định là residential.
Yêu cầu
curl "https://royalproxy.online/api/v1/countries?product=datacenter"
Phản hồi
{
  "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"
        }
      ]
    }
  ]
}

Lấy báo giá

POST/api/v1/quoteKhông cần khóa

Tính tổng tiền cho một đơn hàng mà không trừ tiền. Dùng cùng phần thân như khi đặt hàng.

TrườngÝ nghĩa
productBắt buộcunlimited, residential, isp hoặc datacenter.
quantityBắt buộcSố ngày cho unlimited (1~365), số GB cho residential (5~5,000), số IP cho isp (1~1,000) hoặc datacenter (5~5,000).
concurrencyKhông bắt buộcChỉ cho unlimited: 200, 500, 1000 hoặc 2000.
bandwidthKhông bắt buộcChỉ cho unlimited, đơn vị Mbps: 100, 200, 500 hoặc 1000.
monthsKhông bắt buộcChỉ cho isp và datacenter: 1, 3, 6 hoặc 12.
countryKhông bắt buộcChỉ cho isp và datacenter: mã quốc gia hai chữ cái, ví dụ jp. Xem /countries.
Yêu cầu
curl -X POST https://royalproxy.online/api/v1/quote \
  -H "Content-Type: application/json" \
  -d '{"product":"unlimited","quantity":30,"concurrency":1000,"bandwidth":200}'
Phản hồi
{
  "product": "unlimited",
  "quantity": 30,
  "unit_price_usd": 8.97,
  "unit": "day",
  "total_usd": 269.1
}

Đặt hàng

POST/api/v1/ordersKhóa API

Trừ tổng tiền từ số dư và tạo đơn hàng. Đơn mới bắt đầu ở trạng thái pending (đang kích hoạt) và chuyển sang active khi sẵn sàng. Nếu không kích hoạt được, đơn chuyển sang refunded và toàn bộ số tiền được hoàn về số dư. Trả về 402 khi số dư không đủ.

TrườngÝ nghĩa
productBắt buộcunlimited, residential, isp hoặc datacenter.
quantityBắt buộcSố ngày cho unlimited (1~365), số GB cho residential (5~5,000), số IP cho isp (1~1,000) hoặc datacenter (5~5,000).
concurrencyKhông bắt buộcChỉ cho unlimited: 200, 500, 1000 hoặc 2000.
bandwidthKhông bắt buộcChỉ cho unlimited, đơn vị Mbps: 100, 200, 500 hoặc 1000.
monthsKhông bắt buộcChỉ cho isp và datacenter: 1, 3, 6 hoặc 12.
countryKhông bắt buộcChỉ cho isp và datacenter: mã quốc gia hai chữ cái, ví dụ jp. Xem /countries.
Yêu cầu
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}'
Phản hồi
{
  "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
}

Danh sách đơn hàng

GET/api/v1/ordersKhóa API

Trả về 100 đơn hàng gần nhất, mới nhất trước.

TrườngÝ nghĩa
statusKhông bắt buộcpending, active hoặc refunded. Bỏ trống để lấy tất cả.
Yêu cầu
curl "https://royalproxy.online/api/v1/orders?status=pending" \
  -H "Authorization: Bearer rpk_your_api_key"
Phản hồi
{
  "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"
    }
  ]
}

Lấy một đơn hàng

GET/api/v1/orders/{id}Khóa API

Trả về một đơn hàng theo id, ví dụ để kiểm tra đơn đã active chưa.

TrườngÝ nghĩa
idBắt buộcId đơn hàng, ví dụ RP-7KQ2M-X4HTD.
Yêu cầu
curl https://royalproxy.online/api/v1/orders/RP-7KQ2M-X4HTD \
  -H "Authorization: Bearer rpk_your_api_key"
Phản hồi
{
  "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"
  }
}

Tạo tên người dùng proxy

GET/api/v1/proxy-userKhóa API

Trả về tên người dùng proxy với các tùy chọn của bạn, kèm URL proxy HTTP và SOCKS5 dùng được ngay. Không có session thì IP xoay vòng mỗi yêu cầu.

TrườngÝ nghĩa
productKhông bắt buộcunlimited, residential, isp hoặc datacenter. Mặc định là unlimited.
countryKhông bắt buộcMã quốc gia hai chữ cái, ví dụ jp.
cityKhông bắt buộcGiá trị thành phố từ /countries, ví dụ tokyo. Cần có country.
sessionKhông bắt buộc1~32 chữ cái hoặc chữ số bất kỳ. Các yêu cầu có cùng session giữ cùng một IP.
ttlKhông bắt buộcSố phút giữ IP của phiên, 1~60. Mặc định 30.
Yêu cầu
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"
Phản hồi
{
  "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"
}

Ví dụ đầy đủ

Các ví dụ này kiểm tra giá, đặt hàng từ số dư và kết nối qua một IP Nhật Bả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);

Đơn đặt qua API giống hệt đơn đặt từ bảng điều khiển và hiện trong mục History. Thay rpk_your_api_key bằng khóa của bạn.

Kết nối RoyalProxy với hệ thống của bạn

Tạo tài khoản, rồi tạo khóa API trong bảng điều khiển.

Tạo tài khoảnHướng dẫn cài đặt