Аутентификация MERX API: ключи, разрешения и лимиты на запросы

Каждая интеграция API начинается с аутентификации. Если настроить её правильно, автоматическая торговля энергией будет работать без перебоев круглосуточно. Если ошибиться, придется иметь дело с утёчками учётных данных, непонятными ошибками 403 или блокировками из-за превышения лимитов, которые остановят ваши production-системы в самый неудачный момент.

MERX предоставляет два метода аутентификации, каждый разработан для конкретного случая использования. Эта статья подробно рассматривает оба — как они работают, когда использовать каждый, как управлять разрешениями гранулярно и какие лимиты на запросы применяются ко всему API.

Два метода аутентификации

MERX поддерживает два способа аутентификации API-запросов: API-ключи и JWT-токены. Они служат разным целям и не являются взаимозаменяемы.

Аутентификация с API-ключом

API-ключи — это долгоживущие учётные данные, разработанные для связи между серверами. Вы создаёте их через API или панель администратора, назначаете конкретные разрешения и включаете их в каждый запрос через заголовок X-API-Key.

curl https://merx.exchange/api/v1/prices \
  -H "X-API-Key: merx_live_k7x9m2p4..."

API-ключи — правильный выбор, когда:

Ваш backend-сервис обращается к MERX от имени ваших пользователей.
Вы запускаете запланированные задания, которые создают заказы или проверяют балансы.
Вы хотите контролировать разрешения гранулярно (ключ для создания заказов, который не может выводить средства).
Вам нужны учётные данные, которые работают без интерактивного входа.

API-ключи не имеют срока действия по умолчанию. Они остаются действительными, пока вы не отозвёте их явно. Это удобно для долгоживущих сервисов, но требует тщательного управления.

Аутентификация с JWT-токеном

JWT-токены — это краткосрочные учётные данные, выданные после входа. Вы аутентифицируетесь с помощью электронной почты и пароля (или через OAuth), получаете JWT и включаете его в запросы через заголовок Authorization с префиксом Bearer.

curl https://merx.exchange/api/v1/balance \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

JWT-токены — правильный выбор, когда:

Человек взаимодействует с фронтенд-приложением, которое обращается к API.
Вы хотите ограничить время доступа, который автоматически истекает.
Вы создаёте веб- или мобильное приложение с процессом входа.

JWT-токены, выданные MERX, истекают через 24 часа. После истечения клиент должен повторно пройти аутентификацию, чтобы получить новый токен. Refresh-токены продлевают сеансы без необходимости повторного входа пользователя.

Какой использовать

Для программных интеграций — ботов для платежей, автоматической торговли, backend-сервисов — используйте API-ключи. Они проще в управлении, поддерживают гранулярные разрешения и не требуют процесса входа.

Для приложений, ориентированных на пользователя, где человек входит в систему, используйте JWT-токены. Они обеспечивают доступ на основе сеансов с автоматическим истечением, снижая риск утечки учётных данных из клиентского кода.

Вы можете использовать оба в одной системе. Распространённый паттерн: аутентификация JWT для вашей панели администратора (операторы входят для управления настройками), аутентификация API-ключом для ваших backend-сервисов (автоматическое создание заказов, мониторинг баланса).

Создание и управление API-ключами

Создание ключа

Создавайте API-ключи через сам API или через веб-панель MERX. Эндпоинт API — это POST /api/v1/keys:

curl -X POST https://merx.exchange/api/v1/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..." \
  -H "Content-Type: application/json" \
  -d '{
    "name": "production-order-bot",
    "permissions": ["create_orders", "view_orders", "view_balance"]
  }'

Ответ включает полный API-ключ. Это единственный раз, когда возвращается полный ключ. Сохраните его немедленно в менеджер секретов.

{
  "id": "key_8f3k2m9x",
  "name": "production-order-bot",
  "key": "merx_live_k7x9m2p4q8r1s5t3u7v2w6x0y4z...",
  "permissions": ["create_orders", "view_orders", "view_balance"],
  "created_at": "2026-03-30T10:00:00Z"
}

Примечание: эндпоинт создания ключа требует аутентификацию JWT. Вы должны сначала войти, чтобы создать API-ключи. Это намеренное решение в целях безопасности — API-ключи не могут создавать другие API-ключи.

Использование JavaScript SDK

import { MerxClient } from 'merx-sdk';

const merx = new MerxClient({
  apiKey: process.env.MERX_API_KEY,
  baseUrl: 'https://merx.exchange/api/v1',
});

// SDK автоматически включает заголовок X-API-Key
const prices = await merx.prices.list();
const balance = await merx.account.getBalance();

