# TradingView API

Ethereal exposes a [TradingView UDF-compatible](https://www.tradingview.com/charting-library-docs/latest/connecting_data/UDF/) API for querying historical OHLCV candlestick data, resolving symbol information, and searching available markets. This API powers charting integrations and can be used by any client that supports the TradingView UDF protocol.

<table><thead><tr><th width="146.0859375">Environment</th><th>URL</th></tr></thead><tbody><tr><td>Mainnet</td><td><code>https://tradingview.ethereal.trade</code></td></tr><tr><td>Testnet</td><td><code>https://tradingview.etherealtest.net</code></td></tr></tbody></table>

The full API specification (including request/response schemas, parameter validation rules, and error codes) is available via Swagger UI and as a downloadable OpenAPI spec. Use it to explore the API interactively or generate client SDKs:

<table><thead><tr><th width="146.37890625">Resource</th><th>URL</th></tr></thead><tbody><tr><td>Swagger UI</td><td><code>https://tradingview.ethereal.trade/docs</code></td></tr><tr><td>OpenAPI spec</td><td><code>https://tradingview.ethereal.trade/openapi.json</code></td></tr></tbody></table>

### API Endpoints & Example

Each price type exposes the following endpoints:

<table><thead><tr><th width="256.64453125">Endpoint</th><th>Description</th></tr></thead><tbody><tr><td><code>GET /{price-type}/config</code></td><td>UDF data feed configuration (called on init)</td></tr><tr><td><code>GET /{price-type}/symbols</code></td><td>Resolve full symbol metadata for a given ticker</td></tr><tr><td><code>GET /{price-type}/search</code></td><td>Search for symbols with fuzzy matching</td></tr><tr><td><code>GET /{price-type}/history</code></td><td>Historical OHLCV bar data for a symbol/resolution</td></tr><tr><td><code>GET /{price-type}/time</code></td><td>Current server time (Unix seconds)</td></tr></tbody></table>

*Where `{price-type}` is either last-price or oracle-price.*

### API Price Types

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

<table><thead><tr><th width="174.9140625">URL Prefix</th><th>Description</th></tr></thead><tbody><tr><td><code>/v1/last-price</code></td><td><strong>Last Price</strong> - derived from actual executed trades on the exchange. Only taker fills are included (self-trades, if any, are excluded).</td></tr><tr><td><code>/v1/oracle-price</code></td><td><strong>Oracle Price</strong> - derived from oracle price feed snapshots. Represents the reference price used for mark pricing, funding, and liquidations.</td></tr></tbody></table>

* **Last price** reflects where trades actually executed on the exchange. It is built from taker order fills (excluding self-trades) and includes meaningful volume data. During low-activity periods there may be gaps where no. trades occurred.
* **Oracle price** reflects the external reference price used for mark pricing, funding, and liquidations. It is updated continuously by the oracle, producing a smoother and more complete price line — but volume data reflects oracle update frequency, not trade activity.

{% hint style="info" %}
In most charting scenarios, oracle price provides a more continuous price line, while last price shows where actual trades occurred and includes meaningful volume data.
{% endhint %}

### Ticker Format & Resolution

Symbols follow the format `{TICKER}-{Type}`, e.g. `ETHUSD-Perp` or `BTCUSD-Perp`. *Currently only `Perp` (perpetual) is supported, with `Spot` coming soon.*

**Examples:** `ETHUSD-Perp`, `BTCUSD-Perp`, `SOLUSD-Spot`

Supported candlestick 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`

{% hint style="info" %}
Ethereal currently only supports `Perp` type with `Spot` later.
{% endhint %}

#### Example <kbd>oracle-price</kbd> Candles

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

{% code overflow="wrap" %}

```bash
GET https://tradingview.ethereal.trade/v1/oracle-price/history?symbol=ETHUSD-Perp&resolution=60&from=1704067200&to=1704110400&countback=100
```

{% endcode %}

The history endpoint returns OHLCV arrays:

```json
{
  "s": "ok",
  "t": [1704067200, 1704070800, 1704074400],
  "o": [42000.50, 42100.00, 42050.75],
  "h": [42150.00, 42200.00, 42100.00],
  "l": [41950.00, 42050.00, 41980.00],
  "c": [42100.00, 42050.75, 42080.25],
  "v": [125.5, 98.3, 110.7]
}
```

<table><thead><tr><th width="117.48828125">Field</th><th>Description</th></tr></thead><tbody><tr><td><code>s</code></td><td>Status: <code>ok</code>, <code>no_data</code>, or <code>error</code></td></tr><tr><td><code>t</code></td><td>Timestamps (Unix seconds)</td></tr><tr><td><code>o</code></td><td>Open prices</td></tr><tr><td><code>h</code></td><td>High prices</td></tr><tr><td><code>l</code></td><td>Low prices</td></tr><tr><td><code>c</code></td><td>Close prices</td></tr><tr><td><code>v</code></td><td>Volumes</td></tr></tbody></table>

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

### Limitations & Intended Use

Limitations:

* **No authentication:** this is a public, read-only API
* **No streaming / WebSocket support:** the API is polling-based. Use the `history` endpoint to fetch 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 per request. For example, 1-minute bars are limited to a 1-hour window, while monthly bars can span up to 10 years. If you need more data, paginate by shifting the `from`/`to` window.
* **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 API follows the same rate limits defined at [system-limits](https://docs.ethereal.trade/developer-guides/trading-api/system-limits "mention").

This API is designed for:

* **TradingView charting integrations:** connect directly as a UDF data feed in the [TradingView Charting Library](https://www.tradingview.com/charting-library-docs/)
* **Historical data analysis:** fetch OHLCV candle data for backtesting or analytics
* **Building custom charts:** use the raw OHLCV arrays to render charts in any frontend

It is **not** intended for:

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