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

EIDEX Merchant API v1 — api для обменника криптовалют в одной интеграции: котировки, создание и отслеживание ордеров, выдача депозитных адресов, вывод средств и вебхуки о событиях. Базовый адрес — https://eidex.io/api/merchant/v1, авторизация по паре заголовков.

Что умеет API

Котировки

Эндпоинт GET /tickers отдаёт курсы по доступным торговым парам в едином формате — отдельное подключение к внешней площадке на вашей стороне не требуется. Котировки и исполнение ордеров идут через подключённую биржу-партнёра, то есть API выступает единой точкой интеграции для расчётов и цен. Один и тот же курс используется и для витрины, и для расчёта заявки, поэтому расхождений между показанной клиенту ценой и ценой обмена не возникает.

Ордера

Полный цикл сделки: POST /order создаёт биржевой ордер (пара, сторона BUY/SELL, тип MARKET/LIMIT), GET /order/{id} возвращает статус, GET /orders — список, POST /order/{id}/cancel отменяет. Логика фронтенда остаётся на вашей стороне.

Адреса, депозиты и вывод

GET /deposit-address?network=<сеть> выдаёт адрес для приёма средств в конкретной сети (параметр network обязателен), GET /deposit-addresses — список выданных адресов. POST /address/reserve закрепляет адрес за вашей заявкой по её идентификатору (nonce), POST /address/release возвращает адрес в пул после закрытия сделки. GET /balances показывает текущие остатки мерчанта, POST /withdraw инициирует вывод. Результат вывода приходит вебхуком withdraw.completed — отдельного REST-метода для опроса статуса вывода сейчас нет.

Вебхуки

GET и POST /webhooks, DELETE /webhooks/{id} управляют подписками на события. Сейчас доставляются два события: deposit.confirmed (поступление подтверждено) и withdraw.completed (вывод исполнен). Событие по исполнению ордеров (order.filled) зарезервировано и будет включено позже, поэтому статусы ордеров пока снимаются опросом GET /order/{id}.

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

Что даёт API-ключ

Ключ выпускается с набором прав, и каждое право открывает свой круг операций. Выдавайте интеграции минимально необходимый набор: ключ без права на вывод не сможет вывести средства, даже если попадёт в чужие руки.

Чтение (право READONLY):

Курсы по всем доступным торговым парам — GET /tickers

Балансы мерчанта по каждому активу: свободный и зарезервированный — GET /balances

Депозитный адрес в нужной сети — GET /deposit-address?network=<сеть>

Список всех выданных депозитных адресов — GET /deposit-addresses

Список ордеров с курсорной пагинацией — GET /orders

Статус конкретного ордера — GET /order/{id}

Торговля (право TRADING):

• Создание ордера: пара, сторона BUY/SELL, тип MARKET/LIMIT — POST /order

• Отмена ордера — POST /order/{id}/cancel

Вывод средств (право WITHDRAW):

• Инициирование вывода на внешний адрес — POST /withdraw. Действуют минимальные суммы и дневные лимиты; результат приходит вебхуком withdraw.completed.

Работа с пулом адресов и подписками (право TRADING; просмотр списка подписок — READONLY):

• Закрепление адреса за вашей заявкой по её идентификатору (nonce), повторный вызов с тем же nonce возвращает тот же адрес — POST /address/reserve

• Возврат адреса в пул после закрытия сделки — POST /address/release

• Создание, просмотр и удаление подписок на события — POST/GET /webhooks, DELETE /webhooks/{id}

Чего ключ не даёт:

• Управлять самими ключами: выпуск и отзыв — только в личном кабинете, не через API

• Менять настройки аккаунта, проходить верификацию, работать с P2P

• Действовать от имени других пользователей — все операции идут от вашего аккаунта мерчанта

Быстрый старт за 3 шага

Шаг 1. Получить ключи. В личном кабинете (Настройки → API-ключи) выпускаются X-API-Key и X-API-Secret. Секрет показывается один раз при создании — сохраните его сразу. Там же выбираются права ключа (READONLY / TRADING / WITHDRAW) и, при необходимости, список разрешённых IP.

Шаг 2. Запросить котировки.

curl -X GET "https://eidex.io/api/merchant/v1/tickers" \
  -H "X-API-Key: <your_api_key>" \
  -H "X-API-Secret: <your_api_secret>"

Шаг 3. Создать ордер. Для POST /order обязателен заголовок Idempotency-Key — он защищает от повторного создания сделки при ретраях. Ключ должен иметь право TRADING.

curl -X POST "https://eidex.io/api/merchant/v1/order" \
  -H "X-API-Key: <your_api_key>" \
  -H "X-API-Secret: <your_api_secret>" \
  -H "Idempotency-Key: <уникальный_id_запроса>" \
  -H "Content-Type: application/json" \
  -d '{"pair":"BTCUSDT","side":"BUY","type":"MARKET","amount":"0.001"}'

