PHP调用Mefree.NET API
本指南将详细介绍如何通过PHP实现对Mefree.NET的API调用,包括生成签名的方法、请求的构建以及接口调用的完整流程。
1. 签名规则概述
Mefree.NET API 的身份验证通过签名机制进行,签名的生成逻辑如下:
1.1 签名字符串规则
签名使用以下格式的字符串:
sign = timestamp + method + requestPath
timestamp:UTC 时间,格式为 ISO 8601(例如:
2024-11-26T12:34:56.789Z
)。method:HTTP 方法,如
GET
或POST
。requestPath:API 请求路径(包括查询参数),例如:
/api/config
/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1
1.2 签名生成流程
使用 HMAC-SHA256 算法,用 API 的 Secret Key 对拼接的字符串进行加密。
将加密结果用 Base64 编码,得到签名值。
1.3 请求头参数
每次请求需要添加以下 HTTP 头:
Content-Type: application/json
MF-ACCESS-KEY
: 您的 API Key。MF-ACCESS-SIGN
: 生成的签名值。MF-ACCESS-TIMESTAMP
: 当前的 UTC 时间戳。
2. PHP实现签名方法
2.1 签名生成函数
/**
* 生成 Mefree API 的签名
* @param string $timestamp UTC 时间戳 (ISO 8601 格式)
* @param string $method HTTP 方法 (GET/POST)
* @param string $request_path API 请求路径(含参数)
* @param string $secret_key API 的 Secret Key
* @return string 返回 Base64 编码的签名
*/
function generate_signature($timestamp, $method, $request_path, $secret_key) {
// 拼接待签名字符串
$string_to_sign = $timestamp . $method . $request_path;
// 使用 HMAC-SHA256 算法对字符串进行加密
$hash = hash_hmac('sha256', $string_to_sign, $secret_key, true);
// 返回 Base64 编码的签名
return base64_encode($hash);
}
3. API 请求构建
3.1 基础配置
配置 API 的基础信息:
// API 配置信息
$base_url = "https://api.mefree.net"; // Mefree API 基础地址
$api_key = "your_api_key"; // 替换为实际的 API Key
$secret_key = "your_secret_key"; // 替换为实际的 Secret Key
3.2 发起请求的函数
使用 CURL
构建通用的 HTTP 请求函数:
/**
* 发起 Mefree API 请求
* @param string $method HTTP 方法 (GET/POST)
* @param string $request_path API 请求路径(含查询参数)
* @param string $base_url API 基础 URL
* @param string $api_key API Key
* @param string $secret_key API Secret Key
* @return mixed 返回 API 响应内容
*/
function send_request($method, $request_path, $base_url, $api_key, $secret_key) {
// 当前 UTC 时间戳
$timestamp = gmdate("Y-m-d\TH:i:s.v\Z");
// 生成签名
$signature = generate_signature($timestamp, $method, $request_path, $secret_key);
// 设置请求头
$headers = [
"Content-Type: application/json",
"MF-ACCESS-KEY: {$api_key}",
"MF-ACCESS-SIGN: {$signature}",
"MF-ACCESS-TIMESTAMP: {$timestamp}",
];
// 初始化 CURL
$ch = curl_init();
curl_setopt($ch, CURLOPT_URL, $base_url . $request_path); // 设置 URL
curl_setopt($ch, CURLOPT_CUSTOMREQUEST, $method); // 设置请求方法
curl_setopt($ch, CURLOPT_HTTPHEADER, $headers); // 设置请求头
curl_setopt($ch, CURLOPT_RETURNTRANSFER, true); // 返回响应内容
// 执行请求
$response = curl_exec($ch);
$http_code = curl_getinfo($ch, CURLINFO_HTTP_CODE); // 获取 HTTP 状态码
curl_close($ch);
// 返回结果
return [
"status_code" => $http_code,
"response" => $response
];
}
4. 示例接口调用
4.1 获取账户信息
接口描述:
请求路径:
/api/config
HTTP 方法:
GET
调用代码:
// 获取账户信息
$request_path = "/api/config"; // API 请求路径
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);
// 处理返回结果
if ($response['status_code'] == 200) {
echo "账户信息:\n";
echo $response['response'];
} else {
echo "请求失败,HTTP 状态码:" . $response['status_code'] . "\n";
echo "响应内容:" . $response['response'];
}
4.2 创建订单
接口描述:
请求路径:
/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1
HTTP 方法:
POST
调用代码:
// 创建订单
$request_path = "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"; // API 请求路径
$response = send_request("POST", $request_path, $base_url, $api_key, $secret_key);
// 处理返回结果
if ($response['status_code'] == 200) {
echo "订单已创建:\n";
echo $response['response'];
} else {
echo "请求失败,HTTP 状态码:" . $response['status_code'] . "\n";
echo "响应内容:" . $response['response'];
}
4.3 查询订单状态
接口描述:
请求路径:
/api/order/{pay_hash}
HTTP 方法:
GET
调用代码:
// 查询订单状态
$pay_hash = "abcd1234"; // 替换为实际订单的 pay_hash
$request_path = "/api/order/" . $pay_hash; // API 请求路径
$response = send_request("GET", $request_path, $base_url, $api_key, $secret_key);
// 处理返回结果
if ($response['status_code'] == 200) {
echo "订单状态:\n";
echo $response['response'];
} else {
echo "请求失败,HTTP 状态码:" . $response['status_code'] . "\n";
echo "响应内容:" . $response['response'];
}
5. 常见问题
5.1 签名无效 (401 Unauthorized)
确认
MF-ACCESS-KEY
是否正确。确保签名按照规则生成:
拼接顺序为:
timestamp + method + requestPath
。时间戳需为 UTC 格式,格式示例:
2024-11-26T12:34:56.789Z
。使用正确的
SECRET_KEY
生成签名。
5.2 请求参数错误 (400 Bad Request)
检查请求路径是否正确,尤其是查询参数是否完整。
确认
Content-Type
是否为application/json
。
5.3 请求速率限制 (429 Too Many Requests)
Mefree API 对请求频率有限制,需避免在短时间内发起大量请求。
添加合理的请求间隔(例如每秒最多 2 次请求)。
6. 总结
通过以上文档,您可以使用 PHP 高效实现对 Mefree.NET API 的调用,包括生成签名、发送请求以及解析响应数据。对重要操作(如下单)时,建议加上重试机制以提高稳定性。如有疑问,请联系 Mefree 官方支持团队。
Last updated