# Nameless Proxy API documentation

> Nameless Proxy REST API at namelessproxy.com/api: API keys, errors, limits and endpoints for the balance, crypto top-ups, orders, proxies and mobile IP rotation.

- URL: https://namelessproxy.com/docs/api/
- Last updated: 2026-10-06
- Publisher: Nameless Proxy (https://namelessproxy.com)

Everything you do in your account can be scripted: check the balance, top up in crypto, buy a plan, create proxy credentials, rotate a mobile IP. JSON over HTTPS, one API key, examples in curl, Python and Node.js.

**Quick answer — How do I use the Nameless Proxy API?**

Send HTTPS requests to `https://namelessproxy.com/api/v1` with your API key in the header `Authorization: Bearer API_KEY`. Create the key on the [API & IP whitelist](https://namelessproxy.com/app/developer) page of your account (or with `POST /v1/api-keys`) and give it only the scopes it needs. Requests and responses are JSON; errors always come back as `{ "error": { "code", "message" } }`.

## At a glance

| Attribute | Value |
| --- | --- |
| Base URL | `https://namelessproxy.com/api/v1` |
| Format | JSON over HTTPS, UTF-8 |
| Authentication | API key: `Authorization: Bearer API_KEY` |
| API key scopes | `read`, `proxies`, `billing` |
| Money | USD as a string with 2 decimals (`"29.00"`) |
| Crypto amounts | Decimal strings, never floats (`"0.00045210"`) |
| Traffic | Bytes (1 GB = 1,000,000,000 bytes) |
| Dates | ISO 8601 in UTC (`2026-10-05T14:03:11Z`) |
| Version | `/v1` in every path |

## Authentication

Every request except the public catalogue carries an API key: `Authorization: Bearer API_KEY`. A key is shown in full **once**, when you create it: store it like a password. Revoke a key at any time; requests made with it then return `401 unauthorized`.

### Scopes

Give each key only what your script needs. A key without the required scope gets `403 forbidden`.

| Scope | What it allows |
| --- | --- |
| `read` | read everything (account, balance, services, usage). |
| `proxies` | manage sub-users, whitelist, rotate/relocate mobile ports (includes the rotation link). |
| `billing` | create orders and top-ups, pay from the balance. |

The only exception is the **mobile rotation link**, made to be called from a browser bookmark or a plain `curl`: `GET https://namelessproxy.com/api/v1/mobile/PORT_ID/rotate?key=API_KEY` (key with the `proxies` scope). See [Mobile ports and IP rotation](https://namelessproxy.com/docs/api/mobile/).

*Check your balance*

```bash
curl -s "https://namelessproxy.com/api/v1/balance" \
  -H "Authorization: Bearer $API_KEY"
```

## Requests and responses

- **JSON in, JSON out**: send `Content-Type: application/json` with a body.
- **Lists** that can grow are paginated with `page` (from 1) and `perPage` (1–100, default 20) and return `{ "data": [...], "pagination": { "page", "perPage", "total", "totalPages" } }`. Short lists return `{ "data": [...] }`.
- **IDs** are opaque strings with a type prefix: `ord_` (order), `top_` (top-up), `txn_` (balance movement), `res_` (traffic subscription), `mob_` (mobile port), `key_` (API key), `ipw_` (whitelisted IP).
- **Safe retries**: `POST /v1/orders` and `POST /v1/topups` accept an `Idempotency-Key` header (any unique string, kept 24 h). Replaying the same key returns the first response instead of buying or topping up twice.
- **Examples** show the shape of each answer: the IDs, IPs, amounts and dates in them are illustrative, the plan ids and prices are the real ones.

## Errors

Every error has the same body. `code` is stable and meant for your code; `message` is an English sentence that may change. Validation errors list each invalid field in `fields`. New codes may be added: handle unknown codes as a generic failure.

*422 validation_failed*

```json
{
  "error": {
    "code": "validation_failed",
    "message": "Some fields are invalid.",
    "fields": [
      {
        "field": "amountUsd",
        "code": "too_small",
        "message": "The minimum top-up is 25.00 USD."
      }
    ],
    "requestId": "req_2b7c0f"
  }
}
```

### Status codes

| Status | Meaning |
| --- | --- |
| `422` | `validation_failed`: one or more fields are invalid. |
| `401` | `unauthorized`: missing, invalid or expired token. |
| `402` | `insufficient_balance`: the balance does not cover the order. `details` = `InsufficientBalanceDetails`. |
| `403` | `forbidden`: the API key lacks the required scope, or the account is suspended. |
| `404` | `not_found`: the resource does not exist or belongs to another account. |
| `409` | `conflict` (or a more specific code): the action is not possible in the current state. |
| `429` | `rate_limited` or `rotation_too_soon`. |

## Rate limits

Every response carries `RateLimit-Limit`, `RateLimit-Remaining` and `RateLimit-Reset`. Above the limit the API answers `429 rate_limited` with a `Retry-After` header (seconds): wait that long, then retry. Changing the IP of a mobile port is limited separately: one rotation every 30 seconds per port by default (`429 rotation_too_soon`).

## API reference

- **[Account and balance](https://namelessproxy.com/docs/api/account/)** — Read your account settings, your prepaid USD balance and every movement of that balance (top-ups, purchases, refunds).
- **[Crypto top-ups](https://namelessproxy.com/docs/api/top-ups/)** — Top up the balance in crypto: get the deposit address and the unique exact amount, send it, mark the top-up as sent, then follow the confirmations until the balance is credited. Payments are matched automatically by their exact amount. The balance buys any product in any country.
- **[Orders](https://namelessproxy.com/docs/api/orders/)** — List the plans and their prices, buy a plan from the balance (new service, more traffic or a port extension) and read your past orders.
- **[Residential proxies and credentials](https://namelessproxy.com/docs/api/residential/)** — Manage traffic subscriptions (residential and rotating 4G/5G per GB): proxy credentials, sub-users with their own traffic cap, daily usage and the locations you can target in the proxy username.
- **[Mobile ports and IP rotation](https://namelessproxy.com/docs/api/mobile/)** — Dedicated 4G/5G ports: change the IP now or on a timer, use the rotation link, move a port to another country or carrier, read the IP history and the daily traffic.
- **[API keys and IP whitelist](https://namelessproxy.com/docs/api/api-keys/)** — Create and revoke API keys with limited scopes, and whitelist the source IPs allowed to use the proxies without a username and password.

> **Paying from a script** Plans are always paid from the prepaid USD balance. Top up in crypto (minimum 25.00 USD) with POST /v1/topups, then buy with POST /v1/orders. Both can go in one call: a top-up may carry the order in purchase, and the plan is bought as soon as the top-up is credited.

---

Nameless Proxy: Nameless Proxy is a privacy-first, no-KYC proxy provider: rotating residential and 4G/5G mobile proxies, account-number login, and payment in crypto (Bitcoin, USDT, USDC). Residential from $0.53/GB.