Объекты

Объекты, которые API возвращает и принимает. Необязательные поля без значения в ответе не передаются.

Error

Поле	Тип	Описание
error обязательно	object
error.code обязательно	string	Что не так. Код стабилен — ветвитесь по нему.
error.message обязательно	string	Подробности для людей. Текст может меняться.

Address

Адрес в 0x-hex; в запросах — в любом регистре, в ответах — с контрольной суммой (EIP-55).

Тип: string. Формат: ^0x[0-9a-fA-F]{40}$. Пример: 0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769.

Amount

Целое число в минимальных единицах, строкой.

Тип: string. Формат: ^[0-9]+$. Пример: 1000000.

ChainID

Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.

Тип: integer (int64). Пример: 11155111, 97.

Gas

Количество газа.

Тип: integer (int64).

NextCursor

Курсор следующей страницы; на последней — null.

Тип: string \| null.

LedgerKind

gas — газ транзакции газ-кошелька; fee — комиссия за sweep; fee_charge — начисление по договору; fee_credit — списание по договору, которое уменьшает комиссии к выводу; withdrawal — вывод комиссий с газ-кошелька вместе с газом вывода; topup — пополнение газ-кошелька, найденное сверкой баланса.

Тип: string.

LedgerEntry

Изменение баланса газ-кошелька или комиссий, которые на нём лежат.

Поле	Тип	Описание
id обязательно	integer (int64)
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
kind обязательно	LedgerKind	gas — газ транзакции газ-кошелька; fee — комиссия за sweep; fee_charge — начисление по договору; fee_credit — списание по договору, которое уменьшает комиссии к выводу; withdrawal — вывод комиссий с газ-кошелька вместе с газом вывода; topup — пополнение газ-кошелька, найденное сверкой баланса. Одно из: gas, fee, fee_charge, fee_credit, withdrawal, topup.
amount обязательно	string	Wei со знаком: плюс — topup и fee_credit, минус — газ, комиссии, начисления и вывод. Формат: ^-?[0-9]+$.
tx_hash обязательно	string | null	Транзакция движения; у пополнений, начислений и списаний — null.
sweep_id обязательно	string | null (uuid)	Sweep, за который комиссия fee; у других видов — null.
note обязательно	string | null	Пометка у начислений и списаний; у пополнений — блоки, которые прошла сверка.
created_at обязательно	string (date-time)

UsageDay

Работа партнёра в одной сети за один день UTC.

Поле	Тип	Описание
date обязательно	string (date)	День по UTC.
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
sweeps_done обязательно	integer	Sweep, созданные в этот день и закончившиеся swept.
sweeps_failed обязательно	integer	Sweep, созданные в этот день и закончившиеся failed, — откатились в сети или исчерпали попытки.
sweeps_rejected обязательно	integer	Sweep, созданные в этот день и закончившиеся rejected, — так и не отправлены, потому что проверка перед отправкой не проходила.
revocations_done обязательно	integer	Снятия, созданные в этот день и закончившиеся revoked.
gas_spent обязательно	Amount	Газ транзакций газ-кошелька за день, в wei, без выводов комиссий.
fees обязательно	string	Комиссии и начисления за день за вычетом списаний, в wei; меньше нуля, если списаний больше. Формат: ^-?[0-9]+$.

WebhookDelivery

Событие вебхука и как прошла его доставка.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, как в доставке.
event обязательно	string	Тип события.
status обязательно	string	pending — доставляется или ждёт следующей попытки; delivered — получатель ответил 2xx; failed — попытки кончились или вебхук удалён. Одно из: pending, delivered, failed.
attempts обязательно	integer	Сколько попыток уже было.
last_status_code обязательно	integer | null	HTTP-статус, которым получатель ответил на последнюю попытку; null — не ответил.
last_error обязательно	string | null	Почему последняя попытка не удалась; null, если удалась. status <код> — получатель ответил другим статусом. timeout, connection refused, connection reset, connection closed, DNS lookup failed, TLS error, connection failed — не ответил; private address refused — имя его хоста указывает на непубличный адрес. webhook removed — вебхук удалён. internal — сбой на нашей стороне.
created_at обязательно	string (date-time)	Когда произошло событие.
delivered_at обязательно	string | null (date-time)	Когда событие доставлено; до тех пор — null.
next_attempt_at обязательно	string | null (date-time)	Когда следующая попытка; только у pending.

Balance

Газ-кошелёк и его баланс по сетям.

