> ## Documentation Index > Fetch the complete documentation index at: https://coinstats.app/docs/llms.txt > Use this file to discover all available pages before exploring further. # Get Ohlcv Candles > Get historical OHLCV candles for an exchange market **1** credit per **1,000 returned candles**, rounded up (minimum **1** credit).
* Chronological, fully closed candles for a specific exchange and market pair. * Compact rows shaped as `[timestampMs, open, high, low, close, volumeBase]`. * The effective start and end times. * exchange: Exchange name, for example `Binance`. * pair: Case-sensitive market pair, for example `BTC/USDT`. * interval: Candle interval from `5m` through `1w`. * Exactly one time mode: `range`, or both `start` and `end`. * range: `1h`, `6h`, `24h`, `1w`, `1mo`, `3mo`, `6mo`, `1y`, or `all`. * start / end: ISO 8601 custom bounds. Start is inclusive and end is exclusive. `range=all` returns all stored history available for the pair and may contain genuine source gaps. Maximum: 100,000 candles per response. Requests exceeding this limit return HTTP 400; use a shorter range or a larger interval. Credits are based on the number of candles actually returned: 1 credit per 1,000 candles, rounded up, with a minimum of 1 credit. For example: 150 or 1,000 candles = 1 credit; 1,001 candles = 2 credits; 10,000 candles = 10 credits; 100,000 candles = 100 credits. An empty successful response costs 1 credit. ## OpenAPI ````yaml /api-reference/openapi.json get /v1/ohlcv/candles openapi: 3.0.0 info: title: CoinStats Public API description: >- CoinStats Public API — programmatic access to market data, news, NFTs, wallets, exchange connections, and user portfolios. Authenticate every request with the `X-API-KEY` header (or an OAuth Bearer token in the `Authorization` header). Generate keys at https://openapi.coinstats.app. version: '1.0' contact: {} servers: - url: https://api.coinstats.app security: [] tags: - name: CoinStats description: '' - name: Market Data description: >- The Market Data section of the API provides endpoints to access a wide range of market-related information, including cryptocurrency coins, ticker data, and fiat currency rates. This category offers comprehensive data to help users monitor and analyze the cryptocurrency market, track prices, and gain insights into market trends - name: News description: >- The News section of the API allows you to access news articles and updates related to cryptocurrencies and the blockchain industry. It provides valuable information from various sources to keep you informed about the latest developments - name: NFTs description: >- The NFT section of the API provides endpoints to interact with Non-Fungible Tokens (NFTs), which are unique digital assets stored on a blockchain. These endpoints allow you to retrieve information about NFTs, including collections, assets, trending NFTs, and specific assets associated with wallet addresses. - name: Wallet Data description: >- The Wallet section of the API provides a comprehensive set of endpoints to manage and interact with wallets. It enables users to retrieve wallet balances, monitor syncing status, fetch transaction data, and synchronize wallet information with the blockchain. By integrating these endpoints into your application, you can offer robust wallet functionality to your users. - name: Exchange Connection description: >- The Exchange Connection section of the API provides a comprehensive set of endpoints to manage and interact with exchanges. It enables users to retrieve exchange balances, monitor syncing status, fetch transaction data. By integrating these endpoints into your application, you can offer robust exchange portfolio tracking functionality to your users. - name: User Portfolio description: >- The Portfolio section of the API provides a comprehensive set of endpoints to manage and interact with Share Portfolios. It enables users to retrieve current Portfolio Coins and Transactions. - name: Usage description: The Usage section provides account-level API usage data. - name: Status description: The Status section provides API availability checks. - name: Prediction · Markets description: >- Polymarket markets: list/trend/detail, live CLOB prices and order book, OHLC candles, and price history. Prices are probabilities in 0..1, money is USD, dates are ISO 8601. - name: Prediction · Events description: >- Polymarket events — groups of related markets (e.g. one market per candidate). List, trend, and fetch an event with its child markets. - name: Prediction · Traders description: >- Trader leaderboard plus deep per-trader analytics: profile, open positions, trade history, daily PnL, category stats, aggregate trade stats, and composite score. - name: Prediction · Analytics description: >- Platform-wide analytics: overview stats, smart-money and whale traders, trending-by-smart-money markets, and composite market signals. - name: Prediction · Search description: Full-text search across Polymarket events, markets, and traders. paths: /v1/ohlcv/candles: get: tags: - Market Data summary: Get historical OHLCV candles for an exchange market operationId: get-ohlcv-candles parameters: - name: exchange required: true in: query description: Exchange name. Matching is case-insensitive. schema: type: string example: Binance - name: pair required: true in: query description: Case-sensitive market pair. schema: type: string example: BTC/USDT - name: interval required: true in: query description: Candle interval. schema: type: string enum: - 5m - 15m - 30m - 1h - 4h - 1d - 1w example: 1h - name: range required: false in: query description: >- Rolling time range ending now. Use this or both start and end, never both modes. schema: example: 24h type: string enum: - 1h - 6h - 24h - 1w - 1mo - 3mo - 6mo - 1y - all - name: start required: false in: query description: >- Inclusive custom-range start as an ISO 8601 timestamp. Requires end and cannot be combined with range. schema: format: date-time example: '2026-09-01T00:00:00.000Z' type: string - name: end required: false in: query description: >- Exclusive custom-range end as an ISO 8601 timestamp. Requires start, must be later than start, and cannot be combined with range. schema: format: date-time example: '2026-09-02T00:00:00.000Z' type: string responses: '200': description: Exchange-specific historical OHLCV candles. content: application/json: schema: $ref: '#/components/schemas/OhlcvResponseDto' '400': description: Bad Request content: application/json: example: statusCode: 400 message: Bad Request requestId: 11111111-2222-3333-4444-555555555555 path: '401': description: Unauthorized content: application/json: example: statusCode: 401 message: Unauthorized requestId: 11111111-2222-3333-4444-555555555555 path: '403': description: Forbidden content: application/json: example: statusCode: 403 message: Forbidden requestId: 11111111-2222-3333-4444-555555555555 path: '404': description: Not Found content: application/json: example: statusCode: 404 message: Not Found requestId: 11111111-2222-3333-4444-555555555555 path: '409': description: Conflict (for some endpoints) content: application/json: example: statusCode: 409 message: Transactions not synced requestId: 11111111-2222-3333-4444-555555555555 path: '422': description: The requested interval is smaller than the pair's source interval. '429': description: Too Many Requests content: application/json: example: statusCode: 429 message: Rate limit exceeded requestId: 11111111-2222-3333-4444-555555555555 path: '503': description: Service Unavailable content: application/json: example: statusCode: 503 message: Service Unavailable. Please Contact Support '504': description: The OHLCV query timed out. security: - X-API-KEY: [] x-codeSamples: - lang: curl label: Recent range source: >- curl "https://api.coinstats.app/v1/ohlcv/candles?exchange=Binance&pair=BTC%2FUSDT&interval=1h&range=24h" \ -H "X-API-KEY: YOUR_API_KEY" - lang: curl label: All available history source: >- curl "https://api.coinstats.app/v1/ohlcv/candles?exchange=Binance&pair=BTC%2FUSDT&interval=1d&range=all" \ -H "X-API-KEY: YOUR_API_KEY" - lang: curl label: Custom start and end source: >- curl "https://api.coinstats.app/v1/ohlcv/candles?exchange=Binance&pair=BTC%2FUSDT&interval=1h&start=2026-09-01T00%3A00%3A00.000Z&end=2026-09-02T00%3A00%3A00.000Z" \ -H "X-API-KEY: YOUR_API_KEY" components: schemas: OhlcvResponseDto: type: object properties: exchange: type: string example: Binance pair: type: string example: BTC/USDT interval: type: string enum: - 5m - 15m - 30m - 1h - 4h - 1d - 1w example: 1h start: type: string description: Effective range start. example: '2026-09-01T00:00:00.000Z' format: date-time end: type: string description: Effective range end. example: '2026-09-02T00:00:00.000Z' format: date-time count: type: number example: 24 candles: type: array description: >- Chronological compact candles. Each item is [timestampMs, open, high, low, close, volumeBase]. Volume may be null when the source does not provide it. items: type: array minItems: 6 maxItems: 6 items: type: number nullable: true example: - - 1788220800000 - 78580 - 78900 - 78570.01 - 78605.8 - 522.70913 required: - exchange - pair - interval - start - end - count - candles securitySchemes: X-API-KEY: type: apiKey in: header name: X-API-KEY description: >- API key required to access the endpoints. Generate one from your dashboard at https://openapi.coinstats.app and pass it in the `X-API-KEY` request header. Never expose your key in client-side code. ````