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:
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:
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/configHTTP 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=1HTTP 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.
