SafeMatch — Документация

1. Введение

Что такое SafeMatch

SafeMatch — P2P-платформа для обмена криптовалюты на фиат по модели эскроу. Платформа соединяет площадки, которым нужно пополнение (приём фиата и получение крипты), с площадками, которым нужен вывод (отдача крипты и получение фиата). SafeMatch выступает гарантом сделки: крипта замораживается на платформе до подтверждения оплаты, фиат переводится напрямую между сторонами.

Для кого

SafeMatch создан для бизнес-клиентов — легальных онлайн-площадок (казино, платёжные сервисы, биржи), которым нужно:

• принимать фиатные платежи от клиентов и конвертировать их в крипту;
• выводить криптовалюту клиентам, получая фиат.

Платформа работает по модели B2B: вы интегрируетесь через API, публикуете заявки от имени своих клиентов, а SafeMatch находит встречную сторону и обеспечивает безопасность сделки.

Как это работает (кратко)

1. Ваша площадка публикует заявку (пополнение или вывод) через API.
2. SafeMatch автоматически находит встречную заявку с подходящей суммой и курсом.
3. Стороны получают реквизиты друг друга. Покупатель переводит фиат и загружает чек.
4. Продавец подтверждает получение денег — крипта зачисляется покупателю.

Весь процесс занимает от нескольких минут до нескольких часов в зависимости от наличия встречных заявок.

2. Начало работы

Подключение площадки

Для начала работы с SafeMatch:

1. Свяжитесь с нами — напишите в Telegram: @Kos_Change
2. Предоставьте информацию о вашей площадке для верификации
3. Получите учётные данные:
   • API-ключ — для идентификации вашей площадки
   • Секретный ключ — для подписи запросов (HMAC-SHA256)
4. Настройте интеграцию — подключите API согласно руководству по интеграции

Что нужно для интеграции

• Возможность отправлять HTTP-запросы с вашего сервера
• Реализация подписи запросов (HMAC-SHA256)
• Хранилище для API-ключа и секретного ключа (не в коде, а в защищённых переменных окружения)
• Обработка WebSocket-уведомлений для получения событий в реальном времени

Безопасность

• Все запросы подписываются с помощью HMAC-SHA256 — никто не сможет подделать запрос от вашего имени.
• Секретный ключ никогда не передаётся по сети — он используется только для формирования подписи на вашей стороне.
• Храните секретный ключ в надёжном месте. В случае компрометации немедленно свяжитесь с @Kos_Change для перевыпуска.

3. Типы заявок

В SafeMatch существует два типа заявок:

IN-заявка (пополнение)

Сценарий: вашей площадке нужна криптовалюта, клиент готов заплатить фиат.

• Вы публикуете заявку с суммой в фиате и желаемым диапазоном курса.
• SafeMatch находит продавца, который готов отдать крипту за эту сумму.
• Ваш клиент переводит фиат на реквизиты продавца.
• После подтверждения оплаты крипта зачисляется на ваш баланс.

OUT-заявка (вывод)

Сценарий: площадка отдаёт криптовалюту, клиент хочет получить фиат.

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

Ключевое различие

4. Создание заявки

Параметры заявки

При создании заявки необходимо указать:

Пример IN-заявки

Площадке нужно получить USDT на сумму 100 000 RUB по курсу от 95 до 105 RUB/USDT:

{
  "side": "IN",
  "min_price": 95.0,
  "max_price": 105.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 100000
}

Пример OUT-заявки

Площадка хочет продать крипту и получить фиат, принимая до 3 платежей:

{
  "side": "OUT",
  "min_price": 95.0,
  "max_price": 105.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 100000,
  "max_payments": 3,
  "banks": [
    {
      "bank_name": "Сбербанк",
      "recipient_details": "2200 0000 0000 0000",
      "recipient_name": "Иван Иванов",
      "detail_type": "CARD",
      "priority": 1
    }
  ]
}