Поле	Тип	Описание
gas_wallet обязательно	Address	Газ-кошелёк — один адрес во всех сетях.
chains обязательно	массив object
chains[].chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
chains[].name обязательно	string	Название сети.
chains[].native обязательно	string	Тикер нативной монеты сети.
chains[].balance	Amount	Баланс газ-кошелька, в wei; нет, если есть error.
chains[].fees_accrued обязательно	Amount	Все комиссии и начисления в этой сети за вычетом списаний, в wei.
chains[].fees_withdrawn обязательно	Amount	Сколько комиссий выведено, вместе с газом выводов, в wei.
chains[].fees_due обязательно	Amount	Начисленные и ещё не выведенные комиссии, в wei. Они лежат на газ-кошельке в резерве.
chains[].available	Amount	Что остаётся на газ, в wei: balance минус fees_due, но не меньше нуля. Нет, если есть error.
chains[].error	string	chain_unavailable — нода сети не ответила, поэтому баланса нет. Одно из: chain_unavailable.

ChainTariff

Ставки партнёра и эталоны газа в одной сети.

Поле	Тип	Описание
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
name обязательно	string	Название сети.
rate_bps обязательно	integer	X для sweep токенов в базисных пунктах, 7000 = 70%; 0 — без комиссии.
rate обязательно	string	rate_bps в процентах.
native_markup_bps обязательно	integer	Наценка на газ для sweep нативной монеты, в базисных пунктах.
native_markup обязательно	string	native_markup_bps в процентах.
classic_gas	словарь object	Эталон классики для каждого актива, по тикеру токена или нативной монеты: газ на пополнение депозитного адреса и перевод с него. Нет в сети без эталонов.
classic_gas.<ключ>.new обязательно	Gas	Газ для адреса без аккаунта в сети — его создаёт пополнение (только у токенов).
classic_gas.<ключ>.existing обязательно	Gas	Газ для адреса с аккаунтом.
extra_gas	object	Сколько газа батча несёт первый sweep адреса сверх повторного. Нет в сети без эталонов.
extra_gas.delegation обязательно	Gas	Установка делегата на адрес по его авторизации.
extra_gas.account обязательно	Gas	Ещё и создание аккаунта адреса — для адреса, на котором были только токены.

Settings

Поле	Тип	Описание
keep_one_unit	boolean	Sweep токенов оставляет на депозитном адресе 1 минимальную единицу, и следующий депозит пользователя дешевле. Задание может переопределить. По умолчанию выключено.

HotWallet

Горячий кошелёк в одной сети и его делегат.

Поле	Тип	Описание
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
address обязательно	Address	Горячий кошелёк, куда sweep переводят средства.
delegate обязательно	Address	Делегат горячего кошелька — на этот адрес депозитные адреса подписывают авторизацию.
status обязательно	string	pending — делегат разворачивается; active — развёрнут, можно сметать; failed — развернуть не удалось, повторная регистрация кошелька запускает развёртывание снова. Одно из: pending, active, failed.
error	string	Почему развернуть не удалось; только у failed. Чаще всего — insufficient_gas_balance: пополните газ-кошелёк и зарегистрируйте горячий кошелёк снова. not_deployed — транзакция развёртывания прошла, но делегата по его адресу нет. Остальные коды — причины неудачной попытки, как в reason задания на sweep. Одно из: not_deployed, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
tx_hash	string	Транзакция, которая развернула делегат.
created_at обязательно	string (date-time)	Когда горячий кошелёк зарегистрирован.

Authorization

Авторизация EIP-7702, подписанная ключом депозитного адреса: в сети chain_id на адресе работает код address. Как подписать её, в том числе в HSM, KMS и MPC, — в гайде Подпись авторизаций.

Поле	Тип	Описание
chain_id обязательно	integer (int64)	Сеть запроса; 0 (любая сеть) не принимается.
address обязательно	Address	Делегат горячего кошелька из POST /v1/hot-wallets; для снятия делегации — нулевой адрес.
nonce обязательно	integer (int64)	Текущий nonce депозитного адреса.
y_parity обязательно	integer	Чётность y подписи. Одно из: 0, 1.
r обязательно	string	r подписи, 0x-hex до 32 байт. Формат: ^0x[0-9a-fA-F]{1,64}$.
s обязательно	string	s подписи, 0x-hex до 32 байт, в нижней половине порядка кривой (EIP-2). Формат: ^0x[0-9a-fA-F]{1,64}$.

SweepRequest

Что сметать, откуда и куда.

