NodeProxies · API v1

Reseller API

The NodeProxies API lets approved resellers sell proxies under their own brand. Create plans for your customers, top them up, rotate credentials and track usage from your own website, bot or panel. Everything is billed to your account balance at your reseller rates.

API keys

Scoped to your reseller account

Idempotent

Safe retries on every purchase

IP allowlisting

Lock keys to your servers

Five-minute quickstart

bash
export NODEPROXIES_KEY="np_live_..."

# 1. Check your balance and rates
curl https://nodeproxies.xyz/api/v1/me -H "Authorization: Bearer $NODEPROXIES_KEY"
curl https://nodeproxies.xyz/api/v1/products -H "Authorization: Bearer $NODEPROXIES_KEY"

# 2. Create a 5 GB residential plan for a customer order
curl -X POST https://nodeproxies.xyz/api/v1/plans \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_1042" \
  -d '{"type":"residential","bandwidth_gb":5,"customer_ref":"order_1042"}'

# 3. Hand data.connection.http_url to your customer

Reseller access

API access is only for approved resellers. Apply from your dashboard under Become a reseller. You'll need:

RequirementDetails
DiscordDiscord connected to your account, and you're a member of our server. Reviews and support happen there.
$200 depositedAt least $200 in completed top-ups (lifetime). It stays in your balance to spend on plans.
Launch-ready websiteA live HTTPS site for your proxy brand. We check that it loads when you submit.

Our team reviews applications on Discord, usually within 48 hours. Once you're approved, the Reseller console in your dashboard lets you create API keys, see your rates and watch API activity.

Ready to resell?

Wholesale rates, the full API, and a direct line to the team.

Apply now

Authentication

Send your API key as a Bearer token on every request. Keys start with np_live_. You can also send it in an X-API-Key header.

http
Authorization: Bearer np_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx

Base URL

text
https://nodeproxies.xyz/api/v1
BehaviourDetails
CopyingCopy the full key from your Reseller console anytime. It's stored encrypted and only revealed to you while logged in.
IP allowlistOptionally lock a key to your server IPs. Calls from other IPs get 403 ip_not_allowed.
RevocationRevoking a key, or losing reseller status, blocks it immediately.
Session tokensYour dashboard login token is not accepted by /api/v1.
Keys move money. Keep them on your server (environment variables, secret manager). Never put them in browser code, mobile apps or Discord bots that users can inspect.

Requests & responses

Send JSON request bodies with Content-Type: application/json. Successful responses wrap the result in data. Lists include pagination, and money-moving calls include billing.

json
{
  "data": { ... },
  "billing": { "charged": 2.75, "balance": 247.25 }
}

Errors

Errors share one shape. code is stable, so branch on it. message is written for humans.

json
{
  "error": {
    "code": "insufficient_balance",
    "message": "You need $27.50 but only have $12.00. Please top up and try again.",
    "required": 27.5,
    "available": 12,
    "shortfall": 15.5,
    "request_id": "req_Hk2b9Qx0aLmT"
  }
}

Pagination

List endpoints accept limit (1–100, default 50) and offset.

json
"pagination": { "limit": 50, "offset": 0, "total": 132, "has_more": true }

Headers

HeaderDescription
X-Request-IdUnique id for every request. Include it when contacting support.
X-RateLimit-Limit / -Remaining / -ResetYour current rate-limit window (reset is a Unix timestamp).
Idempotent-Replayedtrue when the response was replayed from a previous Idempotency-Key.

Idempotency

Every endpoint that charges your balance accepts an Idempotency-Key header. Use your own order id. If a request times out, retry with the same key. You'll get the original result back and won't be charged twice.

http
Idempotency-Key: order_1042
SituationResult
Same key, same body (within 24h)The original response is returned with Idempotent-Replayed: true.
Same key, different body422 idempotency_key_reused
Same key while the first call is still running409 idempotency_in_progress. Retry shortly.
First call failed with 5xx / 409 / 429The key is released, so you can retry with it.

Rate limits

ScopeLimit
All requests300 / minute per API key
Write requests (create, top up, delete, reset…)60 / minute per account

