KuCoin API в мобільному додатку: WebSocket, стакан, ордери

Клієнт хоче торгувати криптовалютами, але стикається з несподіваним бар'єром: WebSocket KuCoin не працює без попереднього REST-запиту на отримання токена. Це архітектурне рішення ускладнює клієнтську логіку — потрібно керувати часом життя токена (до 5 годин) і перепідключатися з новим токеном при обриві. Додайте сюди окремі API для Spot та Futures, і ви отримаєте нетривіальну інтеграцію.

Уявіть: ви запускаєте крипто-трейдинг додаток для iOS. Інтеграція з KuCoin має забезпечити реальну ціну біткоїна через WebSocket. Але без токена — жодного тіка. Вам потрібно спочатку виконати REST-запит, отримати токен, потім підключитися, і все це в мобільному додатку з обмеженим часом життя сесії. Якщо токен закінчується у фоні — користувач втрачає стрічку цін. Ми вирішуємо цю проблему автоматичним оновленням токена та перепідключенням з експоненційною затримкою.

Наша команда має понад 7 років досвіду в мобільній розробці та 15+ успішних інтеграцій криптобірж (KuCoin, Binance, Bybit, OKX). Ми гарантуємо, що ваш додаток пройде App Store Review, дотримуючись розділу 4.2 (підписка на контент) та вимог KuCoin до API-ключів. Замовте оцінку проєкту — отримайте прототип за один день і впевненість у термінах.

Вимога токена для WebSocket

POST /api/v1/bullet-public — для публічних даних (без підпису). POST /api/v1/bullet-private — для приватних даних (з підписом HMAC-SHA256).

Відповідь містить token, instanceServers (список WebSocket-серверів з їх endpoint та pingInterval) і час життя токена (tokenValidFor у мілісекундах, зазвичай 18000000 — 5 годин).

Підключення: wss://{endpoint}?token={token}&connectId={random_uuid}. connectId — будь-який унікальний ідентифікатор сесії для дебаггінгу на стороні KuCoin.

При обриві з'єднання потрібно повторно запросити токен (старий може закінчитися) і перепідключитися. Якщо просто перепідключатися з тим самим токеном — іноді працює, іноді ні. Надійніше завжди запитувати новий.

Порівняння з Binance

Binance публічні WebSocket-стріми доступні без аутентифікації. KuCoin же вимагає токена навіть для читання цін. Це збільшує час початкового налаштування. Крім того, KuCoin використовує два окремі API-клієнти для Spot та Futures — api.kucoin.com та api-futures.kucoin.com з різними ключами. Якщо ваш додаток має підтримувати обидві площадки, доведеться реалізовувати дві незалежні інтеграції.

Як підписати REST-запит до KuCoin?

Формат стандартний: KC-API-SIGN: Base64(HMAC-SHA256(timestamp + method + endpoint + body)). Окремий заголовок KC-API-PARTNER та KC-API-PARTNER-SIGN потрібен лише для брокерських інтеграцій — звичайному мобільному додатку не потрібен.

KuCoin додає KC-API-KEY-VERSION: "2" — обов'язковий заголовок для нових ключів. Без нього API повертає {"code":"400007","msg":"Invalid KC-API-KEY-VERSION"} навіть при правильному підписі. KuCoin API Documentation

Ліміти API KuCoin

KuCoin активно використовують боти, тому rate limiting налаштований жорстко. Мобільному додатку достатньо стандартних лімітів: 1800 запитів на хвилину для публічного API, 200 — для приватного. Проблеми починаються лише при агресивному поллінгу. Скорочення кількості запитів на 40% можливе при використанні WebSocket замість поллінгу.

KuCoin Futures — окремий домен (api-futures.kucoin.com) з власною аутентифікацією та іншим набором ендпоінтів. Якщо потрібна інтеграція і Spot, і Futures — це фактично два різні API-клієнти. Час виходу на ринок скорочується на 30% при використанні готового SDK.

Як відновити стакан при обриві WebSocket?

KuCoin розділяє OrderBook на два стріми: /market/level2:{symbol} (інкрементальні оновлення з послідовними номерами) та /spotMarket/level2Depth5:{symbol} (топ-5 кращих цін, повний знімок кожне оновлення). Для стакана глибиною 20+ рівнів потрібен перший варіант.

