Exchange API keys
trade-only, withdrawals off, bound to your server.
How to create a key KESTREL accepts on each exchange, why a key that can withdraw is refused, and what to do about hedge mode. Give these steps to your users too.
01Three rules for every key
- Read and Trade only. Spot trading, futures trading, or both, as you need.
- Withdrawals OFF (and on Binance, internal transfer off too). KESTREL refuses a key with withdraw permission, and on Binance also one with internal transfer enabled.
- IP whitelist ON with only your server's IP. A stolen key is then useless from anywhere else.
Create a new key just for KESTREL; do not reuse a key from another tool. Exchange menu names change from time to time; these three rules are what matter.
API keys are free on all four exchanges. Orders pay the exchange's normal trading fees, and futures positions pay or receive funding.
02Find your server IP
Open https://your-domain/api/server-ip. It answers {"ip":"203.0.113.7"}. The app shows the same IP under Settings, Exchange accounts, and on each account's Key safety page. The value comes from SERVER_PUBLIC_IP in .env, which the installer fills in; if it is empty, ask your hosting provider for the server's IPv4 address and set it.
03Binance
- Open API Management (Profile, API Management) and create a key of type System generated.
- Permissions: tick Enable Spot & Margin Trading and/or Enable Futures. Leave Enable Withdrawals and Enable Internal Transfer unticked: KESTREL refuses the key if either is on. It needs no other transfer permission, so leave those off as well.
- IP access: choose Restrict access to trusted IPs only and add the server IP.
- Copy the API key and the secret key. Binance shows the secret only once.
KESTREL reads the key's restrictions from Binance and treats internal transfer like a withdrawal, because it can move funds to another Binance account (server/src/exchanges/permissions.ts). Futures means USDT-margined perpetuals.
04OKX
- Open API (Profile, API) and create an API key for KESTREL.
- Permissions: Read and Trade. Not Withdraw.
- Passphrase: choose one and keep it. The app asks for it.
- IP allowlist: add the server IP.
05Bybit
- Open API (Profile, API, Create New Key) and choose System-generated API Keys.
- Permissions: Read-Write, with Orders and Positions for the products you trade (Spot trade, Contract or Derivatives). Do not select Wallet withdrawal.
- IP restriction: choose Only IPs with permissions granted are allowed and add the server IP.
A read-only Bybit key is refused as "cannot trade"; a key with the Wallet Withdraw permission is refused as "can withdraw".
06Bitget
- Open API Keys (Profile, API Keys, Create API Key), system-generated.
- Permissions: Read-Write for trade (spot and/or futures). No Withdraw: KESTREL refuses a key with withdraw authority. It does not need Transfer either, so leave it off (KESTREL does not check it).
- Passphrase: set one; the app asks for it.
- Bind the IP address of your server.
KESTREL refuses a Bitget key whose permission list contains a name it does not know, so a new kind of permission can never slip through unchecked.
07Connect the key in the app
- Settings, Exchange accounts, Connect exchange.
- Pick the exchange and the mode. Live trades real funds. Testnet uses the exchange's test or demo-trading environment with its own keys (Bybit: demo trading). Paper needs no key.
- Paste the API key, the secret and, for OKX and Bitget, the passphrase. Add a label if you like.
- Press Check key and connect. The server reads the key's permissions first and only then stores it.
| Answer | Meaning | What to do |
|---|---|---|
withdraw_permission_enabled | The key can withdraw (on Binance: or has internal transfer enabled). | Create a new key with withdrawals off (on Binance also internal transfer off). |
trade_permission_missing | The key cannot trade. | Enable spot and/or futures trading on the key. |
invalid_credentials | The exchange did not accept the key. | Check key, secret, passphrase and the IP whitelist. |
| "Could not verify this key's permissions" | The permissions could not be read with certainty, so the key is refused (fail-closed). | Create a plain trade-only key and try again. |
hedge_mode_unsupported | The futures account is in hedge mode. | Switch it to one-way (below), then add the key again. |
The secret is sent once to your server, encrypted at rest, and never shown again, not even to you. The app shows only a hint such as AbCd…wXyZ.
08Why withdraw keys are refused
KESTREL only needs to place and cancel orders. A key that can only trade cannot move funds off the exchange, so even if the server, the database or a backup were ever stolen, the attacker could not withdraw. A key with withdrawals on would turn every one of those risks into a risk of losing the funds. That is why the server refuses such keys outright and has no deposit or withdrawal feature at all. Together with the IP whitelist, a leaked key is useless anywhere except on your own server.
09Hedge mode
KESTREL works in one-way position mode: one net position per symbol. Switch every futures account to one-way mode on the exchange before you add its key.
- Binance (USDT-M futures) and OKX: the server reads the position mode and refuses a hedge-mode account with
hedge_mode_unsupported. - Bybit and Bitget: the mode cannot be read through the exchange library, so it is recorded as "unknown". The account is accepted, and the app reminds you that hedge mode is not supported. Set one-way mode on the exchange yourself.
Paper accounts always simulate one-way positions.
10Rotate or remove a key
- Rotate key (the account's Key safety page, or Safety): the new key is checked first, and the old one is replaced only if the new one can trade and cannot withdraw. Nothing is stopped. Rotating also clears the account's error and back-off state.
- Remove: the account's bots and Smart Trades are stopped first, then the encrypted key is deleted from the server. Positions on the exchange stay open.
- If a key is revoked on the exchange, the watchdog marks the account error, stops retrying it and probes it once every 15 minutes until you rotate the key (Watchdog).