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

# API

Lies und handle aus deinem Programm über die lokale goodcryptoX-API mit denselben Schlüsseln und Limits wie ein KI-Agent.

Dein eigenes Programm liest und handelt auf den Börsen, die du verbindest, über die goodcryptoX-API, beschrieben im OpenAPI-Dokument. Es nutzt dieselben Schlüssel, Rechte und Limits wie ein KI-Agent ([Schlüssel und Limits](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#keys-and-limits)).

`POST /api/v1/accounts/{id}/check` (MCP `check_api_key`) liest die Berechtigungen des API-Schlüssels eines Binance-, Bybit- oder Bybit EU-Kontos erneut, wie **Erneut prüfen** auf seiner Karte.

Jede Zahl kommt in der Währung ihres Trades: Preise und Werte in der Quote-Währung des Markts, ein PnL in dem Asset, das seine Zeile nennt, Guthaben und `GET /api/v1/portfolio` in USD, die Limits eines Schlüssels in der Währung, in der sie gesetzt wurden. `GET /api/v1/rates` nennt deine Basiswährung und ihren Kurs je 1 USD, um eine Zahl so zu zeigen wie goodcryptoX.

Das MCP-Tool `instruments` und `GET /api/v1/instruments?venue=…` enthalten für jeden Markt das bekannte Volumen über 24 Stunden (Wert in der Quote-Währung), die Preisänderung (in Prozent) und, sofern die Börse ihn sendet, den zuletzt gehandelten Preis. Die API stellt außerdem `instrument-stats/<venue>` über ihre [Topic-Route](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/runtime/api.md#the-socket) bereit. Diese Zahlen bleiben Dezimalstrings. Bei Volumen und Preisänderung bleibt mit null der zuvor bekannte Wert erhalten; das optionale Feld `invalidate` nennt die zu löschenden Werte. Fehlt `lastPrice`, bleibt der bisherige Preis aus Kompatibilitätsgründen erhalten; ein ausdrücklich gesendetes null löscht ihn.

Erstelle unter **Einstellungen › MCP & API** einen Schlüssel ([Anleitung](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#connect-any-mcp-app-or-program)). Die Seite **API** im Verbindungsblock zeigt dann drei Zeilen mit Kopiersymbol: **Adresse**, **Schlüssel** und den Header, den dein Programm mit jeder Anfrage sendet, samt gewähltem Schlüssel: `Authorization: Bearer <your key>`. Das Kopiersymbol daneben kopiert ihn vollständig.

<details>

<summary>Beispiel einer API-Anfrage</summary>

Setze `GCX_URL` auf den von deinem Programm erreichten Ursprung und stelle `GCX_KEY` in dessen Umgebung bereit. Dieses Beispiel liest Konten:

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

Das OpenAPI-Dokument liegt unter `$GCX_URL/api/v1/openapi.json`. Dein Programm fordert es mit demselben Bearer-Header an; die Beschreibung enthält nur erlaubte Aufrufe des Schlüssels. Beträge, Preise und Größen sind Dezimalzeichenfolgen.

</details>

Demokonten und die Bybit-Entwickleransicht mit Beispielen zum Senden mit einem Nur-Lese-Schlüssel und zur Wiederherstellung sind für im Panel angemeldete Personen bestimmt. Zugriffsschlüssel und MCP können weder `demoBybitView` noch `demo=1` verwenden.

## Von einem anderen Computer <a href="#from-another-computer" id="from-another-computer"></a>

Für ein Programm auf einem anderen Computer starte dort den Connector im Modus `connect`. Solange er läuft, stellt er deine Installation unter einer lokalen Adresse bereit ([Koppeln](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#from-another-computer)). Drücke auf diesem Computer **Anzeigen** neben **Cursor und andere Apps** und starte den Connector mit den Werten aus `env` (ohne `GCX_URL` und `GCX_KEY`; dein Programm sendet seinen eigenen Schlüssel):

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

Er gibt die Verbindungsadresse und dann die API-Adresse mit Endung `/api/v1` aus. Lass ihn während der Programmnutzung laufen und nutze die erste Adresse als `GCX_URL`, etwa `http://127.0.0.1:8130`.

<details>

<summary>Spätere Starts und Adressänderungen</summary>

Führe später `npx -y goodcryptox-connector@<version>-<build> connect --profile <the profile>` aus; die gespeicherte Kopplung wird wiederverwendet. Jede Installation hat ihr eigenes Profil und ihre Adresse. Ist die gespeicherte Adresse belegt, füge `--choose-new-address` hinzu und kopiere die neue Adresse ins Programm.

</details>

Ohne Verbindung schlagen Aufrufe fehl; sie werden nicht für später gespeichert. Ohne unser Relay verbindest du dich über [einen SSH-Tunnel](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead).

Öffnest du goodcryptoX unter einer [Heimadresse](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/readme/set-up-on-your-mac.md#your-home-network), ist die **Adresse** auf der Seite **API** diese Adresse: Ein Programm im selben Netzwerk sendet seine Anfragen mit seinem Schlüssel dorthin, ohne Connector und ohne unser Relay, und nutzt die Adresse ohne `/api/v1` als `GCX_URL`. Nutze sie in einem vertrauenswürdigen Netzwerk oder über deine eigene vertrauenswürdige HTTPS-Adresse: Über HTTP kann jemand, der den Verkehr liest, den Schlüssel kopieren.

## Order senden <a href="#sending-an-order" id="sending-an-order"></a>

Fordere zuerst eine Vorschau an ([Order zuerst prüfen](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#checking-an-order-first)). Dann `POST /api/v1/orders` mit:

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

Wenn der Hebel des Kontos noch nicht gelesen wurde, wird eine Order auf einen Perpetual gesendet und die Börse wendet ihren eigenen Hebel an; der Beleg der Vorschau enthält dann keine Angaben zu den Mitteln, und die Margin wurde nicht geprüft.

Eine Order mit einer Größe in der Kurswährung (`"sizeUnit": "quote"` oder `"coin"` bei einem Kontrakt mit Coin-Margin) behält diesen Betrag: Die Coins werden bei jedem Senden zum Sendepreis neu berechnet (eine Limit-Order zu ihrem Preis, nach jeder Preisänderung; ein Stop beim Auslösen). Die Orderzeile zeigt den Betrag als `cost` und `sizeUnit` neben `size`, der aktuellen Coin-Menge. Ein Wert ab dem Börsenminimum wird um einen Größenschritt aufgerundet, wenn Abrunden ihn unter das Minimum bringen würde; deshalb kann `size` in der Zeile bis zu einen Schritt mehr wert sein als der gesendete Betrag. Eine Größe über null, die nichts senden würde (nach dieser Rundung unter einem Größenschritt), wird als ein Schritt des Coins platziert, und die Antwort gibt das an: `{"id": "o1", "size": "0.001", "sizeUnit": "base"}`; null wird abgelehnt. Zum Ändern nimmt `POST /api/v1/orders/{id}/modify` (MCP `modify_order`) `changes.sizeUnit` zusammen mit `size` an: `{"size": "150", "sizeUnit": "quote"}` setzt den Betrag auf 150, `{"price": "2900"}` behält ihn zum neuen Preis bei, und `size` allein bedeutet Coins.

Eine Order unter dem Mindestorderwert der Börse wird so gesendet, wie du sie übergibst (die Vorschau warnt mit `trade.msgMinNotional`); das Ergebnis ist die Antwort der Börse. Bots tun dasselbe: Einstieg und Nachkauf-Orders eines DCA-Bots und die Stufen eines Grids unter dem Minimum werden gesendet. Lehnt die Börse eine ab, gilt sie als fehlgeschlagene Order des Bots (DCA-Stufe `failed`, `failed`-Zähler des Grids) und wird mit Erneut versuchen oder Fehler beheben erneut gesendet. Die Belegzeile der Bot-Vorschau markiert eine solche Order mit `under`; `sent` false steht nur für eine Order, die zum Senden zu klein ist. Eine Grid-Zeile mit `sendAll` platziert jede Stufe; eine ohne diesen Wert (von einer früheren Version gestartet) hält Stufen unter dem Minimum zurück.

Bei einem coin-margined Markt (`contract.method` `"DIV"`) werden Größen von Orders, Positionen und Bots in Kontrakten zusammen mit den Kontraktdaten geliefert: USD = Kontrakte × `contract.multiplier`, und der Coin = diese USD ÷ Preis. Ein DCA-Bot mit `"sizingMode": "coin"` nimmt `entryAmount` und `level1Amount` in der Abrechnungswährung des Kontrakts (`contract.settlement`): Jede Order ist diese Coinmenge zu ihrem eigenen Preis, abgerundet auf ganze Kontrakte. `"cost"` setzt bei jeder Order denselben USD-Betrag ein; ein USD-Betrag unter einem Kontrakt beginnt mit dem USD-Wert eines Kontrakts, und jede Stufe wird davon ausgehend skaliert.

Auf einem Konto im Hedge-Modus hat ein Futures-Markt zwei IDs, `…:long` und `…:short`, und die Seite eröffnet oder schließt: Ein Verkauf auf Long oder ein Kauf auf Short reduziert nur diese Position, mit oder ohne `reduceOnly`; `reduceOnly: true` auf der anderen Seite wird abgelehnt (`reduce-only-opens`).

Eine verlorene Antwort nach dem Senden bedeutet keine fehlgeschlagene Order. Prüfe das Ergebnis vor einem neuen Versuch. Behalte bei der Wiederholung einer Handelsanfrage dieselbe `requestId` und denselben Inhalt, damit dieselbe Order nicht doppelt platziert wird.

`POST /api/v1/margin` fügt einer Position auf Hyperliquid, Binance und Bybit isolierte Margin hinzu (ein positives `amount`) oder entfernt sie (ein negatives), in ihrer Margin-Coin (MCP `change_margin`). Bybit EU unterstützt nur Spot. Ein Handelsschlüssel tut das auf den Konten und Märkten, die seine Limits nennen, wie beim Einstellen des Hebels: Ein Schlüssel ohne Limits oder für ein anderes Konto oder einen anderen Markt erhält 422 `key.*`, und nichts wird gesendet.

Anfrageinhalte und Ablehnungsmeldungen aller Routen stehen im OpenAPI-Dokument unter `/api/v1/openapi.json`.

## Einstellungen, die nur du änderst <a href="#settings-only-you-change" id="settings-only-you-change"></a>

Manche Routen ändern etwas, das nur du entscheidest: Ein Schlüssel, der sie aufruft, bekommt 403 `person-only` mit einem Satz, den er dir weitergibt, und an die Börse geht nichts. Ihre MCP-Tools gibt es, damit ein Agent dir sagen kann, was zu tun ist.

* `POST /api/v1/accounts/{id}/bnb-fees` (`{"on": true}`) schaltet **Gebühren in BNB zahlen** für ein Binance-Konto ein oder aus (MCP `set_bnb_fees`). Die Zeile des Kontos in `GET /api/v1/accounts` zeigt es als `bnbFees`: `on` und die Einstellungen dahinter, `spot` und `usdm`.

Auch der Schalter **Sicherheit** eines Coins ist nur für dich: `POST /api/v1/accounts/{id}/collateral` antwortet einem Schlüssel mit 403 und hat kein MCP-Tool. Ein Programm liest die Einstellung im Thema `balances` (`perCoinCollateral`: die Wallet und je Coin `accepted`, `selected` und `fixed`; null bedeutet unbekannt, nie Aus) oder fragt einen Coin jetzt bei der Börse mit `GET /api/v1/accounts/{id}/collateral?coin=BTC` ab (`{coin, accepted, selected}`; 503, wenn das Lesen fehlschlägt oder länger als zehn Sekunden dauert).

Nur du kannst Konten entfernen: `POST /api/v1/accounts/{sourceId}/remove` gilt auch für Binance, Bybit und Bybit EU; ein MCP-Tool zum Entfernen von Konten wird nicht angeboten.

## Vorschlag zurückziehen <a href="#withdrawing-a-proposal" id="withdrawing-a-proposal"></a>

Ein Schlüssel kann eine selbst vorgeschlagene Order oder einen Bot zurückziehen, solange der Vorschlag wartet: `POST /api/v1/proposals/{id}/withdraw` mit `{"requestId": "..."}`, Berechtigung **Vorschlagen** oder höher. Die Antwort lautet `{"accepted": true}`; Wiederholen antwortet genauso. Ein fremder Vorschlag antwortet 404, als gäbe es ihn nicht; ein gestarteter 422 `proposal-launched`, ein abgelehnter 422 `proposal-rejected`. Ablehnen bleibt dir vorbehalten: Ein Schlüssel kann nicht ablehnen.

## Listen über mehrere Konten <a href="#lists-over-several-accounts" id="lists-over-several-accounts"></a>

`GET /api/v1/lists/positions` und `GET /api/v1/lists/orders` lesen jedes Konto, das die Liste umfasst. Ein Konto, das die Börse nicht lesen konnte, blendet die anderen nicht aus: Der `state` der Seite bleibt `live`, solange ein Konto gelesen wurde, und `accountStates` liefert den Zustand jedes Kontos (`live`, `stale`, `unavailable` oder `waiting` beim ersten Lesen), damit du weißt, wessen Zeilen fehlen könnten. Der `state` der Seite ist nur dann `stale` oder `unavailable`, wenn kein Konto gelesen werden konnte. Alle stornieren, Alle stoppen und Alle schließen beantworten jede Order, jeden Bot oder jede Position einzeln: Was fehlschlägt, steht mit seinem Satz in `refused`, der Rest wird in `count` und `ids` gezählt.

## Fehlgeschlagene Orders eines Bots <a href="#a-bots-failed-orders" id="a-bots-failed-orders"></a>

Eine von der Börse abgelehnte Nachkauf-Order eines DCA-Bots oder eine abgelehnte Grid-Order stoppt den Bot nicht und steht daher weder in den Aufmerksamkeitszeilen noch in den `items` des Bots; dort steht nur, was einen Bot stoppt oder auf dich wartet. Die fehlgeschlagenen Nachkauf-Orders eines DCA-Bots liest du aus `counters.averagingFailed` seiner Zeile, die eines Grids aus seinem `failed` (nächster Abschnitt) und jede fehlgeschlagene Order aus ihrer Order-Zeile: `why` ist der Satz, den das Panel zeigt, `errorType` der Typ dahinter und `exchangeWords` der Wortlaut der Börse selbst; die MCP-Tools lesen dieselben Zeilen. `errorType` ist ein offener String: Zeige die Typen, die du kennst, und erlaube neue Werte. `exchangeWords` enthält den `text` der Börsenmeldung und optional einen `code`; `reason` behält die ursprüngliche Antwort. Beide Felder fehlen ohne Ablehnung durch die Börse und bei älteren Runtimes.

Die fehlgeschlagene Order eines Bots, die der Bot jetzt erneut senden würde, trägt `retry: true`: Die Person kann bei dieser Order **Erneut versuchen** drücken. Ein Schlüssel kann sie nicht senden (`restore-level` gehört nicht zu den Bot-Befehlen eines Schlüssels); sag es also der Person. Bei einem DCA-Bot ist es eine Nachkauf-Order; ohne `retry` würde der Bot sie ablehnen: pausiert, in Reparatur, nachdem sein Stop-Loss ausgelöst hat, während sein Take-Profit nachzieht oder bei einem früheren Versuch derselben Stufe. Bei einem Grid ist es die Order-Zeile des letzten Versuchs einer fehlgeschlagenen Order, und auch die Zeile der fehlgeschlagenen Order in `orders` der Grid-Zeile trägt es, mit `error` (unser Satz `why`, dazu `errorType` und `exchangeWords`, wenn die Börse sie abgelehnt hat) und `past: true`, solange eine erneute Platzierung sofort ausgeführt würde. Ohne `retry` würde das Grid sie nicht platzieren: Es ist pausiert, stoppt gerade, seine Position weicht von der der Börse ab, ein Eintrag hält seine neuen Orders zurück, der Ausgang seines Versuchs ist nicht bekannt, oder eine andere Order belegt diese Stufe. Erneut versuchen bei der Order eines Grids ist **Fehler beheben** für diese eine Order: eine Abfrage dessen, was frei ist, und die Antwort ist die von Fehler beheben, `{"placed", "left", "needed", "unit"}`, für diese Order.

## Was ein Bot von deinem Konto braucht <a href="#what-a-bot-needs-from-your-account" id="what-a-bot-needs-from-your-account"></a>

Bei Perpetuals ist `ownFunds` in der Zeile eines Bots das, was der Bot von deinem Konto braucht, um seinen Stop (den Stop-Loss eines DCA) zu erreichen, oder ohne Stop, um seine letzte Nachkauf-Order auszuführen, inklusive Gebühren: der Wert, den `margin.survive` (`margin.toLast`) der Vorschau lieferte, als der Zyklus dimensioniert wurde. Ein DCA-Zyklus aus einer früheren Version behält den Wert seiner Orders ÷ seinen Hebel. Der eines Grids wird beim Ausliefern der Zeile berechnet, auch bei beendeten Grids. `invested` (Max. geplant) ist der Plan des größten Zyklus; ein Bot ohne Zyklus zeigt den Plan, mit dem er starten wird. Ein Bot, der als Prozent des Kontos dimensioniert ist, wird so dimensioniert, dass sein Bedarf dieses Prozent ist: ein laufender DCA ab seinem nächsten Zyklus, ein Grid ab der nächsten Order, die er platziert.

## Fehlgeschlagene Orders eines Grids <a href="#a-grids-failed-orders" id="a-grids-failed-orders"></a>

Eine Grid-Zeile in `GET /api/v1/bots` enthält `failed`, die Anzahl fehlgeschlagener Orders, und, solange sie größer als null ist, `failedWhy`: `money`, wenn alle wegen fehlender Mittel abgelehnt oder storniert wurden, `other`, wenn keine davon betroffen war, sonst `mixed`. Die Orderabfrage listet jede fehlgeschlagene Order mit ihrem Status auf.

`POST /api/v1/bots/{id}/command` mit `{"requestId": "...", "kind": "fix-failed"}` platziert sie erneut, wie **Fehler beheben** im Panel: eine neue Abfrage dessen, was laut Börse für eine neue Order frei ist, abzüglich deiner Orders unterwegs, dann die fehlgeschlagenen Orders mit den preisnächsten zuerst, soweit es reicht. Was die Abfrage nicht abdeckt, wird nicht gesendet. Die Antwort ist `{"placed", "left", "needed", "unit"}`: wie viele gesendet wurden, wie viele noch fehlgeschlagen sind und wie viel `unit` für den Rest fehlt (eine danach von der Börse abgelehnte Order erscheint wieder in `failed` der Zeile); `later` zählt die aus einem anderen Grund belassenen, `past` die sofort gesendeten, deren Preis schon überschritten war. Ein pausiertes Grid antwortet mit 422 `paused` und platziert nichts; eine fehlgeschlagene Guthabenabfrage mit 422 `balance` und ohne Platzierung; ein gestopptes Grid mit 409 `state`. Es ist eine Orderaktion, daher darf ein Schlüssel sie für ein von ihm erstelltes Grid senden. Die Bot-Probleme enthalten keinen Eintrag `orders-failed` mehr; sein `facts.failed` ist veraltet (siehe Fehlgeschlagene Orders eines Bots). Das MCP-Tool nutzt dieselbe Operation.

Ein Bot, der fünf Minuten nach dem Beginn noch stoppt oder startet und auf nichts wartet, das du festgelegt hast, trägt ein Element mit der Ursache `stuck-stopping`, `stuck-launching` oder `stuck-entry` (ein DCA-Einstieg nicht ausgeführt); `GET /api/v1/bots/{id}` und die Aufmerksamkeitszeilen des Dashboards liefern es, und es verschwindet, wenn der Bot diesen Zustand verlässt.

## Guthaben mit $GOOD bezahlen <a href="#paying-credits-with-good" id="paying-credits-with-good"></a>

Guthaben wird aus dem eigenen Wallet der Person bezahlt; ein Programm oder ein Agent kann nur abfragen, nie bezahlen. `POST /api/v1/credits/pay` mit `build: false` antwortet, was eine Zahlung hinzufügen würde ([Schema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-pay.schema.json)). Frage nach dem Coin-Betrag, wie es Guthaben aufladen tut: `input` ist der Betrag in den eigenen Einheiten des Coins, ein Routenaufruf, und die Zahlung gibt genau das aus. Auf Solana kauft `burn: true` mit jedem Coin außer $GOOD bei derselben Zahlung $GOOD und verbrennt es, für den $GOOD-Rabatt:

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

Die Antwort nennt in `quote.credits` das Guthaben in USD und in `quote.goodMore`, wie viel mehr es ist als dieselben SOL ohne $GOOD kaufen (hier etwa 9,90 und 0,90). Mit `token` als dem $GOOD-Mint selbst werden die gehaltenen $GOOD verbrannt (kein `burn`). `amount` (gewünschtes Guthaben) und `spend` (USD, die auf den $GOOD-Wegen ausgegeben werden) werden weiter akzeptiert.

Auf Tron wird TRX in der Zahlung zu USDT getauscht; jeder andere TRC-20-Token liefert `no-route`.

In der Antwort ist `quote.feeKept`, wie viel vom eigenen Coin des Netzwerks die Zahlung für ihre Gebühr übrig lässt, in diesem Coin (EVM-Netzwerke und Tron).

## Gesamtsummen im Guthabenverlauf <a href="#credits-history-totals" id="credits-history-totals"></a>

Nachdem die Person bezahlt hat, liest `POST /api/v1/credits/pay/receipt` mit `{chain, id}` der Zahlung (und `coin`, dem Ticker, mit dem bezahlt wurde, den der Verlaufseintrag der Zahlung dann als `paidWith` trägt) ihren Status in jedem unserer Netzwerke; das Guthaben erscheint meist Sekunden nach der ersten Bestätigung in `GET /api/v1/credits`, und eine Zahlung, die das Netzwerk später verwirft, wird durch eine Verlaufszeile mit `reason: "reversed"` zurückgenommen (unter null, mit ihrem `chain` und `tx` sowie `token`, `amount` und `seq` der Zahlung unter `payment`). Das `token` einer Zahlung ist der Coin, der angekommen ist (nach einem Swap der Dollar-Token), und ihre Beträge sind in ihm; `paidWith` ist, wenn vorhanden, der Coin, mit dem die Person bezahlt hat (TRX, ETH, SOL), den die Zeile in Zahlungen nennt; fehlt es (eine Zahlung von vor diesem Feld oder von außerhalb der App), nenne `token`.

`GET /api/v1/credits` und MCP `credits` liefern dasselbe optionale zusätzliche Objekt `totals` ([Schema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/credits-api.schema.json)). `totalPaid`, `paymentCredits`, `grants`, `totalVolume`, `totalFees`, `dailyVolume`, `dailyFees`, `monthlyVolume`, `monthlyFees` und `balanceDifference` sind Dezimalzeichenfolgen in USD. `firstDay` ist das UTC-Datum des ersten erfassten Trades oder null, `throughDay` das heutige UTC-Datum; `dayCount` zählt beide Endpunkte und Tage ohne Trades. Monatsdurchschnitte sind dreißigmal der Tagesdurchschnitt, auch bei zehn Tagen Verlauf oder einem Monatswechsel. `paidEstimated` kennzeichnet abgeleitete Kosten von Zahlungen. `balanceDifference = paymentCredits + grants - totalFees - balance`; ein Wert ungleich null warnt, blockiert aber nie. Ausstehende und rückgängig gemachte Zahlungen sind ausgeschlossen; eine vom Netzwerk verworfene Zahlung wird durch ihre `reversed`-Zeile aus `totalPaid` und `paymentCredits` herausgenommen und zählt nie in `grants`. Fehlen Gesamtsummen in einer älteren Version, verwende bekannte Tage und den Verlauf und kennzeichne die Werte als unvollständig. `days` und die Seitennavigation mit `?before=YYYY-MM-DD` bleiben unverändert. Die Zahlung aus dem Wallet bleibt eine Handlung der Person. Nur vollständige Zahlen können eine Abweichung vom Guthaben zeigen. Bei jeder $GOOD-Zahlung wird der Geldbetrag geschätzt.

## Handelsvolumen <a href="#trading-volume" id="trading-volume"></a>

Nutze `GET /api/v1/trading-volume?before=YYYY-MM-DD` mit Leseberechtigung oder frage das MCP-Tool `trading_volume`. Es zeigt dein Handelsvolumen in USD, die Anzahl ausgeführter Trades, deine gezahlten Gebühren und deinen realisierten PnL, aufgeteilt nach Konto, Markt und danach, wer die Order platziert hat, seit du das jeweilige Konto mit goodcryptoX verbunden hast. Siehe das [Antwortschema](https://github.com/GoodCryptoApp/gcx/blob/main/docs/reference/schemas/trading-volume.schema.json).

`totals` umfasst alle gespeicherten Trades. `days` zeigt die letzten 31 UTC-Tage mit Trades, den neuesten zuerst. Für die nächste Seite übergibst du `next` als `before`; dieser Tag ist auf der nächsten Seite nicht enthalten. Beträge sind Dezimalstrings in USD. Funding, Transfers und nicht ausgeführte Orders zählen nicht. Realisierter Spot-PnL fließt nicht in diese Summen ein. Börsengebühren und goodcryptoX-Gebühren stehen getrennt; eine Gebührenrückvergütung ist negativ.

`manual` steht für eine Order, die eine Person oder ein Zugriffsschlüssel platziert hat. `dca` und `grid` stehen für Bot-Orders. `gcx` bedeutet, dass die Order über goodcryptoX kam, wir aber nicht mehr wissen, welche Art von Order es war oder wessen Schlüssel sie platziert hat. `external` umfasst Trades außerhalb von goodcryptoX, Liquidationen und automatischen Positionsabbau.

Prüfe bei jedem Konto `state` und `reason`, bevor du seine Summen als vollständig betrachtest. Trades aus der Zeit, bevor du ein Konto verbunden hast, zählen nicht. Ein Konto, das du mit behaltenem Verlauf entfernt und wieder hinzugefügt hast, behält, was es gezählt hat, und zählt ab dem Wiederhinzufügen weiter. `since` ist der Zeitpunkt des ältesten von uns behaltenen Trades in Millisekunden; das garantiert nicht, dass alle späteren Trades vorhanden sind. Schlägt das Lesen des Verlaufs fehl, bleibt das Konto unvollständig, bis ein neuer Versuch erfolgreich ist. Ein neu verbundenes Konto bleibt ausstehend, während wir die Trades seit seiner Verbindung lesen. Bei Binance zählen wir Trades außerhalb von goodcryptoX, solange goodcryptoX läuft. Trades aus der Zeit, in der es ausgeschaltet war, oder durch einen Absturz verlorene Trades können fehlen, besonders auf Märkten, die uns nicht bekannt waren.

`missing` zählt Trades, deren Wert wir nicht vollständig in USD bestimmen konnten: eine Gebühr in einem Coin, für den uns die Börse keinen Preis gab, oder ein Trade auf einem Markt, den wir noch nicht kannten. Was wir nicht bewerten konnten, geht mit null ein; bei einem Trade auf einem Markt, den wir noch nicht kannten, bleibt es dabei. `estimated` zählt Trades, die wir mit einem gespeicherten Kurs statt mit einem Preis vom Ausführungszeitpunkt bewertet haben. Wir behalten die ursprünglichen Beträge, um diese Zahlen später verbessern zu können. `unknownFees` zählt Trades mit unbekannter Börsengebühr, einschließlich Aktientrades. `unknownPnl` zählt Trades mit Perpetuals, deren realisierter PnL unbekannt ist und nicht nachweislich null beträgt. Die Felder zur Wiederherstellung zeigen, wie weit wir den gespeicherten Verlauf geprüft haben. Für die Person zählt `unmatchedFees` Guthabenabbuchungen, die wir keinem gespeicherten Trade zuordnen konnten.

Ein Schlüssel sieht nur die verbundenen Konten, die er lesen darf. Er sieht seine eigene `keyId`; Zahlen anderer Schlüssel und der Person werden ohne deren Kennungen zusammengefasst. Demo-Zahlen und gelöschte Konten sind ausgeschlossen. Ein Datum, das es nicht gibt, liefert 400.

## Portfolio-Identitäten <a href="#portfolio-identities" id="portfolio-identities"></a>

`GET /api/v1/portfolio` und das schreibgeschützte MCP-Tool `portfolio` fügen `assets` neben den bisherigen Konto-Ergänzungen, Snapshots und dem PnL hinzu. Jedes Asset hat `assetId`, `assetKind` (`bundled` oder `exchange`), `symbol`, `name`, `amount`, `value`, `unpriced` und `holdings`. `bundled` bedeutet eine ausdrückliche Identität aus dem Register, auch wenn sie gerade nur auf einem Konto liegt. `exchange` bedeutet ein nicht zugeordnetes Börsen-Asset; seine ID enthält die Börse und den genauen Asset-Code. Verbinde Zeilen nie über `symbol`.

`holdings` behält jedes Konto, jede Börse, den ursprünglichen Code, die Menge, den Preis, den Wert und die Markierung für einen fehlenden Preis. Werte und Preise sind Dezimalstrings in USD. Mengen sind in den Einheiten dieses Bestands; Wallet-Beträge, die nur einen Wert haben, sind null. Der Wert einer Gruppe summiert die Bestandswerte: 2 UBTC zu 60.000 an einer Börse plus 1 BTC zu 61.000 an einer anderen sind 181.000, nicht das Dreifache eines Referenzpreises. Ohne Preis bleibt die Menge, und der Wert trägt null bei; `unpriced` ist wahr, wenn einem Bestandteil der Preis fehlt. Preise sind die letzten bekannten der lokalen Runtime; diese Abfrage erfindet keinen Preis und braucht keinen goodcryptoX-Dienst. Von den Guthaben ausgenommene Konten und Demo-Geld fehlen in den Summen verbundener Assets. Ältere Runtimes lassen `assets` weg; alle älteren Felder behalten ihre Bedeutung.

`pnl` in der Antwort ist, was die Konten verdient haben, seit sie mit goodcryptoX verbunden sind, nach goodcryptoX' eigener Aufzeichnung, auf jeder Börse gleich: geschlossene Futures-Trades nach Gebühren und Funding. Jede Zeile von `accounts` enthält `connected`, den Zeitpunkt, ab dem der PnL dieses Kontos zählt; nichts davor gehört zu irgendeinem Zeitraum.

Lies Positionskennzahlen über das Topic `positions` (`snapshot` in MCP). `GET /api/v1/funding?sourceId=&instrumentId=` und das schreibgeschützte MCP-Tool `funding` liefern Zahlungen mit Vorzeichen und den Anteil jedes Bots. Das optionale `id` bezeichnet die Börsenzahlung; `asset` ist die von der Börse angegebene Währung des bisherigen Betragsfelds `usdc`. Gehe niemals davon aus, dass dieser Betrag in USDC ist. Binance-Zahlungen im Hedge-Modus bleiben beim Konto, da die Börse keine Seite angibt. Kompatibilität: Ältere Zeilen enthalten weder `id` noch `asset`; bestehende Felder behalten ihre Bedeutung.

## Fragen <a href="#questions" id="questions"></a>

### Gibt es ein OpenAPI-Dokument? <a href="#is-there-an-openapi-document" id="is-there-an-openapi-document"></a>

Ja: unter `/api/v1/openapi.json` an deiner Installationsadresse, angefordert mit demselben Bearer-Header. Es beschreibt nur die erlaubten Aufrufe des Schlüssels.

### Funktioniert die API von einem anderen Computer aus? <a href="#does-the-api-work-from-another-computer" id="does-the-api-work-from-another-computer"></a>

Ja: Starte dort den Connector im Modus `connect`. Solange er läuft, stellt er deine Installation unter einer lokalen Adresse bereit. Ein [SSH-Tunnel](https://docs.goodcrypto.app/goodcryptox-de/goodcryptox-3.0/ai-agents.md#use-an-ssh-tunnel-instead) funktioniert ebenfalls.

### Kann ein Programm Orders platzieren? <a href="#can-a-program-place-orders" id="can-a-program-place-orders"></a>

Ja, mit einem **Handeln**-Schlüssel: `POST /api/v1/orders` innerhalb der Konten, Märkte und Limits des Schlüssels. Fordere zuerst eine Vorschau an; sie sendet nichts.

### Was passiert bei einer Zeitüberschreitung? <a href="#what-happens-if-my-request-times-out" id="what-happens-if-my-request-times-out"></a>

Eine verlorene Antwort bedeutet keine fehlgeschlagene Order. Prüfe das Ergebnis vor einem neuen Versuch. Behalte beim Wiederholen dieselbe `requestId` und denselben Inhalt, damit dieselbe Order nicht doppelt platziert wird.