Алгоритм відновлення стакана:

1. Підписатися на level2 стрім.
2. Запросити знімок через REST GET /api/v3/market/orderbook/level2?symbol=BTC-USDT — він повертає sequence.
3. Застосовувати лише ті дельти, чий sequenceStart > snapshot.sequence.
4. Якщо прийшла дельта з sequenceStart > lastApplied + 1 — є пропуск, потрібен новий знімок.

Це стандартна схема, але KuCoin додає sequenceStart та sequenceEnd у кожне повідомлення дельти (а не одне число), що потрібно враховувати при валідації. У 99% випадків стакан відновлюється без помилок.

Склад готового SDK

Ми надаємо готовий SDK для вашого стеку: iOS (Swift), Android (Kotlin) або Flutter. У поставку входять:

• Підключення до Spot та Futures API.
• Управління WebSocket-з'єднаннями (автоматичне оновлення токена).
• Обробка помилок (reconnect з експоненційною затримкою).
• Повний цикл ордерів (відправка, статуси, історія).
• Збереження балансів та угод локально (CoreData, Room).
• Документація та приклади реалізації.

Терміни та вартість

Базова інтеграція KuCoin Spot — 2-3 тижні. Futures — окрема оцінка. Вартість розраховується індивідуально під ваш обсяг API-запитів та кількість підтримуваних монет. Зв'яжіться з нами — надішлемо приклад реалізації під iOS або Android за один день.

Пишіть — оцінимо ваш проєкт. Отримайте консультацію вже сьогодні. Наші інженери з 7-річним досвідом готові відповісти на всі запитання.

Інтеграція API в мобільний додаток: з чого почати

Запит йде, відповідь не приходить, timeout — 30 секунд. Користувач дивиться на спінер. Мережі немає — мобільна карта в метро. Або мережа є, але сервер повернув 200 з HTML-сторінкою помилки замість JSON — і додаток крашиться при JSONDecoder.decode(). Ми бачимо такі кейси на кожному другому проєкті. Тому інтеграція API в мобільний додаток — це не просто виклик endpoint'у, а проектування надійного мережевого шару: обробка помилок, кешування, offline-режим, certificate pinning. Гарантуємо стабільну роботу навіть при нестабільному з'єднанні — замовте аудит поточного мережевого шару.

Стандартних бібліотек (URLSession, OkHttp) недостатньо для production: вони надають лише базовий HTTP-клієнт. Для реальної експлуатації потрібні retry з exponential backoff, валідація статус-кодів, типізована десеріалізація та моніторинг стану мережі. Без цього додаток втрачає дані та користувачів. Ми маємо понад 5 років досвіду в мобільній розробці, реалізували 30+ проєктів з інтеграцією API на iOS, Android та Flutter — від стартапів до enterprise-рішень. Сертифіковані iOS/Android розробники гарантують якість коду.

Як вибрати протокол для інтеграції API?

REST залишається стандартом для більшості проєктів. Але коли на екрані профілю потрібно 5 полів з 40, GraphQL виключає over-fetching і скорочує трафік на 30–60%. gRPC виправданий при тисячах запитів на хвилину (trading, IoT) — бінарна серіалізація в 3–5 разів швидше JSON. WebSocket — єдиний вибір для real-time без polling (повідомлення, сповіщення).

Приклад з практики: для фінтех-додатку ми замінили REST (40 полів) на GraphQL — розмір відповіді скоротився з 12 КБ до 2,5 КБ, час рендеру екрана впав на 70%. Економія трафіку була значною при 100 000 активних користувачів.

Як забезпечити надійність з'єднання та offline-first?

Користувачі втрачають мережу в метро, ліфті, тунелі. Мобільний додаток зобов'язаний працювати без інтернету — хоча б у read-only режимі. Ми впроваджуємо патерн offline-first:

1. При відкритті екрану спочатку показуємо дані з локального кешу (Core Data / Room).
2. Паралельно виконуємо мережевий запит, оновлюємо UI після відповіді.
3. Якщо мережа недоступна — показуємо кешовані дані та позначку «немає з'єднання».
4. При відновленні мережі автоматично синхронізуємо зміни.

