Как создать обменный ордер через API v2 - marketexchange

Создание обменного ордера через API v2 требует не только отправить JSON на сервер. Сначала нужно выбрать доступную пару и сеть, проверить реквизиты получателя, собрать тело запроса без самовольных полей, вычислить HMAC-SHA256 по правилам MarketExchange и сохранить исходный результат. Ошибка в одном байте, подписи или адресе способна привести к отказу, задержке либо созданию операции с неверными параметрами.

Быстрый ответ: получите `publicKey` и `secretKey`, проверьте пару через актуальные методы API v2, сформируйте JSON заявки по документации, подпишите строго канонические данные с помощью HMAC-SHA256 и отправьте запрос по HTTPS на базовый адрес `/api-v2/`. После ответа сохраните идентификатор заявки и не повторяйте запрос вслепую после тайм-аута.

Документация API уточняет обязательные поля, путь метода, заголовки и правила подписи. Перед реализацией откройте актуальную документацию API v2 и описание методов orders. Это единственный источник точного синтаксиса.

Подготовьте ключи и серверную среду, не передавайте секрет клиенту

Секретный ключ только на сервере

Для авторизованного запроса используются пара ключей `publicKey` и `secretKey`. Публичная часть нужна серверу для определения клиента, а секретная участвует в создании подписи. Секретный ключ нельзя помещать в браузерный код, мобильное приложение, открытый репозиторий, сообщение поддержки или журналы с полным содержимым переменных.

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

До написания обработчика проверьте следующие условия:

• сервер может устанавливать исходящее HTTPS-соединение;
• часы и настройки кодировки окружения не меняют данные запроса;
• тело запроса сохраняется до вычисления подписи и не пересобирается автоматически позже;
• ответ сервера доступен обработчику в исходном виде, включая код результата и текст ошибки;
• секретный ключ не попадает в исключения, трассировки и диагностические сообщения.

Не начинайте с клиентской формы, которая отправляет секрет в браузер. Клиент передаёт серверу только разрешённые параметры. Сервер проверяет их, подписывает запрос и сам обращается к API v2.

Проверьте пару и инструмент, не фиксируйте параметры по памяти

Пара и сеть из актуального API

В API v2 заявлены группы методов `instruments`, `orders` и `pairs`. Используйте их назначение последовательно. Сначала определите, какие инструменты доступны, затем убедитесь, что нужная пара поддерживается, и только после этого готовьте данные для создания заявки. Название актива и название сети не всегда являются взаимозаменяемыми значениями.

Проверяйте отдельно актив, который отдаёт клиент, актив, который он получает, сеть отправки и сеть получения. Для некоторых направлений важны дополнительные реквизиты: MEMO, Destination Tag или Payment ID. Их наличие и формат должны следовать текущей схеме API и условиям конкретного направления.

Соберите внутреннюю модель заявки до сериализации JSON:

1. определите валюту и сеть, из которой будет отправлен актив;
2. определите валюту, сеть и адрес получателя;
3. проверьте доступность пары и минимальные требования в актуальном ответе API;
4. уточните, нужен ли дополнительный реквизит для адреса получателя;
5. выберите режим курса и зафиксируйте показанный платформой курс до отправки;
6. сохраните сумму, направление и версию схемы, с которой работает интеграция;
7. передайте в создание ордера только те поля, которые указаны в документации метода.

Не копируйте имена параметров из API v1, MEXC, OKX или другого сервиса. Даже привычные слова вроде `amount`, `address` или `network` могут иметь иной формат, обязательность или место в структуре. Если документация не подтверждает поле, не добавляйте его по догадке.

Соберите JSON заявки, не меняйте его после сериализации

Финальный JSON до подписи не трогать

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

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

Курс также является частью подготовки заявки. Режим Fixed означает фиксированный курс на период, который указан платформой. Если средства придут после доступного окна, с неверной суммой, по неверной сети или несколькими переводами, результат может быть пересчитан по условиям сервиса. Режим Floating означает плавающий курс: итог зависит от момента, когда поставщик ликвидности получает криптовалюту, поэтому значение до отправки не следует считать бессрочной гарантией.

