Partner Exchange API

1. Обзор

Partner Exchange API позволяет проводить обмены криптовалют из вашего приложения обычными HTTP-запросами. Вы отправляете JSON — API возвращает курс, депозитный адрес и статус обмена. Этот раздел объясняет общую схему; дальше каждый шаг разобран отдельно.

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

Любой обмен проходит по одной и той же схеме из четырёх шагов:

1. Каталог (GET /assets). Вы узнаёте, какие валюты доступны и в каких пределах можно менять. Из каталога берутся короткие коды валют — usdt, btc, eth, xmr и т.д.
2. Котировка (POST /quotes). Вы спрашиваете: «сколько получит клиент, если отправит 20 USDT в BTC?» API отвечает курсом и точными суммами. Котировка ни к чему не обязывает и действует 2 минуты.
3. Создание обмена (POST /exchanges). Вы подтверждаете котировку — API создаёт заявку и возвращает депозитный адрес, на который клиент должен перевести средства.
4. Статус (GET /exchanges/{quote_id}). Вы периодически опрашиваете API и узнаёте, дошёл ли депозит и отправлены ли средства клиенту.

Что нужно для начала работы

1. Аккаунт в кабинете партнёра.
2. Одобренная заявка на доступ к API (подаётся в кабинете, рассматривается администратором).
3. API-ключ вида spx_… — выпускается в кабинете после одобрения. Ключ показывается только один раз при выпуске или перевыпуске: сразу сохраните его в надёжном месте.

Методы

Формат данных

• Все запросы и ответы — JSON в кодировке UTF-8.
• Все денежные суммы передаются строками: "20", "0.000312". Разделитель дробной части — точка. Строки используются намеренно: числа с плавающей точкой теряют точность на криптовалютных суммах.
• Даты — в формате ISO-8601 с часовым поясом, например 2026-07-27T13:02:00+00:00.

Заголовки каждого запроса

X-API-Key: spx_ваш_ключ
Content-Type: application/json   (только для POST)
Accept: application/json

Ключевые правила

• Котировка действует 2 минуты (поле expires_at) — создать обмен нужно до истечения этого срока.
• Не более 1 запроса с одного IP-адреса раз в 7 секунд по всем методам; при превышении — HTTP 429 (подробнее в разделе «Ошибки и лимиты»).
• Повторный вызов создания обмена с теми же параметрами безопасен: дубль не создастся, вернётся тот же обмен.

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

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

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_ваш_ключ
Accept: application/json

Где взять ключ

Кабинет партнёра → вкладка «API» → «Выпустить ключ». Ключ начинается с spx_ и показывается один раз. При перевыпуске старый ключ немедленно перестаёт действовать.

Ошибки аутентификации

3. Каталог валют — GET /assets

Справочник доступных валют и лимитов на сумму отправки. С него начинается интеграция: отсюда берутся коды валют для котировок и границы допустимых сумм. Успешный ответ — HTTP 200.

API принимает только короткие коды из поля code этого каталога (usdt, btc, eth, xmr и т.д.). Внутренние идентификаторы блокчейнов передавать нельзя. Каталог меняется редко — его можно кешировать на своей стороне на 5–10 минут.

Пример запроса

GET https://snapex.pro/api/v1/partner/assets
X-API-Key: spx_ваш_ключ
Accept: application/json

Пример ответа

{
  "assets": [
    {
      "code": "usdt",
      "network": "TRON",
      "symbol": "USDT",
      "name": "USDT TRON",
      "min_amount": "10",
      "max_amount": "5000",
      "min_usd": "10",
      "max_usd": "5000"
    },
    {
      "code": "btc",
      "network": "Bitcoin",
      "symbol": "BTC",
      "name": "BTC",
      "min_amount": "0.000085",
      "max_amount": "0.0425",
      "min_usd": "10",
      "max_usd": "5000"
    }
  ]
}

Поля ответа

Лимиты в USD по типу маршрута

Лимиты зависят от того, участвует ли в обмене Monero (XMR). Проверяется сумма отправки клиента в долларовом эквиваленте.

Актуальный каталог

Таблица ниже — те же данные, что возвращает GET /assets, для быстрой сверки.

