# Java Guide for Calling Mefree.NET API

This guide explains how to use **Java** to interact with the Mefree.NET API. It covers signature generation, HTTP request construction, and example API calls.

***

#### **1. Overview of the Signature Rules**

**1.1 Signature String Rules**

Mefree.NET API requires a signature mechanism for authentication. Ensure the signature is generated following these rules:

1. **Construct the String to Sign**:

   ```
   sign = timestamp + method + requestPath
   ```

   * **timestamp**: UTC time in ISO 8601 format, e.g., `2024-11-26T12:34:56.789Z`.
   * **method**: HTTP method, e.g., `GET` or `POST`.
   * **requestPath**: API request path (including query parameters), such as:
     * `/api/config`
     * `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`
2. **Generate the Signature**:
   * Use the **HMAC-SHA256** algorithm with the **Secret Key** to hash the string.
   * Encode the resulting hash with **Base64** to obtain the final signature.

***

**1.2 Required HTTP Headers**

Each request must include the following headers:

* `Content-Type: application/json`
* `MF-ACCESS-KEY`: Your API Key.
* `MF-ACCESS-SIGN`: The generated signature.
* `MF-ACCESS-TIMESTAMP`: Current UTC timestamp.

***

#### **2. Environment Setup**

Ensure you have the following dependencies available in your Java environment:

* **Java Standard Libraries** for time handling, Base64 encoding, and HTTP requests.
* If using external libraries, you can include:
  * `Apache HttpClient` for HTTP requests.
  * `org.apache.commons.codec` for HMAC-SHA256 and Base64 encoding.

***

#### **3. Signature Generation Method**

Below is the Java implementation for generating the signature:

```java
import javax.crypto.Mac;
import javax.crypto.spec.SecretKeySpec;
import java.util.Base64;

public class MefreeApiHelper {

    // Generate HMAC-SHA256 signature
    public static String generateSignature(String timestamp, String method, String requestPath, String secretKey) {
        try {
            String message = timestamp + method + requestPath;
            Mac mac = Mac.getInstance("HmacSHA256");
            SecretKeySpec secretKeySpec = new SecretKeySpec(secretKey.getBytes(), "HmacSHA256");
            mac.init(secretKeySpec);
            byte[] hash = mac.doFinal(message.getBytes());
            return Base64.getEncoder().encodeToString(hash);
        } catch (Exception e) {
            throw new RuntimeException("Error while generating signature: " + e.getMessage());
        }
    }

    // Get current UTC timestamp in ISO 8601 format
    public static String getUtcTimestamp() {
        return java.time.ZonedDateTime.now(java.time.ZoneOffset.UTC)
                .format(java.time.format.DateTimeFormatter.ofPattern("yyyy-MM-dd'T'HH:mm:ss.SSS'Z'"));
    }
}
```

***

#### **4. HTTP Request Helper**

The following code demonstrates how to make HTTP requests with the required headers:

```java
import org.apache.http.client.methods.*;
import org.apache.http.impl.client.CloseableHttpClient;
import org.apache.http.impl.client.HttpClients;
import org.apache.http.util.EntityUtils;

public class MefreeApiClient {
    private static final String BASE_URL = "https://api.mefree.net";
    private static final String API_KEY = "your_api_key";      // Replace with your API Key
    private static final String SECRET_KEY = "your_secret_key"; // Replace with your Secret Key

    public static String sendRequest(String method, String requestPath) {
        try (CloseableHttpClient httpClient = HttpClients.createDefault()) {
            String timestamp = MefreeApiHelper.getUtcTimestamp();
            String signature = MefreeApiHelper.generateSignature(timestamp, method, requestPath, SECRET_KEY);

            // Create HTTP request
            HttpRequestBase request;
            if (method.equalsIgnoreCase("GET")) {
                request = new HttpGet(BASE_URL + requestPath);
            } else if (method.equalsIgnoreCase("POST")) {
                request = new HttpPost(BASE_URL + requestPath);
            } else {
                throw new IllegalArgumentException("Unsupported HTTP method: " + method);
            }

            // Add headers
            request.setHeader("Content-Type", "application/json");
            request.setHeader("MF-ACCESS-KEY", API_KEY);
            request.setHeader("MF-ACCESS-SIGN", signature);
            request.setHeader("MF-ACCESS-TIMESTAMP", timestamp);

            // Send the request
            try (CloseableHttpResponse response = httpClient.execute(request)) {
                int statusCode = response.getStatusLine().getStatusCode();
                String responseBody = EntityUtils.toString(response.getEntity());

                if (statusCode != 200) {
                    throw new RuntimeException("HTTP " + statusCode + ": " + responseBody);
                }
                return responseBody;
            }
        } catch (Exception e) {
            throw new RuntimeException("Error while sending request: " + e.getMessage(), e);
        }
    }
}
```

***

#### **5. Example API Calls**

**5.1 Get Account Information**

**API Endpoint**: `/api/config`\
**HTTP Method**: `GET`

**Code Example**:

```java
public class Main {
    public static void main(String[] args) {
        try {
            String response = MefreeApiClient.sendRequest("GET", "/api/config");
            System.out.println("Account Information: " + response);
        } catch (Exception e) {
            System.err.println("Failed to fetch account information: " + e.getMessage());
        }
    }
}
```

***

**5.2 Create an Order**

**API Endpoint**: `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`\
**HTTP Method**: `POST`

**Code Example**:

```java
public class Main {
    public static void main(String[] args) {
        try {
            String requestPath = "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1";
            String response = MefreeApiClient.sendRequest("POST", requestPath);
            System.out.println("Order Created: " + response);
        } catch (Exception e) {
            System.err.println("Failed to create order: " + e.getMessage());
        }
    }
}
```

***

**5.3 Query Order Status**

**API Endpoint**: `/api/order/{pay_hash}`\
**HTTP Method**: `GET`

**Code Example**:

```java
public class Main {
    public static void main(String[] args) {
        try {
            String payHash = "abcd1234"; // Replace with actual pay_hash
            String requestPath = "/api/order/" + payHash;
            String response = MefreeApiClient.sendRequest("GET", requestPath);
            System.out.println("Order Status: " + response);
        } catch (Exception e) {
            System.err.println("Failed to fetch order status: " + e.getMessage());
        }
    }
}
```

***

#### **6. Common Issues**

**6.1 Invalid Signature (401 Unauthorized)**

* Ensure the `MF-ACCESS-KEY` matches your API Key.
* Verify the signature generation logic:
  * String concatenation order is `timestamp + method + requestPath`.
  * Use the correct `SECRET_KEY`.
* Ensure the timestamp is in UTC format and not older than 5 seconds.

**6.2 Bad Request (400)**

* Verify the request path and query parameters are correct.
* Ensure `Content-Type` is set to `application/json`.

**6.3 Too Many Requests (429)**

* Respect the API rate limits and implement a delay between requests if necessary.

***

#### **7. Summary**

With this guide, you can now use **Java** to call Mefree.NET APIs. It includes signature generation, HTTP request construction, and example code for various API endpoints. For further clarification, contact Mefree technical support or consult the official API documentation.