Сети и токены¶

У каждого инвойса, платежа, баланса и вывода есть chainId и tokenId. И то и другое — UUID NullSwap, а не идентификаторы самой сети: маршрута, который принял бы вместо них "ethereum", 1 или адрес контракта, в API нет. Эти два эндпоинта и нужны, чтобы перевести то, что вы знаете, в идентификаторы, которые от вас требуются.

Сети¶

curl "https://api.pay.nullswap.com/api/v1/chains?type=EVM" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "name": "Ethereum",
      "networkChainId": 1,
      "type": "EVM",
      "logoURI": "https://cdn.pay.nullswap.com/chains/ethereum.svg",
      "priority": 10,
      "confirmationBlocks": 12,
      "latestBlockNumber": 21345678,
      "explorerTxUrlTemplate": "https://etherscan.io/tx/{value}",
      "explorerAddressUrlTemplate": "https://etherscan.io/address/{value}",
      "standard": "ERC20"
    }
  ]
}

Фильтры: id, type, name. Все повторяются и сравниваются точно; name — без учёта регистра, но это не поиск по подстроке: name=Ethereum сработает, а name=eth не вернёт ничего.

Ответ — { "data": [...] } без объекта pagination: список короткий и отдаётся целиком, offset и limit отклоняются с 400 INVALID_QUERY_PARAMETER, если вы их передадите.

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

depth = chain.latestBlockNumber - payment.blockNumber + 1

Считать глубину приходится самому: confirmations у платежа — снимок на момент последней записи, а не живой счётчик.

На RIPPLE, то есть в XRP Ledger, блок — это леджер: latestBlockNumber и blockNumber платежа — индексы леджеров, и читаются только леджеры, уже валидированные сетью. Монета — XRP с decimals: 6, так что "1000000" — это 1 XRP. Депозит там задаётся адресом и тегом назначения (destination tag) — см. инвойсы.

Токены¶

curl "https://api.pay.nullswap.com/api/v1/tokens?symbol=USDT&status=ENABLED" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "chain": {
        "id": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
        "name": "Ethereum",
        "networkChainId": 1,
        "type": "EVM",
        "logoURI": "https://cdn.pay.nullswap.com/chains/ethereum.svg",
        "priority": 10,
        "confirmationBlocks": 12,
        "latestBlockNumber": 21345678,
        "explorerTxUrlTemplate": "https://etherscan.io/tx/{value}",
        "explorerAddressUrlTemplate": "https://etherscan.io/address/{value}",
        "standard": "ERC20"
      },
      "currency": {
        "id": "7d8e9f0a-1b2c-4d3e-8f40-5a6b7c8d9e0f",
        "name": "Tether USD",
        "symbol": "USDT",
        "logoURI": "https://cdn.pay.nullswap.com/tokens/usdt.svg",
        "decimals": 6,
        "priority": 20
      },
      "address": "0xdac17f958d2ee523a2206206994597c13d831ec7",
      "type": "ERC20",
      "category": "HEDGE",
      "maxAmountOut": "100000000000",
      "decimals": 6,
      "price": "1000200000000000000",
      "status": "ENABLED",
      "srcStatus": "ENABLED",
      "dstStatus": "ENABLED",
      "monitoringCode": "usdt_eth"
    }
  ]
}

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

Разные фильтры объединяются через И, повторы одного фильтра — через ИЛИ. То есть ?chainId=A&chainId=B&status=ENABLED читается как (сеть A или сеть B) и включён.

Валюта и токен¶

Валюта — это актив таким, каким его называет человек: «Tether USD», USDT, 6 знаков после запятой. Токен — та же валюта, развёрнутая в одной конкретной сети по одному адресу. USDT в Ethereum и USDT в Tron — это два токена с общим currency.id.

Инвойсы, балансы и выводы всегда указывают на токен. currency.id пригодится разве что для группировки в вашем собственном интерфейсе.

Остальные поля¶

price — справочный курс, чтобы что-то показать или пересчитать. Инвойс по нему не рассчитывается: сумму NullSwap фиксирует в момент создания инвойса.

Создать инвойс в токене, у которого srcStatus равен DISABLED, не выйдет: ответ — 422 TOKEN_IS_DISABLED. Отключение останавливает только новые инвойсы: платёж, который приходит в этом токене позже — на инвойс, созданный раньше, или на статический кошелёк, — всё равно записывается и свипается.

Курсы¶

curl "https://api.pay.nullswap.com/api/v1/tokens/rate?srcTokenId=3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908&dstTokenId=8c1f2e3d-4a5b-4c6d-8e70-9f0a1b2c3d4e&amountIn=250000000" \
  -H "x-api-key: sk_live_..."

{
  "srcToken": { "id": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908", "…": "полный объект токена" },
  "dstToken": { "id": "8c1f2e3d-4a5b-4c6d-8e70-9f0a1b2c3d4e", "…": "полный объект токена" },
  "rate": "396560000000000",
  "minAmountIn": "10000000",
  "maxAmountIn": "4180000000",
  "maxAmountOut": "1608910000000000000",
  "amountIn": "250000000",
  "amountOut": "99140000000000000",
  "hedgeAmountIn": "248747000"
}

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

rate — это amountOut / amountIn с поправкой на decimals, так что

amountOut ≈ amountIn × rate × 10^(dstDecimals − srcDecimals) / 10^18

воспроизводит котировку с точностью до округления. Если amountOut у вас есть, берите его.

maxAmountIn и maxAmountOut следуют за ликвидностью, доступной для пары, и за тем, сколько dstTokenId мы можем выплатить в данный момент, поэтому движутся вместе с рынком и для малоликвидного токена могут быть намного ниже максимума в USD. Берите их из того же ответа, по которому котируете, а не из более раннего.

TOKENS_RATE_NOT_FOUND означает, что пару нельзя оценить: одного из токенов нет или у него ещё нет цены, пара не поддерживается, или данные о её ликвидности временно недоступны. Последнее проходит само, так что пару, которая работала минуту назад, стоит запросить ещё раз. Формат ошибки описан в разделе Ошибки.

Курс не смотрит на srcStatus и dstStatus: пара с токеном в DISABLED всё равно котируется. Проверьте статусы токена, прежде чем её предлагать.

Кеширование¶

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