Websocket Trade Guideline

URL

Mainnet:
wss://stream.bybit.com/v5/trade

info

Turkey users registered from "www.bybit-tr.com", please use wss://stream.bybit-tr.com/v5/trade
Kazakhstan users registered from "www.bybit.kz", please use wss://stream.bybit.kz/v5/trade

Testnet:
wss://stream-testnet.bybit.com/v5/trade

Scope

Support: USDT Contract, USDC Contract, Spot, Options, Inverse contract
Not support: demo trading, spread trading

Authentication

Request Parameters

Parameter	Required	Type	Comments
reqId	false	string	Optional field, used to match the response If not passed, this field will not be returned in response
op	true	string	Op type. `auth`
args	true	string	["api key", expiry timestamp, "signature"]. Please click here to generate signature

Response Parameters

Parameter	Type	Comments
reqId	string	If it is passed on the request, then it is returned in the response If it is not passed, then it is not returned in the response
retCode	integer	`0`: auth success `20001`: repeat auth `10004`: invalid sign `10001`: param error
retMsg	string	`OK` Error message
op	string	Op type
connId	string	Connection id, the unique id for the connection

Request Example

{
    "op": "auth",
    "args": [
        "XXXXXX",
        1711010121452,
        "ec71040eff72b163a36153d770b69d6637bcb29348fbfbb16c269a76595ececf"
    ]
}

Response Example

{
    "retCode": 0,
    "retMsg": "OK",
    "op": "auth",
    "connId": "cnt5leec0hvan15eukcg-2t"
}

Create/Amend/Cancel Order

Request Parameters

Parameter	Required	Type	Comments
reqId	false	string	Used to identify the uniqueness of the request, the response will return it when passed. The length cannot exceed 36 characters. If passed, it can't be duplicated, otherwise you will get "20006"
header	true	object	Request headers
> X-BAPI-TIMESTAMP	true	string	Current timestamp
> X-BAPI-RECV-WINDOW	false	string	5000(ms) by default. Request will be rejected when not satisfy this rule: Bybit_server_time - X-BAPI-RECV-WINDOW <= X-BAPI-TIMESTAMP < Bybit_server_time + 1000
> Referer	false	string	The referer identifier for API broker user
op	true	string	Op type `order.create`: create an order `order.amend`: amend an order `order.cancel`: cancel an order
args	true	array<object>	Args array, support one item only for now `order.create`: refer to create order request `order.amend`: refer to amend order request `order.cancel`: refer to cancel order request

Response Parameters

Parameter	Type	Comments
reqId	string	If it is passed on the request, then it is returned in the response If it is not passed, then it is not returned in the response
retCode	integer	`0`: success `10403`: exceed IP rate limit. 3000 requests per second per IP `10404`: 1. op type is not found; 2. `category` is not correct/supported `10429`: System level frequency protection `20006`: reqId is duplicated `10016`: 1. internal server error; 2. Service is restarting `10019`: ws trade service is restarting, do not accept new request, but the request in the process is not affected. You can build new connection to be routed to normal service
retMsg	string	`OK` `""` Error message
op	string	Op type
data	object	Business data, keep the same as `result` on rest api response `order.create`: refer to create order response `order.amend`: refer to amend order response `order.cancel`: refer to cancel order response
retExtInfo	object	Always empty object
header	object	Header info
> TraceId	string	Trace ID, used to track the trip of request
> Timenow	string	Current timestamp
> X-Bapi-Limit	string	The total rate limit of the current account for this op type
> X-Bapi-Limit-Status	string	The remaining rate limit of the current account for this op type
> X-Bapi-Limit-Reset-Timestamp	string	The timestamp indicates when your request limit resets if you have exceeded your rate limit. Otherwise, this is just the current timestamp (it may not exactly match `timeNow`)
connId	string	Connection id, the unique id for the connection

info

The ack of create/amend/cancel order request indicates that the request is successfully accepted. Please use websocket order stream to confirm the order status

Request Example

