SafeMatch API & SDK

Полная документация REST API и официальный Python SDK для интеграции с платформой SafeMatch. Все методы для работы с заявками, чеками, апелляциями и WebSocket-уведомлениями.

1. Быстрый старт (SDK)

from safematch import SafeMatch, OrderCreate

# Подключение к основному серверу
client = SafeMatch(api_key="YOUR_API_KEY", secret_key="YOUR_SECRET_KEY")

# Подключение к тестовому серверу (sandbox)
client = SafeMatch(api_key="YOUR_API_KEY", secret_key="YOUR_SECRET_KEY", server="sandbox")

# Создание IN-ордера
order = client.create_order(OrderCreate(
    side="IN",
    fiat_qty=10000,
    min_price=90,
    max_price=95,
))
print(f"Ордер создан: {order.id}, статус: {order.status}")

---

2. Аутентификация

Все запросы к API (кроме /health) требуют аутентификации. Для аутентификации используются три обязательных заголовка:

Формирование подписи

Подпись формируется по следующему алгоритму:

1. Составить строку для подписи: HTTP_МЕТОД + ПУТЬ + TIMESTAMP + ТЕЛО_ЗАПРОСА
   • HTTP_МЕТОД — метод запроса заглавными буквами (POST, GET, DELETE)
   • ПУТЬ — путь запроса (например, /orders)
   • TIMESTAMP — значение заголовка X-Timestamp
   • ТЕЛО_ЗАПРОСА — JSON-тело, сериализованное с отсортированными ключами и без пробелов (разделители: , и :). Для запросов без тела эта часть опускается
2. Вычислить HMAC-SHA256 от полученной строки, используя ваш секретный ключ
3. Результат передать в заголовке X-Signature в hex-формате

Пример (Python):

import hmac
import hashlib
import json
import time

api_key = "ваш-api-key"
secret_key = "ваш-secret-key"

method = "POST"
path = "/orders"
timestamp = str(int(time.time()))

body = {"side": "IN", "min_price": 90.0, "max_price": 95.0,
        "fiat": "RUB", "token": "USDT", "fiat_qty": 10000}
body_str = json.dumps(body, sort_keys=True, separators=(",", ":"))

message = method + path + timestamp + body_str
signature = hmac.new(secret_key.encode(), message.encode(), hashlib.sha256).hexdigest()

headers = {
    "X-API-Key": api_key,
    "X-Timestamp": timestamp,
    "X-Signature": signature,
    "Content-Type": "application/json"
}

Для загрузки файлов (например, чек в формате PDF) подпись формируется аналогично, но тело запроса в подпись не включается — используется только МЕТОД + ПУТЬ + TIMESTAMP.

Python SDK — аутентификация выполняется автоматически. Достаточно передать api_key и secret_key при создании клиента SafeMatch(). Подпись формируется для каждого запроса внутри библиотеки.

---

3. Серверы

REST API серверы

SDK поддерживает переключение между серверами через параметр server:

# Переключение серверов
client_prod = SafeMatch(api_key="...", secret_key="...", server="production")
client_test = SafeMatch(api_key="...", secret_key="...", server="sandbox")

WebSocket серверы

---

4. Заявки

Сводная таблица

---

Создаёт новую заявку на покупку (IN) или продажу (OUT) криптовалюты.

Тело запроса (IN — покупка криптовалюты):

{
  "side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 10000
}

Тело запроса (OUT — продажа криптовалюты):

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

Объект banks[]:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat": "RUB",
  "token": "USDT",
  "fiat_qty": 10000,
  "max_payments": null,
  "banks": null,
  "status": "waiting",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

Python SDK

from safematch import OrderCreate, ClientData, BankDetails

# IN-ордер (покупка крипты)
order = client.create_order(OrderCreate(
    side="IN",
    fiat_qty=10000,
    min_price=90,
    max_price=95,
    fiat="RUB",
    token="USDT",
    client_data=ClientData(name_ru="Иван Иванов"),
))

# OUT-ордер (продажа крипты)
order = client.create_order(OrderCreate(
    side="OUT",
    fiat_qty=50000,
    min_price=90,
    max_price=95,
    max_payments=3,
    banks=[
        BankDetails(
            bank_name="Sberbank",
            recipient_details="2200000000000000",
            recipient_name="Иван Иванов",
            detail_type="CARD",
            priority=1,
        ),
    ],
))

---

Удаляет вашу заявку. Удаление возможно только для заявок в статусе «Ожидание сопоставления».

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

Python SDK

client.delete_order("order-uuid")  # Только в статусе waiting

---

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

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

Python SDK

client.cancel_search("out-order-uuid")

---

Возвращает подробную информацию о заявке. Доступно только участникам сделки (создатель или контрагент).

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "side": "IN",
  "user_side": "IN",
  "min_price": 90.0,
  "max_price": 95.0,
  "fiat_qty": 10000,
  "fiat": "RUB",
  "token": "USDT",
  "max_payments": null,
  "banks": [...],
  "created_at": 1741510800,
  "matched_at": 1741510860,
  "status": "waiting_payment",
  "creator_id": 1,
  "contr_id": 2,
  "rate": 92.5,
  "in_orders_data": null,
  "out_order_id": "out-uuid-...",
  "receipt_data": null,
  "payment_method": null,
  "transfer_time": null,
  "crypto_amount": 108.1,
  "freezeed_crypto": null,
  "fee_collected": 0.0,
  "expected_fiat_qty": null,
  "filled_fiat_qty": null
}

