Proxy gateway and REST API documentation

Connect to the proxy gateway

Quickstart

Point any HTTP(S) or SOCKS5 client at the gateway and authenticate with your proxy username and password. Targeting is set inside the username.

Rotating US proxy over HTTP. Replace USERNAME and PASSWORD with your credentials.

The entry gateway is picked for where you are — the nearest door is usually the fastest. You can override it.

Prefer a full walkthrough for your stack? Each guide covers setup, rotating and sticky sessions, and country targeting.

• cURL
• Python requests
• Node.js axios
• Scrapy
• Playwright
• Puppeteer
• Selenium
• Go
• Java
• PHP

curl -x http://gw.nefo.net:9000 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org?format=json

Response200

{"ip": "104.28.219.14"}

Proxy connection

Every proxy uses the same four parts — host:port:username:password. Your username and password come from the proxy generator in your dashboard. Country, city and session targeting are appended to the username as tokens (see below).

gw.nefo.net:9000:USERNAME-country-us:PASSWORD

Ports & gateways

The entry gateway affects latency — the one nearest you is usually fastest, so we auto-pick it. If a proxy feels slow, change the gateway. The exit country is chosen with the country token, independent of the gateway.

# 9000: a new exit IP on every request
curl -x http://gw.nefo.net:9000 \
  -U "USERNAME-country-us:PASSWORD" \
  https://api.ipify.org

Targeting & sessions

Append tokens to your username, separated by hyphens, to control the exit location and session behaviour:

# Rotating: a fresh IP on every request
USERNAME-country-us

# Sticky: the same IP for 30 minutes
USERNAME-country-us-session-a1b2c3d4-lifetime-30

# State + city
USERNAME-country-us-state-california-city-losangeles

# City + ISP (ASN)
USERNAME-country-us-city-chicago-asn-7922

# Device OS
USERNAME-country-us-os-android

Pools

Residential bandwidth works on all three pools at the same price. Send pool with POST /proxies to choose one; leave it out for Pool 1, exactly as before. A Mix spreads requests across the pools in mixPools, in equal shares. A pool that can't serve the target sits out, and a target only one pool serves runs on Pool 1: each line's pool, mixPools and poolNote say what it runs on.

Places for Pool 2 and Pool 3: GET /locations?pool=2 (or 3). Names work as well as codes: "Los Angeles", "losangeles" and "los_angeles" are the same city.

# Pool 3, Los Angeles, the same IP for 30 minutes
curl -X POST "https://app.nefo.net/api/v1/proxies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pool": "3", "protocol": "http", "country": "us",
       "state": "california", "city": "losangeles",
       "sessionMode": "sticky", "stickyDurationMinutes": 30}'

# A Mix of all three pools, a new IP on every request
curl -X POST "https://app.nefo.net/api/v1/proxies" \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"pool": "mix", "mixPools": "123", "protocol": "http",
       "country": "gb", "sessionMode": "rotating", "count": 5}'

# Pool 2's own states, cities and ISPs in one country
curl "https://app.nefo.net/api/v1/locations?pool=2&country=gb" \
  -H "Authorization: Bearer YOUR_API_KEY"

REST API reference

Authentication

Base URL https://app.nefo.net/api/v1. Create a key under Dashboard → API access and send it as a Bearer token. Keys are scoped — request only what you need.

Rate limit: 120 requests per minute per key (proxy generation is throttled further). Keep your key secret and server-side.

GET /api/v1/account HTTP/1.1
Host: nefo.net
Authorization: Bearer sk_YOUR_API_KEY

Errors

Errors return a JSON body { "error": { "code", "message" } } with the matching HTTP status:

HTTP/1.1 402 Payment Required
Content-Type: application/json

{
  "error": {
    "code": "no_bandwidth",
    "message": "…"
  }
}

Get your bandwidth balance

GET/account

Scope: read:usage

No parameters.

curl "https://app.nefo.net/api/v1/account" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "balance": {
    "purchasedGb": 50,
    "usedGb": 12.34,
    "remainingGb": 37.66
  },
  "datacenterBalance": {
    "purchasedGb": 0,
    "usedGb": 0,
    "remainingGb": 0
  },
  "mobileRotatingBalance": {
    "purchasedGb": 10,
    "usedGb": 1.2,
    "remainingGb": 8.8
  },
  "creditUsd": 40
}

Price ladder and quote for rotating GB

GET/pricing

Scope: read:usage

Query parameters

• productstringOptionalWhich network: residential (default), datacenter or mobile_rotating.residentialdatacentermobile_rotatingDefault: residential
• gbintegerOptionalOptional. A whole number of GB from 5 to 10,240 to get a quote for.

curl "https://app.nefo.net/api/v1/pricing?product=datacenter&gb=100" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "product": "datacenter",
  "currency": "USD",
  "minGb": 5,
  "maxGb": 10240,
  "bandwidthExpires": false,
  "tiers": [
    { "gb": 5, "priceUsd": 3.05, "perGbUsd": 0.61 },
    { "gb": 100, "priceUsd": 49, "perGbUsd": 0.49 },
    { "gb": 10240, "priceUsd": 2969.6, "perGbUsd": 0.29 }
  ],
  "quote": { "gb": 100, "totalUsd": 49, "perGbUsd": 0.49 }
}

Buy rotating GB from your balance

POST/orders

Scope: purchase

Body parameters

• productstringOptionalWhich network: residential (default), datacenter or mobile_rotating.residentialdatacentermobile_rotatingDefault: residential
• gbintegerRequiredGB to buy, from 5 to 10,240. Charged to your wallet at the ladder price, with your rank discount; the GB is credited at once and never expires.

curl -X POST "https://app.nefo.net/api/v1/orders" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "product": "datacenter",
    "gb": 100
  }'

