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

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

---

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

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

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

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

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. Реализация подписи в Python

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

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

import hmac
import hashlib
import base64

def generate_signature(timestamp, method, request_path, secret_key):
    """
    Генерация подписи для Mefree API.

    :param timestamp: Метка времени (UTC в формате ISO 8601)
    :param method: HTTP-метод (GET/POST)
    :param request_path: Путь запроса (включая параметры)
    :param secret_key: Секретный ключ API
    :return: Подпись в формате Base64
    """
    # Формируем строку для подписи
    string_to_sign = f"{timestamp}{method}{request_path}"
    
    # Используем HMAC-SHA256 для шифрования строки
    hmac_obj = hmac.new(secret_key.encode('utf-8'), string_to_sign.encode('utf-8'), hashlib.sha256)
    
    # Возвращаем подпись в формате Base64
    return base64.b64encode(hmac_obj.digest()).decode('utf-8')

---

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

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

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

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

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

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

import requests
from datetime import datetime, timezone

def send_request(method, request_path):
    """
    Отправка запроса к Mefree API.

    :param method: HTTP-метод (GET/POST)
    :param request_path: Путь запроса (включая параметры)
    :return: Ответ API в формате JSON
    """
    # Генерируем метку времени (UTC)
    timestamp = datetime.now(timezone.utc).isoformat(timespec='milliseconds').replace('+00:00', 'Z')

    # Генерируем подпись
    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
    }

    # Полный URL
    url = BASE_URL + request_path

    # Выполняем запрос
    response = requests.request(method, url, headers=headers)

    # Возвращаем JSON-ответ или текст ошибки
    return {
        "status_code": response.status_code,
        "response": response.json() if response.headers.get('Content-Type') == 'application/json' else response.text
    }

---

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

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

• Endpoint: /api/config

• HTTP-метод: GET

Пример:

if __name__ == "__main__":
    # Вызов API для получения информации об аккаунте
    result = send_request("GET", "/api/config")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Информация об аккаунте:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['response'])

---

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

• Endpoint: /api/order?quantity=65000&target_address=TRON_ADDRESS&period=1

• HTTP-метод: POST

Пример:

if __name__ == "__main__":
    # Вызов API для создания заказа
    result = send_request("POST", "/api/order?quantity=65000&target_address=TRON_ADDRESS&period=1")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Заказ успешно создан:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['response'])

---

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

• Endpoint: /api/order/{pay_hash}

• HTTP-метод: GET

Пример:

if __name__ == "__main__":
    # ID заказа для проверки
    pay_hash = "abcd1234"  # Замените на реальный pay_hash

    # Вызов API для проверки статуса заказа
    result = send_request("GET", f"/api/order/{pay_hash}")

    # Обработка ответа
    if result['status_code'] == 200:
        print("Статус заказа:")
        print(result['response'])
    else:
        print(f"Ошибка: {result['status_code']}")
        print(result['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. Заключение

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