Руководство по API WEEX: настройка, вызовы, права доступа и безопасность

Если вы хотите, чтобы код получал цены, размещал ордера и управлял вашим аккаунтом, первое, что нужно сделать правильно, — это понять, как открывается, вызывается и, самое главное, как ограничивается API WEEX. API WEEX — это набор программных интерфейсов, которые WEEX открывает для разработчиков и количественных трейдеров, предоставляя доступ через REST и WebSocket, чтобы вы могли получать рыночные данные, размещать и отменять ордера, а также запрашивать данные аккаунта, не глядя на экран. Это руководство следует одной нити — что это такое, как использовать, как вызывать и безопасно ли это — и уделяет основное внимание части, которую большинство руководств пропускают: права доступа и безопасность API, где чаще всего возникают проблемы с потерей средств.

Все параметры интерфейса ниже взяты из официальной документации API WEEX и отражают публичную информацию по состоянию на июль 2026 года. Правила API могут меняться, поэтому сверяйтесь с центром разработчиков перед интеграцией.

Что такое API WEEX: краткая карта возможностей

В одну строку: API WEEX — это канал, позволяющий коду управлять вашим аккаунтом, разделенный на «публичный» и «приватный». Публичные эндпоинты возвращают рыночные данные и конфигурацию системы и не требуют аутентификации; приватные эндпоинты обрабатывают размещение ордеров, отмену и управление аккаунтом, и каждый запрос должен быть подписан. С точки зрения продукта, он охватывает как спотовую торговлю, так и фьючерсы с маржой в USDT по более чем 100 активам.

Выбор между REST и WebSocket сводится к тому, хотите ли вы «спросить один раз» или «постоянно слушать». Проверяйте баланс или отправляйте один ордер через REST; чтобы получать живые тики цен, изменения глубины или исполнения ордеров, держите соединение WebSocket — это проще и оперативнее.

Как получить ваш ключ API WEEX

Войдите на веб-платформу WEEX и создайте ключ на странице управления API. Система генерирует три вещи сразу, и вам нужны все три:

• APIKey — алгоритмически сгенерированный идентификатор, по сути, ваше «имя пользователя».
• SecretKey — выданный системой приватный ключ, используемый для подписи каждого запроса.
• Passphrase — кодовая фраза, которую вы определяете сами. Запомните это: если Passphrase потеряна, ее нельзя восстановить — вам придется удалить группу ключей и создать новую.

Каждый аккаунт может создать до 10 групп ключей API, что позволяет выпускать отдельные ключи для каждой стратегии и среды. Два выбора при создании задают уровень безопасности ключа: права доступа, которые вы отмечаете (следующий раздел), и IP, который вы привязываете. WEEX прямо указывает, что «неограниченный» ключ без привязки IP — это риск безопасности. Если IP вашего сервера фиксирован, заполните белый список IP.

Права доступа API WEEX: где заканчивается «только чтение» и начинается торговля

Этот раздел стоит прочитать дважды. Созданный ключ API по умолчанию имеет права «Только чтение». Чтобы торговать через API, вы должны вручную включить соответствующее разрешение на «Спотовую» торговлю. Слишком много разрешений означает больший убыток в случае утечки ключа; слишком мало — стратегия не сможет работать. Правило одно: предоставляйте минимум, который действительно нужен стратегии.

Одна деталь, которую легко упустить, но которая важна для безопасности: по состоянию на июль 2026 года разрешения, указанные в документации WEEX, — это только «Только чтение» и «Спотовая торговля» — без отдельного переключателя «Вывод средств». Для большинства стратегий это функция, а не пробел: даже если ключ утечет, тот, кто им владеет, не сможет вывести активы напрямую. Ориентируйтесь на опции, показанные на вашей странице создания ключа.

Как вызывать: что нужно для одного подписанного запроса

Весь барьер для приватных эндпоинтов — это шаг «подписи». WEEX генерирует подписи с помощью HMAC SHA256: зашифруйте строку перед подписью с помощью вашего SecretKey, затем закодируйте результат в Base64. Строка перед подписью собирается в фиксированном порядке:

timestamp + method (uppercase) + requestPath + "?" + queryString + body

queryString опускается, если он пуст. Возьмем запрос глубины GET: /api/v3/market/depth?symbol=BTCUSDT&limit=20 с меткой времени 1591089508404 дает строку 1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20.

После подписи каждый приватный запрос несет четыре заголовка:

Приватные каналы WebSocket работают так же — подпишите метку времени плюс путь запроса /v3/ws/private для входа. Место, где новички чаще всего застревают, — это не криптография, а метка времени: если метка времени вашего запроса отклоняется от времени сервера более чем на 30 секунд, запрос отклоняется. Неправильные локальные часы или устаревшая кэшированная метка времени вызовут ошибку 401. Синхронизация времени NTP перед запуском сэкономит половину времени на отладку. Полные поля и примеры есть в документации по интеграции и справочнике по подписям.

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