Что проверяется при создании

• Разрешена ли торговля для вашей площадки
• Не превышены ли лимиты по апелляциям и отменам
• Достаточно ли средств:
  • Для IN: на балансе должно хватить для оплаты будущей комиссии
  • Для OUT: на балансе должна быть криптовалюта на указанную сумму

Важно: при создании заявки средства не списываются — система только проверяет их наличие. Резервирование и списание происходят позже.

Реквизиты для OUT-заявки

При создании OUT вы указываете реквизиты, на которые покупатель переведёт фиат:

Можно указать несколько комплектов реквизитов — покупатель выберет наиболее подходящий.

5. Процесс мэтчинга

Основные этапы сделки

Как система находит пару

После создания заявки SafeMatch автоматически ищет подходящую встречную заявку. Для сопоставления должны совпасть три условия:

1. Пересечение курсов — диапазоны курсов покупателя и продавца должны пересекаться.
2. Точная сумма — сумма одной или нескольких IN-заявок должна точно совпадать с суммой OUT-заявки.
3. Лимит платежей — количество IN-заявок не превышает max_payments, указанный в OUT.

Как определяется курс

Курс сделки рассчитывается как среднее от пересечения диапазонов:

Что происходит при матче

• Покупатель (IN): получает реквизиты продавца для перевода фиата. Баланс не меняется.
• Продавец (OUT): криптовалюта переводится из доступного баланса в зарезервированные средства (замораживается).

Один OUT — несколько IN

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

Время ожидания

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

6. Жизненный цикл заявок

IN-заявка (покупка крипты)

OUT-заявка (продажа крипты)

Ветвления и исходы

На каждом шаге заявка может пойти по позитивному или негативному пути.

7. Оплата и чек

После сопоставления

Когда система находит пару, покупатель получает реквизиты продавца и должен:

1. Перевести фиат по указанным реквизитам (карта или телефон).
2. Загрузить чек — подтверждение перевода в формате PDF.

Загрузка чека

• Формат: только PDF.
• Способ: загрузка файла через API (multipart/form-data).
• При загрузке указывается приоритет выбранного банка из реквизитов продавца.

Таймаут на загрузку чека

После сопоставления у покупателя есть 20 минут на загрузку чека.

Что происходит при отмене по таймауту

• IN-заявка переходит в статус «отменена».
• Зарезервированная крипта возвращается продавцу в доступный баланс.
• OUT-заявка переходит в режим поиска замены.

8. Подтверждение и завершение

Подтверждение оплаты

После загрузки чека продавец (создатель OUT) проверяет поступление денег и принимает решение:

• Подтвердить — деньги получены, сделка завершается.
• Оспорить — деньги не поступили, создаётся апелляция.

Что происходит при подтверждении

В момент подтверждения оплаты выполняются все финансовые операции:

1. Комиссия покупателя — списывается с доступного баланса покупателя.
2. Перевод крипты — из зарезервированных средств продавца в доступный баланс покупателя.
3. Комиссия продавца — списывается с доступного баланса продавца.
4. Реферальные выплаты — начисляются рефереру (если площадка была приведена партнёром).

Пример

Сделка на 100 000 RUB по курсу 100 RUB/USDT (1 000 USDT):

Итого покупатель получил: 1 000 USDT, заплатил 20 USDT комиссии.
Продавец отдал: 1 000 USDT, заплатил 15 USDT комиссии.

Движение баланса при подтверждении (водопад)

Пошаговое движение средств при подтверждении оплаты одной заявки IN на 50 000 RUB (курс 100, криптовалюта = 500 USDT).

Завершение OUT-заявки

OUT-заявка завершается, когда все привязанные IN-заявки завершены или отменены. Если после завершения у продавца остались зарезервированные средства (например, часть IN была отменена) — остаток автоматически возвращается в доступный баланс.

9. Балансы и резервирование

