WEEX API Python SDK: як підписати та викликати запит від початку до кінця

Перше, що варто вирішити перед написанням коду: станом на липень 2026 року WEEX не випускає офіційного окремого пакета під назвою "weex-python-sdk". Натомість у вас є два робочі шляхи: викликати REST-ендпоінти безпосередньо через requests, використовуючи власні правила підпису WEEX, або скористатися бібліотекою з відкритим кодом ccxt, яка вже підтримує WEEX. Цей посібник охоплює обидва шляхи та приділяє найбільшу увагу двом моментам, що найчастіше спричиняють помилки в інтеграції: як підписати запит і як забезпечити безпеку ключів.

Це технічна нотатка для вставки у проект, а не словник ендпоінтів. API для спотової та контрактної торгівлі WEEX наразі працюють на версії V3 (BETA), при цьому V2 все ще доступна для контрактів; у коді нижче використовується спотова версія V3.

Що насправді означає "WEEX API Python SDK"

Строго кажучи, це не офіційний пакет — це скорочення для "Python-клієнта, що взаємодіє з ендпоінтами WEEX". WEEX надає інтерфейси REST та WebSocket для спотової торгівлі, контрактів, копітрейдингу та брокерських продуктів. Будь-яка мова, здатна надсилати HTTP-запити та обчислювати HMAC-підпис, може виконати інтеграцію.

На практиці "Python SDK" має три форми:

• Легка власна обгортка — requests плюс hmac, кілька десятків рядків коду, мінімум залежностей, максимальний контроль.
• Уніфікована бібліотека ccxt — pip install ccxt, розглядайте WEEX як одну з понад 100 бірж, що підтримуються ccxt, з уніфікованими назвами методів.
• WebSocket-клієнт — websocket-client для підписки на ринкові дані в реальному часі або приватні канали.

У самому вступі до API розробникам рекомендується дотримуватися задокументованих схем і підтримувати версійність клієнтів — іншими словами, ви збираєте SDK самостійно; не варто чекати на офіційний реліз.

Підготовча работа: створення API-ключа та налаштування дозволів

Перед будь-яким викликом створіть API-ключ у своєму акаунті. Згідно з документацією з підготовки до інтеграції, акаунт може містити до 10 груп ключів. Кожен ключ надає три облікові дані, жодна з яких не є необов'язковою:

Дозволи мають значення: новий ключ за замовчуванням має статус Read Only — ви повинні вручну активувати спотову торгівлю для розміщення ордерів. При створенні прив'яжіть IP-адресу до білого списку; документація чітко вказує, що ключі без обмежень та без прив'язки до IP становлять загрозу безпеці.

Як викликати API: підпис запиту на Python

Правило підпису WEEX, згідно з документацією щодо підписів, об'єднує timestamp + метод (верхній регістр) + шлях запиту (з параметрами) + тіло, виконує HMAC SHA256 з вашим SecretKey, а потім кодує результат у Base64. Часова мітка вказується в мілісекундах, і будь-який запит, що відхиляється від часу сервера більш ніж на 30 секунд, відхиляється.

Це працює як є (використовуючи ендпоінт глибини з документації):

import time, hmac, hashlib, base64, requests

API_KEY    = "your-APIKey"
SECRET_KEY = "your-SecretKey"
PASSPHRASE = "your-Passphrase"
BASE = "https://api-spot.weex.com"  # перевірте хост згідно з офіційною документацією StandardSpecifications

def sign(ts, method, path, body=""):
    prehash = f"{ts}{method.upper()}{path}{body}"
    mac = hmac.new(SECRET_KEY.encode(), prehash.encode(), hashlib.sha256)
    return base64.b64encode(mac.digest()).decode()

def request(method, path, body=""):
    ts = str(int(time.time() * 1000))
    headers = {
        "ACCESS-KEY": API_KEY,
        "ACCESS-SIGN": sign(ts, method, path, body),
        "ACCESS-TIMESTAMP": ts,
        "ACCESS-PASSPHRASE": PASSPHRASE,
        "Content-Type": "application/json",
    }
    url = BASE + path
    if method == "GET":
        return requests.get(url, headers=headers).json()
    return requests.post(url, headers=headers, data=body).json()

# Публічні ринкові дані не потребують підпису; це приклад структури підписаних заголовків
print(request("GET", "/api/v3/market/depth?symbol=BTCUSDT&limit=20"))

Пастка: параметри GET потрапляють у запит всередині path, POST використовує тіло JSON, і тіло, яке ви підписуєте, має бути ідентичним байт у байт тілу, яке ви надсилаєте. Інший порядок ключів або зайвий пробіл призведуть до помилки підпису — це найпоширеніша причина помилок 401 у власноруч написаних клієнтах.

Використання ccxt для швидкого старту (найкращий вибір для більшості)

Якщо ви не хочете вручну реалізовувати підпис, ccxt вже підтримує спотову торгівлю WEEX, контракти (свопи) та WebSocket через понад 80 методів. Кілька рядків коду дозволяють отримати тікери та ордери:

import ccxt   # pip install ccxt

ex = ccxt.weex({
    "apiKey": "your-APIKey",
    "secret": "your-SecretKey",
    "password": "your-Passphrase",   # пароль WEEX відповідає полю "password" у ccxt
})

print(ex.fetch_ticker("BTC/USDT"))            # ринкові дані
# print(ex.fetch_balance())                    # потребує дозволу на торгівлю
# ex.create_order("BTC/USDT", "limit", "buy", 0.001, 30000)

