API обмена криптовалют, SDK и виджет

Шесть вызовов

Ещё два — когда понадобятся: /v1/partner/private-quotes и /v1/partner/private-orders проводят обмен через промежуточный анонимный актив двумя связанными плечами, а /v1/export/rates.xml публикует лучший кросс-провайдерский курс по каждому направлению в формате мониторингов.

Клиент примерно на тридцать строк

SDK-пакета для установки нет — и поверхности API он не нужен. Вот всё целиком:

const BASE = "https://api.swapzilla.io";

export class SwapZilla {
  constructor(private key: string) {}

  private headers() { return { "X-API-Key": this.key, "Content-Type": "application/json" }; }

  assets() {
    return fetch(`${BASE}/v1/assets`).then((r) => r.json());
  }

  quotes(q: Record<string, string>) {
    return fetch(`${BASE}/v1/partner/quotes?${new URLSearchParams(q)}`, {
      headers: this.headers(),
    }).then((r) => r.json());
  }

  createOrder(body: object, idempotencyKey: string) {
    return fetch(`${BASE}/v1/partner/orders`, {
      method: "POST",
      headers: { ...this.headers(), "Idempotency-Key": idempotencyKey },
      body: JSON.stringify(body),
    }).then((r) => r.json());
  }

  order(id: string) {
    return fetch(`${BASE}/v1/partner/orders/${id}`, { headers: this.headers() })
      .then((r) => r.json());
  }
}

Кода чуть больше стоит только стриминг — именно он делает интерфейс мгновенным:

const res = await fetch(sseURL, {
  headers: { "X-API-Key": key, Accept: "text/event-stream" },
});
const reader = res.body.pipeThrough(new TextDecoderStream()).getReader();
// делите поток по "\n\n", читайте строки "event:" / "data:" и рисуйте каждый
// `offer` по мере прихода. `done` закрывает поток и приносит финальную карту
// `deviations` — переранжируйте уже нарисованное, а не ждите её, чтобы рисовать.

Как это становится виджетом

Виджет живёт на чужой странице — ровно там, где ключа быть не должно. Рабочая схема такая:

• Проксируйте все вызовы с ключом. API отвечает с Access-Control-Allow-Origin: *, то есть браузер может ходить напрямую — и тогда ключ виден любому в DevTools.
• Пробрасывайте поток как есть. Прокси может передавать text/event-stream без изменений: виджет сохраняет живые цены, ни разу не увидев ключ.
• Кэшируйте котировки на 5–10 секунд. На нашей стороне лимитов нет, но провайдеры начинают троттлить повторные котировки гораздо раньше, чем это заметят пользователи.
• Показывайте, между чем выбирает пользователь. В предложении есть ProviderName, EstimatedMins, KycRating (от A до D) и DeviationPercent: самое дешёвое предложение — не всегда нужное.
• Проверяйте адрес получения через /v1/validate-address до того, как кнопка станет активной. Вызов без ключа, так что виджет может делать его сам.

Что даёт API, а что пишете вы

Чего нет — чтобы никто на это не рассчитывал: опубликованного SDK-пакета, готовой сборки виджета, вебхуков и продакшн-песочницы. Для детерминированных smoke-тестов вместо неё можно включить на ваш ключ провайдер mock.

Кто это встраивает

• Кошельки, которым нужен обмен без кастодиального хранения, ликвидности и разговора про лицензию.
• Telegram-боты и мини-приложения: весь обменник — это четыре экрана, а ключ спокойно лежит на сервере бота.
• Агрегаторы и мониторинги, которые могут читать ещё и /v1/export/rates.xml напрямую.
• Портфельные трекеры и дашборды, превращающие «у вас перевес в ETH» в обмен, который пользователь принимает не выходя из экрана.

Вопросы