Документация API

Начало

Создайте ключ в кабинете и передавайте его в заголовке каждого запроса.

Базовый URL

https://co-re.io

Порядок подключения

1. Храните ключ на сервере. Для сайта без собственного интерфейса используйте готовый виджет. Настроить виджет
2. Загрузите справочник монет, проверьте сети и лимиты, затем запросите курс.
3. Соберите адрес получения, адрес возврата и нужные memo: memo для получения, refundMemo для возврата. Если адрес возврата принадлежит бирже или кастодиальному сервису, возврат без memo теряется: в этом случае всегда передавайте refundMemo. Создавайте обмен с уникальным Idempotency-Key.
4. Показывайте реквизиты депозита только при stage AWAITING_DEPOSIT. При UNDER_REVIEW дождитесь проверки. Передайте клиенту trackUrl и опрашивайте статус.

Открыть кабинет партнёра

Ключи

Ключ идёт в заголовке Authorization как Bearer-токен и показывается один раз. Первый ключ можно создать в кабинете, дополнительные и замену — через поддержку CORE, даже после отзыва. Отозвать ключ можно самостоятельно. Тестовой среды нет: ключ боевой с первой минуты.

curl https://co-re.io/api/v1/quotes \
  -H "Authorization: Bearer <api_key>" \
  -H "Content-Type: application/json" \
  -d '{"send":{"asset":"BTC","network":"BTC"},
       "receive":{"asset":"USDT","network":"TRON"},
       "amount":"0.05"}'

На ключ 600 запросов в минуту на чтение: справочник, границы, проверка адреса, курсы и чтение сделок. GET /pairs — 30 в минуту. Создание обменов и /balance — 60 в минуту, отдельным счётом, так что опрос курсов не отнимает лимит у создания. Пакет /quotes/bulk стоит 1 + ceil(n/5) запросов чтения, пакеты идут по одному. Если нужно больше, напишите нам: лимит ключа поднимается, оба счёта растут в той же пропорции. Опрос статуса раз в 15-30 секунд по каждой открытой сделке входит в лимит чтения. С одного IP допускается 120 запросов в минуту с неверным или отозванным ключом; удачные запросы сюда не входят. Ответ 429 несёт заголовок Retry-After: через сколько секунд повторить.

Соглашения

Суммы передаются десятичными строками, например "0.0213585". Не преобразуйте их в числа с плавающей точкой: это приводит к потере точности.

Указывайте код актива и сеть. USDT в TRON и USDT в Ethereum требуют разных адресов и не взаимозаменяемы.

Используйте code для обработки ошибки и message для сообщения пользователю.

{ "error": { "code": "pair_unavailable", "message": "..." } }

Время в UTC, формат ISO 8601.

Справочник монет

Что CORE умеет обменивать прямо сейчас: код, сеть, в какую сторону работает, нужен ли memo и точность. Для сопоставления со своим списком монет: адрес контракта, chainId для EVM, как сеть называет memo, ссылка на транзакцию в эксплорере ({txHash} заменить на хеш) и иконка. contractAddress указан только там, где мы сверили его с сетью; null значит нативную монету или адрес, которого у нас нет. Не опрашивает исполнителей, поэтому дёшев и кэшируется. У сетей с memo sendEnabled = true, только если исполнитель принимает memo для адреса возврата (refundMemo в POST /deals).

Доступ: Боевой ключ.

Ответ 200

{
  "currencies": [
    {
      "asset": "USDT",
      "network": "ETH",
      "name": "Tether USD",
      "networkName": "Ethereum",
      "sendEnabled": true,
      "receiveEnabled": true,
      "memoRequired": false,
      "decimals": 6,
      "memoName": null,
      "contractAddress": "0xdAC17F958D2ee523a2206206994597C13D831ec7",
      "chainId": 1,
      "explorerTxUrl": "https://etherscan.io/tx/{txHash}",
      "iconUrl": "https://co-re.io/coins/usdt.svg"
    },
    {
      "asset": "XRP",
      "network": "XRP",
      "name": "XRP",
      "networkName": "XRP Ledger",
      "sendEnabled": true,
      "receiveEnabled": true,
      "memoRequired": true,
      "decimals": 6,
      "memoName": "Destination tag",
      "contractAddress": null,
      "chainId": null,
      "explorerTxUrl": "https://xrpscan.com/tx/{txHash}",
      "iconUrl": "https://co-re.io/coins/xrp.svg"
    }
  ],
  "count": 2
}

