API-ключ биржи — это пара API Key и API Secret. По этому ключу программы и сервисы работают с аккаунтом через API: читают баланс, открывают и закрывают сделки и выполняют другие операции, разрешённые для этого ключа, без входа в веб-кабинет.
Цель материала: описать ограничения, которые биржа применяет к API-запросам: проверку подписи через API Secret, права ключа (permissions), привязку источника запроса к IP whitelist, ограничения вывода через whitelist адресов и изоляцию баланса через sub-accounts. Эти ограничения снижают риск, что утечка пары API Key + API Secret приведёт к выводу активов или к убыточным сделкам.
🧭 Как работает контроль API-доступа на криптобиржах
API-ключи используют торговые боты, терминалы, сервисы отчётности и внутренние интеграции. Биржа исполняет API-запрос только после проверки подписи (API Secret), прав на операцию (permissions), IP-адреса источника (IP whitelist) и времени запроса (timestamp и recvWindow). Проверка времени блокирует повтор запроса позже, даже если запрос перехватили.
Риск по API снижают настройками ключа. IP whitelist принимает запросы только с указанных IP-адресов. Permissions ограничивают набор операций, которые биржа выполнит по ключу. Whitelist адресов вывода ограничивает список получателей. Sub-accounts разделяют баланс и ключи между субсчетами, чтобы один ключ не имел доступа ко всем активам аккаунта.
🔍 Как биржа проверяет API-запрос: подпись, права, IP и время
API-ключ состоит из API Key (идентификатор ключа) и API Secret (секрет для подписи). Подпись подтверждает для биржи, что запрос сформирован с использованием API Secret и не был изменён по пути.
- Формирование параметров запроса к API-эндпоинту биржи (адресу API, который принимает конкретную операцию)
- Запрос задаёт операцию: открыть или отменить ордер, получить баланс, выполнить перевод или запустить вывод.
- Запрос содержит временную метку (timestamp) и иногда окно допустимого времени (recvWindow). Биржа сравнивает эти значения со своим временем и отклоняет запрос, если он выходит за допустимый интервал.
- Подписание параметров запроса через HMAC
- HMAC — хэш-подпись по секретному ключу. Строка параметров подписывается ключом API Secret.
- Биржа пересчитывает HMAC по тем же параметрам и сравнивает подпись. Несовпадение означает, что отправитель не владеет API Secret или параметры были изменены.
- Проверка ограничений ключа и решение об исполнении
- Permissions задают, какие операции разрешены для ключа (read/trade/transfer/withdraw у большинства централизованных бирж, CEX).
- IP whitelist ограничивает источники запросов. Биржа отклоняет запрос, если IP отправителя не входит в белый список ключа.
- Исполнение операции и возврат результата
- Если прав недостаточно, биржа возвращает отказ и не выполняет операцию, даже при корректной подписи.
- Если IP не совпадает, биржа возвращает отказ на этапе авторизации и не переходит к торговой или выводной операции.
Компоненты API-доступа, которые контролируются биржей
Биржа снижает риск по API тремя проверками в каждом запросе: подпись через API Secret, permissions для операций и IP whitelist для источника запроса.
- API Secret хранится только в хранилище секретов и в памяти процесса, который подписывает запросы.
- Permissions включают под задачу ключа: чтение для отчётности, торговля для бота, вывод только для операционных выплат.
- IP whitelist содержит только IP серверов, которые реально отправляют запросы, чтобы список не расширял поверхность атаки.
Если злоумышленник получил API Key без API Secret, биржа отклонит запрос из-за неверной подписи. Если злоумышленник получил API Key и API Secret, биржа отклонит запрос, когда permissions не разрешают операцию или IP не входит в whitelist.
🎯 Какие потери возможны по API: вывод, переводы и торговый убыток
Ущерб по API зависит от включённых permissions и от баланса, доступного этому ключу. Trade-only ключ несёт меньший риск на субаккаунте с небольшим рабочим балансом и больший риск на субаккаунте с основным капиталом.
Три сценария, которые исполняются биржей по API
Потери по API возникают через вывод, внутренний перевод или сделки, которые приводят к убытку по цене исполнения.
- Прямой вывод: ключ с withdraw permission запускает вывод на адрес, который биржа пропустит после своих проверок и правил whitelist.
- Внутренний перевод: ключ с transfer permission перемещает активы между кошельками продукта или между субаккаунтами, если биржа разрешает такие операции по API.
- Торговый убыток без вывода: ключ с trade permission выставляет ордера на низколиквидной паре и исполняет сделки по худшей цене, создавая убыток из проскальзывания, спреда и комиссий.
Отключённый withdraw permission убирает прямой вывод. Trade permission остаётся источником убытка, если на торговом кошельке хранится крупный баланс и ключ не ограничен по IP и по инструментам.
Сигналы, после которых проверка API становится необходимой
- Появились ордера, которые не соответствуют логике торговой системы и расписанию запуска.
- Появились переводы между кошельками или субаккаунтами без операционной причины.
- В настройках ключа появились новые permissions или был удалён IP whitelist.
- В логах торговой системы появились ошибки подписи и выросла частота запросов при неизменном коде.
🌐 IP whitelist: привязка ключа к серверу-источнику запросов
IP whitelist заставляет биржу принимать запросы только с заранее указанных IP-адресов. Если API Secret попал в код, логи, резервные копии или сторонний сервис, злоумышленник не сможет отправить запрос с IP, которого нет в whitelist.
Выбор стабильного источника API-запросов
- VPS (виртуальный сервер) с постоянным публичным IP подходит для IP whitelist и для непрерывной работы торговой системы.
- Домашний интернет с динамическим IP не подходит, потому что смена IP вызывает отказы API-запросов до обновления whitelist.
Настройка IP whitelist для API-ключа
- IP whitelist включает IP сервера торговой системы и резервного сервера, если резервный сервер реально используется.
- Если биржа поддерживает CIDR (запись подсети, например 203.0.113.10/32), задают минимальный диапазон, чтобы не расширять список источников.
Проверка отказоустойчивости API-доступа
- Резервный API-ключ на отдельный IP используют при миграции инфраструктуры и смене адреса сервера.
- Порядок обновления IP whitelist фиксируют заранее, чтобы смена IP не совпала с потерей контроля над ордерами.
В облачной инфраструктуре запросы могут выходить в интернет через NAT (преобразование адресов на границе сети). В этом случае внешний IP, который видит биржа, может отличаться от IP контейнера или виртуальной машины. В IP whitelist указывают egress IP (внешний IP исходящего трафика), иначе биржа будет отклонять запросы.
IP whitelist не защищает от компрометации VPS. При захвате сервера злоумышленник отправит запросы с того же IP, поэтому защита доступа к VPS и контроль обновлений остаются частью защиты API.
IP whitelist блокирует запросы с чужих серверов, потому что биржа сравнивает IP источника с whitelist и отклоняет запрос до исполнения торговой или выводной операции.
🔑 Permissions: какие права выдаются ключу под конкретную задачу
Permissions определяют, какие API-эндпоинты биржа разрешит вызывать по этому ключу. Названия прав зависят от биржи, но схема обычно одинаковая: read для чтения, trade для ордеров, transfer для внутренних переводов и withdraw для вывода в блокчейн.
| Задача | Разрешить | Запретить | Блокируемая операция |
|---|---|---|---|
| Скринер/аналитика | Read | Trade; Transfer; Withdraw | Выставление ордеров и перемещение активов |
| Торговый бот | Read; Trade | Withdraw | Прямой вывод средств по API |
| Отчётность | Read | Trade; Transfer; Withdraw | Операции при компрометации сервиса отчётности |
| Операционные переводы | Read; Transfer | Trade; Withdraw | Торговые операции и вывод в блокчейн |
Read-only ключ для мониторинга и отчётности
Read-only ключ используют, когда системе нужно читать балансы, историю сделок и статусы позиций, но нельзя менять состояние аккаунта.
- Read-only ключ блокирует выставление и отмену ордеров, потому что биржа отклоняет торговые эндпоинты по этому ключу.
- IP whitelist ограничивает доступ к данным конкретным сервером и блокирует запросы с чужих IP при утечке API Secret.
- Отдельный read-only ключ для отчётности отделяет риск сервиса отчётности от риска торгового ключа.
Read-only ключ раскрывает баланс и историю, но не позволяет вывод и сделки, потому что биржа отклоняет эндпоинты trade/transfer/withdraw.
Trade ключ для торговой системы без вывода
Trade ключ используют для выставления и отмены ордеров. Withdraw permission для торговых операций не нужен.
- Trade permission даёт доступ к управлению ордерами и позициями в рамках рынков аккаунта.
- Отключённый withdraw permission блокирует вывод, потому что биржа отклоняет выводные эндпоинты по этому ключу.
- IP whitelist привязывает ключ к серверу торговой системы и блокирует запросы с чужих машин при утечке API Secret.
Trade-only ключ создаёт риск для средств на торговом кошельке, поэтому торговый sub-account обычно держит рабочий баланс, а не основной капитал.
Transfer ключ для внутренних перемещений
Transfer ключ используют для переводов внутри биржи: между кошельками продукта или между sub-accounts, если биржа разрешает такие операции по API.
- Transfer permission позволяет выполнять внутренние переводы, которые не уходят в блокчейн.
- Отключённый trade permission исключает сделки, потому что переводной ключ не может создавать ордера.
- Отключённый withdraw permission исключает вывод в блокчейн при компрометации переводного ключа.
Разделение transfer и trade на разные ключи снижает ущерб при утечке, потому что один ключ не даёт одновременно доступ к сделкам и к перемещению активов.
Permissions определяют, какую операцию биржа разрешит по этому ключу. Лишние permissions расширяют набор действий, которые биржа выполнит по скомпрометированному ключу, поэтому права включают только под конкретный процесс.
🏷️ Защита вывода: whitelist адресов, подтверждения и лимиты
Withdraw permission позволяет API-ключу инициировать вывод средств из биржевого баланса в блокчейн. Защита вывода опирается на whitelist адресов получателя, контроль изменения whitelist и лимиты вывода.
В торговых интеграциях withdraw permission обычно отключают. Ордеры, отмена и чтение баланса выполняются внутри биржи и не требуют вывода в сеть. Для мониторинга и отчётности достаточно read-права. Для алгоритмической торговли достаточно trade-права.
Пример: торговый бот работает по ключу с trade permission и без withdraw permission. При компрометации ключа злоумышленник сможет открывать и закрывать сделки через торговые эндпоинты. Запрос на вывод биржа отклонит, потому что у ключа нет withdraw permission.
Whitelist адресов ограничивает получателя вывода: биржа отправляет средства только на заранее добавленные адреса. На многих биржах добавление адреса в whitelist требует 2FA (двухфакторная аутентификация) и подтверждения через отдельный канал, например email, приложение или аппаратный ключ. В этом случае вывод на новый адрес зависит не только от API-ключа, но и от контроля этих каналов подтверждения.
Задержка на изменение whitelist (security lock, холд) не активирует добавленный адрес сразу. При включённой задержке вывод на новый адрес блокируется на время холда, поэтому добавление адреса можно заметить до первого вывода.
API-подключение торговых роботов, trade-only ключи и IP whitelist раскрыты в материале «Заработок с торговыми роботами в криптовалюте».
Лимиты вывода ограничивают сумму потерь, если злоумышленник получил ключ, который проходит проверки whitelist и подтверждений. Дневной лимит задают под суммы регулярных операционных выплат, а не под общий баланс аккаунта, чтобы один цикл вывода не позволял вывести весь депозит.
Компрометация почты повышает риск, потому что на многих биржах подтверждения добавления адресов и сброс настроек безопасности завязаны на email, включая ссылки подтверждения и уведомления о смене whitelist.
Withdraw permission без whitelist адресов делает утечку API-ключа прямым каналом вывода в блокчейн. Withdraw permission с whitelist адресов и с задержкой на изменение whitelist переносит критический риск на компрометацию каналов подтверждения. Лимиты вывода ограничивают сумму потерь при обходе остальных ограничений.
🛡️ Sub-accounts: изоляция баланса, ключей и процессов
Sub-accounts разделяют баланс и API-ключи внутри одной биржи. При утечке ключа операции ограничиваются активами конкретного sub-account.
- Разделение хранения и торговли на разные sub-accounts
- Sub-account хранения держит основной капитал и не использует постоянные торговые API-ключи.
- Торговые sub-accounts держат рабочие балансы под конкретных ботов и стратегии.
- Контроль внутренних переводов по API
- Отключение transfer permission на торговых ключах снижает возможность перемещения активов при утечке торгового ключа.
- Выделенный transfer ключ используют, когда внутренние переводы входят в операционный процесс.
- Ограничение инструментов ключа при поддержке whitelist торговых пар
- Whitelist торговых пар блокирует сделки по инструментам, которые не относятся к торговой системе.
- Ограничение пар снижает риск убытка на низколиквидных рынках.
Схема изоляции для нескольких торговых систем
Схема изоляции разделяет баланс через sub-accounts и разделяет доступ через API-ключи, permissions и IP whitelist.
- Одна торговая система на одной бирже работает через отдельный sub-account и trade-only ключ, привязанный к IP VPS.
- Отчётность подключают read-only ключом на отдельный сервер, чтобы утечка отчётности не раскрывала торговый ключ.
- Операционные переводы выполняют transfer ключом без trade и withdraw permissions.
При утечке ключа торговой системы биржа выполняет операции только в рамках баланса её sub-account, поэтому потери ограничиваются рабочим балансом.
🗄️ Хранение секретов и ротация: как API Secret утекает из инфраструктуры
API Secret чаще утекает не через биржу, а из инфраструктуры торговой системы: из репозиториев кода, CI/CD-пайплайнов (автоматизированных процессов сборки и деплоя), логов приложений, дампов баз данных, скриншотов и резервных копий. Управление секретами фиксирует места хранения API Secret и роли, которые могут получить к нему доступ.
API Secret не хранят в коде приложения. Значение секрета подставляют при запуске сервиса из защищённого хранилища и не сохраняют в файлах проекта или в репозитории. В коде и конфигурации остаётся ссылка на секрет, а не его значение.
Пример: торговый бот разворачивается через CI/CD. В репозитории хранится только имя секрета, а значение API Secret подставляется на этапе деплоя из защищённого хранилища. При утечке кода и истории коммитов API Secret в них отсутствует.
В production API Secret хранят в secret manager — сервисе, который держит секреты в зашифрованном виде и выдаёт их только процессам с разрешением через IAM (управление доступом через роли). Эта схема отделяет production-секреты от dev-окружений и тестовых сервисов.
Поведенческие причины ошибок при работе с риском и торговым планом разобраны в материале «Психология трейдера».
Ротация API-ключей снижает риск долгоживущей утечки. Ротация включает создание нового ключа на бирже, переключение системы на новый API Secret и отзыв старого ключа, чтобы биржа перестала принимать подпись по старому секрету.
Переключение планируют на период без открытых позиций и активных лимитных ордеров, чтобы смена API Secret не прервала управление ордерами и риск-контуром.
Минимальные правила хранения API Secret
- API Secret хранится в secret manager или в зашифрованном хранилище с контролем доступа.
- API Secret не попадает в Git, Docker image, CI artifacts и резервные копии в открытом виде.
- Production-секрет недоступен из dev-среды и недоступен ролям, которые не запускают торговую систему.
- Ротация включает отзыв старого ключа после переключения, чтобы старый secret перестал работать на стороне биржи.
Permissions, IP whitelist и whitelist адресов защищают на стороне биржи, а secret management снижает риск утечки API Secret из кода и логов на стороне инфраструктуры.
🧩 Сторонние терминалы и боты: как подключение влияет на риск
Сторонний сервис получает API Key и API Secret, чтобы подписывать запросы от имени аккаунта. Если сервис принимает ключ в веб-кабинете, API Secret хранится в инфраструктуре провайдера. При инциденте у провайдера злоумышленник сможет подписывать запросы и проходить проверку подписи на стороне биржи.
✅ Признаки управляемого риска
- Сервис работает с read-only и trade-only ключами и не требует withdraw permission для торговли и отчётности.
- Сервис показывает журнал API-действий: созданные ордера и вызванные эндпоинты.
- Сервис поддерживает подключение через отдельный sub-account с ограниченным рабочим балансом.
❌ Признаки повышенного риска
- Сервис требует withdraw permission для функций, которые не связаны с операционными выплатами.
- Сервис требует отключить IP whitelist и не предлагает модель с агентом на стороне пользователя и фиксированным IP.
- Сервис не даёт историю API-действий, поэтому расследование опирается на косвенные признаки.
Пример конфигурации: сигналы и отчётность используют read-only ключ, торговые операции используют trade-only ключ на sub-account с рабочим балансом, вывод по API отключён.
Сторонний сервис не отменяет ограничения биржи. Sub-account, IP whitelist, минимальные permissions и отключённый withdraw permission ограничивают риск рабочим балансом.
🧯 Реакция на утечку ключа: остановка исполнения и фиксация следов
При подозрении на утечку пары API Key + API Secret риск развивается быстро, потому что биржа исполняет операции сразу после проверки подписи, прав, IP и времени запроса. Реакция начинается с остановки авторизации по ключу и фиксации следов операций.
- Отзыв ключа на стороне биржи
- Отключение или удаление ключа прекращает приём подписанных запросов по этому API Key.
- Отключение всех ключей sub-account используют, если источник утечки не определён.
- Фиксация следов операций
- Список открытых ордеров и история сделок за период аномалии показывают, какие операции успели исполниться.
- История выводов и изменения whitelist адресов показывают попытки вывода и подготовку адресов.
- Закрытие дополнительных каналов доступа к аккаунту
- Смена пароля и проверка 2FA снижают риск входа в веб-интерфейс.
- Проверка безопасности почты нужна, потому что подтверждения вывода и изменения whitelist часто завязаны на email.
- Восстановление рабочего доступа
- Новый ключ создают с минимальными permissions и с IP whitelist на актуальный сервер.
- API Secret обновляют в secret manager, чтобы старый секрет перестал использоваться.
Отзыв ключа останавливает исполнение действий, потому что биржа перестаёт принимать подпись по этому API Key, даже если запросы продолжают поступать.
✅ Конфигурация, которая снижает риск вывода при утечке ключа
Риск вывода после утечки пары API Key + API Secret снижается, когда trade ключ не имеет withdraw permission, запросы ограничены IP whitelist, а основной капитал отделён от торгового sub-account.
Минимальный набор параметров для trade ключа торговой системы
- Торговая система работает на VPS с фиксированным IP, и этот IP добавлен в IP whitelist ключа.
- Ключ имеет permissions read + trade и не имеет withdraw permission.
- Торговый sub-account содержит рабочий баланс, а основной капитал хранится отдельно без постоянных торговых ключей.
- API Secret хранится в secret manager или в зашифрованном хранилище и не попадает в репозитории и логи.
IP whitelist, минимальные permissions, whitelist адресов для редких выводов и изоляция через sub-accounts ограничивают ущерб рабочим балансом и снижают риск вывода в блокчейн по скомпрометированному ключу.
❓ FAQ по безопасности API-ключей
Почему IP whitelist защищает даже при утечке API Secret?
Биржа сравнивает IP источника запроса с IP whitelist ключа и отклоняет запрос, если IP не совпадает. Подпись HMAC может быть корректной, но операция не будет выполнена, потому что проверка IP происходит на стороне биржи.
Когда withdraw permission действительно нужен?
Withdraw permission нужен для автоматических операционных выплат в блокчейн. Для торговли, мониторинга и отчётности withdraw permission не нужен, потому что эти процессы используют торговые и читательские эндпоинты внутри биржи.
Почему trade-only ключ может привести к потерям без вывода?
Trade-only ключ позволяет выставлять ордера. При доступе к trade-only ключу злоумышленник может исполнять сделки по худшей цене на низколиквидной паре и создавать убыток из проскальзывания, спреда и комиссий при крупном балансе на торговом кошельке.
Зачем отдельный sub-account для каждой торговой системы?
Sub-account ограничивает баланс, доступный ключу. При утечке ключа торговой системы ущерб ограничивается активами этого sub-account, потому что биржа выполняет операции внутри баланса конкретного sub-account.
Как ротировать ключи без потери контроля над ордерами?
Ротация включает создание нового ключа, переключение торговой системы на новый API Secret и отзыв старого ключа. Переключение планируют на период без открытых позиций и активных лимитных ордеров, чтобы смена ключа не прервала управление ордерами.
Как подключение стороннего терминала ограничивается по риску?
Риск ограничивают trade-only ключом на sub-account с рабочим балансом, IP whitelist (если запросы идут через агент на стороне пользователя) и отключённым withdraw permission, когда терминал не участвует в операционных выводах.
🧷 Как ограничения API снижают риск вывода и торгового ущерба
Риск по API зависит от разрешённых операций и от проверок, которые биржа применяет к каждому запросу: подпись (API Secret), permissions, IP whitelist и параметры времени запроса.
- Отключённый withdraw permission блокирует вывод в блокчейн по API, потому что биржа отклоняет выводные эндпоинты для ключа без этого права.
- Whitelist адресов вывода ограничивает получателя, потому что биржа отправляет средства только на заранее добавленные адреса.
- IP whitelist ограничивает источник запросов, потому что биржа отклоняет запросы с IP, которых нет в списке ключа, даже при корректной подписи.
- Sub-accounts ограничивают объём потерь, потому что ключ получает доступ к балансу конкретного sub-account, а не ко всем активам аккаунта.