Балансы и выводы¶

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

Балансы¶

curl https://api.pay.nullswap.com/api/v1/merchant/balances \
  -H "x-api-key: sk_live_..."

{
  "items": [
    {
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "currency": "USDT",
      "decimals": 6,
      "amount": "125000000",
      "balanceId": "b2c3d4e5-f6a7-4890-8b1c-2d3e4f5a6b7c"
    }
  ]
}

Обратите внимание на конверт: { "items": [...] }, а не { "data": [...], "pagination": {...} }, как в остальных списках. Ни пагинации, ни фильтров здесь нет — вы получаете все свои строки сразу.

Одна строка — это один токен. Токена, в котором вам ни разу не платили, в ответе обычно просто нет, но строка может показывать и "0" — например, после того как вы вывели всё, — поэтому отсутствие строки и "0" обрабатывайте одинаково. Баланс в токене, которого больше нет в /api/v1/tokens, не показывается.

Весь amount можно вывести. На баланс свипаются только деньги, которые подтвердились и прошли скрининг; средства, не прошедшие скрининг, до баланса не доходят и остаются на депозитном или статическом адресе, куда пришли. Смотрите их по платежам: через amlStatus у платежей по инвойсу и settlement: WITHHELD у платежей статических кошельков.

amount — строка с целым числом базовых единиц; чтобы показать её человеку, разделите на 10^decimals. И, как всегда, складывайте суммы только внутри одного tokenId — см. соглашения.

Комиссия мерчанта¶

С каждого мерчанта мы берём комиссию с его платежей: ставку в базисных пунктах, которую показывает поле feePercentage в GET /api/v1/merchant. Её устанавливаем мы, и API-ключ никогда не может её изменить. Комиссия удерживается, когда свип зачисляется на ваш баланс: из того, что пришло, комиссия остаётся у нас, а остальное зачисляется на баланс.

fee      = floor(amount × feePercentage / 10000)
credited = amount − fee − network fee

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

Сетевая комиссия — это стоимость перевода денег при свипе токена, оценённая в зачисленном токене и удерживаемая вместе с комиссией мерчанта. Она равна нулю при свипе нативной монеты сети, в UTXO-сетях и в Monero, где свип сам оплачивает себя из того, что переводит. Отдельного поля у неё нет: это разница между amount − fee и credited.

Каждый свип фиксирует ставку в момент, когда он открыт. Изменение ставки касается свипов, открытых после него, и никогда — свипа, который уже в пути.

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

Список удержанных комиссий¶

curl "https://api.pay.nullswap.com/api/v1/merchant/fees?settledFrom=2026-01-01T00:00:00.000Z&settledTo=2026-02-01T00:00:00.000Z&limit=50" \
  -H "x-api-key: sk_live_..."

{
  "data": [
    {
      "id": "0b1c2d3e-4f50-4617-8a29-3b4c5d6e7f80",
      "merchantId": "9f1d2c3b-4a5e-4f60-8b71-2c3d4e5f6a7b",
      "walletId": "7e2a9c14-8b3d-4c56-a789-0f1e2d3c4b5a",
      "invoiceId": "b2f4a6c8-0d1e-4f23-9a45-6b7c8d9e0f11",
      "staticWalletId": null,
      "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
      "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "transferRequestId": "4d5e6f70-8192-4a3b-9c4d-5e6f708192a3",
      "amount": "25500000",
      "credited": "25117500",
      "fee": "382500",
      "feePercentage": "150",
      "feeUsd": "382576500000000000",
      "settledAt": "2026-01-01T12:14:00.000Z",
      "creditedTokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
      "dstTokenId": null,
      "amountIn": null,
      "amountOut": null,
      "conversionSkipReason": null
    }
  ],
  "pagination": { "offset": 0, "limit": 50, "total": 1, "order": "DESC" }
}

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

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

Создание вывода¶

curl -X POST https://api.pay.nullswap.com/api/v1/merchant/withdrawals \
  -H "x-api-key: sk_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
    "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
    "to": "0xfedcba0987654321fedcba0987654321fedcba09",
    "amount": "50000000",
    "externalId": "payout-2026-01-14-001"
  }'

{
  "transferRequestId": "9c0d1e2f-3a4b-45c6-8d78-9e0f1a2b3c4d",
  "status": "PENDING",
  "hash": null,
  "amount": "50000000",
  "fee": "1350000"
}

201 значит принято к обработке, а не отправлено. До сети дело ещё не дошло, hash равен null, результат придёт асинхронно. А вот списание уже произошло: сумма и fee снимаются с вашего баланса в момент приёма вывода, а вывод, который баланс не покрывает, сразу отклоняется с 422 INSUFFICIENT_MERCHANT_BALANCE.

