Баланс

GET /v1/balance отдаёт деньги проекта: баланс каждого актива, в котором у него что-то есть, и те же деньги в долларах США. Читайте его для своей панели, перед запросом вывода и для сверки своего учёта с сервисом.

У проекта, которому оператор включил прямые сборы, этот баланс остаётся нулевым: деньги каждого платежа пересылаются на собственный кошелёк проекта, а не хранятся, — см. куда уходят деньги. Ноль здесь значит, что деньги уже пришли, а не что проекту не платили.

Запрос

У запроса нет параметров и тела.

В ответе есть ETag, поэтому продукт, который держит баланс на экране, платит за один 304, пока ничего не менялось, — см. условные чтения.

Ответ

200 с balances — по строке на актив — и total: те же строки, сложенные в долларах. Актива, в котором у проекта нет денег, в ответе нет: проект, которому ещё не платили, получает пустой массив и нулевые итоги.

Поле	Тип	Описание
`balances[].asset`	string	Идентификатор актива, например `USDT_TRON`, — см. активы
`balances[].network`	string	Идентификатор сети актива, например `tron`
`balances[].balance`	string	Баланс в единицах актива, со всеми его знаками после точки. Со знаком минус, если выплаты увели его ниже нуля
`balances[].unconfirmed`	string	Платежи, увиденные в сети и ещё не подтверждённые, в единицах актива. В `balance` не входят
`balances[].balance_usd`	string или null	`balance` по курсу, в долларах и центах; `null`, если у сервиса нет свежего курса монеты
`balances[].unconfirmed_usd`	string или null	`unconfirmed` по тому же курсу; `null` при том же условии
`total.balance_usd`	string	Балансы активов, у которых есть свежий курс, сложенные
`total.unconfirmed_usd`	string	Неподтверждённые платежи этих активов, сложенные
`total.unpriced_assets`	array of string	Активы, в которых деньги есть, а свежего курса нет: они есть в `balances` и не входят в суммы
`total.rates_observed_at`	string или null	Когда принят самый старый курс из сумм; `null`, если в суммах нет ни одного курса

Строки идут от большей долларовой стоимости к меньшей, активы без курса — последними.

Откуда берутся числа

balance — это баланс по реестру, сумма журнала проекта, а не хранимое число, которое что-то могло забыть обновить. Платёж добавляет к нему, когда у перевода достаточно подтверждений; выплата и вывод — забирают. Исправление делается сторнирующей проводкой, поэтому баланс всегда равен истории, которая его дала.
unconfirmed стоит рядом с балансом, а не внутри. Перевод, у которого мало подтверждений, может исчезнуть при реорганизации цепи, то есть это ещё не деньги. Он войдёт в balance, когда подтвердится, — см. статусы.
В суммах все знаки после точки их актива, как и везде в этом API: считайте их в строке, а не вшивайте число 6 в свой код, — см. суммы.
Доллары — справочные. Это суммы по последнему принятому сервисом курсу, центы округлены к нулю, поэтому итог может отличаться от суммы округлённых строк на цент на строку. Актив, у монеты которого нет свежего курса, никогда не считается по устаревшему: вместо этого он назван в unpriced_assets.

Ошибки

HTTP	`error.code`	Когда
401	`unauthorized`	Ключ API отсутствует или неверен
403	`merchant_disabled`	Мерчант отключён
429	`rate_limited`	Превышен лимит запросов
500	`internal_error`	Необработанная ошибка сервиса

Мерчант, не прошедший проверку на ревью, свой баланс читать может.

Пример

curl -s https://api.stons.io/v1/balance -H "X-Api-Key: $API_KEY"

200, проект, которому зачислено 100 USDT в TRON, и ещё 5 USDT набирают подтверждения:

{
  "balances": [
    {
      "asset": "USDT_TRON",
      "network": "tron",
      "balance": "100.000000",
      "unconfirmed": "5.000000",
      "balance_usd": "99.96",
      "unconfirmed_usd": "4.99"
    }
  ],
  "total": {
    "balance_usd": "99.96",
    "unconfirmed_usd": "4.99",
    "unpriced_assets": [],
    "rates_observed_at": "2026-10-04T17:31:05.531Z"
  }
}