Reseller API

Overview

The API automates what you do by hand from the buy page: read your balance, check stock and the price of an order, then buy ISP proxies for France, Spain or Europe. Each proxy is valid for 30 days.

An API purchase behaves exactly like a balance purchase on the site:

• the amount is debited from your balance, with your tier discount;
• an invoice is issued, as for any purchase;
• the proxies are created on your account and their credentials are returned in the response;
• they are added to the Resale page of your reseller area, with a sale price of 0 that you then set by hand (or pass in the request).

Quick start

1. Generate your key. In your client area, open the "Reseller area" tab, expand the "Automatic purchase API" block and click "Generate a key". Copy it right away: it is shown only once.
2. Check that it works by reading your balance.
3. Place a first order.

Reading the balance:

export AIRPROXY_KEY="apr_votre_cle_ici"

curl https://airproxy.store/api/v1/reseller/balance \
  -H "Authorization: Bearer $AIRPROXY_KEY"

{ "ok": true, "balance": 94.3, "currency": "EUR" }

Buying 2 French proxies:

curl -X POST https://airproxy.store/api/v1/reseller/buy \
  -H "Authorization: Bearer $AIRPROXY_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{"country":"fr","qty":2}'

{
  "ok": true,
  "order_id": 27,
  "country": "fr",
  "qty": 2,
  "total_debited": 5.4,
  "proxies": [
    {
      "proxy_id": "1791018004491.359791309",
      "host": "203.0.113.10",
      "port": 8888,
      "username": "airproxy4821",
      "password": "k3QxT9mW2vLp8dRa",
      "access": "203.0.113.10:8888:airproxy4821:k3QxT9mW2vLp8dRa",
      "country": "fr",
      "expires_at": "2026-11-02T09:00:04.491Z"
    },
    {
      "proxy_id": "1791018004492.928588261",
      "host": "203.0.113.10",
      "port": 8888,
      "username": "airproxy4822",
      "password": "8JZ5f1O7xG6jPrt5",
      "access": "203.0.113.10:8888:airproxy4822:8JZ5f1O7xG6jPrt5",
      "country": "fr",
      "expires_at": "2026-11-02T09:00:04.491Z"
    }
  ],
  "discount": 0.6,
  "balance": 88.9,
  "listed_in_resale": true
}

On Windows, replace $(uuidgen) with any unique string of 8 characters or more. The addresses in the examples (203.0.113.10) are fictitious: always use the host and port from the response.

Authentication

Every request carries your API key in the Authorization header. The X-API-Key header is accepted instead.

Authorization: Bearer apr_votre_cle_ici

• There is a single key per account. Generating a new one invalidates the old one immediately.
• We do not store the key in clear text: if you lose it, regenerate one.
• It can buy with your balance and nothing else. It gives access neither to your password, nor to your invoices, nor to your payment methods.
• You can revoke it at any time from the same block of your reseller area.
• It stops working (403 not_reseller) if reseller mode is removed from your account.

Conventions

• All routes are over HTTPS. Requests with a body send Content-Type: application/json.
• A successful response contains "ok": true. An error returns {"ok": false, "error": "...", "code": "..."} with the matching HTTP status and, depending on the case, extra fields (balance, available...). Base your logic on code, which is stable, never on error, which is text for humans.
• Amounts are numbers in euros, with at most two decimals. Dates are in ISO 8601 format, in UTC.
• Types are strict: a number is passed as a JSON number ("qty": 2, not "qty": "2"). An ambiguous value is refused rather than interpreted, because this API debits money.
• Unknown fields in a request are ignored. Do the same with responses: fields may be added to them.
• Responses are never cached (Cache-Control: no-store): they contain credentials.
• The API is meant to be called from your server: calls from a browser are blocked.

Routes

The paths below are relative to the base URL https://airproxy.store/api/v1/reseller. The examples read your key from the AIRPROXY_KEY variable.

GET/balance

Returns your current balance.

curl https://airproxy.store/api/v1/reseller/balance \
  -H "Authorization: Bearer $AIRPROXY_KEY"

import os
import requests

r = requests.get(
    "https://airproxy.store/api/v1/reseller/balance",
    headers={"Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}"},
    timeout=15,
)
print(r.json())

const res = await fetch("https://airproxy.store/api/v1/reseller/balance", {
  headers: { Authorization: `Bearer ${process.env.AIRPROXY_KEY}` },
});
console.log(await res.json());

200 response

{ "ok": true, "balance": 94.3, "currency": "EUR" }

GET/stock

Returns, for each country, the number of available proxies and the price of an order of qty proxies. Worth checking before a large purchase: pricing is tiered, so the unit price depends on the quantity.

Query parameter

curl "https://airproxy.store/api/v1/reseller/stock?qty=5" \
  -H "Authorization: Bearer $AIRPROXY_KEY"

import os
import requests

r = requests.get(
    "https://airproxy.store/api/v1/reseller/stock",
    params={"qty": 5},
    headers={"Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}"},
    timeout=15,
)
print(r.json())