Две проверки to всё же проходят до какого-либо списания:

• Скрининг. Адрес назначения проверяется при создании вывода. Адрес, не прошедший скрининг, отклоняется с 422 RECIPIENT_ADDRESS_BLOCKED; SKIPPED вывод пропускает. Адреса Monero не проверяются.
• Ваш белый список выводов, если вы его включили. Владелец мерчанта может ограничить выплаты списком доверенных адресов в кабинете, в разделе Настройки → Белые списки. Когда ограничение включено, to, которого нет в списке для этой сети, отклоняется с 422 WITHDRAWAL_ADDRESS_NOT_WHITELISTED — в том числе при вызовах API, — а при пустом списке отклоняется любая выплата. Список ведётся по сетям: адрес, добавленный для одной EVM-сети, в другой доверенным не считается. На RIPPLE запись списка — это адрес вместе с тегом назначения, и выплата совпадает только с записью ровно с её toTag; запись без тега совпадает только с выплатой без тега.

Вывод на RIPPLE¶

На RIPPLE, то есть в XRP Ledger, большинство бирж и кастодианов принимают деньги на один счёт, общий для всех их клиентов, и различают клиентов по тегу назначения (destination tag). Передайте тег получателя в toTag или передайте в to X-адрес, который вам дали. Выплата на такой счёт без тега дойдёт до биржи, но ни на чей баланс там не попадёт.

Ещё две проверки до какого-либо списания читают счёт получателя из леджера:

• Обязательный тег. Счёт, который не принимает платежи без тега назначения, при выплате без toTag даёт отказ 422 DESTINATION_TAG_REQUIRED.
• Счёт, которого ещё нет. Счёт в XRP Ledger создаётся первым платежом на него, и только если этот платёж не меньше базового резерва сети — сейчас это 1 XRP. Выплата на несуществующий счёт меньше этой суммы отклоняется с 422 DESTINATION_NOT_ACTIVATED, а details.minAmount сообщает, сколько нужно, в drops:

{
  "statusCode": 422,
  "message": "DESTINATION_NOT_ACTIVATED",
  "timestamp": "2026-01-14T09:00:00.000Z",
  "details": {
    "minAmount": "1000000"
  }
}

Берите цифру из details.minAmount, а не зашивайте её в код: резерв устанавливает сеть, и она может его изменить. Ни один из этих отказов ничего не списывает, и тот же externalId можно отправить снова, когда запрос исправлен.

Комиссия¶

Вывод стоит столько, сколько сетевая комиссия за его отправку, и платите вы её в выводимом токене — по текущему курсу этого токена и с небольшим запасом на изменение цены между оценкой и отправкой. fee в ответе — то, что с вас взяли, amount — то, что отправят получателю, оба в базовых единицах tokenId. Других сборов нет, и держать газ не нужно: чтобы вывести токен, баланс в нативной монете сети не требуется.

true — это способ вывести всё: отправьте весь баланс в amount, и комиссия возьмётся из него. С false вывод всего баланса будет отклонён — на комиссию не хватит.

Комиссия пересчитывается в момент вывода, поэтому может отличаться от любой показанной вам оценки. Передайте maxFee, чтобы ограничить её: вывод, комиссия которого оказалась выше, отклоняется с 422 FEE_EXCEEDS_MAX_FEE, и ничего не списывается.

Оценка комиссии¶

curl "https://api.pay.nullswap.com/api/v1/merchant/withdrawals/fee-quote?chainId=1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10&tokenId=3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908" \
  -H "x-api-key: sk_live_..."

{
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "nativeTokenId": "6a7b8c9d-0e1f-4a2b-8c3d-4e5f6a7b8c9d",
  "nativeFee": "2800000",
  "fee": "1350000"
}

fee — сколько взяли бы за вывод tokenId прямо сейчас, в его базовых единицах, с учётом запаса. nativeFee — сетевая стоимость, из которой он пересчитан, в базовых единицах нативной монеты сети nativeTokenId.

Это только оценка. Ничего не резервируется и курс не фиксируется: если комиссия должна остаться в показанных пределах, передайте показанный fee как maxFee при выводе.

Здесь externalId действительно ключ идемпотентности¶

Это единственная операция записи в API, где повторный externalId безопасен, а не ошибочен. Отправьте один и тот же дважды с теми же параметрами — повтор после таймаута сокета, задублившаяся задача — и второй вызов вернёт уже созданный вывод, а не сделает второй. Уникальность считается в пределах вашего мерчанта.

externalId необязателен, но не передавайте его, только если никогда не повторяете запросы. Без него каждый вызов — новый вывод: два одинаковых запроса — это две выплаты, а повтор после таймаута, ответа на который вы так и не увидели, отправит деньги дважды.

