tradingview-api-adapter

📊 Real-time market data from TradingView via WebSocket — typed, composable, and ergonomic.

import { tv } from 'tradingview-api-adapter'

const client = tv()
const btc = client.symbol('BINANCE:BTCUSDT')

console.log(await btc.price()) // → 72183.99

btc.stream().on('price', ({ price }) => {
  console.log('BTC:', price)
})

await client.disconnect()

Features

• ✅ Real-time quotes — typed lp, bid, ask, ch, chp, volume, and 50+ other fields
• ✅ Historical candles — OHLCV bars at any TradingView timeframe (1m → 1M)
• ✅ Symbol metadata — full SymbolInfo (description, exchange, session hours, …) via one .info() call
• ✅ Multi-symbol streams — Portfolio for ad-hoc collections, Group for named, mutable ones
• ✅ Auto-reconnect — exponential backoff + jitter, automatic session replay
• ✅ Full TypeScript types — QuoteSnapshot<['lp', 'bid']> gives you { lp?: number | null; bid?: number | null }
• ✅ Async iterator — for await (const tick of stream) { ... }
• ✅ Explicit resource management — using client = tv() auto-disconnects
• ✅ Node + Browser — dynamic ws import so browser bundles don't carry Node-only code
• ✅ Proxy + auth — HTTP/SOCKS proxy agent, sessionid/authToken for premium access
• ✅ Battle-tested — 227+ unit tests, integration against a mock WebSocket server, live e2e

Installation

npm install tradingview-api-adapter

Requires Node.js ≥ 20. See browser guide for client-side usage.

Quick start

Get a price

import { tv } from 'tradingview-api-adapter'

const client = tv()
const btc = client.symbol('BINANCE:BTCUSDT')

const price = await btc.price()
console.log(`BTC: $${price}`)

await client.disconnect()

Stream live updates

const stream = btc.stream(['lp', 'bid', 'ask', 'ch', 'chp'] as const)

stream.on('price', ({ price }) => console.log(price))
stream.on('change', ({ value, percent }) => console.log(`${value} (${percent}%)`))

// Or use async iteration:
for await (const { data } of stream) {
  console.log(data.lp, data.bid, data.ask)
  if (someCondition) break // ← automatically closes the stream
}

Fetch historical candles

const candles = await btc.candles({ timeframe: '1h', count: 100 })
// → Candle[] with { time, open, high, low, close, volume }

Multi-symbol portfolio

const portfolio = client.symbols([
  'BINANCE:BTCUSDT',
  'BINANCE:ETHUSDT',
  'NASDAQ:AAPL',
])

const prices = await portfolio.prices()
// → { 'BINANCE:BTCUSDT': 72183, 'BINANCE:ETHUSDT': 2200, 'NASDAQ:AAPL': 260 }

portfolio.stream().on('price', ({ symbol, price }) => {
  console.log(`${symbol}: $${price}`)
})

Named groups with live mutation

const crypto = client.createGroup('crypto', ['BINANCE:BTCUSDT', 'BINANCE:ETHUSDT'])

const stream = crypto.stream()
stream.on('price', ({ symbol, price }) => console.log(symbol, price))

// Add a pair — active streams pick it up automatically
crypto.add('BINANCE:SOLUSDT')

// Remove a pair — active streams stop emitting for it
crypto.remove('BINANCE:ETHUSDT')

// List all registered groups on the client
console.log(client.groups.list) // → ['crypto']

Symbol metadata

const info = await btc.info()
console.log(info.description) // → 'Bitcoin / TetherUS'
console.log(info.exchange) // → 'Binance'
console.log(info.currencyCode) // → 'USDT'
console.log(info.isTradable) // → true

Documentation

• Getting Started — installation, first requests, cleanup
• API Reference — Client, TvSymbol, Stream, Group, types
• Guides — streaming best practices, candles, groups, reconnect, browser, proxy, auth
• Migration from 1.x — before/after for every 1.x method
• Contributing — development workflow, conventions, .js extension rationale
• Changelog

Examples

The examples/ directory contains 12 runnable demos:

#	File	What it shows
01	01-single-price.ts	Minimal one-shot price fetch
02	02-streaming.ts	Single-symbol stream with price, change events
03	03-multi-symbol.ts	Ad-hoc Portfolio
04	04-groups.ts	Named Group with live add/remove
05	05-candles-history.ts	Historical OHLCV bars
06	06-candles-streaming.ts	Live bar ticks (via internal ChartSession)
07	07-symbol-info.ts	Full symbol metadata
08	08-async-iterator.ts	for await over a stream
09	09-reconnect-resilience.ts	Automatic reconnect with backoff
10	10-browser.html	Vanilla HTML page via esm.sh CDN
11	11-proxy-node.ts	HTTP/SOCKS proxy through an agent
12	12-auth-session.ts	Authenticated access with TradingView cookies

Run any of them with npx tsx examples/NN-*.ts. Enable verbose logging via DEBUG=tradingview-adapter:* npx tsx examples/NN-*.ts.

Design principles

This library is a full rewrite of 1.x. The redesign prioritised:

1. Typed over stringly-typed. QuoteSnapshot<['lp', 'bid']> is { lp?: number | null; bid?: number | null }, not Record<string, any>.
2. Composable over monolithic. Transport ↔ Protocol ↔ SessionManager ↔ public API are independently testable and swappable.
3. One socket, many sessions. A single WebSocket connection multiplexes every quote and chart subscription through a shared SessionManager.
4. Pooled symbols. client.symbol('BTC') always returns the same instance, so overlapping groups dedupe automatically.
5. No hidden state. Every resource (symbol, stream, group) has an explicit lifecycle.
6. Browser-safe by construction. ws is loaded through dynamic import() so browser bundlers can drop it.

License

MIT © Gerasimenko Oleg