Поле	Тип	Описание
external_id	string	Ваш id задания, уникальный в аккаунте: запрос с уже занятым external_id возвращает то задание, а не создаёт новое, поэтому повторять запрос безопасно. До 128 символов.
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
hot_wallet обязательно	Address	Горячий кошелёк в этой сети; его делегат должен быть active.
account обязательно	Address	Депозитный адрес.
token обязательно	string	Тикер токена из списка сети (в любом регистре), адрес контракта токена из этого списка или native (либо тикер нативной монеты) для нативной монеты.
amount	Amount	Сколько сметать, больше нуля; без поля — весь баланс.
keep_one_unit	boolean	Оставить 1 минимальную единицу токена на депозитном адресе; по умолчанию — из настроек партнёра. Для нативной монеты не действует.
authorization	Authorization	Нужна, пока на депозитном адресе нет делегата этого горячего кошелька. Потом не используется, но присланная всё равно должна быть верной.

Sweep

Задание на sweep и его итог.

Поле	Тип	Описание
id обязательно	string (uuid)
external_id	string	Ваш id задания, если он был в запросе.
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
hot_wallet обязательно	Address	Горячий кошелёк.
account обязательно	Address	Депозитный адрес.
token обязательно	string	Тикер токена или нативной монеты.
token_address	Address	Адрес контракта токена; у нативной монеты его нет.
amount	Amount	Запрошенная сумма; нет, если сметался весь баланс.
keep_one_unit	boolean	Есть и равно true, если sweep оставляет на депозитном адресе 1 минимальную единицу токена.
status обязательно	string	queued — ждёт батча или повтора; processing — в батче, который готовится, отправлен или ждёт подтверждений; swept — готово, средства в горячем кошельке; failed — откатилось в сети или кончились попытки; rejected — не отправлено. Последние три — окончательные. Одно из: queued, processing, swept, failed, rejected.
reason	string	Почему задание закончилось rejected или failed, а пока оно в queued и ждёт повтора — почему не прошла последняя попытка. Это стабильный код: сообщения самой ноды остаются в наших логах. - rejected — проверка перед отправкой так и не прошла: not_upgraded, stale_authorization, would_fail или nothing_to_sweep. - failed в сети, внутри прошедшего батча: ошибка контракта, с которой откатился перевод, — TokenTransferFailed, NativeTransferFailed, NothingToSweep или Unauthorized, или reverted без неё. - Причина неудачной попытки; попытка повторяется, а когда попытки кончились, задание получает failed с этой причиной: insufficient_gas_balance (пополните газ-кошелёк), gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable или internal. Одно из: not_upgraded, stale_authorization, would_fail, nothing_to_sweep, reverted, TokenTransferFailed, NativeTransferFailed, NothingToSweep, Unauthorized, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
attempts обязательно	integer	Сколько раз задание пробовали выполнить.
swept_amount	Amount	Сколько дошло до горячего кошелька; только у swept.
tx_hash	string	Транзакция батча, в которой был sweep.
kind	string	Что понадобилось депозитному адресу в батче; от этого зависят доля газа и эталон. repeat — ничего, делегат уже стоял. first — установка делегата; аккаунт в сети у адреса уже был. first_new — установка делегата, которая заодно создала аккаунт: на адресе были только токены. Одно из: repeat, first, first_new.
gas	Gas	Доля sweep в газе батча.
gas_cost	Amount	То же в wei.
fee	Amount	Комиссия в wei; только у swept.
classic_gas	Gas	Эталон, по которому посчитана комиссия.
rate_bps	integer	Ставка, по которой посчитана комиссия; у нативной монеты — наценка на газ.
created_at обязательно	string (date-time)	Когда задание создано.
updated_at обязательно	string (date-time)	Когда задание менялось в последний раз.

RevocationRequest

С какого депозитного адреса снять делегацию, с его авторизацией на нулевой адрес.

Поле	Тип	Описание
external_id	string	Ваш id снятия, уникальный в аккаунте: запрос с уже занятым external_id возвращает то снятие, а не создаёт новое, поэтому повторять запрос безопасно. До 128 символов.
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
account обязательно	Address	Депозитный адрес.
authorization обязательно	Authorization	Авторизация депозитного адреса с address = 0x0000000000000000000000000000000000000000.

Revocation

Снятие делегации и его итог.

