> For the complete documentation index, see [llms.txt](https://docs.mefree.net/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.mefree.net/zh/getting-started/how-to-buy-energy/go.md).

# Go语言调用 Mefree.NET API

本指南介绍如何使用 **Go语言** 调用 Mefree.NET API，包括签名生成、HTTP 请求构建以及接口调用示例。

***

#### **1. 签名规则概述**

**1.1 签名字符串规则**

Mefree.NET API 使用签名机制验证身份，请确保按照以下规则生成签名：

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`
2. 使用 **HMAC-SHA256** 算法，结合 API 的 **Secret Key** 对拼接字符串进行加密。
3. 将加密结果用 **Base64** 编码，得到最终的签名值。

***

**1.2 请求头参数**

每个请求必须包含以下 HTTP 头：

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

***

#### **2. 环境准备**

确保您的开发环境已安装 **Go**。以下是需要导入的标准库和第三方库：

* **`crypto/hmac`**：用于生成 HMAC 签名。
* **`crypto/sha256`**：用于计算 SHA256 哈希。
* **`encoding/base64`**：用于 Base64 编码。
* **`time`**：用于获取 UTC 时间戳。
* **`net/http` 和 `io/ioutil`**：用于发送 HTTP 请求。

***

#### **3. 签名生成方法**

以下是基于 Go 语言的签名生成方法：

```go
package main

import (
	"crypto/hmac"
	"crypto/sha256"
	"encoding/base64"
	"fmt"
	"time"
)

// 生成签名
func generateSignature(timestamp, method, requestPath, secretKey string) string {
	message := timestamp + method + requestPath
	h := hmac.New(sha256.New, []byte(secretKey))
	h.Write([]byte(message))
	signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
	return signature
}

// 获取当前 UTC 时间戳（ISO 8601 格式）
func getUtcTimestamp() string {
	return time.Now().UTC().Format("2006-01-02T15:04:05.000Z")
}
```

***

#### **4. 通用请求方法**

以下代码展示了一个通用的 HTTP 请求函数，包含签名生成和请求头构建：

```go
package main

import (
	"bytes"
	"fmt"
	"io/ioutil"
	"net/http"
)

// 配置基础信息
const (
	BASE_URL   = "https://api.mefree.net"
	API_KEY    = "your_api_key"    // 替换为您的 API Key
	SECRET_KEY = "your_secret_key" // 替换为您的 Secret Key
)

// 发送 API 请求
func sendRequest(method, requestPath string) ([]byte, error) {
	// 获取当前 UTC 时间戳
	timestamp := getUtcTimestamp()

	// 生成签名
	signature := generateSignature(timestamp, method, requestPath, SECRET_KEY)

	// 构造请求
	client := &http.Client{}
	url := BASE_URL + requestPath
	req, err := http.NewRequest(method, url, nil)
	if err != nil {
		return nil, err
	}

	// 添加请求头
	req.Header.Add("Content-Type", "application/json")
	req.Header.Add("MF-ACCESS-KEY", API_KEY)
	req.Header.Add("MF-ACCESS-SIGN", signature)
	req.Header.Add("MF-ACCESS-TIMESTAMP", timestamp)

	// 发送请求
	resp, err := client.Do(req)
	if err != nil {
		return nil, err
	}
	defer resp.Body.Close()

	// 读取响应
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return nil, err
	}

	if resp.StatusCode != http.StatusOK {
		return nil, fmt.Errorf("HTTP %d: %s", resp.StatusCode, string(body))
	}

	return body, nil
}
```

***

#### **5. 示例接口调用**

**5.1 获取账户信息**

**接口描述**：

* 请求路径：`/api/config`
* HTTP 方法：`GET`

**调用代码**：

```go
func main() {
	response, err := sendRequest("GET", "/api/config")
	if err != nil {
		fmt.Println("请求失败：", err)
		return
	}
	fmt.Println("账户信息：", string(response))
}
```

***

**5.2 创建订单**

**接口描述**：

* 请求路径：`/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`
* HTTP 方法：`POST`

**调用代码**：

```go
func main() {
	requestPath := "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1"
	response, err := sendRequest("POST", requestPath)
	if err != nil {
		fmt.Println("请求失败：", err)
		return
	}
	fmt.Println("订单已创建：", string(response))
}
```

***

**5.3 查询订单状态**

**接口描述**：

* 请求路径：`/api/order/{pay_hash}`
* HTTP 方法：`GET`

**调用代码**：

```go
func main() {
	payHash := "abcd1234" // 替换为实际的 pay_hash
	requestPath := fmt.Sprintf("/api/order/%s", payHash)
	response, err := sendRequest("GET", requestPath)
	if err != nil {
		fmt.Println("请求失败：", err)
		return
	}
	fmt.Println("订单状态：", string(response))
}
```

***

#### **6. 常见问题**

**6.1 签名无效 (401 Unauthorized)**

* 确认 `MF-ACCESS-KEY` 是否正确。
* 确保签名按照规则生成：
  * 拼接顺序为：`timestamp + method + requestPath`。
  * 时间戳格式是否为 UTC。
  * 使用正确的 `SECRET_KEY`。

**6.2 请求参数错误 (400 Bad Request)**

* 检查请求路径是否正确，尤其是查询参数是否完整。
* 确认 `Content-Type` 是否为 `application/json`。

**6.3 请求频率限制 (429 Too Many Requests)**

* 添加合理的请求间隔（例如每秒最多 2 次请求）。

***

#### **7. 总结**

通过本指南，您可以使用 **Go语言** 调用 Mefree.NET API，包括生成签名、构建请求以及解析响应数据。建议为重要操作（如订单创建）添加重试机制，提高调用可靠性。如有问题，请联系 Mefree 官方支持团队。