Вы не можете делать запросы так быстро, как хотите. Лимит по умолчанию — 10 запросов/секунду, некоторые эндпоинты имеют свои лимиты; превышение возвращает 429 Too Many Requests. Учитывайте базу подсчета: авторизованные запросы считаются по ключу API, неавторизованные — по публичному IP. Это значит, что несколько скриптов «только чтение» на одном сервере, использующие один исходящий IP, могут перекрывать друг друга.

Правило пакетной обработки: пакетный ордер, охватывающий 4 торговые пары по 10 ордеров в каждой, считается как один запрос. Группировка ордеров позволяет высокочастотной стратегии повысить пропускную способность и экономить квоту.

Безопасен ли API WEEX? Разделяйте контролируемое и нет

«Безопасно ли это» заслуживает большего, чем да/нет. На стороне платформы вы получаете подписанную аутентификацию, привязку IP, многоуровневые права и защиту от повторов на основе меток времени. Но в сценариях API большинство инцидентов происходит на стороне пользователя — ключи хранятся небрежно, права доступа слишком широкие, учетные данные вшиты во фронтенд или публичный репозиторий. Контролируемая часть полностью в ваших руках:

• Ограничьте права доступа до минимума; стратегия «только чтение» никогда не должна иметь прав на торговлю.
• Привяжите фиксированный IP к каждому ключу — никаких неограниченных ключей.
• Храните SecretKey и Passphrase в переменных окружения или менеджере секретов, никогда не вшивайте их в код или Git.
• Используйте разные ключи для разработки и продакшена.
• Ротируйте ключи по расписанию, и как только увидите аномальные вызовы, удалите ключ на платформе — ключ можно отозвать и пересоздать в любой момент.
• Настройте мониторинг активности аккаунта и объема вызовов.

Для более широкого обзора возможностей и частых вопросов см. статью WEEX о том, поддерживает ли WEEX API-торговлю. Соблюдайте чек-лист выше, и безопасность API WEEX будет зависеть в основном от вашей гигиены ключей.

Краткая версия

Путь к API WEEX прост: создайте ключ API с минимальными правами на веб-платформе (по умолчанию «Только чтение», торговля включается вручную), соберите трио APIKey / SecretKey / Passphrase и привяжите IP; при вызове приватных эндпоинтов подписывайте HMAC SHA256 в фиксированном формате, отправляйте все четыре заголовка, соблюдайте 30-секундное окно метки времени и лимит 10 запросов в секунду; наконец, обеспечьте гигиену ключей, принцип наименьших привилегий, белый список IP и оповещения. Для начала запустите первый запрос к публичным рыночным эндпоинтам в центре разработчиков WEEX, затем добавьте приватное размещение ордеров.

FAQ

1. Поддерживает ли WEEX API-торговлю?

Да. WEEX предлагает REST и WebSocket интерфейсы для автоматизированных рыночных данных, размещения и отмены ордеров, управления аккаунтом на споте и фьючерсах — подходит для количественных, сеточных и маркет-мейкинг ботов.

2. Сколько ключей API может создать один аккаунт?

До 10 групп. Лучше разделять их по стратегии и среде — ключ мониторинга, торговый ключ, ключ для тестов — чтобы они работали независимо.

3. Что если я забуду Passphrase?

Ее нельзя восстановить. Passphrase — это фраза, которую вы определяете при создании, система не хранит ее в открытом виде. Если потеряли, удалите группу ключей и создайте новую.

4. Почему мои приватные запросы отклоняются?

Самая частая причина — метка времени. Если она отклоняется от времени сервера WEEX более чем на 30 секунд, запрос отклоняется — синхронизируйте локальные часы. Затем проверьте порядок строки перед подписью, регистр метода и наличие всех четырех заголовков.

5. Если мой ключ API утечет, сможет ли злоумышленник вывести монеты?

Для спотового API риск ограничен — по состоянию на июль 2026 года разрешены только «Только чтение» и «Спотовая торговля», без отдельного разрешения на вывод. Тем не менее, немедленно удалите скомпрометированный ключ на платформе и проверьте наличие аномальных ордеров.

6. Есть ли лимиты на количество вызовов?

Да. По умолчанию 10 запросов/секунду; превышение возвращает 429. Авторизованные запросы считаются по ключу, неавторизованные — по IP. Пакетный ордер (например, 4 пары по 10 ордеров) считается как один запрос.

Предупреждение о рисках

Цифровые активы крайне волатильны, а программная торговля через API может усилить риски, потенциально приводя к частичной или полной потере капитала. Риски API включают кражу или несанкционированные ордера из-за утечки ключа, каскадные ошибки из-за логики кода, сбои из-за задержек сети или дрейфа меток времени, лимиты запросов и риск ликвидации на фьючерсах. Всегда ограничивайте ключи минимальными привилегиями, привязывайте IP, защищайте SecretKey и Passphrase и тщательно тестируйте в небольшой среде перед запуском. Эта статья является только техническим руководством по интеграции и не является инвестиционным советом.