Going over returns 429 rate_limited with a Retry-After header. Need more? Ask in your reseller channel on Discord.

Account

GET/meBalance, plan counts and the key in use
cURL
curl https://nodeproxies.xyz/api/v1/me \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": {
    "username": "yourbrand",
    "balance": 247.25,
    "currency": "USD",
    "reseller": { "since": "2026-10-01T09:12:00.000Z", "custom_rates": null },
    "plans": { "active": 38, "total": 112 },
    "api_key": { "id": "0b9c…", "name": "Production server" }
  }
}

Products & your prices

GET/productsEvery plan type with the price you pay
cURL
curl https://nodeproxies.xyz/api/v1/products \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": [
    {
      "type": "residential",
      "name": "Residential",
      "billing": "bandwidth",
      "unit": "GB",
      "price": 0.3,
      "currency": "USD",
      "reseller_rate": true,
      "minimum": { "bandwidth_gb": 1, "bandwidth_mb": 100 },
      "maximum": { "bandwidth_gb": 10000 },
      "volume_tiers": null
    },
    {
      "type": "unlimited_residential",
      "name": "Unlimited Residential",
      "billing": "time",
      "unit": "hour",
      "price": 3,
      "minimum": { "duration_hours": 1 },
      "maximum": { "duration_hours": 8760 },
      "step_hours": 1,
      ...
    }
  ]
}
typeBilled perSize field on create
residentialGBbandwidth_gb or bandwidth_mb
mobileGBbandwidth_gb or bandwidth_mb
unlimited_residentialhourduration_hours (1–8760)
Reseller prices are flat. Promo codes, volume discounts and weekly/monthly discounts don't apply on top. Datacenter plans aren't part of the reseller program, so they're not sold through the API.

Locations

GET/locations?type=residentialTargetable countries, states, cities and carriers

Without type you get every product's country list (iso2 + name). With type you get the full tree. Residential includes states and cities, and mobile includes carriers (ASNs).

cURL
curl "https://nodeproxies.xyz/api/v1/locations?type=residential" \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": [
    {
      "name": "United States",
      "iso2": "US",
      "states": [
        { "name": "New York", "code": "NY1", "cities": [{ "name": "New York City", "code": "NYC1" }] }
      ]
    }
  ]
}

Gateways & server IPs

GET/gatewaysProxy hostnames, ports and the IPs they resolve to

Use this to allowlist our servers in a firewall, or to point your own branded hostname (for example proxy.yourbrand.com) at us with a CNAME. IPs can change, so prefer hostnames or re-fetch this regularly.

cURL
curl https://nodeproxies.xyz/api/v1/gateways \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": [
    {
      "id": "global",
      "region": "Auto (recommended)",
      "standard":  { "host": "global.nodeproxies.xyz",   "ips": ["31.59.160.7"] },
      "unlimited": { "host": "u-global.nodeproxies.xyz", "ips": ["213.193.252.195"] }
    }
  ],
  "ports": { "http": 8080, "socks5": 1080 },
  "all_ips": ["213.193.252.195", "31.59.160.7"],
  "resolved_at": "2026-10-16T08:49:49.901Z"
}
standard gateways serve bandwidth plans, and unlimited gateways serve unlimited plans.

Transactions

GET/transactionsYour wallet ledger, newest first
QueryTypeDescription
typestringdeposit, plan_purchase or plan_update
statusstringcompleted, failed or pending
limit / offsetnumberPagination
cURL
curl "https://nodeproxies.xyz/api/v1/transactions?type=plan_purchase&limit=20" \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": [
    {
      "id": "b7a1…",
      "type": "plan_purchase",
      "amount": 2.75,
      "currency": "USD",
      "status": "completed",
      "description": "Purchased residential plan",
      "plan_id": "6f1c2a8e-…",
      "created_at": "2026-10-15T12:00:00.000Z"
    }
  ],
  "pagination": { "limit": 20, "offset": 0, "total": 87, "has_more": true }
}
Top up your balance from the dashboard (card or crypto). Deposits show up here as deposit.

