# TradingView / Candles

Meridian provides an API that is compatible with the [TradingView UDF protocol](https://www.tradingview.com/charting-library-docs/latest/connecting_data/UDF/). Use it to get historical OHLCV candles, resolve a symbol, or search for a market.

## Base URLs

| Environment | URL                                     |
| ----------- | --------------------------------------- |
| Mainnet     | Not yet live                            |
| Testnet     | `https://trading-view.meridiantest.net` |

The full API specification is available through Swagger UI and OpenAPI. It includes schemas, validation rules, and error codes. Use it to examine the API or generate a client.

| Resource     | URL                                                  |
| ------------ | ---------------------------------------------------- |
| Swagger UI   | `https://trading-view.meridiantest.net/docs`         |
| OpenAPI spec | `https://trading-view.meridiantest.net/openapi.json` |

## Endpoints

Each price type exposes the following endpoints:

| Method | Endpoint                | Description                                                           |
| ------ | ----------------------- | --------------------------------------------------------------------- |
| `GET`  | `/{price-type}/config`  | UDF data feed configuration, called by TradingView on initialization. |
| `GET`  | `/{price-type}/symbols` | Resolve full symbol metadata for a given ticker.                      |
| `GET`  | `/{price-type}/search`  | Search available markets with fuzzy matching.                         |
| `GET`  | `/{price-type}/history` | Fetch historical OHLCV bars for a symbol and resolution.              |
| `GET`  | `/{price-type}/time`    | Return the current server time as Unix seconds.                       |

`price-type` is `last-price` or `oracle-price`.

## Price Types

Every endpoint exists under two parallel route prefixes, each querying a different data source:

| URL Prefix         | Source       | Description                                                                                                           |
| ------------------ | ------------ | --------------------------------------------------------------------------------------------------------------------- |
| `/v1/last-price`   | Last Price   | Derived from executed trades on the exchange. Only taker fills are included, and self-trades are excluded if present. |
| `/v1/oracle-price` | Oracle Price | Derived from oracle price feed snapshots. Used for mark pricing, funding, and liquidations.                           |

* **Last price** uses executed taker fills and excludes self-trades. Its volume is trade volume. A period with no trades causes a gap in the data.
* **Oracle price** uses external reference-price snapshots. Meridian uses this price for mark pricing, funding, and liquidations. Its volume is the number of oracle updates, not trade volume.

:::info
Oracle-price candles usually give a more continuous price line. Last-price candles show executed trades and trade volume.
:::

## Ticker Format

Symbols follow the format `TICKER-Type`, for example `ETHUSD-Perp` or `BTCUSD-Perp`. The current API supports the `Perp` type.

Examples are `ETHUSD-Perp` and `BTCUSD-Perp`.

## Resolutions

Supported candlestick resolutions:

| Interval       | Resolutions                                                |
| -------------- | ---------------------------------------------------------- |
| Minutes        | `1`, `3`, `5`, `15`, `30`                                  |
| Hours          | `60` (1h), `120` (2h), `240` (4h), `480` (8h), `720` (12h) |
| Days and above | `1D`, `3D`, `1W`, `1M`                                     |

## Example: Oracle-Price Candles

Fetch 1-hour oracle price candles for ETHUSD-Perp:

```bash
curl 'https://trading-view.meridiantest.net/v1/oracle-price/history?symbol=ETHUSD-Perp&resolution=60&from=1704067200&to=1704110400&countback=100'
```

The history endpoint returns OHLCV arrays:

```json
{
  "s": "ok",
  "t": [1704067200, 1704070800, 1704074400],
  "o": [42000.5, 42100.0, 42050.75],
  "h": [42150.0, 42200.0, 42100.0],
  "l": [41950.0, 42050.0, 41980.0],
  "c": [42100.0, 42050.75, 42080.25],
  "v": [125.5, 98.3, 110.7]
}
```

| Field | Description                         |
| ----- | ----------------------------------- |
| `s`   | Status: `ok`, `no_data`, or `error` |
| `t`   | Timestamps, in Unix seconds         |
| `o`   | Open prices                         |
| `h`   | High prices                         |
| `l`   | Low prices                          |
| `c`   | Close prices                        |
| `v`   | Volumes                             |

:::info
Bars are returned in ascending chronological order (oldest first). When no data exists for the requested range, the response is `{ "s": "no_data" }`.
:::

## Limitations

* **No authentication:** this is a public, read-only API.
* **No streaming or WebSocket support:** use the `history` endpoint to get updated bars.
* **No marks or timescale marks:** `supports_marks` and `supports_timescale_marks` are `false`.
* **No group requests:** symbols must be resolved individually.
* **Query range limits:** each resolution has a maximum time range. For example, the maximum is 1 hour for 1-minute bars and 10 years for monthly bars. Move the `from` and `to` window to get more data.
* **Last price gaps:** the last price feed reflects actual trade executions. During low-liquidity periods, there may be gaps in the data where no trades occurred.
* **Volume on oracle price:** volume data on oracle price candles reflects oracle update frequency, not trade volume. Use last price candles for meaningful volume data.
* **Rate limiting:** TradingView / Candles follows the same rate limits defined at [System Limits](/developer-guides/trading-api/system-limits).

## Intended Use

This API is designed for:

* **TradingView charting integrations:** connect it as a UDF data feed in the [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/).
* **Historical data analysis:** get OHLCV candle data for tests or analysis.
* **Custom charts:** use the OHLCV arrays in a client application.

It is **not** intended for:

* Real-time trade execution or order placement.
* Tick-level or sub-minute trade data.
* Account-specific or authenticated data.