Introduction

Authentication

Copy page

All Binance Web3 API endpoints are protected by API Key authentication. Each request must be signed using your Secret Key, ensuring that only authorized clients with valid credentials can access the platform.

---

Step 1 — Obtain API Credentials

Visit the Developer Portal to create a project and generate an API Key and Secret Key:

Credential	Description
API Key	Uniquely identifies your application (X-OC-APIKEY header)
Secret Key	Used to sign requests (HMAC-SHA256 mode). Keep this private.

---

Step 2 — Understand Required Headers

Every authenticated request must include the following three headers:

Header	Required	Description
X-OC-APIKEY	Yes	Your API Key string
X-OC-TIMESTAMP	Yes	Current UTC time in ISO 8601 format with milliseconds, e.g. 2026-05-11T10:08:57.715Z
X-OC-SIGN	Yes	Request signature (Base64-encoded), see Step 3
X-OC-RECV-WINDOW	No	Allowed time deviation in milliseconds (default: 5000, max: 60000)
X-OC-NONCE	No	Unique request identifier for anti-replay; falls back to X-OC-SIGN if omitted

---

Step 3 — Generate the Signature

3.1 Build the Pre-Hash String

Concatenate the following four components without any separator:

Code
preHash = timestamp + method + requestPath + body

Component	Rule
timestamp	Exact value of the X-OC-TIMESTAMP header (ISO 8601, e.g. 2026-05-11T10:08:57.715Z)
method	HTTP method in UPPERCASE (e.g. GET, POST)
requestPath	Full HTTP path (including any base-path prefix) plus query string in raw URL-encoded form, e.g. /build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT
body	Raw request body string for POST/PUT/DELETE; empty string "" for GET/HEAD

Example (GET request)

Code
timestamp   = "2026-05-11T10:08:57.715Z"
method      = "GET"
requestPath = "/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT"
body        = ""

preHash = "2026-05-11T10:08:57.715ZGET/build/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT"

Example (POST request)

Code
timestamp   = "2026-05-11T10:08:57.715Z"
method      = "POST"
requestPath = "/build/api/v1/dex/swap"
body        = '{"chainId":1,"fromToken":"0xEEEE...","toToken":"0xA0b8...","amount":"1000000000000000000"}'

preHash = "2026-05-11T10:08:57.715ZPOST/build/api/v1/dex/swap{\"chainId\":1,...}"

---

3.2 Sign with HMAC-SHA256 (Default)

Compute HMAC-SHA256 over preHash using your Secret Key, then Base64-encode the result:

Code
signature = Base64( HMAC-SHA256(preHash, secretKey) )

All strings are UTF-8 encoded before hashing.

JavaScript / Node.js

Code
const crypto = require("crypto");

const timestamp = new Date().toISOString(); // e.g. "2026-05-11T10:08:57.715Z"
const method = "GET";
const pathWithQuery = "/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT";
const body = ""; // empty for GET

const preHash = timestamp + method + pathWithQuery + body;
const signature = crypto
  .createHmac("sha256", secretKey)
  .update(preHash, "utf8")
  .digest("base64");

Python

Code
import hmac, hashlib, base64
from datetime import datetime, timezone

now        = datetime.now(timezone.utc)
timestamp  = now.strftime("%Y-%m-%dT%H:%M:%S.") + f"{now.microsecond // 1000:03d}Z"
method     = "GET"
path_query = "/api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT"
body       = ""

pre_hash   = timestamp + method + path_query + body
signature  = base64.b64encode(
    hmac.new(secret_key.encode("utf-8"), pre_hash.encode("utf-8"), hashlib.sha256).digest()
).decode("utf-8")

Java

Code
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

String preHash    = timestamp + method + pathWithQuery + body;
Mac mac           = Mac.getInstance("HmacSHA256");
mac.init(new SecretKeySpec(secretKey.getBytes("UTF-8"), "HmacSHA256"));
String signature  = Base64.getEncoder().encodeToString(
    mac.doFinal(preHash.getBytes("UTF-8"))
);

---

Step 4 — Send the Request

Attach the three required headers to every authenticated request:

Code
GET /api/v1/dex/market/price?chainId=1&symbol=ETH%20USDT HTTP/1.1
Host: web3.binance.com/build
X-OC-APIKEY:    your-api-key-here
X-OC-TIMESTAMP: 2026-05-11T10:08:57.715Z
X-OC-SIGN:      k3Y2mNpQr...base64sig...==

Complete JavaScript Example

Code
const crypto = require("crypto");
const axios = require("axios");

