> 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-uk/goodcryptox-3.0/api.md).

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

Читай дані й торгуй зі своєї програми через локальний API goodcryptoX із тими самими ключами та лімітами, що в ШІ-агента.

Твоя програма читає й торгує на підключених біржах через API goodcryptoX, описаний в OpenAPI. Ключі, дозволи та ліміти ті самі, що в ШІ-агента ([Ключі та ліміти](https://docs.goodcrypto.app/goodcryptox-uk/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-uk/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-uk/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-uk/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Якщо відкрити goodcryptoX за [домашньою адресою](https://docs.goodcrypto.app/goodcryptox-uk/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-uk/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-uk/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` і тіло, щоб не розмістити ордер двічі.
