# Баланс

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

У проекта, которому оператор включил прямые сборы, этот баланс остаётся нулевым: деньги каждого платежа пересылаются на собственный кошелёк проекта, а не хранятся, — см. [куда уходят деньги](https://stons.io/ru/docs/invoices.md#куда-уходят-деньги). Ноль здесь значит, что деньги уже пришли, а не что проекту не платили.

## Запрос

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

В ответе есть `ETag`, поэтому продукт, который держит баланс на экране, платит за один `304`, пока ничего не менялось, — см. [условные чтения](https://stons.io/ru/docs/authentication.md#условные-чтения).

## Ответ

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

| Поле | Тип | Описание |
| --- | --- | --- |
| `balances[].asset` | string | Идентификатор актива, например `USDT_TRON`, — см. [активы](https://stons.io/ru/docs/invoices.md#активы) |
| `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`, когда подтвердится, — см. [статусы](https://stons.io/ru/docs/invoices.md#статусы).
- **В суммах все знаки после точки их актива**, как и везде в этом API: считайте их в строке, а не вшивайте число 6 в свой код, — см. [суммы](https://stons.io/ru/docs/invoices.md#суммы).
- **Доллары — справочные.** Это суммы по последнему принятому сервисом курсу, центы округлены к нулю, поэтому итог может отличаться от суммы округлённых строк на цент на строку. Актив, у монеты которого нет свежего курса, никогда не считается по устаревшему: вместо этого он назван в `unpriced_assets`.

## Ошибки

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

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

## Пример

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

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

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