The KuCoin Passphrase Nobody Tells You to Write Down

Most exchanges hand you two secrets: a key and a secret. KuCoin hands you three, and the third one is not issued at all. You invent it, on the spot, in a field labelled passphrase, at the exact moment you are focused on ticking permission boxes correctly.

Then KuCoin uses that passphrase as part of the signature on every request. Without it, the key and secret together are inert. And KuCoin does not store it in a form it can give back to you. Lose it and the key is scrap.

That single design choice generates more failed KuCoin connections than every permission mistake combined. So: open a password manager before you open KuCoin, not after.

What am I actually creating?

Sign in on the web, click your avatar in the top right, and open API Management, then Create API. KuCoin will ask you to pass its verification step first.

The form wants an API Name, an API Passphrase, a set of permissions, and optionally an IP restriction. Name it after the app you are connecting so the list stays legible when there are four entries on it. Set the passphrase to something a password manager generated, save it before you continue, and do not use your account password.

When you submit, KuCoin shows the API Key and the API Secret once. You now hold three strings, and your tracker will ask for all three. If it only asks for two, it is not built for KuCoin, and pasting the secret into a passphrase field will fail in ways the error message will not explain.

The failure has a signature worth recognising. KuCoin returns error code 400004 with the message Invalid KC-API-PASSPHRASE. Trackers usually swallow that and show "could not connect", so if a KuCoin connection refuses to authenticate and the key looks right, the passphrase is the first suspect and the key version is the second.

Which permission means read-only?

General. KuCoin's own API documentation describes it as limited to read-only operations such as querying account information, account statements and order information. That is the whole permission a portfolio tracker requires.

The others stay off. Spot Trading, Margin Trading and Futures Trading place and cancel orders. Transfer is the dangerous one, and KuCoin is unusually blunt about why: the Transfer scope permits withdrawal and deposit-address operations, and it does so without the email or authenticator confirmation you would normally face when moving funds off the exchange. KuCoin will not even grant it unless you first enable an IP restriction. Read that sequence again and then never tick the box.

What you are left with is a credential that can answer questions and do nothing else. That is not a matter of the tracker behaving well. KuCoin evaluates the permission attached to the key on every signed request and refuses anything outside it, so a General key attempting a withdrawal is rejected at KuCoin's edge regardless of who is holding the credential. Read-only API keys works through why the location of that check is the entire argument, and is it safe to connect an exchange is honest about the exposure that remains, which is informational rather than financial.

If your tracker publishes a static outbound address, allowlist it. Enter the tracker's address, not your own, because the request reaches KuCoin from the tracker's servers rather than from your phone.

Why is my KuCoin total lower than the app shows?

Because KuCoin partitions money into accounts you have to move funds between by hand, and most people forget how many there are.

The Main account, also called Funding, is where deposits land and withdrawals leave from. The Trading account is where spot orders draw from, and it is a genuinely separate pot. Then there is Margin, in cross and isolated flavours, Futures, the Earn or financial account holding staked and locked positions, and balances committed to trading bots. Buy on spot and the coins sit in Trading. Subscribe to a KuCoin Earn product and they leave Trading entirely.

A key with General permission reads what the exchange exposes to that scope, and how completely a given tracker enumerates those compartments varies. The reliable move is to check rather than assume: open KuCoin's own asset overview, note the figure for each account section, and compare against the tracker's holdings list rather than only against the total. A discrepancy that maps neatly onto one section tells you exactly what is missing. Why your portfolio balance is wrong covers the same failure mode across venues.

Locked Earn positions and futures collateral are the two most likely to be absent. Where they are, enter them as manual positions with their real acquisition price so the quantity is counted and cost basis survives. Adding a manual position takes about a minute per holding.

What else should I expect from a KuCoin connection?

Two things, both consequences of what KuCoin is rather than defects in the connection.

KuCoin lists a very long tail of small-cap tokens, many of which trade meaningfully on KuCoin and almost nowhere else. Your tracker's price for those assets comes from an aggregate across venues, and the aggregate can differ noticeably from the KuCoin order book you would actually sell into. That is not a bug in either number. Why the same coin shows two different prices explains how the aggregation works and when to distrust it.

The same long tail turns over. Tokens listed on KuCoin get delisted more often than tokens on venues with narrower listing criteria, and a delisting breaks the mapping between your holding and its price feed, so the position freezes or disappears from your total. What happens when a coin is delisted is the recovery procedure, and it is worth reading before it happens rather than after.

One last piece of housekeeping. Keys accumulate. Delete any you are no longer using directly on the API Management page, and rotate the ones you keep every six months or so; revoking an API key covers where the controls live. Rotation on KuCoin means generating a new passphrase too, which is the one venue-specific reason to do it on a calmer day than the one where you discover you need to.