Интеграция с ChangeNOW API
Представьте: кошелёк с 50 000 пользователей, каждый хочет обменять ETH на USDT без регистрации. Лобовая интеграция через CEX требует KYC и занимает недели. ChangeNOW API — готовый non-custodial мост с 850+ монетами, фиксированным курсом и временем обмена около 4 минут. Мы интегрировали это API для пятидесяти проектов — от мелких кошельков до крупных обменников с оборотами в десятки BTC в день. В этой статье детально разберём процесс: от регистрации API-ключа до настройки webhook-уведомлений и обработки ошибок. Вы узнаете, какие эндпоинты использовать для получения курсов, создания обмена и мониторинга статусов, а также как избежать типичных проблем с extraId и минимальными суммами.
Какие проблемы решает интеграция?
Ликвидность. Вместо накопления собственных резервов вы получаете доступ к глубокой ликвидности через единый API. ChangeNOW агрегирует несколько пулов (Binance, Huobi, Kraken), что минимизирует проскальзывание даже для сумм порядка 5 BTC.
KYC. Non-custodial модель означает, что средства не хранятся у провайдера — риски комплаенса снижаются. Большинство обменов проходит без верификации, только при суммах выше порога (например, >10 BTC) требуется проверка. Это экономит до 40% времени на онбординг пользователей.
Волатильность. Режим Fixed Rate фиксирует курс на 2–3 минуты, что идеально для арбитража и крупных транзакций. Standard режим использует рыночный курс с обновлением каждые 5 секунд — подходит для мелких обменов с минимальными задержками.
Время разработки. ChangeNOW предлагает хорошо документированный REST API и SDK под Python, JS, Go. С использованием нашего готового модуля интеграция занимает от 3 дней до 2 недель — в 2 раза быстрее по сравнению с самостоятельной разработкой. Дополнительно это снижает затраты на инфраструктуру примерно на 30% за счёт отказа от собственных пулов ликвидности.
Как мы интегрировали ChangeNOW API: реальный кейс
Разберём реальный кейс — интеграцию для мультивалютного кошелька на базе Python (FastAPI) и PostgreSQL. Кошелёк поддерживал 20 монет, требовался обмен без регистрации.
Стек: Python 3.11, httpx 0.25, pydantic для валидации, asyncpg для БД, celery для фоновых задач. Для отслеживания статусов использовали вебхуки от ChangeNOW.
Ключевые моменты:
- Реализовали кэширование курсов с TTL 30 секунд, чтобы снизить нагрузку на API — до 10 запросов/сек вместо 50.
- Для Fixed Rate создали очередь с таймером: если пользователь не отправил депозит за 2 минуты, курс пересчитывается.
- Обрабатывали крайние случаи: недостаточный баланс, сетевые задержки (повтор через 30 сек), возвраты при ошибках сети.
Результат у клиента: среднее время обмена — 4 минуты, уровень успешных транзакций — 98.7%. ChangeNOW API обрабатывает такие транзакции быстрее в 1.5 раза, чем средний провайдер.
Получите консультацию по интеграции ChangeNOW API — оценим объём работ за 1 день.
Как выбрать между Standard и Fixed Rate?
| Параметр | Standard | Fixed Rate |
|---|---|---|
| Курс | Плавающий, обновляется каждые 5 сек | Фиксированный на 2–3 мин |
| Комиссия | 0.5–1.5% от суммы | 0.8–2% от суммы |
| Проскальзывание | Возможно при высокой волатильности | Нет в пределах лимитов |
| Минимальная сумма | От 0.001 BTC | От 0.01 BTC |
| Подходит для | Мелких/средних обменов | Крупных обменов, арбитража |
Для большинства пользователей кошелька достаточно Standard. Fixed Rate рекомендуем при суммах >0.1 BTC или когда важна точность.
Как обеспечить 98% успешных транзакций?
Ключ — мониторинг статуса обмена в реальном времени. ChangeNOW возвращает статусы: waiting, confirming, exchanging, sending, finished, failed, refunded, verifying. Без автоматизации вы не узнаете, когда обмен завершён или возникла ошибка. Мы настраиваем webhook-уведомления на ваш сервер, чтобы автоматически обновлять баланс и уведомлять пользователя. Мониторинг статуса через webhook позволяет сократить время реакции на инциденты до нескольких секунд.
| Статус | Значение | Действие |
|---|---|---|
| waiting | Ожидание депозита | Показать адрес для пополнения |
| confirming | Подтверждение сети | Подождать 1-2 блока |
| exchanging | Обмен в процессе | Обновить статус |
| sending | Отправка на кошелёк | Ждать подтверждения |
| finished | Завершён | Зачислить средства |
| failed | Ошибка | Инициировать возврат |
| refunded | Возврат средств | Уведомить пользователя |
| verifying | KYC требуется | Запросить документы |
Дополнительно: настройте алерты на статусы failed и refunded — это сократит время реакции на инциденты.
Почему стоит выбрать ChangeNOW API для кошелька?
ChangeNOW поддерживает 850+ монет, включая редкие активы. Стандартный REST API на HTTPS обеспечивает простоту интеграции. Non-custodial подход исключает необходимость в лицензии обменника. Кроме того, реферальная программа возвращает 35-40% от маржи — это приятный бонус. Всё это делает ChangeNOW одним из лучших решений для добавления обмена в кошелёк.
Процесс работы
- Аналитика — изучаем вашу архитектуру, выбираем режимы и пары.
- Проектирование — разрабатываем схему интеграции, определяем эндпоинты и кэширование.
- Реализация — пишем код на вашем стеке с обработкой всех граничных случаев.
- Тестирование — тестовый период на sandbox-среде ChangeNOW с эмуляцией ошибок.
- Деплой — разворачиваем в production, настраиваем мониторинг и алерты.
Что входит в интеграцию
- Анализ текущей архитектуры и выбор оптимальных режимов (Standard/Fixed Rate).
- Проектирование схемы интеграции с учётом кэширования и обработки ошибок.
- Реализация модуля на вашем стеке (Python, JS, Go, Rust).
- Тестирование на sandbox-среде ChangeNOW с эмуляцией всех статусов.
- Деплой в production с настройкой мониторинга и webhook-уведомлений.
- Предоставление документации интеграции и обучение команды.
Свяжитесь с нами для бесплатной оценки вашего проекта — поможем спроектировать оптимальную архитектуру. Закажите тестовый доступ к нашему готовому модулю интеграции.
Распространённые проблемы
- Пропущенный extraId. Для сетей XRP, EOS, STELLAR требуется дополнительный идентификатор (memo/tag). Без него депозит не зачисляется.
- Некорректная валидация минимальной суммы. Эндпоинт
/v2/exchange/rangeвозвращает актуальные лимиты — не полагайтесь на хардкод. - Игнорирование статуса
verifying. Если требуется KYC, обмен не перейдёт вfinishedбез действия со стороны провайдера. - Отсутствие обработки timeout. Fixed Rate имеет таймаут — после отправки депозита курс может измениться, если не уложиться в 2 минуты.
Ключевые эндпоинты ChangeNOW API
Получение курса
import httpx
from decimal import Decimal
class ChangeNOWClient:
BASE_URL = "https://api.changenow.io/v2"
def __init__(self, api_key: str):
self.api_key = api_key
self.headers = {"x-changenow-api-key": api_key}
async def get_estimated_amount(
self,
from_currency: str, # 'btc'
to_currency: str, # 'eth'
from_amount: float,
flow: str = 'standard' # 'standard' или 'fixed-rate'
) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(
f"{self.BASE_URL}/exchange/estimated-amount",
params={
"fromCurrency": from_currency.lower(),
"toCurrency": to_currency.lower(),
"fromAmount": str(from_amount),
"flow": flow,
"type": "direct"
},
headers=self.headers
)
data = response.json()
if "error" in data:
raise ChangeNOWError(f"{data['error']}: {data.get('message', '')}")
return {
"estimated_amount": data["toAmount"],
"rate": data["toAmount"] / from_amount,
"min_amount": data.get("minAmount"),
"max_amount": data.get("maxAmount"),
"network_fee": data.get("networkFee")
}
Создание обмена
async def create_exchange(
self,
from_currency: str,
to_currency: str,
from_amount: float,
to_address: str,
refund_address: str = None,
flow: str = 'standard',
user_id: str = None
) -> dict:
payload = {
"fromCurrency": from_currency.lower(),
"toCurrency": to_currency.lower(),
"fromAmount": str(from_amount),
"address": to_address,
"flow": flow,
"type": "direct",
"extraId": "", # memo/tag для XRP, EOS, etc.
}
if refund_address:
payload["refundAddress"] = refund_address
# userId — для отслеживания конверсий affiliate
if user_id:
payload["userId"] = user_id
async with httpx.AsyncClient() as client:
response = await client.post(
f"{self.BASE_URL}/exchange",
json=payload,
headers=self.headers
)
data = response.json()
return {
"order_id": data["id"],
"deposit_address": data["payinAddress"],
"deposit_amount": data["fromAmount"],
"receive_amount": data["toAmount"],
"payin_extra_id": data.get("payinExtraId"),
"status": data["status"]
}
Мониторинг статуса
async def get_exchange_status(self, order_id: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(
f"{self.BASE_URL}/exchange/by-id",
params={"id": order_id},
headers=self.headers
)
data = response.json()
status_map = {
"waiting": "awaiting_deposit",
"confirming": "confirming",
"exchanging": "processing",
"sending": "sending",
"finished": "completed",
"failed": "failed",
"refunded": "refunded",
"verifying": "kyc_required"
}
return {
"status": status_map.get(data["status"], data["status"]),
"payin_hash": data.get("payinHash"),
"payout_hash": data.get("payoutHash"),
"amount_received": data.get("amountReceived"),
"amount_sent": data.get("amountSent"),
"updated_at": data.get("updatedAt")
}
Список поддерживаемых валют
async def get_currencies(self, active: bool = True) -> list[dict]:
async with httpx.AsyncClient() as client:
response = await client.get(
f"{self.BASE_URL}/exchange/currencies",
params={"active": str(active).lower(), "flow": "standard"},
headers=self.headers
)
currencies = response.json()
return [
{
"ticker": c["ticker"],
"name": c["name"],
"network": c.get("network"),
"image": c.get("image"),
"is_stable": c.get("isStable", False)
}
for c in currencies
]
Минимальные суммы и валидация
async def validate_exchange_params(
self,
from_currency: str,
to_currency: str,
from_amount: float
) -> ValidationResult:
range_data = await self.get_range(from_currency, to_currency)
if from_amount < range_data["min_amount"]:
return ValidationResult(
valid=False,
error=f"Amount too small. Min: {range_data['min_amount']} {from_currency.upper()}"
)
if range_data.get("max_amount") and from_amount > range_data["max_amount"]:
return ValidationResult(
valid=False,
error=f"Amount too large. Max: {range_data['max_amount']} {from_currency.upper()}"
)
return ValidationResult(valid=True)
async def get_range(self, from_currency: str, to_currency: str) -> dict:
async with httpx.AsyncClient() as client:
response = await client.get(
f"{self.BASE_URL}/exchange/range",
params={"fromCurrency": from_currency, "toCurrency": to_currency, "flow": "standard"},
headers=self.headers
)
data = response.json()
return {"min_amount": data["minAmount"], "max_amount": data.get("maxAmount")}