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
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 customerReseller access
API access is only for approved resellers. Apply from your dashboard under Become a reseller. You'll need:
| Requirement | Details |
|---|---|
| Discord | Discord connected to your account, and you're a member of our server. Reviews and support happen there. |
| $200 deposited | At least $200 in completed top-ups (lifetime). It stays in your balance to spend on plans. |
| Launch-ready website | A 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.
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.
Authorization: Bearer np_live_xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
Base URL
https://nodeproxies.xyz/api/v1
| Behaviour | Details |
|---|---|
| Copying | Copy the full key from your Reseller console anytime. It's stored encrypted and only revealed to you while logged in. |
| IP allowlist | Optionally lock a key to your server IPs. Calls from other IPs get 403 ip_not_allowed. |
| Revocation | Revoking a key, or losing reseller status, blocks it immediately. |
| Session tokens | Your dashboard login token is not accepted by /api/v1. |
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.
{
"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.
{
"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.
"pagination": { "limit": 50, "offset": 0, "total": 132, "has_more": true }Headers
| Header | Description |
|---|---|
| X-Request-Id | Unique id for every request. Include it when contacting support. |
| X-RateLimit-Limit / -Remaining / -Reset | Your current rate-limit window (reset is a Unix timestamp). |
| Idempotent-Replayed | true 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.
Idempotency-Key: order_1042
| Situation | Result |
|---|---|
| Same key, same body (within 24h) | The original response is returned with Idempotent-Replayed: true. |
| Same key, different body | 422 idempotency_key_reused |
| Same key while the first call is still running | 409 idempotency_in_progress. Retry shortly. |
| First call failed with 5xx / 409 / 429 | The key is released, so you can retry with it. |
Rate limits
| Scope | Limit |
|---|---|
| All requests | 300 / 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
/meBalance, plan counts and the key in usecurl https://nodeproxies.xyz/api/v1/me \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"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
/productsEvery plan type with the price you paycurl https://nodeproxies.xyz/api/v1/products \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"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,
...
}
]
}| type | Billed per | Size field on create |
|---|---|---|
| residential | GB | bandwidth_gb or bandwidth_mb |
| mobile | GB | bandwidth_gb or bandwidth_mb |
| unlimited_residential | hour | duration_hours (1–8760) |
Locations
/locations?type=residentialTargetable countries, states, cities and carriersWithout 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 "https://nodeproxies.xyz/api/v1/locations?type=residential" \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"data": [
{
"name": "United States",
"iso2": "US",
"states": [
{ "name": "New York", "code": "NY1", "cities": [{ "name": "New York City", "code": "NYC1" }] }
]
}
]
}Gateways & server IPs
/gatewaysProxy hostnames, ports and the IPs they resolve toUse 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 https://nodeproxies.xyz/api/v1/gateways \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"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
/transactionsYour wallet ledger, newest first| Query | Type | Description |
|---|---|---|
| type | string | deposit, plan_purchase or plan_update |
| status | string | completed, failed or pending |
| limit / offset | number | Pagination |
curl "https://nodeproxies.xyz/api/v1/transactions?type=plan_purchase&limit=20" \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"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 }
}deposit.The plan object
Every plan endpoint returns this shape. Bandwidth plans have bandwidth, and unlimited plans have duration.
{
"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
}| Field | Type | Description |
|---|---|---|
| id | string | Plan UUID. Every :id path parameter also accepts code. |
| code | string | Short human-friendly plan code |
| type | string | residential, mobile or unlimited_residential |
| status | string | active, inactive, completed (bandwidth used up / removed) or expired |
| customer_ref | string | null | Your own reference (order id, customer id…). Filterable. |
| credentials | object | Proxy username and password |
| connection | object | Gateway hosts, ports and ready-made proxy URLs |
| bandwidth | object | null | Limit, used and remaining in bytes and GB (bandwidth plans) |
| duration | object | null | Hours purchased, hours remaining and data used (unlimited plans) |
List plans
/plansYour plans, newest first, with live usage| Query | Type | Description |
|---|---|---|
| type | string | Filter by plan type |
| status | string | active or inactive |
| customer_ref | string | Only plans tagged with this reference |
| sync | boolean | Default true: refreshes usage for the page. Send false for a faster cached read. |
| limit / offset | number | Pagination (max 100) |
curl "https://nodeproxies.xyz/api/v1/plans?status=active&customer_ref=order_1042" \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{
"data": [ { "id": "6f1c2a8e-…", "type": "residential", "status": "active", ... } ],
"pagination": { "limit": 50, "offset": 0, "total": 1, "has_more": false }
}Create a plan
/plansChargesIdempotentProvision a plan, charged to your balance| Field | Type | Required | Description |
|---|---|---|---|
| type | string | Yes | residential, mobile or unlimited_residential |
| bandwidth_gb | number | Bandwidth plans* | 1–10000 GB |
| bandwidth_mb | integer | Bandwidth plans* | ≥ 100 MB (instead of bandwidth_gb) |
| duration_hours | integer | Unlimited plans | 1–8760 |
| username | string | No | Custom proxy username, 4–32 chars [a-z0-9_], starting with a letter. Must be unique. Random if omitted. |
| password | string | No | Custom proxy password, 6–64 chars [A-Za-z0-9_-]. Random if omitted. |
| customer_ref | string | No | Your reference, up to 120 chars |
* Send exactly one of bandwidth_gb or bandwidth_mb.
Bandwidth plan
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 -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
{
"data": { "id": "6f1c2a8e-…", "code": "K7Q2M9XA", "type": "residential", "status": "active", ... },
"billing": { "charged": 2.75, "balance": 247.25 }
}402 insufficient_balance with required, available and shortfall. Nothing is charged. If provisioning fails, the charge is automatically reversed.Retrieve a plan
/plans/:idOne plan with fresh usage. :id is the UUID or code.curl https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{ "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
/plans/:id/topupChargesIdempotentAdd bandwidth or time to an existing plan| Field | Type | Plan types | Description |
|---|---|---|---|
| bandwidth_gb | number | Bandwidth plans | GB to add (0.1–10000) |
| duration_hours | integer | Unlimited plans | Hours to add (1–8760) |
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}'{
"data": { "id": "6f1c2a8e-…", "bandwidth": { "limit_gb": 15, ... }, ... },
"billing": { "charged": 5.5, "balance": 241.75 }
}Reset proxy password
/plans/:id/reset-passwordRotate the proxy password. The old one stops working immediately.| Field | Type | Required | Description |
|---|---|---|---|
| password | string | No | 6–64 chars [A-Za-z0-9_-]. Random if omitted. |
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
/plans/:idChange metadata (free)| Field | Type | Description |
|---|---|---|
| customer_ref | string | null | Set, change or clear (null) your reference |
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
/plans/:idPermanently remove a plan and refund its unused sharecurl -X DELETE https://nodeproxies.xyz/api/v1/plans/K7Q2M9XA \ -H "Authorization: Bearer $NODEPROXIES_KEY"
{ "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
refund = (purchase price + top-ups paid) × unused share
| Plan type | Unused 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:
| Plan | Paid | Used | Refund |
|---|---|---|---|
| 10 GB Residential | $6.00 | 2.5 GB (25%) | $6.00 × 75% = $4.50 |
| 10 GB + 10 GB top-up | $6.00 + $6.00 | 5 GB of 20 GB | $12.00 × 75% = $9.00 |
| 24 h Unlimited Residential | $93.60 | 18 h, 6 h left | $93.60 × 25% = $23.40 |
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.
| Gateway | Unlimited plans | Region |
|---|---|---|
global.nodeproxies.xyz | u-global.nodeproxies.xyz | Auto (recommended) |
| eu-1.nodeproxies.xyz | u-eu-1.nodeproxies.xyz | Europe 1 |
| eu-2.nodeproxies.xyz | u-eu-2.nodeproxies.xyz | Europe 2 |
| na.nodeproxies.xyz | u-na.nodeproxies.xyz | North America |
curl -x "http://USERNAME:[email protected]:8080" https://httpbin.org/ip curl -x "socks5h://USERNAME:[email protected]:1080" https://httpbin.org/ip
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.
| Syntax | Example | Effect |
|---|---|---|
| -country-{cc} | -country-us | Exit from one country |
| -country-{cc},{cc} | -country-us,gb,de | Random exit from several countries |
| -state-{code}-city-{code} | -country-us-state-NY1-city-NYC1 | City targeting (residential only) |
| -asn-{asn} | -country-us-asn-VZ1 | Carrier / ISP targeting |
# 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.
# 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
Error codes
| HTTP | code | Meaning |
|---|---|---|
| 400 | invalid_request | Missing or invalid parameters. The message says which. |
| 401 | unauthorized | Missing, malformed, invalid or revoked API key |
| 402 | insufficient_balance | Top up your balance. Includes required / available / shortfall. |
| 403 | not_reseller | The account behind this key isn't an approved reseller |
| 403 | ip_not_allowed | Request IP isn't on the key's allowlist |
| 403 | account_banned | The account is suspended |
| 403 | forbidden | Action not allowed for this account or plan |
| 404 | not_found | No such plan on your account |
| 409 | balance_conflict | Balance changed mid-request. Retry with the same Idempotency-Key. |
| 409 | username_taken | The custom username is already in use. Nothing was charged; pick another. |
| 409 | idempotency_in_progress | First request with this key is still running |
| 422 | idempotency_key_reused | Key already used with a different body |
| 429 | rate_limited | Slow down. See the Retry-After header. |
| 500 | internal_error / upstream_error | Something failed on our side. Safe to retry with an Idempotency-Key. |
| 503 | service_unavailable | Provisioning temporarily paused. Contact support. |
Need help?
Resellers get priority support on Discord. Include the request_id.
Changelog
| Date | Version | Changes |
|---|---|---|
| 2026-10-31 | v1 | DELETE /plans/:id now returns refund: the unused share of everything paid for the plan (purchase + top-ups) is credited to your balance. |
| 2026-10-15 | v1 | Reseller API launched: API keys, idempotent purchases, customer_ref, unified errors. The old undocumented /api/* account-token endpoints are no longer supported for integrations. |