Тот же externalId с любым изменённым параметром — chainId, tokenId, to, toTag, amount, subtractFeeFromAmount или maxFee — отклоняется с 409 WITHDRAWAL_EXTERNAL_ID_CONFLICT, и ничего не отправляется. Это значит, что ваша система использовала одну ссылку для двух разных выплат; исправьте ссылку, а не повторяйте запрос.

Сравните с инвойсами, где повторный externalId даёт 409. Асимметрия сделана намеренно: дублирующийся инвойс поправим, а дублирующийся вывод отправит деньги дважды.

Повтор возвращает существующий вывод, чем бы он ни закончился, в том числе FAILED. Чтобы повторить проваленный вывод, отправьте новый externalId. Вывод, отклонённый с 422, не записывается, поэтому тот же externalId можно использовать снова, когда причина устранена. После 5xx externalId остаётся занятым: повтор с ним вернёт то, чем закончилась первая попытка.

Ошибки¶

Отслеживание вывода¶

curl "https://api.pay.nullswap.com/api/v1/merchant/withdrawals?limit=50" \
  -H "x-api-key: sk_live_..."

Только offset, limit и order: фильтров по статусу, токену или externalId здесь нет. По умолчанию сортировка createdAt DESC.

{
  "id": "9c0d1e2f-3a4b-45c6-8d78-9e0f1a2b3c4d",
  "chainId": "1c9a7f36-5f2b-4a83-9d51-0e6b7c8d9a10",
  "tokenId": "3b7e1a48-2c6d-4e9f-8a01-5d4c3b2a1908",
  "toAddress": "0xfedcba0987654321fedcba0987654321fedcba09",
  "toTag": null,
  "amount": "50000000",
  "fee": "1350000",
  "decimals": 6,
  "status": "CONFIRMED",
  "hash": "0x9a8b7c6d5e4f30211a2b3c4d5e6f708192a3b4c5d6e7f8091a2b3c4d5e6f70819",
  "error": null,
  "createdAt": "2026-01-14T09:00:00.000Z",
  "updatedAt": "2026-01-14T09:04:00.000Z"
}

id — это тот самый transferRequestId, что вернулся вам при создании: то же значение под другим именем. amount — то, что отправлено получателю (уже за вычетом комиссии, если вы задали subtractFeeFromAmount), а fee — то, что с вас взяли сверх этого. toTag — тег назначения, с которым выплата ушла на RIPPLE; null, если тега не было, и на всех остальных сетях. toAddress всегда классический адрес, даже если вы отправили X-адрес. fee равен null у выплат, сделанных до того, как комиссию за вывод стали брать в выводимом токене.

stateDiagram-v2
    [*] --> PENDING: POST принят
    PENDING --> BROADCASTING: отправляется
    BROADCASTING --> BROADCAST: опубликован
    BROADCASTING --> FAILED: не удалось отправить
    PENDING --> FAILED: не удалось отправить
    BROADCAST --> CONFIRMED: подтверждён в сети
    BROADCAST --> FAILED: откачен
    CONFIRMED --> [*]
    FAILED --> [*]

Две детали, которые нужно учесть в опрашивающем коде:

• У записи FAILED hash может быть null — и навсегда. У вывода, провалившегося ещё до публикации, хеша не было никогда. Проверяйте поле, прежде чем показывать ссылку на обозреватель.
• decimals тоже может быть null. Это значит, что токен с тех пор делистнули. Возьмите закешированное значение из /api/v1/tokens, но не подставляйте по умолчанию 18.

Вывод, провалившийся до попадания в сеть, возвращает на баланс и сумму, и fee. Вывод, который был отправлен и откачен, возвращает только сумму: сетевая комиссия уже потрачена.

Два случая автоматически не урегулируются, и снаружи ни один из них не выглядит иначе:

• Вывод FAILED, который, возможно, дошёл до сети. Когда отправка обрывается по таймауту так, что неизвестно, ушла ли транзакция, запись получает FAILED, но ничего не возвращается: выплата ещё может дойти. По записи не понять, какой это FAILED: сверьте баланс и, если деньги не вернулись, обратитесь в поддержку с id вывода.
• Вывод BROADCAST, который сеть отбросила. Он остаётся BROADCAST, и ничего не возвращается. Если вывод остаётся BROADCAST намного дольше времени подтверждения в этой сети, обратитесь в поддержку с его id и hash.

error заполняется только при FAILED, кодом: WITHDRAWAL_REVERTED — транзакция попала в сеть и откатилась, сумма вернулась на баланс, сетевая комиссия потрачена; WITHDRAWAL_FAILED — всё остальное, ничего не отправлено. Незнакомый код считайте WITHDRAWAL_FAILED: коды могут добавляться.