Response201

{
  "order": {
    "id": "cmv…",
    "orderNumber": "SN-MVFRMPRO-B26F94",
    "product": "datacenter",
    "gb": 100,
    "amountUsd": 49,
    "discountUsd": 0,
    "status": "paid"
  },
  "balanceUsd": 51
}

Get usage analytics

GET/usage

Scope: read:usage

Query parameters

• rangestringOptionalTime window. An unknown value falls back to 24h.1h24h7d30d90dtodaymonth12mallDefault: 24h
• productstringOptionaldatacenter reads datacenter usage; anything else reads residential.residentialdatacentermobile_rotatingDefault: residential

curl "https://app.nefo.net/api/v1/usage?range=30d" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "range": "30d",
  "product": "residential",
  "granularity": "day",
  "totalGb": 12.34,
  "series": [{ "period": "2026-09-01", "gb": 1.2 }],
  "requests": {
    "total": 10420,
    "successful": 10310,
    "failed": 110,
    "successRate": 98.9,
    "avgLatencyMs": 280
  },
  "byCountry": [{ "country": "us", "requests": 8200, "gb": 9.1 }],
  "truncated": false
}

List saved proxy credentials

GET/proxies

Scope: read:proxies

No parameters.

curl "https://app.nefo.net/api/v1/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "data": [
    {
      "id": "clx…",
      "product": "residential",
      "label": "scraper",
      "protocol": "http",
      "country": "us",
      "sessionMode": "rotating",
      "host": "gw.nefo.net",
      "port": 9000,
      "username": "USERNAME-country-us",
      "pool": "1",
      "status": "active",
      "createdAt": "2026-09-30T08:12:44.000Z"
    }
  ]
}

Generate proxy credentials (password returned once)

POST/proxies

Scope: write:proxies

Body parameters

• protocolstringRequiredProtocol the credentials speak.httpsocks5
• countrystringRequiredTwo-letter country code, or ANY for worldwide.
• statestringOptionalUS state, full name without spaces, e.g. california.
• citystringOptionalCity name without spaces, e.g. losangeles. Ignored when asn is set.
• asnintegerOptionalISP network number, e.g. 7922 for Comcast.
• sessionModestringRequiredrotating gives a new IP on every request; sticky keeps one IP for stickyDurationMinutes.rotatingsticky
• stickyDurationMinutesintegerOptionalHow long a sticky IP is held, 1–1440 minutes. Required when sessionMode is sticky.
• countintegerOptionalHow many credentials to create, 1–20.Default: 1
• labelstringOptionalYour name for them, up to 80 characters. With count above 1 each one gets #n.
• poolstringOptionalResidential pool: 1 (default), 2, 3 or mix. See Pools.123mixDefault: 1
• mixPoolsstringOptionalWith pool mix: the pools it draws on, 12, 13, 23 or 123 (default 123).121323123Default: 123
• strictbooleanOptionaltrue: only the exact state, city or ISP; false: fall back to the country when it has no free IP. Default true on Pool 1 and false on a Mix; a strict Mix runs on Pool 1.
• gatewaystringOptionalEntry gateway the line dials: fr, us or sg — or auto (default), which returns the geo-routed host and lets DNS pick the nearest. Residential only.autofrussgDefault: auto
• osstringOptionalDevice OS fingerprint: windows, android, ios or mac. Omit for any device.windowsandroidiosmac
• productstringOptionalWhich balance pays and which network the proxies come from: residential (default), datacenter or mobile_rotating. For mobile_rotating, country targeting is the default; state, city and ASN targeting count traffic twice, and a sticky IP is held for at most 120 minutes.residentialdatacentermobile_rotatingDefault: residential

curl -X POST "https://app.nefo.net/api/v1/proxies" \
  -H "Authorization: Bearer sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "protocol": "http",
    "country": "us",
    "sessionMode": "rotating",
    "count": 2,
    "label": "scraper"
  }'

Response201

{
  "data": [
    {
      "id": "clx…",
      "host": "gw.nefo.net",
      "port": 9000,
      "username": "USERNAME-country-us",
      "password": "shown once",
      "protocol": "http",
      "country": "us",
      "state": null,
      "city": null,
      "sessionMode": "rotating",
      "stickyDurationMinutes": null,
      "label": "scraper #1",
      "product": "residential",
      "pool": "1",
      "mixPools": null,
      "poolNote": null
    }
  ]
}

Delete a saved proxy credential

DELETE/proxies/{id}

Scope: write:proxies

Path parameters

• idstringRequiredThe saved proxy's id, as GET /proxies returns it.

curl -X DELETE "https://app.nefo.net/api/v1/proxies/PROXY_ID" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "data": { "id": "clx…", "deleted": true }
}

Targeting catalogue: countries, their states and cities

GET/locations

Scope: read:proxies

Query parameters

• countrystringOptionalCountry code. Returns its states.
• statestringOptionalState code, together with country. Returns its cities.
• productstringOptionalWhose catalogue to read: residential (default), datacenter or mobile_rotating. Datacenter and rotating mobile also list the country's ASNs.residentialdatacentermobile_rotatingDefault: residential
• poolstringOptionalResidential pool whose places to list: 1 (default), 2 or 3. A Mix targets with Pool 1's list.123Default: 1

curl "https://app.nefo.net/api/v1/locations?country=us" \
  -H "Authorization: Bearer sk_YOUR_API_KEY"

Response200

{
  "data": {
    "country": "us",
    "states": [
      { "code": "california", "name": "California", "cities": 212 },
      { "code": "texas", "name": "Texas", "cities": 187 }
    ]
  }
}

Start building

Generate credentials in the dashboard or create an API key to automate it.

• Create API key
• Open generator

Frequently asked questions