Candle (OHLCV) Tool-Referenz

Diese Seite ist die Tool-Referenz für** das Abrufen von Candle (OHLCV) Daten aus dem Cryptohopper Market Data MCP**.

Tool-Name

get_candles

Zweck

Gibt eine Serie von OHLCV (Open, High, Low, Close, Volume) Candles für ein bestimmtes Paar auf einer bestimmten Börse bei einem bestimmten Zeitrahmen zurück. Unterstützt aktuelle (Echtzeit-) Candles auf allen Stufen und historische Candles auf Explorer, Adventurer und Hero.

Argumente

Argument	Typ	Erforderlich	Beschreibung
exchange	string	Ja	Börsen-Identifier (Kleinbuchstaben). Siehe unterstützte Börsen.
pair	string	Ja	Paar im BASE/QUOTE-Format.
timeframe	string	Ja	Candle-Größe. Siehe unterstützte Zeitrahmen unten.
limit	integer	Nein	Anzahl der zurückzugebenden Candles. Standard und Maximum sind stufenabhängig.
since	string (ISO-8601)	Nein	Startzeit für historische Abfragen. Falls nicht angegeben, werden die neuesten limit Candles zurückgegeben.

Entweder limit allein (neueste Candles) oder since + limit (historischer Bereich) können verwendet werden. limit allein ist der häufigste Fall.

Unterstützte Zeitrahmen

Wert	Dauer
1m	1 Minute
5m	5 Minuten
15m	15 Minuten
1h	1 Stunde
4h	4 Stunden
1d	1 Tag

Wöchentliche, monatliche und andere Zeitrahmen-Aliase werden nicht unterstützt und werden abgelehnt. Nicht jeder unterstützte Zeitrahmen ist auf jeder Börse verfügbar. Nicht unterstützte Kombinationen geben TIMEFRAME_NOT_SUPPORTED zurück.

Response-Schema

{
  "exchange": "binance",
  "pair": "BTC/USDT",
  "timeframe": "1h",
  "candles": [
    [1778540400000, 80214.00, 80820.50, 80120.00, 80651.42, 412.85, 318],
    [1778544000000, 80651.42, 80936.22, 80590.00, 80934.19, 298.12, 274]
  ]
}

Top-Level-Felder

Feld	Typ	Beschreibung
exchange	string	Der Börsen-Identifier, von dem die Daten stammen.
pair	string	Das Paar im BASE/QUOTE-Format.
timeframe	string	Die Candle-Größe (z.B. 1h).
candles	array	Array von OHLCV-Datensätzen, chronologisch geordnet (ältester zuerst). Jeder Datensatz ist selbst ein Array mit sieben Positionen.

Candle-Datensatzfelder

Jede Candle ist ein Array mit den folgenden Positionen:

Index	Feld	Typ	Beschreibung
0	timestamp	number	Öffnungszeit der Candle (Unix-Zeitstempel in Millisekunden).
1	open	number	Erster gehandelter Preis in der Candle.
2	high	number	Höchster gehandelter Preis in der Candle.
3	low	number	Niedrigster gehandelter Preis in der Candle.
4	close	number	Letzter gehandelter Preis in der Candle (oder aktueller Preis bei einer offenen Candle).
5	volume	number	Handelsvolumen des Basis-Assets in der Candle.
6	count	number	Anzahl der Trades in der Candle.

Preise und Volumen werden als JSON-Zahlen zurückgegeben. Clients, die exakte Präzision benötigen, sollten sie unmittelbar nach dem Parsen in einen Dezimaltyp umwandeln. Siehe Datenmodell.

Sortierung

Candles werden in chronologischer Reihenfolge zurückgegeben — die älteste Candle zuerst, die neueste Candle zuletzt. Dies entspricht dem, was die meisten Indikator-Bibliotheken als Eingabe erwarten.

Offene vs. geschlossene Candles

Das letzte Element des candles-Arrays ist typischerweise die aktuelle, offene Candle — die Candle, deren Zeitfenster noch nicht abgeschlossen ist. Ihr close-Wert spiegelt den aktuellen Preis wider, nicht einen finalisierten Schlusspreis. Alle früheren Candles sind geschlossen und unveränderlich.