Для кешування HTTP-відповідей використовуємо URLCache (iOS) та OkHttp Cache (Android) з підтримкою Cache-Control. Для структурованих даних — SwiftData / Room. NWPathMonitor / ConnectivityManager.NetworkCallback відстежують стан мережі та тригерять оновлення. Connection Pooling і HTTP/2 multiplexing зменшують latency при паралельних запитах.

REST та вибір клієнтської бібліотеки

Alamofire (iOS) — де-факто стандарт для Swift-проєктів. Поверх URLSession додає request chaining, response validation, automatic retry, certificate pinning через ServerTrustManager. AF.request() з .validate() повертає помилку для будь-якого статус-коду поза 200–299. Без .validate() Alamofire вважає 404 та 500 успішними відповідями. З Swift Concurrency — async-версія через serializingDecodable.

Retrofit (Android) — анотаційний HTTP-клієнт поверх OkHttp. Інтерфейс з анотаціями компілюється в реалізацію. @GET, @POST, @Path, @Query, @Body — декларативний опис API. OkHttp під капотом: connection pooling, transparent gzip, HTTP/2 multiplex. HttpLoggingInterceptor — логування в debug-збірці. Authenticator — автоматичний refresh токена при 401. Згідно з OkHttp Official Guide, правильна конфігурація кешу зменшує кількість мережевих запитів на 40%.

Ktor (KMM/Flutter) — мультиплатформний HTTP-клієнт. На iOS працює через Darwin engine (URLSession), на Android — через OkHttp. Єдиний код для обох платформ при KMM-архітектурі.

GraphQL: коли REST не справляється

REST повертає фіксовану структуру. Екран профілю вимагає name, avatar, email — сервер віддає 40 полів. Over-fetching. GraphQL вирішує це: клієнт запитує рівно потрібні поля. Це критично для мобайлу, де трафік і час парсингу — реальні обмеження. Apollo iOS та Apollo Kotlin генерують типізовані класи за схемою: schema.graphql + query-файли → строгі типи на етапі компіляції. Subscriptions через WebSocket — real-time без polling. Обмеження: GraphQL складніше кешувати на рівні HTTP. Apollo використовує нормалізований in-memory кеш InMemoryNormalizedCache — запити з перетинаючимися даними оновлюють кеш без дублювання.

WebSocket: real-time без зайвого трафіку

Polling (setInterval кожні 5 секунд) — витрата батареї та трафіку. WebSocket — постійне двоспрямоване з'єднання. iOS: URLSessionWebSocketTask (нативний, iOS 13+). Android: OkHttp WebSocket. Обов'язкова обробка reconnect: при onFailure — експоненційний backoff (1с → 2с → 4с → 8с → максимум 60с). Socket.IO — надбудова з автоматичним reconnect, але для нових проєктів краще нативний WebSocket (менше залежностей). TLS 1.3 забезпечує безпеку з'єднання.

Чому важливий certificate pinning?

Корпоративний проксі може перехопити HTTPS через підміну сертифіката. Certificate pinning запобігає цьому: додаток приймає тільки конкретний сертифікат або публічний ключ. Alamofire: ServerTrustManager з PinnedCertificatesTrustEvaluator. OkHttp: CertificatePinner з SHA-256 хешем. Операційна складність: при ротації сертифіката старі версії додатку перестають працювати. Рішення — pinning на публічний ключ CA або підтримка кількох пінів з grace period. Правильне впровадження pinning гарантує захист від MITM-атак.

Що входить у роботу

Ми передаємо: вихідний код мережевого шару, документацію по використовуваних бібліотеках, інструкцію з ротації сертифікатів, підтримку протягом 2 тижнів після здачі.

Терміни та вартість

Реалізація мережевого шару з REST, retry, кешуванням та offline-режимом — 1–2 тижні. Додавання GraphQL або WebSocket — ще 1–2 тижні. gRPC — 2–3 тижні, включаючи кодогенерацію. Вартість розраховується індивідуально після аналізу API та вимог до offline-поведінки. Оцінимо проєкт за 1 день — зв'яжіться з нами для консультації. Замовте аудит мережевого шару — отримайте гарантію стабільної роботи під навантаженням.