Install and activate

Activate the KuCoin provider licence, set the three APP_KUCOIN_* variables, enable KuCoin as the active exchange, and verify the connection before any customer touches it.

6 min readUpdated 3 August 2026install, licence, environment, kucoin, verification

There is nothing to upload and no extension folder to extract. The KuCoin provider ships inside the core: the exchange table is seeded with a kucoin row on install, and what you are buying is the licence that lets you switch it on. The work is a licence, three environment variables, one toggle and one verification.

Do all of it before you enable spot trading for users. Every step below fails in a way that is visible to you and invisible to them.

Order of operations

Activate the licence. Admin → System → Extensions (or /admin/extensions) lists exchange providers alongside addons and blockchains. Find KuCoin, activate it with your Envato purchase code and username. Activation writes lic/37179816.lic under the project root.

Until that file exists, the enable toggle refuses with a 403 and licenseRequired: true. The check is a filesystem check on every request, so a licence file deleted by a bad deploy takes the provider down at the next toggle.
Create the KuCoin API key. Do this before touching .env, because the secret and the passphrase are both unrecoverable afterwards. Full walkthrough in API keys and permissions.
Write the three variables into .env. In the project root, not backend/.env:
```
APP_KUCOIN_API_KEY="your_api_key"
APP_KUCOIN_API_SECRET="your_api_secret"
APP_KUCOIN_API_PASSPHRASE="the_passphrase_you_invented"
```
The names are not decorative. The backend builds them at runtime from the provider name in the database — APP_${provider.toUpperCase()}_API_KEY — so KUCOIN_API_KEY or APP_KUCOIN_PASSPHRASE are read by nothing.
Point the frontend at KuCoin. One more variable, and it is a three-letter alias rather than the full name:
```
NEXT_PUBLIC_EXCHANGE="kuc"
```
This decides the TradingView chart's provider prefix and the order-book depth the browser asks for. Left at "bin", charts are drawn against Binance symbols while your order book comes from KuCoin.
Restart the backend. NEXT_PUBLIC_* values are compiled into the frontend, so a change to that one needs a frontend rebuild as well.
```
pnpm stop && pnpm start
```
Enable KuCoin as the active provider. Toggle it on from the extensions screen. Enabling one exchange disables every other exchange in the same database transaction — there is no multi-provider mode.
Verify. Admin → Finance → Exchange (/admin/finance/exchange) loads the active provider and immediately runs a live credential test. Press Verify to run it again on demand.
Import currencies, then markets. Both are dry runs until you confirm them. See Currencies and markets.

What verification actually does

The verify call is not a lookup of stored state. It builds a throwaway ccxt instance with your credentials, synchronises the clock against KuCoin's server time, calls loadMarkets(), then calls fetchBalance() — a signed, private request — and closes the connection.

That last call is the point. It is the cheapest thing that cannot succeed without a correct key, a correct secret and a correct passphrase all at once.

Runs the live credential test for one provider. Not written to the admin audit trail; saving the key is the audited action.

A timestamp error triggers up to two automatic retries with a fresh clock sync before the failure is reported, so an occasional drift does not show up as a credential problem.

Reading the result

The verification message is deliberately short, and one of them is misleading in a way you need to know about.

Message	What it means
"API credentials are valid and connection successful"	All three secrets are correct and the key has at least General permission
"API credentials are missing from environment variables"	`APP_KUCOIN_API_KEY` or `APP_KUCOIN_API_SECRET` is unset or empty. The passphrase is not checked here
"Invalid API credentials. Please check your API key and secret."	Any `AuthenticationError` from ccxt — including a wrong or missing passphrase, which the wording does not mention
"Access denied: Your server's location is blocked by this exchange…"	HTTP 451. Configure a proxy on the Settings tab
"Insufficient API permissions…"	The key exists but lacks the permission the call needed
"Server time synchronization failed…"	`fetchTime` failed twice; check the server clock and outbound access
"Rate limit exceeded…"	A ban marker is set in Redis; wait for it to expire

Admin → System → Health reports the exchange provider by testing only that APP_KUCOIN_API_KEY and APP_KUCOIN_API_SECRET are non-empty. With those two set and the passphrase missing, health reports "kucoin configured" in green while ExchangeManager cannot build a client at all. Trust the Exchange screen's verify result, not the health badge.

Two distinct passphrase failures

They present completely differently, so it is worth knowing which one you have.

Passphrase absent or empty. ccxt requires password for KuCoin and throws before any network call. ExchangeManager catches the throw as a generic initialisation failure, retries three times with five-second gaps, and then returns nothing. Every spot route answers with Failed to start exchange provider: kucoin. Charts, tickers, order book — all gone. It is loud.

Passphrase present but wrong. The credential check passes, so the client is built and loadMarkets() runs. KuCoin rejects the signed account-mode probe inside currency loading, and the manager falls back to an unauthenticated KuCoin instance, logging a warning that authenticated data will be unavailable. Public data keeps flowing: markets load, tickers update, charts look fine. What silently stops is everything that needs a signature — balances, deposit addresses, withdrawals. This one is quiet, and it is the one that costs money.

If you are unsure which you are looking at, search the backend log for Falling back to an unauthenticated kucoin instance.

Proxy, if KuCoin will not serve your server

KuCoin restricts a number of regions. The admin Exchange screen names them under Regions: the United States, North Korea, Singapore, Hong Kong, Iran and the Crimean region. A server in one of them gets HTTP 451 on every call, including public ones.

The fix is a proxy, stored per provider on the exchange row rather than in .env. On /admin/finance/exchange → Settings, enter a proxy URL and test it before saving. Supported schemes are http://, https://, socks4:// and socks5://, with optional user:pass@ credentials — those are masked whenever the row is read back.

Opens a public connection through a proxy URL and reports whether KuCoin answered.

Saving a proxy clears the settings cache and evicts the cached KuCoin client, so the next call rebuilds through the new proxy without a restart. With no proxy configured, the platform connects over a keep-alive agent pinned to IPv4 — relevant if you are whitelisting your server's address on KuCoin.

Before you hand it to users

Verify returns green on /admin/finance/exchange.
Spot currencies imported, and the handful you intend to support are enabled.
Spot markets imported, and the pairs you intend to list are enabled — imports arrive disabled.
spotWallets is on under Admin → Trading → Settings, or nothing appears in the user-facing wallet and withdraw screens.
A small test deposit has credited, and a small test withdrawal has left.