Reseller API

Sell NobleProxy dedicated static residential proxies and rotating residential proxies under your own brand, at your own prices, inside your own app. You buy at NobleProxy's public prices from your account balance, and the API returns ready-to-use proxy credentials for your customers.

New to reselling? Read how to start a proxy business, the proxy reseller program overview and the white label setup for your own proxy hostname.

Quick start

1. Sign in at nobleproxy.com/dashboard and add balance (crypto top-up).
2. In the dashboard, open Reseller API and click Create API key. Copy the key; it is shown once.
3. Call the API:

curl https://nobleproxy.com/api/v1/products \
  -H "Authorization: Bearer np_your_api_key"

Basics

• Base URL: https://nobleproxy.com/api/v1
• Authentication: send Authorization: Bearer with every request. A missing or wrong key returns 401. Creating a new key in the dashboard disables the old one at once.
• Format: JSON requests and responses. Send Content-Type: application/json on POST and PATCH.
• Money: all amounts are integers in US cents (1750 = $17.50).
• Billing: every order and renewal is paid from your NobleProxy balance at public prices. You set the price your customers pay.
• Keep your key on your server. Never put it in a browser or mobile app.

Errors

Errors return a non-2xx status and { "error": "message" }.

Products

Two products are available.

• static: dedicated static residential proxies. Each proxy is a fixed IP with unlimited traffic. You choose a type (the platform the proxies are for) and a country. Quantity 1 to 1000. The price per proxy falls as quantity rises.
• residential: rotating residential proxies. One gateway with a new home IP on every request, from millions of IPs worldwide. Sold in monthly GB packages: 1, 5, 10, 15, 20, 30, 50 or 100 GB. Unused GB do not carry over to the next month.

GET /products

Returns the catalog with prices, types and the countries in stock.

{
  "static": {
    "description": "Dedicated static residential proxies, unlimited traffic, priced per proxy per month",
    "minQuantity": 1,
    "maxQuantity": 1000,
    "priceTiers": [
      { "minQuantity": 1, "unitPriceCents": 356 },
      { "minQuantity": 5, "unitPriceCents": 355 }
    ],
    "types": [
      {
        "type": "instagram-12",
        "label": "Instagram",
        "countries": [{ "code": "US", "name": "United States" }, { "code": "ANY", "name": "Any" }]
      }
    ]
  },
  "residential": {
    "description": "Rotating residential proxies, a new IP per request, priced per GB package per month",
    "packages": [{ "gb": 1, "priceCents": 400 }, { "gb": 5, "priceCents": 1750 }]
  }
}

Static price: find the last tier whose minQuantity is at most your quantity. The order costs quantity × unitPriceCents. For example, 10 proxies at 355 cents cost 3550 cents.

Residential price: the package's priceCents.

Countries can be sent as the ISO code or the name. Stock changes, so read the catalog again before you show options to your customers (it is cached for up to 5 minutes).

Balance

GET /balance

{ "balanceCents": 12500 }

Add balance in the dashboard with a crypto top-up. Your balance also pays renewals.

Orders

An order is one purchase: a set of static proxies or one rotating GB package. It lasts 30 days and renews automatically from your balance unless you turn renewal off.

POST /orders

Buys proxies. The cost is taken from your balance and the proxies are returned at once.

Static example:

curl -X POST https://nobleproxy.com/api/v1/orders \
  -H "Authorization: Bearer np_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"static","type":"instagram-12","country":"US","quantity":5,"label":"customer-481","idempotencyKey":"order-9f2c"}'

Residential example:

curl -X POST https://nobleproxy.com/api/v1/orders \
  -H "Authorization: Bearer np_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{"product":"residential","quantity":10,"label":"customer-482"}'

Response (an order with its proxies):

{
  "id": "6aef0c1de0d37f93b5f27101",
  "product": "residential",
  "label": "customer-482",
  "status": "active",
  "quantity": 10,
  "unit": "GB",
  "autoRenew": true,
  "renewalPriceCents": 3000,
  "paidUntil": "2026-12-07T10:00:00.000Z",
  "createdAt": "2026-11-07T10:00:00.000Z",
  "expiresAt": "2026-12-07T10:00:00.000Z",
  "proxies": [
    { "host": "gate.nobleproxy.com", "port": 8888, "username": "ab12c", "password": "secret", "protocol": "http" }
  ]
}

