ProxyMaxy
Buy proxiesSubscriptionsBillingDocumentation
Sign in
RUEN

Documentation

Version: 1.0.0 · Last updated: 2026-08-25

Table of contents

  1. Getting started
  2. Authentication
  3. Proxy access
  4. Rotation and geo
  5. Errors
  6. Rate limits
  7. REST API reference
  1. Getting started
  2. Authentication
  3. Proxy access
  4. Rotation and geo
  5. Errors
  6. Rate limits
  7. REST API reference

Getting started

ProxyMaxy hands out proxy access through your dashboard. Going from sign-up to your first request takes a few minutes.

  • Create an account and confirm your sign-in.
  • Top up your balance to cover the plan you want.
  • Place an order in the configurator: proxy type, traffic volume and geography.
  • Wait for the order to activate — access details then appear on the proxy card.
  • Copy the access string and paste it into your client.

Buy proxies

© 2026 ProxyMaxy

If an order stays pending longer than usual, check your balance: insufficient funds block activation.

Authentication

Proxies authenticate clients with a username and password. The pair is issued per order and is visible only in your dashboard.

  • Never share the credential pair or commit it to a repository.
  • Restrict access with the IP allowlist in your account settings.
  • If a pair is compromised, revoke it and issue a new one.

The REST API uses a separate API key. It is issued in settings and shown once — store it immediately.

Proxy access

An access string combines the gateway host, a port and your credential pair. Supported shapes are host:port:user:pass, user:pass@host:port and a ready-to-run curl command.

Example pending verification

We publish the gateway host, port and access-string format only after verifying them against a real purchase from the provider. Until that check is complete the example stays hidden — your live values appear in your dashboard once an order is active.

  • The gateway host is not confirmed yet.
  • The port range is not confirmed yet.

Each order card offers a bulk export of every location x protocol combination as a single file.

Rotation and geo

Country selection and rotation mode are chosen at checkout and reflected in the ports you receive.

  • Per-request rotation: a new IP for every connection.
  • Sticky session: the IP is held for the session duration your plan allows.
  • Geo targeting: available countries depend on the proxy type and are listed in the configurator.

The exact rotation parameters and country list for your order appear on its card — they depend on the provider and differ between proxy types.

Errors

REST API responses share one envelope: the ok field separates success from failure, and error carries a machine-readable code.

Error response
{ "ok": false, "error": { "code": "VALIDATION", "message": "..." } }
  • VALIDATION — the request failed schema validation.
  • UNAUTHORISED — the access key is missing or invalid.
  • NOT_FOUND — the object does not exist or is not visible to your account.
  • RATE_LIMITED — the request rate limit was exceeded; retry later.

Proxy connection errors surface through the protocol instead: 407 means an authentication problem, and a dropped connection means the selected node is unreachable.

Rate limits

The REST API limits request rate per API key. Exceeding the limit returns the RATE_LIMITED code.

  • Retry with exponential backoff rather than in a tight loop.
  • Cache data that changes rarely — the plan catalogue and order status.
  • Do not poll status more often than once every few seconds.

Numeric limit values will be published together with the full REST API reference.

REST API v1

Authentication
Send the key as Authorization: Bearer <API_KEY>. Every key failure returns the same 401 response.
Scopes
Each operation requires its own scope. A missing scope returns 403; resource ownership is enforced independently.
Rate limits
Unauthenticated traffic is limited to 20 requests per minute per address. Proxy operations use independent 30-per-minute buckets per key; follow the limit headers and Retry-After.
Idempotency
Mutations require Idempotency-Key. Keys are namespaced per account; a retry safely returns the original result or a reconciliation state.
Pagination
Lists use cursor and limit. nextCursor=null means the end of the result set. Never treat a cursor as a record id.
Errors
Errors use {ok:false, version, requestId, error:{code,message}}. Stable code is for automation; message is display copy.
GET

Profile

The current user and safe profile metadata.

Path
/api/v1/profile
Scope
profile:read
Rate limits
profile
Errors
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "id": "usr_example",
    "email": "user@example.invalid"
  }
}
GET

Balance

The authoritative USD wallet balance.

Path
/api/v1/balance
Scope
balance:read
Rate limits
balance
Errors
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "amountUsd": "10.00"
  }
}
GET

Catalogue

Plans and capabilities with vendor cost and margin removed.

Path
/api/v1/catalogue
Scope
catalogue:read
Rate limits
catalogue
Errors
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "products": []
  }
}
GET

List orders

The owner's paginated order history.

Path
/api/v1/orders
Scope
orders:read
Rate limits
orders
Errors
  • 400
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "items": [],
    "nextCursor": null
  }
}
POST

Create order

Creates an order from configuration and an idempotency key.

Path
/api/v1/orders
Scope
orders:write
Rate limits
orders:write
Errors
  • 400
  • 401
  • 402
  • 403
  • 409
  • 429
  • 500
  • 502

Example temporarily unavailable

A new machine client cannot call this operation yet: the request requires a legacy planId while the v1 catalogue does not publish one. The example will appear after planId becomes discoverable; no fabricated id is shown.

GET

Order

One owned order; foreign and missing ids return the same 404.

Path
/api/v1/orders/{id}
Scope
orders:read
Rate limits
orders:detail
Errors
  • 401
  • 403
  • 404
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "id": "ord_example",
    "status": "created"
  }
}
GET

Payments

Settlement and refund history without internal provider strings.

Path
/api/v1/payments
Scope
payments:read
Rate limits
payments
Errors
  • 400
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "items": [],
    "nextCursor": null
  }
}
GET

List proxies

Subscriptions, states and a safe access summary.

Path
/api/v1/proxies
Scope
proxies:read
Rate limits
proxies
Errors
  • 400
  • 401
  • 403
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "items": [],
    "nextCursor": null
  }
}
GET

Proxy

One subscription and its available actions.

Path
/api/v1/proxies/{id}
Scope
proxies:read
Rate limits
proxies:detail
Errors
  • 401
  • 403
  • 404
  • 429
  • 500

Example temporarily unavailable

The provider does not publish gateway host or port for metered networks yet. Those fields remain null; no working access string is invented.

Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "id": "ent_example",
    "endpoints": [
      {
        "host": null,
        "port": null
      }
    ]
  }
}
GET

Usage

Traffic balances and lots with exact byte values represented as strings.

Path
/api/v1/proxies/{id}/usage
Scope
proxies:read
Rate limits
proxies:usage
Errors
  • 400
  • 401
  • 403
  • 404
  • 429
  • 500
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "availableBytes": "0",
    "lots": []
  }
}
POST

Proxy action

Credentials, top-up, access configuration or cancellation.

Path
/api/v1/proxies/{id}/actions
Scope
proxies:write
Rate limits
proxies:write
Errors
  • 400
  • 401
  • 402
  • 403
  • 404
  • 409
  • 429
  • 500
  • 502

Example temporarily unavailable

Gateway host and port remain partial until the provider publishes them. Capability mutations stay closed behind the evidence matrix.

Request
{
  "action": "credentials"
}
Response
{
  "ok": true,
  "version": "v1",
  "requestId": "req_example",
  "data": {
    "action": "credentials",
    "status": "completed"
  }
}

API Playground

The playground sends requests to the current origin only.

The key stays in this tab's memory and is never written to the URL or localStorage.

Operation

v1 · 2026-08-28

ProxyMaxy
Buy proxies
Subscriptions
Billing
Documentation