KuCoin Exchange Provider

The KuCoin Exchange Provider makes KuCoin the source of truth for everything your SPOT wallets touch: the market list, the tickers, the order book, the candles, the deposit addresses your users are shown, and the withdrawals that leave the platform. Your install does not match orders — it forwards them, and mirrors the result into its own database.

Exactly one exchange provider can be active at a time. Enabling KuCoin disables Binance and XT in the same database transaction, and every route that reaches for ExchangeManager follows the switch immediately.

What it requires

It does not need Ecosystem, ScyllaDB or any blockchain configuration. Those belong to the in-house matching engine, which is a different product solving the opposite problem. The two can run side by side: Ecosystem markets use ECO wallets and your own order book, KuCoin-backed markets use SPOT wallets and KuCoin's. Balances never mix, and neither does the market list.

How the platform reaches KuCoin

There is one shared, process-wide client. ExchangeManager reads the single exchange row with status = true, takes its name (kucoin), and builds a ccxt.pro.kucoin instance from three environment variables named after that value:

APP_KUCOIN_API_KEY="..."
APP_KUCOIN_API_SECRET="..."
APP_KUCOIN_API_PASSPHRASE="..."

That instance is cached for the life of the backend process. Consequences worth internalising before you go live:

• Credentials are read once, at first use. Editing .env does nothing until the backend restarts.
• The clock matters. Signed requests are timestamped against KuCoin's own server time, measured with a bracketed fetchTime round trip and deliberately biased 500 ms behind. The offset is refreshed in the background every five minutes. A badly wrong system clock still breaks things, but ordinary drift does not.
• Failures are sticky. Three consecutive initialisation failures put the provider into a 30-minute cooldown during which it returns nothing at all, without retrying. Fixing .env and restarting is faster than waiting.
• Rate limiting is a kill switch. A RateLimitExceeded from KuCoin writes a ban marker into Redis under exchange:ban_status. While it is set, every spot path — prices, order reconciliation, deposits, withdrawals, the admin screens — no-ops and reports success. The key carries a TTL so it self-clears, and any ban longer than 24 hours is clamped.

What KuCoin-specific behaviour exists

Most of the integration is generic ccxt. Five things are branched on the provider name being kucoin, and each of them is a place where KuCoin differs from the other two providers:

Two accounts, not one. KuCoin splits funds between a Main (funding) account and a Trade account. After a deposit is credited, the platform transfers the amount main → trade. Before a withdrawal, it transfers main → trade again, and refuses to proceed if that transfer does not return an id. Where you park your float therefore decides whether withdrawals work at all — see Deposits and withdrawals.

Networks are named after token standards. KuCoin identifies a chain as ERC20, BEP20, TRC20 rather than ETH, BSC, TRX. The platform maps between them before asking for a deposit address, and again before submitting a withdrawal.

Order book depth is quantised. KuCoin accepts depths of 5, 20, 50 or 100 only. A request for any other depth is snapped to the nearest allowed value and trimmed back to the requested size before it reaches the browser.

Tickers are polled, not streamed. For KuCoin the ticker service uses fetchTickers with retries and stops the batching interval, rather than the watchTickers stream used elsewhere.

Market imports must be filtered. ccxt loads KuCoin's spot, swap and futures markets together. Symbols such as BTC/USDT:USDT are dropped on import, because a single contract symbol in exchange_market makes multi-symbol calls fail outright with "kucoin symbols must be of the same type" and takes the whole ticker batch with it.

Where to start