OKX V5 API Trading Order Issues and Solutions

·

When interacting with the OKX V5 API for programmatic trading, developers often encounter specific challenges related to request signing and JSON formatting. Two common issues have been identified, particularly after interface updates made around 2023. This guide outlines these problems and provides clear, actionable solutions to ensure your orders execute smoothly.

Common Issue 1: Python Bytes to String Serialization Error

One frequent problem occurs when using Python to generate the required cryptographic signature for API authentication.

The error Object of type bytes is not JSON serializable typically appears because the signature (sign) is generated in a byte format. The requests library expects a string when sending JSON data.

Solution: Convert Bytes to String

The solution involves a simple conversion from bytes to a string after the base64 encoding process. Here is the corrected code snippet for the signature method:

@staticmethod
def signature(timestamp, method, request_path, body, secret_key):
    message = timestamp + method + request_path + body
    mac = hmac.new(bytes(secret_key, encoding='utf8'), bytes(message, encoding='utf-8'), digestmod='sha256')
    output = mac.digest()
    base1 = base64.b64encode(output)  # This is a bytes object
    str1 = str(base1, encoding='utf-8')  # Convert bytes to string
    return str1

This ensures the OK-ACCESS-SIGN header value is a serializable string, preventing the request from failing.

Common Issue 2: "Invalid Sign" Error (Code 50113) in Node.js and C

A more subtle issue emerged in 2023, primarily affecting POST requests made with languages like Node.js and C#. While these requests worked previously, they began failing with the error code 50113 and message "Invalid Sign". GET requests, however, continued to work without issues.

Root Cause: JSON Formatting Differences

Upon investigation, the discrepancy was traced to the precise formatting of the JSON body used in the request.

The OKX API signature verification process is sensitive to the exact string content of the request body. The problem arises from how different programming languages serialize JSON objects by default:

This difference in whitespace changes the message string used to generate the signature. If the server generates its signature based on the Python-style format but the client sends a compact format, the signatures will not match, resulting in the "Invalid Sign" error.

Solution 1: Standardize JSON Serialization

The most robust solution is to configure your JSON serializer to produce the same output format that the OKX API expects.

For C# Developers:

Use the JsonSerializerOptions to include indentation and spacing, which mimics Python's default output.

using System.Text.Json;

var options = new JsonSerializerOptions
{
    WriteIndented = false, // Keep it on one line
    Encoder = System.Text.Encodings.Web.JavaScriptEncoder.UnsafeRelaxedJsonEscaping
    // The key is to ensure a space after ':' and ','
};

// A custom formatter loop might be needed, as standard options may not add the space.
string bodyJson = JsonSerializer.Serialize(orderBody, options);
// You may need a helper method to add the specific spacing (see below).

For Node.js Developers:

Use the JSON.stringify method with a spacer argument.

// This will add spaces, making the output match Python's default
const bodyJson = JSON.stringify(orderBody, null, 2);

However, note that using a spacer of 2 adds full indentation. For a more precise match (just the spaces after colons and commas), a custom serialization function or a third-party library might be necessary.

Solution 2: Use a Custom Helper Function

A more direct and language-agnostic approach is to create a helper function that takes a compact JSON string and programmatically adds the required spaces after colons and commas.

Here is a conceptual example in C#:

public static string FormatJsonWithSpaces(string compactJson)
{
    // This is a simplified example. A more robust implementation would be needed.
    var stringBuilder = new StringBuilder();
    bool inQuotes = false;
    char prevChar = '\0';

    foreach (char c in compactJson)
    {
        if (c == '"' && prevChar != '\\')
            inQuotes = !inQuotes;

        if (!inQuotes)
        {
            if (c == ':')
                stringBuilder.Append(": ");
            else if (c == ',')
                stringBuilder.Append(", ");
            else
                stringBuilder.Append(c);
        }
        else
        {
            stringBuilder.Append(c);
        }
        prevChar = c;
    }
    return stringBuilder.ToString();
}

You would use it like this:

string compactJson = JsonSerializer.Serialize(orderBody);
string formattedJson = FormatJsonWithSpaces(compactJson);
// Use formattedJson as the request body

Important Additional Requirement: Field Ordering

Beyond spacing, the OKX V5 API can also be sensitive to the alphabetical order of the fields in the JSON body when generating the signature. Always sort your JSON object properties alphabetically before serializing them to a string for the signing process.

In C#:

var orderBody = new Dictionary<string, object>
{
    ["instId"] = "BTC-USDT-SWAP",
    ["ordType"] = "market",
    ["posSide"] = "long",
    ["side"] = "buy",
    ["sz"] = "20",
    ["tdMode"] = "cross"
};
// Serializing a sorted dictionary will maintain order
var sortedDict = new SortedDictionary<string, object>(orderBody);
string bodyJson = JsonSerializer.Serialize(sortedDict);

👉 Explore more API integration strategies

Best Practices for OKX V5 API Integration

To avoid common pitfalls and ensure reliable operation, follow these best practices:

  1. Consistent Body Generation: The string used to create the signature must be 100% identical to the body sent in the actual HTTP request. Handle your JSON precisely.
  2. Check Timestamp: Ensure your system's clock is synchronized. The API rejects requests with timestamps that deviate too far from the server time.
  3. Review API Documentation: The OKX API documentation is regularly updated. Always refer to the latest official version for endpoints, parameters, and requirements.
  4. Use the Simulation Flag: During development, always set the x-simulated-trading header to "1". This ensures your test orders are not placed on the live market, preventing accidental real trades.
  5. Error Handling: Implement robust error handling for API responses. Codes like 50113 indicate an authentication issue, while others relate to liquidity, order parameters, or rate limiting.

Frequently Asked Questions

Why does my Python code work but my C#/Node.js code fail with an "Invalid Sign" error?
The most likely cause is a difference in how the JSON request body is formatted. The OKX API signature verification is strict and expects a specific format (including spaces after colons and commas), which is the default in Python's json.dumps() but not in other languages.

How can I see the exact string being used for the signature on the OKX server?
You cannot see the server's internal process. The best approach is to meticulously ensure your client's signing process matches the expected format as outlined in the official documentation and community solutions.

Is the field ordering requirement documented by OKX?
While not always explicitly highlighted in every section, the need for consistent and often alphabetical field ordering is a common requirement in cryptographic signing processes to ensure both the client and server are signing the identical string. It is considered a best practice.

Will OKX fix this inconsistency in their API?
API specifications can evolve. It is crucial to rely on the official OKX API documentation for the definitive guide on how to structure requests. Developers should write code that is adaptable to changes in API requirements.

What is the purpose of the 'x-simulated-trading' header?
This header allows you to test your order placement logic without risking real funds. When set to "1", the API processes the request in a simulated environment, returning a realistic response without executing a live trade.

Are these issues specific to certain endpoints?
The signing process is universal for all private endpoints (those requiring API keys). However, the sensitivity to body formatting is most apparent in POST requests (like /api/v5/trade/order) that carry a JSON payload. GET requests, which usually place parameters in the query string, are less prone to this specific spacing issue.