The plan object

Every plan endpoint returns this shape. Bandwidth plans have bandwidth, and unlimited plans have duration.

json
{
  "id": "6f1c2a8e-3b7d-4c55-9a0e-2d4b1f8c9e10",
  "code": "K7Q2M9XA",
  "type": "residential",
  "status": "active",
  "enabled": true,
  "customer_ref": "order_1042",
  "created_at": "2026-10-15T12:00:00.000Z",
  "expires_at": null,
  "last_used_at": "2026-10-15T12:41:07.000Z",
  "credentials": { "username": "np8f2kq1", "password": "Xq81rPz0" },
  "connection": {
    "host": "global.nodeproxies.xyz",
    "http_port": 8080,
    "socks5_port": 1080,
    "gateways": ["eu-1.nodeproxies.xyz", "eu-2.nodeproxies.xyz", "na.nodeproxies.xyz", "global.nodeproxies.xyz"],
    "http_url": "http://np8f2kq1:[email protected]:8080",
    "socks5_url": "socks5://np8f2kq1:[email protected]:1080"
  },
  "bandwidth": {
    "limit_bytes": 5368709120,
    "used_bytes": 734003200,
    "remaining_bytes": 4634705920,
    "limit_gb": 5,
    "used_gb": 0.6836,
    "remaining_gb": 4.3164,
    "used_percent": 13.7
  },
  "duration": null
}
FieldTypeDescription
idstringPlan UUID. Every :id path parameter also accepts code.
codestringShort human-friendly plan code
typestringresidential, mobile or unlimited_residential
statusstringactive, inactive, completed (bandwidth used up / removed) or expired
customer_refstring | nullYour own reference (order id, customer id…). Filterable.
credentialsobjectProxy username and password
connectionobjectGateway hosts, ports and ready-made proxy URLs
bandwidthobject | nullLimit, used and remaining in bytes and GB (bandwidth plans)
durationobject | nullHours purchased, hours remaining and data used (unlimited plans)

List plans

GET/plansYour plans, newest first, with live usage
QueryTypeDescription
typestringFilter by plan type
statusstringactive or inactive
customer_refstringOnly plans tagged with this reference
syncbooleanDefault true: refreshes usage for the page. Send false for a faster cached read.
limit / offsetnumberPagination (max 100)
cURL
curl "https://nodeproxies.xyz/api/v1/plans?status=active&customer_ref=order_1042" \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{
  "data": [ { "id": "6f1c2a8e-…", "type": "residential", "status": "active", ... } ],
  "pagination": { "limit": 50, "offset": 0, "total": 1, "has_more": false }
}

Create a plan

POST/plansChargesIdempotentProvision a plan, charged to your balance
FieldTypeRequiredDescription
typestringYesresidential, mobile or unlimited_residential
bandwidth_gbnumberBandwidth plans*1–10000 GB
bandwidth_mbintegerBandwidth plans*≥ 100 MB (instead of bandwidth_gb)
duration_hoursintegerUnlimited plans1–8760
usernamestringNoCustom proxy username, 4–32 chars [a-z0-9_], starting with a letter. Must be unique. Random if omitted.
passwordstringNoCustom proxy password, 6–64 chars [A-Za-z0-9_-]. Random if omitted.
customer_refstringNoYour reference, up to 120 chars

* Send exactly one of bandwidth_gb or bandwidth_mb.

Bandwidth plan

cURL
curl -X POST https://nodeproxies.xyz/api/v1/plans \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Idempotency-Key: order_1042" \
  -H "Content-Type: application/json" \
  -d '{"type":"residential","bandwidth_gb":5,"customer_ref":"order_1042"}'

Unlimited plan

cURL
curl -X POST https://nodeproxies.xyz/api/v1/plans \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Idempotency-Key: order_1043" \
  -H "Content-Type: application/json" \
  -d '{"type":"unlimited_residential","duration_hours":24}'

Response · 201 Created

