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:

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:

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:

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:

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:

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.