Для обменников

Файл курсов: формат и правила

Changerella берёт ваши курсы из одного XML-файла по публичному адресу. Ниже — что в нём должно быть, как мы его читаем и проверяем и какими кодами обязана называться каждая валюта.

XMLUTF-8, структура BestChange

179кодов валют

70 / 109крипто / фиат

~1 минот файла до сайта

Справочник кодов Пример файла

Минимальный рабочий файл

Один <item> на одно направление обмена, все — прямо внутри одного корневого элемента. Имя корня любое, принято <rates>.

rates.xml

<?xml version="1.0" encoding="UTF-8"?>
<rates>
  <item>
    <from>BTC</from>
    <to>USDTTRC20</to>
    <in>1</in>
    <out>63250.40</out>
    <amount>185000</amount>
    <minamount>0.005 BTC</minamount>
    <maxamount>2.5 BTC</maxamount>
  </item>
  <item>
    <from>USDTTRC20</from>
    <to>XMR</to>
    <in>164.20</in>
    <out>1</out>
    <amount>412.7</amount>
    <minamount>50 USDT</minamount>
    <maxamount>25000 USDT</maxamount>
  </item>
  <item>
    <from>SBERRUB</from>
    <to>BTC</to>
    <in>6120000</in>
    <out>1</out>
    <amount>3.4</amount>
    <minamount>5000 RUB</minamount>
    <maxamount>1500000 RUB</maxamount>
  </item>
</rates>

Что внутри <item>

Каждое направление описывается одним и тем же набором тегов. Порядок тегов не важен.

Тег	Тип	Что означает	Пример
`<from>`обязателен	код	Что отдаёт клиент. Код из справочника ниже.	`BTC`
`<to>`обязателен	код	Что получает клиент. Код из справочника ниже.	`USDTTRC20`
`<in>`обязателен	число	Сколько «from» отдаёт клиент…	`1`
`<out>`обязателен	число	…чтобы получить столько «to». Курс = out ÷ in.	`63250.40`
`<amount>`обязателен	число	Резерв: сколько «to» вы готовы выплатить прямо сейчас.	`185000`
`<minamount>`необязателен	число + ед.	Минимальная сумма заявки в «from». Через пробел можно указать единицу.	`0.005 BTC`
`<maxamount>`необязателен	число + ед.	Максимальная сумма заявки в «from». Формат как у minamount.	`2.5 BTC`
`<param>`необязателен	текст	Флаги в стиле BestChange (manual, verifying…). Принимаются, на сайте пока не выводятся.	`manual`
`<tofee>`необязателен	текст	Доп. комиссия на выплату. Принимается, пока не выводится.	`1 USDT`

Одно кривое число ломает весь файл. in, out и amount — только числа с точкой: 1500, 0.00042, 1e-5. Запятая, пробел, знак валюты или текст хотя бы в одном из них делают файл нечитаемым — и пропадают сразу все ваши направления. С minamount/maxamount мягче: берём первое число, остальное игнорируем.

Как in и out превращаются в курс

in и out — две стороны одной сделки: «отдаёте in единиц from — получаете out единиц to». Мы делим out на in и получаем, сколько «to» дают за единицу «from». Ставьте 1 на стороне более дорогой валюты, а цену — на другой: такой курс проще читать и проверять.

BTC →

USDTTRC20

<in>1</in><out>63250.40</out>

Клиент отдаёт 1 BTC и получает 63 250,40 USDT.

USDTTRC20 →

BTC

<in>64110</in><out>1</out>

Клиент отдаёт 64 110 USDT за 1 BTC. То же, что in=1, out=0.0000156, — но читается.

amount

Резерв — всегда в валюте «to», то есть то, что вы можете выплатить. 185000 у направления BTC→USDT — это 185 000 USDT, а не BTC.

minamount / maxamount

Лимиты — в валюте «from», то есть то, что присылает клиент. «0.005 BTC» и «0.005» читаются одинаково.

Ноль = нет направления

in или out, равные 0, убирают направление из таблицы. Чтобы приостановить направление, просто уберите его <item>.

Требования к отдаче файла

Мы забираем файл сами, круглосуточно. Получится ли — решают эти шесть условий.

Только UTF-8

В заголовке — UTF-8 или ничего. Файл в windows-1251 отклоняется целиком, а не частично.

HTTP 200 по постоянному адресу

Обычный GET без cookies, авторизации и редиректов на HTML-страницу. HTTPS приветствуется.

Ответ за 25 секунд

Заголовки — за 15 с, всё тело — за 25 с. Медленный файл считается недоступным.