const API_KEY = process.env.OC_API_KEY;
const SECRET_KEY = process.env.OC_SECRET_KEY;
const BASE_URL = "https://web3.binance.com";

async function get(path, params = {}) {
  // Use encodeURIComponent so spaces become %20 (not +), matching the raw wire encoding
  const queryStr = Object.entries(params)
    .map(([k, v]) => `${encodeURIComponent(k)}=${encodeURIComponent(v)}`)
    .join("&");
  const fullPath = queryStr ? `${path}?${queryStr}` : path;

  const timestamp = new Date().toISOString();
  // requestPath is the full path as sent on the wire (already includes /build prefix)
  const requestPath = fullPath;
  const body = ""; // empty string for GET requests

  const preHash = timestamp + "GET" + requestPath + body;
  const signature = crypto
    .createHmac("sha256", SECRET_KEY)
    .update(preHash, "utf8")
    .digest("base64");

  const resp = await axios.get(BASE_URL + fullPath, {
    headers: {
      "X-OC-APIKEY": API_KEY,
      "X-OC-TIMESTAMP": timestamp,
      "X-OC-SIGN": signature,
    },
  });
  return resp.data;
}

// Usage
get("/build/api/v1/dex/aggregator/supported/chain", {
  binanceChainId: "56",
}).then(console.log);

---

Timestamp & Anti-Replay

The gateway validates X-OC-TIMESTAMP on every authenticated request:

1. Format: Must be a valid ISO 8601 string (e.g. 2026-05-11T10:08:57.715Z).
2. Time window: The request timestamp must be within recv_window milliseconds of server time. Default is 5 000 ms (5 s), configurable via X-OC-RECV-WINDOW (max 60 000 ms / 60 s).
3. Anti-replay: Each nonce (X-OC-NONCE or the signature itself) is valid only once within the 2 × recv_window time window. Replayed requests are rejected with error 40103.

---

Rate Limits

Authenticated requests are subject to four concurrent rate-limit dimensions:

Dimension	Default Limit	Window	Response Header
Per IP	1 200 requests	60 s	X-OC-RateLimit-Limit
Per API Key	1 200 requests	60 s	X-OC-RateLimit-Remaining
Per User	6 000 requests	60 s	X-OC-Used-Weight
Per Endpoint	5 RPS (default)	1 s	X-OC-Used-Weight

When a limit is exceeded the gateway returns HTTP 429 with a Retry-After header (in seconds).

---

Error Codes

HTTP Status	Error Code	Meaning
400	40001	Invalid request parameters
401	40101	API Key is missing, invalid, or disabled
401	40102	Signature mismatch or missing
401	40103	Timestamp expired or request replayed
403	40104	API Key lacks required permission
429	42900	Rate limit exceeded
500	50000	Internal server error
503	50001	Service temporarily unavailable

All error responses follow the unified format:

Code
{
  "code": 40102,
  "msg": "Invalid signature",
  "data": null,
  "timestamp": 1715420937000
}

---

Postman Quick Start

Add the following Pre-request Script to your Postman collection to auto-sign every request:

Code
// Binance Web3 API Gateway — Auto Sign Script
const apiKey = pm.variables.get("api_key");
const secretKey = pm.variables.get("secret_key");
if (!apiKey || !secretKey) {
  throw new Error("Set api_key and secret_key in Collection Variables first");
}

const timestamp = new Date().toISOString();
const method = pm.request.method.toUpperCase();
const url = pm.request.url;

const pathStr = "/" + (url.path || []).join("/");
const qParams = (url.query || []).filter((p) => !p.disabled && p.key);
const queryStr = qParams
  .map(
    (p) => encodeURIComponent(p.key) + "=" + encodeURIComponent(p.value || ""),
  )
  .join("&");
const pathWithQuery = queryStr ? pathStr + "?" + queryStr : pathStr;

const body =
  method === "GET" || method === "HEAD"
    ? ""
    : pm.request.body
      ? pm.request.body.toString()
      : "";

const preHash = timestamp + method + pathWithQuery + body;
const signature = CryptoJS.enc.Base64.stringify(
  CryptoJS.HmacSHA256(preHash, secretKey),
);

pm.request.headers.upsert({ key: "X-OC-APIKEY", value: apiKey });
pm.request.headers.upsert({ key: "X-OC-TIMESTAMP", value: timestamp });
pm.request.headers.upsert({ key: "X-OC-SIGN", value: signature });

Set api_key and secret_key under Collection → Variables and every request will be signed automatically.