# 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 签名生成流程**

1. 使用 **HMAC-SHA256** 算法，用 API 的 **Secret Key** 对拼接的字符串进行加密。
2. 将加密结果用 **Base64** 编码，得到签名值。

**1.3 请求头参数**

每次请求需要添加以下 HTTP 头：

* `Content-Type: application/json`
* `MF-ACCESS-KEY`: 您的 API Key。
* `MF-ACCESS-SIGN`: 生成的签名值。
* `MF-ACCESS-TIMESTAMP`: 当前的 UTC 时间戳。

***

#### **2. PHP实现签名方法**

**2.1 签名生成函数**

```php
/**
 * 生成 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 的基础信息：

```php
// 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 请求函数：

```php
/**
 * 发起 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`

**调用代码**：

```php
// 获取账户信息
$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`

**调用代码**：

```php
// 创建订单
$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`

**调用代码**：

```php
// 查询订单状态
$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 官方支持团队。