До 64 МБ

Самый большой файл сейчас весит около 3 МБ — запас огромный.

Обновляется, а не застыл

Если Last-Modified старше суток, файл считается мёртвым даже при ответе 200.

Пускайте нашего робота

Запросы идут с User-Agent «Changerella-Monitoring/1.0». Не блокируйте его и не прячьте файл за JS-проверкой.

Если файл замолчал. Курсы остаются на сайте до 30 минут после последнего удачного чтения, затем исчезают, пока файл снова не ответит. Ничего пересылать не нужно — они вернутся сами.

Как мы проверяем курсы

Посетитель верит первой строке таблицы, поэтому каждый курс проходит три фильтра, прежде чем туда попасть.

Медиана пары

Если у пары не меньше 3 предложений, курс, отклонившийся от их медианы больше чем на 5% (на 10%, если в паре фиат), уходит в список «подозрительных», а не в основную таблицу.

Сверка с рынком

Крипто-курсы сравниваются с биржевой ценой. Предложение выгоднее рынка больше чем на 5% — почти всегда опечатка, и оно прячется так же.

Правдоподобный резерв

Резерв больше 10 медиан пары или круглое число на миллион долларов и выше (вроде 1000000) помечается как сомнительный. Указывайте резерв, который у вас действительно есть.

Частые ошибки

Всё это — из реальных файлов, которые мы читаем сегодня. Каждая ошибка стоит обменнику направления, а то и всего файла.

USDT→USDTTRC20

Голого тикера токену мало — нужна сеть.

USDT TRC20→USDTTRC20

Внутри кода нет пробелов, дефисов и подчёркиваний.

USDTSOLANA→USDTSOL

Суффиксы сетей фиксированы: SOL, TRC20, ERC20, BEP20, POLYGON.

TON→GRAM

Toncoin в справочнике записан кодом GRAM.

BNB→BNBBEP20

BNB у нас только в сети BNB Smart Chain.

JUSANKZT→JSNBKZT

Коды банков берутся из справочника, а не придумываются.

<in>1,5</in>→<in>1.5</in>

Десятичный разделитель — точка. Запятая ломает весь файл.

<in>1 000</in>→<in>1000</in>

Никаких разделителей тысяч в in, out и amount.

Справочник кодов валют

Пишите в <from> и <to> ровно эти коды. Список собирается из живого справочника сайта: сейчас здесь 179 валют.

Монеты

Монета со своим блокчейном пишется тикером: BTC, ETH, XMR, LTC, TRX.

Токены

Тикер + сеть без разделителя: USDTTRC20, USDCERC20, SHIBBEP20. Один токен в пяти сетях — пять разных кодов.

Фиат

Способ + ISO-код валюты: SBERRUB, CARDUSD, CASHEUR, WIREGBP. Тот же банк в другой валюте — другой код.

Суффиксы сетей

TRC20TRONTRC-20

ERC20EthereumERC-20

BEP20BNB Smart ChainBEP-20

POLYGONPolygon PoSERC-20 (Polygon)

SOLSolanaSPL

OMNIOmni LayerOmni

LNLightning NetworkLightning

Один тикер — несколько кодов

BTC

ETH

SHIB

TUSD

USDC

USDT

Криптовалюты

Монеты и токены. У токена сеть входит в код.

Банковские карты

Перевод на карту или с карты — по валюте.

Банки

Перевод через конкретный банк.

Платёжные системы

Электронные кошельки и системы денежных переводов.

Банковский перевод

Перевод на банковский счёт в любом банке в указанной валюте.

Наличные

Наличные в офисе или курьером.

Нажмите на код, чтобы скопировать.

Вопросы

Что будет с кодом, которого нет в справочнике?

Направление тихо пропускается: остальной файл работает, но эта строка до сайта не доходит. Если нужной валюты нет — напишите нам, добавим код.

Важен ли регистр кода?

Нет: usdttrc20 и USDTTRC20 — одно и то же. Рекомендуем верхний регистр — так записан справочник.

Как часто читается файл?

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

Почему мой курс не показан, хотя он есть в файле?

Чаще всего: кода нет в справочнике, in или out равны нулю, или курс слишком далеко от медианы других обменников или от рынка и ушёл в список «подозрительных». Проверки описаны выше.

Подходит ли файл в формате BestChange как есть?

Да, структура та же. Сверьте только коды валют с нашим справочником: часть из них отличается (например, Toncoin — это GRAM).

Файл готов?

Пришлите нам ссылку — проверим и подключим обменник к мониторингу.

Добавить обменник