Может вернуть

Направления обмена

Все направления, которые CORE может котировать прямо сейчас: актив и сеть с обеих сторон, плюс сохранённый минимум. Исполнителей не опрашивает: список строится из того же справочника, по которому идёт котировка, и хранится в памяти 5 минут, поэтому вызов дешёвый. Свой лимит: 30 вызовов в минуту на ключ. Ответ несёт ETag и Cache-Control: пришлите If-None-Match, и без изменений придёт 304 без тела. Фильтр ?send=АКТИВ:СЕТЬ (например, BTC:BTC) оставляет направления из одного актива. min — наименьший минимум, который назвал хоть один исполнитель, в активе отправки; null, если его не измеряли последние 12 часов. max пока всегда null: живые границы даёт /limits. Котировка остаётся главной: пара из списка может не пройти, если исполнитель отказал. Одно направление — около 110 байт, а без фильтра в ответе все направления сразу, так что просите сжатие (Accept-Encoding: gzip) или берите фильтр. Сеть с memo бывает стороной отправки, только если направление обслуживает исполнитель, который принимает memo для адреса возврата (так же, как sendEnabled в /currencies). Если адрес возврата принадлежит бирже или кастодиальному сервису, для такого направления передавайте refundMemo в POST /deals: без memo возврат теряется.

Доступ: Боевой ключ.

Ответ 200

