# Руководство по вызову Mefree.NET API на Go

В этом руководстве подробно описано, как работать с API платформы **Mefree.NET** на языке Go. Приведены инструкции по генерации подписи, отправке запросов и обработке ответов.

***

#### **1. Общая информация о правилах подписи**

Для аутентификации API **Mefree.NET** используется механизм подписи. Подпись формируется следующим образом:

**1.1 Формирование строки для подписи**

Строка подписи формируется по следующему шаблону:

```plaintext
sign = timestamp + method + requestPath
```

* **timestamp**: Метка времени в формате UTC (ISO 8601), например: `2024-11-26T12:34:56.789Z`.
* **method**: HTTP-метод, например, `GET` или `POST`.
* **requestPath**: Путь запроса, включая параметры, например:
  * `/api/config`
  * `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`

**1.2 Процесс генерации подписи**

1. Создайте строку из `timestamp`, `method` и `requestPath`.
2. Используйте алгоритм **HMAC-SHA256** для шифрования строки с использованием **секретного ключа API (Secret Key)**.
3. Закодируйте результат с помощью **Base64** — это и будет подпись.

**1.3 Заголовки запроса**

Каждый запрос к API должен содержать следующие заголовки:

* `Content-Type`: `application/json`
* `MF-ACCESS-KEY`: Ваш API-ключ.
* `MF-ACCESS-SIGN`: Сгенерированная подпись.
* `MF-ACCESS-TIMESTAMP`: Метка времени в формате UTC.

***

#### **2. Реализация подписи на Go**

**2.1 Функция для генерации подписи**

Пример функции для создания подписи:

```go
package main

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

// GenerateSignature создаёт подпись для Mefree API
func GenerateSignature(timestamp, method, requestPath, secretKey string) (string, error) {
	// Формируем строку для подписи
	stringToSign := timestamp + method + requestPath

	// Создаём HMAC-SHA256 хэш
	h := hmac.New(sha256.New, []byte(secretKey))
	_, err := h.Write([]byte(stringToSign))
	if err != nil {
		return "", err
	}

	// Кодируем хэш в Base64
	signature := base64.StdEncoding.EncodeToString(h.Sum(nil))
	return signature, nil
}
```

***

#### **3. Отправка запросов к API**

**3.1 Базовая конфигурация**

Настройте параметры подключения к API:

```go
const (
	BaseURL   = "https://api.mefree.net"  // Базовый URL Mefree API
	APIKey    = "your_api_key"        // Ваш API-ключ
	SecretKey = "your_secret_key"     // Ваш секретный ключ
)
```

**3.2 Функция отправки запросов**

Используйте следующую функцию для отправки запросов к API:

```go
package main

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

// SendRequest отправляет запрос к Mefree API
func SendRequest(method, requestPath string) (int, string, error) {
	// Генерируем текущую метку времени в формате UTC
	timestamp := time.Now().UTC().Format("2006-01-02T15:04:05.000Z")

	// Создаём подпись
	signature, err := GenerateSignature(timestamp, method, requestPath, SecretKey)
	if err != nil {
		return 0, "", fmt.Errorf("error generating signature: %v", err)
	}

	// Устанавливаем заголовки
	headers := map[string]string{
		"Content-Type":           "application/json",
		"MF-ACCESS-KEY":          APIKey,
		"MF-ACCESS-SIGN":         signature,
		"MF-ACCESS-TIMESTAMP":    timestamp,
	}

	// Формируем запрос
	url := BaseURL + requestPath
	req, err := http.NewRequest(method, url, nil)
	if err != nil {
		return 0, "", fmt.Errorf("error creating request: %v", err)
	}

	// Добавляем заголовки к запросу
	for key, value := range headers {
		req.Header.Set(key, value)
	}

	// Отправляем запрос
	client := &http.Client{}
	resp, err := client.Do(req)
	if err != nil {
		return 0, "", fmt.Errorf("error sending request: %v", err)
	}
	defer resp.Body.Close()

	// Читаем тело ответа
	body, err := ioutil.ReadAll(resp.Body)
	if err != nil {
		return resp.StatusCode, "", fmt.Errorf("error reading response: %v", err)
	}

	return resp.StatusCode, string(body), nil
}
```

***

#### **4. Примеры вызовов API**

**4.1 Получение информации об аккаунте**

* **Endpoint**: `/api/config`
* **HTTP-метод**: `GET`

**Пример кода:**

```go
func main() {
	// Путь запроса
	requestPath := "/api/config"

	// Отправляем запрос
	statusCode, response, err := SendRequest("GET", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Информация об аккаунте:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, response)
	}
}
```

***

**4.2 Создание заказа**

* **Endpoint**: `/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"

	// Отправляем запрос
	statusCode, response, err := SendRequest("POST", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Заказ успешно создан:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, response)
	}
}
```

***

**4.3 Проверка статуса заказа**

* **Endpoint**: `/api/order/{pay_hash}`
* **HTTP-метод**: `GET`

**Пример кода:**

```go
func main() {
	// Путь запроса
	payHash := "abcd1234" // Замените на реальный pay_hash
	requestPath := "/api/order/" + payHash

	// Отправляем запрос
	statusCode, response, err := SendRequest("GET", requestPath)
	if err != nil {
		fmt.Printf("Ошибка: %v\n", err)
		return
	}

	// Обрабатываем ответ
	if statusCode == 200 {
		fmt.Println("Статус заказа:")
		fmt.Println(response)
	} else {
		fmt.Printf("Ошибка: HTTP статус %d\nОтвет: %s\n", statusCode, response)
	}
}
```

***

#### **5. Частые ошибки**

**5.1 Неверная подпись (401 Unauthorized)**

* Проверьте правильность `MF-ACCESS-KEY`.
* Убедитесь, что строка для подписи составлена по шаблону: `timestamp + method + requestPath`.
* Используется правильный **SECRET\_KEY**.
* Метка времени должна быть в формате UTC.

**5.2 Ошибка параметров (400 Bad Request)**

* Проверьте корректность пути и параметров запроса.
* Убедитесь, что заголовок `Content-Type` установлен как `application/json`.

**5.3 Ограничение частоты запросов (429 Too Many Requests)**

* Mefree API ограничивает частоту запросов. Избегайте чрезмерного количества запросов за короткий период.
* Рекомендуемая частота: не более 2 запросов в секунду.

***

#### **6. Заключение**

С помощью данного руководства вы сможете эффективно взаимодействовать с API платформы **Mefree.NET** на языке Go. Включены примеры создания запросов, обработки ответов и управления операциями через API. Для критически важных операций (например, создание заказа) рекомендуется реализовать повторные попытки. Если у вас возникнут вопросы, обращайтесь в службу поддержки **Mefree.NET**.


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://docs.mefree.net/ru/getting-started/how-to-buy-energy/go.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.