Real-time price streaming over a persistent, bidirectional WebSocket at wss://ws.twelvedata.com/v1/quotes/price. Clients authenticate with an apikey query parameter, send JSON subscribe / unsubscribe / reset control messages, and receive pushed price events (roughly 170ms average latency), subscribe-status acknowledgements, and heartbeats.
asyncapi: '2.6.0'
id: 'urn:com:twelvedata:ws:v1:quotes:price'
info:
title: Twelve Data Real-Time Price WebSocket
version: '1.0.0'
description: |
AsyncAPI 2.6 description of Twelve Data's **real-time price WebSocket**.
Unlike a one-way HTTP Server-Sent Events stream, this is a genuine,
bidirectional WebSocket (`wss://`) surface. The client opens a persistent
connection to `wss://ws.twelvedata.com/v1/quotes/price`, authenticates with
an `apikey` query parameter, and then sends JSON control messages
(`subscribe`, `unsubscribe`, `reset`) to manage which instruments it wants.
The server pushes `price` events as trades occur (average latency ~170 ms),
plus `subscribe-status` acknowledgements and periodic `heartbeat` events.
Each successfully subscribed symbol consumes 1 WebSocket credit. WebSocket
access is metered separately from REST API credits and varies by plan
(trial credits on Basic/Grow, 1,500 on Pro, 10,000 on Ultra).
Source: https://twelvedata.com/docs/websocket/ws-real-time-price
contact:
name: API Evangelist
email: kin@apievangelist.com
url: https://apievangelist.com
license:
name: API documentation - Twelve Data Terms of Service
url: https://twelvedata.com/terms
x-transport-notes:
transport: WebSocket
protocol: wss
direction: bidirectional
url: 'wss://ws.twelvedata.com/v1/quotes/price'
auth: 'apikey query parameter, e.g. ?apikey=YOUR_API_KEY'
subscribeMessage: '{"action":"subscribe","params":{"symbols":"AAPL,EUR/USD,BTC/USD"}}'
creditWeight: '1 WebSocket credit per successfully subscribed symbol'
source: https://twelvedata.com/docs/websocket/ws-real-time-price
defaultContentType: application/json
servers:
production:
url: ws.twelvedata.com/v1/quotes/price
protocol: wss
description: |
Twelve Data real-time price WebSocket server. Authenticate by appending
the `apikey` query parameter to the connection URL:
`wss://ws.twelvedata.com/v1/quotes/price?apikey=YOUR_API_KEY`.
security:
- apikeyQuery: []
channels:
/v1/quotes/price:
description: |
Single multiplexed price channel. The client publishes control messages
(subscribe / unsubscribe / reset) and the server publishes price events,
subscription acknowledgements, and heartbeats over the same connection.
publish:
operationId: sendControlMessage
summary: Send a subscription control message to the server.
description: |
Client-to-server control messages. `subscribe` adds symbols to the
stream, `unsubscribe` removes them, and `reset` clears all current
subscriptions on the connection.
message:
oneOf:
- $ref: '#/components/messages/SubscribeAction'
- $ref: '#/components/messages/UnsubscribeAction'
- $ref: '#/components/messages/ResetAction'
subscribe:
operationId: receivePriceEvents
summary: Receive real-time price events and status messages from the server.
description: |
Server-to-client messages. After a successful `subscribe`, the server
emits a `subscribe-status` acknowledgement, then streams `price` events
as new trades arrive, interleaved with periodic `heartbeat` events.
message:
oneOf:
- $ref: '#/components/messages/PriceEvent'
- $ref: '#/components/messages/SubscribeStatus'
- $ref: '#/components/messages/Heartbeat'
components:
securitySchemes:
apikeyQuery:
type: httpApiKey
in: query
name: apikey
description: Twelve Data API key passed as the `apikey` query parameter on the connection URL.
messages:
SubscribeAction:
name: subscribe
title: Subscribe to symbols
summary: Add one or more instruments to the price stream.
contentType: application/json
payload:
$ref: '#/components/schemas/SubscribeActionPayload'
examples:
- name: subscribeAAPL
summary: Subscribe to several instruments
payload:
action: subscribe
params:
symbols: 'AAPL,EUR/USD,BTC/USD'
UnsubscribeAction:
name: unsubscribe
title: Unsubscribe from symbols
summary: Remove one or more instruments from the price stream.
contentType: application/json
payload:
$ref: '#/components/schemas/SubscribeActionPayload'
examples:
- name: unsubscribeAAPL
summary: Unsubscribe from a single instrument
payload:
action: unsubscribe
params:
symbols: 'AAPL'
ResetAction:
name: reset
title: Reset subscriptions
summary: Clear all active subscriptions on the connection.
contentType: application/json
payload:
$ref: '#/components/schemas/ResetActionPayload'
examples:
- name: reset
summary: Reset all subscriptions
payload:
action: reset
PriceEvent:
name: price
title: Real-time price event
summary: A single real-time price update for a subscribed instrument.
contentType: application/json
payload:
$ref: '#/components/schemas/PriceEventPayload'
examples:
- name: applePrice
summary: Price tick for AAPL
payload:
event: price
symbol: AAPL
currency: USD
exchange: NASDAQ
type: 'Common Stock'
timestamp: 1618482192
price: 134.28
day_volume: 6323234
SubscribeStatus:
name: subscribe-status
title: Subscription status
summary: Acknowledgement listing which symbols were successfully subscribed and which failed.
contentType: application/json
payload:
$ref: '#/components/schemas/SubscribeStatusPayload'
examples:
- name: statusOk
summary: Successful subscription acknowledgement
payload:
event: subscribe-status
status: ok
success:
- symbol: AAPL
exchange: NASDAQ
mic_code: XNGS
type: 'Common Stock'
fails: []
Heartbeat:
name: heartbeat
title: Heartbeat
summary: Periodic keep-alive event confirming the connection is healthy.
contentType: application/json
payload:
$ref: '#/components/schemas/HeartbeatPayload'
examples:
- name: heartbeat
summary: Heartbeat event
payload:
event: heartbeat
status: ok
schemas:
SubscribeActionPayload:
type: object
required:
- action
- params
properties:
action:
type: string
enum:
- subscribe
- unsubscribe
description: The control action to perform.
params:
type: object
required:
- symbols
properties:
symbols:
type: string
description: Comma-separated list of instrument symbols, e.g. 'AAPL,EUR/USD,BTC/USD'.
ResetActionPayload:
type: object
required:
- action
properties:
action:
type: string
enum:
- reset
description: Clears all active subscriptions on the connection.
PriceEventPayload:
type: object
required:
- event
- symbol
- price
properties:
event:
type: string
enum:
- price
description: Event discriminator, always 'price' for a price tick.
symbol:
type: string
description: Instrument symbol.
currency:
type: string
description: Quote currency.
exchange:
type: string
description: Exchange the instrument trades on.
mic_code:
type: string
description: Market Identifier Code (ISO 10383) of the exchange.
type:
type: string
description: Instrument type, e.g. 'Common Stock', 'Digital Currency', 'Physical Currency'.
timestamp:
type: integer
description: Unix timestamp (seconds) of the price event.
price:
type: number
description: The real-time price.
day_volume:
type: integer
description: Cumulative traded volume for the current day, where available.
SubscribeStatusPayload:
type: object
required:
- event
- status
properties:
event:
type: string
enum:
- subscribe-status
status:
type: string
enum:
- ok
- error
success:
type: array
description: Instruments that were successfully subscribed.
items:
type: object
properties:
symbol:
type: string
exchange:
type: string
mic_code:
type: string
type:
type: string
fails:
type: array
description: Symbols that could not be subscribed.
items:
type: string
HeartbeatPayload:
type: object
required:
- event
- status
properties:
event:
type: string
enum:
- heartbeat
status:
type: string
enum:
- ok