API key permissions, IP whitelist and the unified trading account
The key you give to the bot defines what the bot can do on your account. The rule is simple: permission to trade on the market you need — yes, permission to withdraw funds — never.
Which permissions the key needs
| Bot type | Permission on Bybit |
|---|---|
| Bybit Spot | Spot Trading (or Order + Position) |
| Bybit Futures | Derivatives / Contract Trading (or Order + Position) — orders and positions |
The bot does not need withdrawal and transfer permissions: it only places and cancels orders. Do not grant them — you lose no features that way, and the key becomes safer.
A copy-trading master account key does not fit: the bot rejects it, because all orders of Grid and DCA bots would be copied automatically to your followers. Use a regular account.
The permissions are checked when you send the keys to the bot. If the permissions are revoked on the exchange later, trades stop opening and the bot sends a notification with the reason.
IP whitelist
On Bybit a key can be restricted to a list of IP addresses it works from. If there is no such restriction, the bot warns you once when the keys are saved:
⚠️ API key without IP whitelist Your API key works from any IP, which increases the risk if the key is compromised. We recommend adding to your exchange key settings IP whitelist — only our server IP: [the address the bot shows] This is not mandatory, the bot works without IP whitelist. But IP whitelist adds an extra security layer.
The whitelist is an extra layer of protection: even if the key leaks, it will not work from someone else's address. It is configured on the Bybit side in the key parameters; nothing has to be changed in the bot.
Unified trading account (UTA)
Bybit works in unified trading account mode. What matters here for the bot:
- The margin mode is set for the whole account, not for a single pair. If the bot could not switch CROSS/ISOLATED, the trade opens in the account's current mode, and the mode you need has to be set by hand: Bybit → Account settings → Margin mode. See Margin type.
- Collateral. If a coin is not included in the collateral, the exchange rejects the order — enable it in the collateral settings of the unified account.
- Verification. For some operations the exchange requires KYC Level 2; without it orders are rejected.
- Trading terms. The exchange may ask you to confirm a market that is new for you by hand — open it in the Bybit app and accept the terms.
- Protections count the whole account. For example, the margin overload protection of a Grid bot looks at the margin of the whole account, so other positions on the same account can stop the bot. For bots it is convenient to open a separate subaccount.
Limits and allowed values
| Parameter | Value | Note |
|---|---|---|
| Permission for spot | Spot Trading | Or Order + Position |
| Permission for futures | Derivatives / Contract Trading | Or Order + Position |
| Withdrawal permission | Not needed | Do not grant it |
| Copy-trading (master) key | Not accepted | Regular account only |
| IP whitelist | Recommended, not mandatory | The bot shows the server address itself |
| Margin mode on UTA | One for the whole account | Changed in the Bybit settings |
Common errors and what the bot says
- “API keys do not have the required permissions” — during bot creation: the key has no permission for the chosen market. The bot does not say which permission exactly is missing — check the table above.
- “Your API key is invalid or lacks required permissions. Update API keys according to the instructions” — during work: reissue the key and replace it through the bot card → Bot settings → Update API keys.
- “API keys have expired. (You can update them in bot settings)” — the key's validity period on Bybit has ended.
- “The API key has no permission for this operation” — the permissions were revoked after the bot was created.
- “ℹ️ Couldn't set the margin mode 'ISOLATED' automatically. On Unified Trading (UTA) accounts the margin mode is set at the account level, not per symbol. The trade was opened using the account's current mode…” — set the mode by hand on the exchange.
- “This API key belongs to a copy-trading master account…” — use a key of a regular account.