Для лимитного ордера добавьте "type":"LIMIT" и "price":"<цена>". Полный состав полей и допустимые значения — в спецификации.

Дальше остаётся подписаться на вебхуки о депозитах и выводах, а статусы ордеров снимать через GET /order/{id}.

Таблица эндпоинтов

Как устроен поток обмена

Типовая сделка на стороне обменника собирается из шести вызовов, и порядок обмена данными между вашим бэкендом и API выглядит так:

1. Клиент выбирает направление обмена — витрина берёт цены из GET /tickers.

2. Ваш бэкенд резервирует адрес под заявку: POST /address/reserve с параметрами network и nonce. Повторный вызов с тем же nonce вернёт тот же адрес, поэтому дубли заявок не ломают логику обмена.

3. Клиент переводит средства на выданный адрес.

4. Приходит вебхук deposit.confirmed — с этого момента поступление считается подтверждённым.

5. Бэкенд создаёт ордер: POST /order с заголовком Idempotency-Key, статус снимается через GET /order/{id}.

6. Выплата клиенту инициируется через POST /withdraw, факт исполнения приходит вебхуком withdraw.completed. После закрытия сделки адрес возвращается в пул через POST /address/release.

Такой сценарий обмена криптовалютами покрывает и разовые заявки, и поток из десятков сделок в час: узкое место обычно не в API, а в скорости подтверждений в самой сети.

Сценарии интеграции

Сайт обменника

Классический вариант: форма расчёта на странице, курс криптовалюты подтягивается из GET /tickers, заявка ведётся вашей CRM. API закрывает ценообразование, исполнение и расчёты, а правила обмена, верификацию клиента и поддержку вы держите у себя.

Телеграм-бот

Тот же контур без сайта: интерфейсом выступает бот, а его бэкенд работает с теми же эндпоинтами. Логика диалога — выбор пары, показ курса, выдача адреса, уведомление о зачислении — ложится на вебхуки, поэтому опрашивать статусы в цикле не нужно. Здесь удобно выпускать отдельный ключ с правами READONLY и TRADING, оставив вывод средств на другом контуре.

White label обменник

Витрина, бренд и клиентская база ваши, расчётный слой — на стороне биржи. Сценарий white label обменника собирается из тех же вызовов и отличается только глубиной кастомизации интерфейса; работа с криптовалютами при этом полностью скрыта от конечного пользователя за вашим брендом.

Лимиты и идемпотентность

Действует ограничение 60 запросов в минуту на один API-ключ — общее на все эндпоинты. Текущий остаток лимита возвращается в заголовках каждого ответа: X-RateLimit-Limit и X-RateLimit-Remaining. При превышении приходит код 429 и заголовок Retry-After с числом секунд до следующего окна.

Для POST /order и POST /withdraw обязателен заголовок Idempotency-Key. Повторный запрос с тем же ключом и тем же телом вернёт сохранённый ответ вместо создания дубля; тот же ключ с другим телом отклоняется. Это делает ретраи безопасными для денежных операций.

На аккаунт доступно до 10 активных API-ключей и до 5 webhook-подписок. Ошибки возвращаются единым JSON вида {"code", "message", "request_id"} — request_id удобно указывать при обращении в поддержку.

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

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

Права ключа ограничивают его возможности: READONLY — чтение, TRADING — создание и отмена ордеров, резерв и освобождение депозитных адресов, управление подписками на вебхуки, WITHDRAW — вывод средств. Выдавайте каждому интеграционному контуру минимально необходимый набор: скомпрометированный ключ без права WITHDRAW не сможет вывести средства.

IP-whitelist настраивается вами при выпуске ключа: в поле указывается список адресов или подсетей в нотации CIDR. Если список не задан, ключ по умолчанию принимается с любого адреса — для ключей с правом WITHDRAW рекомендуем всегда задавать whitelist явно.

Вебхуки подписываются: каждый запрос к вашему обработчику содержит заголовок X-Webhook-Signature с HMAC-SHA256 от тела, вычисленным на секрете подписки (секрет выдаётся один раз при её создании). При недоступности вашего эндпоинта доставка повторяется до 5 раз с нарастающими интервалами. Проверяйте подпись перед обработкой.

Храните секрет на стороне сервера; фронтенд к нему доступа иметь не должен. Порядок работы и ответственность сторон описаны в разделе условия использования.

Как подключиться

Полная спецификация доступна в машиночитаемом виде: https://eidex.io/merchant-openapi.json — файл импортируется в Postman, Insomnia или генератор клиентов. Подключить обменник проще всего по шагам из quickstart-гайда: получить ключи, проверить GET /tickers, собрать первый тестовый ордер.