Reference

Every environment variable, platform setting, admin endpoint, permission and background job the KuCoin provider touches, with the connection defaults the shared exchange client is built with.

1 min readUpdated 3 August 2026reference, environment, endpoints, permissions, cron

Everything on this page is read from the project root .env, the settings table, or the exchange database row. Nothing here has a KuCoin-specific admin form beyond the Exchange screen.

Environment variables

All four live in the project root .env, not backend/.env. The three APP_KUCOIN_* names are not hard-coded anywhere — the backend builds them at runtime as APP_${provider.toUpperCase()}_API_* from the provider name in the database, which for this product is always kucoin. Renaming them breaks nothing loudly; it simply means no credentials are found.

KuCoin API key. Checked for presence before a client is built; an empty value is treated as absent.

KuCoin API secret. Also signs the passphrase, so a wrong secret invalidates both.

KuCoin API passphrase, passed to ccxt as password. NOT checked by the platform's own credential guard or by the system health check — ccxt is what rejects its absence.

Three-letter frontend alias. Set to "kuc" for KuCoin. Selects the TradingView chart provider and the order-book depth ladder the browser requests. Compiled into the frontend, so changing it needs a frontend rebuild.

There is no sandbox or testnet variable for this provider. Anything you point it at is live.

Platform settings

These live in the settings table and are strings, not booleans — the value for "off" is the string "false".

Master switch for spot trading. With it off, the SPOT wallet, deposit and withdraw screens do not appear regardless of provider state. Admin → Trading → Settings.

Percentage fee added to every spot withdrawal, on top of the currency's own fee. Admin → Settings → Wallet → Fees.

True makes the platform absorb the chain fee and send the full requested amount; false deducts it from what the user receives. No admin field — set it directly.

When enabled, a deposit whose exchange timestamp is more than 15 minutes either side of the request, or more than 45 minutes old, is marked TIMEOUT instead of credited.

Chart provider for the spot trading pages. TRADINGVIEW or CHART_ENGINE.

JSON blob holding the candle cache configuration — cacheDays, rateLimit, intervals and autoUpdate. Written by the chart settings endpoint, not by hand.

The exchange row

Provider state lives in the exchange table, seeded on install. The KuCoin row:

Column	Value
`name`	`kucoin` — the ccxt class id, and the source of the `APP_KUCOIN_*` prefix
`title`	`KuCoin`
`type`	`spot`
`productId`	`37179816`
`status`	The active flag. Only one row may be true
`licenseStatus`	Synced from the presence of `lic/37179816.lic` on every read
`proxyUrl`	Optional per-provider proxy. Credentials in it are masked on read

Re-running the seeder refreshes productId, title, description, link and type. It never touches status or version, so an update cannot silently switch your provider.

Connection defaults

The shared ccxt client is built once per process with these, and none of them are configurable:

Setting	Value	Why
Timeout	30,000 ms	Per request
`enableRateLimit`	true	ccxt throttles before KuCoin has to
`recvWindow`	60,000 ms	Timestamp tolerance
`adjustForTimeDifference`	true	Clock offset applied to signed requests
Signing bias	500 ms behind server time	Being slightly behind is always safe; being ahead is not
Fallback offset	1,000 ms behind	Used when `fetchTime` itself fails
Clock resync	Every 5 minutes	Background, never blocks a caller
HTTP agent	Keep-alive, IPv4 only	Unless a proxy is configured, in which case the proxy agent replaces it
Init retries	3, five seconds apart	Then a 30-minute cooldown returning nothing
Rate-limit ban	1 minute, clamped to 24 hours max	Stored in Redis as `exchange:ban_status` with a matching TTL

Admin endpoints

Provider lifecycle:

Returns the currently enabled provider and runs a live credential test against it.

Returns one provider by product id, syncs its licence status from disk, and runs a credential test.

Enables or disables a provider. Enabling disables every other provider in the same transaction, and refuses with 403 when the licence file is absent.

Updates the provider row — proxy URL and licence status. Clears the settings cache and evicts the cached client.

Activates the provider licence from an Envato purchase code and username, then marks the provider active.

Runs the live credential test on demand. Excluded from the audit trail.

Opens a public connection through a proxy URL and reports whether the exchange answered. Excluded from the audit trail.

Data import and operations:

Imports spot currencies. Dry run unless confirm=true.

Imports spot markets. Dry run unless confirm=true.

Lists imported markets.

Bulk-enables or disables markets. Note the Ecosystem permission key.

Live balances on the exchange account, filtered to non-zero holdings.

Compares the fees the exchange charged against the fees the platform calculated, grouped by fee currency.

Candle cache statistics per market.

Reads the candle cache configuration and the current exchange ban status.

Builds candle history for the named markets and intervals.

Backfills gaps in one market and interval.

Clears cached candles from disk and optionally Redis.

Permissions

Grant these to any role that operates the provider. Keys are validated against the admin route they gate — see Permissions.

Permission	Covers
`view.exchange`	The Exchange provider screen
`edit.exchange`	Enable/disable, proxy, licence activation, verify
`view.exchange.market`	The market table
`create.exchange.market`	Market import
`edit.exchange.market`	Editing a market's precision, limits and fees
`delete.exchange.market`	Removing markets
`edit.ecosystem.market`	Enabling or disabling a market, single or bulk
`view.spot.currency` / `edit.spot.currency`	The spot currency table
`create.spot.currency`	Currency import
`view.exchange.balance`	Live exchange balances
`view.exchange.fee`	The fee comparison screen
`view.exchange.chart` / `manage.exchange.chart`	Candle cache read / build
`view.exchange.order` / `edit.exchange.order` / `delete.exchange.order`	The spot order table

Background jobs

All of these depend on a working provider connection. While the Redis ban marker is set, they run and report success while doing nothing.

Job	Every	What it does
`processPendingSpotOrders`	1 min	Reconciles open spot orders against KuCoin — credits fills, refunds cancellations, handles partials
`processCurrenciesPrices`	2 min	Refreshes exchange currency prices
`reconcileSpotWithdrawals`	5 min	Finds withdrawals stranded by a restart between the debit and the send; confirms or refunds them
`processSpotPendingDeposits`	15 min	Catch-up deposit detection for anything the live WebSocket path missed
`processPendingWithdrawals`	30 min	General pending-withdrawal sweep

The live deposit WebSocket is not a cron: it polls every 15 seconds for 30 minutes while the user has the deposit screen open, then stops.

Log prefixes

Backend logs are tagged by module. When diagnosing this provider, these are the ones that matter:

Tag	Emitted by
`EXCHANGE`	Client construction, credential checks, clock sync, ban handling, network mapping, deposit address cascade
`SPOT_DEPOSIT`	The live deposit verification WebSocket
`WITHDRAW`	The user withdrawal path
`CRON`	The reconciliation and catch-up jobs
`CURRENCY`	Currency loading and price processing