Sweep

Sweep переводит токен или нативную монету с депозитного адреса в горячий кошелёк. Задания одного кошелька уходят в сеть батчами.

Список заданий на sweep

GET/v1/sweeps

Задания на sweep, новые первыми. Фильтры можно сочетать.

Параметры

Имя	Где	Тип	Описание
limit	query	integer	Сколько строк на странице. От 1 до 200. По умолчанию 50.
cursor	query	string	next_cursor прошлой страницы; для первой страницы не нужен.
status	query	string	Только задания с этим статусом. Одно из: queued, processing, swept, failed, rejected.
chain_id	query	ChainID	Только эта сеть.
account	query	Address	Только задания с этого депозитного адреса.
hot_wallet	query	Address	Только задания в этот горячий кошелёк.

Ответы

Код	Описание
200	Страница заданий. Возвращает поля ниже.
400	invalid_query — параметр запроса не подходит; какой — в message.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.

Тело ответа

Поле	Тип	Описание
items обязательно	массив Sweep
next_cursor обязательно	NextCursor	Курсор следующей страницы; на последней — null.

Пример запроса

curl "https://api-testnet.portuna.io/v1/sweeps?chain_id=11155111&status=swept&limit=1" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Пример ответа

200 OK

{
  "items": [
    {
      "id": "8a6e2f31-0c4b-4d7a-b1e5-92f3c6d8a047",
      "external_id": "dep-80c2d4",
      "chain_id": 11155111,
      "hot_wallet": "0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769",
      "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
      "token": "USDT",
      "token_address": "0x5B74f75040584b133Ff1EB67eEe646B0da26e39C",
      "status": "swept",
      "attempts": 1,
      "swept_amount": "250000000",
      "tx_hash": "0xe2a3d8ffdcd7c4ed8a2389a59ce91622863c495d052a7571206bb494919dc35b",
      "kind": "repeat",
      "gas": 18078,
      "gas_cost": "21693600000000",
      "fee": "23358000000000",
      "classic_gas": 53633,
      "rate_bps": 7000,
      "created_at": "2026-10-11T07:02:15Z",
      "updated_at": "2026-10-11T07:03:02Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMVQwNzowMjoxNVoiLCJpZCI6IjhhNmUyZjMxIn0"
}

Создать задание на sweep

POST/v1/sweeps

Сметает токен или нативную монету с депозитного адреса в горячий кошелёк. Задания одного кошелька, пришедшие к моменту отправки, уходят одним батчем. Пока на депозитном адресе нет делегата, в запросе нужна его авторизация, authorization. Итог приходит событием вебхука sweep.swept, sweep.failed или sweep.rejected и виден в GET /v1/sweeps/{id}.

Тело запроса

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

Ответы

Код	Описание
200	Задание с этим external_id уже есть. Возвращается оно в текущем состоянии, нового задания не создаётся. Возвращает Sweep.
202	Задание в очереди. Возвращает Sweep.
400	invalid_json — тело не JSON, больше 64 КиБ или в нём неизвестные поля.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.
409	hot_wallet_not_active — делегат горячего кошелька ещё разворачивается или не развернулся.
422	unknown_chain, invalid_external_id, invalid_address, unknown_token, invalid_amount, unknown_hot_wallet (горячий кошелёк не зарегистрирован в этой сети) или invalid_authorization; что не так — в message.

Пример запроса

curl -X POST "https://api-testnet.portuna.io/v1/sweeps" \
  -H "Authorization: Bearer $PORTUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "external_id": "dep-7f3a91",
  "chain_id": 11155111,
  "hot_wallet": "0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769",
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "token": "USDT",
  "authorization": {
    "chain_id": 11155111,
    "address": "0xE60fdf70a794C76094f86b990a821D55e3096AA5",
    "nonce": 0,
    "y_parity": 0,
    "r": "0x15fc7bd79ea3d30b5c40814f1c7ce35274d35ad96f9654d1379680d15cbba039",
    "s": "0x7e9e601a6b0c3e554c8befe6ae019c344b115cf061994e9388787bd39e76bb83"
  }
}'

Пример ответа

202 Accepted

{
  "id": "3d0c5d0e-6b7f-4a5e-9a51-3c8f0b2e7d14",
  "external_id": "dep-7f3a91",
  "chain_id": 11155111,
  "hot_wallet": "0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769",
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "token": "USDT",
  "token_address": "0x5B74f75040584b133Ff1EB67eEe646B0da26e39C",
  "status": "queued",
  "attempts": 0,
  "created_at": "2026-10-10T09:20:41Z",
  "updated_at": "2026-10-10T09:20:41Z"
}

Задание на sweep

GET/v1/sweeps/{id}

Параметры

Имя	Где	Тип	Описание
id обязательно	path	string (uuid)	id задания.

Ответы

Код	Описание
200	Задание. Возвращает Sweep.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.
404	not_found — такого объекта у партнёра нет.

Пример запроса

curl "https://api-testnet.portuna.io/v1/sweeps/8a6e2f31-0c4b-4d7a-b1e5-92f3c6d8a047" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Пример ответа

200 OK

{
  "id": "8a6e2f31-0c4b-4d7a-b1e5-92f3c6d8a047",
  "external_id": "dep-80c2d4",
  "chain_id": 11155111,
  "hot_wallet": "0x2Cd50979a8A33e8CA37DA85F8517fb148a67b769",
  "account": "0x2c7536E3605D9C16a7a3D7b1898e529396a65c23",
  "token": "USDT",
  "token_address": "0x5B74f75040584b133Ff1EB67eEe646B0da26e39C",
  "status": "swept",
  "attempts": 1,
  "swept_amount": "250000000",
  "tx_hash": "0xe2a3d8ffdcd7c4ed8a2389a59ce91622863c495d052a7571206bb494919dc35b",
  "kind": "repeat",
  "gas": 18078,
  "gas_cost": "21693600000000",
  "fee": "23358000000000",
  "classic_gas": 53633,
  "rate_bps": 7000,
  "created_at": "2026-10-11T07:02:15Z",
  "updated_at": "2026-10-11T07:03:02Z"
}