{
    "reqId": "test-005",
    "header": {
        "X-BAPI-TIMESTAMP": "1711001595207",
        "X-BAPI-RECV-WINDOW": "8000",
        "Referer": "bot-001" // for api broker
    },
    "op": "order.create",
    "args": [
        {
            "symbol": "ETHUSDT",
            "side": "Buy",
            "orderType": "Limit",
            "qty": "0.2",
            "price": "2800",
            "category": "linear",
            "timeInForce": "PostOnly"
        }
    ]
}

Response Example

{
    "reqId": "test-005",
    "retCode": 0,
    "retMsg": "OK",
    "op": "order.create",
    "data": {
        "orderId": "a4c1718e-fe53-4659-a118-1f6ecce04ad9",
        "orderLinkId": ""
    },
    "retExtInfo": {},
    "header": {
        "X-Bapi-Limit": "10",
        "X-Bapi-Limit-Status": "9",
        "X-Bapi-Limit-Reset-Timestamp": "1711001595208",
        "Traceid": "38b7977b430f9bd228f4b19724794dfd",
        "Timenow": "1711001595209"
    },
    "connId": "cnt5leec0hvan15eukcg-2v"
}

Batch Create/Amend/Cancel Order

info

A maximum of 20 orders (option), 20 orders (inverse), 20 orders (linear), 10 orders (spot) can be placed per request. The returned data list is divided into two lists. The first list indicates whether or not the order creation was successful and the second list details the created order information. The structure of the two lists are completely consistent.

Option rate limt instruction: its rate limit is count based on the actual number of request sent, e.g., by default, option trading rate limit is 10 reqs per sec, so you can send up to 20 * 10 = 200 orders in one second.
Perpetual, Futures, Spot rate limit instruction, please check here

The account rate limit is shared between websocket and http batch orders
The acknowledgement of batch create/amend/cancel order requests indicates that the request was sucessfully accepted. The request is asynchronous so please use the websocket to confirm the order status.

Request Parameters

Parameter	Required	Type	Comments
reqId	false	string	Used to identify the uniqueness of the request, the response will return it when passed. The length cannot exceed 36 characters. If passed, it can't be duplicated, otherwise you will get "20006"
header	true	object	Request headers
> X-BAPI-TIMESTAMP	true	string	Current timestamp
> X-BAPI-RECV-WINDOW	false	string	5000(ms) by default. Request will be rejected when not satisfy this rule: Bybit_server_time - X-BAPI-RECV-WINDOW <= X-BAPI-TIMESTAMP < Bybit_server_time + 1000
> Referer	false	string	The referer identifier for API broker user
op	true	string	Op type `order.create-batch`: batch create orders `order.amend-batch`: batch amend orders `order.cancel-batch`: batch cancel orders
args	true	array<object>	Args array `order.create-batch`: refer to Batch Place Order request `order.amend-batch`: refer to Batch Amend Order request `order.cancel-batch`: refer to Batch Cancel Order request

Response Parameters

Parameter	Type	Comments
reqId	string	If it is passed on the request, then it is returned in the response If it is not passed, then it is not returned in the response
retCode	integer	`0`: success `10403`: exceed IP rate limit. 3000 requests per second per IP `10404`: 1. op type is not found; 2. `category` is not correct/supported `10429`: System level frequency protection `20006`: reqId is duplicated `10016`: 1. internal server error; 2. Service is restarting `10019`: ws trade service is restarting, do not accept new request, but the request in the process is not affected. You can build new connection to be routed to normal service
retMsg	string	`OK` `""` Error message
op	string	Op type
data	object	Business data, keep the same as `result` on rest api response `order.create-batch`: refer to Batch Place Order response `order.amend-batch`: refer to Batch Amend Order response `order.cancel-batch`: refer to Batch Cancel Order response
retExtInfo	object
> list	array<object>
>> code	number	Success/error code
>> msg	string	Success/error message
header	object	Header info
> TraceId	string	Trace ID, used to track the trip of request
> Timenow	string	Current timestamp
> X-Bapi-Limit	string	The total rate limit of the current account for this op type
> X-Bapi-Limit-Status	string	The remaining rate limit of the current account for this op type
> X-Bapi-Limit-Reset-Timestamp	string	The timestamp indicates when your request limit resets if you have exceeded your rate limit. Otherwise, this is just the current timestamp (it may not exactly match `timeNow`)
connId	string	Connection id, the unique id for the connection

