Skip to main content

Websocket Trade Guideline

URL

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

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

Support

Unified Trading Account

category=linear, spot, option

Authentication

Request Parameters

ParameterRequiredTypeComments
reqIdfalsestringOptional field, used to match the response
  • If not passed, this field will not be returned in response
  • optruestringOp type. auth
    argsfalsestring["api key", expiry timestamp, "signature"]. Please click here to generate signature

    Response Parameters

    ParameterTypeComments
    reqIdstring
  • 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
  • retCodeinteger
  • 0: auth success
  • 20001: repeat auth
  • 10004: invalid sign
  • 10001: param error
  • retMsgstring
  • OK
  • Error message
  • opstringOp type
    connIdstringConnection 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

    ParameterRequiredTypeComments
    reqIdfalsestringUsed 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"
  • headertrueobjectRequest headers
    > X-BAPI-TIMESTAMPtruestringCurrent timestamp
    > X-BAPI-RECV-WINDOWfalsestring5000(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
    > RefererfalsestringThe referer identifier for API broker user
    optruestringOp type
  • order.create: create an order
  • order.amend: amend an order
  • order.cancel: cancel an order
  • argsfalsearray<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

    ParameterTypeComments
    reqIdstring
  • 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
  • retCodeinteger
  • 0: success
  • 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
  • retMsgstring
  • OK
  • ""
  • Error message
  • opstringOp type
    dataobjectBusiness 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
  • headerobjectHeader info
    > TraceIdstringTrace ID, used to track the trip of request
    > TimenowstringCurrent timestamp
    > X-Bapi-LimitstringThe total rate limit of the current account for this op type
    > X-Bapi-Limit-StatusstringThe remaining rate limit of the current account for this op type
    > X-Bapi-Limit-Reset-TimestampstringThe 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)
    connIdstringConnection id, the unique id for the connection

    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": ""
    },
    "header": {
    "X-Bapi-Limit": "10",
    "X-Bapi-Limit-Status": "9",
    "X-Bapi-Limit-Reset-Timestamp": "1711001595208",
    "Traceid": "38b7977b430f9bd228f4b19724794dfd",
    "Timenow": "1711001595209"
    },
    "connId": "cnt5leec0hvan15eukcg-2v"
    }

    Ping

    Request Parameters

    ParameterRequiredTypeComments
    optruestringOp type. ping

    Response Parameters

    ParameterTypeComments
    retCodeintegerResult code
    retMsgstringResult message
    opstringOp type pong
    dataarrayOne item in the array, current timestamp (string)
    connIdstringConnection id, the unique id for the connection

    Request Example

    {
    "op": "ping"
    }

    Response Example

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