const res = await fetch("https://airproxy.store/api/v1/reseller/stock?qty=5", {
  headers: { Authorization: `Bearer ${process.env.AIRPROXY_KEY}` },
});
console.log(await res.json());

200 response

{
  "ok": true,
  "currency": "EUR",
  "stock": [
    { "country": "fr", "available": 24, "qty": 5, "total": 12.6, "unit_price": 2.52 },
    { "country": "es", "available": 12, "qty": 5, "total": 9.5,  "unit_price": 1.9 },
    { "country": "eu", "available": 0,  "qty": 5, "total": 9.5,  "unit_price": 1.9 }
  ]
}

The values in this example are fictitious. Stock is shared across all clients: available may change from one call to the next.

POST/buy

Buys qty proxies of a country, for 30 days, debiting your balance. The order is all-or-nothing: if the balance or stock is not enough, nothing is debited.

Headers

Request body

curl -X POST https://airproxy.store/api/v1/reseller/buy \
  -H "Authorization: Bearer $AIRPROXY_KEY" \
  -H "Idempotency-Key: commande-4821" \
  -H "Content-Type: application/json" \
  -d '{"country":"fr","qty":2}'

import os
import requests

r = requests.post(
    "https://airproxy.store/api/v1/reseller/buy",
    headers={
        "Authorization": f"Bearer {os.environ['AIRPROXY_KEY']}",
        "Idempotency-Key": "commande-4821",
    },
    json={"country": "fr", "qty": 2},
    timeout=30,
)
data = r.json()
if r.status_code in (200, 201):
    for p in data["proxies"]:
        print(p["access"])
else:
    print(data["code"], data["error"])