Python SDK

order = client.get_order("order-uuid")
print(f"Статус: {order.status}, крипто: {order.crypto_amount}")

---

Возвращает список ваших заявок с пагинацией, сортировкой и фильтрами.

Параметры (query):

Успешный ответ:

{
  "orders": [
    {
      "id": "a1b2c3d4-...",
      "side": "IN",
      "status": "waiting",
      "fiat_qty": 10000,
      "fiat": "RUB",
      "token": "USDT",
      "created_at": 1741510800,
      ...
    }
  ],
  "total_count": 42,
  "page": 1,
  "page_size": 10,
  "total_pages": 5
}

Python SDK

result = client.get_orders(page=1, page_size=20, side="IN", status="waiting")
for o in result["orders"]:
    print(f"{o['id']} — {o['status']} — {o['fiat_qty']} {o['fiat']}")

---

5. Самосопоставление (Self-Matching)

SafeMatch позволяет площадке сопоставлять собственные IN и OUT заявки между собой. Это полезно, когда площадка выступает и покупателем, и продавцом одновременно.

Как включить

Для самосопоставления обе заявки (IN и OUT) должны быть созданы с полем allow_self_match: true:

# OUT-заявка с разрешённым самосопоставлением
out_order = client.create_order(OrderCreate(
    side="OUT",
    fiat_qty=50000,
    min_price=90,
    max_price=95,
    allow_self_match=True,
    banks=[...],
))

# IN-заявка с разрешённым самосопоставлением
in_order = client.create_order(OrderCreate(
    side="IN",
    fiat_qty=10000,
    min_price=90,
    max_price=95,
    allow_self_match=True,
))

Если хотя бы у одной из заявок allow_self_match = false (по умолчанию), система не будет сопоставлять их друг с другом.

Определение самосопоставления

После сопоставления в данных заявки появляется поле is_self_matched: true (read-only, устанавливается системой автоматически):

{
  "id": "a1b2c3d4-...",
  "allow_self_match": true,
  "is_self_matched": true,
  "status": "waiting_payment",
  ...
}

Особенности поведения

Важно: Self-match диспут — это упрощённый механизм отмены. Поскольку обе стороны принадлежат одной площадке, полноценное разбирательство не требуется.

---

6. Чеки и подтверждение

Загружает PDF-файл чека об оплате для IN-заявки (покупка). После загрузки заявка переходит в статус «Ожидание подтверждения» — продавец должен подтвердить получение средств.

Формат запроса: multipart/form-data

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

Python SDK

# Из файла
client.upload_receipt("in-order-id", "receipt.pdf", payment_method=1)

# Из file-like объекта
with open("receipt.pdf", "rb") as f:
    client.upload_receipt("in-order-id", f, payment_method=1)

---

Создатель OUT-заявки (продавец) подтверждает, что получил фиатный перевод от покупателя. После подтверждения заявка покупателя завершается, криптовалюта зачисляется покупателю.

Параметры:

Успешный ответ:

{
  "id": "a1b2c3d4-...",
  "result": "success"
}

Возможные ошибки:

Python SDK

client.confirm_payment("in-order-id")

---

Создатель OUT-заявки (продавец) не подтверждает получение оплаты по загруженному чеку. Создаётся диспут для разбирательства.

Алиас: /orders/{order_id}/dispute-receipt также поддерживается для обратной совместимости.

Параметры:

Тело запроса:

{
  "reason": "fake_receipt",
  "description": "Оплата не поступила на указанный счёт"
}

Успешный ответ (обычная заявка):

{
  "appeal_id": "appeal-uuid-...",
  "order_id": "out-order-uuid-...",
  "reason": "fake_receipt",
  "status": "waiting_confirmation",
  "created_at": "2026-03-09T12:00:00"
}

Успешный ответ (self-matched заявка):

