Интеграция ChangeNOW API: обмен криптовалют в кошельке

Интеграция с 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 рекомендуем при суммах >0.1 BTC или когда важна точность.

Как обеспечить 98% успешных транзакций?

Ключ — мониторинг статуса обмена в реальном времени. ChangeNOW возвращает статусы: waiting, confirming, exchanging, sending, finished, failed, refunded, verifying. Без автоматизации вы не узнаете, когда обмен завершён или возникла ошибка. Мы настраиваем webhook-уведомления на ваш сервер, чтобы автоматически обновлять баланс и уведомлять пользователя. Мониторинг статуса через webhook позволяет сократить время реакции на инциденты до нескольких секунд.

Дополнительно: настройте алерты на статусы failed и refunded — это сократит время реакции на инциденты.

Почему стоит выбрать ChangeNOW API для кошелька?

ChangeNOW поддерживает 850+ монет, включая редкие активы. Стандартный REST API на HTTPS обеспечивает простоту интеграции. Non-custodial подход исключает необходимость в лицензии обменника. Кроме того, реферальная программа возвращает 35-40% от маржи — это приятный бонус. Всё это делает ChangeNOW одним из лучших решений для добавления обмена в кошелёк.

Процесс работы

1. Аналитика — изучаем вашу архитектуру, выбираем режимы и пары.
2. Проектирование — разрабатываем схему интеграции, определяем эндпоинты и кэширование.
3. Реализация — пишем код на вашем стеке с обработкой всех граничных случаев.
4. Тестирование — тестовый период на sandbox-среде ChangeNOW с эмуляцией ошибок.
5. Деплой — разворачиваем в 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")}