json
{
  "data": { "id": "6f1c2a8e-…", "code": "K7Q2M9XA", "type": "residential", "status": "active", ... },
  "billing": { "charged": 2.75, "balance": 247.25 }
}
If your balance is too low you get 402 insufficient_balance with required, available and shortfall. Nothing is charged. If provisioning fails, the charge is automatically reversed.

Retrieve a plan

GET/plans/:idOne plan with fresh usage. :id is the UUID or code.
cURL
curl https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{ "data": {
    "id": "6f1c2a8e-3b7d-4c55-9a0e-2d4b1f8c9e10",
    "code": "K7Q2M9XA",
    "type": "residential",
    "status": "active",
    "enabled": true,
    "customer_ref": "order_1042",
    "created_at": "2026-10-15T12:00:00.000Z",
    "expires_at": null,
    "last_used_at": "2026-10-15T12:41:07.000Z",
    "credentials": { "username": "np8f2kq1", "password": "Xq81rPz0" },
    "connection": {
      "host": "global.nodeproxies.xyz",
      "http_port": 8080,
      "socks5_port": 1080,
      "gateways": ["eu-1.nodeproxies.xyz", "eu-2.nodeproxies.xyz", "na.nodeproxies.xyz", "global.nodeproxies.xyz"],
      "http_url": "http://np8f2kq1:[email protected]:8080",
      "socks5_url": "socks5://np8f2kq1:[email protected]:1080"
    },
    "bandwidth": {
      "limit_bytes": 5368709120,
      "used_bytes": 734003200,
      "remaining_bytes": 4634705920,
      "limit_gb": 5,
      "used_gb": 0.6836,
      "remaining_gb": 4.3164,
      "used_percent": 13.7
    },
    "duration": null
  } }

Top up a plan

POST/plans/:id/topupChargesIdempotentAdd bandwidth or time to an existing plan
FieldTypePlan typesDescription
bandwidth_gbnumberBandwidth plansGB to add (0.1–10000)
duration_hoursintegerUnlimited plansHours to add (1–8760)
cURL
curl -X POST https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA/topup \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Idempotency-Key: order_1042-topup-1" \
  -H "Content-Type: application/json" \
  -d '{"bandwidth_gb":10}'
json
{
  "data": { "id": "6f1c2a8e-…", "bandwidth": { "limit_gb": 15, ... }, ... },
  "billing": { "charged": 5.5, "balance": 241.75 }
}

Reset proxy password

POST/plans/:id/reset-passwordRotate the proxy password. The old one stops working immediately.
FieldTypeRequiredDescription
passwordstringNo6–64 chars [A-Za-z0-9_-]. Random if omitted.
cURL
curl -X POST https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA/reset-password \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Returns the updated plan object with the new credentials and connection URLs.

Update a plan

PATCH/plans/:idChange metadata (free)
FieldTypeDescription
customer_refstring | nullSet, change or clear (null) your reference
cURL
curl -X PATCH https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA \
  -H "Authorization: Bearer $NODEPROXIES_KEY" \
  -H "Content-Type: application/json" \
  -d '{"customer_ref":"customer_88"}'

Delete a plan

DELETE/plans/:idPermanently remove a plan and refund its unused share
cURL
curl -X DELETE https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA \
  -H "Authorization: Bearer $NODEPROXIES_KEY"
json
{ "data": { "id": "6f1c2a8e-…", "code": "K7Q2M9XA", "deleted": true, "refund": 4.50 } }

Deleting an active plan refunds the part you haven't used to your account balance, instantly. The same rule applies when you delete a plan from the dashboard. refund is the amount credited in USD, and a matching refund transaction appears in GET /transactions.

How the refund is calculated

text
refund = (purchase price + top-ups paid) × unused share
Plan typeUnused share
Residential, Mobile, Datacenter (per GB)(GB in plan − GB used) ÷ GB in plan, using live usage at the moment you delete
Unlimited Residential / Datacenter (time)Hours left before the plan expires ÷ total hours bought. A plan whose clock hasn't started yet counts as fully unused

The result is rounded to the nearest cent. Some examples:

