Best Practices

Time sync

Run an NTP daemon (chrony, systemd-timesyncd). Your clock must stay within ±5 seconds of the server clock — otherwise every signed call returns 401 Invalid or expired timestamp.

Connection pool

Reuse sockets — HTTP/1.1 keep-alive or HTTP/2. A new TLS handshake on every request adds ~30 ms of latency for nothing.

Back-off strategy

• 429 → wait Retry-After, then exponential back-off (1 s, 2 s, 4 s, 8 s).
• 5xx → exponential back-off + jitter.
• 4xx (validation / permission) → do not retry, surface the error.

Always set clientOrderId

It is the only practical defence against duplicate orders caused by network glitches and retry storms. Generate it once per intent, not per attempt.

Order monitoring without a private WebSocket

Until API-key WebSocket auth ships, poll REST:

1. Place the order → keep order.id and order.venueOrderId.
2. GET /v2/orders/:id every 1 – 3 s; watch status.
3. Or stream fills via GET /v2/futures/myTrades?symbol=X&fromId=<last>.
4. Position deltas → GET /v2/positions every 3 – 5 s.

Risk management

• The backend RMS limits per-order notional via RISK_MAX_ORDER_NOTIONAL_USDT (default $10M; admin-overridable per user). Hitting the cap returns 400 with reason: "max_order_notional_exceeded".
• Layer your own max-position-size, max-loss, and max-drawdown controls on top — never rely on the venue alone.

IP whitelist

For production, always set it. The client host needs a static IP — running behind dynamic-NAT addresses defeats the protection.

Key rotation

• Rotate keys every 90 days.
• Verify the new key works before revoking the old one.
• On any suspicion of compromise, revoke immediately (DELETE /v2/api-keys/:id from the UI).

HTTPS is mandatory

Bodies are not part of the HMAC signature — only the query string is. Without TLS, a man-in-the-middle could rewrite the body. Always use https:// in production.

Logging

• Log every request as (timestamp, path, status, errorId).
• Persist errorId for support cases.
• Never log the API key or the signature.