Binance Web3 API Specification V0.0.7 (2024-12-18)

Web3 API description

• Binance's Partners need to follow the API specification in this doc to provide Binance with a set of endpoints in order to integrate with Binance.

General API Information

• All endpoints return a common JSON object with "code", "message" and "data", no matter if it's a success or not.
• Here "data" is either a customized JSON object or a simple type (int, string...). It may vary from endpoint to endpoint.

  {
      "code": "XXXXXX",
      "message": "success",
      "data": {
         "abc": "efg",
         ...
     }
  }
• General codes in responses:

  code	Description
  000000	success
  000001	too many requests
  000002	system busy
  000003	invalid signature
  000004	invalid recvWindow
  000005	invalid timestamp. timestamp for this request is outside of the recvWindow. Or timestamp for this request was 1000ms ahead of the server's time.
  000006	invalid argument

• All time and timestamp related fields are in milliseconds.
• HTTP 5XX return codes are used for internal errors. The issue is on the partner's side. Binance will NOT treat this as a failure operation; the execution status is UNKNOWN.
• For GET endpoints, parameters must be sent as a query string.
• For POST, PUT , and DELETE endpoints, the parameters must be sent in the request body with content type application/x-www-form-urlencoded.
• Parameters may be sent in any order.
• Requests out of the receiving window must NOT be executed. Partner's server should verify:
  1. recvWindow <= 10000 (ms)
  2. partner's server time - 3000 < timestamp < partner's server time + recvWindow.
• Every partner needs to define a url prefix so that Binance can invoke the partner's endpoint using prefix + endpoint_url.
• Each request and response should be logged in both Binance and partner's sides for further investigation.

API Specification​

Server Time

GET /v1/time
to check the partner's server time

Parameters: None

Response Body:

Name	Type	Mandatory	Description
code	String	YES	"000000"
message	String	YES	"success"
data	Long	YES	timestamp

Response examples:

{
 "code": "000000",
 "message": "success",
 "data": 1499827319559
}

{
 "code": "000002",
 "message": "system busy",
 "data": null
}

Task Completion

GET /v1/task/completion

Parameters:

Name	Type	Mandatory	Description
walletAddress	String	YES	a user's unified id
task	String json array	YES	task names. "deposit", "withdraw". if it's not empty, just return specific task completion status. Otherwise, return all tasks completion statuses.
recvWindow	Long	YES	received window
timestamp	Long	YES	client timestamp of the request

Headers:

Name	Type	Mandatory	Description
code	String	YES	signature of the request

Response Body:

Name	Type	Mandatory	Description
code	String	YES
message	String	YES
data	JSON Object	YES	timestamp

data:

Name	Type	Mandatory	Description
walletAddress	String	YES	a user's unified id
task	String json array	YES	task names. "deposit", "withdrawal"
recvWindow	Long	YES	received window
timestamp	Long	YES	client timestamp of the request

Examples:

GET {prefix} + /v1/task/completion?walletAddress=0xabcdefg&task=["deposit", "withdrawal"]&recvWindow=3000&timestamp=1499827319559

Response:
{
 "code": "000000",
 "message": "success",
 "data": {
     "withdrawal": true, // complete
     "deposit": false, // incomplete
 }
}

{
 "code": "000003",
 "message": "invalid signature",
 "data": null
}
{
 "code": "000006",
 "message": "invalid argument",
 "data": null
}

Provide feedback on this document: https://forms.gle/zpBnQWCqoFMmby698