Bybit V5

Bybit AI Skills

Unified API skill for Bybit V5 covering all product types: spot, linear (USDT/USDC perpetuals), inverse (inverse perpetuals/futures), and option. All endpoints share a common category parameter to specify the product type. Returns results in JSON format.

Authentication

Base URLs

Agent SHALL auto-select the base URL based on the account's Region field. If no region is set, default to https://api.bybit.com. Testnet accounts always use https://api-testnet.bybit.com.

Required Headers

Signing Process

Step 1: Build the string to sign

For GET requests:

{timestamp}{apiKey}{recvWindow}{queryString}

For POST requests:

{timestamp}{apiKey}{recvWindow}{jsonBodyString}

Step 2: Generate HMAC-SHA256 signature

echo -n "${PARAM_STR}" | openssl dgst -sha256 -hmac "${SECRET_KEY}" | cut -d' ' -f2

The result is a lowercase hex string.

Step 3: Include signature in X-BAPI-SIGN header

Complete Examples

GET request (authenticated):

#!/bin/bash
API_KEY="your_api_key"
SECRET_KEY="your_secret_key"
BASE_URL="https://api.bybit.com"
RECV_WINDOW=5000
TIMESTAMP=$(date +%s000)

QUERY="category=linear&symbol=BTCUSDT"
PARAM_STR="${TIMESTAMP}${API_KEY}${RECV_WINDOW}${QUERY}"
SIGN=$(echo -n "$PARAM_STR" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

curl -s "${BASE_URL}/v5/position/list?${QUERY}" \
  -H "X-BAPI-API-KEY: ${API_KEY}" \
  -H "X-BAPI-TIMESTAMP: ${TIMESTAMP}" \
  -H "X-BAPI-SIGN: ${SIGN}" \
  -H "X-BAPI-RECV-WINDOW: ${RECV_WINDOW}" \
  -H "User-Agent: bybit-v5/1.0.0 (Skill)"

POST request (place order):

#!/bin/bash
API_KEY="your_api_key"
SECRET_KEY="your_secret_key"
BASE_URL="https://api.bybit.com"
RECV_WINDOW=5000
TIMESTAMP=$(date +%s000)

BODY='{"category":"spot","symbol":"BTCUSDT","side":"Buy","orderType":"Market","qty":"0.001"}'
PARAM_STR="${TIMESTAMP}${API_KEY}${RECV_WINDOW}${BODY}"
SIGN=$(echo -n "$PARAM_STR" | openssl dgst -sha256 -hmac "$SECRET_KEY" | cut -d' ' -f2)

curl -s -X POST "${BASE_URL}/v5/order/create" \
  -H "Content-Type: application/json" \
  -H "X-BAPI-API-KEY: ${API_KEY}" \
  -H "X-BAPI-TIMESTAMP: ${TIMESTAMP}" \
  -H "X-BAPI-SIGN: ${SIGN}" \
  -H "X-BAPI-RECV-WINDOW: ${RECV_WINDOW}" \
  -H "User-Agent: bybit-v5/1.0.0 (Skill)" \
  -d "${BODY}"

Response Format

All Bybit V5 responses follow this structure:

{
  "retCode": 0,
  "retMsg": "OK",
  "result": { },
  "retExtInfo": {},
  "time": 1672211918471
}

retCode=0 means success. Non-zero indicates an error.

Rate Limit Response Headers:

• X-Bapi-Limit — Your rate limit for this endpoint
• X-Bapi-Limit-Status — Remaining requests in current window
• X-Bapi-Limit-Reset-Timestamp — When limit resets (ms)

Quick Reference

Market Data (No Authentication)

Trade (Authentication Required)

Position (Authentication Required)

Account (Authentication Required)

Asset (Authentication Required)

User (Authentication Required)

Spot Margin — Unified Account (Authentication Required)

Leverage Token (Authentication for Purchase/Redeem)

Broker (Authentication Required)

Earn (Authentication Required)

Crypto Loan

Crypto Loan — Common (Authentication Required)

Crypto Loan — Fixed Term (Authentication Required)

Crypto Loan — Flexible (Authentication Required)

Institutional Loan (Authentication Required)

RFQ — Block Trading (Authentication Required, 50/s)

Spread Trade (Authentication Required)

Fiat (Authentication Required)

Lending (Authentication Required)

API Rate Limit (Authentication Required)

Parameters

Common Parameters

• category: Product type — spot, linear, inverse, option
• symbol: Trading pair symbol, uppercase (e.g., BTCUSDT, ETH-25DEC22-1400-C)
• side: Buy, Sell
• orderType: Market, Limit
• qty: Order quantity (string)
• price: Order price (string, required for Limit orders)
• timeInForce: GTC (default), IOC, FOK, PostOnly, RPI
• orderLinkId: Custom order ID (max 36 chars, unique among open orders)
• positionIdx: 0 (one-way mode), 1 (hedge-mode buy side), 2 (hedge-mode sell side)
• triggerPrice: Conditional order trigger price (string)
• triggerBy: Trigger price type — LastPrice, IndexPrice, MarkPrice
• reduceOnly: true = reduce position only
• closeOnTrigger: true = close order behavior
• isLeverage: 0 (no borrow, default), 1 (margin trading, spot only)
• orderFilter: Spot only — Order (default), tpslOrder, StopOrder
• marketUnit: Spot market orders — baseCoin, quoteCoin. Tip: For spot market Buy orders, prefer marketUnit=quoteCoin with qty as the USDT amount (e.g., "qty":"7000","marketUnit":"quoteCoin") for more reliable execution. Using baseCoin qty may hit "Order value exceeded lower limit" on some environments.

TP/SL Parameters

Used on /v5/order/create, /v5/order/amend, and /v5/position/trading-stop:

• takeProfit: Take profit price (pass "0" to cancel)
• stopLoss: Stop loss price (pass "0" to cancel)
• tpTriggerBy: TP trigger price type — LastPrice (default), IndexPrice, MarkPrice
• slTriggerBy: SL trigger price type — LastPrice (default), IndexPrice, MarkPrice
• tpslMode: Full (entire position), Partial (specify size)
• tpSize: TP quantity for partial mode
• slSize: SL quantity for partial mode
• tpLimitPrice: Limit price when TP is triggered (partial mode, Limit order)
• slLimitPrice: Limit price when SL is triggered (partial mode, Limit order)
• tpOrderType: Market (default), Limit
• slOrderType: Market (default), Limit
• trailingStop: Trailing stop distance (pass "0" to cancel, position only)
• activePrice: Trailing stop activation price (position only)

Enums

• category: spot | linear | inverse | option
• side: Buy | Sell
• orderType: Market | Limit
• timeInForce: GTC | IOC | FOK | PostOnly | RPI
• triggerBy: LastPrice | IndexPrice | MarkPrice
• positionIdx: 0 (one-way) | 1 (hedge-buy) | 2 (hedge-sell)
• accountType: UNIFIED | FUND
• tpslMode: Full | Partial
• tradeMode: 0 (cross margin) | 1 (isolated margin)
• positionMode: 0 (MergedSingle / one-way) | 3 (BothSide / hedge)
• orderStatus (open): New | PartiallyFilled | Untriggered
• orderStatus (closed): Rejected | PartiallyFilledCanceled | Filled | Cancelled | Triggered | Deactivated
• execType: Trade | AdlTrade | Funding | BustTrade | Delivery | Settle | BlockTrade | MovePosition
• stopOrderType: TakeProfit | StopLoss | TrailingStop | Stop | PartialTakeProfit | PartialStopLoss | tpslOrder | OcoOrder
• cancelType: CancelByUser | CancelByReduceOnly | CancelByPrepareLiq | CancelByPrepareAdl | CancelByAdmin | CancelBySettle | CancelByTpSlTsClear | CancelBySmp | CancelByDCP
• 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
• setMarginMode: ISOLATED_MARGIN | REGULAR_MARGIN | PORTFOLIO_MARGIN
• collateralSwitch: ON | OFF
• autoAddMargin: 0 (off) | 1 (on)
• frozen (sub account): 0 (unfreeze) | 1 (freeze)
• memberType (sub account): 1 (normal) | 6 (custodial)
• spotMarginMode: 0 (off) | 1 (on)
• direction (collateral adjust): ADD | REDUCE
• earnOrderType: Stake | Redeem

WebSocket Reference

For agents that need real-time push notifications (e.g., always-on assistants).

Public Streams

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

Where {category} = spot, linear, inverse, option

Private Streams

URL: wss://stream.bybit.com/v5/private Testnet: wss://stream-testnet.bybit.com/v5/private

Subscription Format

{"op": "subscribe", "args": ["orderbook.50.BTCUSDT", "publicTrade.BTCUSDT"]}

Unsubscribe:

{"op": "unsubscribe", "args": ["orderbook.50.BTCUSDT"]}

Heartbeat: Send {"op": "ping"} every 20 seconds.

Private Stream Authentication

{"op": "auth", "args": ["<apiKey>", "<expires>", "<signature>"]}

Where:

• expires = future timestamp in milliseconds
• signature = HMAC-SHA256 of GET/realtime{expires} using secret key

Security

Share Credentials

Users can provide Bybit API credentials by sending a file:

abc123...xyz
secret123...key

Never Display Full Secrets

When showing credentials to users:

• API Key: Show first 5 + last 4 characters: su1Qc...8akf
• Secret Key: Always mask, show only last 5: ***...aws1

Example:

Account: main
API Key: su1Qc...8akf
Secret: ***...aws1
Environment: Mainnet
Region: Global

Listing Accounts

Show names, environment, and region only — never keys:

Bybit Accounts:
* main (Mainnet, Global)
* testnet-dev (Testnet)
* uae-trading (Mainnet, UAE)

Mainnet Confirmation Rules

Not all requests need confirmation. Only mainnet write operations require user to type "CONFIRM":

…(truncated)