Anwendungen, die Indikatorberechnungen durchführen (RSI, MACD, gleitende Durchschnitte), sollten typischerweise nur mit geschlossenen Candles arbeiten und das letzte Element ignorieren. Die Verwendung der offenen Candle führt zu Look-Ahead-Rauschen, das Signale destabilisieren kann.

Kosten

Szenario	Kosten auf Pioneer	Kosten auf Explorer/Adventurer	Kosten auf Hero
Nur aktuelle Candle (Echtzeit)	1	1	1
Kurzer Verlaufs-Lookback	Nicht verfügbar	5×	1×
Langer Verlaufs-Lookback	Nicht verfügbar	20×	1×

Die Grenze zwischen "kurzem" und "langem" Lookback ist stufenspezifisch. Siehe Rate-Limits erklärt für die genaue Kostenmatrix und Hinweise zur Effizienzsteigerung.

Stufenzugriff für historische Daten

Stufe	Historischer Lookback
Pioneer	Nicht verfügbar — nur aktuelle Candle
Explorer	Bis zu 90 Tage
Adventurer	Bis zu 365 Tage
Hero	Bis zu 3 Jahre

Anfragen, die das maximale Verlaufsmaximum der Stufe überschreiten, geben HISTORY_LIMIT_EXCEEDED zurück.

Lookback-Empfehlungen

Die meisten Analysen benötigen weitaus weniger Candles, als Nutzer intuitiv anfordern. Empfohlene Lookbacks:

Indikator	Minimale Candles	Komfortabel
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Gleitender Durchschnitt (N-Perioden)	N	N + 50
Bollinger-Bänder (20, 2?)	20	100
ATR(14)	14	100

Das Abrufen von mehr Candles als notwendig erhöht die Kosten (historische Abfragen auf Explorer/Adventurer können bis zu 20× eines Basis-Aufrufs kosten), ohne die Qualität des Indikators zu verbessern.

Beispielaufrufe

Neueste Candles

Eingegeben in einem MCP-Client:

Hole die letzten 100 1-Stunden-Candles für ETH/USDT auf Binance.

Der Agent ruft get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100) auf.

Historischer Bereich

Hole tägliche Candles für BTC/USDT auf Binance ab dem 01.01.2026.

Der Agent ruft get_candles(exchange="binance", pair="BTC/USDT", timeframe="1d", since="2026-01-01T00:00:00Z", limit=120) auf.

Multi-Zeitrahmen

Hole 1h- und 4h-Candles für SOL/USDT auf Binance, jeweils die letzten 100. Berechne RSI auf beiden Zeitrahmen.

Der Agent ruft get_candles zweimal mit unterschiedlichen timeframe-Werten auf. Die RSI-Berechnung erfolgt im Reasoning des Modells, nicht in einem Tool-Aufruf.

Fehler

Fehlercode	Ursache
UNAUTHORIZED	API-Schlüssel ungültig oder widerrufen.
EXCHANGE_NOT_SUPPORTED	Börse nicht auf der aktiven Stufe verfügbar.
PAIR_NOT_FOUND	Paar existiert nicht auf der angegebenen Börse.
TIMEFRAME_NOT_SUPPORTED	Angeforderter Zeitrahmen wird für dieses Paar/diese Börse nicht unterstützt.
HISTORY_LIMIT_EXCEEDED	Angeforderter Lookback überschreitet das maximale Verlaufsmaximum der Stufe.
INVALID_PARAMETER	Argument hat Validierung nicht bestanden (z.B. limit außerhalb des Bereichs, nicht erkannter Zeitrahmen-Alias).
EXCHANGE_UNAVAILABLE	Upstream-Börse antwortet nicht.
DATA_UNAVAILABLE	Angeforderte Candles sind von der Upstream-Börse für diesen Bereich nicht verfügbar.
RATE_LIMIT_EXCEEDED	Kurzintervall-Rate-Limit erreicht.
QUOTA_EXCEEDED	Wöchentliches Kontingent erreicht.