Static orders also include purposeId and country. A static order has one entry in proxies per IP.

New proxies start working within a few minutes (static IPs can take up to 5 minutes, also after a swap).

If your balance is too low the response is 402 and nothing is charged. If provisioning fails the response is 502, nothing is charged, and you can retry with the same idempotency key.

GET /orders

Lists your orders, newest first, without proxy credentials. Includes orders bought in the dashboard.

Query parameters: limit (1 to 100, default 50) and before (an order id, for the next page). The response has orders and nextBefore (pass it as before to get the next page, or null on the last page).

GET /orders/{id}

Returns one order with its current proxies. Read it again after a swap. status is active, expired (not renewed), failed or pending. expiresAt is when the proxies stop working if the order is not renewed.

PATCH /orders/{id}

Turns automatic renewal on or off.

{ "autoRenew": false }

With renewal off the proxies keep working until the end of the paid period, then stop.

POST /orders/{id}/renew

Renews now: charges the renewal price to your balance and adds 30 days to the paid period. Returns the order. Use it if you manage renewals yourself (with autoRenew off) or to extend early. A low balance returns 402.

Rotating residential orders can be renewed this way only while autoRenew is on (otherwise 422); the payment then covers the next month in advance.

POST /orders/{id}/swap

Static orders only. Replaces the order's IPs with new ones, using its free swaps. Returns the order with the new proxies. If no free swaps are left the response is 422.

Using the proxies

Every proxy is an HTTP proxy with username and password authentication:

http://USERNAME:PASSWORD@HOST:PORT

curl -x http://USERNAME:PASSWORD@HOST:PORT https://api.ipify.org

Rotating residential: each request gets a new IP. To choose a country, add -cc- and the two-letter country code to the username. For example, username ab12c-cc-us gives US IPs and ab12c-cc-de gives German IPs. Without it, the IP can be from any country. Traffic is counted in both directions. When the package's GB are used up, buy another package.

Renewals

• Orders renew every 30 days. With autoRenew on, the renewal price is taken from your balance on the renewal date.
• If your balance is too low, the renewal is retried while you top up. If it is not paid by the end of the period, the proxies stop.
• Static renewals keep the same IPs. Rotating renewals keep the same username and password and start a fresh GB allowance.
• To stop selling an order, turn autoRenew off.

Integration guide

1. Catalog: call GET /products on your server, add your margin, and show the types, countries and sizes to your customers.
2. Checkout: when your customer pays you, call POST /orders. Use your own order id as idempotencyKey so a retry never buys twice, and put your customer's id in label.
3. Delivery: store the order id and show the proxies to your customer.
4. Lifecycle: when your customer renews or cancels, call POST /orders/{id}/renew or PATCH /orders/{id}. Read GET /orders/{id} to refresh credentials and expiry.
5. Balance: watch GET /balance and top up before renewals are due.

JavaScript example:

const API = "https://nobleproxy.com/api/v1"
const headers = { Authorization: `Bearer ${process.env.NOBLEPROXY_API_KEY}`, "Content-Type": "application/json" }

async function buyResidential(gb, customerOrderId) {
  const res = await fetch(`${API}/orders`, {
    method: "POST",
    headers,
    body: JSON.stringify({ product: "residential", quantity: gb, label: customerOrderId, idempotencyKey: customerOrderId }),
  })
  const body = await res.json()
  if (!res.ok) throw new Error(`${res.status}: ${body.error}`)
  return body // body.proxies[0] has host, port, username, password
}

Python example:

import os, requests

API = "https://nobleproxy.com/api/v1"
HEADERS = {"Authorization": f"Bearer {os.environ['NOBLEPROXY_API_KEY']}"}

def buy_static(type_, country, quantity, customer_order_id):
    res = requests.post(f"{API}/orders", headers=HEADERS, json={
        "product": "static", "type": type_, "country": country, "quantity": quantity,
        "label": customer_order_id, "idempotencyKey": customer_order_id,
    })
    res.raise_for_status()
    return res.json()["proxies"]

Support

Questions or a feature you need? Contact us through the support chat on nobleproxy.com.