Bybit Trading

Bybit Trading Skill

Trade on Bybit using natural language. Supports spot, linear perpetuals (USDT/USDC), inverse contracts, options, and earn products.

Version: 1.0.0 | Updated: 2026-03-10 | Architecture: Monolithic (single file; modules inlined)

Quick Start

Step 1: Get an API Key

1. Log in to Bybit → API Management → Create New Key
2. Permissions: enable Read + Trade only (NEVER enable Withdraw for AI use)
3. Recommended: bind your IP address (makes the key permanent; otherwise expires in 3 months)
4. Strongly recommended: Create a dedicated sub-account for AI trading with limited balance

Step 2: Configure Credentials

Credential setup depends on where the AI runs. Auto-detect the environment and follow the matching path:

Path A — Local CLI (Claude Code, Cursor, or any tool with shell access):

# User sets once in shell profile (~/.zshrc or ~/.bashrc):
export BYBIT_API_KEY="your_api_key"
export BYBIT_API_SECRET="your_secret_key"
export BYBIT_ENV="mainnet"  # or "testnet"

On first use, check if these environment variables exist. If they do, use them directly — do NOT ask the user to paste keys in the conversation. If they don't exist, guide the user to set them up:

1. Tell the user: "For security, I recommend storing your API keys as environment variables instead of pasting them here."
2. Provide the export commands above
3. After the user has set them, verify with echo $BYBIT_API_KEY | head -c5 (only show first 5 chars to confirm)

Path B — Self-hosted OpenClaw (user runs OpenClaw on their own machine/server):

Keys stay on the user's machine — same security level as Path A. Configure via .env file:

# Option 1: Global config (recommended) — ~/.openclaw/.env
BYBIT_API_KEY=your_api_key
BYBIT_API_SECRET=your_secret_key
BYBIT_ENV=mainnet

# Option 2: Project-level — ./.env in working directory (higher priority)
# Option 3: openclaw.json env block
# { "env": { "vars": { "BYBIT_API_KEY": "...", "BYBIT_API_SECRET": "...", "BYBIT_ENV": "mainnet" } } }

On first use, check if these environment variables exist. If they do, use them directly. If they don't, guide the user to create ~/.openclaw/.env with the variables above.

Path C — Cloud platforms (hosted OpenClaw, Claude.ai, ChatGPT, Gemini, and other hosted AI services):

