Документация API

Аутентификация

Передавай ключ в заголовке Authorization как bearer-токен или в заголовке X-API-Key. Никогда не вставляй ключ в URL.

Authorization: Bearer sk_live_your_key_here
# or
X-API-Key: sk_live_your_key_here

У ключей могут быть скоупы: read (только чтение) и trade (создание и продление заказов). Ключ без скоупов имеет полный доступ.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/ping
# → {"ok":true,"service":"sotaproxy","version":"v1"}

Лимиты запросов

Лимиты действуют на каждый API-ключ (в минуту):

• Чтение (баланс, заказы, прокси): 120 / мин
• Каталог и расчёт цены: 60 / мин
• Заказы и продления: 20 / мин

При превышении лимита вернётся HTTP 429.

Идемпотентность

Запросы, которые двигают деньги (создание заказа, продление прокси), требуют заголовок Idempotency-Key - любую уникальную строку на попытку (до 128 символов). Если запрос повторён с тем же ключом, вернётся исходный результат вместо повторного списания. В повторном ответе будет "idempotentReplay": true.

Ошибки

Ошибки возвращают соответствующий HTTP-статус и JSON-тело: {"error":{"code":"...","message":"..."}}.

Возвращает доступные продукты со странами и сроками аренды. Цены зависят от аккаунта - за ценой обращайся к /quote.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/products

{
  "products": [
    {
      "product": "ipv4",
      "unit": "proxy",
      "countries": [ { "id": 565, "name": "US", "alpha3": null }, ... ],
      "periods": [
        { "id": "1m", "name": "1 month",  "days": 30 },
        { "id": "2m", "name": "2 months", "days": 60 }, ...
      ]
    }
  ]
}

Возвращает точную цену для заданных продукта, страны, срока и количества - без покупки.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"product":"ipv4","countryId":565,"periodId":"1m","quantity":5}' \
  https://api.sotaproxy.com/api/v1/quote

{
  "product": "ipv4", "countryId": 565, "periodId": "1m", "quantity": 5,
  "unitPrice": 1.8, "total": 9, "currency": "USD",
  "balance": 42.5, "sufficientBalance": true
}

Покупает и выдаёт прокси, списывая деньги с баланса. Требует скоуп trade и заголовок Idempotency-Key. Необязательные поля тела: purpose (заметка о назначении) и protocol (HTTPS или SOCKS5).

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: your-unique-id" \
  -d '{"product":"ipv4","countryId":565,"periodId":"1m","quantity":5}' \
  https://api.sotaproxy.com/api/v1/orders

{
  "order": {
    "id": "31307ef6-6ee4-4ec7-8a78-e5bd6ee52b9b",
    "product": "ipv4", "country": "US", "periodId": "1m",
    "quantity": 5, "total": 9, "currency": "USD",
    "status": "completed", "createdAt": "2026-07-24T23:11:03.617Z"
  },
  "idempotentReplay": false
}

Заметка: прокси нового заказа могут появиться через несколько минут (особенно IPv6). Опрашивай /orders/{id}/proxies, пока они не вернутся.

Список твоих заказов (с пагинацией: ?page, ?limit) или чтение одного заказа по id.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/orders?limit=20"
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/orders/ORDER_ID

Возвращает выданные прокси заказа. Добавь ?format=txt для строк вида ip:port:login:password.

curl -H "Authorization: Bearer $KEY" \
  "https://api.sotaproxy.com/api/v1/orders/ORDER_ID/proxies?format=txt"

{
  "proxies": [
    {
      "id": "e8c2...", "product": "ipv4", "ip": "23.165.240.2",
      "portHttp": 11565, "portSocks": null,
      "login": "user", "password": "pass",
      "country": "US", "status": "active",
      "expiresAt": "2026-07-31T00:00:00.000Z"
    }
  ]
}

Возвращает все активные прокси аккаунта. Фильтруй по продукту через ?product=ipv4.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/proxies?product=ipv4"

Возвращает точную цену продления заказа прокси на заданный срок без списания - покажи её перед подтверждением. Как и само продление, это уровень заказа: proxiesRenewed - весь заказ, а price покрывает их все. Query-параметр periodId - один из 1m, 3m, 6m, 12m (по умолчанию 1m). Idempotency-Key не нужен.

curl -H "Authorization: Bearer $KEY" \
  "https://api.sotaproxy.com/api/v1/proxies/PROXY_ID/renew-quote?periodId=1m"

