Sweeps

A sweep moves a token or the native coin from a deposit address to a hot wallet. Sweeps of one hot wallet go on chain in batches.

List sweeps

GET/v1/sweeps

Your sweeps, newest first. The filters combine.

Parameters

Name	In	Type	Description
`limit`	query	integer	How many rows a page holds. From 1 to 200. Default: `50`.
`cursor`	query	string	The `next_cursor` of the previous page; none for the first page.
`status`	query	string	Only sweeps with this status. One of: `queued`, `processing`, `swept`, `failed`, `rejected`.
`chain_id`	query	ChainID	Only this chain.
`account`	query	Address	Only sweeps from this deposit address.
`hot_wallet`	query	Address	Only sweeps to this hot wallet.

Responses

Status	Description
`200`	A page of sweeps. Returns the fields below.
`400`	`invalid_query`: a query parameter is not valid; `message` says which.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.

Response body

Field	Type	Description
`items` required	array of Sweep
`next_cursor` required	NextCursor	The cursor of the next page; `null` on the last page.

Example request

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

Example response

{
  "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"
}

Create a sweep

POST/v1/sweeps

Sweeps a token or the native coin from a deposit address to a hot wallet. Sweeps of one hot wallet that have arrived by the time a batch is sent go in that one batch. Until the deposit address is delegated, the request carries its authorization. The outcome comes in a sweep.swept, sweep.failed or sweep.rejected webhook event and shows in GET /v1/sweeps/{id}.

Request body

Field	Type	Description
`external_id`	string	Your id for the sweep, unique in your account: a request with an `external_id` that is already taken returns that sweep instead of creating another, so retries are safe. Up to 128 characters.
`chain_id` required	ChainID	The chain’s id (EIP-155): `11155111` Sepolia and `97` BSC testnet with a test key, `1` Ethereum and `56` BSC with a live key.
`hot_wallet` required	Address	Your hot wallet on this chain; its delegate must be `active`.
`account` required	Address	The deposit address.
`token` required	string	A token’s ticker listed on the chain (in any case), the contract address of a listed token, or `native` (or the native coin’s ticker) for the native coin.
`amount`	Amount	How much to sweep, above zero; without it, the whole balance.
`keep_one_unit`	boolean	Leave 1 smallest unit of the token on the deposit address; defaults to your settings. Ignored for the native coin.
`authorization`	Authorization	Needed until the deposit address is delegated to this hot wallet’s delegate. After that it is not used, though one that is sent must still be valid.
`authorization.chain_id` required	integer (int64)	The chain of the request; 0 (any chain) is refused.
`authorization.address` required	Address	The hot wallet’s delegate from `POST /v1/hot-wallets`; the zero address for a revocation.
`authorization.nonce` required	integer (int64)	The deposit address’s current nonce.
`authorization.y_parity` required	integer	The signature’s y parity. One of: `0`, `1`.
`authorization.r` required	string	The signature’s r, `0x`-hex of up to 32 bytes. Format: `^0x[0-9a-fA-F]{1,64}$`.
`authorization.s` required	string	The signature’s s, `0x`-hex of up to 32 bytes, in the lower half of the curve order (EIP-2). Format: `^0x[0-9a-fA-F]{1,64}$`.

Responses

Status	Description
`200`	A sweep with this `external_id` already exists. It is returned as it is now, and no other sweep is created. Returns Sweep.
`202`	The sweep is queued. Returns Sweep.
`400`	`invalid_json`: the body is not JSON, is over 64 KiB or has unknown fields.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`409`	`hot_wallet_not_active`: the hot wallet’s delegate is still being deployed, or its deployment failed.
`422`	`unknown_chain`, `invalid_external_id`, `invalid_address`, `unknown_token`, `invalid_amount`, `unknown_hot_wallet` (the hot wallet is not registered on this chain) or `invalid_authorization`; `message` says what is wrong.

Example request

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"
  }
}'

Example response

{
  "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"
}

Get a sweep

GET/v1/sweeps/{id}

Parameters

Name	In	Type	Description
`id` required	path	string (uuid)	The sweep’s `id`.

Responses

Status	Description
`200`	The sweep. Returns Sweep.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.
`404`	`not_found`: there is no such object in your account.

Example request

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

Example response

{
  "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"
}