These platforms have no secret store. Keys must be pasted in the conversation (sent to AI provider's servers).

On first use:

1. Accept keys pasted in the conversation
2. Warn once: "Your keys will be sent through this platform's servers. For safety, use a sub-account with limited balance and Read+Trade permissions only (no Withdraw)."
3. Do NOT ask again in the same session

Fallback (all platforms): If the user provides keys directly in the conversation, accept them but remind once about the more secure alternative for their platform.

Display rules (never show full credentials):

• API Key: show first 5 + last 4 characters (e.g., AbCdE...x1y2)
• Secret Key: show last 5 only (e.g., ***...vWxYz)
• Code blocks: NEVER include raw API Key or Secret Key values in generated code, scripts, or curl examples. Use placeholder variables like ${API_KEY} and ${SECRET_KEY} instead of actual values. This applies to ALL output formats including bash, python, and JSON.

Step 3: Verify Connection (auto-run on first use)

After credentials are configured, automatically run these checks:

# 1. Clock sync check (no auth needed)
GET /v5/market/time
# Compare response "timeSecond" with local time. If difference > 5 seconds:
#   → Tell user: "Your system clock is off by Xs. Please sync your clock (e.g., enable automatic date/time in system settings)."
#   → Do NOT proceed with authenticated requests until clock is synced (signatures will fail).

# 2. Verify signature and permissions
GET /v5/account/wallet-balance?accountType=UNIFIED

• If clock difference > 5s: stop and ask user to fix clock sync first
• If retCode=0: credentials are valid. Tell user "Connected to Bybit [Mainnet/Testnet]. Account verified."
• If retCode=10003/10004: signature error. Check timestamp sync and signature calculation.
• If retCode=10005: insufficient permissions. Tell user to check API Key permissions.
• If retCode=10010: IP not whitelisted. Tell user to add current IP in API Key settings.

Step 4: Choose Environment

Default: Mainnet. Always start in Mainnet mode unless the user explicitly requests Testnet.

Switching rules:

• To switch to Testnet, the user must explicitly say "switch to testnet" / "use test account" / "use demo"
• When switching to Testnet, display: "Switching to TESTNET. All operations will use test funds — no real money at risk."
• Always show the current environment in every response that involves API calls: [MAINNET] or [TESTNET]
• If the user provides a Testnet API Key (starts with testing), automatically use Testnet URL

Step 5: Start Trading

Tell the user what they can do. Examples:

• "What's the BTC price?"
• "Buy 500 USDT worth of BTC"
• "Open a 10x BTC long position"
• "Check my balance"
• If you'd like to practice first, say "switch to testnet" to use test funds.

Modules (Inlined)

ClawHub skills do not support modular routing. This file includes all modules inline.

Module Index (Intent Map)

Market Data

Scenario: Check Market Data

User might say: "What's the BTC price?", "Show me ETH chart", "What's the current funding rate?"

Get real-time price

GET /v5/market/tickers?category=spot&symbol=BTCUSDT
GET /v5/market/tickers?category=linear&symbol=BTCUSDT  (derivatives)

Get candlestick/kline data

GET /v5/market/kline?category=linear&symbol=BTCUSDT&interval=60&limit=100

interval: 1 3 5 15 30 60 120 240 360 720 D W M (minutes or day/week/month)

Get funding rate

GET /v5/market/funding/history?category=linear&symbol=BTCUSDT&limit=10

Get orderbook depth

GET /v5/market/orderbook?category=linear&symbol=BTCUSDT&limit=50

Market data endpoints require no authentication and can be called directly.

API Reference

Enums

• interval (kline): 1 | 3 | 5 | 15 | 30 | 60 | 120 | 240 | 360 | 720 | D | W | M
• intervalTime (open interest): 5min | 15min | 30min | 1h | 4h | 1d
• period (long/short ratio): 5min | 15min | 30min | 1h | 4h | 1d
• category: spot | linear | inverse | option

Spot Trading

Scenario: Spot Trading

User might say: "Buy 500U of BTC", "Sell all my ETH", "Place a limit order"

Market buy (recommended: use quoteCoin to specify USDT amount)

POST /v5/order/create
{"category":"spot","symbol":"BTCUSDT","side":"Buy","orderType":"Market","qty":"500","marketUnit":"quoteCoin"}

Market sell (use baseCoin to specify coin quantity)

POST /v5/order/create
{"category":"spot","symbol":"ETHUSDT","side":"Sell","orderType":"Market","qty":"2.5"}

Limit buy

POST /v5/order/create
{"category":"spot","symbol":"BTCUSDT","side":"Buy","orderType":"Limit","qty":"0.01","price":"80000","timeInForce":"GTC"}

View open orders

GET /v5/order/realtime?category=spot&symbol=BTCUSDT

Cancel order

POST /v5/order/cancel
{"category":"spot","symbol":"BTCUSDT","orderId":"xxx"}

Important: For spot market buy orders, using marketUnit=quoteCoin + USDT amount is recommended over specifying coin quantity — it is more reliable.

API Reference

Trade (authentication required)

Spot Margin (authentication required)

Enums

• side: Buy | Sell
• orderType: Market | Limit
• timeInForce: GTC | IOC | FOK | PostOnly | RPI
• orderStatus (open): New | PartiallyFilled | Untriggered
• orderStatus (closed): Rejected | PartiallyFilledCanceled | Filled | Cancelled | Triggered | Deactivated
• spotMarginMode: 0 (off) | 1 (on)
• marketUnit: baseCoin | quoteCoin (spot market buy only)

Derivatives Trading

Scenario: Derivatives Trading

User might say: "Open a BTC long with 10x leverage", "Close position", "Set take profit at 90000"

Pre-trade preparation

### 1. Check current account mode
GET /v5/account/info
### Returns marginMode: REGULAR_MARGIN / ISOLATED_MARGIN / PORTFOLIO_MARGIN

### 2. Check position mode (MUST do before any write operation)
GET /v5/position/list?category=linear&symbol=BTCUSDT
### Response positionIdx: 0 → one-way mode, 1 or 2 → hedge mode
### One-way: use positionIdx=0 for all orders
### Hedge: use positionIdx=1 (Buy/Long), positionIdx=2 (Sell/Short)

### 2b. (Optional) Switch position mode — only if user explicitly requests
POST /v5/position/switch-mode
{"category":"linear","coin":"USDT","mode":0}   # 0=one-way, 3=hedge
### retCode=0 → switched successfully
### retCode=110025 → already in target mode
### retCode=110026 → cannot switch while holding positions or active orders

### 3. Set leverage (buy and sell leverage must match)
POST /v5/position/set-leverage
{"category":"linear","symbol":"BTCUSDT","buyLeverage":"10","sellLeverage":"10"}

Position mode check: Always query position mode via /v5/position/list before placing the first order in a session. Cache the result (one-way vs hedge) and use the correct positionIdx for all subsequent orders. One-way mode: positionIdx=0. Hedge mode: positionIdx=1 (long), positionIdx=2 (short). Never call switch-mode to "detect" — it changes state.

Open long

POST /v5/order/create
{"category":"linear","symbol":"BTCUSDT","side":"Buy","orderType":"Market","qty":"0.01","positionIdx":0}
### positionIdx=0 for one-way mode; use 1 for hedge mode long

Open short

POST /v5/order/create
{"category":"linear","symbol":"BTCUSDT","side":"Sell","orderType":"Market","qty":"0.01","positionIdx":0}
### positionIdx=0 for one-way mode; use 2 for hedge mode short

Open position with take profit and stop loss

POST /v5/order/create
{"category":"linear","symbol":"BTCUSDT","side":"Buy","orderType":"Market","qty":"0.01",
 "takeProfit":"90000","stopLoss":"78000","tpslMode":"Full"}

View positions

GET /v5/position/list?category=linear&symbol=BTCUSDT

Close position (recommended: query size first, then close)

### 1. Query actual position size
GET /v5/position/list?category=linear&symbol=BTCUSDT
### Read "size" from response to get exact position quantity

### 2. Close with exact quantity
POST /v5/order/create
{"category":"linear","symbol":"BTCUSDT","side":"Sell","orderType":"Market","qty":"<size_from_step_1>","reduceOnly":true,"positionIdx":0}

Shortcut: On Bybit V5 linear/inverse, qty="0" + reduceOnly=true closes the entire position. Use this only when you're confident the symbol supports it. The query-first approach is safer and works across all categories.

Modify take profit / stop loss

POST /v5/position/trading-stop
{"category":"linear","symbol":"BTCUSDT","takeProfit":"92000","stopLoss":"79000","tpslMode":"Full","positionIdx":0}

Hedge mode handling:

• If an order returns retCode=10001 "position idx not match position mode", the account is in hedge mode
• Use positionIdx=1 for long, positionIdx=2 for short
• Remember the account is in hedge mode and automatically include positionIdx in subsequent orders

Category confirmation: When the user says "BTCUSDT", you must confirm whether they mean spot or derivatives — do not assume.

Scenario: Conditional Orders & Advanced Orders

User might say: "Buy BTC when it hits 85000", "Set a trailing stop"

Conditional order (trigger price order)

POST /v5/order/create
{"category":"linear","symbol":"BTCUSDT","side":"Buy","orderType":"Market","qty":"0.01",
 "triggerPrice":"85000","triggerDirection":2,"triggerBy":"LastPrice"}

triggerDirection is required for conditional orders:

• 1 = triggered when price rises to triggerPrice (triggerPrice > current price)
• 2 = triggered when price falls to triggerPrice (triggerPrice < current price)

Rule of thumb: buying the dip → triggerDirection=2; breakout buy → triggerDirection=1.

Trailing stop

POST /v5/position/trading-stop
{"category":"linear","symbol":"BTCUSDT","trailingStop":"500","activePrice":"88000","positionIdx":0}

trailingStop="500" means the stop triggers when price retraces by $500. activePrice is the activation price (tracking begins only after this price is reached).

API Reference

Trade (authentication required)

Position (authentication required)

Enums

• positionIdx: 0 (one-way) | 1 (hedge-buy) | 2 (hedge-sell)
• positionMode: 0 (MergedSingle / one-way) | 3 (BothSide / hedge)
• tradeMode: 0 (cross margin) | 1 (isolated margin)
• triggerBy: LastPrice | IndexPrice | MarkPrice
• tpslMode: Full | Partial
• stopOrderType: TakeProfit | StopLoss | TrailingStop | Stop | PartialTakeProfit | PartialStopLoss | tpslOrder | OcoOrder
• execType: Trade | AdlTrade | Funding | BustTrade | Delivery | Settle | BlockTrade | MovePosition
• setMarginMode: ISOLATED_MARGIN | REGULAR_MARGIN | PORTFOLIO_MARGIN
• autoAddMargin: 0 (off) | 1 (on)

Take Profit / Stop Loss Parameters

Earn

Scenario: Earn Products

User might say: "Show me available earn products", "Deposit USDT", "Redeem"

View product list

GET /v5/earn/product?category=FlexibleSaving&coin=USDT

Use the returned productId for place-order requests.

Stake

POST /v5/earn/place-order
{"category":"FlexibleSaving","orderType":"Stake","accountType":"UNIFIED","coin":"USDT","amount":"1000","productId":"123","orderLinkId":"unique-id-123"}

All 7 params above are required. Get productId from the product list first.

View orders

GET /v5/earn/order?category=FlexibleSaving

View yield history

GET /v5/earn/yield?category=FlexibleSaving&coin=USDT

Redeem

POST /v5/earn/place-order
{"category":"FlexibleSaving","orderType":"Redeem","accountType":"UNIFIED","coin":"USDT","amount":"500","productId":"123","orderLinkId":"unique-id-456"}

API Reference

Earn (authentication required)

Enums

• orderType: Stake | Redeem
• accountType: FUND | UNIFIED (OnChain only supports FUND)
• earn category: FlexibleSaving | OnChain

Account & Asset Management

Scenario: Account & Asset Management

User might say: "Check my balance", "Transfer from spot to derivatives", "Show today's trade history"

View wallet balance

GET /v5/account/wallet-balance?accountType=UNIFIED

View fee rate

GET /v5/account/fee-rate?category=linear&symbol=BTCUSDT

Internal transfer (spot <-> derivatives <-> funding account)

POST /v5/asset/transfer/inter-transfer
{"transferId":"uuid","coin":"USDT","amount":"1000","fromAccountType":"UNIFIED","toAccountType":"FUND"}

View trade history

GET /v5/execution/list?category=linear&symbol=BTCUSDT

View realized PnL

GET /v5/position/closed-pnl?category=linear&symbol=BTCUSDT

API Reference

Account (authentication required)

Asset (authentication required)

User (authentication required)

Enums

• accountType: UNIFIED | FUND
• collateralSwitch: ON | OFF
• frozen (sub account): 0 (unfreeze) | 1 (freeze)
• memberType (sub account): 1 (normal) | 6 (custodial)

Advanced Features

WebSocket

Use WebSocket when real-time push is needed. The REST API covers most scenarios.

Public Stream

URL: wss://stream.bybit.com/v5/public/{category} Testnet: wss://stream-testnet.bybit.com/v5/public/{category}

Private Stream

URL: wss://stream.bybit.com/v5/private

Subscribe: {"op": "subscribe", "args": ["orderbook.50.BTCUSDT"]} Heartbeat: Send {"op": "ping"} every 20 seconds Auth: {"op": "auth", "args": ["<apiKey>", "<expires>", "<signature>"]}

Crypto Loan

Crypto Loan — Common (authentication required)

Crypto Loan — Fixed Term (authentication required)

Crypto Loan — Flexible (authentication required)

Institutional Loan (authentication required)

…(truncated)