Использование Python SDK

from merx_sdk import MerxClient

client = MerxClient(
    api_key="merx_live_k7x9m2p4...",
    base_url="https://merx.exchange/api/v1",
)

prices = client.get_prices()
balance = client.get_balance()

Список и отзыв ключей

Просмотрите все активные ключи вашего аккаунта:

curl https://merx.exchange/api/v1/keys \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Отозвите ключ немедленно:

curl -X DELETE https://merx.exchange/api/v1/keys/key_8f3k2m9x \
  -H "Authorization: Bearer eyJhbGciOiJIUzI1NiIs..."

Отзыв происходит мгновенно. Любой запрос с использованием отозванного ключа немедленно возвращает 401. Периода отсрочки нет.

Типы разрешений

API-ключи MERX поддерживают гранулярные разрешения. При создании ключа вы указываете, какие операции он может выполнять. Ключ без требуемого разрешения получает ответ 403 Forbidden.

Доступные разрешения

Data table
Разрешение	Описание	Типичный случай использования
`view_balance`	Прочитать баланс счёта и историю транзакций	Панели мониторинга, оповещения
`view_orders`	Прочитать статус заказа и историю заказов	Отслеживание заказов, отчётность
`create_orders`	Создать новые заказы энергии и bandwidth	Боты автоматической торговли
`broadcast`	Отправить подписанные транзакции на трансляцию	Пользовательские рабочие процессы транзакций

Принципы разработки разрешений

Наименьшие привилегии. Дайте каждому ключу только те разрешения, которые ему нужны. Панель мониторинга не нуждается в create_orders. Виджет отображения цен не нуждается в view_balance.

Отдельные ключи для отдельных задач. Используйте один ключ для вашего бота заказов (create_orders, view_orders, view_balance) и другой ключ для вашей системы мониторинга (view_balance, view_orders). Если ключ мониторинга утечёт, злоумышленник не сможет создавать заказы.

Никакого разрешения на вывод средств на API-ключах. Выводы требуют аутентификацию JWT. Это намеренно. API-ключ, даже с полными разрешениями, не может вывести средства с вашего счёта. Это добавляет слой защиты для операции наивысшего риска.

Пример: минимальный ключ для виджета цен

Общедоступный виджет цен требует только получение цен. Ему вообще не нужна аутентификация, так как эндпоинт цен открыт, но если вы хотите отслеживать использование:

curl -X POST https://merx.exchange/api/v1/keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "website-price-widget",
    "permissions": []
  }'

Ключ с пустым массивом разрешений может получить доступ к открытым эндпоинтам (цены, список провайдеров), позволяя вам отслеживать объём запросов и применять лимиты на запросы к каждому ключу.

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

curl -X POST https://merx.exchange/api/v1/keys \
  -H "Authorization: Bearer $JWT_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "trading-bot-prod",
    "permissions": ["create_orders", "view_orders", "view_balance"]
  }'

Лимиты на запросы

MERX применяет лимиты на запросы для каждой категории эндпоинтов, не на каждый ключ. Все лимиты измеряются в количестве запросов в минуту от одного аутентифицированного источника (API-ключ или JWT-сеанс).

Таблица лимитов на запросы

Data table
Категория эндпоинта	Лимит	Примеры
Данные цен	300/мин	`GET /prices`, `GET /prices/history`
Создание заказов	10/мин	`POST /orders`
Запросы к заказам	60/мин	`GET /orders`, `GET /orders/:id`
Выводы	5/мин	`POST /withdraw`
Данные аккаунта	60/мин	`GET /balance`, `GET /keys`
Управление ключами	10/мин	`POST /keys`, `DELETE /keys/:id`

Заголовки лимитов на запросы

Каждый ответ включает информацию о лимитах на запросы в HTTP-заголовках:

X-RateLimit-Limit: 300
X-RateLimit-Remaining: 287
X-RateLimit-Reset: 1711785660

X-RateLimit-Limit — максимум запросов, разрешённых в текущем окне.
X-RateLimit-Remaining — количество запросов, оставшихся перед достижением лимита.
X-RateLimit-Reset — Unix-временная метка, когда окно сбросится.

Когда вы превысите лимит

Превышение лимита на запросы возвращает HTTP 429 Too Many Requests с заголовком Retry-After, указывающим количество секунд ожидания:

{
  "error": {
    "code": "RATE_LIMIT_EXCEEDED",
    "message": "Rate limit exceeded. Retry after 12 seconds.",
    "details": {
      "limit": 10,
      "window": "1m",
      "retry_after": 12
    }
  }
}

Обработка лимитов в коде