4. Котировка — POST /quotes

Рассчитывает курс и точные суммы обмена. Ничего не создаёт и ни к чему не обязывает: депозитный адрес не выделяется, средства не резервируются. Успешный ответ — HTTP 201. Котировка действует 2 минуты.

Два режима: side=send и side=receive

Параметр side определяет, какая из двух сумм фиксируется:
side=send — «клиент отправляет ровно X, сколько он получит?» Сумма amount указывается в валюте отправки (from).
side=receive — «клиент хочет получить ровно Y, сколько ему нужно отправить?» Сумма amount указывается в валюте получения (to).

Передавайте либо amount, либо amount_usd — что-то одно. Оба сразу — ошибка 422.

Пример запроса

POST https://snapex.pro/api/v1/partner/quotes
Content-Type: application/json
X-API-Key: spx_ваш_ключ

{
  "from_asset_id": "usdt",
  "to_asset_id": "btc",
  "side": "send",
  "amount": "20",
  "recipient_address": "bc1qexampleaddress"
}

Параметры запроса

Пример ответа

{
  "quote_id": "pq_abc123",
  "status": "quoted",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00"
}

Поля ответа

5. Создание обмена — POST /exchanges

Превращает котировку в реальный обмен: создаётся заявка и возвращается депозитный адрес для перевода клиента. Вызывайте до истечения котировки (2 минуты). Успешный ответ — HTTP 201.

Пример запроса

POST https://snapex.pro/api/v1/partner/exchanges
Content-Type: application/json
X-API-Key: spx_ваш_ключ

{
  "quote_id": "pq_abc123",
  "recipient_address": "bc1qexampleaddress"
}

Параметры запроса

Что происходит при вызове

1. API находит вашу котировку и проверяет, что она не истекла.
2. Курс перепроверяется по рынку. Если за прошедшее время он ухудшился более чем на 2% относительно котировки — обмен не создаётся, возвращается 422 (просто запросите новую котировку).
3. Создаётся заявка и выделяется депозитный адрес.
4. В ответе приходит блок deposit — адрес и сумма, которую клиент должен перевести.

Пример ответа

{
  "quote_id": "pq_abc123",
  "status": "awaiting_deposit",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "awaiting_deposit",
    "recipient_address": "bc1qexampleaddress"
  }
}

Новые поля по сравнению с котировкой

Повторные вызовы (идемпотентность)

Если соединение оборвалось и вы не получили ответ — просто повторите запрос с теми же quote_id и recipient_address. Дубль не создастся: API вернёт уже существующий обмен. Изменить recipient_address после создания нельзя — при попытке вернётся 422.

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

• 409 quote_expired — котировка истекла (прошло больше 2 минут). Запросите новую через POST /quotes.
• 422 validation_error — невалидные параметры; попытка изменить recipient_address при повторе; либо курс сдвинулся более чем на 2% — запросите новую котировку.
• 404 not_found — quote_id не существует или принадлежит другому партнёру.
• 503 upstream_unavailable — временный сбой у поставщика ликвидности. Повторите позже с той же котировкой (если не истекла) или новой.

6. Статус — GET /exchanges/{quote_id}

Возвращает текущее состояние котировки или обмена. Формат ответа полностью совпадает с ответом создания обмена. Успешный ответ — HTTP 200. Опрашивайте не чаще раза в 7 секунд.

Пример запроса

GET https://snapex.pro/api/v1/partner/exchanges/pq_abc123
X-API-Key: spx_ваш_ключ
Accept: application/json

Значения поля status

Финальные статусы: completed, error, cancelled, expired. После них состояние не меняется — дальнейший опрос не нужен.

При status=completed в блоке exchange может появиться поле partner_api_earning_usd — ваш заработок по этой сделке в долларах.

Пример ответа

