> For the complete documentation index, see [llms.txt](https://docs.goodcrypto.app/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/api.md).

# Программный API

Читай данные и торгуй из своей программы через локальный API goodcryptoX с теми же ключами и лимитами, что у ИИ-агента.

Твоя программа читает и торгует на подключенных биржах через API goodcryptoX, описанный в OpenAPI. Ключи, разрешения и лимиты те же, что у ИИ-агента ([Ключи и лимиты](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) заново считывает разрешения API-ключа аккаунта Binance, Bybit или Bybit EU, как кнопка **Проверить еще раз** в его карточке.

Каждая цифра приходит в валюте своей сделки: цены и стоимости в валюте котировки рынка, PnL в активе, который называет его строка, кредиты и `GET /api/v1/portfolio` в USD, лимиты ключа в валюте, в которой их задали. `GET /api/v1/rates` отвечает твоей базовой валютой и ее курсом за 1 USD, чтобы показать цифру так, как ее показывает goodcryptoX.

Инструмент MCP `instruments` и `GET /api/v1/instruments?venue=…` включают известные для каждого рынка объем за 24 часа (в валюте котировки), изменение цены (в процентах) и цену последней сделки, если биржа ее передает. API также предоставляет `instrument-stats/<venue>` через [маршрут топиков](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket). Эти значения остаются десятичными строками. Для объема и изменения цены null сохраняет предыдущее известное значение; необязательное поле `invalidate` указывает, какие значения очистить. Если `lastPrice` отсутствует, прежняя цена сохраняется для совместимости; явно переданный null ее очищает.

В **Настройки › MCP & API** создай ключ ([как](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)); на стороне **API** блока подключения появятся три строки с кнопками копирования: **Адрес**, **Ключ** и заголовок для каждого запроса с выбранным ключом — `Authorization: Bearer <your key>`. Кнопка рядом с заголовком копирует его целиком.

<details>

<summary>Пример запроса API</summary>

Задай `GCX_URL` как адрес установки, доступный программе, и передай `GCX_KEY` через окружение. Пример читает аккаунты:

```sh
curl --fail-with-body -H "Authorization: Bearer $GCX_KEY" "$GCX_URL/api/v1/accounts"
```

Документ OpenAPI находится на `$GCX_URL/api/v1/openapi.json`. Программа запрашивает его с тем же заголовком Bearer; описание содержит только доступные ключу вызовы. Суммы, цены и размеры — десятичные строки.

</details>

Демо-аккаунты и режим Bybit для разработчиков, включая отправку с ключом только для чтения и восстановление, доступны людям, вошедшим в панель. Ключи доступа и MCP не могут использовать `demoBybitView` или `demo=1`.

## С другого компьютера <a href="#from-another-computer" id="from-another-computer"></a>

Для программы на другом компьютере запусти там коннектор в режиме `connect`: пока он работает, установка доступна по локальному адресу ([подключение](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#from-another-computer)). Нажми **Показать** рядом с **Cursor и другие приложения** на том компьютере и запусти коннектор со значениями `env` (кроме `GCX_URL` и `GCX_KEY`; программа отправляет свой ключ):

```sh
GCX_RELAY=… GCX_MAILBOX=… GCX_R=… GCX_PROFILE=… GCX_PAIR=… npx -y goodcryptox-connector@<version>-<build> connect --profile <the GCX_PROFILE value>
```

Он выведет адрес подключения, затем адрес API с окончанием `/api/v1`. Оставь его работающим, пока программа использует соединение; первый адрес используй как `GCX_URL`, например `http://127.0.0.1:8130`.

<details>

<summary>Следующие запуски и смена адреса</summary>

Позже запускай `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>`: сохраненное подключение используется повторно. У каждой установки свой профиль и адрес. Если адрес занят, добавь `--choose-new-address` и скопируй новый адрес в программу.

</details>

Без соединения вызовы завершаются ошибкой и не сохраняются на потом. Для доступа без ретранслятора используй [SSH-туннель](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Если открыть goodcryptoX по [домашнему адресу](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), **Адрес** на стороне **API** будет этим адресом: программа в той же сети отправляет туда запросы со своим ключом, без коннектора и нашего ретранслятора, и берет адрес без `/api/v1` как `GCX_URL`. Используй его в сети, которой доверяешь, или через свой доверенный HTTPS-адрес: по HTTP тот, кто может читать трафик, может скопировать ключ.

## Отправка ордера <a href="#sending-an-order" id="sending-an-order"></a>

Сначала запроси предпросмотр ([Проверка ордера перед отправкой](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Затем `POST /api/v1/orders` с телом:

```json
{
  "requestId": "my-strategy-0001",
  "sourceId": "YOUR-ACCOUNT-ID",
  "instrumentId": "ETH",
  "type": "limit",
  "side": "buy",
  "size": "90",
  "sizeUnit": "quote",
  "price": "3000",
  "overrides": [],
  "bracket": {
    "reduceOnly": true,
    "tp": { "type": "market", "mode": "percent", "targets": [{ "value": "3", "share": "100" }] },
    "sl": { "type": "market", "mode": "percent", "value": "1.5" }
  }
}
```

Если плечо аккаунта ещё не прочитано, ордер на бессрочный контракт отправляется, а биржа применяет своё плечо; в квитанции предпросмотра тогда нет данных о средствах, и маржа не проверена.

Ордер, размер которого задан в валюте котировки (`"sizeUnit": "quote"` или `"coin"` на контракте с маржой в монете), сохраняет эту сумму: количество монет пересчитывается при каждой отправке по цене отправки (лимитный — по своей цене после каждого ее изменения; стоп — при срабатывании). Строка ордера показывает сумму как `cost` и `sizeUnit` рядом с `size` — текущим количеством монет. Значение не ниже минимума биржи округляется вверх на один шаг размера, если округление вниз опустило бы его ниже минимума, поэтому стоимость `size` в строке может превышать отправленную сумму на величину до одного шага. Если размер больше нуля, но после этого округления остаётся меньше одного шага и отправлять нечего, ордер размещается с размером в один шаг по количеству монет. Ответ указывает это: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`; нулевой размер отклоняется. Для изменения `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) принимает `changes.sizeUnit` вместе с `size`: `{"size": "150", "sizeUnit": "quote"}` задает сумму 150, `{"price": "2900"}` сохраняет сумму при новой цене, а один `size` задает монеты.

Ордер со стоимостью ниже минимума биржи отправляется таким, как ты его передаёшь (предпросмотр предупреждает через `trade.msgMinNotional`); ответ биржи и есть результат. Боты делают то же: вход и усредняющие ордера DCA-бота и уровни грида ниже минимума отправляются, а отклонённый биржей ордер становится неудавшимся ордером бота (уровень DCA `failed`, счётчик `failed` грида); «Повторить» или «Исправить» отправляет его снова. Строка ордера в предпросмотре бота помечает такой ордер как `under`; `sent` false означает только ордер, слишком маленький для отправки. Строка грида с `sendAll` размещает все уровни; без него (запущенная более ранней версией) удерживает уровни ниже минимума.

На рынке с маржой в монете (`contract.method` — `"DIV"`) размеры ордеров, позиций и ботов возвращаются в контрактах вместе с параметрами контракта: USD = контракты × `contract.multiplier`, а монета = эти USD ÷ цена. Бот DCA с размером в `"sizingMode": "coin"` принимает `entryAmount` и `level1Amount` в расчётной монете контракта (`contract.settlement`): каждый ордер — это количество монет по собственной цене, округлённое вниз до целых контрактов. `"cost"` задаёт одинаковую сумму в USD для каждого ордера; если сумма в USD меньше стоимости одного контракта, за исходную сумму берётся стоимость одного контракта в USD, и от неё рассчитывается каждый уровень с учётом множителя.

На аккаунте с выбранным «Режим хеджирования» у фьючерсного рынка два идентификатора, `…:long` и `…:short`, а сторона открывает или закрывает позицию: продажа на лонге или покупка на шорте только уменьшает эту позицию, с `reduceOnly` или без; `reduceOnly: true` на другой стороне отклоняется (`reduce-only-opens`).

Потерянный ответ после отправки не означает сбой ордера: проверь результат до повтора. При повторе торгового запроса сохраняй те же `requestId` и тело, чтобы не разместить ордер дважды.

`POST /api/v1/margin` добавляет (положительный `amount`) или снимает (отрицательный) изолированную маржу позиции на Hyperliquid, Binance и Bybit в ее монете маржи (MCP `change_margin`). Bybit EU поддерживает только спот. Торговый ключ делает это на аккаунтах и рынках из его лимитов, как при установке плеча: ключ без лимитов или для другого аккаунта или рынка получает 422 `key.*`, и ничего не отправляется.

Тела запросов и сообщения отказа всех маршрутов — в документе OpenAPI на `/api/v1/openapi.json`.

## Настройки, которые меняешь только ты <a href="#settings-only-you-change" id="settings-only-you-change"></a>

Некоторые маршруты меняют то, что решаешь только ты: ключ, который их вызывает, получает 403 `person-only` с фразой, которую нужно передать тебе, и на биржу ничего не отправляется. Их инструменты MCP есть, чтобы агент мог сказать тебе, что сделать.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) включает или выключает **Платить комиссии в BNB** для аккаунта Binance (MCP `set_bnb_fees`). Строка аккаунта в `GET /api/v1/accounts` показывает это как `bnbFees`: `on` и настройки за ним, `spot` и `usdm`.

Переключатель **Залог** у монеты тоже доступен для изменения только тебе: `POST /api/v1/accounts/{id}/collateral` отвечает ключу 403 и не имеет инструмента MCP. Программа читает настройку в теме `balances` (`perCoinCollateral`: кошелёк и для каждой монеты `accepted`, `selected` и `fixed`; null означает неизвестное значение, а не выключенное), либо запрашивает одну монету на бирже прямо сейчас через `GET /api/v1/accounts/{id}/collateral?coin=BTC` (`{coin, accepted, selected}`; 503, если чтение не удалось или заняло больше десяти секунд).

Удалять аккаунты можешь только ты: `POST /api/v1/accounts/{sourceId}/remove` работает также для Binance, Bybit и Bybit EU; инструмента MCP для удаления аккаунтов нет.

## Отзыв предложения <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

Ключ, предложивший ордер или бота, может отозвать его до твоего решения: `POST /api/v1/proposals/{id}/withdraw` с `{"requestId": "..."}`, права **Предложения** или выше. Ответ — `{"accepted": true}`; повтор дает тот же ответ. Чужое предложение отвечает 404, будто его нет; запущенное тобой — 422 `proposal-launched`, отклоненное — 422 `proposal-rejected`. Отклонение остается за тобой: ключ не может отклонять.

## Списки по нескольким аккаунтам <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` и `GET /api/v1/lists/orders` читают все аккаунты, которые охватывает список. Если биржа не дала прочитать один аккаунт, остальные не скрываются: `state` страницы остаётся `live`, пока прочитан хотя бы один аккаунт, а `accountStates` даёт состояние каждого (`live`, `stale`, `unavailable` или `waiting` при первом чтении), чтобы ты знал, чьих строк может не хватать. `state` страницы становится `stale` или `unavailable`, только когда не удалось прочитать ни одного аккаунта. «Отменить все», «Остановить все» и «Закрыть все» отвечают по каждому ордеру, боту или позиции отдельно: неудавшееся действие попадает в `refused` со своим сообщением, а остальные учитываются в `count` и `ids`.

## Ордера бота со сбоем <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Отклоненный ордер усреднения DCA или ордер сетки не останавливает бота, поэтому его нет ни в строках внимания, ни в `items` бота; там только то, что останавливает бота или ждет тебя. Неудавшиеся усредняющие ордера DCA-бота читай в `counters.averagingFailed` его строки, ордера сетки — в ее `failed` (следующий раздел), а каждый такой ордер — в его строке ордера: `why` — фраза, которую показывает панель, `errorType` — тип, который за ней стоит, `exchangeWords` — собственные слова биржи; инструменты MCP читают те же строки. `errorType` — открытая строка: показывай известные тебе типы и допускай новые значения. В `exchangeWords` лежат сообщение биржи `text` и необязательный `code`; `reason` хранит исходный ответ. Обоих полей нет, если биржа не отказывала, и в старых версиях рантайма.

Ордер бота со сбоем, который бот отправил бы снова, теперь несет `retry: true`: человек может нажать **Повторить** у этого ордера. Ключ отправить его не может (`restore-level` нет среди команд бота для ключа), так что скажи человеку. У DCA-бота это ордер усреднения; без `retry` бот его отклонил бы: он на паузе, в ремонте, после срабатывания стоп-лосса, пока тейк-профит следует за ценой, или это более ранняя попытка этого уровня. У сетки это строка ордера последней попытки ордера со сбоем, и строка этого ордера в `orders` строки сетки тоже ее несет, вместе с `error` (наша фраза `why`, а также `errorType` и `exchangeWords`, если отказала биржа) и `past: true`, пока повторное выставление исполнило бы его сразу. Без `retry` сетка его не выставит: она на паузе, останавливается, ее позиция отличается от биржевой, какой-то элемент держит ее новые ордера, итог ее попытки неизвестен или другой ордер занимает этот уровень. Повтор для ордера сетки — это **Исправить** для этого одного ордера: одно чтение того, что свободно, а ответ — тот же, что у Исправить, `{"placed", "left", "needed", "unit"}`, для этого ордера.

## Что боту нужно от твоего счета <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

На перпетуалах `ownFunds` в строке бота — то, что нужно боту от твоего счета, чтобы дойти до стопа (у DCA — до стоп-лосса), а без него — чтобы исполнить последний усредняющий ордер, с комиссиями: цифра, которую дали `margin.survive` (`margin.toLast`) в предпросмотре, когда рассчитывался цикл. Цикл DCA из прежней версии сохраняет стоимость своих ордеров ÷ плечо. Значение сетки считается при выдаче строки, в том числе для завершенных сеток. `invested` (Макс. по плану) — план самого большого цикла; у бота без цикла показан план, с которого он начнет. Бот, размер которого задан в процентах счета, рассчитывается так, чтобы его потребность была этим процентом: работающий DCA — со следующего цикла, сетка — со следующего ордера, который она ставит.

## Ордера сетки со сбоем <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Строка сетки в `GET /api/v1/bots` содержит `failed` — число ордеров со сбоем, а пока оно больше нуля, еще и `failedWhy`: `money`, если все отклонены или отменены из-за нехватки средств, `other`, если ни один, и `mixed` в остальных случаях. Чтение ордеров перечисляет каждый ордер со сбоем и его статус.

`POST /api/v1/bots/{id}/command` с `{"requestId": "...", "kind": "fix-failed"}` выставляет их снова, как **Исправить** в панели: заново считывает, сколько биржа считает свободным для нового ордера, вычитает твои ордера в пути и выставляет ордера со сбоем, начиная с ближайших к цене, насколько хватит средств. Ничего сверх прочитанного не отправляет. Ответ — `{"placed", "left", "needed", "unit"}`: сколько отправлено, сколько еще со сбоем и сколько `unit` нужно для остальных (ордер, который затем отклонит биржа, снова попадет в `failed` строки); `later` считает оставленные по другой причине, `past` — отправленные сразу, поскольку цена их уже прошла. Сетка на паузе отвечает 422 `paused` и ничего не выставляет; сбой чтения баланса — 422 `balance` без выставления; остановленная сетка — 409 `state`. Это действие с ордерами, поэтому ключ может отправить его для созданной им сетки. Проблемы бота больше не содержат пункт `orders-failed`; его `facts.failed` устарело (см. Ордера бота со сбоем). Инструмент MCP использует ту же операцию.

Бот, который все еще останавливается или запускается через пять минут после начала и не ждет ничего, что ты задал, несет элемент с причиной `stuck-stopping`, `stuck-launching` или `stuck-entry` (вход DCA не исполнен); его отдают `GET /api/v1/bots/{id}` и строки внимания на Дашборде, и он исчезает, когда бот выходит из этого состояния.

## Оплата кредитов $GOOD <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

Кредиты оплачиваются из собственного кошелька человека; программа или агент может только запросить котировку, но не заплатить. `POST /api/v1/credits/pay` с `build: false` отвечает, сколько добавил бы платеж ([схема](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). Спрашивай по сумме в монете, как «Добавить кредиты»: `input` — сумма в единицах самой монеты, один вызов маршрута, и платеж тратит ровно её. В Solana `burn: true` с любой монетой, кроме $GOOD, покупает $GOOD в том же платеже и сжигает его, чтобы получить скидку $GOOD:

```json
{"chain":"solana","token":"native","input":"0.1007","burn":true,"payer":"<the wallet's address>","build":false}
```

`quote.credits` в ответе — кредиты в USD, а `quote.goodMore` — на сколько больше, чем те же SOL купили бы без $GOOD (здесь около 9,90 и 0,90). Если в `token` указан сам минт $GOOD, сжигаются имеющиеся $GOOD (без `burn`). `amount` (нужные кредиты) и `spend` (сколько USD потратить на путях с $GOOD) по-прежнему принимаются.

В Tron TRX обменивается на USDT в том же платеже; любой другой TRC-20 получает ответ `no-route`.

В ответе `quote.feeKept` — сколько собственной монеты сети платеж оставляет на комиссию, в этой монете (сети EVM и Tron).

## Итоги истории кредитов <a href="#credits-history-totals" id="credits-history-totals"></a>

После оплаты `POST /api/v1/credits/pay/receipt` с `{chain, id}` платежа (и `coin`, тикер, которым платили, который элемент истории платежа затем несет как `paidWith`) читает его статус в любой из наших сетей; кредиты обычно появляются в `GET /api/v1/credits` через несколько секунд после первого подтверждения, а платеж, который сеть потом отбросит, списывается строкой истории с `reason: "reversed"` (ниже нуля, с ее `chain` и `tx`, а также `token`, `amount` и `seq` платежа в `payment`). `token` платежа — монета, которая пришла (после свопа долларовый токен), и его суммы выражены в ней; `paidWith`, если он есть, — монета, которой заплатил человек (TRX, ETH, SOL), ее и называет строка таблицы Платежи; если его нет (платеж сделан до появления поля или отправлен не из приложения), называй `token`.

`GET /api/v1/credits` и MCP `credits` возвращают один и тот же дополнительный необязательный объект `totals` ([схема](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees` и `balanceDifference` — десятичные строки в USD. `firstDay` — дата первой записанной сделки по UTC или null, `throughDay` — сегодняшняя дата по UTC, `dayCount` учитывает обе границы и дни без сделок. Средние месячные значения в тридцать раз больше дневных, даже при десяти днях истории или переходе между месяцами. `paidEstimated` отмечает расчетную стоимость платежей. `balanceDifference = paymentCredits + grants - totalFees - balance`; ненулевое значение вызывает предупреждение, но ничего не блокирует. Ожидающие и отмененные платежи исключены; платеж, отброшенный сетью, вычитается из `totalPaid` и `paymentCredits` своей строкой `reversed` и никогда не входит в `grants`. Если старая версия не возвращает итоги, используй известные дни и историю и укажи, что показатели неполные. `days` и постраничное чтение `?before=YYYY-MM-DD` не меняются. Платеж из кошелька остается действием самого человека. Предупреждение о несовпадении баланса появляется только при полных данных. Стоимость каждого платежа в $GOOD приблизительная.

## Объем торговли <a href="#trading-volume" id="trading-volume"></a>

Используй `GET /api/v1/trading-volume?before=YYYY-MM-DD` с разрешением на чтение или обратись к инструменту MCP `trading_volume`. Он показывает объем твоей торговли в USD, число исполненных сделок, уплаченные комиссии и реализованный PnL по аккаунту, рынку и тому, кто разместил ордер, с момента подключения каждого аккаунта к goodcryptoX. См. [схему ответа](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`totals` охватывает все сохраненные сделки. `days` показывает последний 31 день UTC, в котором были сделки, начиная с самого нового. Чтобы получить следующую страницу, передай `next` как `before`; этот день не войдет в следующую страницу. Суммы — десятичные строки в USD. Фандинг, переводы и неисполненные ордера не учитываются. Реализованный PnL на споте не входит в эти итоги. Комиссии биржи и goodcryptoX указаны отдельно; возврат комиссии имеет отрицательное значение.

`manual` означает ордер, размещенный человеком или ключом доступа. `dca` и `grid` означают ордера ботов. `gcx` означает, что мы знаем: ордер прошел через goodcryptoX, но уже не знаем его вид или чей ключ его разместил. `external` включает сделки вне goodcryptoX, ликвидации и автоматическое сокращение позиций.

Проверь `state` и `reason` каждого аккаунта, прежде чем считать его итоги полными. Сделки до подключения аккаунта не учитываются. Аккаунт, который удалили с сохранением истории и вернули, сохраняет то, что уже посчитал, и снова считает с момента возврата. `since` — время самой старой сделки, которую мы сохранили, в миллисекундах; оно не гарантирует наличие всех последующих сделок. Если чтение истории не удалось, данные аккаунта остаются неполными до успешной повторной попытки. Только что подключенный аккаунт остается в ожидании, пока мы читаем его сделки с момента подключения. На Binance мы учитываем сделки вне goodcryptoX, пока goodcryptoX работает. Сделки, совершенные при выключенном goodcryptoX или потерянные при сбое, могут отсутствовать, особенно на рынках, о которых мы не знали.

`missing` считает сделки, которые мы не смогли полностью оценить в USD: комиссию в монете, цену которой биржа нам не дала, или сделку на рынке, которого мы еще не знали. То, что мы не смогли оценить, учитывается как ноль; сделка на рынке, которого мы еще не знали, так и остается. `estimated` считает сделки, оцененные по сохраненному у нас курсу, а не по цене на момент исполнения. Мы храним исходные суммы, чтобы позже уточнять эти цифры. `unknownFees` считает сделки с неизвестной комиссией биржи, включая сделки с акциями. `unknownPnl` считает сделки с бессрочными контрактами, у которых реализованный PnL неизвестен, а не заведомо равен нулю. Поля восстановления показывают, до какого места мы проверили сохраненную историю. Для человека `unmatchedFees` считает списания кредитов, которые мы не смогли связать с сохраненной сделкой.

Ключ видит только подключенные аккаунты, которые ему разрешено читать. Он видит свой `keyId`; цифры других ключей и человека объединены без их идентификаторов. Демо-данные и стертые аккаунты исключены. Несуществующая дата возвращает 400.

## Идентификаторы активов в портфеле <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` и инструмент MCP `portfolio` только для чтения добавляют `assets` рядом с уже имеющимися данными аккаунтов, снимками и PnL. У каждого актива есть `assetId`, `assetKind` (`bundled` или `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced` и `holdings`. `bundled` — явная идентичность из реестра, даже если сейчас актив лежит на одном аккаунте. `exchange` — актив биржи без соответствия; в его id входят биржа и точный код актива. Никогда не объединяй строки по `symbol`.

`holdings` хранит каждый аккаунт, биржу, исходный код, количество, цену, стоимость и признак отсутствующей цены. Стоимости и цены — десятичные строки в USD. Количества указаны в единицах этого актива; суммы кошельков, заданные только стоимостью, равны null. Стоимость группы — сумма стоимостей активов: 2 UBTC по 60 000 на одной бирже плюс 1 BTC по 61 000 на другой дают 181 000, а не утроенную справочную цену. Без цены количество остается, а стоимость вносит ноль; `unpriced` истинно, если у какой-либо составляющей нет цены. Цены — последние известные локальному goodcryptoX; это чтение не придумывает цену и не требует сервиса goodcryptoX. Аккаунты, исключенные из балансов, и демо-деньги в итогах подключенных активов отсутствуют. Старые версии не отдают `assets`; все прежние поля сохраняют смысл.

`pnl` в ответе — то, что аккаунты заработали с момента подключения к goodcryptoX, по собственному учету goodcryptoX, одинаково на всех биржах: закрытые фьючерсные сделки за вычетом комиссий и фандинг. Каждая строка `accounts` содержит `connected` — момент, с которого считается PnL этого аккаунта; ничего до него не входит ни в один период.

Читай показатели позиций через топик `positions` (`snapshot` в MCP). `GET /api/v1/funding?sourceId=&instrumentId=` и инструмент MCP `funding` только для чтения возвращают платежи со знаком и долю каждого бота. Необязательный `id` обозначает платеж биржи; `asset` — указанную биржей валюту суммы в прежнем поле `usdc`. Не считай эту сумму автоматически суммой в USDC. В хедж-режиме Binance платежи остаются у аккаунта: биржа не указывает сторону. Совместимость: в старых строках нет `id` и `asset`; смысл существующих полей сохраняется.

## Вопросы <a href="#questions" id="questions"></a>

### Есть документ OpenAPI? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

Да: `/api/v1/openapi.json` на адресе установки, с тем же заголовком Bearer. Описывает только доступные ключу вызовы.

### API работает с другого компьютера? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

Да: запусти там коннектор в режиме `connect`; пока работает, установка доступна по локальному адресу. [SSH-туннель](https://docs.goodcrypto.app/goodcryptox-ru/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) тоже подойдет.

### Программа может размещать ордера? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

Да, с ключом **Торговля**: `POST /api/v1/orders` в разрешенных аккаунтах, рынках и лимитах. Сначала попроси предпросмотр: он ничего не отправляет.

### Что будет при тайм-ауте запроса? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

Потерянный ответ не означает сбой ордера: проверь результат до повтора. При повторе сохраняй те же `requestId` и тело, чтобы не разместить ордер дважды.
