Getting Started
Set up authentication, synchronize your clock, and make your first Binance C2C API request in under 5 minutes.
1. Prerequisites
Create a Binance API Key with these permissions:
- Read — required for all endpoints
- Trade P2P — required for ad management and orders
- No withdrawals — never enable withdrawal permissions
Restrict your API key to your server's IP address for additional security.
2. Time Synchronization
All signed requests include a timestamp parameter. If your server clock drifts more than recvWindow (default 60,000ms) from Binance's server, requests fail with error -1021.
3. HMAC-SHA256 Signing
Signing Process
- Collect query string params:
timestamp=X&recvWindow=Y - Sort alphabetically by key name
- Concatenate into a single query string
- Compute
HMAC-SHA256(secret_key, query_string) - Append
&signature=RESULTto the URL - Set header:
X-MBX-APIKEY: api_key - Set header:
clientType: web - Send request — JSON body is NOT included in the signature
2026 Breaking Change: Percent-Encoding
Starting in 2026, Binance requires percent-encoding of special characters in query string values before HMAC computation. Values containing =,&, or spaces must be URL-encoded before signing. Previously, raw values were accepted.
import hmac, hashlib, time
from urllib.parse import urlencode
def sign_request(api_secret: str, params: dict) -> str:
"""Generate HMAC-SHA256 signature for Binance SAPI."""
params["timestamp"] = int(time.time() * 1000)
params["recvWindow"] = 60000
# Sort alphabetically and encode
query_string = urlencode(sorted(params.items()))
signature = hmac.new(
api_secret.encode(), query_string.encode(), hashlib.sha256
).hexdigest()
return f"{query_string}&signature={signature}"4. Signature Scope Gotcha
Important: The HMAC signature covers only the query string parameters. The JSON request body is NOT included in the signature computation. This is consistent across all SAPI endpoints but poorly documented.
5. Common Headers
| Header | Value | Required |
|---|---|---|
| X-MBX-APIKEY | Your API key | Yes (signed) |
| clientType | web | Yes (all SAPI) |
| Content-Type | application/json | For POST with body |
6. First Request (No Auth)
Start with an unauthenticated endpoint to verify connectivity:
7. First Signed Request
Now try a signed request to verify your HMAC implementation:
Next Steps
- → Market Data — Search the P2P order book (public, no auth)
- → Ads Reference — Manage your P2P advertisements
- → Error Codes — Handle every error code correctly