{
  "proxyId": "2364b03b-...", "periodId": "1m",
  "proxiesRenewed": 10, "price": 2, "currency": "USD",
  "newExpiresAt": "2026-10-01T00:00:00.000Z"
}

Продлевает прокси - продление работает на уровне заказа: продлевая один прокси, ты продлеваешь все прокси из того же заказа, и списание покрывает их все. Требует скоуп trade и Idempotency-Key. Поле тела periodId - один из 1m, 3m, 6m, 12m.

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: renew-unique-id" \
  -d '{"periodId":"1m"}' \
  https://api.sotaproxy.com/api/v1/proxies/PROXY_ID/renew

{
  "proxyId": "2364b03b-...", "newExpiresAt": "2026-10-01T00:00:00.000Z",
  "amountCharged": 2, "proxiesRenewed": 10, "currency": "USD",
  "idempotentReplay": false
}

Резидентские устроены иначе, чем продукты со сроком: ты покупаешь пакет трафика в ГБ, а затем создаёшь внутри него один или несколько эндпоинтов. Каждый эндпоинт закрепляет необязательный гео-таргетинг (страна / регион / город / провайдер) и ротацию и возвращает готовые данные для подключения к шлюзу. Трафик списывается из пакета по мере использования эндпоинтов.

1. Тарифы - GET /residential/plans показывает пакеты ГБ с ценами твоего аккаунта (контрактная цена за ГБ применяется автоматически).

2. Гео-каталог - GET /residential/locations возвращает страны; добавь ?country=AT для регионов, городов и провайдеров.

3. Покупка пакета - требует скоуп trade и Idempotency-Key:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: res-unique-id" \
  -d '{"planId":"ind_3gb"}' \
  https://api.sotaproxy.com/api/v1/residential/orders

{
  "package": { "id": "81cdc5d0-...", "plan": "3 GB", "trafficGb": 3,
    "pricePerGb": 2, "totalPrice": 6, "trafficLeftGb": 3,
    "active": true, "expiresAt": "2026-08-22T23:59:59.000Z" },
  "amountCharged": 6, "currency": "USD", "idempotentReplay": false
}

4. Создание эндпоинта (гео закрепляется здесь) - ответ содержит доступы, которые можно сразу вставить в любой клиент:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"packageId":"81cdc5d0-...","name":"Austria sticky","country":"AT","rotation":-1}' \
  https://api.sotaproxy.com/api/v1/residential/lists

{
  "list": { "id": "d7e8cbf4-...", "country": "AT", "rotation": -1, ... },
  "proxy": {
    "host": "proxy.sotaproxy.com", "portHttp": 10000, "portSocks": 10000,
    "login": "3c4d8398...", "password": "fTYRr2CH...",
    "httpUrl": "http://login:password@proxy.sotaproxy.com:10000",
    "socksUrl": "socks5://login:password@proxy.sotaproxy.com:10000"
  }
}

rotation: 0 = новый IP на каждый запрос, -1 = sticky-сессия, 1–3600 = секунды между ротациями. Управляй эндпоинтами через GET /residential/lists, DELETE /residential/lists/{id}; следи за расходом через GET /residential/packages.

Мобильные прокси продаются помодемно из фиксированного каталога тарифов (страна + оператор + срок аренды). Выбери тариф, купи N штук - дальше заказ ведёт себя как любой другой: GET /orders/{id}/proxies вернёт доступы.

curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/mobile/tariffs?country=DE"

{
  "tariffs": [
    { "id": "mt_f1098dbc7be7a1b0", "country": "DE", "carrier": "Vodafone Germany",
      "periodId": "day", "period": "1 day", "unitPrice": 8.64,
      "dedicated": true, "stock": 16 }
  ],
  "currency": "USD"
}

Покупка - требует скоуп trade и Idempotency-Key:

curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: mob-unique-id" \
  -d '{"tariffId":"mt_f1098dbc7be7a1b0","quantity":1}' \
  https://api.sotaproxy.com/api/v1/mobile/orders

Тарифы ограничены наличием - всегда проверяй stock перед заказом. Мобильные прокси также видны в GET /proxies?product=mobile.

Читай предоплаченный баланс или аккаунт и скоупы, к которым привязан ключ.

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/balance
# → {"balance":42.5,"currency":"USD"}

curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/me
# → {"accountId":"...","scopes":["read","trade"]}

Партнёр со своей платформой держит пользователей, регистрации и балансы у себя. От нас ему нужна возможность нарезать уже купленный запас: завести клиента, выдать ему объём, выпустить доступы и прочитать расход для собственных счетов.