Поле	Тип	Описание
id обязательно	string (uuid)
external_id	string	Ваш id снятия, если он был в запросе.
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
account обязательно	Address	Депозитный адрес.
status обязательно	string	queued и processing — как у sweep; revoked — делегации на депозитном адресе больше нет; failed — транзакция прошла, но сеть пропустила авторизацию, или кончились попытки; rejected — не отправлено. Последние три — окончательные. Одно из: queued, processing, revoked, failed, rejected.
reason	string	Почему снятие закончилось rejected или failed, а пока оно в queued и ждёт повтора — почему не прошла последняя попытка. У rejected: not_delegated (делегации и так нет), stale_authorization (nonce депозитного адреса уже другой) или invalid_authorization. У failed: not_applied (сеть пропустила авторизацию). Остальные коды — причины неудачной попытки, как в reason задания на sweep. Одно из: not_delegated, stale_authorization, invalid_authorization, not_applied, insufficient_gas_balance, gas_limit_exceeded, transaction_reverted, nonce_conflict, chain_unavailable, internal.
attempts обязательно	integer	Сколько раз снятие пробовали выполнить.
tx_hash	string	Транзакция, в которой было снятие.
gas	Gas	Доля снятия в газе транзакции.
gas_cost	Amount	То же в wei.
created_at обязательно	string (date-time)	Когда снятие создано.
updated_at обязательно	string (date-time)	Когда снятие менялось в последний раз.

Webhook

Настройка вебхука.

Поле	Тип	Описание
url обязательно	string (uri)	Куда приходят события.
secret обязательно	string	Секрет подписи, whsec_…. Храните его на бэкенде.
low_balance обязательно	массив object	Алерты о низком балансе газ-кошелька, по одному на сеть.
low_balance[].chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
low_balance[].threshold обязательно	Amount	Порог, в wei.
low_balance[].low обязательно	boolean	Баланс ниже порога, алерт отправлен; он снова взводится, когда баланс восстановится.

Event

Тело доставки вебхука. type говорит, что произошло и что лежит в data: задание на sweep, как в GET /v1/sweeps/{id}; снятие делегации, как в GET /v1/revocations/{id}; горячий кошелёк, как в GET /v1/hot-wallets; алерт о низком балансе или тестовое событие. Задания, снятия и кошельки показываются такими, какие они в момент доставки.

Одно из: SweepEvent, RevocationEvent, HotWalletEvent, BalanceLowEvent, WebhookTestEvent; какое именно — говорит поле type.

SweepEvent

Задание на sweep закончилось. sweep.swept — средства переведены; sweep.failed — откатилось в сети или кончились попытки; sweep.rejected — так и не отправлено.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, во всех попытках один и тот же.
type обязательно	string	Тип события. Одно из: sweep.swept, sweep.failed, sweep.rejected.
created_at обязательно	string (date-time)	Когда произошло событие.
data обязательно	Sweep	Задание на sweep и его итог.

RevocationEvent

Снятие делегации закончилось. revocation.revoked — делегация снята; revocation.failed — сеть пропустила авторизацию или кончились попытки; revocation.rejected — так и не отправлено.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, во всех попытках один и тот же.
type обязательно	string	Тип события. Одно из: revocation.revoked, revocation.failed, revocation.rejected.
created_at обязательно	string (date-time)	Когда произошло событие.
data обязательно	Revocation	Снятие делегации и его итог.

HotWalletEvent

Развёртывание делегата горячего кошелька закончилось. hot_wallet.active — делегат развёрнут; hot_wallet.failed — развернуть не удалось.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, во всех попытках один и тот же.
type обязательно	string	Тип события. Одно из: hot_wallet.active, hot_wallet.failed.
created_at обязательно	string (date-time)	Когда произошло событие.
data обязательно	HotWallet	Горячий кошелёк в одной сети и его делегат.

BalanceLowEvent

Баланс газ-кошелька опустился ниже порога. По событию на каждое падение ниже порога; алерт снова взводится, когда баланс восстановится.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, во всех попытках один и тот же.
type обязательно	string	Тип события. Одно из: balance.low.
created_at обязательно	string (date-time)	Когда произошло событие.
data обязательно	BalanceLow	Алерт о низком балансе.

WebhookTestEvent

Тестовое событие, запрошенное через POST /v1/webhook/test.

Поле	Тип	Описание
id обязательно	string (uuid)	id события, во всех попытках один и тот же.
type обязательно	string	Тип события. Одно из: webhook.test.
created_at обязательно	string (date-time)	Когда произошло событие.
data обязательно	WebhookTest	Данные тестового события.

BalanceLow

Алерт о низком балансе.

Поле	Тип	Описание
chain_id обязательно	ChainID	Идентификатор сети (EIP-155): 11155111 Sepolia и 97 BSC testnet с тестовым ключом, 1 Ethereum и 56 BSC с боевым.
gas_wallet обязательно	Address	Газ-кошелёк.
balance обязательно	Amount	Его баланс в этой сети в момент алерта, в wei.
threshold обязательно	Amount	Порог, ниже которого он опустился, в wei.

WebhookTest

Данные тестового события.

Поле	Тип	Описание
message обязательно	string