const res = await fetch("https://airproxy.store/api/v1/reseller/buy", {
  method: "POST",
  headers: {
    Authorization: `Bearer ${process.env.AIRPROXY_KEY}`,
    "Idempotency-Key": "commande-4821",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({ country: "fr", qty: 2 }),
});
const data = await res.json();
if (res.ok) data.proxies.forEach((p) => console.log(p.access));
else console.error(data.code, data.error);

In these examples, the idempotency key is derived from the order identifier of your own system, which is the best practice (see Idempotency).

201 response

The order is created. Replaying the same request returns status 200 with the header Idempotent-Replay: true.

proxies[] object

Idempotency

A purchase debits your balance. If the connection drops before the response, you cannot know whether it happened. The Idempotency-Key header, required on POST /buy, solves this: replaying the same request with the same key never debits twice. Either the purchase had not happened and it happens now, or it had happened and you receive the same order.

Choosing the key

Derive it from the order identifier of your own system (order-4821, ticket-98123...) and save it before the first call. If your program restarts mid-order, it will replay the same key instead of creating a new one, and will never pay twice for the same order.

A key is 8 to 128 characters: letters, digits and . _ : -. Keys are specific to your account. Never use the same key for two different orders, even weeks apart.

What a replay returns

The original order, rebuilt from its current state: the credentials and balance are today's. The discount and listed_in_resale fields are returned on creation only. Only country and qty are compared: if you replay with a different price, the original order is returned as-is and its price is not changed.

Pricing and discounts

The price of an order depends on the country and the quantity (tiered pricing). GET /stock?qty=N returns the exact amount POST /buy will debit for N proxies at the time of the call.

Your reseller tier discount is applied automatically: your tiers are shown in the "Reseller area" tab of your client area. If a review discount is available and more advantageous, that one applies. Promo codes and the daily wheel do not apply to API purchases.

The POST /buy response indicates the amount debited (total_debited) and the discount already deducted (discount).

After the purchase

The Resale page

Proxies bought via the API are added automatically to the Resale page of your reseller area, with the sale price passed in price (0 if absent). You then set the price and the buyer's name there whenever you want, as for any proxy.

Using a credential

The entry point (host:port) is the same for all your proxies: it is the username that designates each proxy. It accepts SOCKS5 and HTTP (CONNECT tunnel, so for HTTPS traffic). Always reuse host and port from the response instead of hard-coding them. To check a credential, ask the site which address it sees:

# SOCKS5
curl --proxy socks5h://USERNAME:PASSWORD@HOST:PORT https://airproxy.store/api/ip

# HTTP (tunnel CONNECT)
curl --proxy http://USERNAME:PASSWORD@HOST:PORT https://airproxy.store/api/ip

Expiry and renewal

Each proxy expires on the expires_at date. Renewal is not available through the API: do it from the Resale page of your client area, where upcoming expiries are flagged.

Invoice and balance

Each purchase issues an invoice, viewable in your client area like the others. Topping up the balance is done from the site, by card or crypto: the API has no top-up route.

Limits

• The 24-hour cap counts the proxies ordered, including those of an order still in progress. An order refused before any debit (balance, stock) does not count.
• The per-minute rate counts all authenticated requests, including those that are refused.
• Each response carries the headers RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset (in seconds). A 429 refusal adds Retry-After.
• Need higher caps? Contact support, stating your use case.

Errors

Every error is a JSON object: ok is false, code is the stable identifier to test, error a readable message. Some codes add fields, noted in the table.

{
  "ok": false,
  "error": "Solde insuffisant.",
  "code": "insufficient_balance",
  "balance": 1.2,
  "required": 5.4
}

The two order_failed errors are the only ones never to replay: money may have moved without delivery, and only support can settle the order. For all other network or server errors, replaying with the same Idempotency-Key is safe.

Full example

This function buys proxies and handles network drops, unavailable upstreams and rate limits by replaying with the same idempotency key. It stops as soon as an error must not be replayed.

import os
import time
import requests

BASE = "https://airproxy.store/api/v1/reseller"
KEY = os.environ["AIRPROXY_KEY"]
RETRY_CODES = {"request_in_progress", "server_error"}


def acheter(country, qty, idem_key, price=None, essais=5):
    """Achète des proxies. Rejouer avec la même idem_key ne débite jamais deux fois."""
    body = {"country": country, "qty": qty}
    if price is not None:
        body["price"] = price

    for essai in range(essais):
        try:
            r = requests.post(
                f"{BASE}/buy",
                json=body,
                headers={"Authorization": f"Bearer {KEY}", "Idempotency-Key": idem_key},
                timeout=30,
            )
        except requests.RequestException:
            time.sleep(2 ** essai)  # coupure réseau : on rejoue avec la MÊME clé
            continue

        try:
            data = r.json()
        except ValueError:
            data = {}  # 502, 503, 504 d'un relais : corps non JSON

        if r.status_code in (200, 201):
            return data
        if r.status_code == 429 and data.get("code") == "rate_limited":
            time.sleep(int(r.headers.get("Retry-After", "5")))
            continue
        if r.status_code in (502, 503, 504) or data.get("code") in RETRY_CODES:
            time.sleep(2 ** essai)
            continue
        raise RuntimeError(f"{data.get('code')}: {data.get('error')}")  # à ne pas rejouer

    raise RuntimeError(f"Abandon après {essais} essais (clé {idem_key})")


# Servir un acheteur : la clé est dérivée de VOTRE identifiant de commande
commande = acheter("fr", 3, idem_key="commande-4821")
for p in commande["proxies"]:
    print(p["access"])

// Node.js 18 ou plus, module ES (fichier .mjs)
const BASE = "https://airproxy.store/api/v1/reseller";
const KEY = process.env.AIRPROXY_KEY;
const pause = (ms) => new Promise((resolve) => setTimeout(resolve, ms));

// Rejouer avec la même idemKey ne débite jamais deux fois.
async function acheter({ country, qty, price }, idemKey, essais = 5) {
  const body = { country, qty, ...(price != null && { price }) };

  for (let essai = 0; essai < essais; essai++) {
    let res;
    try {
      res = await fetch(`${BASE}/buy`, {
        method: "POST",
        headers: {
          Authorization: `Bearer ${KEY}`,
          "Idempotency-Key": idemKey,
          "Content-Type": "application/json",
        },
        body: JSON.stringify(body),
        signal: AbortSignal.timeout(30000),
      });
    } catch {
      await pause(2 ** essai * 1000); // coupure réseau : on rejoue avec la MÊME clé
      continue;
    }

    const data = await res.json().catch(() => ({})); // 502, 503, 504 d'un relais : corps non JSON
    if (res.ok) return data;

    if (res.status === 429 && data.code === "rate_limited") {
      await pause(Number(res.headers.get("retry-after") ?? 5) * 1000);
      continue;
    }
    if ([502, 503, 504].includes(res.status) || ["request_in_progress", "server_error"].includes(data.code)) {
      await pause(2 ** essai * 1000);
      continue;
    }
    throw new Error(`${data.code}: ${data.error}`); // à ne pas rejouer
  }
  throw new Error(`Abandon après ${essais} essais (clé ${idemKey})`);
}

// Servir un acheteur : la clé est dérivée de VOTRE identifiant de commande
const commande = await acheter({ country: "fr", qty: 3 }, "commande-4821");
commande.proxies.forEach((p) => console.log(p.access));

Best practices

• One idempotency key per order, saved before the call. Derive it from your system's order identifier.
• Never replay an order_failed. Contact support with the order_id.
• Treat out_of_stock as a normal response. Warn your buyer or try again later, without a tight loop.
• Keep enough balance for overnight. An insufficient_balance debits nothing: after topping up, replay the same key.
• Store the delivered credentials with the order reference, in your database. A replay returns the current state of the order, not its original state.
• Do not poll the stock in a loop. One call every few seconds is more than enough, and you have 30 requests per minute.
• Watch expires_at and renew before the deadline from your client area.
• Keep the key secret and regenerate it at the slightest doubt.

Support

A question, or unexpected behavior? Open a ticket from your client area, or write to us on Discord. State the order_id reference of the order concerned, the time of the call and the error code received: this lets us find the request right away.

History

3 October 2026: first version, with the balance, stock and buy routes.