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

Данное руководство описывает процесс взаимодействия с API платформы **Mefree.NET** с использованием Node.js. Оно включает создание подписи, отправку запросов и обработку ответов от API.

***

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

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

**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 Заголовки HTTP-запроса**

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

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

***

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

**2.1 Установка необходимых библиотек**

Перед началом убедитесь, что у вас установлены следующие библиотеки:

```bash
npm install axios crypto
```

* **axios**: Для отправки HTTP-запросов.
* **crypto**: Встроенная библиотека Node.js для создания подписи.

***

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

Ниже приведён пример функции для генерации подписи:

```javascript
const crypto = require('crypto');

/**
 * Генерация подписи для Mefree API.
 *
 * @param {string} timestamp Метка времени (UTC в формате ISO 8601)
 * @param {string} method HTTP-метод (GET/POST)
 * @param {string} requestPath Путь запроса (включая параметры)
 * @param {string} secretKey Секретный ключ API
 * @returns {string} Подпись в формате Base64
 */
function generateSignature(timestamp, method, requestPath, secretKey) {
    // Формируем строку для подписи
    const stringToSign = `${timestamp}${method}${requestPath}`;

    // Используем HMAC-SHA256 для шифрования строки
    const hmac = crypto.createHmac('sha256', secretKey);
    hmac.update(stringToSign);

    // Возвращаем подпись в формате Base64
    return hmac.digest('base64');
}
```

***

#### **3. Создание запросов к API**

**3.1 Конфигурация**

Задайте базовые параметры для подключения к API:

```javascript
const axios = require('axios');

// Конфигурация API
const BASE_URL = "https://api.mefree.net";       // Базовый URL Mefree API
const API_KEY = "your_api_key";             // Ваш API-ключ
const SECRET_KEY = "your_secret_key";       // Ваш секретный ключ
```

**3.2 Универсальная функция для отправки запросов**

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

```javascript
/**
 * Отправка запроса к Mefree API.
 *
 * @param {string} method HTTP-метод (GET/POST)
 * @param {string} requestPath Путь запроса (включая параметры)
 * @returns {Promise<Object>} Ответ API
 */
async function sendRequest(method, requestPath) {
    // Генерируем метку времени (UTC)
    const timestamp = new Date().toISOString();

    // Генерируем подпись
    const signature = generateSignature(timestamp, method, requestPath, SECRET_KEY);

    // Заголовки запроса
    const headers = {
        'Content-Type': 'application/json',
        'MF-ACCESS-KEY': API_KEY,
        'MF-ACCESS-SIGN': signature,
        'MF-ACCESS-TIMESTAMP': timestamp,
    };

    // Полный URL
    const url = `${BASE_URL}${requestPath}`;

    try {
        // Выполняем запрос
        const response = await axios({
            method,
            url,
            headers,
        });

        // Возвращаем ответ API
        return {
            statusCode: response.status,
            data: response.data,
        };
    } catch (error) {
        // Обработка ошибок
        return {
            statusCode: error.response?.status || 500,
            error: error.response?.data || error.message,
        };
    }
}
```

***

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

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

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

**Пример:**

```javascript
(async () => {
    const response = await sendRequest('GET', '/api/config');

    if (response.statusCode === 200) {
        console.log("Информация об аккаунте:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

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

* **Endpoint**: `/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1`
* **HTTP-метод**: `POST`

**Пример:**

```javascript
(async () => {
    const requestPath = '/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1';
    const response = await sendRequest('POST', requestPath);

    if (response.statusCode === 200) {
        console.log("Заказ успешно создан:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

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

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

**Пример:**

```javascript
(async () => {
    const payHash = 'abcd1234'; // Замените на реальный pay_hash
    const requestPath = `/api/order/${payHash}`;
    const response = await sendRequest('GET', requestPath);

    if (response.statusCode === 200) {
        console.log("Статус заказа:", response.data);
    } else {
        console.error("Ошибка:", response);
    }
})();
```

***

#### **5. Часто встречающиеся ошибки**

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

* Убедитесь, что заголовок `MF-ACCESS-KEY` содержит правильный API-ключ.
* Проверьте, что строка для подписи сформирована в правильной последовательности: `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. Заключение**

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


---

# 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/nodejs.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.