Аккаунт

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

Баланс газ-кошелька

GET/v1/balance

Газ-кошелёк, его баланс и комиссии по каждой сети. Газ-кошелёк — один адрес во всех сетях. Комиссии к выводу (fees_due) лежат на нём в резерве и на газ не тратятся; available — то, что остаётся на газ.

Ответы

Код	Описание
200	Баланс по каждой сети. Возвращает Balance.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.

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

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

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

200 OK

{
  "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/v1/tariff

Ставки партнёра по сетям и эталоны газа, по которым считается комиссия. Комиссия за sweep токена — max(0; X × эталон классики − газ sweep), где X — rate_bps. За sweep нативной монеты — наценка на газ sweep, native_markup_bps, но не больше того, что sweep экономит по сравнению с обычным переводом за 21 000 газа. Всё считается в газе по цене газа батча.

Ответы

Код	Описание
200	Тариф по каждой сети. Возвращает поля ниже.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.

Тело ответа

Поле	Тип	Описание
chains обязательно	массив ChainTariff

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

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

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

200 OK

{
  "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/v1/settings

Ответы

Код	Описание
200	Настройки партнёра. Возвращает Settings.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.

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

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

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

200 OK

{
  "keep_one_unit": false
}

Изменить настройки

PATCH/v1/settings

Меняет только поля из запроса, остальные остаются как были.

Тело запроса

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

Ответы

Код	Описание
200	Настройки после изменения. Возвращает Settings.
400	invalid_json — тело не JSON, больше 64 КиБ или в нём неизвестные поля.
401	unauthorized — нет API-ключа, он неизвестен или отозван.
403	partner_disabled — аккаунт партнёра отключён.

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

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

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

200 OK

{
  "keep_one_unit": true
}

Движения по газ-кошельку

GET/v1/ledger

Всё, что меняло баланс газ-кошелька, новые первыми: газ транзакций, комиссии, начисления и списания по договору, вывод комиссий и пополнения. Комиссии (fee, fee_charge) остаются на кошельке в резерве, пока их не выведет withdrawal, поэтому вывод — не новая трата, а уход этого резерва с кошелька вместе с газом вывода.

Параметры

Имя	Где	Тип	Описание
limit	query	integer	Сколько строк на странице. От 1 до 200. По умолчанию 50.
cursor	query	string	next_cursor прошлой страницы; для первой страницы не нужен.
chain_id	query	ChainID	Только эта сеть.
kind	query	LedgerKind	Только движения этого вида. Одно из: gas, fee, fee_charge, fee_credit, withdrawal, topup.

Ответы

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

Тело ответа

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

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

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

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

200 OK

{
  "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/v1/usage

Каждый день из последних days, включая сегодняшний, по дням UTC, старые первыми — в каждой сети окружения (или только в chain_id), дни без работы с нулями. Sweep и снятия считаются в день, когда созданы, по тому, чем закончились; газ — в день транзакции, комиссии — в день начисления.

Параметры

Имя	Где	Тип	Описание
days	query	integer	Сколько дней вернуть, включая сегодняшний. От 1 до 90. По умолчанию 30.
chain_id	query	ChainID	Только эта сеть.

Ответы

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

Тело ответа

Поле	Тип	Описание
days обязательно	массив UsageDay

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

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

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

200 OK

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