SDK автоматически обрабатывают лимиты на запросы с настраиваемым поведением повторных попыток:

const merx = new MerxClient({
  apiKey: process.env.MERX_API_KEY,
  maxRetries: 3,
  retryOnRateLimit: true, // Автоматически ждать и повторять при 429
});

Для raw HTTP-клиентов реализуйте backoff на основе заголовка Retry-After:

import requests
import time

def merx_request(method, path, **kwargs):
    url = f"https://merx.exchange/api/v1{path}"
    headers = {"X-API-Key": API_KEY}

    for attempt in range(3):
        response = requests.request(method, url, headers=headers, **kwargs)

        if response.status_code == 429:
            retry_after = int(response.headers.get("Retry-After", 10))
            print(f"Rate limited. Waiting {retry_after}s...")
            time.sleep(retry_after)
            continue

        response.raise_for_status()
        return response.json()

    raise Exception("Rate limit retries exhausted")

Лучшие практики безопасности

Сохраняйте ключи в переменных окружения

Никогда не кодируйте API-ключи в исходный код. Используйте переменные окружения или менеджер секретов:

# .env файл (никогда не коммитьте это)
MERX_API_KEY=merx_live_k7x9m2p4q8r1s5t3u7v2w6x0y4z...

// Загрузите из окружения
const merx = new MerxClient({
  apiKey: process.env.MERX_API_KEY,
});

Ротируйте ключи периодически

Создайте новый ключ, обновите ваши сервисы для его использования, затем отозвите старый ключ. MERX поддерживает несколько одновременно активных ключей, поэтому вы можете ротировать без простоя:

Создайте новый ключ с теми же разрешениями.
Развёртывайте новый ключ на ваши сервисы.
Проверьте, что новый ключ работает в production.
Отозвите старый ключ.

Мониторьте использование ключей

Периодически просматривайте список API-ключей вашего аккаунта. Отзывайте ключи, которые больше не используются. Каждый ключ имеет временную метку last_used_at — если ключ не использовался месяцами, это кандидат на отзыв.

Никогда не раскрывайте ключи в клиентском коде

API-ключи никогда не должны появляться в JavaScript, выполняющемся в браузере, в пакетах мобильных приложений или в любом коде, который пользователи могут проверить. Если вам нужно обращаться к MERX с фронтенда, перенаправляйте запросы через ваш backend, который хранит API-ключ на стороне сервера.

Browser -> Your Backend (holds API key) -> MERX API

Используйте отдельные ключи для отдельных окружений

Поддерживайте различные ключи для разработки, staging и production. Если ключ разработки утечёт, это не может повлиять на production. MERX в настоящее время не имеет ключей, ограниченных окружением, но соглашения об именовании помогают:

dev-price-monitor
staging-order-bot
prod-order-bot
prod-balance-alerter

Проверьте подозрения

Если вы подозреваете, что ключ был скомпрометирован, отозвите его немедленно и создайте замену. Проверьте вашу недавнюю историю заказов и выводов на наличие несанкционированной активности. MERX регистрирует всё использование API-ключей с IP-адресами, что может помочь определить источник несанкционированного доступа.

Собираем всё вместе

Полная конфигурация аутентификации для production-системы обычно выглядит так:

Войдите через веб-панель, чтобы получить JWT-сеанс.
Создайте отдельные API-ключи для каждого сервиса: бот заказов, мониторинг, отчётность.
Назначьте минимальные разрешения каждому ключу.
Сохраните ключи в вашем менеджере секретов или переменных окружения.
Реализуйте обработку лимитов на запросы с автоматическим повтором.
Установите ротацию ключей по регулярному расписанию (ежеквартально — разумно).
Мониторьте использование ключей и отзывайте неиспользуемые ключи.

Аутентификация — основа каждой интеграции MERX. Час времени, потраченный на правильную настройку, сэкономит дни отладки и предотвратит инциденты безопасности.

Платформа и панель: merx.exchange
Полная справка API: merx.exchange/docs
JavaScript SDK: github.com/Hovsteder/merx-sdk-js
Python SDK: github.com/Hovsteder/merx-sdk-python

Попробуйте прямо сейчас с AI

Добавьте MERX в Claude Desktop или любой MCP-совместимый клиент — без установки, без API-ключа, требуемого для инструментов только для чтения:

{
  "mcpServers": {
    "merx": {
      "url": "https://merx.exchange/mcp/sse"
    }
  }
}

Спросите вашего AI-агента: "Какова самая дешёвая TRON energy прямо сейчас?" и получите актуальные цены от всех подключённых провайдеров.

Полная документация MCP: merx.exchange/docs/tools/mcp-server