PlanPaidUsedRefund
10 GB Residential$6.002.5 GB (25%)$6.00 × 75% = $4.50
10 GB + 10 GB top-up$6.00 + $6.005 GB of 20 GB$12.00 × 75% = $9.00
24 h Unlimited Residential$93.6018 h, 6 h left$93.60 × 25% = $23.40
No refund is given for free trials, plans that are expired or fully used, or plans that no longer exist on the network. Deleting is irreversible: the credentials stop working immediately.

Proxy connection

Every plan's connection object has ready-to-use URLs. HTTP(S) uses port 8080 and SOCKS5 uses port 1080. Unlimited plans use the u- prefixed gateways.

GatewayUnlimited plansRegion
global.nodeproxies.xyzu-global.nodeproxies.xyzAuto (recommended)
eu-1.nodeproxies.xyzu-eu-1.nodeproxies.xyzEurope 1
eu-2.nodeproxies.xyzu-eu-2.nodeproxies.xyzEurope 2
na.nodeproxies.xyzu-na.nodeproxies.xyzNorth America
cURL
curl -x "http://USERNAME:[email protected]:8080" https://httpbin.org/ip
curl -x "socks5h://USERNAME:[email protected]:1080" https://httpbin.org/ip
Python
import requests

proxy = "http://USERNAME:[email protected]:8080"
r = requests.get("https://httpbin.org/ip", proxies={"http": proxy, "https": proxy})
print(r.json())

Geo targeting

Add targeting flags to the proxy username, separated by hyphens. Codes come from GET /locations.

SyntaxExampleEffect
-country-{cc}-country-usExit from one country
-country-{cc},{cc}-country-us,gb,deRandom exit from several countries
-state-{code}-city-{code}-country-us-state-NY1-city-NYC1City targeting (residential only)
-asn-{asn}-country-us-asn-VZ1Carrier / ISP targeting
cURL
# US exit IP
curl -x "http://USERNAME-country-us:[email protected]:8080" https://httpbin.org/ip

# New York City, residential
curl -x "http://USERNAME-country-us-state-NY1-city-NYC1:[email protected]:8080" https://httpbin.org/ip

Sticky sessions

By default every request rotates to a new IP. To keep the same exit IP, add -session-{id}-time-{minutes} to the username. The session keeps that IP for as many minutes as you set, and there's no maximum. Use a new id whenever you want a fresh IP.

cURL
# Same IP for 10 minutes
curl -x "http://USERNAME-session-ORDER1042-time-10:[email protected]:8080" https://httpbin.org/ip

# Same IP for a full day, combined with country targeting
curl -x "http://USERNAME-country-us-session-ORDER1042-time-1440:[email protected]:8080" https://httpbin.org/ip
Use one session id per task (an order id, account id, etc.) so unrelated work never shares an IP.

Error codes

HTTPcodeMeaning
400invalid_requestMissing or invalid parameters. The message says which.
401unauthorizedMissing, malformed, invalid or revoked API key
402insufficient_balanceTop up your balance. Includes required / available / shortfall.
403not_resellerThe account behind this key isn't an approved reseller
403ip_not_allowedRequest IP isn't on the key's allowlist
403account_bannedThe account is suspended
403forbiddenAction not allowed for this account or plan
404not_foundNo such plan on your account
409balance_conflictBalance changed mid-request. Retry with the same Idempotency-Key.
409username_takenThe custom username is already in use. Nothing was charged; pick another.
409idempotency_in_progressFirst request with this key is still running
422idempotency_key_reusedKey already used with a different body
429rate_limitedSlow down. See the Retry-After header.
500internal_error / upstream_errorSomething failed on our side. Safe to retry with an Idempotency-Key.
503service_unavailableProvisioning temporarily paused. Contact support.

Need help?

Resellers get priority support on Discord. Include the request_id.

Changelog

DateVersionChanges
2026-10-31v1DELETE /plans/:id now returns refund: the unused share of everything paid for the plan (purchase + top-ups) is credited to your balance.
2026-10-15v1Reseller API launched: API keys, idempotent purchases, customer_ref, unified errors. The old undocumented /api/* account-token endpoints are no longer supported for integrations.