{
  "pairs": [
    {
      "send":    { "asset": "BTC",  "network": "BTC" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "min": "0.0007",
      "max": null
    },
    {
      "send":    { "asset": "BTC", "network": "BTC" },
      "receive": { "asset": "XRP", "network": "XRP" },
      "min": null,
      "max": null
    }
  ],
  "count": 2,
  "updatedAt": "2026-09-30T09:14:44.000Z"
}

Может вернуть

Границы суммы

Минимум и максимум по паре, обе цифры в активе отправки. Считается опросом провайдеров двумя заведомо негодными суммами, поэтому стоит два обращения к провайдерам; полный ответ по паре хранится 5 минут. Кэшируйте на пару, не дёргайте на каждое нажатие клавиши; минимум всех пар сразу есть в GET /pairs. null означает «ни один провайдер не назвал» — не ноль и не «без ограничений».

Доступ: Боевой ключ.

Запрос

{
  "send":    { "asset": "BTC",  "network": "BTC" },
  "receive": { "asset": "USDT", "network": "TRON" }
}

Ответ 200

{
  "limits": {
    "send":    { "asset": "BTC",  "network": "BTC" },
    "receive": { "asset": "USDT", "network": "TRON" },
    "min": "0.0007",
    "max": null
  }
}

Может вернуть

Проверка адреса

Тот же вопрос, который задаст создание обмена, и тем же модулем — проверив адрес заранее, можно быть уверенным, что создание из-за него не откажет. Заодно отвечает про memo: выплата в XRP без тега невозвратна, и узнать это до отправки формы дороже, чем после. Проверка структурная: форма, алфавит, длина. Не контрольная сумма и не «этим адресом кто-то владеет».

Доступ: Боевой ключ.

Запрос

{
  "asset":   "XRP",
  "network": "XRP",
  "address": "rN7n7otQDd6FczFgLdSqtcsAUxDkw6fzRH"
}

Ответ 200

{
  "valid": true,
  "networkKnown": true,
  "memoRequired": true,
  "checked": "structure"
}

Может вернуть

Баланс комиссии

Вознаграждение в USD. pending - вознаграждение по завершённым обменам, доход по которым ещё не подтверждён; к выводу оно недоступно. После подтверждения сумма переходит в available. available учитывает удержания, резервы и суммы к восстановлению. held означает проверку источника. Минимум вывода берите из balance.minPayout. monthVolume - объём, засчитанный в вашу долю за календарный месяц (UTC), в USD; с ним растёт доля. toNextLevel - сколько засчитанного объёма в этом месяце осталось до повышения доли, null на максимальном уровне. Оба поля null, когда показать нечего; денежные поля от этого не зависят.

Доступ: Боевой ключ.

Ответ 200

{
  "balance": {
    "currency": "USD",
    "available": "0",
    "pending": "0",
    "held": "0",
    "reserved": "0",
    "paid": "0",
    "minPayout": "100",
    "monthVolume": "3120.45",
    "toNextLevel": "11879.55"
  }
}

Может вернуть

Курс

Лучший живой курс на пару и сумму среди активных провайдеров. Ничего не создаёт и не двигает. Исполнитель назван там, где этого требуют его собственные условия, иначе помечен как нераскрытый. Только плавающий курс и сумма отправки, как в /deals: rateType и amountSide можно не передавать, другое значение даст unsupported_option. min и max — сохранённые границы пары, те же, что в GET /pairs, в активе отправки; null — «здесь не известно», не ноль и не «без ограничений». Если сеть отправки требует memo, курс сравнивается только среди исполнителей, которые принимают memo для адреса возврата: туда же POST /deals отправит обмен.

Доступ: Боевой ключ.

Запрос

{
  "send":    { "asset": "BTC",  "network": "BTC" },
  "receive": { "asset": "USDT", "network": "TRON" },
  "amount":  "0.05"
}

Ответ 200

{
  "quote": {
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
    "rateType": "float",
    "expiresAt": "2026-08-24T09:14:44Z",
    "executor": { "disclosed": false, "executorTermsAccepted": true },
    "coreMarkup": "0",
    "partnerMarkup": "0",
    "comparedExecutors": 3,
    "min": "0.0007",
    "max": null
  }
}

Что можно показать своему клиенту

Ответ /quotes несёт executor: по умолчанию только факт, что исполнитель есть и его условия приняты. Имя, disclosure и passport (кто держит депозит, режимы курса, условия и наша история с этим провайдером) приходят там, где условия исполнителя требуют назвать его. comparedExecutors по умолчанию число: сколько исполнителей ответило на запрос. Показывать ли это пользователю, решаете вы. Имена исполнителей включаются на ключе, если вы действительно показываете сравнение.

Может вернуть

Курсы пакетом

До 20 котировок одним вызовом, для витрин с курсами по многим парам. Каждый элемент считается ровно как POST /quotes и отвечает тем же телом: quote или error, плюс status — HTTP-статус, который дал бы одиночный запрос. Ответы идут в порядке элементов, index — номер элемента. Плохой элемент не ломает пакет: его ошибка приходит в его ответе. Элементы считаются параллельно; на весь пакет не больше 8 секунд, опоздавшие элементы получают quote_timeout. Стоит 1 + ceil(n/5) запросов чтения: 20 элементов — 5. У ключа идёт не больше одного пакета за раз: второй, пока первый не закончен, получает 429 с Retry-After. Ошибки в списке ниже — ошибки всего запроса.

Доступ: Боевой ключ.

Запрос

{
  "items": [
    {
      "send":    { "asset": "BTC",  "network": "BTC" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "amount":  "0.05"
    },
    {
      "send":    { "asset": "ETH",  "network": "ETH" },
      "receive": { "asset": "USDT", "network": "TRON" },
      "amount":  "0.0001"
    }
  ]
}

Ответ 200

{
  "results": [
    {
      "index": 0,
      "status": 200,
      "quote": {
        "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
        "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
        "rateType": "float",
        "expiresAt": "2026-08-24T09:14:44Z",
        "executor": { "disclosed": false, "executorTermsAccepted": true },
        "coreMarkup": "0",
        "partnerMarkup": "0",
        "comparedExecutors": 3,
        "min": "0.0007",
        "max": null
      }
    },
    {
      "index": 1,
      "status": 422,
      "error": {
        "code": "amount_below_minimum",
        "message": "The amount is below the minimum for this pair. The minimum is 0.004 ETH/ETH."
      }
    }
  ],
  "count": 2
}

Может вернуть

Список сделок

Ваши сделки, новые сверху. Параметры: limit (по умолчанию 50, максимум 100) и cursor из nextCursor предыдущей страницы. partnerMarkup — наценка партнёра, записанная в котировке этой сделки, как есть; у сделок с отключённой наценкой это «0», и по нему нельзя определять доход. commissionUsd — проведённое начисление в USD. null означает, что начисления ещё нет, в том числе у завершённого обмена без подтверждения дохода. Это не нулевой заработок. Доступную к выводу сумму запрашивайте через /balance.

Доступ: Боевой ключ. Видны только сделки, созданные вашим ключом.

Ответ 200

{
  "deals": [
    {
      "id": "7f1c...",
      "status": "COMPLETED",
      "stage": "COMPLETED",
      "createdAt": "2026-08-24T09:12:44Z",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3180.31", "final": true },
      "partnerMarkup": "0",
      "commissionUsd": null
    }
  ],
  "nextCursor": "MjAyNi0wOC0yNFQwOToxMjo0NFp8N2YxYw"
}

Может вернуть

Создание обмена

Выбирает исполнителя, пере-котирует у него и возвращает адрес депозита, на который платит ваш клиент. Курс из /quotes не принимается: он всегда считается заново. Только плавающий курс и сумма отправки: rateType и amountSide можно не передавать, другое значение даст unsupported_option. memo — строка; целое число (тег XRP) тоже принимается. refundMemo — memo адреса возврата, по тем же правилам; если сеть отправки требует memo или refundMemo передан, обмен уйдёт только к исполнителю, который принимает memo для возврата. Если адрес возврата принадлежит бирже или кастодиальному сервису, возврат без memo теряется: в этом случае всегда передавайте refundMemo. Повтор с тем же Idempotency-Key отвечает записанной сделкой без новой котировки, поэтому он не зависит от того, доступна ли пара сейчас. status и stage в ответе те же, что вернёт GET /deals/:id: у нового обмена это ACTIVE и AWAITING_DEPOSIT.

Доступ: Только боевой ключ. Обязателен заголовок Idempotency-Key.

Запрос

{
  "send":          { "asset": "BTC",  "network": "BTC" },
  "receive":       { "asset": "USDT", "network": "TRON" },
  "amount":        "0.05",
  "payoutAddress": "TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
  "refundAddress": "bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4",
  "refundMemo":    null,
  "memo":          null,
  "campaignId":    null
}

Ответ 201

{
  "deal": {
    "id": "7f1c...",
    "status": "ACTIVE",
    "stage": "AWAITING_DEPOSIT",
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44" },
    "deposit": {
      "address":  "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
      "tag":      null,
      "amount":   "0.05",
      "deadline": "2026-07-27T10:15:00Z"
    },
    "trackUrl": "https://<site>/track/7f1c..."
  }
}

Может вернуть

Статус

Текущее состояние вашей сделки, восстановленное из журнала событий. status - статус сделки, stage - шаг обмена (таблицы ниже). Чтение не пассивное: пока сделка идёт, перед ответом CORE спрашивает у исполнителя свежий статус и продвигает сделку, поэтому GET может вернуть статус новее, чем был до запроса (не больше шести раз в минуту на сделку). Пока идёт ожидание депозита, ответ повторяет реквизиты депозита.

Доступ: Только боевой ключ. Видны только сделки, созданные вашим ключом.

Ответ 200

{
  "deal": {
    "id": "7f1c...",
    "status": "ACTIVE",
    "stage": "AWAITING_DEPOSIT",
    "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
    "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44", "final": false },
    "deposit": {
      "address": "bc1qrp33g0q5c5txsp9arysrx4k6zdkfs4nce4xj0gdcccefvpysxf3qccfmv3",
      "tag": null,
      "amount": "0.05",
      "deadline": "2026-08-24T09:42:44Z"
    },
    "trackUrl": "https://<site>/track/7f1c..."
  }
}

trackUrl в ответе это публичная страница сделки. Её можно отдать клиенту: аккаунт не нужен, там видно статус, хеши и форма обращения.

Может вернуть

Статусы сделки

status - статус сделки: идёт она или чем закончилась. Создание, GET, список и вебхуки отдают его одинаково.

Шаг обмена

stage - шаг внутри сделки, его и показывайте клиенту. Приходит рядом со status везде, где есть сделка.

Смена статуса и шага приходит вебхуком, если он настроен: deal.status_changed и deal.stage_changed. Источник истины - GET /api/v1/deals/:id: без вебхука опрашивайте его раз в 15-30 секунд и останавливайтесь на конечном статусе.

Вебхуки

Вебхук задаётся на API-ключ в кабинете: один https-адрес на порту 443 на ключ. При сохранении показывается секрет подписи, один раз. Там же тестовое событие, новый секрет и последние доставки с кодом ответа. Получить ключ

События

{
  "id": "0b6c3a1e-5d2f-4c8a-9e61-2f4b7d9c1a30",
  "type": "deal.status_changed",
  "createdAt": "2026-08-24T09:40:02.113Z",
  "data": {
    "previousStatus": "ACTIVE",
    "status": "COMPLETED",
    "deal": {
      "id": "7f1c...",
      "status": "COMPLETED",
      "stage": "COMPLETED",
      "trackUrl": "https://<site>/track/7f1c...",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3180.31", "final": true }
    }
  }
}

{
  "id": "4d2a7c90-1b3e-4f5a-8c6d-7e8f9a0b1c2d",
  "type": "deal.stage_changed",
  "createdAt": "2026-08-24T09:21:37.540Z",
  "data": {
    "previousStage": "AWAITING_DEPOSIT",
    "stage": "CONFIRMING",
    "deal": {
      "id": "7f1c...",
      "status": "ACTIVE",
      "stage": "CONFIRMING",
      "trackUrl": "https://<site>/track/7f1c...",
      "send":    { "asset": "BTC",  "network": "BTC",  "amount": "0.05" },
      "receive": { "asset": "USDT", "network": "TRON", "amount": "3212.44", "final": false }
    }
  }
}

{
  "id": "5e0a9d44-7b1c-4f3e-8a26-c91d0f6b2e77",
  "type": "reward.available",
  "createdAt": "2026-08-31T00:01:10.502Z",
  "data": {
    "reward": { "id": "c2d4e6f8-1a3b-4c5d-8e7f-9a0b1c2d3e4f", "amount": "1.25", "currency": "USD" }
  }
}

{
  "id": "9a7e2c11-3f64-4d0b-b5a8-0e2c6f1d4b93",
  "type": "webhook.test",
  "createdAt": "2026-08-24T09:12:44.000Z",
  "data": {}
}

Подпись

Каждый запрос несёт заголовок X-Core-Signature: t=<unix-секунды>,v1=<hex>. v1 - HMAC-SHA256 от строки «t.тело» с вашим секретом. Проверяйте подпись по сырому телу запроса до разбора JSON и отклоняйте t старше 300 секунд.

const crypto = require("node:crypto");

// rawBody: the request body exactly as received, before any JSON parsing.
function verifyCoreWebhook(rawBody, header, secret, toleranceSeconds = 300) {
  if (typeof header !== "string" || header === "") return false;
  const parts = Object.fromEntries(header.split(",").map((p) => p.split("=", 2)));
  const timestamp = Number(parts.t);
  if (!Number.isInteger(timestamp) || !/^[0-9a-f]{64}$/.test(parts.v1 ?? "")) return false;
  if (Math.abs(Date.now() / 1000 - timestamp) > toleranceSeconds) return false;
  const expected = crypto.createHmac("sha256", secret).update(`${timestamp}.${rawBody}`).digest();
  return crypto.timingSafeEqual(Buffer.from(parts.v1, "hex"), expected);
}

import hashlib, hmac, re, time

# raw_body: the request body bytes exactly as received, before any JSON parsing.
def verify_core_webhook(raw_body: bytes, header, secret: str, tolerance: int = 300) -> bool:
    if not isinstance(header, str) or not header:
        return False
    parts = dict(p.split("=", 1) for p in header.split(",") if "=" in p)
    t, v1 = parts.get("t", ""), parts.get("v1", "")
    if not re.fullmatch(r"[0-9]{1,12}", t) or not re.fullmatch(r"[0-9a-f]{64}", v1):
        return False
    if abs(time.time() - int(t)) > tolerance:
        return False
    expected = hmac.new(secret.encode(), t.encode() + b"." + raw_body, hashlib.sha256).hexdigest()
    return hmac.compare_digest(expected, v1)

<?php
// $rawBody = file_get_contents('php://input');
// $header  = $_SERVER['HTTP_X_CORE_SIGNATURE'] ?? '';
function verifyCoreWebhook(string $rawBody, string $header, string $secret, int $tolerance = 300): bool {
    $parts = [];
    foreach (explode(',', $header) as $pair) {
        [$key, $value] = array_pad(explode('=', $pair, 2), 2, '');
        $parts[$key] = $value;
    }
    $t = $parts['t'] ?? '';
    $v1 = $parts['v1'] ?? '';
    if (!preg_match('/^[0-9]{1,12}$/', $t) || !preg_match('/^[0-9a-f]{64}$/', $v1)) {
        return false;
    }
    if (abs(time() - (int) $t) > $tolerance) {
        return false;
    }
    $expected = hash_hmac('sha256', $t . '.' . $rawBody, $secret);
    return hash_equals($expected, $v1);
}

Доставка

Доставлено - это любой ответ 2xx за 5 секунд. Редиректы не выполняются и считаются ошибкой. Повторы через: 30 с, 2 мин, 10 мин, 30 мин, 1 ч, 3 ч, 6 ч, 12 ч, после этого доставка прекращается. Одно событие может прийти больше одного раза и не по порядку: храните id обработанных событий (он же заголовок X-Core-Event-Id, свой у каждого вебхука и не меняется при повторах) и сверяйте статус через GET. Адрес должен быть публичным: во внутренние сети и на адреса метаданных запросы не уходят.

Идемпотентность

Заголовок Idempotency-Key обязателен при создании обмена. Без него API возвращает 400. Повтор с тем же ключом возвращает исходную сделку, не создавая новую и не запрашивая курс заново: ответ не зависит от того, доступна ли пара сейчас.

curl https://co-re.io/api/v1/deals \
  -H "Authorization: Bearer <api_key>" \
  -H "Idempotency-Key: 6b1f2c58-0a1e-4b3f-9d21-8c0f4a7e5b12" \
  -H "Content-Type: application/json" \
  -d '{"send":{"asset":"BTC","network":"BTC"},
       "receive":{"asset":"USDT","network":"TRON"},
       "amount":"0.05",
       "payoutAddress":"TJRabPrwbZy45sbavfcjinPJC18kjpRTv8",
       "refundAddress":"bc1qw508d6qejxtdg4y5r3zarvary0c5xw7kv8f3t4"}'

Ошибки

Чего API не делает

Не поддерживаются: фиксированный курс, отмена созданного обмена, указание точной суммы получения, отдельная разбивка сетевых комиссий и тестовая среда. Активные провайдеры работают с плавающим курсом.

Страны и территории

CORE не обслуживает клиентов из следующих стран и территорий: Северная Корея, Иран, Сирия, Куба, Мьянма, Крым, Севастополь, Донецкая область, Луганская область, США, Пуэрто-Рико, Гуам, Виргинские острова США, Американское Самоа, Северные Марианские острова, Внешние малые острова США, Великобритания, Канада, Япония. API не проверяет страну по IP запроса: запросы приходят с вашего сервера. Не создавайте обмены для пользователей из этих стран и территорий.