Connect a market-data feed¶
Goal: get live market data (order books, trades, candles) from a venue onto the platform's topics, by defining a feed and connecting it.
A feed definition (cfg.feed.<name>, shared on the context — the same the web app's
Trading › Feeds shows) names a venue preset and the topics to serve. Connecting it
creates or re-targets WebSocketFeed workers (tagged feedowner=<name>) that serve exactly
those topics; disconnecting deletes them.
Prerequisites
- An active context (Switch context). Saving, connecting and disconnecting are writes: the server lets only admins make them.
- For a venue that needs credentials (e.g.
alpaca): the key of the cluster's worker Secret (virtufin-worker-secrets) that holds them, e.g.alpaca-paper-key.
Presets shipped by market-data-devkit: binance (orderbook.update, trade.update,
candle.update), alpaca (orderbook.update, trade.update), fakevenue-binance,
fakevenue-alpaca (orderbook.update), binance-account-testnet.
Steps¶
- Open Feeds: Trading top tab,
1(Feeds) in the default layout. - Add a definition: press
a, pick a preset in New feed definition: venue preset, press Next. -
Edit the JSON template. For
binanceit starts as:{ "$schema": "https://app.virtufin.com/schemas/feed-definition.v1.schema.json", "name": "binance", "preset": "binance", "world": "act", "pairs": [], "families": ["orderbook.update"], "reconnect": true }Set a lower-case
name(it becomes the feeds' owner), thepairs(e.g.["BTC_USDT", "ETH_USDT"]) and thefamilies; addintervals(e.g.["1m"]) forcandle.update. Instead ofpairsxfamiliesyou may listtopicsdirectly.worldisactorhyp.<NAME>. For credentials add"secrets": {"alpacakey": "alpaca-paper-key"}(a reference into the worker Secret, never the value). The box below the editor validates as you type: errors at their JSON paths in red, warnings in yellow, orvalid: <N> topicsand the topics. 4. Save: Save (shared). A toast saysSaved feed '<name>' (shared on this context); the row appears as disconnected. 5. Connect: highlight the row, pressC. market-data-devkit's resolver plans the feeds (refusing topics over a venue's limits) and creates or re-targets them.
To change a definition later: Enter on its row, edit, Save, then C again — the
feeds move to the edited topics, and the definition's surplus feeds are deleted.
To stop it: X (asks first: its consumers get no data). To remove it: X, then d.
What you should see¶
- A toast
'<name>': <N> feed(s) serving <M> topics, <K> new. - The row's State becomes connected (every feed's socket open) or partly connected, with Feeds and Msg/s.
- The feeds as rows on Infra › Connections (
Msg/s,Subscribed,Latency) and on Infra › Workers; the data on Trading › Order Book, or on Infra › Events after adding the topics (athere).
Troubleshooting¶
| Symptom | Cause and fix |
|---|---|
'<name>' is not valid: <error> on C |
The saved definition does not validate; Enter, fix the error shown at its path, Save. |
A feed '<name>' exists already: edit it (Enter) |
Names are unique; edit the existing one or choose another name. |
'<name>' is connected: disconnect it first (X) on d |
Only a disconnected definition can be deleted. |
| Connect fails with a permission error | Only admins may change feeds on the server. |
The feed stays partly connected or Msg/s stays 0 |
Check the feed on Infra › Connections: Status, Failures, and Enter for its detail. A missing secret key leaves the worker LOAD_FAILED. |
| Connect is refused naming topics | They exceed the venue's limits (the preset's maximum items or connections); serve fewer pairs or families. |
The local World files (~/.config/virtufin/tui/worlds/*.toml) and composite worlds are
gone (tui#53); feed definitions replace them. Reference:
Keybindings › Feeds. The AI tab can do the same with
feeds__save, feeds__connect, feeds__disconnect (The TUI's API).