Request Example

{
    "op": "order.create-batch",
    "header": {
        "X-BAPI-TIMESTAMP": "1740453381256",
        "X-BAPI-RECV-WINDOW": "1000"
    },
    "args": [
        {
            "category": "linear",
            "request": [
                {
                    "symbol": "SOLUSDT",
                    "qty": "10",
                    "price": "500",
                    "orderType": "Limit",
                    "timeInForce": "GTC",
                    "orderLinkId": "-batch-000",
                    "side": "Buy"
                },
                {
                    "symbol": "SOLUSDT",
                    "qty": "20",
                    "price": "1000",
                    "orderType": "Limit",
                    "timeInForce": "GTC",
                    "orderLinkId": "batch-001",
                    "side": "Buy"
                },
                {
                    "symbol": "SOLUSDT",
                    "qty": "30",
                    "price": "1500",
                    "orderType": "Limit",
                    "timeInForce": "GTC",
                    "orderLinkId": "batch-002",
                    "side": "Buy"
                }
            ]
        }
    ]
}

Response Example

{
    "retCode": 0,
    "retMsg": "OK",
    "op": "order.create-batch",
    "data": {
        "list": [
            {
                "category": "linear",
                "symbol": "SOLUSDT",
                "orderId": "",
                "orderLinkId": "batch-000",
                "createAt": ""
            },
            {
                "category": "linear",
                "symbol": "SOLUSDT",
                "orderId": "",
                "orderLinkId": "batch-001",
                "createAt": ""
            },
            {
                "category": "linear",
                "symbol": "SOLUSDT",
                "orderId": "",
                "orderLinkId": "batch-002",
                "createAt": ""
            }
        ]
    },
    "retExtInfo": {
        "list": [
            {
                "code": 10001,
                "msg": "position idx not match position mode"
            },
            {
                "code": 10001,
                "msg": "position idx not match position mode"
            },
            {
                "code": 10001,
                "msg": "position idx not match position mode"
            }
        ]
    },
    "header": {
        "Timenow": "1740453408556",
        "X-Bapi-Limit": "150",
        "X-Bapi-Limit-Status": "147",
        "X-Bapi-Limit-Reset-Timestamp": "1740453408555",
        "Traceid": "0e32b551b3e17aae77651aadf6a5be80"
    },
    "connId": "cupviqn88smf24t2kpb0-536o"
}

Ping

Request Parameters

Parameter	Required	Type	Comments
op	true	string	Op type. `ping`

Response Parameters

Parameter	Type	Comments
retCode	integer	Result code
retMsg	string	Result message
op	string	Op type `pong`
data	array	One item in the array, current timestamp (string)
connId	string	Connection id, the unique id for the connection

Request Example

{
    "op": "ping"
}

Response Example

{
    "retCode": 0,
    "retMsg": "OK",
    "op": "pong",
    "data": [
        "1711002002529"
    ],
    "connId": "cnt5leec0hvan15eukcg-2v"
}

URL​

Scope​

Authentication​

Request Parameters​

Response Parameters​

Request Example​

Response Example​

Create/Amend/Cancel Order​

Request Parameters​

Response Parameters​

Request Example​

Response Example​

Batch Create/Amend/Cancel Order​

Request Parameters​

Response Parameters​

Request Example​

Response Example​

Ping​

Request Parameters​

Response Parameters​

Request Example​

Response Example​

URL

Scope

Authentication

Request Parameters

Response Parameters

Request Example

Response Example

Create/Amend/Cancel Order

Request Parameters

Response Parameters

Request Example

Response Example

Batch Create/Amend/Cancel Order

Request Parameters

Response Parameters

Request Example

Response Example

Ping

Request Parameters

Response Parameters

Request Example

Response Example