WEEX API Integration Guide: Auth, Limits, and the 403 Trap

Most guides to a crypto exchange API stop at "create a key and point your bot at it." That gets you to your first -1052, not to a working integration. The WEEX API is a two-stack system — spot and futures live on different domains with different order schemas — and the failures that cost developers the most time are not conceptual. They are a missing User-Agent header, a clock that drifted 31 seconds, and a trading pair that exists on the exchange but is not enabled for programmatic access.

This guide walks the WEEX API integration end to end: what the API covers, how to provision a key that won't lock you out, how the signature is actually constructed, the rate limits you will hit in production, and the specific errors that break most first attempts. Every figure here comes from the WEEX V3 documentation as of August 2026.

What the WEEX API Covers — and What It Still Doesn't

The WEEX API exposes two independent REST surfaces plus a WebSocket layer. They are not interchangeable, and this is the first structural decision an integration has to get right.

Coverage is real but bounded. The WEEX OpenAPI beta announcement lists 140+ supported pairs — but the split is lopsided: the futures table runs to roughly 130 perpetual contracts, while the spot list is around 25 pairs. If your strategy trades a mid-cap spot pair, check that list before you write a line of code, because a pair being live on the web interface does not mean it accepts API orders.

Two absences matter for anyone migrating from another venue. WEEX's spot API FAQ, last updated 14 April 2026, states plainly that neither FIX API nor TradingView integration is currently supported. If your execution stack assumes a FIX session or webhook alerts routed from TradingView, you are rebuilding that layer against REST and WebSocket.

Also worth noting: V1 and V2 endpoints are being deprecated, and WEEX recommends V3 for new builds. Sample code you find on third-party bot platforms may still target V2 paths.

How to Create a WEEX API Key Without Locking Yourself Out

Key creation happens on the WEEX API Management page under Account. The mechanics take two minutes. The configuration decisions take longer, and three of them are irreversible.

1. Create the key. Each account supports up to 10 API key groups. New keys default to Read Only.
2. Select permissions explicitly. Readonly, Spot, and Futures/Contract are independent. Checking Spot does not grant futures access, and a futures order sent on a spot-only key returns -1052 INSUFFICIENT_PERMISSIONS rather than anything more descriptive.
3. Set the passphrase carefully. WEEX's own security guidance says to use alphanumeric characters only — special characters in the passphrase are a documented source of auth failures. The passphrase cannot be modified or recovered. Lose it and you create a new key.
4. Bind an IP allowlist. Up to 10 IPs, comma-separated. Unrestricted keys are the single largest custody risk in an API setup, and WEEX flags them as such.
5. Wait. Newly created or modified keys take roughly 15 minutes to propagate across WEEX's systems. Developers routinely interpret this window as a broken signature and start rewriting working code.

Store the APIKey, SecretKey, and Passphrase at creation. Only the APIKey is retrievable afterwards.

One habit worth adopting from day one: never enable withdrawal-adjacent permissions on a key that lives in a trading process. Separate read-only keys for monitoring from trade-permissioned keys for execution, and give each its own IP binding. The operational cost is ten minutes; the failure mode it prevents is total.

Signing a WEEX API Request: The 30-Second Window

Every private WEEX API call carries four headers plus a content type:

The message you sign is a concatenation, and the concatenation rule changes depending on whether a query string exists:

# queryString present
timestamp + METHOD + requestPath + "?" + queryString + body

# queryString absent
timestamp + METHOD + requestPath + body

METHOD is uppercase. body is the raw JSON string, byte-for-byte identical to what you transmit — serialize once, sign that string, send that string. Re-serializing between signing and sending is the most common self-inflicted signature failure, because key ordering or whitespace shifts and the hash no longer matches.

A worked example from the WEEX signature spec, fetching depth:

1591089508404GET/api/v3/market/depth?symbol=BTCUSDT&limit=20

And an order:

1561022985382POST/api/v3/order{"symbol":"BTCUSDT","side":"BUY","type":"LIMIT","timeInForce":"GTC","quantity":"1","price":"68900","newClientOrderId":"my-order-001"}

Then HMAC-SHA256 with your secret key, then Base64.

The constraint that catches people in production is the clock. Requests are rejected if ACCESS-TIMESTAMP deviates more than 30 seconds from WEEX server time, returning -1046 ACCESS_TIMESTAMP_EXPIRED. Containers with drifting clocks, serverless cold starts, and VMs without NTP all fail this intermittently — which is worse than failing consistently, because it looks like a network problem. Query the server time endpoint at startup, store the offset, and apply it to every timestamp.

WebSocket private channels use a shorter message: timestamp + "/v3/ws/private", signed the same way — same headers, same HMAC-SHA256 and Base64 steps, just a different string.

WEEX API Rate Limits You'll Actually Hit

Exceeding a limit returns HTTP 429 and a 10-second ban. WEEX splits limiting into two independent budgets, which is the part most integrations model incorrectly.

Rate limits sourced from WEEX spot API documentation and FAQ, current as of 14 April 2026.

