Kaars (OHLCV) tool referentie

Deze pagina is de tool referentie voor** het ophalen van kaarsgegevens (OHLCV) van de Cryptohopper Market Data MCP**.

Tool naam

get_candles

Doel

Geeft een reeks OHLCV (Open, High, Low, Close, Volume) kaarsen terug voor een opgegeven paar op een opgegeven beurs met een opgegeven tijdsbestek. Ondersteunt huidige (realtime) kaarsen op alle niveaus en historische kaarsen op Explorer, Adventurer en Hero.

Argumenten

Argument	Type	Vereist	Beschrijving
exchange	string	Ja	Beurs-identificatie (kleine letters). Zie ondersteunde beurzen.
pair	string	Ja	Paar in BASIS/QUOTE formaat.
timeframe	string	Ja	Kaarsgrootte. Zie ondersteunde tijdsbestekken hieronder.
limit	integer	Nee	Aantal kaarsen om terug te geven. Standaard en maximum zijn niveau-afhankelijk.
since	string (ISO-8601)	Nee	Starttijd voor historische zoekopdrachten. Indien weggelaten, geeft de meest recente limit kaarsen terug.

Alleen limit (recente kaarsen) of since + limit (historisch bereik) kan worden gebruikt. Alleen limit is het meest voorkomende geval.

Ondersteunde tijdsbestekken

Waarde	Duur
1m	1 minuut
5m	5 minuten
15m	15 minuten
1h	1 uur
4h	4 uur
1d	1 dag

Wekelijkse, maandelijkse en andere tijdsbestek aliassen worden niet ondersteund en worden afgewezen. Niet elk ondersteund tijdsbestek is beschikbaar op elke beurs. Niet-ondersteunde combinaties geven TIMEFRAME_NOT_SUPPORTED terug.

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 velden

Veld	Type	Beschrijving
exchange	string	De beurs-identificatie waar de gegevens vandaan komen.
pair	string	Het paar, in BASIS/QUOTE formaat.
timeframe	string	De kaarsgrootte (bijv. 1h).
candles	array	Reeks van OHLCV records, chronologisch geordend (oudste eerst). Elk record is zelf een reeks van zeven posities.

Kaarsrecord velden

Elke kaars is een reeks met de volgende posities:

Index	Veld	Type	Beschrijving
0	timestamp	number	Opentijd van de kaars (Unix timestamp in milliseconden).
1	open	number	Eerste verhandelde prijs in de kaars.
2	high	number	Hoogste verhandelde prijs in de kaars.
3	low	number	Laagste verhandelde prijs in de kaars.
4	close	number	Laatste verhandelde prijs in de kaars (of huidige prijs, voor een open kaars).
5	volume	number	Basisvaluta volume verhandeld in de kaars.
6	count	number	Aantal transacties in de kaars.

Prijzen en volume worden teruggegeven als JSON numbers. Clients die exacte precisie vereisen, moeten ze onmiddellijk na het parsen converteren naar een decimaal type. Zie gegevensmodel.

Volgorde

Kaarsen worden teruggegeven in chronologische volgorde — de oudste kaars eerst, de meest recente kaars laatst. Dit komt overeen met wat de meeste indicatorbibliotheken als invoer verwachten.

Open vs. gesloten kaarsen

Het laatste element van de candles reeks is doorgaans de huidige, open kaars — de kaars waarvan het tijdsvenster nog niet is voltooid. De close waarde weerspiegelt de huidige prijs, niet een definitieve sluiting. Alle eerdere kaarsen zijn gesloten en onveranderlijk.

Applicaties die indicatorberekeningen uitvoeren (RSI, MACD, voortschrijdende gemiddelden) moeten doorgaans alleen op gesloten kaarsen werken en het laatste element negeren. Het gebruik van de open kaars introduceert vooruitkijkende ruis die signalen kan destabiliseren.

Kosten

Scenario	Kosten op Pioneer	Kosten op Explorer/Adventurer	Kosten op Hero
Alleen huidige kaars (realtime)	1	1	1
Korte geschiedenis terugkijken	N.v.t.	5×	1×
Lange geschiedenis terugkijken	N.v.t.	20×	1×

De grens tussen "korte" en "lange" terugkijk is niveau-specifiek. Zie snelheidslimieten uitgelegd voor de exacte kostenmatrix en begeleiding om efficiënt te blijven.

Niveautoegang voor historische gegevens

Niveau	Historisch terugkijken
Pioneer	Niet beschikbaar — alleen huidige kaars
Explorer	Tot 90 dagen
Adventurer	Tot 365 dagen
Hero	Tot 3 jaar

Verzoeken die de maximale geschiedenis van het niveau overschrijden, geven HISTORY_LIMIT_EXCEEDED terug.

Terugkijk begeleiding

De meeste analyses vereisen veel minder kaarsen dan gebruikers intuïtief aanvragen. Aanbevolen terugkijkperioden:

Indicator	Minimum kaarsen	Comfortabel
RSI(14)	14	100
MACD(12, 26, 9)	35	100
Voortschrijdend gemiddelde (N-periode)	N	N + 50
Bollinger Bands (20, 2?)	20	100
ATR(14)	14	100

Het ophalen van meer kaarsen dan nodig vergroot de kosten (historische zoekopdrachten op Explorer/Adventurer kunnen tot 20× een basislijn call kosten) zonder de kwaliteit van de indicator te verbeteren.

Voorbeeld invocaties

Recente kaarsen

Gevraagd in een MCP client:

Haal de laatste 100 1-uurs kaarsen op voor ETH/USDT op Binance.

De agent roept get_candles(exchange="binance", pair="ETH/USDT", timeframe="1h", limit=100) aan.

Historisch bereik

Haal dagelijkse kaarsen op voor BTC/USDT op Binance vanaf 2026-01-01.

De agent roept get_candles(exchange="binance", pair="BTC/USDT", timeframe="1d", since="2026-01-01T00:00:00Z", limit=120) aan.

Multi-tijdsbestek

Haal 1h en 4h kaarsen op voor SOL/USDT op Binance, laatste 100 elk. Bereken RSI op beide tijdsbestekken.

De agent roept get_candles tweemaal aan met verschillende timeframe waarden. De RSI-berekening vindt plaats in de redenering van het model, niet in een tool call.

Fouten

Foutcode	Oorzaak
UNAUTHORIZED	API-sleutel ongeldig of ingetrokken.
EXCHANGE_NOT_SUPPORTED	Beurs niet beschikbaar op het actieve niveau.
PAIR_NOT_FOUND	Paar bestaat niet op de opgegeven beurs.
TIMEFRAME_NOT_SUPPORTED	Gevraagd tijdsbestek wordt niet ondersteund voor dit paar/beurs.
HISTORY_LIMIT_EXCEEDED	Gevraagde terugkijk overschrijdt de maximale geschiedenis van het niveau.
INVALID_PARAMETER	Argument voldeed niet aan validatie (bijv. limit buiten bereik, niet-herkende tijdsbestek alias).
EXCHANGE_UNAVAILABLE	Upstream beurs reageert niet.
DATA_UNAVAILABLE	Gevraagde kaarsen zijn niet beschikbaar van de upstream beurs voor dit bereik.
RATE_LIMIT_EXCEEDED	Korte-interval snelheidslimiet bereikt.
QUOTA_EXCEEDED	Wekelijkse quota bereikt.