Требуется признак is_reseller на аккаунте. Для записи нужен скоуп trade. Те же операции есть в кабинете, и оба входа зовут один и тот же сервис.

Полный цикл

Пять вызовов ведут клиента от регистрации до счёта. Трафик везде возвращается в обеих единицах: {"mb": 1024, "gb": 1}.

# 1. how much can I hand out right now
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/stock

# 2. a new client signed up on your platform
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"acme-corp"}' https://api.sotaproxy.com/api/v1/reseller/clients
# → {"client":{"id":"<clientId>", ...}}

# 3. they paid you for 10 GB
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -H "Idempotency-Key: order-8412" \
  -d '{"trafficGb":10}' https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/traffic

# 4. issue their credentials
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"name":"main","ports":5,"rotation":-1,"country":"US"}' \
  https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/access
# → login/password + host + portFrom..portTo + readyInSeconds

# 5. bill them: poll usage on your schedule
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/usage

Со статическими прокси всё иначе

Трафик делится, адрес нет. IPv4, IPv6 и ISP можно только закрепить за клиентом, разделить нельзя. Владельцем и плательщиком остаётесь вы, поэтому продления и автопродление продолжают идти с вашего баланса, а отношения с клиентом нас не касаются. Открепление возвращает прокси в ваш свободный пул нетронутым.

# what is free to hand out right now
curl -H "Authorization: Bearer $KEY" "https://api.sotaproxy.com/api/v1/reseller/proxies?filter=free&type=ipv4"

# pin two of them to a client
curl -X POST -H "Authorization: Bearer $KEY" -H "Content-Type: application/json" \
  -d '{"proxyIds":["<id1>","<id2>"]}' https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/proxies
# → {"requested":2,"assigned":2}

# what that client holds, with credentials to hand over
curl -H "Authorization: Bearer $KEY" https://api.sotaproxy.com/api/v1/reseller/clients/<clientId>/proxies

Заметки, которые экономят обращение в поддержку

• ·Доступам нужно около 90 секунд, прежде чем они начнут авторизовываться: вышестоящая сеть регистрирует их асинхронно. До этого соединения отвечают 407. В ответе на выпуск приходит readyInSeconds, чтобы вы могли придержать показ доступов своему пользователю.
• ·`rotation`: -1 держит липкую сессию, 0 даёт новый IP на каждый запрос, любое другое значение это число секунд до смены IP.
• ·Порты: один доступ занимает диапазон portFrom..portTo, и каждый порт это независимая сессия со своим IP. Один и тот же порт обслуживает и HTTP, и SOCKS5.
• ·Выдача ограничена реальным запасом, а не сырым остатком: трафик, уже отданный другим клиентам, вычитается заранее.
• ·Иерархия одноуровневая. У клиента не может быть своих клиентов, и входа в наш кабинет ваши клиенты не получают. Ваши пользователи живут на вашей платформе, в этом и смысл этого API.
• ·assigned сообщает, что произошло на самом деле при закреплении прокси. Чужие или уже исчезнувшие идентификаторы пропускаются, а не роняют весь вызов, поэтому сравнивайте его с requested, если нужно реагировать.

Подключи SotaProxy к Claude (или любому ИИ-ассистенту с поддержкой MCP) и управляй прокси просто в чате: «купи мне 5 ISP-прокси США на месяц», «возьми 3 ГБ резидентского трафика с гео Австрия», «какой у меня баланс?». Ассистент всегда показывает точную цену и спрашивает подтверждение, прежде чем что-то потратить. Полный гайд по MCP со всеми 18 инструментами →

https://api.sotaproxy.com/mcp?key=sk_live_YOUR_KEY

claude mcp add --transport http sotaproxy https://api.sotaproxy.com/mcp \
  --header "Authorization: Bearer sk_live_YOUR_KEY"

{
  "mcpServers": {
    "sotaproxy": {
      "url": "https://api.sotaproxy.com/mcp",
      "headers": { "Authorization": "Bearer sk_live_YOUR_KEY" }
    }
  }
}

Если что-то не работает: ошибка аутентификации значит, что ключ неверный или отозван, - создай новый в кабинете. Если покупка падает с ошибкой скоупа, у ключа нет trade. Покупки списываются с предоплаченного баланса - сначала пополни его в кабинете. Ключи в URL - чувствительные данные: где возможно, используй заголовок и отзывай ключи, которыми больше не пользуешься.