Документація 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 - чутливі дані: де можливо, використовуй заголовок і відкликай ключі, якими більше не користуєшся.