Важно: зарезервированные средства нельзя использовать для новых заявок и операций.

Когда меняется баланс

Резервирование средств (водопад)

Хронология всех операций с зарезервированными средствами продавца от начала до конца.

10. Комиссии и реферальная программа

Как рассчитывается комиссия

Процент комиссии назначается индивидуально для каждой площадки при подключении. Комиссия списывается только при подтверждении оплаты, а не при создании заявки.

Сумма крипты = сумма в фиате / согласованный курс
Комиссия = сумма крипты * процент комиссии

Пример расчёта

Условия: сделка на 100 000 RUB, курс 100 RUB/USDT, комиссия покупателя 2%, комиссия продавца 1.5%.

Когда списывается

• Не при создании заявки (только проверка достаточности средств).
• Не при сопоставлении.
• Только при подтверждении оплаты продавцом.

Если сделка отменена (таймаут, отклонение чека), комиссия не списывается — ни с покупателя, ни с продавца.

Реферальная программа

Как делится комиссия

Условия для реферальной выплаты

Примеры с разными ставками

Как стать реферером

Свяжитесь с @Kos_Change в Telegram для обсуждения условий партнёрской программы.

11. Отмена и замена

Удаление заявки

Вы можете удалить свою заявку, пока она не сопоставлена (статус «ожидание сопоставления»). После сопоставления удаление невозможно.

При удалении OUT-заявки зарезервированные средства (если были) возвращаются в доступный баланс.

Когда IN-заявка отменяется

Поиск замены (для OUT)

Если один из IN-заявок по вашему OUT был отменён, система автоматически переходит в режим поиска замены:

1. OUT-заявка получает статус «поиск замены».
2. Система ищет новую IN-заявку на недостающую сумму.
3. При нахождении замены — дополнительное резервирование крипты и продолжение сделки.

Отмена поиска замены

Если вы не хотите ждать замену, можно отменить поиск. В этом случае:

• OUT-заявка завершится по тем IN, которые уже подтверждены.
• Неиспользованные зарезервированные средства вернутся в доступный баланс.

12. Апелляции

Когда можно создать апелляцию

Причины апелляций

Для покупателя (IN):

Для продавца (OUT):

Как проходит апелляция

1. Подача — вы указываете причину и описание проблемы.
2. Рассмотрение — администратор SafeMatch изучает материалы (чеки, данные сделки).
3. Решение — одно из трёх:
   • В вашу пользу — корректировка балансов.
   • В пользу контрагента — апелляция отклонена.
   • Нейтральное решение — без изменений.
4. Вы также можете отозвать свою апелляцию до решения.

Пока идёт апелляция, связанные заявки не могут быть отменены по таймауту или удалены.

13. Таймауты

После сопоставления заявки у покупателя есть 20 минут на загрузку чека.

При отмене IN-заявки по таймауту:

• Зарезервированная крипта возвращается в доступный баланс продавца
• OUT-заявка переходит в режим поиска замены

14. WebSocket-уведомления

SafeMatch отправляет уведомления о событиях в реальном времени через WebSocket. Это позволяет вашей системе моментально реагировать на изменения без постоянного опроса API.

Типы уведомлений

Содержание уведомления

Каждое уведомление содержит актуальные данные по заявке: текущий статус, реквизиты, курс, суммы и другие параметры.

Рекомендации

• Подключайтесь к WebSocket сразу после получения ключей — это самый быстрый способ узнавать о событиях.
• Обрабатывайте order_matched для оперативной реакции на сопоставление.
• URL для подключения: wss://ws.safematch.io. Детали аутентификации — в API-документации.

15. Полный пример сделки

Максимально долгий путь: создание → сопоставление → частичное подтверждение → таймаут → поиск замены → дополнение → чек → оспаривание → апелляция → решение → подтверждение → завершение.

16. Частые сценарии

Сценарий 1: Простая покупка крипты