Сохраните claimed rate, то есть курс, который платформа показала для данной заявки до отправки. Сохраняйте его вместе со временем показа, режимом курса, суммой и техническим идентификатором операции. Не придумывайте имя поля API для этого значения и не подменяйте сохранённую котировку текущим курсом при разборе результата.

Подпишите запрос HMAC, не меняйте байты после подписи

HMAC-SHA256 подтверждает, что запрос собрал владелец secretKey. Канонические данные, заголовки и HTTP-метод берите только из актуальной документации API v2. Не копируйте схему подписи с MEXC, OKX или API v1.

1. Зафиксируйте финальное JSON-тело после сериализации. Это тот набор байтов, который уйдёт на сервер.
2. Соберите канонические данные в порядке из актуальной документации. Не меняйте кодировку и разделители по своему вкусу.
3. Вычислите HMAC-SHA256 с secretKey и приложите подпись вместе с publicKey так, как требует документация.
4. Отправьте HTTPS-запрос без повторной сериализации JSON и без правки заголовков после подписи.
5. При ошибке подписи сравните тело, канонические данные, ключи и URL. Не чините отказ случайными пробелами.

Проверьте тестовый ордер и ответ, не повторяйте запрос вслепую

После отправки проверьте HTTP-код, структуру JSON и бизнес-статус. Успешный транспортный ответ сам по себе не означает, что ордер принят. Сохраните исходный ответ, время запроса и безопасный идентификатор попытки, чтобы повторно сопоставить операцию без нового создания заявки.

Что проверить	Зачем это нужно
Идентификатор ордера	Связать ответ с внутренней записью
Статус операции	Понять, требуется ли ожидание
Сумму и сеть	Исключить ошибку реквизитов
Код и текст ошибки	Корректно обработать отказ

Перед показом результата клиенту сопоставьте ответ с исходной заявкой. Не сообщайте об успешном обмене только потому, что запрос завершился без сетевой ошибки.

• ключи относятся к нужной среде и не попали в клиент;
• пара, сеть и реквизиты совпадают с проверенной моделью заявки;
• JSON-тело и HMAC собраны по актуальной документации;
• после тайм-аута статус проверен, повтор вслепую запрещён.

Частые вопросы

Какие ключи нужны для создания ордера через API v2?

Используйте `publicKey` и `secretKey`. Разместите их на сервере, ограничьте доступ к секрету и не передавайте его в браузер, приложение или журналы. Перед рабочим запуском проверьте, что ключ относится к нужной среде и разрешённому сценарию.

Как подписать запрос к API v2?

Соберите финальное тело и канонические данные по актуальной документации, затем вычислите HMAC-SHA256 с помощью `secretKey`. После подписи не меняйте JSON, порядок байтов, путь, кодировку или значения заголовков, которые входят в правила авторизации.

Куда отправлять запрос создания обменного ордера?

Используйте базовый адрес `/api-v2/` и точный путь метода из текущей документации API v2. Не переносите endpoint из API v1, MEXC или другой криптоплатформы. HTTP-метод и заголовки также сверяйте с документацией.

Какие параметры нужны в заявке?

Сначала получите актуальные сведения о доступных инструментах и парах, затем заполните обязательные поля метода `orders`. Проверьте сумму, активы, сети, адрес и дополнительные реквизиты. Не придумывайте названия полей и не смешивайте форматы разных версий API.

Что делать при ошибке подписи?

Сравните `publicKey`, секретный ключ, финальное JSON-тело, каноническую строку, порядок частей, кодировку, URL и заголовки. Убедитесь, что HTTP-клиент не сериализует объект заново после вычисления подписи. Не публикуйте секрет при диагностике.

Можно ли повторить запрос после тайм-аута?

Сначала проверьте, не создан ли ордер предусмотренным документацией способом. Если результат неизвестен, сохраните данные попытки и напишите в официальную поддержку. Повторяйте запрос только после подтверждения, что первая операция не принята, иначе можно создать дубликат.

Нужно ли учитывать AML и проверку реквизитов?

Да. Перед отправкой проверьте адрес, сеть, MEMO, Destination Tag или Payment ID и предупредите клиента о возможной AML/KYC-проверке. Автоматизация должна уметь остановить заявку на дополнительной проверке и не обходить её изменением параметров.