Public WebSocket API for Binance (2024-10-17)

General API Information

• The base endpoint is: wss://ws-api.binance.com:443/ws-api/v3
  • If you experience issues with the standard 443 port, alternative port 9443 is also available.
  • The base endpoint for testnet is: wss://testnet.binance.vision/ws-api/v3
• A single connection to the API is only valid for 24 hours; expect to be disconnected after the 24-hour mark.
• Websocket server will send a ping frame every 3 minutes.
  • If the websocket server does not receive a pong frame back from the connection within a 10 minute period, the connection will be disconnected.
  • When you receive a ping, you must send a pong with a copy of ping's payload as soon as possible.
  • Unsolicited pong frames are allowed, but will not prevent disconnection. It is recommended that the payload for these pong frames are empty.
• Lists are returned in chronological order, unless noted otherwise.
• All timestamps are in milliseconds in UTC, unless noted otherwise.
• All field names and values are case-sensitive, unless noted otherwise.

Request format

Requests must be sent as JSON in text frames, one request per frame.

Example of request:

{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "method": "order.place",
  "params": {
    "symbol": "BTCUSDT",
    "side": "BUY",
    "type": "LIMIT",
    "price": "0.1",
    "quantity": "10",
    "timeInForce": "GTC",
    "timestamp": 1655716096498,
    "apiKey": "T59MTDLWlpRW16JVeZ2Nju5A5C98WkMm8CSzWC4oqynUlTm1zXOxyauT8LmwXEv9",
    "signature": "5942ad337e6779f2f4c62cd1c26dba71c91514400a24990a3e7f5edec9323f90"
  }
}

Request fields:

Name	Type	Mandatory	Description
id	INT / STRING / null	YES	Arbitrary ID used to match responses to requests
method	STRING	YES	Request method name
params	OBJECT	NO	Request parameters. May be omitted if there are no parameters

• Request id is truly arbitrary. You can use UUIDs, sequential IDs, current timestamp, etc. The server does not interpret id in any way, simply echoing it back in the response.

  You can freely reuse IDs within a session. However, be careful to not send more than one request at a time with the same ID, since otherwise it might be impossible to tell the responses apart.

• Request method names may be prefixed with explicit version: e.g., "v3/order.place".

• The order of params is not significant.

Response format

Responses are returned as JSON in text frames, one response per frame.

Example of successful response:

{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 200,
  "result": {
    "symbol": "BTCUSDT",
    "orderId": 12510053279,
    "orderListId": -1,
    "clientOrderId": "a097fe6304b20a7e4fc436",
    "transactTime": 1655716096505,
    "price": "0.10000000",
    "origQty": "10.00000000",
    "executedQty": "0.00000000",
    "cummulativeQuoteQty": "0.00000000",
    "status": "NEW",
    "timeInForce": "GTC",
    "type": "LIMIT",
    "side": "BUY",
    "workingTime": 1655716096505,
    "selfTradePreventionMode": "NONE"
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 12
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4043
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 321
    }
  ]
}

Example of failed response:

{
  "id": "e2a85d9f-07a5-4f94-8d5f-789dc3deb097",
  "status": 400,
  "error": {
    "code": -2010,
    "msg": "Account has insufficient balance for requested action."
  },
  "rateLimits": [
    {
      "rateLimitType": "ORDERS",
      "interval": "SECOND",
      "intervalNum": 10,
      "limit": 50,
      "count": 13
    },
    {
      "rateLimitType": "ORDERS",
      "interval": "DAY",
      "intervalNum": 1,
      "limit": 160000,
      "count": 4044
    },
    {
      "rateLimitType": "REQUEST_WEIGHT",
      "interval": "MINUTE",
      "intervalNum": 1,
      "limit": 6000,
      "count": 322
    }
  ]
}

Response fields:

Name	Type	Mandatory	Description
id	INT / STRING / null	YES	Same as in the original request
status	INT	YES	Response status. See Status codes
result	OBJECT / ARRAY	YES	Response content. Present if request succeeded
error	OBJECT		Error description. Present if request failed
rateLimits	ARRAY	NO	Rate limiting status. See Rate limits

Status codes

Status codes in the status field are the same as in HTTP.

Here are some common status codes that you might encounter:

• 200 indicates a successful response.
• 4XX status codes indicate invalid requests; the issue is on your side.
  • 400 – your request failed, see error for the reason.
  • 403 – you have been blocked by the Web Application Firewall.
  • 409 – your request partially failed but also partially succeeded, see error for details.
  • 418 – you have been auto-banned for repeated violation of rate limits.
  • 429 – you have exceeded API request rate limit, please slow down.
• 5XX status codes indicate internal errors; the issue is on Binance's side.
  • Important: If a response contains 5xx status code, it does not necessarily mean that your request has failed. Execution status is unknown and the request might have actually succeeded. Please use query methods to confirm the status. You might also want to establish a new WebSocket connection for that.

See Error codes for Binance for a list of error codes and messages.