Account

Your gas wallet and its balance on each chain, your tariff and your settings.

Get the balance

GET/v1/balance

Your gas wallet and its balance and fees on each chain. The gas wallet is one address on every chain. Fees due (fees_due) stay on it in reserve and are not spent on gas; available is what is left for gas.

Responses

Status	Description
`200`	The balance on each chain. Returns Balance.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.

Example request

curl "https://api-testnet.portuna.io/v1/balance" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

{
  "gas_wallet": "0xf0259b04f5D336E624A84780d1B365fAFc3f5A85",
  "chains": [
    {
      "chain_id": 97,
      "name": "bsc-testnet",
      "native": "BNB",
      "balance": "100000000000000000",
      "fees_accrued": "0",
      "fees_withdrawn": "0",
      "fees_due": "0",
      "available": "100000000000000000"
    },
    {
      "chain_id": 11155111,
      "name": "sepolia",
      "native": "ETH",
      "balance": "48712400000000000",
      "fees_accrued": "23358000000000",
      "fees_withdrawn": "0",
      "fees_due": "23358000000000",
      "available": "48689042000000000"
    }
  ]
}

Get the tariff

GET/v1/tariff

Your rates on each chain and the gas benchmarks your fees are computed with. The fee for a token sweep is max(0; X × classic benchmark − gas of the sweep), where X is rate_bps. For a native coin sweep it is a markup on the sweep’s gas, native_markup_bps, but never more than the sweep saves against a plain 21,000-gas transfer. Everything is counted in gas, at the batch’s gas price.

Responses

Status	Description
`200`	The tariff on each chain. Returns the fields below.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.

Response body

Field	Type	Description
`chains` required	array of ChainTariff

Example request

curl "https://api-testnet.portuna.io/v1/tariff" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

{
  "chains": [
    {
      "chain_id": 97,
      "name": "bsc-testnet",
      "rate_bps": 0,
      "rate": "0%",
      "native_markup_bps": 0,
      "native_markup": "0%",
      "classic_gas": {
        "BNB": {
          "new": 21000,
          "existing": 21000
        },
        "USDT": {
          "new": 50667,
          "existing": 50667
        }
      },
      "extra_gas": {
        "delegation": 15176,
        "account": 2824
      }
    },
    {
      "chain_id": 11155111,
      "name": "sepolia",
      "rate_bps": 7000,
      "rate": "70%",
      "native_markup_bps": 1000,
      "native_markup": "10%",
      "classic_gas": {
        "ETH": {
          "new": 21000,
          "existing": 21000
        },
        "USDT": {
          "new": 237233,
          "existing": 53633
        }
      },
      "extra_gas": {
        "delegation": 49106,
        "account": 176503
      }
    }
  ]
}

Get the settings

GET/v1/settings

Responses

Status	Description
`200`	Your settings. Returns Settings.
`401`	`unauthorized`: no API key, an unknown one or a revoked one.
`403`	`partner_disabled`: your account is disabled.

Example request

curl "https://api-testnet.portuna.io/v1/settings" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

{
  "keep_one_unit": false
}

Update the settings

PATCH/v1/settings

Changes only the fields in the request and keeps the others.

Request body

Field	Type	Description
`keep_one_unit`	boolean	Token sweeps leave 1 smallest unit on the deposit address, which makes your user’s next deposit cheaper. A sweep request can override it. Off by default.

Responses

Status	Description
`200`	The settings after the change. Returns Settings.
`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.

Example request

curl -X PATCH "https://api-testnet.portuna.io/v1/settings" \
  -H "Authorization: Bearer $PORTUNA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "keep_one_unit": true
}'

Example response

{
  "keep_one_unit": true
}

List gas wallet entries

GET/v1/ledger

Everything that moved your gas wallet’s balance, newest first: the gas of transactions, fees, charges and credits under your agreement, withdrawals of fees and top-ups. Fees (fee, fee_charge) stay on the wallet in reserve until a withdrawal takes them, so a withdrawal is not a new expense: it is that reserve leaving the wallet, together with the withdrawal’s gas.

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.
`chain_id`	query	ChainID	Only this chain.
`kind`	query	LedgerKind	Only entries of this kind. One of: `gas`, `fee`, `fee_charge`, `fee_credit`, `withdrawal`, `topup`.

Responses

Status	Description
`200`	A page of entries. 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 LedgerEntry
`next_cursor` required	NextCursor	The cursor of the next page; `null` on the last page.

Example request

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

Example response

{
  "items": [
    {
      "id": 1042,
      "chain_id": 11155111,
      "kind": "fee",
      "amount": "-23358000000000",
      "tx_hash": "0xe2a3d8ffdcd7c4ed8a2389a59ce91622863c495d052a7571206bb494919dc35b",
      "sweep_id": "8a6e2f31-0c4b-4d7a-b1e5-92f3c6d8a047",
      "note": null,
      "created_at": "2026-10-11T07:03:02Z"
    },
    {
      "id": 1041,
      "chain_id": 11155111,
      "kind": "gas",
      "amount": "-3791988000000000",
      "tx_hash": "0xe2a3d8ffdcd7c4ed8a2389a59ce91622863c495d052a7571206bb494919dc35b",
      "sweep_id": null,
      "note": null,
      "created_at": "2026-10-11T07:03:02Z"
    },
    {
      "id": 1017,
      "chain_id": 11155111,
      "kind": "topup",
      "amount": "50000000000000000",
      "tx_hash": null,
      "sweep_id": null,
      "note": "blocks 9402114–9402415",
      "created_at": "2026-10-10T09:05:11Z"
    }
  ],
  "next_cursor": "eyJ0IjoiMjAyNi0xMC0xMFQwOTowNToxMVoiLCJpZCI6MTAxN30"
}

Get daily usage

GET/v1/usage

Each of the last days days, today included, by UTC day, oldest first, on every chain of the environment (or only on chain_id), with zeros for days without activity. Sweeps and revocations count on the day they were created, by how they ended; gas counts on the day of its transaction, fees on the day they accrued.

Parameters

Name	In	Type	Description
`days`	query	integer	How many days to return, today included. From 1 to 90. Default: `30`.
`chain_id`	query	ChainID	Only this chain.

Responses

Status	Description
`200`	A row for each day and chain. 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
`days` required	array of UsageDay

Example request

curl "https://api-testnet.portuna.io/v1/usage?days=2&chain_id=11155111" \
  -H "Authorization: Bearer $PORTUNA_API_KEY"

Example response

{
  "days": [
    {
      "date": "2026-10-10",
      "chain_id": 11155111,
      "sweeps_done": 3,
      "sweeps_failed": 0,
      "sweeps_rejected": 1,
      "revocations_done": 0,
      "gas_spent": "1427640000000000",
      "fees": "0"
    },
    {
      "date": "2026-10-11",
      "chain_id": 11155111,
      "sweeps_done": 50,
      "sweeps_failed": 0,
      "sweeps_rejected": 0,
      "revocations_done": 1,
      "gas_spent": "3826548000000000",
      "fees": "934320000000000"
    }
  ]
}