FreeProxy Relay API

HTTP API для изолированного выполнения внешних HTTP/HTTPS-запросов через серверный пул прокси. Отдаёт статус, очищенные заголовки, cookies и тело ответа целевого сайта — в JSON-конверте или прямым потоком байт.

Шлюз никогда не раскрывает клиенту учётные данные прокси (host:port:user:pass) и никогда не отправляет запросы со своего реального IP. Если пул недоступен, сервер возвращает 503.

Base URL

https://freeproxy.eu.cc/v1

Формат

JSON, UTF-8 (или сырой поток при response_mode: "raw")

Ключ

Заголовок X-API-Key

Шифрование

TLS 1.3 + опционально X25519 + ChaCha20-Poly1305

Лимит Free

30 запросов в минуту, 1 000 запросов и 250 МБ в сутки

Для закрепления одного выходного узла за серией запросов передавайте поле session. Для клиентского софта, где возможен локальный перехват трафика (HTTP Toolkit, Fiddler, mitmproxy), используйте POST /v1/fetch/sealed.

Как устроен поток

Быстрый старт

От выпуска бесплатного ключа до первого запроса через шлюз проходит меньше минуты.

1. Получите ключВыпустите Free-ключ в консоли ниже или запросом POST /v1/keys/free. VIP-ключи с повышенными квотами выдаёт оператор.
2. Сохраните в окружениеПоложите ключ в переменную FREEPROXY_KEY — не храните его в исходном коде и репозитории.
3. Отправьте запросПередайте целевой url и опциональный идентификатор session в POST /v1/fetch.
4. Включите защиту для софтаЕсли код запускается на машинах пользователей, переключитесь на POST /v1/fetch/sealed с шифрованием X25519.

Получить ключ и проверить квоты

Бесплатный тариф позволяет мгновенно выпустить до двух ключей в сутки на одну /24 подсеть. Секрет api_key и hmac_secret хранятся на сервере в хэшированном виде и показываются только один раз при создании.

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

Защищённые эндпоинты (/v1/fetch, /v1/fetch/sealed, /v1/keys/me) требуют API-ключ в заголовке X-API-Key либо Authorization: Bearer <key>.

Бесплатные ключи имеют префикс fp_free_, выделенные операторские ключи — fp_vip_. При выдаче также возвращается hmac_secret для опциональной криптографической подписи тела запроса.

Не встраивайте открытый ключ в веб-фронтенд: любой посетитель заберёт его через DevTools. Для распространяемого десктопного софта обязательно включайте Sealed Mode и TLS SPKI Pinning.

Опциональная подпись HMAC-SHA256

Чтобы защитить обычный запрос /v1/fetch от модификации и повторной отправки (replay), передайте три заголовка: X-FP-Timestamp (Unix-время в секундах), X-FP-Nonce (случайная строка 8–128 символов) и X-FP-Signature = HMAC_SHA256(hmac_secret, "{ts}.{nonce}.{sha256_hex(raw_body)}").

Ошибки аутентификации

Лимиты

Лимит запросов в минуту считается по скользящему окну в 60 секунд (а не с начала календарной минуты). При превышении сервер отвечает 429 RATE_LIMIT_EXCEEDED и заголовком Retry-After — через сколько секунд освободится слот.

Суточные квоты запросов и трафика сбрасываются в 00:00 UTC. Параллельные соединения ограничиваются на уровне активных in-flight запросов ключа.

Сравнение тарифов

Заголовки лимита

Каждый авторизованный ответ несёт состояние окна — следите за остатком и не доводите воркеры до 429:

Ошибки

Все ошибки шлюза возвращают JSON с "ok": false и объектом error. Ветвите логику кода по полю error.code, а не по тексту error.message: формулировка может уточняться, машинный код стабилен.

Повторы и таймауты

Шлюз сам делает до 2 внутренних попыток через альтернативные узлы пула при сетевом сбое прокси. Если целевой сайт всё же вернул временную ошибку доставки, клиент на вашей стороне должен уметь безопасно повторить запрос.

Правила надёжного клиента:

• повторяйте только коды шлюза 429 (кроме DAILY_*_QUOTA_EXCEEDED), 500, 502, 503, 504;
• никогда не повторяйте 403: повторные обращения к заблокированным доменам или путям накопят страйки и приведут к автобану ключа и /24 подсети;
• учитывайте заголовок Retry-After, если он пришёл в ответе;
• задавайте внешний HTTP-таймаут клиента чуть больше поля timeout в JSON (например, timeout: 20 в теле и 35 секунд на сокете).

Объекты Relay

