# Покупка энергии через API

####

Данное руководство поможет вам быстро освоить процесс подключения и использования REST API платформы **Mefree.NET** для автоматизированной покупки энергии TRON.

***

#### **1. Подготовка**

**1.1 Регистрация и получение API-ключей**

1. Войдите в Telegram-бот платформы Mefree.NET: [**@SuperXCoinBot**](https://t.me/SuperXCoinBot).
2. Перейдите в раздел **"Личный кабинет"** и выберите **"API Покупка"**.
3. Сохраните следующие данные:
   * **API KEY (ACCESS KEY)**
   * **SECRET KEY (API SECRET)**

**1.2 Инструменты для работы**

* **Тестирование API**: Postman, Curl или командная строка.
* **Язык разработки**: Python (рекомендуется библиотека `requests`) или любой язык, поддерживающий HTTP-запросы.

**1.3 Документация**

Ознакомьтесь с [официальной документацией Mefree.NET API](https://github.com/xcoin-blockchain/xcoin-energy/blob/doc-ru/getting-started/how-to-buy-energy/broken-reference/README.md) для получения более подробной информации об интерфейсах.

***

#### **2. Основы работы с API**

**2.1 Базовый URL**

Для продакшн-среды используйте:**`https://api.mefree.net`**

**2.2 Заголовки API**

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

* **Content-Type**: `application/json`
* **MF-ACCESS-KEY**: ваш API-ключ.
* **MF-ACCESS-SIGN**: подпись запроса (см. раздел о генерации подписи).
* **MF-ACCESS-TIMESTAMP**: текущая временная метка.

**2.3 Формат временной метки**

**MF-ACCESS-TIMESTAMP** должен быть в формате ISO 8601 (UTC). Пример: **`2023-01-01T12:00:00.000Z`**

**2.4 Правила подписи**

Подпись используется для проверки подлинности запроса. Алгоритм формирования подписи:

1. Составьте строку для подписи: **`sign = timestamp + method + requestPath`**

   * `timestamp`: значение MF-ACCESS-TIMESTAMP.
   * `method`: HTTP-метод (например, GET, POST).
   * `requestPath`: путь запроса (включая параметры, если они есть).

   Пример:\
   `/api/order?quantity=65000&period=1&target_address=Txxx...7n`
2. Выполните хэширование строки с использованием алгоритма **HMAC-SHA256** и вашего **SECRET KEY**.
3. Закодируйте результат в формате Base64.

***

#### **3. Примеры запросов**

**3.1 Установка окружения**

Убедитесь, что библиотеки **requests** и **datetime** установлены:

```bash
pip install requests
```

**3.2 Пример запроса: Проверка баланса**

**Описание запроса**:

* URL: `GET /api/config`
* Функция: Получение информации о балансе аккаунта.

**Код на Python**:

```python
import requests
import hmac
import base64
from datetime import datetime

# Конфигурация API
BASE_URL = "https://api.mefree.net"
API_KEY = "your_api_key"
SECRET_KEY = "your_secret_key"

# Генерация подписи
def generate_signature(timestamp, method, request_path, secret_key):
    message = f"{timestamp}{method}{request_path}"
    mac = hmac.new(secret_key.encode(), message.encode(), digestmod="sha256")
    return base64.b64encode(mac.digest()).decode()

# Текущая временная метка
timestamp = datetime.utcnow().isoformat(timespec="milliseconds") + "Z"
method = "GET"
request_path = "/api/config"

# Формирование подписи
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,
}

# Отправка запроса
response = requests.get(BASE_URL + request_path, headers=headers)
if response.status_code == 200:
    print("Баланс аккаунта:", response.json())
else:
    print("Ошибка:", response.status_code, response.text)
```

***

**3.3 Пример запроса: Создание заказа**

**Описание запроса**:

* URL: `POST /api/order`
* Функция: Создание заказа на покупку энергии.

**Код на Python**:

```python
# Параметры заказа
quantity = 65000  # количество энергии
target_address = "TDYk....4rnPfkdPZ"
period = 1  # срок аренды (в днях)
request_path = f"/api/order?quantity={quantity}&target_address={target_address}&period={period}"

# Генерация подписи
timestamp = datetime.utcnow().isoformat(timespec="milliseconds") + "Z"
method = "POST"
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,
}

# Отправка POST-запроса
response = requests.post(BASE_URL + request_path, headers=headers)
if response.status_code == 200:
    print("Заказ успешно создан:", response.json())
else:
    print("Ошибка:", response.status_code, response.text)
```

***

#### **4. Частые ошибки и их решение**

1. **HTTP 401 Unauthorized**:
   * Проверьте, правильно ли указаны **MF-ACCESS-KEY** и **MF-ACCESS-SIGN**.
   * Убедитесь, что API-ключ активен.
2. **HTTP 400 Bad Request**:
   * Проверьте корректность параметров запроса.
3. **Ошибка подписи**:
   * Убедитесь, что временная метка в формате UTC и подпись сформирована строго по правилам.

***

#### **5. Дальнейшие шаги**

* Изучите документацию API, чтобы освоить другие функции (например, проверку деталей заказа).
* Интегрируйте API в вашу систему для автоматизации процессов.

Следуя этому руководству, вы успешно подключитесь к API Mefree.NET и сможете автоматизировать покупку энергии TRON. Удачи!


---

# 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/buy-energy-by-api-quickstart.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.