Tradingview API Integration

TradingView API Integration

Help developers integrate the TradingView Data API and answer data questions by calling it live.

Recommended (Console)

• Base URL: https://api.tradingviewapi.com
• Auth: Authorization: Bearer <KEY> (equivalent: X-API-Key: <KEY>)
• Get a key at https://console.tvapis.com/start

Alternate (RapidAPI)

• Base URL: https://tradingview-data1.p.rapidapi.com
• Auth: x-rapidapi-host: tradingview-data1.p.rapidapi.com and x-rapidapi-key: <KEY>
• Console and RapidAPI keys are billed separately. Paths after the host are the same.

Prefer Console for new integrations and generated examples. Use RapidAPI only when the user already has a RapidAPI subscription or asks for it.

API key workflow (required for live calls)

scripts/tv_api.py defaults to Console. It resolves the key in this order:

1. --key CLI argument
2. TRADINGVIEW_API_KEY environment variable
3. RAPIDAPI_KEY environment variable (legacy RapidAPI)
4. .api-key file in this skill's root directory
5. .rapidapi-key file in this skill's root directory (legacy)

If the only available key came from RAPIDAPI_KEY or .rapidapi-key, the script uses the RapidAPI host automatically. --backend console|rapid or --rapid overrides that.

If none is available, ask the user for a Console API key.

When the user provides a key, ask whether to save it for future sessions. Only after explicit consent, save it:

python3 scripts/tv_api.py --save-key 'THE_KEY'

This writes .api-key (chmod 600) to the skill root so future calls need no key prompt.

Making live requests

Use scripts/tv_api.py (stdlib only, handles key resolution and JSON pretty-printing):

python3 scripts/tv_api.py GET '/api/quote/NASDAQ:AAPL'
python3 scripts/tv_api.py GET '/api/price/BINANCE:BTCUSDT?timeframe=60&range=20'
python3 scripts/tv_api.py POST '/api/screener/scan' --body '{"market":"america","range":[0,20],"filters":{"market_cap_basic":{"operation":"greater_or_equal","value":1e10}}}'
python3 scripts/tv_api.py --rapid GET '/api/quote/NASDAQ:AAPL'

Equivalent Console curl:

curl --location 'https://api.tradingviewapi.com/api/quote/NASDAQ:AAPL' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Choosing the right endpoint

Map the user's need to an endpoint family:

Full parameter tables, enums, and request/response shapes: read references/endpoint-catalog.md.

A machine-readable OpenAPI 3.0 spec snapshot is at references/openapi.json (~870 KB, 72 paths — too large to read whole; query it instead):

# List all paths
python3 -c "import json; print('\n'.join(json.load(open('references/openapi.json'))['paths']))"
# Dump one endpoint's full schema
python3 -c "import json; print(json.dumps(json.load(open('references/openapi.json'))['paths']['/api/quote/{symbol}'], indent=2))"

The live, always-current version is at https://www.tradingviewapi.com/openapi.json (public, no key). Fetch it to a temporary path when the snapshot seems stale or an endpoint is missing; update the bundled snapshot only when intentionally maintaining this skill:

curl -fsSL https://www.tradingviewapi.com/openapi.json -o /tmp/tradingview-openapi.json

Captured request/response examples live in references/examples/ (file names listed in the table above; also 10-mcp.md). Consult the example file before parsing a response shape you haven't seen. In the examples, repeated result rows and long string values are truncated with explicit (truncated) markers; all response fields are preserved. The real responses contain the full data.

Parameters that come from metadata

Many parameters must be valid values fetched from metadata endpoints (all public):

• market_code / calendar market / screener market → GET /api/metadata/markets
• leaderboard tab → GET /api/metadata/tabs?type={stocks|indices|crypto|futures|currencies|bonds|corporate_bonds|etfs}
• leaderboard columnset → GET /api/metadata/columnsets
• lang → GET /api/metadata/languages
• world-economy indicator slug → GET /api/metadata/world-economy/indicators
• exchange names for screener filters → GET /api/metadata/exchanges

When unsure whether a parameter value is valid, fetch the metadata endpoint first instead of guessing.

Screener workflow

The screener is the most powerful but most complex endpoint. Always follow this order:

1. Pick asset type: stock, crypto, etf, bond, cex, dex
2. GET /api/screener/presets?asset_type=... → choose preset_fields (column groups)
3. GET /api/screener/filter-options?asset_type=...&lang=en → discover filter field ids, operations, and enum values
4. POST /api/screener/{...}/scan with body { market, range, preset_fields, filters, sort }

Filter syntax: array = multi-select, { "operation": "greater_or_equal", "value": n } = comparison, scalar = equality. Details in the catalog.

MCP (AI assistants)

Recommended for Cursor, VS Code, and Claude: add the hosted URL and sign in with Console. No JWT in the config file.

{
  "mcpServers": {
    "tradingview": {
      "type": "http",
      "url": "https://mcp.tradingviewapi.com/mcp"
    }
  }
}

Older clients may use "type": "streamable-http". JWT fallback: POST /api/mcp/generate, then copy exampleConfig (http) or exampleConfigStreamableHttp. RapidAPI local OpenAPI MCP: npx -y @ivotoby/openapi-mcp-server (OpenAPI tools, not hosted tradingview_*). Details: references/examples/10-mcp.md.

Streaming (WebSocket & SSE)

Streaming is a different host from REST. Mint a JWT first, then connect to ws.tradingviewapi.com. Do not call /sse/stream on api.tradingviewapi.com.

# 1. JWT (Console API key)
curl --request POST \
  --url 'https://api.tradingviewapi.com/api/token/generate' \
  --header 'Content-Type: application/json' \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --data '{}'

# 2a. SSE — token in the query string (EventSource cannot set Authorization)
curl --request GET \
  --url 'https://ws.tradingviewapi.com/sse/stream?token=YOUR_JWT&symbols=BINANCE:BTCUSDT&type=quote' \
  --header 'Accept: text/event-stream' \
  --no-buffer

WebSocket: connect to wss://ws.tradingviewapi.com/ws?token=YOUR_JWT, then send JSON actions (subscribe with symbol + optional timeframe; subscribe_quote with symbols array). Server messages are update and quote_update.

When generating client code for streaming, read references/examples/11-websocket.md (and 15-token.md for the mint response).

Symbol format

Always EXCHANGE:TICKER (e.g. NASDAQ:AAPL, BINANCE:BTCUSDT, HKEX:9988). If the user gives a bare name ("Apple", "比亚迪"), resolve it via /api/search/market/ first.

Answering data questions

When the user asks a data question (not an integration question):

1. Ensure a key is available (see key workflow)
2. Resolve symbols via search if needed
3. Fetch required metadata for parameter values
4. Call the endpoint(s) with scripts/tv_api.py
5. Summarize the result; cite which endpoint(s) you used so the developer can reproduce the call