{
  "appeal_id": "self-match-auto",
  "order_id": "in-order-uuid-...",
  "status": "cancelled",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

Python SDK

from safematch import DisputeCreate

appeal = client.dispute_receipt("in-order-id", DisputeCreate(
    reason="fake_receipt",
    description="Описание проблемы",
))

---

Возвращает PDF-файл чека по его идентификатору. Доступно только участникам сделки.

Параметры:

ID чека можно получить из поля receipt_data в данных заявки.

Ответ: PDF-файл (application/pdf).

Возможные ошибки:

Python SDK

pdf_bytes = client.download_receipt("receipt-id")
with open("saved.pdf", "wb") as f:
    f.write(pdf_bytes)

---

7. Апелляции

Создаёт апелляцию по завершённой заявке. Доступно для обоих участников сделки (создатель IN и создатель OUT). Для self-matched заявок апелляции заблокированы (HTTP 400).

Тело запроса:

{
  "order_id": "a1b2c3d4-...",
  "reason": "appeal",
  "description": "Описание проблемы"
}

Успешный ответ:

{
  "appeal_id": "appeal-uuid-...",
  "order_id": "a1b2c3d4-...",
  "reason": "appeal",
  "status": "completed",
  "created_at": "2026-03-09T12:00:00"
}

Возможные ошибки:

Python SDK

from safematch import AppealCreate

appeal = client.create_appeal(AppealCreate(
    order_id="order-uuid",
    description="Описание проблемы",
))
print(f"Апелляция: {appeal.appeal_id}")

Причина всегда appeal (задаётся автоматически). Указывать не нужно — только order_id и опционально description.

---

8. Аккаунт

Возвращает данные пользователя, привязанного к API-ключу: ID, балансы, комиссии. Приватные данные (пароль, секретный ключ и т.д.) не возвращаются.

Успешный ответ:

{
  "user_id": 35,
  "username": "MyPlatform",
  "working_balance": 1500.00,
  "frozen_balance": 200.00,
  "referral_balance": 12.50,
  "in_fee_rate": 1.0,
  "out_fee_rate": 1.0,
  "role": "Proc_Admin"
}

Python SDK

me = client.get_me()
print(f"User: {me['username']} (ID {me['user_id']})")
print(f"Рабочий: {me['working_balance']} USDT")
print(f"Замороженный: {me['frozen_balance']} USDT")
print(f"Реферальный: {me['referral_balance']} USDT")
print(f"Комиссия IN: {me['in_fee_rate']}%, OUT: {me['out_fee_rate']}%")

---

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

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

URL подключения

wss://ws.safematch.io/ws?api_key={API_KEY}&signature={SIGNATURE}&session_id={SESSION_ID}

Параметры аутентификации

Подключение

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

{
  "type": "connection_established",
  "user_id": 123,
  "session_id": "550e8400-e29b-41d4-a716-446655440000",
  "realm": "main",
  "timestamp": 1710604800
}

Клиентские сообщения

Для поддержания соединения отправляйте ping:

// Отправка
{"type": "ping"}

// Ответ сервера
{"type": "pong", "timestamp": 1710604800}

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

Формат уведомления

Все уведомления приходят в едином формате:

{
  "type": "notification",
  "notification_type": "order_matched",
  "data": {
    "order_id": "550e8400-e29b-41d4-a716-446655440000",
    "side": "IN",
    "status": "waiting_payment",
    "fiat_qty": 10000.0,
    "fiat": "RUB",
    "token": "USDT",
    "banks": [{"bank_name": "Sberbank", "detail_type": "card", "details": "****1234"}],
    "creator_id": 123,
    "contr_id": 456,
    "min_price": 90.0,
    "max_price": 100.0,
    "crypto_amount": 100.0,
    "created_at": 1710604000,
    "last_update_time": 1710604800
  },
  "timestamp": 1710604800
}

Лимиты и keepalive

• Максимум 2 соединения на пользователя одновременно
• Клиент должен отправлять ping каждые 30 секунд
• Соединение закрывается через 60 секунд без ping

Python SDK

from safematch import SafeMatchWS

ws = SafeMatchWS(api_key="YOUR_KEY", secret_key="YOUR_SECRET")

# Sandbox
ws = SafeMatchWS(api_key="YOUR_KEY", secret_key="YOUR_SECRET", server="sandbox")

@ws.on("order_matched")
def on_matched(data):
    print(f"Ордер сматчен: {data['order_id']}")
    print(f"Банк: {data.get('banks', [{}])[0].get('bank_name')}")

@ws.on("order_completed")
def on_completed(data):
    print(f"Ордер завершён: {data['order_id']}")

@ws.on("order_cancelled")
def on_cancelled(data):
    print(f"Ордер отменён: {data['order_id']}")

# Блокирующее подключение (Ctrl+C для остановки)
ws.connect()

# Или в фоновом потоке
thread = ws.connect_in_background()

Async-режим

import asyncio
from safematch import SafeMatchWS

async def main():
    ws = SafeMatchWS(api_key="...", secret_key="...", server="sandbox")

    @ws.on("order_matched")
    def handler(data):
        print(data)

    await ws.connect_async()

asyncio.run(main())

---

10. Статусы заявок

---

11. Коды ответов и ошибки

HTTP-коды ответов

Исключения SDK

Пример обработки ошибок (SDK)

from safematch import SafeMatch
from safematch.exceptions import (
    SafeMatchError,
    AuthError,
    NotFoundError,
    ValidationError,
    InsufficientBalanceError,
    RateLimitError,
    MaintenanceError,
)

client = SafeMatch(api_key="...", secret_key="...")

try:
    order = client.get_order("non-existent-id")
except NotFoundError:
    print("Ордер не найден")
except AuthError:
    print("Ошибка авторизации — проверьте ключи")
except InsufficientBalanceError:
    print("Недостаточно средств")
except RateLimitError:
    print("Слишком много запросов — подождите")
except MaintenanceError:
    print("Сервер на обслуживании")
except SafeMatchError as e:
    print(f"Ошибка {e.status_code}: {e.detail}")

---

12. Справочник методов SDK