Перевага: той самий код, який сьогодні викликає WEEX, завтра працюватиме з іншою біржею завдяки зміні лише одного рядка класу. Ціна цього — ccxt є абстракцією, що підтримується спільнотою; покриття нових ендпоінтів WEEX може затримуватися, тому перевіряйте поля згідно з офіційною документацією, коли використовуєте нові функції.

Дані в реальному часі: підключення до WebSocket на Python

Опитування REST швидко призведе до лімітів за кількістю запитів. Для даних у реальному часі використовуйте WebSocket — публічний канал wss://ws-spot.weex.com/v3/ws/public, а приватний — .../private, останній автентифікується тими самими чотирма полями ACCESS-KEY / ACCESS-SIGN / ACCESS-TIMESTAMP / ACCESS-PASSPHRASE (рядок підпису: timestamp + /v3/ws/private).

import json, websocket   # pip install websocket-client

ws = websocket.create_connection("wss://ws-spot.weex.com/v3/ws/public")
ws.send(json.dumps({"method": "SUBSCRIBE", "params": ["BTCUSDT@ticker"], "id": 1}))
print(ws.recv())

Сервер надсилає періодичні повідомлення ping; клієнт повинен відповісти {"method":"PONG","id":1}, інакше з'єднання буде розірвано. Деталі полів можна знайти в документації WebSocket.

Чи це безпечно? Дозволи та гігієна ключів на практиці

Безпека API-торгівлі залежить від управління ключами, а не від ендпоінту. Майже кожна втрата коштів пов'язана з неправильним поводженням з ключами, а не зі зламом інтерфейсу. Практичний чек-лист:

• Мінімальні привілеї — активуйте лише те, що потрібно для поточної стратегії. Ключ "лише для читання" ніколи не отримає доступу до торгівлі; ключі WEEX також за замовчуванням не мають дозволу на виведення коштів, що обмежує шкоду в разі крадіжки ключа.
• Прив'язка до IP — заблокуйте ключ на вихідній IP-адресі вашого сервера, щоб викрадений ключ був марним в іншому місці.
• Тримайте ключі поза кодом — використовуйте змінні середовища або менеджер секретів; ніколи не записуйте їх у код, не комітьте в Git і не відправляйте в клієнтський код.
• Розділяйте розробку та продакшн — два набори ключів, жодної перехресної контамінації, простіший аналіз інцидентів.
• Регулярна ротація — оновлюйте ключі та налаштуйте сповіщення про помилки підпису та 429.

Проектуйте з урахуванням лімітів запитів: публічні ринкові ендпоінти дозволяють приблизно 20 запитів за 2 секунди, перевищення призводить до HTTP 429; приватні ендпоінти дотримуються правил для кожного ключа. Вбудована логіка повторних спроб та затримок у клієнті краща за гасіння пожеж пізніше.

Короткий довідник

Підсумок

Офіційного окремого WEEX API Python SDK не існує, і це не є перешкодою: логіка підпису проста (HMAC SHA256 + Base64), а ccxt надає готову уніфіковану точку входу. Результат залежить від управління дозволами та ключами — за замовчуванням обирайте "лише для читання", прив'язуйте IP, тримайте секрети поза репозиторієм — і з цими заходами інтеграція WEEX API на Python буде швидкою та стабільною. Коли будете готові, створіть свій перший ключ згідно з документацією з підготовки до інтеграції.

Додаткове читання: підтримка WEEX у ccxt задокументована в її офіційній вікі.

FAQ

1. Чи має WEEX офіційний Python SDK?

Станом на липень 2026 року — ні. WEEX надає інтерфейси REST та WebSocket; на стороні Python ви або пишете обгортку для requests, або використовуєте ccxt, яка вже включає WEEX.

2. Мої виклики постійно повертають помилку підпису (401) — як її відлагодити?

Зазвичай це одна з трьох причин: часова мітка не в мілісекундах або відхиляється від сервера більш ніж на 30 секунд; порядок рядка підпису неправильний (має бути timestamp + метод + шлях + тіло); або підписане тіло відрізняється від тіла, яке фактично надсилається в POST. Перевірте кожен пункт.

3. Куди вводити пароль WEEX у ccxt?

У поле password. ccxt використовує apiKey, secret та password для відповідності APIKey, SecretKey та Passphrase у WEEX.

4. Чи потребують публічні ринкові ендпоінти підпису?

Публічні ендпоінти, такі як ринкові дані, зазвичай не потребують підпису; лише приватні ендпоінти, що стосуються вашого акаунта або ордерів, вимагають повного набору з чотирьох заголовків автентифікації. Публічні ендпоінти все одно мають ліміти запитів.

5. Чому мій новий API-ключ не може розміщувати ордери?

Тому що новий ключ за замовчуванням має статус Read Only. Вручну активуйте дозвіл на спотову торгівлю під час створення або редагування ключа та одночасно прив'яжіть білий список IP-адрес.

Попередження про ризики

Цифрові активи дуже волатильні, а автоматизована торгівля може призвести до втрати частини або всього капіталу через недоліки стратегії, ринкові коливання або системні збої. API-торгівля додає специфічні ризики: викрадений ключ без прив'язки до IP може дозволити зловмиснику діяти від вашого імені; контракти з високим кредитним плечем збільшують збитки; а обмеження кількості запитів (429) або розриви мережі можуть призвести до невиконання ордерів або помилок скасування. Застосовуйте мінімальні привілеї, прив'язуйте IP-адреси, захищайте свій SecretKey та Passphrase і ретельно тестуйте з невеликими обсягами перед запуском у продакшн. Ця стаття є технічним посібником з інтеграції і не є інвестиційною порадою.