Narzędzie do pobierania danych świec (OHLCV) – dokumentacja referencyjna

Ta strona to dokumentacja referencyjna narzędzia do pobierania danych świec (OHLCV) z Cryptohopper Market Data MCP.

Nazwa narzędzia

get_candles

Cel

Zwraca serie świec OHLCV (Open, High, Low, Close, Volume) dla określonej pary na określonej giełdzie w określonym przedziale czasowym. Obsługuje aktualne (w czasie rzeczywistym) świece na wszystkich poziomach oraz historyczne świece na poziomach Explorer, Adventurer i Hero.

Argumenty

Argument	Typ	Wymagany	Opis
exchange	string	Tak	Identyfikator giełdy (małe litery). Zobacz obsługiwane giełdy.
pair	string	Tak	Para w formacie BASE/QUOTE.
timeframe	string	Tak	Rozmiar słupka. Zobacz obsługiwane przedziały czasowe poniżej.
limit	integer	Nie	Liczba świec do zwrócenia. Wartość domyślna i maksymalna zależą od poziomu.
since	string (ISO-8601)	Nie	Czas rozpoczęcia dla zapytań historycznych. Jeśli pominięte, zwraca ostatnie limit słupków.

Można użyć samego limit (ostatnie słupki) lub since + limit (zakres historyczny). Sam limit to typowy przypadek.

Obsługiwane przedziały czasowe

Wartość	Czas trwania
1m	1 minuta
5m	5 minut
15m	15 minut
1h	1 godzina
4h	4 godziny
1d	1 dzień

Tygodniowe, miesięczne i inne aliasy przedziałów czasowych nie są obsługiwane i zostaną odrzucone. Nie każdy obsługiwany przedział czasowy jest dostępny na każdej giełdzie. Nieobsługiwane kombinacje zwracają TIMEFRAME_NOT_SUPPORTED.

Schemat odpowiedzi

{
  "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]
  ]
}

Pola najwyższego poziomu

Pole	Typ	Opis
exchange	string	Identyfikator giełdy, z której pochodzą dane.
pair	string	Para w formacie BASE/QUOTE.
timeframe	string	Rozmiar słupka (np. 1h).
candles	array	Tablica rekordów OHLCV, uporządkowanych chronologicznie (najstarsze jako pierwsze). Każdy rekord to również tablica siedmiu pozycji.

Pola rekordu świecy

Każda świeca to tablica z następującymi pozycjami:

Indeks	Pole	Typ	Opis
0	timestamp	number	Czas otwarcia słupka (znacznik czasu Unix w milisekundach).
1	open	number	Pierwsza cena handlowa w słupku.
2	high	number	Najwyższa cena handlowa w słupku.
3	low	number	Najniższa cena handlowa w słupku.
4	close	number	Ostatnia cena handlowa w słupku (lub aktualna cena dla otwartego słupka).
5	volume	number	Wolumen aktywów podstawowych w słupku.
6	count	number	Liczba transakcji w słupku.

Ceny i wolumen są zwracane jako liczby JSON. Klienci wymagający dokładnej precyzji powinni przekonwertować je na typ dziesiętny natychmiast po parsowaniu. Zobacz model danych.

Kolejność

Świece są zwracane w kolejności chronologicznej — najstarszy słupek jako pierwszy, najnowszy słupek jako ostatni. To odpowiada temu, czego oczekują większość bibliotek wskaźników jako danych wejściowych.

Słupki otwarte a zamknięte

Ostatni element tablicy candles to zazwyczaj aktualny, otwarty słupek — słupek, którego okno czasowe jeszcze się nie zakończyło. Jego wartość close odzwierciedla aktualną cenę, a nie ostateczne zamknięcie. Wszystkie wcześniejsze słupki są zamknięte i niezmienne.

Aplikacje wykonujące obliczenia wskaźników (RSI, MACD, średnie kroczące) powinny zazwyczaj operować tylko na zamkniętych słupkach, ignorując ostatni element. Użycie otwartego słupka wprowadza szum wyprzedzający, który może zdestabilizować sygnały.

Koszt

Scenariusz	Koszt na Pioneer	Koszt na Explorer/Adventurer	Koszt na Hero
Tylko aktualny słupek (w czasie rzeczywistym)	1	1	1
Krótkie spojrzenie wstecz	N/D	5×	1×
Długie spojrzenie wstecz	N/D	20×	1×

Granica między "krótkim" a "długim" spojrzeniem wstecz jest specyficzna dla poziomu. Zobacz wyjaśnienie limitów żądań dla dokładnej macierzy kosztów i wskazówek dotyczących utrzymania efektywności.

Dostęp do danych historycznych według poziomu

Poziom	Spojrzenie wstecz historyczne
Pioneer	Niedostępne — tylko aktualny słupek
Explorer	Do 90 dni
Adventurer	Do 365 dni
Hero	Do 3 lat

Żądania przekraczające maksymalną historię poziomu zwracają HISTORY_LIMIT_EXCEEDED.

Wskazówki dotyczące spojrzenia wstecz

Większość analiz wymaga znacznie mniej świec niż użytkownicy intuicyjnie żądają. Sugerowane spojrzenia wstecz:

Wskaźnik	Minimalne słupki	Wygodne
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Średnia krocząca (okres N)	N	N + 50
Wstęgi Bollingera (20, 2?)	20	100
ATR(14)	14	100

Pobieranie większej liczby słupków niż konieczne zwiększa koszt (zapytania historyczne na Explorer/Adventurer mogą kosztować do 20× podstawowego wywołania) bez poprawy jakości wskaźnika.

Przykładowe wywołania

Ostatnie słupki

Zapytane w kliencie MCP:

Pobierz ostatnie 100 1-godzinnych świec dla ETH/USDT na Binance.

Agent wywołuje get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100).

Zakres historyczny

Pobierz dzienne świece dla BTC/USDT na Binance od 2026-01-01 wzwyż.

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

Wiele przedziałów czasowych

Pobierz świece 1h i 4h dla SOL/USDT na Binance, po 100 każdego. Oblicz RSI dla obu przedziałów czasowych.

Agent wywołuje get_candles dwa razy z różnymi wartościami timeframe. Obliczenie RSI odbywa się w rozumowaniu modelu, a nie w wywołaniu narzędzia.

Błędy

Kod błędu	Przyczyna
UNAUTHORIZED	Klucz API jest nieprawidłowy lub cofnięty.
EXCHANGE_NOT_SUPPORTED	Giełda niedostępna na aktywnym poziomie.
PAIR_NOT_FOUND	Para nie istnieje na określonej giełdzie.
TIMEFRAME_NOT_SUPPORTED	Żądany przedział czasowy nie jest obsługiwany dla tej pary/giełdy.
HISTORY_LIMIT_EXCEEDED	Żądane spojrzenie wstecz przekracza maksymalną historię poziomu.
INVALID_PARAMETER	Argument nie przeszedł walidacji (np. limit poza zakresem, nierozpoznany alias przedziału czasowego).
EXCHANGE_UNAVAILABLE	Giełda nadrzędna nie odpowiada.
DATA_UNAVAILABLE	Żądane świece nie są dostępne z giełdy nadrzędnej dla tego zakresu.
RATE_LIMIT_EXCEEDED	Osiągnięto limit żądań w krótkim interwale.
QUOTA_EXCEEDED	Osiągnięto tygodniowy limit.