OpenAPI Documentation: Signature Method

OpenAPI Documentation: Signature Method Description

1. Overview

This document describes how clients use asymmetric encryption (RSA) to sign API requests and include the signature, user ID, and timestamp in the request headers when sending to the server.

2. Process Description

2.1 Key Generation

Users generate RSA public-private key pairs.

Upload the public key to the agent backend, while the private key is securely stored by the client.

2.2 Request Signing (Client-side)

The client generates a timestamp of the current time (Unix timestamp, accurate to seconds).

Compress and sort the request body according to JSON rules.

Concatenate the timestamp and request body into a string, and sign it using the private key.

Include the signature, user ID, and timestamp in the request headers.

2.3 Request Sending

The client sends the signed request to the server, with the following fields in the request headers:

X-User-ID: User ID.

X-Signature: Signature generated using the private key (Base64 encoded).

X-Timestamp: Timestamp.

3. JSON Compression and Sorting Rules

To ensure consistency between client and server when generating and verifying signatures, the request body must be JSON stringified according to the following rules:

JSON Stringification:

Use json.dumps() to convert the entire request body to a JSON string.

Data Types:

Numbers should not be quoted.

Example

Original Request Body

{
    "key2": "value2",
    "key1": "value1",
    "key3": {
        "nestedKey2": "nestedValue2",
        "nestedKey1": "nestedValue1"
    }
}

Formatted Request Body

{"key1":"value1","key2":"value2","key3":{"nestedKey1":"nestedValue1","nestedKey2":"nestedValue2"}}

4. Request Example

Request Headers

Request Body

{
    "key1": "value1",
    "key2": "value2"
}

5. Code Examples

5.1 Generate Signature (Client-side)

5.2 Send Request (Client-side)

6. Important Notes

Key Security: Private keys must be securely stored to prevent leakage.

Time Synchronization: Ensure client system time is synchronized with the server to avoid verification failures due to time zone differences.

HTTPS: Use HTTPS protocol for data transmission to ensure data security during transmission.

Through the above instructions and code examples, clients can correctly generate signatures and send requests, ensuring the integrity and security of API requests.

7. Webhook Signature Method Description

7.1 Overview

This document describes how the server signs webhook callback requests and how agents can verify signatures.

7.2 Key Management

The server uses RSA algorithm to generate public-private key pairs

Provides the public key to agents, who configure the public key in their backend

The server keeps the private key secure for signing webhook requests

7.3 Signing Process

The server generates a timestamp of the current time (Unix timestamp, accurate to seconds)

Converts the request body to a JSON string

Concatenates the timestamp and request body into a string, and signs it using the private key

Includes the signature and timestamp in the request headers

7.4 Request Headers

When the server sends webhook requests, the request headers contain the following fields:

X-Signature: Signature generated using the private key (Base64 encoded)

X-Timestamp: Timestamp

7.5 Signature Verification Example (Agent-side)

7.6 Important Notes

Agent-side considerations:

Time Validation: It is recommended to verify that the timestamp is within a reasonable time range (e.g., 5 minutes) to prevent replay attacks

Public Key Security: Although public keys can be made public, it is still recommended to transmit and store them through secure channels

HTTPS: Webhook callbacks must use HTTPS protocol to ensure transmission security

Server-side implementation notes:
4. Retry Mechanism ✅:

Implemented intelligent retry mechanism for webhook callback requests

Handle different error types accordingly:

Network timeout: Wait 30 seconds before retry

Server errors (5xx): Wait 1 minute before retry

Client errors (4xx): Only retry for specific error codes

Maximum of 3 retry attempts

Each retry logs detailed information

Ensures message eventually reaches agent servers

8. OpenAPI Status Description

8.1 Error Status Codes

invalidBody: Request body does not comply with specifications

Unauthorized: Signature verification failed

Not Found: Resource does not exist

insufficientBalance: Insufficient balance

Too Many Requests: Too frequent requests

verifySignFailed: All secret comparisons failed

accountNotExist: Account/Agent does not exist

notAgencyMerchant: When filtering merchant information, the accountId is not an agency merchant, or the currencyAccount merchant is not an agency merchant

tradeCurrencyAccountFoundErr: Currency merchant query failed

dbNotMatch: For exact matching of single data, when request data is compliant but no matching data is found

OpenAPI Documentation: Signature Method