Запрос к шлюзу описывается объектом RelayRequest, а результат в стандартном режиме (response_mode: "json") возвращается в виде RelayResponse.

RelayRequest

RelayResponse

Выполнить запрос

Основной эндпоинт шлюза. Принимает объект RelayRequest, выполняет HTTP/HTTPS-запрос через пул прокси и возвращает конверт RelayResponse (либо сырой поток при response_mode: "raw").

Обратите внимание на разницу статусов: HTTP-статус самого ответа /v1/fetch отражает работу шлюза (200 — запрос доставлен, 429 — лимит, 503 — нет пула), а код ответа целевого сайта лежит внутри JSON в поле status_code.

Заголовки ответа

X-RateLimit-Limit, X-RateLimit-Remaining, X-RateLimit-Reset, X-FP-Request-Id, X-FP-Elapsed-Ms.

Ошибки

400, 401, 403, 413, 422, 429, 500, 502, 503, 504. Подробнее в разделе «Ошибки».

Защищённый запрос (Sealed)

Криптографический конверт поверх HTTPS против локальных MITM-снифферов (HTTP Toolkit, Fiddler, Charles, mitmproxy). Даже если пользователь установил свой корневой сертификат в систему, в перехваченном трафике видны только случайные base64url-поля — ни целевой url, ни заголовки, ни тело ответа не читаются.

Поля запроса

Ключи шифрования выводятся через HKDF-SHA256(shared_secret, salt = epk || server_pub, info = "freeproxy-seal-v1", len = 64): первые 32 байта — ключ запроса, вторые 32 байта — ключ ответа (AAD ответа = jti). Полная реализация приведена в разделе «Защита софта (Sealed Mode)».

Выпустить Free-ключ

Публичный эндпоинт автоматического выпуска бесплатного ключа. Ограничен лимитом до 2 ключей в сутки на IP / /24 подсеть.

Параметры тела

Ошибки

403 FREE_TIER_DISABLED, 403 ACCESS_SUSPENDED, 429 FREE_KEY_QUOTA_REACHED.

Квоты ключа

Возвращает тариф ключа, расход запросов и трафика за текущие сутки UTC, остаток в минутном окне и число активных штрафных баллов безопасности.

Обратите внимание: вызов GET /v1/keys/me проходит через ту же проверку ключа и учитывается в минутном окне RPM, но не расходует суточную квоту Relay-запросов.

Публичный ключ X25519

Публичный эндпоинт, отдающий статический публичный ключ сервера X25519 (в формате base64url) и идентификатор key_id для работы с POST /v1/fetch/sealed.

В продакшн-софте рекомендуется зашить значение public_key в конфигурацию клиента, чтобы исключить лишний сетевой запрос при старте.

Статус шлюза

Публичная сводка готовности шлюза: флаг наличия здоровых выходных узлов relay_capacity_ready, список доступных ISO-стран пула countries_available, активные функции и базовые параметры Free-тарифа.

Защита софта (Sealed Mode)

Когда ваш скрипт или десктопное приложение запускается на чужом ПК, пользователь может включить HTTP Toolkit, Fiddler или Proxifier с подменным корневым сертификатом. Справа приведён полный клиент Sealed Mode, который защищает трафик на прикладном уровне.

1. Отключите системные прокси ОССоздавайте HTTP-клиент с игнорированием переменных HTTP_PROXY / HTTPS_PROXY (в Python — trust_env=False).
2. Получите публичный ключ шлюзаЗапросите GET /v1/crypto/pubkey один раз или зашейте 32-байтовый ключ в константу.
3. Сгенерируйте эфемерную пару X25519На каждый запрос создавайте новый одноразовый ключ epk, вычисляйте общий секрет и выводите пару ключей req_key / resp_key через HKDF-SHA256.
4. Запечатайте запрос и распечатайте ответЗашифруйте {ts, jti, request} алгоритмом ChaCha20-Poly1305 (AAD = api_key), отправьте в POST /v1/fetch/sealed и расшифруйте ответ с AAD = jti.

Зависимости для примеров

OpenAPI, Postman, Swagger

Спецификация публичных и Relay-эндпоинтов доступна в файле openapi.yaml (OpenAPI 3.0.3). Импортируйте её напрямую по ссылке, чтобы получить готовую коллекцию или сгенерировать типизированный SDK.

Postman и Insomnia

Import → Link → вставьте https://freeproxy.eu.cc/docs/openapi.yaml. На вкладке Authorization укажите тип API Key, имя заголовка X-API-Key.

Генерация клиента

Через OpenAPI Generator можно сгенерировать клиент под любой из 50+ языков одной командой.