API Frequently Asked Questions

·

Navigating the world of trading APIs can be challenging, especially when dealing with technical configurations and error handling. This comprehensive guide addresses common questions and issues users encounter when working with trading APIs—particularly those related to account setup, order execution, and troubleshooting. Whether you're a beginner or an experienced developer, this resource will help clarify key concepts and improve your API integration experience.

Understanding Passphrase and APIKey Security

When creating an APIKey, you'll be prompted to set a passphrase. This is a user-defined password used to authenticate your API access. Unlike other credentials, the passphrase is not recoverable—if forgotten, the only option is to generate a new APIKey. Therefore, it's crucial to store your passphrase securely using a trusted password manager or encrypted storage solution.

👉 Discover how secure API access can enhance your trading strategy

Creating a Demo Account APIKey

To test your strategies without risking real funds, use a demo (paper) trading account. You can create a dedicated APIKey for demo trading by following these steps:

  1. Log in to your account
  2. Navigate to Trade > Demo Trading > Personal Center
  3. Select Create Demo APIKey
  4. Begin simulated trading immediately

This allows developers and traders to validate their bots and algorithms in a risk-free environment before going live.

Does an APIKey Expire?

APIKey expiration depends on usage and configuration:

To maintain long-term access, ensure regular interaction with authenticated endpoints such as balance checks, order placement, or transaction history retrieval.

Contract Order Units: Can You Trade in USDT or Coins?

No. Contract trading via API operates exclusively in contract units ("lots" or "sheets"), not in USDT or individual coins. To convert between coin amounts and contract units, use the Unit Conversion API:

This enables accurate position sizing based on your desired exposure.

How to Calculate Price Change Percentage

While there's no direct endpoint for 24-hour price change percentage, you can compute it using ticker data:

Price Change % = ((Last Price - Open24h) / Open24h) × 100

Use the Get Ticker endpoint (GET /api/v5/market/ticker) to retrieve:

This method ensures precise calculation aligned with platform metrics.

Frequently Asked Questions

Q: What does "posSide" mean in contract orders?
A: The posSide parameter defines the position direction—long or short. It’s required in single-position mode for contracts. For example:

In net mode, only posSide=net is allowed.

Q: Why am I getting error 51000 "Parameter posSide error"?
A: This occurs when posSide is missing or invalid. Check your account’s position mode:

👉 Learn how advanced order types can optimize your trades

Q: How do I find contract value and minimum order size?
A: Use the Get Instruments endpoint (GET /api/v5/public/instruments). Key fields include:

This data is essential for compliance with lot size rules.

Instrument ID (instId) Format Guide

Each trading pair has a standardized instId format:

Ensure correct formatting to avoid invalid instrument errors.

Setting Up Take-Profit and Stop-Loss Orders

You can configure take-profit (TP) and stop-loss (SL) in two ways:

  1. With Regular Orders: Use the attachAlgoOrds array in the place-order request.

    "attachAlgoOrds": [{
  "tpTriggerPx": "50000",
  "tpOrdPx": "-1"
}]
  2. As Standalone Algo Orders: Use the Place Algo Order endpoint with order type trigger.

Both methods support conditional execution based on market price.

Common TP/SL Errors (51046–51049)

These codes indicate incorrect trigger pricing logic:

Violating these rules results in rejection. Always validate prices against current market data before submission.

Handling Timestamp Errors (50102)

Error 50102 indicates a timestamp mismatch between your system and the server. To resolve:

  1. Call the Get System Time endpoint (GET /api/v5/public/time)
  2. Sync your local clock to stay within ±30 seconds of server time
  3. Note: Request headers use UTC+0, while the time endpoint returns UTC+8

Maintaining accurate time prevents authentication failures due to expired requests.

Environment Mismatch Error (50101)

Error 50101 occurs when the APIKey environment doesn't match the request context:

Double-check both credentials and headers to ensure consistency.

Account Mode Restrictions (51010)

Certain trading types require specific account modes:

Initial changes must be made via UI; subsequent updates can use API.

Lot Size Validation Error (51121)

This error means your order quantity isn’t a multiple of the product’s lot size (lotSz). Always:

Automated systems should validate inputs before sending requests.

Withdrawal Whitelist Issues (58207)

Even if whitelist verification is disabled on the withdrawal page, API withdrawals still require pre-approved addresses. To avoid this error:

  1. Add the address manually through the UI
  2. Enable "Exempt from Verification"
  3. Confirm it appears in your approved list

APIs do not bypass security policies—even when UI settings suggest otherwise.

Request Timeout Errors (50004)

Error 50004 typically occurs during high-load periods like funding fee settlements at 08:00, 16:00, and 24:00 UTC. Recommendations:

System stability improves significantly outside peak windows.

Final Tips

If you're still facing unexplained issues:

👉 Access powerful tools to streamline your API trading journey