{
  "quote_id": "pq_abc123",
  "status": "completed",
  "side": "send",
  "from_symbol": "USDT",
  "to_symbol": "BTC",
  "from_network": "TRON",
  "to_network": "Bitcoin",
  "request_amount": "20",
  "send_amount": "20",
  "receive_amount": "0.000312",
  "amount_in_usd": "20",
  "amount_out_usd": "19.85",
  "expires_at": "2026-07-27T13:02:00+00:00",
  "deposit": {
    "asset": "USDT",
    "amount": "20",
    "address": "TXyz…",
    "amount_usd": "20"
  },
  "exchange": {
    "public_id": "ex_…",
    "status": "completed",
    "recipient_address": "bc1qexampleaddress",
    "partner_api_earning_usd": "0.20"
  }
}

7. Ошибки и лимиты

Все ошибки возвращаются в едином JSON-формате. Код HTTP-ответа дублирует смысл поля error — можно ориентироваться на любой из них.

{
  "ok": false,
  "error": "validation_error",
  "message": "Человекочитаемое пояснение на английском"
}

Справочник ошибок

Лимиты частоты запросов

8. Пример: обмен от начала до конца

Полный сценарий: клиент отдаёт 20 USDT (сеть TRON) и получает BTC на свой биткоин-адрес. Замените YOUR_KEY на ваш API-ключ.

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

curl -sS -X POST 'https://snapex.pro/api/v1/partner/quotes' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample"
  }'

В ответе придёт quote_id (pq_…) и суммы. Покажите клиенту receive_amount — столько BTC он получит. У вас 2 минуты на следующий шаг.

Шаг 2. Создать обмен

curl -sS -X POST 'https://snapex.pro/api/v1/partner/exchanges' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Content-Type: application/json' \
  -H 'Accept: application/json' \
  -d '{
    "quote_id": "pq_ИЗ_ШАГА_1",
    "recipient_address": "bc1qexample"
  }'

В ответе появится блок deposit с адресом и суммой. Покажите клиенту deposit.address и deposit.amount — он должен перевести ровно эту сумму на этот адрес.

Шаг 3. Отслеживать статус

curl -sS 'https://snapex.pro/api/v1/partner/exchanges/pq_ИЗ_ШАГА_1' \
  -H 'X-API-Key: YOUR_KEY' \
  -H 'Accept: application/json'

Повторяйте запрос с паузой 7–10 секунд. Когда клиент переведёт средства, статус сменится на processing, а затем на completed — средства отправлены клиенту. Финальные статусы: completed, error, cancelled, expired.

Тот же сценарий на Python

import time
import requests

API = "https://snapex.pro/api/v1/partner"
HEADERS = {
    "X-API-Key": "YOUR_KEY",
    "Content-Type": "application/json",
    "Accept": "application/json",
}

# Шаг 1. Котировка: клиент отправляет 20 USDT, получает BTC
quote = requests.post(f"{API}/quotes", headers=HEADERS, json={
    "from_asset_id": "usdt",
    "to_asset_id": "btc",
    "side": "send",
    "amount": "20",
    "recipient_address": "bc1qexample",
}).json()
print("Клиент получит:", quote["receive_amount"], quote["to_symbol"])

# Шаг 2. Создание обмена (в течение 2 минут после котировки)
exchange = requests.post(f"{API}/exchanges", headers=HEADERS, json={
    "quote_id": quote["quote_id"],
    "recipient_address": "bc1qexample",
}).json()
deposit = exchange["deposit"]
print("Клиент должен перевести:", deposit["amount"], deposit["asset"])
print("На адрес:", deposit["address"])

# Шаг 3. Опрос статуса до финального
while True:
    time.sleep(10)  # не чаще 1 запроса в 7 секунд
    state = requests.get(
        f"{API}/exchanges/{quote['quote_id']}", headers=HEADERS
    ).json()
    print("Статус:", state["status"])
    if state["status"] in ("completed", "error", "cancelled", "expired"):
        break

Частые ошибки новичков

• Сумма передана числом, а не строкой. Правильно: "amount": "20", а не "amount": 20.
• При side=receive сумма указана в валюте отправки. При receive amount — это сумма в валюте получения (to).
• Обмен создаётся спустя больше 2 минут после котировки — придёт 409 quote_expired. Запрашивайте котировку непосредственно перед созданием.
• Запросы отправляются чаще раза в 7 секунд — придёт 429. Добавьте паузу между запросами.