> 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/ru/getting-started/how-to-buy-energy/buy-energy-by-api-quickstart.md).

# Покупка энергии через 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. Удачи!