Условия: Площадка A хочет получить USDT за 50 000 RUB. Комиссия A — 2%.

1. Площадка A создаёт IN-заявку: 50 000 RUB, курс 95–105 RUB/USDT.
2. SafeMatch находит OUT-заявку Площадки B на ту же сумму. Курс — 100 RUB/USDT.
3. A получает реквизиты B. Клиент A переводит 50 000 RUB на карту B.
4. A загружает чек (PDF).
5. B подтверждает получение денег.
6. Результат:
   • A получает: 500 USDT (50 000 ÷ 100)
   • A платит комиссию: 500 × 2% = 10 USDT
   • Итого на балансе A: +490 USDT

Сценарий 2: Продажа крипты (OUT с несколькими IN)

Условия: Площадка B создаёт OUT на 200 000 RUB (max_payments = 3). Баланс B — 5 000 USDT. Комиссия B — 1.5%.

1. B создаёт OUT-заявку. Курс 95–105 RUB/USDT.
2. SafeMatch находит два IN: площадка C (120 000 RUB) и площадка D (80 000 RUB). Курс — 100.
3. У B замораживается: 120 000 ÷ 100 + 80 000 ÷ 100 = 2 000 USDT.
   • Доступный баланс B: 5 000 → 3 000. Зарезервировано: 2 000.
4. C переводит 120 000 RUB, загружает чек. B подтверждает.
   • Комиссия B: 1 200 × 1.5% = 18 USDT. C получает 1 200 USDT (минус своя комиссия).
   • Зарезервировано у B: 2 000 → 800.
5. D переводит 80 000 RUB, загружает чек. B подтверждает.
   • Комиссия B: 800 × 1.5% = 12 USDT. D получает 800 USDT (минус своя комиссия).
   • Зарезервировано: 800 → 0.
6. OUT завершён. Итого B отдала 2 000 USDT, заплатила 30 USDT комиссий, получила 200 000 RUB на карту.

Сценарий 3: Таймаут и поиск замены

Условия: OUT Площадки B на 100 000 RUB. Найден один IN — Площадка A (100 000 RUB). Курс 100.

1. Матч: у B замораживается 1 000 USDT.
2. A не загружает чек в течение 20 минут — таймаут.
3. IN A отменён. Крипта (1 000 USDT) возвращается B в доступный баланс.
4. OUT B переходит в «поиск замены».
5. SafeMatch находит новую IN-заявку — Площадка E (100 000 RUB). Матч.
6. У B снова замораживается 1 000 USDT.
7. E загружает чек, B подтверждает — сделка завершена.

Сценарий 4: Апелляция после завершения

1. Сделка между A (IN) и B (OUT) завершена: A получила 500 USDT, B получила 50 000 RUB.
2. A обнаруживает, что зачислена неверная сумма, и создаёт апелляцию (причина: «неверная сумма»).
3. Администратор рассматривает материалы.
4. Решение в пользу A — производится корректировка баланса.

Сценарий 5: Частичное выполнение OUT с отменой поиска

Условия: OUT Площадки B на 150 000 RUB (max_payments = 3). Курс 100.

1. Найдены два IN: A (100 000 RUB) и C (50 000 RUB). Заморожено: 1 500 USDT.
2. A загружает чек, B подтверждает — IN A завершён (1 000 USDT переведены A).
3. C не загружает чек — таймаут. IN C отменён. Крипта (500 USDT) возвращена B.
4. OUT переходит в «поиск замены» на 50 000 RUB.
5. B решает не ждать замену и отменяет поиск.
6. OUT завершается по тем IN, которые уже подтверждены (только A).
7. Итог: B отдала 1 000 USDT (вместо 1 500), получила 100 000 RUB (вместо 150 000).

17. Риски и решения

18. Контакты

По всем вопросам, подключению и партнёрской программе — @Kos_Change в Telegram.

Техническая документация по API: API & SDK