For the complete documentation index, see llms.txt. This page is also available as Markdown.

API

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).

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 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). 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.

Beispiel einer API-Anfrage

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

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.

Von einem anderen Computer

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). 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):

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.

Spätere Starts und Adressänderungen

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.

Ohne Verbindung schlagen Aufrufe fehl; sie werden nicht für später gespeichert. Ohne unser Relay verbindest du dich über einen SSH-Tunnel.

Öffnest du goodcryptoX unter einer Heimadresse, 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

Fordere zuerst eine Vorschau an (Order zuerst prüfen). Dann POST /api/v1/orders mit:

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 isolierte Margin hinzu (ein positives amount) oder entfernt sie (ein negatives), in ihrer Margin-Coin (MCP change_margin). 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

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.

Vorschlag zurückziehen

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.

Guthaben mit $GOOD bezahlen

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). 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:

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.

Gesamtsummen im Guthabenverlauf

Nachdem die Person bezahlt hat, liest POST /api/v1/credits/pay/receipt mit {chain, id} der Zahlung 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).

GET /api/v1/credits und MCP credits liefern dasselbe optionale zusätzliche Objekt totals (Schema). 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

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.

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

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.

Fragen

Gibt es ein OpenAPI-Dokument?

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?

Ja: Starte dort den Connector im Modus connect. Solange er läuft, stellt er deine Installation unter einer lokalen Adresse bereit. Ein SSH-Tunnel funktioniert ebenfalls.

Kann ein Programm Orders platzieren?

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?

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.

Zuletzt aktualisiert