The distinction that matters: order placement is limited by account, everything else by IP. Placement endpoints consume zero IP weight — the IP counter in their response headers reads 0. So running three strategies behind one IP does not triple your order budget (it's per-account), but it does triple your consumption of the 500-weight IP pool for market data and queries.

Read the headers rather than guessing. Every response carries X-USED-WEIGHT-1M and X-REMAINING-WEIGHT-1M; order endpoints carry X-ORDER-COUNT-10S and X-ORDER-REMAINING-10S. A back-off driven by the remaining-weight header will outperform any fixed sleep interval you hard-code.

Spot and Futures Orders Don't Share a Schema

This is the divergence that breaks shared abstraction layers, and it is not called out prominently anywhere in the docs — you find it by diffing the two order pages.

That last row deserves emphasis. The futures endpoint can return HTTP 200 with {"success": false, "errorCode": "...", "errorMessage": "..."}. Code that checks only the HTTP status will register a rejected order as filled and happily proceed to build a position it doesn't have. Check success explicitly on every futures order response.

There is also a live inconsistency in the documentation itself. The spot API Public Parameters page still lists lowercase enums (buy, sell, limit, market) alongside a force field, while the V3 order endpoints under Trade use uppercase BUY, SELL, LIMIT and timeInForce. The endpoint pages reflect V3; the parameters page carries V2-era values. When they disagree, trust the endpoint page — and send -1116 INVALID_ORDER_TYPE to your logs as a signal you copied from the wrong one.

Symbols are case-sensitive and must be uppercase. btcusdt returns -1121.

Five Errors That Break Most WEEX API Integrations

The WebSocket 403 is the one worth internalizing. It has nothing to do with your credentials — WEEX's edge rejects header-less handshakes outright, so a perfectly signed private subscription fails identically to an unsigned one. Developers debug their signature for an hour before finding it. WEEX documents this in the spot API FAQ, and the fix is one line.

Keep connections alive properly too. The server sends periodic pings — {"event":"ping","time":"..."} on public channels, {"type":"ping","time":"..."} on private — and expects {"method":"PONG","id":1} back. Miss more than 10 and the server closes the connection. A silent disconnect during a volatile session is how a bot ends up trading on a stale book.

Full error taxonomy lives in the WEEX spot API FAQ and error code reference.

Test in Demo Mode Before You Risk Real Margin

WEEX ships a simulated futures environment reachable through the same authenticated pattern, under /capi/v3/sim/. The demo balance endpoint returns positions denominated in SUSDT — simulated USDT — alongside availableBalance, frozen, and unrealizePnl. Demo PlaceOrder, GetAllPositions, and GetOrderHistory are all exposed.

Use it for what it's actually good at: validating your signature construction, your error handling, and your reconnect logic. Do not use it to validate strategy economics. A simulated venue has no queue position, no partial-fill behaviour under stress, and no slippage — the three things that separate a backtest from a P&L.

For calibration on the live side: WEEX quoted BTC perpetuals at 65,088.80 USDT on its BTC/USDT futures market as of 21 August 2026, with leverage available up to 400×. That leverage ceiling is a reason to be conservative with an automated system, not a feature to lean on. A signing bug that fires duplicate orders is survivable at 3×. It is not at 400×.

The Short Version

The WEEX API is straightforward once three things are true: your clock is synced inside the 30-second window, your WebSocket sends a User-Agent, and your futures code checks the success field rather than the HTTP status. Everything else — permissions, IP allowlists, rate-limit back-off — is standard exchange integration work.

The one thing that is not standard, and the one worth budgeting time for, is the spot/futures schema divergence. A shared order abstraction across both surfaces will look correct in review and fail in production. Build them as two adapters.

Ready to start? Create a key under Account → API Management on WEEX, point it at demo mode first, and only widen permissions once your reconnect and error paths are proven.

FAQ

1. Is the WEEX API free to use?

Yes. There is no separate charge for API access. You pay standard spot or futures trading fees on executed orders, the same as manual trading.

2. How many API keys can I create on WEEX?

Up to 10 API key groups per account. Each key can be configured independently with Readonly, Spot, or Futures/Contract permissions and its own IP allowlist of up to 10 addresses.

3. Why does my WEEX API key work in Postman but not from my server?

Almost always the IP allowlist (-1056) or clock drift (-1046). Cloud environments frequently egress from a rotating NAT IP that isn't on your allowlist, and containers without NTP drift past the 30-second signature window.

4. Does the WEEX API support FIX or TradingView webhooks?

No. As of the April 2026 documentation update, neither FIX API nor TradingView integration is supported. REST and WebSocket are the available transports.

5. How long before a new WEEX API key starts working?

Roughly 15 minutes for a new or modified key to propagate. Authentication failures inside that window are expected and are not a signature problem.

6. Can I test WEEX API strategies without real funds?

Yes, for futures. The demo endpoints under /capi/v3/sim/ accept the same authenticated requests and return SUSDT-denominated balances. Treat them as an integration test harness, not a strategy backtest.

Risk Warning

Crypto assets are volatile, and trading them may result in partial or total loss of capital. API trading concentrates that risk rather than reducing it: a logic error, an unhandled rejection, or a stale WebSocket feed can execute dozens of unintended orders before a human notices. WEEX offers leverage up to 400× on some perpetual contracts, which magnifies both correct and incorrect signals — an automated system running at high leverage can be liquidated in a single adverse move.

Specific risks to account for in an API deployment: custody risk from unrestricted or leaked keys, which grant full trading control of the account; operational risk from clock drift, rate-limit bans and dropped connections that leave positions unmanaged; liquidity risk on thinly traded pairs where a market order moves the book against you; and counterparty and regulatory risk, since availability of API trading and specific pairs can change without notice. Bind an IP allowlist, keep withdrawal permissions off trading keys, cap position size in code rather than in intent, and test error paths in demo mode before deploying capital. Nothing here is investment advice.